$ cat ~/map/pi-rolling-compaction.md
pi-rolling-compaction
Trigger pi's built-in compaction once context hits a configurable threshold (default 50% of the window) so large-context models get a continuously-maintained rolling summary instead of a near-full cliff-edge.
extensions✓ Oct 16
Facts
- GitHub Stars
- ★ 0
- Forks
- 0
- license
- MIT
- npm / mo
- —
- last push
- Aug 18, 2026
install
cp rolling-compaction.ts ~/.pi/agent/extensions/## TL;DR
Codex-style rolling summarization for pi — a single-file extension that triggers compaction at a configurable percentage of the context window (default 50%) instead of near-full, keeping a continuously maintained summary on large-context models.
## Key points
- $Pi's built-in auto-compaction fires when contextTokens exceeds contextWindow minus 16384 — around 98% of the window on 1M-token models, which in practice means compaction never fires; this extension triggers at a percentage threshold (default 50%) instead.
- $Because pi folds the previous summary into every subsequent compaction, repeated threshold firing produces a true rolling summary: old work stays compressed, recent work stays verbatim (keepRecentTokens defaults to 20000).
- $Single-file extension: rolling-compaction.ts is copied into pi's auto-discovery directory (~/.pi/agent/extensions/) and then runs in every session; a one-off test is possible with pi -e ./rolling-compaction.ts.
- $How it works: listens for agent_settled, checks ctx.getContextUsage(), and calls ctx.compact() with Codex-style summary instructions covering goals, decisions with rationale, task state, files touched read-versus-modified, and next steps; a loop guard prevents re-triggering.
- $v2 hardening: compaction defers to a queued turn's settle via before_agent_start, treats the session_compact event as the only success signal for the fire-and-forget ctx.compact(), and arms a 3-minute safety timer that resets the guards if it never fires.
- $Configuration: PI_AUTOCOMPACT_THRESHOLD env var or THRESHOLD_PERCENT in the file; keepRecentTokens and reserveTokens (16384 safety net) via the compaction block in ~/.pi/agent/settings.json.
- $Summaries are generated by the current conversation model; summarizing with a cheaper model is possible via pi's custom-compaction example and its session_before_compact hook.
## FAQ
Q Why not just use pi's built-in auto-compaction?
The built-in threshold only fires when the context window is nearly full (contextTokens > contextWindow − 16384 by default) — roughly 98% on large-context models, so in practice compaction never fires and you lose the continuously maintained summary.
Q How do I test that it works?
Force the threshold with PI_AUTOCOMPACT_THRESHOLD=0.5 pi --print 'say ok' for a headless end-to-end run, or PI_AUTOCOMPACT_THRESHOLD=1 pi interactively; you should see the rolling-compaction notice and a compaction entry in the newest session file. On a tiny conversation pi may answer that there is nothing to compact, which is correct behavior.
## References
## Related entries
$ big-pi
Model-driven compression that summarizes completed phases into tiered blocks while Pi's JSONL transcript stays authoritative and untouched.
$ Self Compact
Gives autonomous pi agents their own context gauge — notice and warning lines first, then a hard cutoff where only self_compact runs.
$ dsh-pi-agent
DeepSeek Harness (DSH) AgentFactory that swaps DSH's native agent loop for a headless pi --mode rpc child, so DSH's web UI, sessions, hooks, and presets keep working with pi's minimal prompt and four tools.
## Guides
Last updated: Aug 31, 2026