@pi-unipi/compactor

Compaction for Pi — lossless zero-LLM or model summaries, rebuilt from full history, with session recall

Packages

Package details

extensionskill

Install @pi-unipi/compactor from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@pi-unipi/compactor
Package
@pi-unipi/compactor
Version
3.0.0
Published
Oct 25, 2026
Downloads
7,009/mo · 303/wk
Author
neuron-mr-white
License
MIT
Types
extension, skill
Size
219.4 KB
Dependencies
3 dependencies · 3 peers
Pi manifest JSON
{
  "skills": [
    "./skills"
  ],
  "themes": [],
  "prompts": [],
  "extensions": [
    "./index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Compactor

Compactor makes the context smaller when it fills up, so long work can continue. The full history stays in the session file, and the agent can search it.

@pi-unipi/compactor · part of UniPi

What it does

  • Replaces old messages with a summary when the context fills up.
  • The default method, lossless, makes the summary with 0 model calls.
  • The model summary method uses Pi's model-written summary. It adds the active work block at the top. It costs one model call.
  • Makes each lossless summary again from the full history. It does not merge old summaries, so the summary does not grow over time.
  • Removes passwords, API keys and bearer tokens from the summary. session_recall can still find them.
  • Shows a compaction card in the chat and a compaction count in the footer.

Quick start

  1. Install UniPi: pi install npm:@pi-unipi/unipi. You can also install this package alone: pi install npm:@pi-unipi/compactor.
  2. Work as usual. Compaction starts at Pi's context limit.
  3. Type /unipi:compact-stats to see the tokens that compaction saved.

Commands

Command What it does
/unipi:compact-vcc [keep:N] Runs lossless compaction now. keep:N keeps the last N user turns.
/unipi:compact-by-llm [focus] Runs model summary compaction now. The text sets the focus of the summary.
/unipi:session-recall <query> Searches the full session history. Add scope:all or page:N.
/unipi:compact-stats Shows the compactions and the saved tokens of this session.
/unipi:compact-doctor Checks the settings, Pi's compaction switch and old files.
/unipi:compact-help Shows a list of compactor commands.
/unipi:compact-then [prompt] Compacts, then sends prompt once it lands. Not a registered command — the package adds its own single autocomplete entry for it.

/unipi:compact-then works idle or while the agent is streaming. Idle, it compacts now and queues the prompt as a follow-up. Streaming, it queues the compaction for the next turn boundary and delivers the prompt the same way you submitted it — as a steer (Enter) or a follow-up (Alt+Enter) — once that turn's own compaction lands. With no prompt, it just compacts.

Agent tools

Tool What it does
session_recall Searches the session with keywords or a regex. It also finds messages that compaction removed. expand gives full entries by index.
context_budget Gives the percent of the context in use and the tokens left.

Lossless summary

The summary has these sections. Each section gets a part of a token budget. The auto budget is 1.5k to 4k tokens. It grows with the session size.

  1. Active Work: the goal, ralph loop or kanboard task that runs now.
  2. Your Requests: your messages and your ask_user answers.
  3. Latest State: the last step and the last progress report.
  4. Decisions & Constraints: your instructions, corrections and rules.
  5. Files: changed, new and read files, with relative paths.
  6. Lessons: notes that the agent wrote, such as memory notes and diagnoses.
  7. Project Knowledge: project notes, repeated build and test commands, hosts.
  8. Commits: hash and subject.
  9. Open Errors: recent failures with no later success.
  10. Recent Transcript: a ranked part of the recent work.

Settings

Namespace compactor. Open it with /unipi:settings.

Key Default What it does
method vcc vcc is lossless. llm is the model summary.
piCompact follow Sets what Pi's /compact does. follow uses method.
trigger pi pi uses Pi's context limit. percent compacts at thresholdPercent.
thresholdPercent 80 Context percent for the percent trigger. Range 30 to 95.
notify true Shows the card after an automatic compaction. Failures always show.
smartKeepTail true Keeps more recent turns when the kept tail is very small.
summaryBudgetTokens 0 Lossless summary size. 0 is auto.
sections.<name> true Turns one summary section on or off.
cooldownMs 60000 Minimum time between two percent compactions.
repeatMinGrowthTokens 4000 New tokens needed before the next percent compaction.
llmInstructions empty More instructions for the model summary.
debug false Writes diagnostics to /tmp/compactor-debug.json.

The percent trigger compacts at a turn boundary. Goal, ralph and kanboard loops continue without a stop.

For other modules

Register an active work provider. The summary then starts with your state.

import { registerCompactionContext } from "@pi-unipi/core";
registerCompactionContext("my-module", () => (running ? "Task X is in progress" : null));

A turn-boundary compaction does not fire Pi's session_compact event. Listen to UNIPI_EVENTS.COMPACTOR_COMPACTED to get each compaction.

How it works

Read Compaction and Prefix cache.

See also