diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index babec691c..9ad42270d 100644 --- a/.openclaw-sync/source.json +++ b/.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" } diff --git a/docs/.generated/config-baseline.sha256 b/docs/.generated/config-baseline.sha256 index 237f6856e..15ec791ff 100644 --- a/docs/.generated/config-baseline.sha256 +++ b/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 diff --git a/docs/concepts/compaction.md b/docs/concepts/compaction.md index 95e0b8517..d7ebc4504 100644 --- a/docs/concepts/compaction.md +++ b/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 diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md index 13fec116f..4c36bf8e8 100644 --- a/docs/gateway/config-agents.md +++ b/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. diff --git a/docs/reference/session-management-compaction.md b/docs/reference/session-management-compaction.md index aced66973..a1e2ab7cd 100644 --- a/docs/reference/session-management-compaction.md +++ b/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