Pi · 3 of 5
Tools, context, and compaction
Pi’s coding layer manages context at several points: bounded reads before text enters history, typed session entries, compaction-aware path construction, token estimates, valid cut points, and lossy summaries.
§1
The read tool paginates before the model sees the file
At the pinned commit, the coding-agent read schema accepts a one-indexed offset and optional limit. Text output is capped at 2,000 lines or 50 KiB, whichever arrives first, and the tool description tells the model to continue with another offset. Source · schema Source · defaults
Head truncation keeps complete lines. If the first line alone exceeds the byte budget, the bounded head can contain no text, rather than returning an invalid partial line. This is coding-tool policy, not a limit in pi-agent-core.
§2
Context policy spans three representations
| Representation | Owner | Pressure operation | Information consequence |
|---|---|---|---|
| Tool observation | Coding tool | Offset/limit and line/byte truncation. | Only a bounded page becomes a tool-result message. |
| Session entry tree | SessionManager | Follow active leaf; insert compaction or branch-summary entries. | Full branch structure remains; one active path becomes context. |
| LLM messages | Agent context transform/conversion | Build compaction-aware entries and convert custom types. | Provider sees a selected summary plus retained tail. |
Pi’s session is an append-only tree of entries. Branching moves the active leaf without deleting old descendants. Context construction follows the current root-to-leaf path; after a compaction entry, older summarized entries are omitted and the summary plus kept tail remain. Source · active context path
§3
The trigger math is simple and conditional
The pinned defaults enable compaction, reserve 16,384 tokens for the next request/output margin, and target 20,000 recent tokens to keep verbatim. Source · defaults
The threshold test is contextTokens > contextWindow - reserveTokens. For a hypothetical 128,000-token model under the defaults, the threshold is 111,616 tokens. This arithmetic is an example; the code uses the selected model’s actual context window and configuration. Source · trigger
When provider usage is available, the estimator uses it for the covered prefix and estimates later messages. Otherwise it estimates all messages. After compaction, stale pre-compaction usage must not immediately retrigger the same decision.
§4
Cut points preserve protocol structure
The selector walks backward from the recent tail target and accepts only valid boundaries. It avoids starting the retained region at an orphaned tool result and distinguishes ordinary turn boundaries from a possible split-turn prefix.
prepareCompaction() carries a previous summary forward, separates history selected for summarization from the retained tail, preserves a split-turn prefix when needed, and accumulates file-operation information for the next summary. Source · cut selection Source · preparation
§5
Branch summaries preserve an abandoned path as context
When navigation branches from an earlier entry, Pi can append a branch_summary at the new target describing the abandoned path. The old branch remains in the entry tree; the summary becomes part of the new active path. Source · branch methods
Compaction and branch summary are both lossy model-visible representations, but they answer different navigation events: pressure within a path versus moving to another path while retaining a digest of what was left behind.
§6
What remains recoverable
The session tree preserves original entries and branches. The active model context may contain only the latest compaction summary, a retained tail, and a branch summary. A read page omitted by the tool is not in session unless fetched later. A summary can carry file-operation lists and decisions, but cannot preserve every exact line of earlier context.