[](https://github.com/alpertarhan/pi-smart-compact/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/pi-smart-compact)
[](https://github.com/alpertarhan/pi-smart-compact/blob/main/LICENSE)
[](https://github.com/earendil-works/pi)
### Verification-oriented context compaction for the Pi Coding Agent
Preserve the agent's **working state**—goals, files, decisions, errors,
constraints, and open loops—not just a vague recap of the conversation.
## Install
```bash
pi install npm:pi-smart-compact
```
Or install directly from GitHub:
```bash
pi install git:github.com/alpertarhan/pi-smart-compact
```
## Quick start
```bash
/smart-compact # interactive model + profile picker
/smart-compact balanced # direct profile
/smart-compact anthropic/claude-sonnet-4 balanced # direct model + profile
/smart-compact balanced --focus=auth # preserve extra auth detail
/smart-compact metrics # text metrics report
/smart-compact dashboard # interactive metrics dashboard
/smart-compact restore # browse and restore backups
/smart-compact loops # manage persisted open loops
```
The extension also participates in Pi's native compaction flow automatically
when actual context usage crosses the configured threshold (60% by default),
and exposes a `smart_compact` tool for long-running agents.
> The tool path stages a safe pending summary. It never compacts the active
> conversation in the middle of an agent turn.
## Why smart compaction?
| Native-style recap | `pi-smart-compact` |
| --- | --- |
| Summarizes prose | Preserves operational coding state |
| Trusts one LLM response | Extracts deterministic ground truth first |
| File/error omissions can be silent | Verifies coverage and repairs known gaps |
| One strategy for every session | Chooses single-pass or hierarchical synthesis |
| No quality feedback | Tracks provenance, damage signals, and metrics |
The design principle is simple:
> **Facts first. Synthesis second. Verification before apply.**
## EESV pipeline
```text
Pi conversation
│
▼
┌───────────┐ ┌───────────┐ ┌────────────┐ ┌───────────┐
│ Extract │ → │ Explore │ → │ Synthesize │ → │ Verify │
│ 0 LLM │ │ adaptive │ │ 1-pass or │ │ + repair │
│ calls │ │ │ │ hierarchical│ │ │
└───────────┘ └───────────┘ └────────────┘ └───────────┘
│
▼
staged/applied by Pi
```
| Stage | Responsibility |
| --- | --- |
| **Extract** | Deterministically catalogs files, errors, decisions, constraints, topics, media metadata, and open loops. This is the verification ground truth. |
| **Explore** | Uses a cheaper segmentation model when a complex session needs deeper topic boundaries or error-chain inspection. Simple sessions skip it. |
| **Synthesize** | Uses one pass for short sessions and bounded chunk/assembly fallbacks for long sessions. Focus and call/latency budgets are enforced here. |
| **Verify** | Checks canonical sections and extracted facts, applies every safe deterministic repair, and escalates only unresolved low-scoring gaps to an LLM patch. |
### What survives compaction
- The current goal and user constraints
- Modified, read, and deleted files
- Unresolved **and** resolved error history
- Explicit and implicit decisions
- Open follow-ups, blockers, priorities, and pinned loops
- Next actions and critical continuation context
- Changes since the previous compaction
Summaries use a canonical H1/H2/H3-aware structure, collision-safe file
matching, typed verification gaps, and persisted repair provenance.
## Usage surfaces
| Surface | Behavior |
| --- | --- |
| `/smart-compact` | Explicit manual run. Supports picker UI, direct args, dry-run, focus, and budgets. |
| `session_before_compact` | Auto path. Runs before Pi's native compaction and returns a verification-scored result when context pressure is high. |
| `smart_compact` tool | Agent path. Produces a pending summary for Pi's next natural compact; does not compact mid-turn. |
| `/smart-compact loops` | Project-level open-loop manager: resolve/reopen, priority, pin/unpin. |
### Focus and budgets
```bash
/smart-compact balanced --focus=authentication
/smart-compact aggressive --max-calls=6 --max-latency=30000
/smart-compact balanced --focus=src/auth.ts --max-calls=8
```
- `--focus` assigns more synthesis/exploration budget to a topic or path. It
does **not** attempt unsupported non-contiguous compaction.
- `--max-calls` accepts `1–100`.
- `--max-latency` accepts `5000–600000` milliseconds.
- Call-budget exhaustion degrades to deterministic summaries. The latency
budget is a hard cancellation deadline.
The tool exposes equivalent `focus`, `max_calls`, and `max_latency_ms`
parameters.
## Profiles
| Profile | Summary budget | Recent context kept | Best for |
| --- | ---: | ---: | --- |
| `light` | 10,000 tokens | 30,000 tokens | Maximum continuity and detail |
| `balanced` | 6,000 tokens | 20,000 tokens | General use; default |
| `aggressive` | 3,000 tokens | 10,000 tokens | Tight context budgets |
Profiles are a starting policy. Provider/model calibration, conversation shape,
focus hints, damage feedback, and explicit budgets refine the actual run.
## Safety and privacy
### Deterministic safeguards
- Tool-call-aware recent-tail budgeting
- Exact access-call pruning—different reads, searches, offsets, and patterns do not collapse
- Tool-call/tool-result pair integrity at the compaction boundary
- Collision-safe modified-file verification for monorepos
- Mandatory deterministic repair for patchable verification gaps
- Cross-session guard and five-minute TTL for pending summaries
- Session-log recovery for older, truncated tool results
- Retention-pruned backups before compaction
### Secrets and PII
High-confidence secret scrubbing is enabled by default at every relevant trust
boundary:
```text
provider request · extraction cache · backup · state · pending summary
```
It covers common API keys, cloud/GitHub/Slack tokens, JWTs, bearer tokens,
private keys, and credential assignments. Optional email/phone/payment-card
scrubbing is available through `scrubPii`.
Secret scrubbing is defense in depth, **not a replacement for proper secret
handling or a dedicated DLP system**. See the
[security policy](https://github.com/alpertarhan/pi-smart-compact/blob/main/SECURITY.md).
### Approval and feedback
- `requireApproval: true` adds a fail-closed manual **Apply / Cancel** decision
after the provenance review screen. Auto and tool paths retain their native
staged lifecycle.
- Online damage monitoring observes the first post-compaction messages and
records re-read files or repeated context. Remediation hints feed those files
into the next compaction.
- `adaptiveDamageFeedback` can opt a project into larger preservation budgets
after repeated high-damage reports.
## Open-loop control
```bash
/smart-compact loops
```
The manager operates on the project's persisted `CompactionState`:
- resolve or reopen a loop
- change priority
- pin or unpin it across later compactions
Overrides use normalized summary identity instead of positional IDs, so a loop
cannot accidentally inherit another loop's state on a later run.
## Configuration
Add `smartCompact` to `~/.pi/agent/settings.json`:
```json
{
"smartCompact": {
"profile": "balanced",
"summaryModel": null,
"segmentationModel": null,
"summaryThinkingLevel": null,
"segmentationThinkingLevel": null,
"autoTrigger": true,
"minContextPercent": 60,
"backupEnabled": true,
"scrubSecrets": true,
"scrubPii": false,
"requireApproval": false,
"maxLlmCalls": 0,
"maxLatencyMs": 0,
"focusWeighting": true,
"onlineDamageMonitor": true,
"adaptiveDamageFeedback": false,
"pinPaths": []
}
}
```
### Per-phase reasoning
Exploration can use a cheaper reasoning level while final synthesis and repair
use a stronger one:
```json
{
"smartCompact": {
"segmentationThinkingLevel": "low",
"summaryThinkingLevel": "high"
}
}
```
`segmentationThinkingLevel` applies to exploration; `summaryThinkingLevel`
applies to synthesis, assembly, and repair. Supported values are `minimal`,
`low`, `medium`, `high`, `xhigh`, and `max`. Leave either value as `null` to
preserve the provider's existing behavior. An explicit call-level reasoning
option takes precedence over these defaults.