chore(sync): mirror docs from openclaw/openclaw@29af4add2a

.openclaw-sync/source.json

@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "ef31a333f79696781d17ddf08479204c663e0984",
-  "syncedAt": "2026-04-27T02:41:27.941Z"
+  "sha": "29af4add2a8e612921e87aeb6426373e162c9d4a",
+  "syncedAt": "2026-04-27T02:48:15.316Z"
 }

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-29181dbaa26242ced515ba4c2b363853a24b5b2623b33ecfede252c2a984b7c6  config-baseline.json
-2edac1da06bbb3709375bf82ae68890c67634f5ad3200a98a1d008b22c335e79  config-baseline.core.json
+0c3eaaee031f0adec2fcfc8a3a6a0d80dfc19d4d1c10b0ff4249b30e04b3c47d  config-baseline.json
+420269ce22f17382cb253c80a232329e943296be101cda313506341ae39cc674  config-baseline.core.json
 07963db49502132f26db396c56b36e018b110e6c55a68b3cb012d3ec96f43901  config-baseline.channel.json
 74b74cb18ac37c0acaa765f398f1f9edbcee4c43567f02d45c89598a1e13afb4  config-baseline.plugin.json

docs/concepts/compaction.md

@@ -124,6 +124,16 @@ active successor transcript from the compaction summary, preserved state, and
 unsummarized tail, then keeps the previous JSONL as the archived checkpoint
 source.
 
+When `agents.defaults.compaction.maxActiveTranscriptBytes` is set, OpenClaw can
+trigger normal local compaction before a run if the active JSONL reaches that
+size. This is useful for long-running sessions where provider-side context
+management may keep model context healthy while the local transcript keeps
+growing. It does not split raw JSONL bytes; it only asks the normal compaction
+pipeline to create a semantic summary. Combine it with
+`truncateAfterCompaction: true` to move future turns onto the smaller successor
+transcript; without transcript rotation, the byte guard remains inactive because
+the active file would not shrink.
+
 ## Using a different model
 
 By default, compaction uses your agent's primary model. You can use a more

docs/gateway/config-agents.md

@@ -554,6 +554,8 @@ Periodic heartbeat runs.
         qualityGuard: { enabled: true, maxRetries: 1 },
         postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
         model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
+        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
+        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
         notifyUser: true, // send brief notices when compaction starts and completes (default: false)
         memoryFlush: {
           enabled: true,
@@ -576,6 +578,7 @@ Periodic heartbeat runs.
 - `qualityGuard`: retry-on-malformed-output checks for safeguard summaries. Enabled by default in safeguard mode; set `enabled: false` to skip the audit.
 - `postCompactionSections`: optional AGENTS.md H2/H3 section names to re-inject after compaction. Defaults to `["Session Startup", "Red Lines"]`; set `[]` to disable reinjection. When unset or explicitly set to that default pair, older `Every Session`/`Safety` headings are also accepted as a legacy fallback.
 - `model`: optional `provider/model-id` override for compaction summarization only. Use this when the main session should keep one model but compaction summaries should run on another; when unset, compaction uses the session's primary model.
+- `maxActiveTranscriptBytes`: optional byte threshold (`number` or strings like `"20mb"`) that triggers normal local compaction before a run when the active JSONL grows past the threshold. Requires `truncateAfterCompaction` so successful compaction can rotate to a smaller successor transcript. Disabled when unset or `0`.
 - `notifyUser`: when `true`, sends brief notices to the user when compaction starts and when it completes (for example, "Compacting context..." and "Compaction complete"). Disabled by default to keep compaction silent.
 - `memoryFlush`: silent agentic turn before auto-compaction to store durable memories. Skipped when workspace is read-only.
 

docs/reference/session-management-compaction.md

@@ -259,6 +259,13 @@ Where:
 
 These are Pi runtime semantics (OpenClaw consumes the events, but Pi decides when to compact).
 
+OpenClaw can also trigger a preflight local compaction before opening the next
+run when `agents.defaults.compaction.maxActiveTranscriptBytes` is set and the
+active transcript file reaches that size. This is a file-size guard for local
+reopen cost, not raw archival: OpenClaw still runs normal semantic compaction,
+and it requires `truncateAfterCompaction` so the compacted summary can become a
+new successor transcript.
+
 ---
 
 ## Compaction settings (`reserveTokens`, `keepRecentTokens`)
@@ -285,6 +292,11 @@ OpenClaw also enforces a safety floor for embedded runs:
   and keeps Pi's recent-tail cut point. Without an explicit keep budget,
   manual compaction remains a hard checkpoint and rebuilt context starts from
   the new summary.
+- Set `agents.defaults.compaction.maxActiveTranscriptBytes` to a byte value or
+  string such as `"20mb"` to run local compaction before a turn when the active
+  transcript gets large. This guard is active only when
+  `truncateAfterCompaction` is also enabled. Leave it unset or set `0` to
+  disable.
 - When `agents.defaults.compaction.truncateAfterCompaction` is enabled,
   OpenClaw rotates the active transcript to a compacted successor JSONL after
   compaction. The old full transcript remains archived and linked from the