# @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