This reference describes automatic compaction, branch summarization, persisted entries, and extension hooks. For the user workflow, see Sessions and Context.
Source files (pi):
packages/coding-agent/src/core/compaction/compaction.ts- Auto-compaction logicpackages/coding-agent/src/core/compaction/branch-summarization.ts- Branch summarizationpackages/coding-agent/src/core/compaction/utils.ts- Shared utilities (file tracking, serialization)packages/coding-agent/src/core/session-manager.ts- Entry types (CompactionEntry,BranchSummaryEntry)packages/coding-agent/src/core/extensions/types.ts- Extension event types
For TypeScript definitions in your project, inspect node_modules/@earendil-works/pi-coding-agent/dist/.
Pi has two summarization mechanisms:
| Mechanism | Trigger | Purpose |
|---|---|---|
| Compaction | Context exceeds threshold, or /compact |
Summarize old messages to free up context |
| Branch summarization | /tree navigation |
Preserve context when switching branches |
Both use closely related structured formats and track file operations cumulatively. Summarization requests disable prompt-cache writes because these one-off prompts are unlikely to be reused.
Auto-compaction triggers when:
contextTokens > contextWindow - reserveTokens
By default, reserveTokens is 16384 tokens (configurable in ~/.pi/agent/settings.json or <project-dir>/.pi/settings.json). It only decides when compaction starts. Summary requests use the model's output limit, reduced when needed so input and output fit the context window.
Before delivering new input (prompt, steering, follow-up, or prepared messages), Pi estimates the projected context plus that input. If it crosses the threshold, compaction is persisted first, then input is emitted and appended, then the request is sent. Pending input is not part of the summarized history. The TUI shows submitted text as pending only while such a compaction runs and renders the completed compaction above the new user message. With a virtual model, Pi routes using context plus pending input, stores router state, and checks the physical model's window. The following request reuses that route only when the selected model, thinking level, and messages are unchanged.
This ordering guarantee covers input as submitted. Late message_end transformations or request-hook context growth invalidate preparation; Pi reroutes and checks the threshold again, which can compact after input delivery. If input preparation throws or the agent is aborted during it, Pi still records the pending input before reporting the failed/aborted response, so retries and session history retain it.
During a multi-turn agent run, Pi checks the canonical projected context after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Pi compacts during prepareNextTurn, then performs the existing catch-up steering poll before turn_start. It skips this between-turn check when the completed tool batch terminates the run and no queued message requires another response. Pi retains a pre-request threshold fallback for context growth after input preparation and for requests without new input, and performs final-attempt overflow recovery after the low-level run ends. A run that ends above the threshold does not compact on its own: compaction waits until the next request needs the context, so an idle or abandoned session never pays for it.
Waiting for the summary at the threshold stalls the agent for the duration of a summarization request. With compaction.background enabled (false by default), Pi starts the threshold compaction early instead:
- At the same points where it checks the threshold (before the next assistant response and before delivering new input), Pi starts summarizing in the background once the projected context reaches
contextWindow - reserveTokensminusmin(32768, (1 - backgroundStartRatio) * (contextWindow - reserveTokens)). ThebackgroundStartRatiosetting (default0.85) bounds how early background work may start on small windows; the 32768-token fixed budget bounds it on large windows. It snapshots the current branch, runssession_before_compactwithreason: "threshold", and generates the summary without blocking the agent. - The agent keeps working. Messages appended meanwhile come after the snapshot's
firstKeptEntryId, so the compaction keeps them verbatim. Background work alone does not makeAgentSession.isCompactingtrue. - At the next check after the summary is ready, Pi persists it as an ordinary compaction, even below the threshold. A result is committed once, including when several foreground callers were waiting for it.
- If threshold compaction, overflow recovery, or manual
/compactarrives first, it waits for the existing background request. It does not cancel that request or start a concurrent summary. Success reuses the still-valid result; failure or an invalid snapshot permits the original foreground path only after the background request settles. Callers arriving while that fallback runs also share its successful result, with each overflow caller retaining its own retry intent.
The TUI shows a separate Compacting(background)... indicator with an italic label. It coexists with Working, transport and retry statuses. Embedded editor indicators use ── between components; standalone indicators use |. A foreground caller waiting for the background request does not show another compaction indicator. Each indicator clears independently.
The result is discarded when the snapshot leaf left the branch, another compaction was appended, or a later context_edit targets a summarized entry. A failed background summary is not retried until history compacts again; its retry notices are not shown. Cancelling a foreground waiter does not start fallback summarization or cancel the background request. Disabling background compaction prevents new jobs and cancels unclaimed work; a summary already claimed by a foreground caller can finish for that caller.
A summary that waited for the threshold keeps every entry after the earlier snapshot cut, so the context after compaction can stay above the start ratio and begin the next background summary immediately.
A provider context-overflow error or an early final stopReason: "length" can select one compact-and-retry recovery attempt. Length responses with tool calls retain their synthetic failed tool results and follow the ordinary tool/queue scheduler rather than forcing the run to end.
You can also trigger manually with /compact [instructions], where optional instructions focus a newly generated summary. Stopping the agent for /compact does not cancel the summary being joined. Explicit cancellation, disposal, or session replacement also invalidates a queued manual request while it is still stopping the agent. If an existing background result or shared fallback is reused, the TUI reports Compaction skipped: reusing completed compaction; instructions do not cause another summary request. If background work fails or its result is invalid, manual fallback preserves those instructions and the normal extension hooks.
- Find cut point: Walk backwards through the finalized session projection, accumulating token estimates until
keepRecentTokens(default 20k, configurable in~/.pi/agent/settings.jsonor<project-dir>/.pi/settings.json) is reached - Extract messages: Collect projected messages from the previous kept boundary (or session start) up to the cut point
- Generate summary: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
- Append entry: Save
CompactionEntrywith summary andfirstKeptEntryId - Rebuilds context: Session rebuilds the context for the next request, using summary + messages from
firstKeptEntryIdonwards
Before compaction:
entry: 0 1 2 3 4 5 6 7 8 9
┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
│ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
└─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
└────────┬───────┘ └──────────────┬──────────────┘
messagesToSummarize kept messages
↑
firstKeptEntryId (entry 4)
After compaction (new entry appended):
entry: 0 1 2 3 4 5 6 7 8 9 10
┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┬─────┐
│ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
└─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
└──────────┬──────┘ └──────────────────────┬───────────────────┘
not sent to LLM sent to LLM
↑
starts from firstKeptEntryId
What the LLM sees:
┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
│ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
└────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
↑ ↑ └─────────────────┬────────────────┘
prompt from cmp messages from firstKeptEntryId
On repeated compactions, the summarized span starts at the previous compaction's kept boundary (firstKeptEntryId), not at the compaction entry itself, falling back to the entry after the previous compaction if that kept entry cannot be found in the path. A retain-none compaction records its own ID as firstKeptEntryId; repeated compaction starts after that entry. This preserves messages that survived the earlier compaction by including them in the next summarization pass as well. Pi also recalculates tokensBefore from the rebuilt, context-edited session projection before writing the new CompactionEntry, so the token count reflects the actual pre-compaction context being replaced. Omitted raw entries remain stored but do not affect cut selection, summaries, checkpoints, or token estimates.
Recovery preserves the existing lifecycle and queue order. The completed attempt remains visible to turn_end and agent_end; post-run recovery then repairs persisted model context before a fresh retry:
persist final assistant response
→ extension/public turn_end
→ extension/public agent_end
→ append context_edit omissions for the selected attempt
→ for overflow/length: run session_before_compact and append compaction on success
→ start the retry as a fresh run
If recovery compaction fails or is cancelled, Pi keeps the omission edits, appends no compaction, and schedules no internal retry. Existing queued work remains governed by ordinary steering and follow-up rules. agent_before_settle sees the repaired projection after recovery processing. Raw transcript history, exports, billing totals, and history-search extensions can still inspect the omitted attempt.
A user-message span starts with a user message and includes all turns until the next user message. Normally, compaction cuts at user-message boundaries.
When one user-message span exceeds keepRecentTokens, the cut point lands within that span at an assistant message. This is a split user-message span:
Split user-message span (one span exceeds budget):
entry: 0 1 2 3 4 5 6 7 8
┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
│ hdr │ usr │ ass │ tool │ ass │ tool │ tool │ ass │ tool │
└─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴──────┘
↑ ↑
turnStartIndex = 1 firstKeptEntryId = 7
│ │
└──── turnPrefixMessages (1-6) ───────┘
└── kept (7-8)
isSplitTurn = true
messagesToSummarize = [] (no earlier user-message spans)
turnPrefixMessages = [usr, ass, tool, ass, tool, tool]
For split user-message spans, Pi generates two summaries and merges them:
- History summary: Previous context (if any)
- User-message-span prefix summary: The early part of the split user-message span
Valid cut points are:
- User messages
- Assistant messages
- BashExecution messages
- Custom messages (custom_message, branch_summary)
Never cut at tool results (they must stay with their tool call).
Preparation advances the kept boundary into a context-invisible suffix only when that suffix contains an omitted assistant attempt and no unomitted context-producing entries. Recovery context_edit omissions satisfy this rule; intrinsically context-invisible metadata may coexist with them. Metadata alone and newly appended custom messages do not move the cut. A replacement edit affecting the candidate input or summarized prefix also blocks advancement because the omitted assistant answered the pre-edit input; replacements of suffix entries that are ultimately omitted remain safe. This allows an over-budget recovered input to be summarized while retaining the edits that keep the abandoned attempt omitted, without making bookkeeping change whether new model input is preserved verbatim.
Defined in session-manager.ts:
interface CompactionEntry<T = unknown> {
type: "compaction";
id: string;
parentId: string | null;
timestamp: string;
summary: string;
firstKeptEntryId: string;
tokensBefore: number;
usage?: Usage; // LLM usage that generated the summary
fromHook?: boolean; // true if provided by extension (legacy field name)
details?: T; // implementation-specific data
}
// Default compaction uses this for details (from compaction.ts):
interface CompactionDetails {
readFiles: string[];
modifiedFiles: string[];
}Extensions can store any JSON-serializable data in details. The default compaction tracks file operations, but custom extension implementations can use their own structure. Generated and extension-provided summaries store their LLM usage when available so session totals include summarization work.
See prepareCompaction() and compact() for the implementation. For direct programmatic summarization, generateSummary() returns the summary text and generateSummaryWithUsage() returns { text, usage }.
When you use /tree to navigate to a different branch, Pi offers to summarize the work you're leaving. This injects context from the left branch into the new branch.
- Find common ancestor: Deepest node shared by old and new positions
- Collect entries: Walk from old leaf back to common ancestor
- Prepare with budget: Include messages up to token budget (newest first)
- Generate summary: Call LLM with structured format
- Append entry: Save
BranchSummaryEntryat navigation point
Tree before navigation:
┌─ B ─ C ─ D (old leaf, being abandoned)
A ───┤
└─ E ─ F (target)
Common ancestor: A
Entries to summarize: B, C, D
After navigation with summary:
┌─ B ─ C ─ D
A ───┤
└─ E ─ F ─ [summary of B,C,D] (new leaf)
Default compaction and branch summarization track files cumulatively. Both extract file operations from tool calls in the messages being summarized. Compaction also carries file lists from the previous Pi-generated compaction. Branch summarization carries file lists from Pi-generated branch summaries in the entries it summarizes.
File tracking therefore accumulates across default compactions and nested default branch summaries. Pi does not automatically carry file lists from extension-generated summaries whose fromHook field is true; extensions manage their own details format.
Defined in session-manager.ts:
interface BranchSummaryEntry<T = unknown> {
type: "branch_summary";
id: string;
parentId: string | null;
timestamp: string;
summary: string;
fromId: string; // Entry we navigated from
usage?: Usage; // LLM usage that generated the summary
fromHook?: boolean; // true if provided by extension (legacy field name)
details?: T; // implementation-specific data
}
// Default branch summarization uses this for details (from branch-summarization.ts):
interface BranchSummaryDetails {
readFiles: string[];
modifiedFiles: string[];
}Same as compaction, extensions can store custom data in details.
See collectEntriesForBranchSummary(), prepareBranchEntries(), and generateBranchSummary() for the implementation.
Both formats include Goal, Constraints & Preferences, Progress, Key Decisions, and Next Steps. Compaction summaries also include Critical Context. Branch summaries stop after Next Steps. Pi appends file lists to either format when relevant.
Compaction summaries use this format:
## Goal
[What the user is trying to accomplish]
## Constraints & Preferences
- [Requirements mentioned by user]
## Progress
### Done
- [x] [Completed tasks]
### In Progress
- [ ] [Current work]
### Blocked
- [Issues, if any]
## Key Decisions
- **[Decision]**: [Rationale]
## Next Steps
1. [What should happen next]
## Critical Context
- [Data needed to continue]
<read-files>
path/to/file1.ts
path/to/file2.ts
</read-files>
<modified-files>
path/to/changed.ts
</modified-files>Before summarization, messages are serialized to text via serializeConversation():
[User]: What they said
[Assistant]: Response text
[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
[Tool result]: Output from tool
This prevents the model from treating it as a conversation to continue.
Thinking blocks are omitted. Providers return summaries of the real reasoning, and replayed thinking is often not part of the model's live context, so including it could make the summarization request larger than the context it summarizes.
Tool results are truncated to 2000 characters during serialization. Content beyond that limit is replaced with a marker indicating how many characters were truncated. This keeps summarization requests within reasonable token budgets, since tool results (especially from read and bash) are typically the largest contributors to context size.
Extensions can intercept and customize both compaction and branch summarization. See extensions/types.ts for event type definitions.
Fired before auto-compaction or /compact. Can cancel or provide custom summary. With background compaction, threshold events fire when background summarization starts, while the agent is still running; the returned compaction is persisted later if the snapshot is still valid. See SessionBeforeCompactEvent and CompactionPreparation in the types file.
pi.on("session_before_compact", async (event, ctx) => {
const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;
// preparation.messagesToSummarize - messages to summarize
// preparation.turnPrefixMessages - user-message-span prefix (if isSplitTurn)
// preparation.previousSummary - previous compaction summary
// preparation.fileOps - extracted file operations
// preparation.tokensBefore - context tokens before compaction
// preparation.firstKeptEntryId - where kept messages start
// preparation.settings - effective settings after applying model overrides
// branchEntries - all entries on current branch (for custom state)
// reason - "manual" (/compact), "threshold", or "overflow"
// willRetry - whether the aborted turn is retried after compaction (overflow recovery)
// signal - AbortSignal (pass to LLM calls)
// Cancel:
return { cancel: true };
// Custom summary:
return {
compaction: {
summary: "Your summary...",
firstKeptEntryId: preparation.firstKeptEntryId,
tokensBefore: preparation.tokensBefore,
// usage: summaryResponse.usage, // Optional; included in session totals
details: { /* custom data */ },
}
};
});To generate a summary with your own model, convert messages to text using serializeConversation:
import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
pi.on("session_before_compact", async (event, ctx) => {
const { preparation } = event;
// Convert AgentMessage[] to Message[], then serialize to text
const conversationText = serializeConversation(
convertToLlm(preparation.messagesToSummarize)
);
// Returns:
// [User]: message text
// [Assistant]: response text
// [Assistant tool calls]: read(path="..."); bash(command="...")
// [Tool result]: output text
// Now send to your model for summarization
const { summary, usage } = await myModel.summarize(conversationText);
return {
compaction: {
summary,
firstKeptEntryId: preparation.firstKeptEntryId,
tokensBefore: preparation.tokensBefore,
usage,
}
};
});See custom-compaction.ts for a complete example using a different model.
Fired when manual or automatic compaction fails or is aborted. This is useful for telemetry extensions that need to pair session_before_compact attempts with terminal outcomes.
pi.on("session_compact_failed", async (event, ctx) => {
const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
// reason - "manual" (/compact), "threshold", or "overflow"
// errorMessage - present for non-abort failures
// aborted - true for canceled/aborted compactions
// willRetry - whether the aborted turn would have retried after compaction
// fromExtension - whether extension-provided compaction content was being used
});Fired before /tree navigation. Always fires regardless of whether user chose to summarize. Can cancel navigation or provide custom summary.
pi.on("session_before_tree", async (event, ctx) => {
const { preparation, signal } = event;
// preparation.targetId - where we're navigating to
// preparation.oldLeafId - current position (being abandoned)
// preparation.commonAncestorId - shared ancestor
// preparation.entriesToSummarize - entries that would be summarized
// preparation.userWantsSummary - whether user chose to summarize
// Cancel navigation entirely:
return { cancel: true };
// Provide custom summary (only used if userWantsSummary is true):
if (preparation.userWantsSummary) {
return {
summary: {
summary: "Your summary...",
// usage: summaryResponse.usage, // Optional; included in session totals
details: { /* custom data */ },
}
};
}
});See SessionBeforeTreeEvent and TreePreparation in the types file.
Configure compaction in ~/.pi/agent/settings.json or <project-dir>/.pi/settings.json:
{
"compaction": {
"enabled": true,
"reserveTokens": 16384,
"keepRecentTokens": 20000
}
}| Setting | Default | Description |
|---|---|---|
enabled |
true |
Enable auto-compaction |
reserveTokens |
16384 |
Free context tokens below which auto-compaction starts |
keepRecentTokens |
20000 |
Recent tokens to keep (not summarized) |
background |
false |
Summarize ahead of the threshold without blocking the agent; requires enabled |
backgroundStartRatio |
0.85 |
Earliest-start guard for background summarization; the actual start point is threshold - min(32768, (1 - ratio) * threshold) |
Disable auto-compaction with "enabled": false. You can still compact manually with /compact.
Use compaction.modelOverrides to tune token budgets for different models:
{
"compaction": {
"reserveTokens": 16384,
"keepRecentTokens": 20000,
"modelOverrides": {
"some-provider/big-model": {
"reserveTokens": 400000
}
}
}
}For a model with a 1M context window, this override triggers compaction above 600K tokens and keeps the ordinary 20000 recent tokens. Other models retain the ordinary 16384-token reserve.
Keys are exact, case-sensitive provider/modelId values, including any slashes within the model ID. Each reserveTokens and keepRecentTokens value falls back independently from the model override to the ordinary setting to the built-in default. Values must be non-negative safe integers. Invalid values in the matching model override produce an error when read; only omitted fields fall back to the ordinary setting. Model override entries must be objects. Invalid ordinary token settings produce an error when read, even if the active model has a valid override. Only omitted ordinary values use built-in defaults. enabled remains global, not model-specific.
These resolved values are used for manual compaction, all automatic threshold checks, overflow recovery, and extension-visible preparation.settings. Model switches affect subsequent checks and compactions without changing ordinary settings. Compaction already in progress uses the model and settings captured for that operation. Branch summarization settings are unaffected.
Overrides work in both global and project settings. The files merge recursively before lookup, so a global model-specific value beats a project-wide fallback; a project must override that model entry to change it. See Settings for details.