Session Pruning

Session pruning trims ''old tool results'' from the in-memory context right before each LLM call. It does ''not'' rewrite the on-disk session history (''*.jsonl'').

- When ''mode: "cache-ttl"'' is enabled and the last Anthropic call for the session is older than ''ttl''.

- Only affects the messages sent to the model for that request.

- Only active for Anthropic API calls (and OpenRouter Anthropic models).

- For best results, match ''ttl'' to your model ''cacheControlTtl''.

- After a prune, the TTL window resets so subsequent requests keep cache until ''ttl'' expires again.

Pruning applies only to tool results:

- ''tool_result''Messages

- ''tool_use'' messages are ''not pruned'' (needed for the LLM to know which tool it called)

Currently supported strategies:

- Context size reduction: old tool results are removed, making context smaller

- Cost reduction: API calls are made with smaller context, reducing costs

- Performance improvement: processing with smaller context may reduce response time

Best practices for using session pruning effectively:

- Match TTL to models' ''cacheControlTtl''

- Enable pruning in long sessions to prevent context bloat

- Monitor logs to confirm pruning is working as expected

- Adjust TTL value considering cost and performance balance

Troubleshooting if pruning is not working as expected:

- Confirm TTL value matches models' ''cacheControlTtl''

- Confirm you're using Anthropic API (doesn't work with other providers)

- Confirm the session's last human message is older than TTL

Pruning has the following effects:

- Reduced context size: old tool results are removed, making context smaller

Pruning has the following limitations:

- Only works with Anthropic API (and OpenRouter Anthropic models)

- Only tool results are pruned (other message types are not affected)

- On-disk session history is not modified

To monitor pruning behavior, check the logs:

- When pruning runs, a message is logged

- The count of pruned messages is logged

- The context size after pruning is shown in logs

Best practices for using session pruning effectively:

- Match TTL to models' ''cacheControlTtl''

Troubleshooting if pruning is not working as expected:

- Confirm TTL value matches models' ''cacheControlTtl''

- Confirm you're using Anthropic API (doesn't work with other providers)

- Confirm the session's last human message is older than TTL

- Check logs to confirm pruning is running

ReferenceConceptsSessionPruningPage step 11: P6

ReferenceConceptsSessionPruningPage step 11: P7

Session pruning is a powerful tool to prevent context bloat in long sessions. Using TTL-based pruning strategy, you can remove old tool results, reduce context size, and improve cost and performance.

{
  agent: {
    contextPruning: { mode: "off" },
  },
}

It works with Anthropic API and coordinates with model cache control settings to provide optimal results.

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

ReferenceConceptsSessionPruningPage step 12: P3

{
  agent: {
    contextPruning: {
      mode: "cache-ttl",
      tools: { allow: ["exec", "read"], deny: ["*image*"] },
    },
  },
}

ReferenceConceptsSessionPruningPage step 12: P4