Session Pruning: Optimizing Context and Cache Efficiency

Session pruning removes older tool outputs from the context prior to every LLM request. This curbs context expansion caused by accumulated tool data (command results, file contents, search findings) while leaving regular conversational text untouched.

Info

Pruning operates solely in memory, never altering the session transcript stored on disk. Your complete history remains intact.

Why it matters

Extended sessions build up tool output that enlarges the context window. That drives up expenses and may trigger compaction earlier than needed.

Pruning proves especially useful for Anthropic prompt caching. Once the cache TTL lapses, the following request re-caches the entire prompt. Pruning shrinks the cache-write size, which cuts costs directly.

How it works

Pruning activates in cache-ttl mode, controlled by both a timing condition and a context-size condition:

1. Await the cache TTL expiry (default 5 minutes when configured manually; see Smart defaults for the Anthropic auto-default). Before the TTL passes, pruning is entirely bypassed to maintain prompt-cache reuse for adjacent turns.
2. After the TTL passes, compare total context size against the model's context window. When usage falls below roughly 30%, pruning is bypassed and the TTL timer continues running.
3. Soft-trim oversized tool results: outputs exceeding 4,000 characters retain their opening and closing 1,500 characters with ... placed between them.
4. If context usage still reaches roughly 50% or higher and at least 50,000 characters of prunable tool content remain, hard-clear those results: swap their content for a placeholder (default [Old tool result content cleared], adjustable via agents.defaults.contextPruning.hardClear.placeholder; set hardClear.enabled: false to skip this action).
5. Restart the TTL timer only when pruning actually altered the context, ensuring subsequent requests benefit from the refreshed cache.

Two safeguards apply regardless of thresholds: the last three assistant turns are never pruned, and nothing preceding the session's first user message is ever pruned (protects bootstrap reads like SOUL.md/USER.md). The size thresholds and trim windows above reflect built-in behavior, not configuration keys; the adjustable surface is agents.defaults.contextPruning (mode, ttl, tools, hardClear).

Only toolResult messages qualify; regular conversational text remains untouched. Use agents.defaults.contextPruning.tools.{allow,deny} to limit which tool names can be pruned.

Legacy image cleanup

OpenClaw additionally constructs 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 nearby follow-ups stay consistent. This count covers all completed turns, not just those with images, so text-only turns also consume the window.
• Within the replay view, older already-processed image blocks from user or toolResult history get replaced with [image data removed - already processed by model].
• Older textual media references such as [media attached: ...], [Image: source: ...], and media://inbound/... get replaced with [media reference removed - already processed by model]. Current-turn attachment markers remain unchanged so vision models can still hydrate fresh images.
• The raw session transcript stays unmodified, letting history viewers render the original message entries and their images.
• This operates independently of the 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 explicitly set:

If you configure agents.defaults.contextPruning.mode or agents.defaults.heartbeat.every yourself, OpenClaw leaves them alone. This auto-default applies solely to Anthropic-family auth; other providers receive pruning off unless you configure it.

Enable or disable

Pruning is disabled by default for non-Anthropic providers. To activate it:

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

To deactivate it: set mode: "off".

Pruning vs compaction

They work together, with pruning keeping tool output lean between compaction cycles.

Further reading

• Compaction: summarization-based context reduction
• Gateway Configuration: all pruning config knobs (contextPruning.*)

Related

• Session management
• Session tools
• Context engine