OpenClaw Compaction: Keep Long Sessions Useful Without Losing Context

Long OpenClaw sessions do not fail all at once. They usually decay quietly. The agent gets slower, tool output piles up, old decisions compete with new ones, and eventually the model is trying to reason inside a context window that was never meant to hold an entire operating history.

That is what compaction is for. OpenClaw compaction summarizes older conversation into a smaller entry, keeps the recent working tail intact, and persists that summary into the session transcript so the session can continue instead of hitting a hard wall.

The important part is the boundary. Compaction is not memory. It is not session pruning. It is not a magic guarantee that every detail survives forever. It is a pressure-release valve for long sessions. Used well, it keeps an agent useful. Used casually, it can hide the fact that durable facts should have been written to files in the first place.

What compaction actually does

The OpenClaw docs define compaction very plainly: older conversation is summarized into a compact summary entry, recent messages after the compaction point stay intact, and the summary is stored in the session history.

That means future requests are rebuilt from two pieces:

• the compaction summary, which carries the older session context forward in compressed form
• recent messages after the compaction point, which preserve the active working area

The summary persists in the session's JSONL history. That persistence is the thing that separates compaction from lighter cleanup. The agent is not just trimming a prompt for one call. It is creating a new durable checkpoint that future turns will see.

If you are already tuning session pruning, keep that distinction sharp. Pruning trims old tool results in memory for a request. Compaction summarizes older conversation and saves the summary into the transcript.

Why this matters in real operator sessions

An OpenClaw session can carry a lot of operational weight: Slack decisions, code review context, deploy notes, browser findings, customer issues, cron follow-ups, and tool outputs. That is exactly why long-lived sessions are useful. It is also why they get heavy.

Every model has a context window. OpenClaw resolves the context window from the configured model definition or provider catalog. Once the session nears the limit, the runtime needs a way to continue without sending everything forever.

Auto-compaction is on by default. The docs say OpenClaw may compact when the session nears or exceeds the model context window, and it can also compact after a context-overflow error and retry the original request with the compacted context.

In verbose mode, you may see 🧹 Auto-compaction complete. In chat, /status can show the compaction count for the session. The deep-dive docs also note that the session store tracks fields like contextTokens and compactionCount, but those counters are best treated as runtime reporting, not as a perfect contract.

Manual compaction is a steering tool

You do not have to wait for the automatic threshold. OpenClaw supports the /compact command, optionally with instructions:

/compact Focus on decisions, blockers, and open questions

That instruction matters. A generic compaction summary can keep the session alive, but an instructed compaction can preserve the shape you actually care about. If the session is about a deploy, ask it to preserve decisions, URLs, blockers, rollback notes, and pending approvals. If the session is about product strategy, ask it to preserve assumptions, rejected options, and next decisions.

I like manual compaction before a long second phase of work. If a thread has already spent an hour investigating, compacting with a targeted instruction before implementation gives the agent a cleaner runway without throwing away the investigation.

Compaction is not the same as memory

This is where operators get themselves into trouble. Compaction keeps a conversation moving. Memory keeps durable facts available across sessions. Those are not the same promise.

OpenClaw memory lives in plain Markdown files in the agent workspace. The memory docs call out MEMORY.md for long-term facts and memory/YYYY-MM-DD.md for daily notes. The model only “remembers” what is written to disk and later loaded or retrieved.

Compaction, by contrast, creates a summary inside the session transcript. It is useful for continuity, but it should not be your only storage layer for important business rules, preferences, credentials policy, launch decisions, or promises to a user.

My rule is simple: if the fact should survive a reset, a new thread, or a future agent run, write it to memory or the project files. Do not hope a compaction summary keeps it perfectly forever.

The pre-compaction memory flush exists for a reason

OpenClaw has a nice safety feature here. Before compaction, it can run a silent memory flush turn that reminds the agent to write durable notes to disk. The docs say this is controlled under agents.defaults.compaction.memoryFlush and is enabled by default in the normal flow.

A simplified shape looks like this:

{
  agents: {
    defaults: {
      compaction: {
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 4000,
          prompt: "Write durable notes before compaction; reply NO_REPLY if nothing matters."
        }
      }
    }
  }
}

The flush is meant to be silent. The docs describe the NO_REPLY convention so background housekeeping does not leak user-visible chatter. If there is nothing durable to store, the agent can stay quiet.

This is one of the most operator-minded parts of the design. OpenClaw does not pretend summarization is enough. It gives the agent a chance to persist the important bits before summarization changes the working context.

How compaction differs from session pruning

Compaction and pruning are easy to mix up because both reduce context pressure. The docs draw a hard line:

• Compaction: summarizes older conversation and persists the summary in JSONL history.
• Session pruning: trims old toolResult messages only, in memory, before a request.

Session pruning is especially useful for accumulated shell output, file reads, and search dumps. It reduces prompt-cache waste without changing the actual transcript. Compaction is heavier. It changes the durable session shape by inserting a summary checkpoint.

The best setups use both. Pruning handles stale tool-result bulk between turns. Compaction handles the bigger problem of a session that has simply grown too long.

The config knobs I would actually touch

Most teams should not start by over-tuning compaction. The documented defaults exist for a reason. But there are a few knobs worth knowing.

Use a dedicated compaction model when needed

By default, compaction uses the agent's primary model. The docs allow an override at agents.defaults.compaction.model when you want summarization handled by a different model:

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

That is useful if your main session uses a smaller or local model, but you want a stronger summarizer for compaction. The docs also show local model examples such as an Ollama model dedicated to summarization. When unset, OpenClaw uses the primary model.

Preserve identifiers deliberately

The compaction docs say identifier preservation defaults to identifierPolicy: "strict". That matters because agents often operate on IDs, filenames, issue numbers, channel IDs, session keys, URLs, and commit hashes. Losing or mutating those during summarization is not harmless.

You can turn identifier preservation off or provide custom instructions, but I would be conservative. For operator work, strict preservation is usually the right baseline.

Respect the reserve-token floor

The session deep dive documents Pi compaction settings such as reserveTokens and keepRecentTokens, and also notes that OpenClaw enforces a default reserveTokensFloor of 20000 tokens for embedded runs unless you set it to 0.

The reason is practical: leave enough headroom for prompts, tool use, and housekeeping before the session gets trapped at the edge of overflow. If you lower that floor, know why you are doing it.

How I debug a stale long session

If an OpenClaw session feels confused after a lot of work, I would not immediately switch models. I would check the operating state first:

1. Run /status. Look at session state and whether compactions have already happened.
2. Ask what must be durable. If the answer belongs in memory or a project file, write it there instead of relying on summary context.
3. Use instructed /compact. Tell the agent exactly what to preserve before the next phase.
4. Enable or tune pruning if tool output is the bloat. If old logs are the problem, compaction is not the only lever.
5. Start fresh when the job has changed. The compaction docs still point to /new or /reset when you need a clean slate.

The source-of-truth detail matters too. The deep-dive docs say the Gateway owns session state. In remote mode, checking local session files on the wrong machine can mislead you. Query the Gateway-facing state instead of debugging a copy that the active runtime is not using.

The operator takeaway

Compaction is not glamorous, but it is one of the reasons a serious AI agent can keep working past the first neat demo. Long sessions need a way to compress history without losing the active thread. OpenClaw's answer is a persisted summary, recent-message preservation, visible status, manual steering through /compact, and a pre-compaction memory flush for durable notes.

The habit I recommend is simple: let auto-compaction protect you from overflow, use manual compaction before long phase changes, keep pruning for tool-result bloat, and write important facts to files before they become summary mush.

That is how long sessions stay useful instead of becoming haunted.

Want the complete guide? Get ClawKit — $9.99