OpenClaw Compaction: Keep Long Sessions Useful Without Losing Context

Long-running AI agent sessions do not fail all at once. They usually get weird first. The agent starts carrying too much history, old tool output keeps showing up in the prompt, the model gets close to its context window, and suddenly a conversation that felt useful starts acting heavy.

OpenClaw compaction is the safety valve for that moment. It lets a session continue by summarizing older conversation into a smaller persisted entry while keeping the recent working tail intact. The goal is not to erase history. The goal is to stop the model from re-reading the entire past every time it needs to answer the next message.

This is different from session pruning, and the distinction matters. Pruning trims old tool results in memory for a request. Compaction summarizes conversation history and saves that summary into the session transcript. If you run agents as real operators, you need both ideas in your head.

The problem: context windows are real

Every model has a context window: the maximum amount of tokens it can see at once. A serious OpenClaw session can grow quickly because it includes messages, tool calls, tool results, system context, memory, and recent operational instructions.

That is fine for short chats. It is not fine for a channel that stays alive for weeks, a coding thread with repeated file reads, or a production ops session where the agent keeps handling follow-ups. Eventually, the model either approaches the configured context limit or a provider returns a context-overflow error.

The documented OpenClaw behavior is straightforward: when the session gets tight, OpenClaw compacts older history so the conversation can continue under the model limit. The full transcript remains on disk, but the rebuilt model context uses the compaction summary plus the recent messages after the compaction point.

What compaction actually saves

Compaction creates a persisted summary entry in the session transcript. OpenClaw sessions are stored as JSONL transcripts, and the deep-dive docs describe a compaction entry that includes the summary plus metadata such as the first kept entry and token count before compaction.

In plain English: the older branch of the conversation gets condensed into a checkpoint, and the most recent unsummarized tail stays available for the next run.

Before compaction:
old messages + old tool work + decisions + recent messages

After compaction:
compaction summary + recent messages after the compaction point

That is why compaction is more durable than a local prompt trick. The summary persists in session history, so future turns can rebuild context from it. The docs are explicit that this is not the same as pruning, which is per-request and in-memory only.

When auto-compaction happens

OpenClaw auto-compaction is on by default. The docs describe two main trigger paths in the embedded Pi runtime.

• Overflow recovery: the model or provider reports that the input is too large, so OpenClaw compacts and retries the original request.
• Threshold maintenance: after a successful turn, the runtime sees that contextTokens is greater than contextWindow - reserveTokens.

contextWindow is the model limit from the provider catalog or config override. reserveTokens is headroom reserved for prompts and the next model output. That headroom is important. You do not want an agent using every last token just to remember yesterday's logs and then having no room left to answer.

You can see compaction activity through normal OpenClaw surfaces. Verbose mode can show 🧹 Auto-compaction complete, and /status reports the compaction count for the session.

Manual compaction is for operator judgment

Auto-compaction handles the emergency. Manual compaction is for judgment.

If a thread has wandered through several unrelated tasks, or the agent keeps anchoring on an old decision that no longer matters, you can force a compaction pass with /compact. The docs also support adding instructions:

/compact Focus on current deployment state, open blockers, and user-approved decisions

I like using manual compaction before a long thread enters a new phase. For example, after a debugging session has ended and the next phase is deployment, the useful summary is not every failed attempt. It is the final cause, the fix, the remaining risk, and the next command that should run.

The practical rule: use /compact when the conversation has value, but the raw path it took is no longer the best thing for the model to carry.

If you are building an agent that works for hours instead of minutes, compaction is not optional ops trivia. Get ClawKit and set up the full long-session operating playbook.

The memory flush is the part operators should care about

Compaction is summarization, and summarization always creates a risk: something important can be compressed too aggressively. OpenClaw handles that with a pre-compaction memory flush.

The memory docs say OpenClaw memory is plain Markdown in the agent workspace. Durable facts belong in files like MEMORY.md and memory/YYYY-MM-DD.md. Before compaction, OpenClaw can run a silent turn that reminds the agent to save important notes to disk. The default memory flush is enabled.

