$ cat ~/map/big-pi.md

big-pi

Model-driven compression that summarizes completed phases into tiered blocks while Pi's JSONL transcript stays authoritative and untouched.

extensions✓ Oct 16

Installs from a local package directory: pi install /opt/big-pi after verifying the release archive (sha256sum -c big-pi-0.1.0.zip.sha256, then node verify-release.js); no third-party runtime dependencies

## TL;DR

A standalone pi extension for model-driven conversation compression: the active model summarizes completed phases into three tiers of blocks while the JSONL transcript stays authoritative, with checkpoints before every model request and bounded emergency recovery under context pressure.

## Key points

• $Three tiers of blocks: Tier 1 compresses eligible raw messages, Tier 2 consolidates Tier-1 blocks, Tier 3 consolidates Tier-2 blocks, and only one highest applicable representation of a source range reaches the model; the README credits billion-context-pi as the approach's inspiration.
• $The active model does the compressing: /big-pi compact queues a follow-up, the model must first call big_pi_compression_sources and select one contiguous candidate, then pass its candidateId with an agent-written summary to big_pi_compress — no hidden summarizer or automatic range selector is used.
• $Growth, percentage, and hybrid checkpoints run before every model request, including between tool cycles; compression happens in a bounded phase where task tools pause, capped at a six-request prompt budget, after which big-pi lets the agent response settle and yields to native compaction.
• $Pi-native compaction is intercepted while big-pi's state is healthy, with bounded, model-driven emergency recovery for context pressure or overflow; unsafe or failed recovery yields to Pi's native fallback.
• $Storage sits beside the session in a <session>.jsonl.big-pi folder with an atomic manifest.json and immutable chunk files; chunks are validated before the manifest references them, and the JSONL transcript is never rewritten.
• $Extensions that run independent agents can set BIG_PI_AGENT_ID for a separate context store per agent, with deleteBigPiAgentData exported for cleanup.

## FAQ

## References

• README ↗
• START_HERE ↗

Last updated: Oct 16, 2026