12  Compaction & Branch Summarization

12.1 Overview

As conversations grow, the context window fills up. Pi provides two mechanisms to manage context growth: auto-compaction and branch summarization. Both reduce token usage while preserving the ability to continue the conversation.

12.2 Auto-Compaction

12.2.1 Triggers

Auto-compaction activates when the session approaches the model’s context window limit. The exact threshold depends on the model but typically triggers when approximately 80-90% of the context window is consumed.

You can also trigger compaction manually:

/compact
/compact Focus on the database schema changes

When you provide a prompt with /compact, it guides the summarization to prioritize specific topics.

12.2.2 How Compaction Works

graph TD
    A[Context near limit] --> B[Identify cut point]
    B --> C[Extract older entries]
    C --> D[Summarize extracted entries]
    D --> E[Insert CompactionEntry]
    E --> F[Continue session with freed context]

12.2.3 Step 1: Identify Cut Point

The cut point is the boundary between entries that will be summarized and entries that remain in full. Pi uses these rules to select the cut point:

1. Never summarize the most recent user message — always keep the current exchange intact
2. Prefer cutting after a tool result — so the model has full context of the last completed action
3. Never cut in the middle of a tool call/result pair — these must stay together
4. Respect minimum context — keep a minimum number of recent entries unsummarized
5. Prefer natural boundaries — cut at user message boundaries when possible

12.2.4 Step 2: Extract Older Entries

All entries before the cut point are collected for summarization. This includes:

• User messages
• Assistant messages
• Tool calls and their results
• Previous CompactionEntries (these get re-summarized)

Tool results may be truncated before summarization to reduce token usage. Tools listed in compactExcludedTools are never truncated.

12.2.5 Step 3: Generate Summary

Pi sends the extracted entries to the model with a summarization prompt. The model produces a structured summary that captures:

• Key decisions and their rationale
• Files created or modified
• Commands run and their outcomes
• Important context discovered
• Outstanding issues or TODOs

12.2.6 Step 4: Insert CompactionEntry

The summarized entries are replaced with a single CompactionEntry in the session tree:

{
  "type": "compaction",
  "id": "compaction-001",
  "parentId": "entry-005",
  "summary": "The user is working on a Node.js REST API...",
  "summarizedEntryIds": ["entry-001", "entry-002", "entry-003", "entry-004"],
  "filesMentioned": ["src/app.ts", "src/routes/users.ts"],
  "timestamp": "2026-07-31T12:00:00Z"
}

12.3 Split Turns

A split turn occurs when compaction happens during an active assistant response. Pi handles this gracefully:

1. The current assistant turn completes normally
2. Compaction runs before the next user message is processed
3. The model sees the compacted context for the next turn

This ensures no in-flight responses are lost.

12.4 CompactionEntry Structure

The CompactionEntry replaces the summarized entries:

Field	Type	Description
type	"compaction"	Entry type identifier
id	string	Unique entry ID
parentId	string	Parent entry in the session tree
summary	string	Model-generated summary text
summarizedEntryIds	string[]	IDs of entries that were summarized
filesMentioned	string[]	Files referenced in summarized entries
timestamp	string	ISO timestamp of compaction
modelId	string	Model used for summarization
tokenCount	number	Approximate token count of the summary

12.5 Cumulative File Tracking

Compaction entries track files mentioned across all summarized entries. This cumulative tracking ensures:

• The model knows which files have been discussed
• File paths are available for quick reference
• Re-summarization (when compaction entries are themselves summarized) preserves file history

12.6 Manual Compaction

12.6.1 Basic Usage

/compact

Summarizes all eligible older entries, keeping recent context intact.

12.6.2 Guided Compaction

/compact Focus on the authentication module changes

The prompt guides the summarization to prioritize specific content. This is useful when you want to ensure certain topics are preserved in detail while others are condensed.

12.6.3 Disabling Auto-Compaction

// ~/.pi/agent/settings.json
{
  "autoCompact": false
}

When disabled, the context window may fill up. Pi will warn you when approaching the limit. You can still compact manually with /compact.

Warning

Disabling auto-compaction means long conversations will eventually hit the context window limit, preventing further messages. Always use manual compaction or start new sessions when needed.

12.7 Branch Summarization

12.7.1 What It Does

When you explore multiple branches in the session tree, abandoned branches accumulate. Branch summarization automatically summarizes these abandoned branches so you can understand them at a glance in the /tree view.

12.7.2 Enabling Branch Summaries

// ~/.pi/agent/settings.json
{
  "branchSummary": true
}

12.7.3 How It Works

graph TD
    A[User navigates away from branch] --> B{Branch qualifies?}
    B -->|Yes| C[Generate summary]
    B -->|No| D[Skip]
    C --> E[Store summary with branch]
    E --> F[Show in tree view]

A branch qualifies for summarization when:

• It has more than a minimum number of messages (configurable)
• It was not the last active branch
• It has not already been summarized

12.7.4 Summary Format

Branch summaries are short (2-3 sentences) and describe:

• What was attempted in the branch
• What was achieved
• Why the branch was likely abandoned

Branch summaries appear in the /tree view as collapsed entries with a summary label.

12.8 Message Serialization

During compaction, messages are serialized in a specific order:

1. System prompt — always preserved, never summarized
2. CompactionEntry (if previous compaction occurred)
3. Context files — AGENTS.md content is preserved
4. Remaining entries — full content kept
5. Summarized entries — replaced by CompactionEntry

This serialization ensures the model always has access to project instructions and recent context.

12.9 Custom Summarization via Extensions

Extensions can intercept the compaction process to customize how summaries are generated.

12.9.1 Intercepting Compaction Events

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("compaction:before", async (event, ctx) => {
    // Modify what gets summarized
    // event.entries contains entries to be summarized
    // event.cutPoint can be adjusted
    
    // Return false to prevent default summarization
    return false;
  });

  pi.on("compaction:after", async (event, ctx) => {
    // React to compaction completion
    // event.summary contains the generated summary
    // event.compactedEntries contains original entries
    ctx.ui.notify("Context compacted!", "info");
  });
}

12.9.2 Custom Summarization Logic

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("compaction:before", async (event, ctx) => {
    // Generate custom summary
    const customSummary = generateCustomSummary(event.entries);
    
    // Return custom summary to bypass default summarization
    return {
      summary: customSummary,
      filesMentioned: extractFiles(event.entries),
    };
  });
}

Note

Custom summarization extensions can be useful for specialized workflows where the default summarization loses important domain-specific details.

12.10 Best Practices

1. Let auto-compaction handle routine cases — it is designed to preserve critical context
2. Use guided compaction when transitioning between major topics
3. Use /tree to verify context — check that important information is in the active branch
4. Start new sessions for unrelated work — compaction is not a substitute for session hygiene
5. Enable branch summary to keep the tree view manageable
6. Review compaction summaries when they appear — verify nothing critical was lost