@pi-unipi/compactor

Context engine that keeps sessions lean. Compacts conversations, indexes code, searches history, and runs sandboxed code — all without burning LLM tokens on compaction.

The zero-LLM pipeline compresses context through 6 stages (normalize, filter, build sections, brief, format, merge) to hit 95%+ token reduction at zero API cost. Session continuity preserves context across compaction boundaries with XML resume snapshots.

Commands

Command	Description
/unipi:compact	Manual compaction with stats
/unipi:session-recall	Search session history (BM25 or regex)
/unipi:content-index	Index current project into FTS5
/unipi:content-search	Search indexed content
/unipi:content-purge	Wipe all indexed content
/unipi:compact-stats	Context savings dashboard
/unipi:compact-doctor	Run diagnostics
/unipi:compact-settings	TUI settings overlay
/unipi:compact-preset <name>	Apply quick preset
/unipi:compact-help	Show detailed documentation

Special Triggers

Compactor tools are available to the main agent when installed. All workflow skills can use compactor tools for context management.

Compactor registers with the info-screen dashboard, showing compaction count, tokens saved, compression ratio, and indexed documents. The footer subscribes to COMPACTOR_STATSUPDATED events to display compaction stats in the status bar.

Agent Tools

Tool	Family	Description
compact	compaction	Trigger manual compaction (dryRun: true to preview)
session_recall	session	BM25 session history search
sandbox	sandbox	Run code in sandbox (11 languages)
sandbox_file	sandbox	Execute file via FILE_CONTENT
sandbox_batch	sandbox	Atomic batch of commands + searches
content_index	content	Chunk content to FTS5 index
content_search	content	Query indexed content
content_fetch	content	Fetch URL and index
compactor_stats	compactor	Context savings dashboard
compactor_doctor	compactor	Diagnostics checklist
context_budget	compactor	Estimate remaining context window

Two-Tier Skills

• Tier 1 (compactor): ~175 tokens, always loaded. Routing and critical rules.
• Tier 2 (compactor-detail): On-demand. Full tool reference, anti-patterns, sandbox languages, FTS5 modes, workflows.

Configurables

Config lives at ~/.unipi/config/compactor/config.json. Per-project overrides at <project>/.unipi/config/compactor.json.

Presets

Preset	Description
precise	Code-heavy, minimal waste — compaction: full, pipeline: 2/6 on
balanced	Daily use (default) — all strategies moderate, pipeline: all on
thorough	Debug/audit — everything on, full transcript
lean	Quick fixes — compaction only, pipeline: all off

Apply via /unipi:compact-preset <name>.

Pipeline Features

Feature	Description	Context
TTL Cache	Cache with time-based expiry	On Compaction
Auto Injection	Inject behavioral state after compaction	On Compaction
MMap Pragma	Use mmap for SQLite I/O	On Compaction
Proximity Reranking	Rerank search results by proximity	On Search
Timeline Sort	Sort session events chronologically	On Search
Progressive Throttling	Slow down indexing for large projects	On Index

TUI

Tabbed settings interface (Presets / Strategies / Pipeline):

• / key opens search filter in Strategies tab
• Preset selection shows 3-line preview
• Per-project override checkbox (o key)
• Keyboard: left/right cycle modes, Space toggle, s save, Esc cancel

Architecture

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ Compaction Core │  │ Session Engine  │  │ Display Engine  │
│ (zero-LLM)      │  │ (SQLite + XML)  │  │ (mode-aware)    │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                    │
         └────────────────────┼────────────────────┘
                              ▼
                    ┌─────────────────────┐
                    │   Config Manager    │
                    └─────────────────────┘

License

MIT