ToolRecall — Deterministic Execution Layer for Agent Tools

🌐 toolrecall.dev — documentation, benchmarks, downloads

You run agents. Every session spawns its own MCP servers, every test run hits live APIs, every tool call is unrepeatable, and your agent can read ~/.ssh if it feels like it.

ToolRecall is one shared daemon that pools your MCP servers, records and replays tool results, caches repeated API calls, and enforces filesystem/terminal policy for any agent framework.

One warm daemon instead of five cold Node processes. ~132 KB install. Python 3.11+ stdlib only.

pipx install toolrecall
toolrecall setup          # One-shot: config -> systemd -> daemon start

Zero config mode: Every toolrecall command auto-starts the daemon if it isn't running. You never need to think about it.

Quickstart — MCP Bridge (30 seconds)

Connect any MCP agent by registering one server:

// ~/.claude/settings.json  or  ~/.cursor/mcp.json  or  ~/.config/cline/mcp_settings.json
{
  "mcpServers": {
    "toolrecall": {
      "command": "toolrecall",
      "args": ["mcp"]
    }
  }
}

# ~/.config/toolrecall/toolrecall.toml
[mcp_multiplex]
servers = ["time", "github", "fetch"]

That's it. Your agent now has access to all multiplexed MCP servers, caching, and security — with zero per-agent configuration.

Before: 5 agents x 3 MCP servers = 15 cold Node processes, ~25 MB RAM per server
After:  5 agents x 1 toolrecall mcp = 3 warm subprocesses, shared across all agents

Features:

• Lazy loading: servers boot on first call, not at daemon start
• Idle timeout: inactive subprocesses killed after 15 min (configurable)
• Failure isolation: one server crash doesn't affect others (auto-reconnect)
• Auto-resolution: server names resolve from built-in registry

See MCP Multiplexer for full configuration.

What ToolRecall Does

Full detail in Architecture.

How It Works

flowchart LR
    subgraph Agents
        A1["Claude Code"]
        A2["Cursor"]
        A3["Aider"]
        A4["Hermes"]
    end
    subgraph Daemon["ToolRecall Daemon"]
        MP["MCP Multiplexer"]
        CA["Cache (LRU + SQLite)"]
        SG["Security Gate"]
        FP["Forward Proxy"]
    end
    subgraph OS["OS Layer"]
        FS["Filesystem / Network"]
    end

    A1 --> MP
    A2 --> MP
    A3 --> MP
    A4 --> MP
    MP --> CA
    MP --> SG
    MP <--> FS
    A1 --> FP
    FP --> CA
    FP <--> FS

One daemon, five access paths: Python client, MCP bridge, HTTP bridge, forward proxy, OS-level shim. All share one cache, one security gate, one multiplexer. See Architecture.

When To Use It

Installation

One-time setup

pipx install toolrecall        # or: uv tool install toolrecall
                               # or: pip install toolrecall (inside a venv)
toolrecall setup                # config -> systemd service -> daemon start

PATH check: After installation, make sure toolrecall is on your $PATH.
pipx puts binaries in ~/.local/bin/, uv tool install in ~/.local/share/uv/tools/.
If toolrecall isn't found, add the right directory to your PATH or reinstall inside the venv your agent uses.

Shim in the right venv: toolrecall shim --install installs the .pth shim into the current Python environment. If you installed via pipx or uv tool install, the shim goes into that isolated environment — not your agent's venv. The agent won't see it. toolrecall setup auto-detects common agent venvs and installs the shim there too. toolrecall shim --install --all scans for agent venvs (Hermes, OpenCode) and installs into all of them at once. If you need to target a specific venv manually:

toolrecall shim --install --venv ~/.hermes/hermes-agent/venv
toolrecall shim --install --venv ~/.local/share/uv/tools/hermes-agent

The toolrecall package must also be installed in that venv (import toolrecall must work).

toolrecall setup creates ~/.config/toolrecall/toolrecall.toml with default-deny security, generates a systemd user unit, and starts the daemon. After this, every toolrecall command "just works".

Daemon auto-start fallback: systemd -> os.fork() -> DETACHED_PROCESS (Linux -> Docker/macOS -> Windows).

