01 / a deterministic execution layer for agent tools

ToolRecall — Deterministic Execution Layer

Caches tool results so repeat reads are ~1000× faster and context doesn't snowball. 8K vs 76K at turn 10 — 84+ vs 16 turns.

✓ installed — zero dependencies, pure Python stdlib

02 / results — 13h real session

Ready to cut your token costs?

76K

per-turn tokens at
turn 10 (naive)

8K

per-turn tokens at
turn 10 (ToolRecall)

~90%

fewer tokens at
turn 10 vs naive

9.5×

fewer tokens at
turn 10 vs naive

84+

median exhaustion
turns (naive: 16)

99%

cache hit rate
(review workload)

~0.6ms

repeat reads —
~1000× faster

up to 90%

provider prefix-cache
discount unlocked

0

dependencies —
stdlib only

$ pipx install toolrecall
$ toolrecall setup ★ Star on GitHub →

03 / the problem

The Context Snowball

LLM context accumulates everything. Every file read and command output stays in context forever — even exact duplicates.

session context 0 tokens

Red blocks are repeat reads of the same file. In our benchmark: naive sessions exhausted at 16 turns — ToolRecall runs 84+ turns before exhaustion. That's a 5×+ increase in usable session length.

04 / how it works

One daemon. Four cache layers.

ToolRecall caches file reads, terminal output, MCP tool results, and API requests. Any layer can miss once and hit forever — the daemon auto-invalidates on mtime changes and signals the agent to drop clean content from context.

05 / context tracker

Breaking O(N²) growth

The tracker knows which files the agent wrote (dirty) vs. only read (clean). Clean content drops from context (driven by tracker signals) — agent reasoning still accumulates, but at ~1,500 tok/turn instead of the snowball's ~52K. The structural ceiling: file bloat gone, reasoning only.

main.py · dirty utils.py · clean config.json · clean api.py · dirty README.md · clean

Without TR — exhausted at 16 turns With TR — runs 84+ turns

06 / why not an LLM-powered cache?

No LLM in the caching loop

LLM-driven cache

ToolRecall

Guesses what's static — messages silently dropped

ttl=0 means never cache. Binary, no AI middleman

Extra LLM call to classify every new tool

$0 — SQLite. No embeddings, no API calls

Blind to side effects; may misjudge freshness

mtime invalidation — file edited? next read is fresh

Non-deterministic — same tool, different verdicts

Byte-identical for same args + mtime. 100% reproducible