Pi Continuity

Keep useful context. Keep the way back.

Pi Continuity helps long-running Pi Coding Agent sessions manage noisy tool output, recover evidence, and carry goals, constraints, decisions and unfinished work through compaction. Pi owns the session lifecycle; this extension adds context hygiene and continuity policies around it.

Get started · User guide · Configuration · Documentation index

Pi Continuity is the product name; pi-smart-compact is the package. /smart-compact, smart_* tools and smartCompact settings are unchanged. The TUI still says Smart Compact. No data or configuration migration is needed. Identity and naming.

Upgrading from 9.x? Update Pi to 0.87.1 or newer and read the upgrade notes. Optional memory engines and image rendering are installed separately. The changelog records the full release and its evidence limits.

New in 10.4.0 — cache-aware economics: configurable trim limits with a tail-aware planning frontier, an opt-in fingerprint-aware pending lifetime, a provider cache-capability matrix, cache-inactive route detection, opt-in prompt_cache_key routing, long-context pricing visibility, trim ROI in smart_context status, and automatic anchors for committed compactions. See the changelog and configuration.

What it does

| Task | Use | Boundary | | --- | --- | --- | | Reduce old tool-output noise | Context hygiene: archive eligible output behind retrievable references | Protected instructions, failures and recent work stay in context. | | Finish a research detour | Checkpoint and rewind: retain a report and a path back to evidence | Not a filesystem or side-effect rollback. | | Make room for the next stage | Verified compaction: extract working state, synthesize a bounded summary, check it before apply | Verification catches known gaps; it does not guarantee semantic truth. | | Revisit a milestone | Session navigation: named anchors, read-only cross-session search, return on a new branch with carryover | Files, processes and external services are unchanged. | | Continue in a fresh session | Handoff: seed a new session from recorded state, without a model call | Not a new summary of the entire transcript; parent evidence remains retrievable. | | Reuse an approved fact | Project memory: scoped recall through one selected backend | Separate from session state, output archives and backups. |

The goal is a smaller working set, not an inaccessible history. Compaction uses Extract → Explore → Synthesize → Verify (EESV); exploration depends on the mode, and verification is primarily deterministic. How it works · Architecture

Get started

Requires Pi 0.87.1+ and Node.js 22.19+.

pi install npm:pi-smart-compact

Then, in Pi's interactive TUI:

/smart-compact

Opening Home changes nothing. Without a UI (print, RPC or SDK), the bare command instead runs a compaction with your configured defaults.

Open Settings → How it runs to choose your level of control:

| Preset | Behavior | | --- | --- | | Manual only | You start compaction or cleanup; no extension-scheduled work. | | Manual + agent | You or the agent can request compaction. | | Cleanup only | Local, recoverable cleanup; no automatic summary generation. | | Fully automatic | Cleanup plus compaction requests when idle at the configured context threshold. |

Pi's own compaction setting is separate. Pressure-first (default) keeps roomy history unchanged, allows cleanup at an early pressure gate, then requests compaction when idle at 80% if still needed. The optional native-hook strategy participates only when Pi starts compaction. Trigger settings.

For your first run, choose Compact now, inspect the plan, then review the result. A applies it; C or Esc cancels. Enter does not apply on the review screen. Approval is required unless you explicitly disable requireApproval, which then also skips the early-anchor cleanup and project-memory save/resolve confirmations.

Optional components

A normal Pi install does not install these opt-in components. Enable them only for the feature you need; nothing is downloaded, started or configured on your behalf.

| Feature (off by default) | Component | Approximate disk use¹ | | --- | --- | --- | | Mnemopi memory store | @oh-my-pi/[email protected] and its engine packages | 195 MB | | Mnemopi without Bun 1.3.14+ on PATH | [email protected] | 60 MB | | Image snapshots (visualArchiveEnabled) | @resvg/[email protected] | 3.5 MB |

¹ Measured on macOS arm64; not download sizes or cross-platform guarantees.

Status & help → Readiness & details shows the exact install command for a missing component and your Pi install root. A typical Mnemopi setup is:

npm install @oh-my-pi/[email protected] [email protected] --prefix ~/.pi/agent/npm --legacy-peer-deps

Pi uses --legacy-peer-deps, so optional peers are not pulled in automatically. Installing them explicitly records them in that package directory; they survive pi update. For a bun- or pnpm-managed Pi install, use the equivalent add command in the same directory. Memory setup.

One Home, five choices

Compact now · Clean up tool output · Settings · History & recovery · Status & help

Use arrows and Enter to navigate, Esc to go back, and D for planning or result details. Home shows context usage and effective permissions; unavailable actions explain why.

| Direct command | What happens | | --- | --- | | /smart-compact trim | Queues local cleanup without a model call. The next request is still untrimmed; the edit commits at the next natural completed-turn boundary. | | /smart-compact storage | Reports archived output; never deletes it. A scan cannot prove that an unreferenced artifact is safe to remove. | | /smart-compact context | Opens anchors, cross-session search and branch navigation. | | /smart-compact handoff dry-run | Previews a new-session seed without opening one. Use handoff [-- note] to proceed. | | /smart-compact metrics | Shows effective state, run outcomes, recent issues and the host prompt-cache ledger. |

By default permitted agent tools stay visible from session start, avoiding late schema changes to cached prefixes. Actions, not visibility, are pressure-gated; read-only recovery and metadata checkpoints remain available while roomy. Optional lazy loading uses smart_tools. The context guide is read on request, not injected. Tool availability and compaction permission are separate controls. Agent tools · All commands

Memory is optional; continuity is the core

No remote memory service is needed for session continuity. Local graph is the default for on-machine scoped recall. Choose Mnemopi for a separate local engine, or Hindsight for your existing server and bank. Only the selected backend is read or written; failures never silently fall back to another store.

Explicit saves require confirmation. When enabled, the local graph also indexes derived state after host-confirmed compactions. None of these stores replaces session backups or archived tool output. Memory workflows · Hindsight and privacy

Boundaries worth knowing

• Recovery is bounded. Rewind does not undo file changes. Archives cannot restore bytes omitted before Pi recorded the output.
• Review the summary. Extraction and deterministic verification can miss information. A verifier score is not a measure of task success.
• Experimental formats are opt-in. Provider-native summaries are not EESV-verified. Image snapshots need a supported reader and a cost check; otherwise text is used.
• Claude OAuth needs a compatible adapter. The published [email protected] normalizes Pi's own requests, not all nested model-runtime calls. Full coverage needs final-payload normalization (upstream PR #10). Compatibility details.
• Cost and quality need live evidence. Cancelled or discarded preparation still costs. Offline pilots do not establish billed savings, model fidelity or production readiness. Evaluation limits.

Documentation and development

| Need | Start here | | --- | --- | | Use, configure or recover a session | User guide · Configuration | | Understand internals or evaluate behavior | Architecture · Evaluation | | Contribute or prepare a package | Contributing · Release checklist | | Report a problem safely | Support · Security | | Browse every guide and historical report | Documentation index |

MIT © Alper Tarhan.