@pi-unipi/compactor

Deterministic context management for Pi/UniPi. The compactor keeps long coding sessions usable by replacing large conversation history with a structured, zero-LLM summary, while preserving session recall, continuity snapshots, stats, sandbox helpers, and safer tool display.

What it does

• Zero-LLM compaction: Pi asks for compaction; UniPi builds the summary locally instead of spending model tokens on a summarization call.
• Session continuity: important goals, changed files, commits, blockers, preferences, and a recent transcript survive compaction.
• Optional percentage trigger: UniPi can compact at a configured context percentage before Pi's fixed reserve-token safety net fires.
• Recall: agents can search the append-only session branch, including messages that no longer fit in live LLM context.
• Runtime helpers: sandbox execution, context budget checks, diagnostics, and stats.
• Display guards: tool output/diff rendering is clamped and summarized to avoid noisy or terminal-breaking output.

The compaction pipeline is deterministic and runs locally. It does not call an LLM during compaction.

Quick start

/unipi:compact-settings

1. Choose a preset in Presets.
2. Optionally enable Auto → Percentage Trigger.
3. Press Enter to save.
4. Use /unipi:lossless-compact when you want to compact immediately.

Config files:

| Scope | Path | Notes | |---|---|---| | Global | ~/.unipi/config/compactor/config.json | Used by default | | Per project | <project>/.unipi/config/compactor.json | Enabled from settings with Project Override |

Per-project config is merged over global config when the current project directory is known.

User-facing slash commands

| Command | What it does | Notes | |---|---|---| | /unipi:lossless-compact | Immediately calls Pi compaction with UniPi's zero-LLM sentinel. | Main manual compaction command. | | /unipi:compact | Deprecated alias for /unipi:lossless-compact. | Kept for backward compatibility. | | /unipi:session-recall <query> | Searches current session history with BM25/regex recall. | Uses the append-only session branch when available, so pre-compaction messages can still be found. | | /unipi:compact-recall <query> | Deprecated alias for /unipi:session-recall. | Kept for backward compatibility. | | /unipi:compact-stats | Shows session events, compaction count, token savings, sandbox runs, and search counts. | Stats are DB-backed with runtime fallbacks. | | /unipi:compact-doctor | Runs diagnostics for config, SQLite/session DB, and runtimes. | Useful when stats/recall/sandbox look broken. | | /unipi:compact-settings | Opens the TUI settings overlay. | Tabs: Presets, Strategies, Auto, Pipeline. | | /unipi:compact-preset <name> | Applies a preset globally. | Names: precise, balanced, thorough, lean. Old names map to new ones: opencode→precise, verbose→thorough, minimal→lean. | | /unipi:compact-help | Shows compact help inside Pi. | Quick command reference. |

Content/project indexing is handled by @pi-unipi/cocoindex, not this package. Use /unipi:cocoindex-init, /unipi:cocoindex-update, and cocoindex_search for indexed project search.

User-facing settings

Open settings with /unipi:compact-settings.

Keyboard:

| Key | Action | |---|---| | Tab | Switch tabs | | ↑/↓ | Move selection | | Space | Cycle/toggle selected value | | / | Search inside the Strategies tab | | Enter | Save and close | | Esc | Cancel |

Presets tab

Presets are profiles that set strategies, pipeline switches, sandbox mode, and display mode.

| Preset | Intended use | Important effects | |---|---|---| | precise | Code-heavy work, minimal waste | Full compaction sections, safe-only sandbox, opencode display, Pipeline: ttlCache + mmapPragma on. | | balanced | Daily/default profile | Compact transcript, balanced display, FTS mode auto, sandbox all, Pipeline: all six switches on. | | thorough | Debug/audit sessions | Full transcript, verbose display, sandbox all, Pipeline: all six switches on. | | lean | Quick fixes or short sessions | Brief/minimal compaction sections, no sandbox, no session continuity, Pipeline: all off. |

The Project Override row controls where settings are saved:

• disabled → save global config.
• enabled → save <project>/.unipi/config/compactor.json for only this project.

Strategies tab

These settings control what is extracted into compaction summaries or how related compactor features behave.

| Setting | Values | Meaning | |---|---|---| | Verbose Debug | on, off | Enables internal debug state. Console debug output is intentionally muted to avoid TUI rendering issues. | | Session Goals | full, brief, off | Extracts the user's active goals/request history into [Session Goal]. | | Files & Changes | all, modified-only, off | Tracks read, created, edited, and written files in [Files And Changes]. | | Commits | full, brief, off | Captures git commit hashes/messages detected in the conversation. | | Outstanding Context | full, critical-only, off | Keeps blockers, TODOs, pending decisions, and follow-ups. | | User Preferences | all, recent-only, off | Preserves user preferences learned during the session. | | Brief Transcript | full, compact, minimal, off | Keeps a rolling recent transcript after the structured sections. | | Session Continuity | full, essential-only, off | Controls XML-style resume snapshots that help the next turn continue after compaction. | | Sandbox Execution | all, safe-only, off | Controls agent-facing sandbox availability/intent. Safe-only is intended for less risky execution. | | Tool Display | opencode, balanced, verbose, custom | Controls built-in tool output rendering style and diff display behavior. |

