From ead4678ee5074f74be88cfdf26ecd33d23e22434 Mon Sep 17 00:00:00 2001 From: Levi Neely Date: Sat, 25 Apr 2026 11:19:05 +0200 Subject: [PATCH] docs: correct Session and Context section in ARCHITECTURE.md Remove references to the non-existent contextBuilder and rolling window. Describe the actual compaction model: unbounded history, explicit /compact trigger, LLM-generated summary, system message preservation, user message budget (~20k tokens), tool call flattening, and pre-compaction snapshot. Co-Authored-By: Claude Sonnet 4.6 --- doc/ARCHITECTURE.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/ARCHITECTURE.md b/doc/ARCHITECTURE.md index 4f17a3e..57389f1 100644 --- a/doc/ARCHITECTURE.md +++ b/doc/ARCHITECTURE.md @@ -148,7 +148,27 @@ core := agent.NewAgentCore(agent.AgentCoreConfig{ ## Session and Context -`agent.Session` owns the message history. A `contextBuilder` enforces a rolling window to prevent unbounded prompt growth. When the window fills, older messages are either evicted (with a compaction notice injected) or proactively summarized via `/compact`. +`agent.Session` owns the message history as a flat `[]backend.Message` slice. There is +no rolling window or automatic eviction — the history grows unboundedly until compaction +is explicitly triggered. + +**Compaction** is invoked via `/compact` (from `s/sh` or the `ctl` file) or by the +agent itself. It makes a single LLM call to summarize the conversation, then replaces +the history with a compact representation: + +1. All `system` messages are preserved verbatim. +2. Recent `user` messages are preserved up to a ~20 000-token budget (newest first, + estimated at 4 chars/token). +3. The LLM-generated summary is appended as a `user` message with a handoff prefix + so the next turn can resume seamlessly. + +Tool call/result pairs are flattened to plain text before the compaction request so no +tool schemas are needed for the summarization call. Before compaction runs, a full +snapshot of the pre-compaction history is written to +`{sessionsDir}/{sessionID}.compaction.jsonl` for recovery. + +`/context` and `/usage` commands report the current message breakdown and token usage +without modifying history. ## Sandboxing