pi-fold

Long sessions without forgetting. pi-fold rotates stale context out of the window and into short briefs, while the exact originals stay on disk one tool call away. It runs automatically, keeps your prefix cache warm, and never throws anything away.

Install

pi install npm:pi-fold

Requires Node 22+ and Pi 0.83+ (Pi 1.0 needs Node 22.19+). MIT licensed.

For the best results, pair it with a long-term memory store such as pi-canon. Folding keeps the window lean; the store keeps what the session learned. Together they were the strongest setup in every benchmark.

Why fold instead of compact

Compaction replaces the transcript with a summary and discards the originals. Folding replaces old spans with briefs and keeps the originals retrievable, so nothing is ever lost.

On a 64-stage coding assignment over the curl codebase, followed by a 16-question recall test about the whole session:

Same recall, half the cost, and hours faster. The savings come from the cache: folding batches its rewrites so the provider replays the cached prefix instead of rereading the session from scratch, and roughly 95% of input in the pi-fold run was served from cache.

Full write-ups, data and logs are on Zenodo (design, working memory, retrieval, rotation and retention), with friendlier versions on Medium and shaneconner.com.

What you get

• Automatic folding. Completed work is marked as it finishes and folded when the window fills up. The agent doesn't have to do anything.
• Lossless recall. Every brief links back to the original messages, verified by hash. The agent can peek at them or expand them back in place.
• A cache-friendly cadence. Marks cost nothing. All of them land together in one commit, so the cache is spent once per commit instead of on every change.
• A clean chat. Folded spans collapse into a single muted row in the chat, so your screen matches what the model actually sees.
• The fold bar. A compact usage bar above Pi's footer shows how full the window is and what's in it, from deeply folded to still raw.

Commands

The agent gets one tool, pi_fold_context, with actions to status, peek, expand, refold, pin and unpin content, plus brief, reboundary and unmark for curating pending folds. It's all optional; a session that never calls the tool still folds.

Configuration

The defaults are the benchmarked setup, so there's nothing you need to tune.

How it works

Prefix caches are positional. A provider replays the longest byte-identical prefix of a prompt, so changing one early byte invalidates everything after it. pi-fold only rewrites the window at a commit; everything else is a pure append.

Marks, then commits. As each tool batch or chapter finishes, the runtime marks it as a fold candidate. A mark lives outside the window, so it changes nothing and costs nothing. When the window reaches maxTarget, a single commit folds the stalest marks into briefs until it's back down to minTarget, leaving recent work raw.

Peek and expand. peek appends a verified, plain-text view of a fold's originals (without thinking blocks or provider metadata) for one turn, then steps aside. expand restores the original messages in place until the fold is refolded.

Plays well with Pi. Pi's own compaction stays enabled underneath. Threshold compaction is skipped because folding gets there first, overflow is recovered by folding and retrying, and manual /compact still works as an escape hatch.

Prior work

pi-fold builds on lossless hierarchical compaction (LCM, arXiv:2605.04050) and agentic context management (Letta, arXiv:2510.11967); see also arXiv:2607.00692. Its contribution is the cache-aware commit: stage every fold as a free mark, then pay for the rewrite once.