Semantic Cache MCP server

---

Coding agents read the same files over and over: before an edit, after an edit, after every context compaction. A built-in Read sends the whole file each time. Semantic Cache MCP knows what your agent already holds. Measured on one 7,891-token file:

Read	Built-in Read	Semantic Cache MCP
First read	7,891 tokens	full file, plus a hash
Re-read, file unchanged	7,891 tokens	77 tokens
Re-read after a one-line edit	7,891 tokens	137 tokens (a diff)

Across a 48-file project it saves 98.7% of re-read tokens, and an unchanged read takes 0.17 ms. It also gives your agent grep, BM25 search and glob over the cache, atomic edits with dry_run, and token-budgeted batch reads. Three runtime dependencies, no API keys, no GPU.

Quick start

You need uv. In Claude Code:

claude mcp add semantic-cache --scope user -- uvx semantic-cache-mcp

Any other client (Cursor, Claude Desktop, and others that take mcpServers JSON):

{
  "mcpServers": {
    "semantic-cache": {
      "command": "uvx",
      "args": ["semantic-cache-mcp"]
    }
  }
}

Configs for VS Code, Codex and OpenCode, and how to turn off the built-in file tools so the agent uses the cache: docs/clients.md.

How it works

Every file the server sends comes with a content_hash. The agent passes it back as known_hash on the next read:

flowchart LR
    R["read(path, known_hash)"] --> M{"hash matches<br/>the file now?"}
    M -- yes --> U["unchanged<br/>~40 tokens"]
    M -- "no, older version" --> D["diff of changed lines"]
    M -- "no hash" --> F["full file + content_hash"]

• No stale content. Every read checks the file on disk first. unchanged only answers when the hash matches the current bytes.
• Forgetting is safe. After a compaction, the agent reads without the hash and gets the full file back.
• Large files become maps. A file over max_size returns an outline of its definitions, not a blind cut.
• Everything stays local. The cache is a SQLite file. One background daemon serves every client on your machine.

Tools

read · batch_read · read_image · write · edit · batch_edit · edit_preview · delete · warm · grep · search · glob · stats · clear

Parameters and examples: docs/tools.md.

FAQ

Is the search "semantic" in the embeddings sense? No. search is BM25 keyword ranking and grep is exact. No model to download, no GPU, no API key.

Does it send my code anywhere? No. The only network request is a one-time download of the o200k tokenizer file, checked against a SHA-256 hash.

Does it work on Windows? Yes. CI runs on Linux and macOS.

Documentation

Guide	Covers
Clients	Setup for each client, turning off built-in file tools
Tools	Every tool, with parameters and examples
Environment Variables	Every setting, with defaults
Performance	Benchmarks and methodology
Architecture	Storage, algorithms, the shared daemon
Security	Threat model, size limits, path handling
Troubleshooting	Common issues, debug logging
Advanced Usage	Python API

Contributing

git clone https://github.com/CoderDayton/semantic-cache-mcp.git
cd semantic-cache-mcp
uv sync --extra dev
uv run pytest

See CONTRIBUTING.md. Issues and pull requests are welcome.

License

MIT.