Session Pruning: Reducing Context Bloat by Trimming Old Tool Results

Session pruning removes older tool results from the context before each LLM request. This cuts down on context bloat caused by repeated tool outputs (execution results, file reads, search results) while leaving normal chat text untouched.

Info

Pruning only happens in memory. It never changes the session transcript stored on disk. Your full history remains intact.

Why it matters

Long-running sessions accumulate tool output that fills up the context window. This drives up costs and may trigger compaction earlier than needed.

Pruning is especially useful for Anthropic prompt caching. Once the cache TTL runs out, the next request re-caches the entire prompt. By pruning, you shrink the cache-write size and directly cut costs.

How it works

Pruning operates in cache-ttl mode and depends on both a time condition and a context-size condition:

Wait until the cache TTL expires (default 5 minutes when set manually; see Smart defaults for the Anthropic auto-default). Before that TTL, pruning is completely skipped so nearby turns can reuse the prompt cache.
After the TTL expires, estimate the total context size relative to the model's context window. If the ratio is below softTrimRatio (default 0.3), skip pruning and let the TTL clock keep running.
Soft-trim tool results that exceed the ratio: keep the beginning and end (default 1500 characters each, up to 4000 total), and insert ... between them.
If the ratio is still at or above hardClearRatio (default 0.5) and at least minPrunableToolChars (default 50,000) of prunable tool content remains, hard-clear those results by replacing their content with a placeholder (default [Old tool result content cleared]).
Reset the TTL clock only when pruning actually changed the context, so follow-up requests benefit from a fresh cache.

Two safety rules apply regardless of thresholds: the most recent keepLastAssistants assistant turns (default 3) are never pruned, and nothing before the session's first user message is ever pruned (protects bootstrap reads like SOUL.md/USER.md).

Only toolResult messages are eligible; normal conversation text is left alone. Use agents.defaults.contextPruning.tools.{allow,deny} to control which tool names are prunable.

Legacy image cleanup

OpenClaw also creates a separate idempotent replay view for sessions that store raw image blocks or prompt-hydration media markers in history.

It keeps the 3 most recent completed turns byte-for-byte so prompt cache prefixes for recent follow-ups remain stable. This count includes all completed turns, not just those with images, so text-only turns also consume the window.
In the replay view, older already-processed image blocks from user or toolResult history are replaced with [image data removed - already processed by model].
Older textual media references such as [media attached: ...], [Image: source: ...], and media://inbound/... are replaced with [media reference removed - already processed by model]. Current-turn attachment markers stay intact so vision models can still hydrate fresh images.
The raw session transcript is not rewritten, so history viewers can still render the original message entries and their images.
This is separate from the normal cache-TTL pruning described above. It exists to prevent repeated image payloads or stale media refs from breaking prompt caches on later turns.

Smart defaults

The bundled Anthropic plugin auto-configures pruning and heartbeat cadence the first time it resolves an Anthropic (or Claude CLI) auth profile, but only for fields you have not already set explicitly:

Auth mode	`contextPruning.mode`	`contextPruning.ttl`	`heartbeat.every`
OAuth/token (including Claude CLI reuse)	`cache-ttl`	`1h`	`1h`
API key	`cache-ttl`	`1h`	`30m`

If you set agents.defaults.contextPruning.mode or agents.defaults.heartbeat.every yourself, OpenClaw does not override them. This auto-default only fires for Anthropic-family auth; other providers get pruning off unless you configure it.

Enable or disable

Pruning is off by default for non-Anthropic providers. To enable:

{
  agents: {
    defaults: {
      contextPruning: { mode: "cache-ttl", ttl: "5m" },
    },
  },
}

To disable: set mode: "off".

Pruning vs compaction

	Pruning	Compaction
What	Trims tool results	Summarizes conversation
Saved?	No (per-request)	Yes (in transcript)
Scope	Tool results only	Entire conversation

They complement each other. Pruning keeps tool output lean between compaction cycles.