Config-only legacy field: fts5Index remains in the schema for compatibility, but project indexing has moved to @pi-unipi/cocoindex.

Auto tab

These settings control UniPi-managed percentage auto-compaction. They are separate from Pi core's own compaction.reserveTokens behavior.

| Setting | Default | Meaning | |---|---:|---| | Percentage Trigger | off | When on, UniPi checks context usage at turn_end and can call compaction when the threshold is reached. Disabled by default for backward compatibility. | | Threshold | 80% | Trigger point using Pi's live ctx.getContextUsage().percent. | | Cooldown | 60s | Minimum time between UniPi-triggered compaction attempts. Prevents loops. | | Repeat Growth | 4k | If usage is still above threshold after compaction, require this many new tokens before triggering again. | | Notifications | on | Shows user-visible notifications for UniPi-triggered compaction attempts/results. |

Example config:

{
  "autoCompaction": {
    "enabled": true,
    "thresholdPercent": 80,
    "cooldownMs": 60000,
    "repeatMinGrowthTokens": 4000,
    "notify": true
  }
}

Pipeline tab

Pipeline switches are low-level feature flags used by presets and advanced users.

| Setting | Preset behavior | Current effect | |---|---|---| | TTL Cache | On in precise, balanced, thorough; off in lean | Reserved/compatibility switch for cache behavior. Search has an internal cache, but this toggle is not currently required for it. | | Auto Injection | On in balanced, thorough; off in precise, lean | Active. Adds behavioral/session state to the resume snapshot after compaction. | | MMap Pragma | On in precise, balanced, thorough; off in lean | Reserved/compatibility switch for SQLite mmap tuning. | | Proximity Reranking | On in balanced, thorough; off in precise, lean | Reserved/compatibility switch for future recall/search ranking. | | Timeline Sort | On in balanced, thorough; off in precise, lean | Reserved/compatibility switch for future chronological recall sorting. | | Progressive Throttling | On in balanced, thorough; off in precise, lean | Reserved/compatibility switch for future large-project throttling. |

If all Pipeline values stay off after choosing a preset, that means the running version is not applying preset pipeline values correctly. Choose a preset, press Enter to save, and verify you are on a version containing the preset pipeline fix.

Config-only pipeline field:

| Field | Meaning | |---|---| | customNoisePatterns | Extra regex/string patterns used by session recall filtering to remove noisy user blocks. |

What the agent gets

Agent tools

The extension registers tools during session_start after the session DB is initialized.

| Tool | Purpose | |---|---| | compact | Agent-facing compaction request; supports dryRun: true preview. Slash command /unipi:lossless-compact is the user-facing immediate compaction path. | | session_recall | Search current session history with BM25 or regex. | | vcc_recall | Deprecated alias for session_recall. | | sandbox | Run code in a sandboxed environment. Languages: JavaScript, TypeScript, Python, shell, Ruby, Go, Rust, PHP, Perl, R, Elixir. | | sandbox_file | Execute a file with its content injected as FILE_CONTENT. | | sandbox_batch | Run multiple sandbox execution items in one atomic response. | | ctx_execute | Deprecated alias for sandbox. | | ctx_execute_file | Deprecated alias for sandbox_file. | | ctx_batch_execute | Deprecated alias for sandbox_batch. | | compactor_stats | Agent-readable stats dashboard. | | ctx_stats | Deprecated alias for compactor_stats. | | compactor_doctor | Agent-readable diagnostics. | | ctx_doctor | Deprecated alias for compactor_doctor. | | context_budget | Uses live Pi context usage when available and returns compaction guidance. |

Agent skills

| Skill | Purpose | |---|---| | compactor | Small always-loadable routing skill: when to compact, recall, check budget, or use sandbox. | | compactor-detail | On-demand full tool reference and workflow guidance. | | compactor-stats | Help interpreting compactor stats. | | compactor-doctor | Help diagnosing config/DB/runtime issues. |

How the system works

Chronological hook flow

Typical session order:

1. Extension load

   • Registers compaction hooks immediately with lazy dependencies.
   • Creates in-memory runtime counters/state.

2. session_start

   • Scaffolds config if needed.
   • Initializes SessionDB and sandbox executor.
   • Computes the current session ID, including worktree suffix.
   • Registers agent tools and slash commands.
   • Registers the info-screen Compactor group.
   • Emits UniPi MODULE_READY.

