Merge pull request #700 from clawdbot/shadow/compaction

Agents: safeguard compaction summarization

docs/compaction.md

@@ -0,0 +1,40 @@
+---
+summary: "Compaction modes and configuration"
+read_when:
+  - You want to configure compaction summarization behavior
+  - You are tuning compaction settings in clawdbot.json
+---
+# Compaction
+
+Compaction summarizes older session history so the conversation stays within the model context window. The summary is stored in the session JSONL history and combined with the most recent messages.
+
+## Modes
+
+`agents.defaults.compaction.mode` controls how summaries are generated.
+
+- `default` (default): use the built-in compaction summarizer.
+- `safeguard`: uses a chunked summarization pass to avoid context overflow for very long histories. If chunked summarization fails, Clawdbot falls back to a minimal summary plus file-operation metadata.
+
+## Configuration
+
+```json5
+{
+  agents: {
+    defaults: {
+      compaction: {
+        mode: "safeguard",
+        reserveTokensFloor: 20000,
+        memoryFlush: {
+          enabled: true,
+          softThresholdTokens: 4000
+        }
+      }
+    }
+  }
+}
+```
+
+## Related docs
+
+- [Context window + compaction behavior](/concepts/compaction)
+- [Gateway configuration reference](/gateway/configuration)

docs/concepts/compaction.md

@@ -15,6 +15,9 @@ Compaction **summarizes older conversation** into a compact summary entry and ke
 
 Compaction **persists** in the session’s JSONL history.
 
+## Configuration
+See [Compaction config & modes](/compaction) for the `agents.defaults.compaction` settings.
+
 ## Auto-compaction (default on)
 When a session nears or exceeds the model’s context window, Clawdbot triggers auto-compaction and may retry the original request using the compacted context.
 

docs/gateway/configuration.md

@@ -1392,6 +1392,8 @@ See [/concepts/session-pruning](/concepts/session-pruning) for behavior details.
 
 #### `agents.defaults.compaction` (reserve headroom + memory flush)
 
+`agents.defaults.compaction.mode` selects the compaction summarization strategy. Defaults to `default`; set `safeguard` to enable chunked summarization for very long histories. See [/compaction](/compaction).
+
 `agents.defaults.compaction.reserveTokensFloor` enforces a minimum `reserveTokens`
 value for Pi compaction (default: `20000`). Set it to `0` to disable the floor.
 
@@ -1413,6 +1415,7 @@ Example (tuned):
   agents: {
     defaults: {
       compaction: {
+        mode: "safeguard",
         reserveTokensFloor: 24000,
         memoryFlush: {
           enabled: true,