OpenClaw Compaction Explained

Compaction is OpenClaw's answer to a simple reality: models have context windows, and long sessions eventually run out of room. The docs describe compaction as summarizing older messages into a compact entry so the chat can continue while recent messages stay intact. That sounds mundane, but it is one of the core reasons a serious operator can keep a session alive for longer than a toy chat window would normally allow.

What compaction changes and what it does not

The key boundary is this: compaction changes what the model sees on the next turn, not what is saved on disk. OpenClaw summarizes older conversation turns into a compact entry, stores that summary in the transcript, and keeps the recent tail unsummarized. The docs also call out an implementation detail that matters for reliability. Assistant tool calls stay paired with their matching toolResult entries. If a split point lands in the middle of a tool block, OpenClaw moves the boundary instead of breaking the pair.

How auto-compaction behaves

Auto-compaction is enabled by default. It runs when the session nears the context limit, and it can also kick in when a model returns a context-overflow error. The docs even list common overflow signatures, including request_too_large, context length exceeded, input exceeds the maximum number of tokens, and the familiar ollama error: context length exceeded. When OpenClaw hits one of those situations, it can compact and retry instead of just dying in place.

Another useful safeguard appears before compaction happens. OpenClaw can remind the agent to save important notes to memory files so durable information is not lost in the summary step. The docs mention a silent memory flush turn as an optional part of the flow. That is a nice example of the platform thinking like an operator. Summaries are helpful, but important identifiers, decisions, and follow-ups still belong in durable files, not only inside a compressed transcript.

The knobs operators can tune

Compaction behavior lives under agents.defaults.compaction in openclaw.json. The docs call out options like mode, target tokens, notifyUser, identifierPolicy, and even a separate model override for summarization. If your main model is small, local, or cheap, you can point compaction at a different provider or model id. The examples show both a hosted option like openrouter/anthropic/claude-sonnet-4-6 and a local option like ollama/llama3.1:8b.

{
  "agents": {
    "defaults": {
      "compaction": {
        "notifyUser": true,
        "model": "openrouter/anthropic/claude-sonnet-4-6"
      }
    }
  }
}

Compaction is not pruning

The docs draw a clean line between compaction and pruning. Compaction summarizes older conversation and saves the result in the transcript. Pruning trims old tool results from the in-memory request and does not rewrite history. If a session feels bloated because command output is huge, pruning may be enough. If the actual conversation has become too long, compaction is the right tool. That distinction helps a lot when you are debugging stale context or repeated overflows.

My read is that compaction is one of the most quietly important features in OpenClaw. It is not flashy, but it is the thing that lets serious sessions survive real work. Use /compact intentionally, keep memory files current, and think of compaction as a pressure valve, not a magic memory system. The docs set that expectation clearly, and that clarity is what keeps long-running agent work stable instead of mysterious.

There is also a user-experience angle here. When notifyUser is enabled, compaction can be visible instead of feeling like the agent randomly forgot something. That matters because trust drops fast when a long session feels inconsistent. The docs are effectively telling operators to pair compaction with clear expectations, durable memory habits, and the right model choice so summary quality stays high.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.