Semantic Cache MCP

io.github.CoderDaytonPublished by GitHub account CoderDaytonv0.7.0Updated Oct 30, 2026

File cache for coding agents: re-reads cost ~40 tokens, changed files return diffs.

VerifiedSTDIODesktop onlyFiles & StorageDeveloper Tools

Overview

AI-generated overview

A local file cache for AI coding agents that returns hashes, diffs or outlines instead of whole files, so re-reads cost far fewer tokens.

What you can do
  • Read files with a content hash, re-read unchanged files cheaply, and get diffs of changed lines
  • Batch-read files within a token budget and preview large files as outlines of their definitions
  • Search the cache with BM25 keyword ranking, exact grep and glob
  • Write, edit and delete files, with atomic edits and a dry-run preview
  • Warm the cache, inspect statistics and clear it
When to use it
Useful for coding agents that repeatedly read the same project files before and after edits or after context compaction, where cutting re-read token cost matters. It is a local replacement for built-in file tools rather than an addition to them.
Requirements
Runs locally over stdio via uvx from the semantic-cache-mcp PyPI package, so uv must be installed. No API keys, no GPU and no declared environment variables. The only network request is a one-time download of a tokenizer file.
Before you install
It can write, edit and delete files in your project, so review edits and use the dry-run preview before applying them. The cache is a SQLite file served by a background daemon shared across clients on the machine. The README recommends disabling built-in file tools so the agent uses the cache instead.

Installation

In SourceWeft

  1. Open Semantic Cache MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Semantic Cache MCP Logo]

Semantic Cache MCP

Stop paying for the same file twice.
An MCP file cache for AI coding agents: a re-read costs ~40 tokens instead of the whole file.

[PyPI version] [PyPI downloads] [Python 3.12+] [License: MIT]

[Semantic Cache MCP on Glama]   [Support on Ko-fi]

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:

ReadBuilt-in ReadSemantic Cache MCP
First read7,891 tokensfull file, plus a hash
Re-read, file unchanged7,891 tokens77 tokens
Re-read after a one-line edit7,891 tokens137 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:

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

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

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:

mermaid
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

GuideCovers
ClientsSetup for each client, turning off built-in file tools
ToolsEvery tool, with parameters and examples
Environment VariablesEvery setting, with defaults
PerformanceBenchmarks and methodology
ArchitectureStorage, algorithms, the shared daemon
SecurityThreat model, size limits, path handling
TroubleshootingCommon issues, debug logging
Advanced UsagePython API

Contributing

bash
git clone https://github.com/CoderDayton/semantic-cache-mcp.gitcd semantic-cache-mcpuv sync --extra devuv run pytest

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

License

MIT.

Source: README.md at commit d6a780b

Tools

0
SourceWeft started this package once in an isolated sandbox, without credentials, to list its tools. That failed: the package did not install.

Version history

1
  1. v0.7.0LatestOct 23, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts