From e6a302b935a515762b3b457773a59d0c50439f98 Mon Sep 17 00:00:00 2001 From: warren Date: Sun, 29 Mar 2026 17:03:56 +0200 Subject: [PATCH] docs(coding-agent): clarify repeated compaction boundary behavior (#2662) --- packages/coding-agent/docs/compaction.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/coding-agent/docs/compaction.md b/packages/coding-agent/docs/compaction.md index 2b34273a..7445be2c 100644 --- a/packages/coding-agent/docs/compaction.md +++ b/packages/coding-agent/docs/compaction.md @@ -39,8 +39,8 @@ You can also trigger manually with `/compact [instructions]`, where optional ins ### How It Works 1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.pi/agent/settings.json` or `/.pi/settings.json`) is reached -2. **Extract messages**: Collect messages from previous compaction (or start) up to cut point -3. **Generate summary**: Call LLM to summarize with structured format +2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point +3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present 4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId` 5. **Reload**: Session reloads, using summary + messages from `firstKeptEntryId` onwards @@ -76,6 +76,8 @@ What the LLM sees: 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. 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 session context before writing the new `CompactionEntry`, so the token count reflects the actual pre-compaction context being replaced. + ### Split Turns A "turn" starts with a user message and includes all assistant responses and tool calls until the next user message. Normally, compaction cuts at turn boundaries.