31% cheaper per session.
Same model, same work, less context. For stateless agents (Hermes, Cline, ADK)

ToolRecall's context tracker tells your agent which files to drop after every turn.
Your agent sends 46% fewer prompt tokens — and survives workloads
naive sessions can't finish.

⚠️ File caching via MCP only helps stateless agents. If your agent already manages its own context (Claude Code, Cursor), routing file tools through ToolRecall increases costs (~2.4×, measured). Use TR for the forward proxy and MCP multiplexer instead — those save money for everyone. (Claude Code A/B: real billed API usage, n=2, adoption forced, edit-heavy, Sonnet 5 — directional. Separate from provider prefix caching, which is orthogonal and complements TR on stateless agents.)

v0.8.15 · stdlib only · 132 KB · Agent compatibility →

$7.87 ToolRecall total spend
3/3 workloads completed

$11.36 Naive total spend
1/3 workloads completed

−31% Cheaper on matched
workload (bugfix)

N=1 seed per workload. Custom scripted workloads on ToolRecall's own codebase — not SWE-bench. Full methodology →

$ pipx install toolrecall Zero deps, pure stdlib

$ toolrecall setup Sets up daemon + per-agent config

By Agent

Who benefits from file caching?

ToolRecall's file cache eliminates repeat file-read tokens. Whether that saves you money depends on whether your agent already manages its own context.

Agent	File Cache via MCP	Forward Proxy	Multiplexer	Why
Hermes	✅ Saves 73–91%	✅	✅	Stateless. No built-in context management. Biggest win.
Cline	✅ Saves	✅	✅	Python agent, little native context management.
Google ADK	✅ Saves	✅	✅	No built-in tool caching in the framework.
OpenCode	✅ Saves	✅	✅	Node.js (shim N/A), but MCP bridge helps.
Claude Code	❌ Avoid — 2.4× cost	✅	✅	Native Read + compaction already manage context. File cache adds cost.
Cursor	⚠️ No benefit	✅	⚠️ Redundant	Manages its own tool state aggressively.

File cache savings measured in 13h Hermes benchmark: 73-91% fewer repeat file tokens. Claude Code A/B test: 2.4× cost increase when routing file I/O through MCP (real billed API usage, n=2, adoption forced, edit-heavy — directional). Full agent compatibility →

The Problem

Context Snowball

Every LLM agent session accumulates context turn by turn — every file read, every command output stays forever. Eventually you hit the context limit and the session dies. All progress lost.

unbounded growth

Without ToolRecall

Full conversation history re-sent every turn. Hits the model's context cap and dies — typically within a few hundred turns on DeepSeek V4 Flash.

stays under cap

With ToolRecall

Clean file content is dropped each turn. Only instructions and responses accumulate. Survives workloads naive sessions can't finish — benchmarked at 450+ turns with 35% headroom.

Full benchmark results →

How It Works

One daemon. Three mechanisms.

ToolRecall intercepts file reads via a shared daemon. Every read is cached. Every write is tracked. Your agent can drop clean files from context.

1. File Cache

Read once from disk → served from memory forever.
~0.6ms vs ~1.5s subprocess fork.
99.3% hit rate in benchmark.
Stateless agents only — see table above.

2. Context Tracker

Tracks which files are clean (read) vs dirty (written).
Agent drops clean content from context each turn.
86–92% less payload at matched turn count.

3. MCP Multiplexer

One daemon pools MCP servers across all agents.
Lazy loading — servers boot on first call.
Works for every agent — even Claude Code.

For Every Agent

These work for everyone

File caching is agent-specific, but these features save time and money regardless of which agent you use.

$0 dev loops

Forward Proxy

Caches API responses by body hash. Hit = zero tokens billed, zero API calls. Works with any agent — set OPENAI_BASE_URL=http://localhost:8569/v1.

10× fewer processes

MCP Multiplexer

One warm daemon instead of N cold Node processes per agent session. Shared subprocesses for GitHub, Postgres, fetch — across all agents simultaneously.

deterministic

Replay Mode

Record agent sessions, replay in CI. Byte-identical tool outputs every time. Works with any agent that connects via MCP.

Evidence

Sessions: outlasts naive

Measured on DeepSeek V4 Flash at the model's true 1,048,576 context limit. On read-heavy workloads, naive sessions hit the cap at ~112 turns while ToolRecall completes all 200 turns at 142K context. On analysis workloads, TR completes 400 turns vs naive's 145. The same pattern across all workloads: ToolRecall keeps sessions alive longer. Full benchmark →

FAQ

Myths & clarity

Does the file cache work with Claude Code?

No — it makes sessions more expensive. A controlled A/B test showed 2.4× cost increase and 3.1× longer wall time when routing file I/O through ToolRecall's MCP bridge (real billed API usage, n=2, adoption forced, edit-heavy, Sonnet 5 — directional). This is specific to Claude Code's append-only harness: it can't drop context, so TR's file-cache stubs add round-trips without savings. It is orthogonal to provider prefix caching, which pairs well with TR on stateless agents. Use TR for the forward proxy and MCP multiplexer only. Details →

Why does file caching cost more for some agents?

Agents like Claude Code already have native Read tools, compaction, and prompt caching. Adding an MCP layer with patch (which lacks replace_all) duplicates tool infrastructure while turn-inflation from extra round-trips swamps any stub savings (~15K tokens saved vs ~690K extra billed — 45×).

71–91% fewer repeat file tokens — is that real?

Yes, for stateless agents. Measured in real Hermes sessions. The file cache eliminates repeat file-read tokens entirely. For agents without native context management (Hermes, Cline, ADK), this translates to real cost savings and longer-lived sessions.

Does ToolRecall work with my agent at all?

Every MCP-capable agent benefits from the MCP multiplexer (shared subprocesses) and forward proxy (cached API responses). The file cache via MCP is only beneficial for stateless agents without built-in context management. See the agent compatibility table.

Install

Get started in 30 seconds

No dependencies. Just Python 3.11+.

$ pipx install toolrecall

Zero dependencies, pure stdlib

$ toolrecall setup

Creates config, detects agents, starts daemon

$ toolrecall status

Check cache hit rate, active sessions, file stats

Works with Hermes Agent, Claude Code, Cursor, Cline, opencode — any MCP-capable agent. Per-agent notes →