Semantic Cache MCP

Cut your MCP client's token usage by about 98% on cached reads, and get answers back in milliseconds.

Semantic Cache MCP is a Model Context Protocol server that puts every file operation behind one cache. The first read of a file seeds the cache and returns a content hash. After that, an unchanged file comes back as a short unchanged reply instead of the whole file, a changed file comes back as a unified diff, and a file that is too large is summarized down to its structure. Search and grep run over the same cached files, so the agent searches what it already read instead of going back to disk. Thirteen tools (read, read_image, batch_read, write, edit, edit_preview, batch_edit, search, grep, glob, delete, clear, stats) share that one cache-aware layer.

Why this exists

1. Reads stop costing tokens. The first read seeds the cache and hands back a content_hash. Send that hash back on the next read (as known_hash) and the server replies unchanged without resending the file. A modified file returns a unified diff with the changed line numbers. A file larger than the budget collapses to a structure-preserving summary instead of a blind cut at a byte offset.

2. Search and grep run on the cache, not the disk. Keyword search (BM25), glob, and grep all read from the same indexed corpus that read/batch_read populate. An in-session result LRU collapses repeated queries to sub-millisecond hits.

3. Mutations are bounded by default. write, edit, and batch_edit enforce size and match limits, support dry_run, can run formatters, and refresh the cache atomically.

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: add to ~/.claude/settings.json:

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

OpenCode: add to ~/.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 tool map. This section only shows 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

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

Configuration

Environment Variables

See docs/env_variables.md for detailed descriptions, model selection guidance, and examples.

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  │
 └──────────┘    └──────────┘

Every read also returns a content_hash. Hand it back as known_hash on your next read and the server answers unchanged from that fact alone, with no guess about what it already sent you.

search works the same way. An in-session LRU keyed on (query, k, directory) returns warm hits in ~10 µs; misses fall through to BM25 keyword search. 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 40 source files (177,509 tokens), i9-13900K, with the corpus held fixed across all phases. Reproducible via --json output for CI diffing.

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

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

Run benchmarks yourself:

uv run python benchmarks/benchmark_token_savings.py    # token savings
uv run python benchmarks/benchmark_performance.py      # operation latency

See docs/performance.md for full benchmarks and 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 3.2+ 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