Compaction
Compaction
Auto context management in OpenClaw that summarizes older conversation turns when approaching a model's token limit, allowing sessions to continue without losing history.
Core Mechanism
When triggered, compaction:
- Condenses older conversation exchanges into summaries
- Persists those summaries to the session transcript on disk
- Preserves the most recent messages in their original form
Tool calls are kept paired with their corresponding results throughout — the tool-pair invariant is maintained.
Auto-Compaction
Enabled by default. Triggers when:
- A session approaches the model's context limit, or
- The model returns an overflow error (
request_too_large,context length exceeded,input exceeds the maximum number of tokens, etc.)
Before compaction runs, the system can perform a silent memory flush — agents write critical information to persistent storage files so it survives across the compaction boundary.
Configuration (openclaw.json)
All options live under agents.defaults.compaction:
| Option | Default | Notes |
|---|---|---|
model |
(same model) | Alternate model for summarization — provider/model-id format, e.g. "openrouter/anthropic/claude-sonnet-4-6" or a local Ollama instance |
identifierPolicy |
"strict" |
Controls identifier preservation during summarization; also "off" or "custom" (with custom instructions) |
notifyUser |
false |
When true, displays a brief status message when compaction begins |
provider |
— | Name of a custom provider registered via registerCompactionProvider() (plugin API) |
Manual Control
/compact [guidance]— force compaction immediately; optional natural-language guidance shapes what the summary emphasizes/new— start a fresh conversation, bypassing compaction entirely
Status Indicators
- Verbose mode prints:
🧹 Auto-compaction complete /statusdisplays:🧹 Compactions: <count>
Hook Points
before_compaction— observe or annotate before compaction runsafter_compaction— observe or annotate after
Compaction vs. Session Pruning
| Compaction | Session Pruning | |
|---|---|---|
| Scope | Permanent — saves condensed summary to session transcript | Per-request — silently drops tool outputs before sending to model |
| History on disk | Full original history preserved | Unaffected |
| Visibility | Optional notifyUser notification |
Silent |
| Trigger | Context limit / overflow / /compact |
Each API request, as needed |
Session pruning is a per-request optimization; compaction is a durable record-keeping event.
Related
- Session Pruning — per-request in-memory complement; frequent compaction may mean session pruning is under-used
- Session Management (OpenClaw) — session lifecycle and storage context
- Agent Loop (OpenClaw)
- Source - Compaction (OpenClaw Docs)
- Streaming
- OpenClaw
- Hermes Agent Loop — Hermes uses two compression thresholds (50% preflight / 85% gateway); compare with OpenClaw's single overflow trigger