3. before_agent_start

   • Reloads config for the active project.
   • Applies runtime autoDetect behavior, such as disabling commit extraction outside git repos.
   • Rebuilds cached recall blocks from Pi's append-only session branch.
   • If a resume snapshot exists from a prior compaction, injects it into session context and marks it consumed.

4. input

   • Performs advisory security checks for shell/network/file patterns.
   • Can block some known-dangerous network shell commands.

5. Tool execution → tool_result

   • Extracts file/change/search/sandbox events into the session DB.
   • Updates runtime byte/tool counters.
   • Applies display overrides and width-safe diff clamping before output reaches the TUI.

6. turn_end

   • If percentage auto-compaction is enabled, reads ctx.getContextUsage().
   • Runs cooldown/repeat-growth safeguards.
   • Calls ctx.compact({ customInstructions: COMPACTOR_INSTRUCTION }) when eligible.

7. Pi decides to compact

   • This can be from /unipi:lossless-compact, UniPi percentage auto-compaction, or Pi core's reserve-token fallback.

8. session_before_compact

   • Pi provides preparation, branchEntries, and optional custom instructions.
   • If compactor should handle it, UniPi:
     1. chooses the safe cut point (buildOwnCut),
     2. converts messages to LLM-like input,
     3. runs the zero-LLM compile pipeline,
     4. persists stats/snapshots,
     5. returns { compaction: { summary, details, tokensBefore, firstKeptEntryId } } to Pi.

9. session_compact

   • Pi commits the compaction entry.
   • UniPi increments compaction counters and persists token/character savings.

10. Next before_agent_start after compaction

    • UniPi injects the resume snapshot so the agent gets continuity without needing the full old transcript in context.

11. session_shutdown

    • Cleans old sessions.
    • Cleans sandbox/background processes.
    • Closes DB handles.

Zero-LLM compile pipeline

When UniPi handles session_before_compact, it transforms old messages through these deterministic stages:

1. Normalize — flatten user/assistant/tool/thinking messages into normalized blocks.
2. Filter — remove noise and apply customNoisePatterns.
3. Build sections — extract goals, files, commits, outstanding context, preferences, and transcript entries.
4. Brief — cap and condense transcript lines.
5. Format — emit a structured markdown summary.
6. Merge — merge with the previous summary when Pi provides one.

The resulting summary is optimized for continuity, not for perfect archival fidelity. Use session_recall when the agent needs details from the raw session branch.

Benchmarks

Synthetic compile-only benchmark, run on this repository with Node 24 using compile() directly. Token counts use the common chars / 4 estimate. Real compaction also keeps a recent live tail, so final live-context size can be larger than the summary-only number below.

| Synthetic session | Input chars | Approx input tokens | Summary chars | Approx summary tokens | Reduction | Compile time | |---:|---:|---:|---:|---:|---:|---:| | 100 turns / 400 messages | 356,913 | 89,228 | 36,451 | 9,113 | 89.8% | 12.5 ms | | 250 turns / 1,000 messages | 894,063 | 223,516 | 36,585 | 9,146 | 95.9% | 16.6 ms | | 500 turns / 2,000 messages | 1,789,313 | 447,328 | 36,605 | 9,151 | 98.0% | 35.8 ms |

Practical interpretation:

• Larger sessions compress better because the structured summary has fixed caps.
• Runtime is local and usually small relative to model/tool latency.
• Actual savings reported to users should come from /unipi:compact-stats, because Pi supplies real tokensBefore during compaction when available.

Troubleshooting

"Whatever preset I choose, Pipeline is always off"

That means preset application is not updating config.pipeline. The intended behavior is:

• precise: ttlCache + mmapPragma on.
• balanced: all six pipeline switches on.
• thorough: all six pipeline switches on.
• lean: all pipeline switches off.

Make sure you are running a version with the preset pipeline fix, select the preset, and press Enter to save.

"Compaction did not happen"

• For immediate user-triggered compaction, use /unipi:lossless-compact.
• For automatic percentage compaction, enable Auto → Percentage Trigger.
• Pi core still has its own reserve-token fallback; UniPi's percentage trigger is optional and disabled by default.

"Stats show zero"

• Stats only increase after compaction or after tracked sandbox/search events.
• Run /unipi:compact-doctor to check DB/config health.
• Long sessions may show all-time DB fallbacks if current in-memory counters are zero.

"Recall cannot find something"

• Use specific terms with /unipi:session-recall <query>.
• The recall path prefers Pi's append-only branch and falls back to cached normalized blocks.
• Extra noise filtering can be added with pipeline.customNoisePatterns.

License

MIT