Semantic Cache MCP

Cut your MCP client's token usage by ~98% on cached reads, with millisecond responses.

Semantic Cache MCP is a Model Context Protocol server that puts every file operation behind one cache. Re-reading a file you already hold costs a few tokens instead of the whole file, and search and grep run over that same corpus rather than the disk.

Fourteen tools share the layer: read, read_image, batch_read, warm, write, edit, edit_preview, batch_edit, search, grep, glob, delete, clear, stats.

Why this exists

Reads stop costing tokens. The first read hands back a content_hash. Send it back — known_hash on read, a known_hashes entry on batch_read — and the server replies unchanged without resending. A modified file returns a diff with changed line numbers; an oversized one collapses to a structure-preserving summary rather than a blind cut at a byte offset.

Hashes travel as their first 16 hex characters — a claim is only ever checked against the entry for the path it names, so 64 bits separates two versions of one file with room to spare, and the full digest is still accepted. A shorter prefix is not: that would match every version at once.

That echoed hash is the whole contract, and it is the only evidence the server has that a file is still in your context. A warm cache proves the server holds the file, never that you do — the store is on disk and outlives the process, the session, and your context window. A read without a matching hash always sends the file, so forgetting is safe: after a compaction, omit the hashes and get your files back in full.

Search and grep run on the cache, not the disk. BM25 keyword search, glob, and grep all read the corpus that read, batch_read and warm populate — and warm fills it without returning a byte of content, so a whole tree becomes searchable for a few dozen tokens. An in-session result LRU collapses repeated queries to sub-millisecond hits.

Mutations are bounded by default. write, edit, and batch_edit enforce size and match limits, can run formatters, and refresh the cache atomically. A dry_run writes nothing and says so — the status becomes would_create / would_update / would_edit — so a preview is never mistaken for a completed write.

Installation

Add to Claude Code settings (~/.claude.json).

Option 1: uvx, always runs the latest version:

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

Option 2: uv tool install:

uv tool install semantic-cache-mcp

{
  "mcpServers": {
    "semantic-cache": {
      "command": "semantic-cache-mcp"
    }
  }
}

Restart Claude Code.

Block Native File Tools (Recommended)

Disable the client's built-in file tools so all file I/O routes through semantic-cache.

Claude Code — ~/.claude/settings.json:

{
  "permissions": {
    "deny": ["Read", "Edit", "Write"]
  }
}

OpenCode — ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "read": "deny",
    "edit": "deny",
    "write": "deny"
  }
}

CLAUDE.md Configuration

Add to ~/.claude/CLAUDE.md to enforce semantic-cache globally:

## Tools

- MUST use `semantic-cache-mcp` instead of native I/O tools (98% token savings on cached reads)

Tools

Core

Discovery

Management

Tool Reference

The table above is the authoritative map; these are the common call shapes.

read path="/src/app.py"                        # automatic: full, unchanged, or diff
read path="/src/app.py" offset=120 limit=80    # lines 120 to 199 only

write path="/src/new.py" content="..."
write path="/src/new.py" content="..." auto_format=true
write path="/src/large.py" content="...chunk1..." append=false   # first chunk
write path="/src/large.py" content="...chunk2..." append=true    # subsequent chunks

# Mode A: find/replace, searches the entire file
edit path="/src/app.py" old_string="def foo():" new_string="def foo(x: int):"
edit path="/src/app.py" old_string="..." new_string="..." replace_all=true auto_format=true

# Mode B: scoped find/replace, searches only within the line range (a shorter old_string works)
edit path="/src/app.py" old_string="pass" new_string="return x" start_line=42 end_line=42

# Mode C: line replace, swaps the whole range with no old_string needed (most token savings)
edit path="/src/app.py" new_string="    return result\n" start_line=80 end_line=83

# Mode A: find/replace, [old, new]
batch_edit path="/src/app.py" edits='[["old1","new1"],["old2","new2"]]'

# Mode B: scoped, [old, new, start_line, end_line]
batch_edit path="/src/app.py" edits='[["pass","return x",42,42]]'

# Mode C: line replace, [null, new, start_line, end_line]
batch_edit path="/src/app.py" edits='[[null,"    return result\n",80,83]]'

