ToolRecall — Deterministic Execution Layer for Agent Tools

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
toolrecall setup                # config -> systemd service -> daemon start

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   Forward proxy on custom port
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

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

• 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
• Benchmark Report — latest measured results per arm
• 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
• Agent Tracking — per-agent cache stats, TOOLRECALL_AGENT_ID
• 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