Context Window & Compaction
Every model has a context window (max tokens it can see). Long-running chats accumulate messages and tool results; once the window is tight, WednesdayAI compacts older history to stay within limits.What compaction is
Compaction summarizes older conversation into a compact summary entry and keeps recent messages intact. The summary is stored in the session history, so future requests use:- The compaction summary
- Recent messages after the compaction point
Configuration
Use theagents.defaults.compaction object in your openclaw.json to control compaction behavior.
Fields
Examples
Disable compaction entirely:Auto-compaction (default on)
When a session nears or exceeds the model’s context window, WednesdayAI triggers auto-compaction and may retry the original request using the compacted context. You’ll see:🧹 Auto-compaction completein verbose mode/statusshowing🧹 Compactions: <count>
memoryFlush.forceFlushTranscriptBytes measures serialized UTF-8 bytes, including
one newline per entry, without changing the configured threshold behavior.
Manual compaction
Use/compact (optionally with instructions) to force a compaction pass:
Compaction ownership
Sessions claimed by a compaction-stage context owner suppress core compaction: the owner’ssession_before_compact hook cancels SDK auto-compaction (including run-loop overflow recovery)
and core /compact for the claimed session, so the owner — not WednesdayAI — decides when and how
history is compacted.
For operators:
- Do not expect
🧹 Auto-compaction completeor the/compactcommand to fire on sessions owned by a compaction-stage owner. The owner is responsible for keeping that session under its window. - A claimed session can still hit its context window if the owner never compacts; monitor owned sessions through the owner’s own reporting rather than WednesdayAI’s compaction counters.
- Unclaimed (core-owned) sessions behave exactly as described in the sections above.
Context window source
Context window is model-specific. WednesdayAI uses the model definition from the configured provider catalog to determine limits.Compaction vs pruning
- Compaction: summarises and appends the summary to SQL history.
- Session pruning: trims old tool results only, in-memory, per request.
OpenAI server-side compaction
WednesdayAI also supports OpenAI Responses server-side compaction hints for compatible direct OpenAI models. This is separate from local WednesdayAI compaction and can run alongside it.- Local compaction: WednesdayAI summarizes and appends the summary to SQL session history.
- Server-side compaction: OpenAI compacts context on the provider side when
store+context_managementare enabled.
Tool output is capped before it accumulates
Tool results are capped in memory at400,000 text characters at the tool seam and again
when a session hydrates from storage. Oversized results keep a head-and-tail excerpt plus a size
note. When database write-through is enabled, the full raw bytes are stored out-of-band, so the
storage layer still holds the original output even though the model view is capped. Long sessions
do not accumulate multi-megabyte tool output in memory.
If a prune or compaction decision cannot be replayed from its stored ledger row, the session logs
prompt ledger unavailable; recomputing projections and repairs itself by recomputing the
projection from stored history. This is a one-time, self-repairing warning — not a data loss.
Tips
- Use
/compactwhen sessions feel stale or context is bloated. - Large tool outputs are already truncated (tool results are capped at 400k chars in memory); pruning can further reduce tool-result buildup in the request view.
- If you need a fresh slate,
/newor/resetstarts a new session id.
Troubleshooting
Compaction triggers but the session still hits context limits The summary may be larger than expected, or recent messages alone already exceed the window. Check yourkeepRecentTokens and reserveTokens settings. If recent messages are unavoidably large (for example, huge tool outputs), combine compaction with session pruning (contextPruning) to trim tool results before the LLM call.
Identifier (ticket ID, branch name) lost after compaction
The default identifierPolicy: "strict" adds built-in guidance, but identifiers buried deep in tool output may not survive. Switch to "custom" and provide explicit identifierInstructions naming the identifier patterns you care about (for example "Preserve all PROJ-* ticket IDs exactly"). Confirm with /compact Focus on ticket IDs and branch names.
enabled: false still seems to compact
Config is read at gateway start. Restart the gateway after changing compaction.enabled. Also verify the config is under agents.defaults.compaction, not a top-level key.
Memory flush runs unexpectedly or too often
The flush fires when serialized conversation entries in SQL reach memoryFlush.forceFlushTranscriptBytes. Set it to 0 to disable size-based triggers, or increase the value. Set memoryFlush.enabled: false to turn off pre-compaction memory flushes entirely.
Related: Session pruning · Memory · Session management · OpenAI provider