pi-smart-compact

Verification-oriented smart compaction for the Pi Coding Agent.

Default compaction trims your conversation blind. pi-smart-compact keeps what
the agent actually needs to continue — the goal, changed files, unresolved
errors, decisions, constraints, and open loops — through a verified
Extract → Explore → Synthesize → Verify pipeline.

Facts first, synthesis second, verification last.

Why

Default compaction produces a vague recap and quietly drops the operational
context that matters most during coding. The result is the classic
"didn't we already fix this?" loop.

Install

pi install npm:pi-smart-compact

From GitHub:

pi install git:github.com/alpertarhan/pi-smart-compact

Quick start

/smart-compact                              # interactive — pick model + profile
/smart-compact anthropic/claude-sonnet-4 balanced
/smart-compact "focus on auth + unresolved follow-ups"
/smart-compact metrics                      # profile / provider comparison
/smart-compact dashboard                    # interactive TUI dashboard

Or let the agent call it as a tool on long sessions:

{
  "name": "smart_compact",
  "parameters": { "profile": "balanced", "dashboard": false }
}

Auto-compaction also runs before Pi's native compact once context pressure
crosses your threshold (default 60% actual context usage).

How it works

flowchart LR
    A["Extract<br/>deterministic facts<br/><i>0 LLM calls</i>"] --> B["Explore<br/>optional deep<br/>analysis"]
    B --> C["Synthesize<br/>single-pass or<br/>chunked summary"]
    C --> D["Verify<br/>score gaps,<br/>repair"]
    D --> E["Return verified<br/>summary to Pi"]

What it preserves: user goal · constraints & preferences · modified / read /
deleted files · unresolved & resolved errors · key decisions · open follow-up
work · critical next-turn context · the delta since the previous compaction.

Integration surfaces

A short-lived pending summary is staged in memory (5-minute TTL) and handed to
Pi when compaction is applied.

Example output

A generated summary follows a stable, structured contract:

## Goal
Add retry/backoff to the LLM client so transient 429/5xx don't abort compaction.

## Constraints & Preferences
- [requirement] never compact mid-turn from the tool path

## Progress
### Done
- [x] Added `withRetry` wrapper in src/infra/llm-retry.ts
### In Progress
- [ ] Wire retry client into the services container
### Blocked
- None

## Key Decisions
- **Honor Retry-After verbatim**: providers that set it know their limits best.

## Files Modified
- src/infra/llm-retry.ts
- src/infra/llm-client.ts

## Files Read
- src/app/run-smart-compact.ts

## Open Loops
- [high] Retried but unresolved: AbortSignal ignored by some providers

## Changes Since Last Compaction
- New files touched: src/infra/llm-retry.ts
- New loops: AbortSignal ignored by some providers

## Next Steps
1. Add an outer hard-timeout as a second line of defense

## Critical Context
- 408/425/429/5xx are retriable; 4xx (other) fails fast

## Topics Covered
- LLM retry wrapper (high)

A machine-readable CompactionState is built alongside it for reuse across
later compactions (delta tracking, damage detection).

Configuration

Add to ~/.pi/agent/settings.json:

{
  "smartCompact": {
    "profile": "balanced",
    "summaryModel": "anthropic/claude-sonnet-4",
    "autoTrigger": true,
    "minContextPercent": 60,
    "backupEnabled": true
  }
}

Profiles

The legacy config key semanticCompact is still accepted.

Safeguards

Correctness

• Deterministic extraction before any synthesis
• Verification scoring with deterministic patching before LLM patching
• Hallucinated file-reference detection (SemVer-aware)
• Open-loop injection + cross-compaction delta tracking

Safety

• Conversation backups before compaction (retention-pruned)
• toolCall / toolResult pair integrity at the compaction boundary
• Cross-session leak guard on the pending summary
• Session-log recovery that bypasses truncation of older tool results

Observability

• Metrics logging with profile / provider comparison
• Post-compaction damage (regression) detection
• Interactive TUI + HTML dashboards

Usage notes

• Auto / tool compaction is skipped while context is small (below 60% actual usage).
• Manual /smart-compact bypasses that gate — you asked for it.
• pi-toolkit's tool=XX% means tool-output ratio, not context fullness;
  smart-compact uses actual context=XX%.
• The tool path does not compact mid-turn (it stages a pending summary).
• Exploration is adaptive and may be skipped for simple sessions.

Companions & compatibility

pi-smart-compact is designed to coexist with — and recommended alongside —
pi-toolkit. pi-toolkit handles
everyday context hygiene (anchors, pivots, status lines, old tool-output
trimming); smart-compact handles high-pressure verified compaction. The
integration protects recent pi-toolkit anchors and recovers original tool
outputs from the session log.

Because smart-compact sits close to Pi's compaction path, take extra care with
extensions that also rewrite compaction hooks, branch history, entry IDs, tool
output, or the compaction boundary. If you run another automatic compaction /
context-rewriting extension, prefer a single session_before_compact owner
unless hook order is explicitly coordinated.

Runtime artifacts

The extension writes under ~/.pi/agent/:

Development

bun install
bun run typecheck   # tsc --noEmit
bun test            # full test suite
bun run build       # dist/ output for publishing

Pull requests run the same verification in GitHub Actions before merge.

Documentation

• ARCHITECTURE.md — system design, execution model, layer responsibilities
• CHANGELOG.md — release history
• CONTRIBUTING.md — contributor workflow and expectations
• SECURITY.md — vulnerability reporting and data-handling notes
• SUPPORT.md — where to ask for help
• docs/RELEASE.md — release checklist

License

MIT © Alper Tarhan