# Mixed modes in one call (object syntax also supported)
batch_edit path="/src/app.py" edits='[
  ["old1", "new1"],
  {"old": "pass", "new": "return x", "start_line": 42, "end_line": 42},
  {"old": null, "new": "    return result\n", "start_line": 80, "end_line": 83}
]' auto_format=true

batch_read paths="/src/a.py,/src/b.py" max_total_tokens=50000
batch_read paths='["/src/a.py","/src/b.py"]' priority="/src/main.py"
batch_read paths="/src/*.py" max_total_tokens=30000
batch_read paths="/src/a.py,/src/b.py" known_hashes='{"/src/a.py":"8f3c..."}'

warm paths="src/**/*.py"
warm paths="src/a.py,src/b.py"
warm paths="src/**/*" max_files=500

search query="authentication middleware logic" k=5
glob pattern="**/*.py" directory="./src" cached_only=true
grep pattern="class Cache" path="src/**/*.py"
grep pattern="content_hash" output="paths"
grep pattern="TODO" output="count"

Configuration

Environment Variables

A malformed value falls back to the default and logs a warning naming the variable. See docs/env_variables.md for detail.

Safety Limits

MCP Server Config

{
  "mcpServers": {
    "semantic-cache": {
      "command": "uvx",
      "args": ["semantic-cache-mcp"],
      "env": {
        "LOG_LEVEL": "INFO",
        "TOOL_OUTPUT_MODE": "compact",
        "MAX_CONTENT_SIZE": "100000"
      }
    }
  }
}

Cache location: ~/.cache/semantic-cache-mcp/ (Linux), ~/Library/Caches/semantic-cache-mcp/ (macOS), %LOCALAPPDATA%\semantic-cache-mcp\ (Windows). Override with SEMANTIC_CACHE_DIR.

How It Works

┌──────────┐     ┌────────────┐     ┌──────────────────────────┐
│  Claude  │────▶│ smart_read │────▶│ stat() + cache lookup    │
│   Code   │     │            │     │ (BEFORE any disk read)   │
└──────────┘     └────────────┘     └──────────────────────────┘
                        │
       ┌────────────────┼─────────────────┬──────────────────┐
       ▼                ▼                 ▼                  ▼
 ┌──────────┐    ┌──────────┐      ┌──────────┐      ┌────────────┐
 │ mtime    │    │ mtime    │      │ Changed  │      │ New /      │
 │ match    │    │ drift,   │      │ content  │      │ Large      │
 │ FAST     │    │ hash     │      │ → diff   │      │ → summary  │
 │ PATH     │    │ match    │      │ (80-95%) │      │  or full   │
 │ ~5 tok   │    │ ~5 tok   │      └──────────┘      └────────────┘
 │ (99%)    │    │ (99%)    │
 │ ~1 ms    │    │ ~1 ms    │
 │ no I/O   │    │ +update  │
 └──────────┘    └──────────┘

search is cached on the same principle. An in-session LRU keyed on (query, k, directory) returns warm hits in ~10 µs, and misses fall through to BM25. Every cache mutation (put, clear, delete_path, update_mtime) bumps the LRU, so callers never see a result that predates a write.

Performance

Measured on this project's 41 source files (212,499 tokens), i9-13900K, ext4 on NVMe, corpus held fixed across phases. Every phase models a caller that keeps its hashes and echoes them back — that is what earns the savings.

Token savings: 98.9% overall (phases 2 to 6)

Latency: unchanged reads ~1 ms; repeat searches < 0.01 ms

Run them yourself. Pin TMPDIR to a real disk — the default /tmp is usually tmpfs, which discards fsync and reports write latency ~40% low:

TMPDIR="$HOME/.cache/scmcp-bench" \
  uv run python benchmarks/benchmark_performance.py    # operation latency
uv run python benchmarks/benchmark_token_savings.py    # token savings

See docs/performance.md for full methodology.

Documentation

Contributing

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

See CONTRIBUTING.md for commit conventions, pre-commit hooks, and code standards.

License

MIT License. Use it freely in personal and commercial projects.

Credits

Built with FastMCP 4.0+ and:

• SQLite with FTS5 for keyword (BM25) full-text search, vendored as a small built-in store
• Semantic summarization based on TCRA-LLM (arXiv:2310.15556)
• BLAKE3 cryptographic hashing for content freshness
• W-TinyLFU frequency-aware cache eviction