Every AI model has a hard ceiling on how much text it can read at once. Hit that ceiling in the middle of a long agent session and the conversation dies with a context-overflow error. Context compaction is the fix: instead of failing, the agent summarizes its older messages, keeps the recent ones, and carries on. OpenClaw does this automatically, and more usefully, it lets you control how it happens.
That control is the part most write-ups skip. Plenty of guides explain that Claude Code or some other tool “auto-compacts” at 95% of the window, then stop there, as if it were a black box. If you self-host your agent, it isn’t a black box. You pick the summarizer model. You decide how much recent history survives. You choose whether the agent saves notes to disk before it forgets. This post walks through what compaction really does, where it costs you, and the knobs worth touching.
Why context windows fill up (and why a bigger one isn’t the fix)
A context window is the maximum number of tokens a model can process in a single turn. Long chats, big tool outputs, and files you paste in all eat into it. Eventually you run out of room and the provider returns an error like context length exceeded or input is too long for the model.
The obvious reaction is “just use a model with a bigger window.” It helps less than you’d think. Research keeps finding that models get worse at using information as the window grows, a problem Anthropic and others now call context rot. In Anthropic’s words, “as the number of tokens in the context window increases, the model’s ability to accurately recall information from that context decreases,” and this “emerges across all models” (Anthropic, Effective context engineering for AI agents).
It gets more specific. The well-known “lost in the middle” finding showed accuracy is highest when the relevant fact sits at the very start or very end of the input, and drops by more than 30% when it’s buried in the middle, a U-shaped curve that held across six different model families (Redis, Context rot explained; Chroma research). So a stuffed 200K window isn’t a win. A model wading through 180K tokens of history to answer one question is slower, more expensive, and often less accurate than the same model working from a tight summary. Compaction exists because smaller, cleaner context usually beats bigger context.
What context compaction actually does
Here is the mechanic, straight from how OpenClaw handles it. When a session nears the limit, three things happen:
- Older conversation turns get summarized into one compact entry.
- That summary is saved into the session transcript.
- Recent messages are kept intact, word for word.
The model’s next turn sees the summary plus the recent tail, not the full backlog. One detail matters more than it sounds: OpenClaw keeps every assistant tool call paired with its matching tool result. If the natural cut point would land in the middle of a tool call, it moves the boundary so the pair stays together. A summary that severed a function call from its output would confuse the model, so the split respects those blocks.
The reassuring part: your full conversation history stays on disk. Compaction only changes what the model reads on the next turn. Nothing is deleted from the transcript. If you need the raw exchange later, it’s still there.
This lines up with how Anthropic describes the same technique: “passing the message history to the model to summarize and compress the most critical details.” The trade is deliberate. You give up fine detail in the old turns to buy runway for the conversation to keep going.
Auto-compaction vs manual /compact
OpenClaw runs compaction two ways.
Automatic. On by default. It fires when the session approaches the context limit, or when the model returns a context-overflow error, in which case OpenClaw compacts and retries the request instead of just failing. You’ll see embedded run auto-compaction start and complete in the Gateway logs, a 🧹 Auto-compaction complete line in verbose mode, and a running count under /status. OpenClaw recognizes dozens of provider-specific overflow strings across Anthropic, OpenAI, Bedrock, Gemini, Ollama, and others, so overflow recovery works no matter which model you’re on.
Manual. Type /compact in any chat to force it. You can steer the summary by adding an instruction:
/compact Focus on the API design decisionsThat’s genuinely useful. If you know the next hour of work is about one subsystem, telling the summarizer what to prioritize keeps the important thread sharp instead of averaged out. Manual compaction uses the keepRecentTokens budget (default 20,000) as its cut point and preserves that recent tail.
The knobs you actually control
This is where self-hosting pays off. Compaction lives under agents.defaults.compaction in your openclaw.json. A few settings are worth knowing.
Use a different (or cheaper) model to summarize
By default, compaction uses your agent’s primary model. You can hand the job to another one:
{
"agents": {
"defaults": {
"compaction": {
"model": "openrouter/anthropic/claude-sonnet-4-6"
}
}
}
}Two reasons to do this. One, summarizing is a narrower task than reasoning, so a smaller or cheaper model often handles it fine and cuts cost. Two, it works with local models, so you can dedicate a second Ollama model purely to summarization and keep that work off your paid API entirely:
{
"agents": {
"defaults": {
"compaction": {
"model": "ollama/llama3.1:8b"
}
}
}
}Safeguard mode
New configs default agents.defaults.compaction.mode to "safeguard", which adds stricter guardrails and audits the quality of the summary. If you want the older, looser behavior, set mode: "default" to opt out. For most people the safeguard default is the right call, since a bad summary is worse than a slow one.
Keep more recent history
keepRecentTokens (default 20,000) controls how much of the recent tail survives verbatim. Raise it if your agent keeps losing the thread right after a compaction; lower it if you want a more aggressive squeeze.
The transcript byte guard
Long-running sessions can keep a healthy model context while the saved transcript on disk grows and grows. Set maxActiveTranscriptBytes to a size like "20mb" and OpenClaw will trigger a normal semantic compaction once history reaches that size. It doesn’t chop raw bytes; it asks the regular pipeline for a proper summary.
Tell the user when it happens
Compaction runs silently by default. Set notifyUser: true to get brief “compaction started / complete” messages, which is handy while you’re tuning things and want to see when the squeeze kicks in.
Compaction vs pruning: two different levers
OpenClaw ships a second, lighter mechanism called pruning, and people constantly confuse the two. They solve related problems in different ways.
| Compaction | Pruning | |
|---|---|---|
| What it does | Summarizes older conversation | Trims old tool results |
| Saved? | Yes, into the session transcript | No, in-memory only, per request |
| Scope | The entire conversation | Tool results only |
Anthropic makes the same point about tool results, calling their removal “one of the safest lightest touch forms of compaction,” on the logic that once a tool ran deep in the history, the agent rarely needs to see the raw output again. If your sessions balloon because of huge tool outputs rather than long back-and-forth, reach for pruning first. It’s cheaper than a full summarization pass and it doesn’t touch the actual conversation.
Compaction is lossy, so flush to memory first
Here’s the mistake worth avoiding: treating the summary as lossless. It isn’t. A summary is a compression, and compression drops detail. A decision you made 40 turns ago might not survive the squeeze in the exact form you need.
OpenClaw’s answer is a memory flush. Before it compacts, it reminds the agent to save important notes to its memory files. Those notes live on disk as durable Markdown, separate from the conversation, so they outlast any number of compactions. You can even point the flush at a local model so the housekeeping turn costs nothing:
{
"agents": {
"defaults": {
"compaction": {
"memoryFlush": {
"model": "ollama/qwen3:8b"
}
}
}
}
}The rule of thumb: context is disposable, memory is durable. Anything the agent must not forget belongs in a memory file, not in a hope that the summarizer keeps it. Auto-compaction on plus memory flush on is the pairing I’d default to.
Troubleshooting compaction
Compacting too often? Either the model’s window is small or your tool outputs are big. Turn on pruning to trim tool results before they force a full summarization.
Context feels stale afterward? Guide the next summary with /compact Focus on <topic>, or enable the memory flush so key notes survive on disk instead of in the summary.
Want a genuinely clean slate? Don’t compact at all. Run /new to start a fresh session. Compaction is for continuing the same task with less baggage; /new is for when the task itself changed.
Frequently asked questions
Does compaction delete my conversation history?
No. The full history stays on disk in the session transcript. Compaction only changes what the model sees on the next turn, not what’s stored.
Can I turn auto-compaction off?
Yes. Set agents.defaults.compaction.enabled: false to disable the proactive threshold trigger. Overflow-recovery compaction and manual /compact still work, so you keep a safety net.
What’s the difference between /compact and /clear or /new?
/compact summarizes and keeps going on the same task. /new starts a fresh session with no summary. Use compaction to continue, and a new session when you’re switching to unrelated work.
Will compaction slow down my agent?
The summarization pass itself takes a moment, but the turns after it are faster and cheaper because the model reads far fewer tokens. Delegating the summary to a smaller or local model keeps that one-time cost down.
Does a bigger context window remove the need for compaction?
Not really. Because of context rot, a model working from a huge stuffed window is often slower and less accurate than one working from a tight summary. Compaction is about quality of context, not just fitting under the limit.
The takeaway
Context compaction is what keeps a long agent session from hitting a wall, but it’s a lossy trade, not free infinite memory. The teams who get the most out of it treat the summary as disposable and push anything important into memory files, tune the summarizer model to control cost, and reach for pruning or a fresh session when that’s the better tool. On a self-hosted setup you get all of those levers instead of a black box, which is the whole point.
Running OpenClaw and want your agent to hold long conversations without falling over or burning tokens? Open your openclaw.json, confirm auto-compaction and the memory flush are on, and point the summarizer at a cheap local model. That three-line change is the difference between an agent that forgets and one that keeps its head. For the full reference, see the OpenClaw compaction docs.