Per-agent integration

Extra storage backends

pip install toolrecall[libsql]       # libSQL local backend
pip install toolrecall[libsql-sync]  # libSQL + Turso Cloud sync

CLI Quick Reference

toolrecall setup          One-shot: config + systemd + daemon start  [required once]
toolrecall status         Cache status and stats                     [auto-starts]
toolrecall stats          Detailed cache statistics (JSON)           [auto-starts]
toolrecall invalidate     Clear all caches                           [auto-starts]
toolrecall mcp            Start MCP Bridge                           [auto-starts]
toolrecall serve          Forward proxy (cache API responses)        [auto-starts]
toolrecall serve --9000   Custom port forward proxy
toolrecall replay         Record/replay agent sessions
toolrecall shim --install Install OS-level cache shim (.pth file)
toolrecall turso          Turso Cloud sync: init, enable, disable, status
toolrecall init           Create default config.toml and .env
toolrecall config-set     Set a config value
toolrecall index          Index knowledge DB (FTS5 search)  [not file cache pre-warm]
toolrecall index-memory   Index agent memory stores
toolrecall index-dir      Index a directory for FTS5 search [not file cache pre-warm]

Knowledge indexing ≠ cache warming: toolrecall index* commands build an FTS5 search index for knowledge retrieval (docs_search()). They do NOT pre-warm the file/terminal/API response cache. The daemon's file cache warms naturally as the agent reads files — no separate command needed.

Full reference: CLI.md

Configuration

# ~/.config/toolrecall/toolrecall.toml
[mcp]
allowed_paths = ["/home/user/projects"]  # Default-deny!
allow_terminal = false

[cache]
terminal_default_ttl = 60

[mcp_multiplex]
enabled = true
servers = ["time", "sequential-thinking"]

[forward_proxy]
# Starts on :8569 automatically with the daemon

TOOLRECALL_* env vars override TOML. Full reference: Configuration Reference

Platform Support

Documentation

• toolrecall.dev — documentation portal, benchmarks, downloads
• Architecture — system design, components, data flow, token costs
• MCP Multiplexer — daemon-managed MCP server pool
• Forward Proxy — API response caching, provider list, auth routing
• Replay Mode — record/replay tool calls for deterministic CI
• Security Architecture — policy gate, trust boundary
• Agent Compatibility — per-agent value, config, caveats
• Benchmark — three-arm controlled measurement (naive vs prefix vs toolrecall), context efficiency, billed cost
• Bench Infrastructure — reproduce the three-arm benchmark
• Test Suite — test runner documentation
• CLI Reference — all subcommands
• Configuration Reference — config.toml, env vars
• Context Stale — provably stale files in agent conversations
• Context Tracker — checkpoint-based dirty-file tracking
• Testing Guide — test philosophy, per-file coverage
• How It Works — quick technical overview
• libSQL Backend — multi-writer, vector search, cloud sync
• Docker Deployment — containerized stack
• Troubleshooting — common fixes
• Changelog — version history
• Go Client — standalone tr binary for any language/shell
• Agent Configs — ready-to-use MCP configs for popular agents
• Framework Adapters:
  • Google ADK — @cached_tool decorator + forward proxy
  • LangChain / LangGraph — ToolRecallCache BaseCache + callback
  • herdr — tr binary + MCP bridge for any pane
  • Odysseus — cached_tool decorator + MCP server caching
• Hermes Transparent Cache — auto-patching for Hermes
• Normalizer — cache key normalization, deterministic JSON
• Knowledge DB — FTS5 indexing guide
• Real-Agent Benchmark — edit-heavy session results
• Appendix — comparison tables, OSI model, ROI, audit

Contributing

git clone https://github.com/whiskybeer/toolrecall.git
cd toolrecall
make setup    # one-time dev deps
make test     # run tests
make check    # lint + format

See Testing Guide and Makefile.

Uninstall

systemctl --user stop toolrecall-daemon
systemctl --user disable toolrecall-daemon
pipx uninstall toolrecall
rm -rf ~/.toolrecall ~/.config/toolrecall