That design is exactly right. A compaction summary is useful working context. A memory file is durable state. If the user made a decision, changed a preference, approved a deployment rule, or gave the agent a new responsibility, that should survive as a file-backed note, not just as a sentence inside a model-generated summary.

The documented config lives under agents.defaults.compaction.memoryFlush:

{
  agents: {
    defaults: {
      compaction: {
        reserveTokensFloor: 20000,
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

The deep-dive docs also call out boundaries: the flush runs once per compaction cycle, uses NO_REPLY convention so the user does not see housekeeping, and is skipped when the session workspace is read-only or unavailable. That is a good operational tradeoff. Silent housekeeping should be quiet, but it should not pretend it wrote durable state when it could not.

Compaction versus pruning

The shortest version is this:

• Compaction summarizes older conversation and persists the summary into the JSONL transcript.
• Session pruning trims old toolResult messages from the in-memory context before an LLM call.

Pruning does not rewrite on-disk history. It only changes what is sent to the model for that request. It is especially useful for old shell output, large file reads, and stale tool results that would otherwise bloat context after a cache TTL expires.

Compaction is broader and more semantic. It is the thing you need when the conversation itself has grown too large. Pruning keeps tool noise lean. Compaction keeps the session alive.

If your agent feels slow or expensive after idle periods, look at pruning. If the whole thread is nearing model limits or repeatedly hitting overflow, look at compaction. If both are happening, tune both instead of expecting one feature to solve every context problem.

The config knobs I would touch first

The compaction docs point to agents.defaults.compaction for behavior. I would avoid over-tuning until you have evidence, but there are a few settings worth knowing.

Use a stronger summarization model when needed

By default, compaction uses the agent's primary model. The docs allow a dedicated model override through agents.defaults.compaction.model. That is useful when your primary model is local, small, or optimized for cheap turns, but you want summaries produced by a stronger model.

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

The docs also show local model examples such as an Ollama model. The operational point is not that every setup needs a fancy compaction model. The point is that the summary quality matters because it becomes the durable bridge between old and new context.

Preserve opaque identifiers

Compaction preserves opaque identifiers by default with identifierPolicy: "strict". That matters for ticket ids, session ids, commit hashes, message ids, channel ids, and other strings where “close enough” is not acceptable.

You can turn that policy off or provide custom identifier instructions, but I would be careful. In agent ops, losing or mutating an id can be worse than losing a paragraph of explanation.

Understand reserve-token headroom

The deep-dive docs describe Pi compaction settings like reserveTokens and keepRecentTokens. OpenClaw also enforces a safety floor through agents.defaults.compaction.reserveTokensFloor, with a documented default floor of 20000 tokens for embedded runs.

Do not treat that as random overhead. The floor exists because the agent may need room for housekeeping and the next answer before compaction becomes unavoidable.

What not to do

• Do not use compaction as a substitute for memory. Durable facts should be written to memory files.
• Do not assume the session store counters are hard guarantees. The docs describe token counters as best-effort and provider-dependent.
• Do not debug remote sessions by only checking local files. The Gateway owns session state, and remote mode means the files live on the remote host.
• Do not compact away an active investigation too early. If the model still needs detailed tool output, let the current phase finish first.

The operator takeaway

Compaction is not a magic memory system. It is a practical context-management layer. It keeps long sessions usable by turning old conversation into a persisted summary, keeping recent turns intact, and giving the agent a chance to flush important notes into memory before the cleanup happens.

The best OpenClaw setups treat context like an operating budget. Memory files hold durable truth. Session pruning trims stale tool output. Compaction condenses old conversation when the window gets tight. Manual /compact gives the operator a way to reset the working shape of a thread without throwing it away.

That combination is what lets an agent stay useful past the first impressive demo and into actual daily work.

Want the complete guide? Get ClawKit — $9.99