From db78574cb87f1d60b07684f8f77df54e3509351c Mon Sep 17 00:00:00 2001 From: Xubin Ren Date: Thu, 16 Apr 2026 17:20:38 +0000 Subject: [PATCH] docs(README): update auto compact section to clarify session file behavior and mental model --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 60233f067..5cce6a336 100644 --- a/README.md +++ b/README.md @@ -1666,8 +1666,12 @@ How it works: 3. **Summary injection**: When the user returns, the summary is injected as runtime context (one-shot, not persisted) alongside the retained recent suffix. 4. **Restart-safe resume**: The summary is also mirrored into session metadata so it can still be recovered after a process restart. -> [!TIP] -> Think of auto compact as "summarize older context, keep the freshest live turns." It is not a hard session reset. +> [!NOTE] +> Mental model: "summarize older context, keep the freshest live turns, **and overwrite the session file with the compact form.**" It is not a full `session.clear()`, but it is a write — not a soft cursor move. +> +> Concretely, auto compact rewrites `sessions/.jsonl` in place: older messages (including their structured `tool_calls` / `tool_call_id` / `reasoning_content`) are replaced by just the retained recent suffix (currently 8 messages), while the archived prefix is preserved only as a plain-text summary appended to `memory/history.jsonl` (or a `[RAW] ...` flattened dump if LLM summarization fails). The original structured JSON of those turns is no longer recoverable from the session file. +> +> This differs from the **token-driven soft consolidation** that fires when a prompt exceeds the context budget: that path only advances an internal `last_consolidated` cursor and leaves the session file untouched, so the raw tool-call trail stays on disk and can still be replayed or audited. If you rely on that trail for debugging or auditing, leave `idleCompactAfterMinutes` at the default `0` and let only the token-driven path run. ### Timezone