Skip to main content
Glama

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.

Related MCP server: Ambiance MCP Server

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.

Available Tools

14 tools
batch_editBatch EditA

Apply many exact edits to one file in a single atomic call.

Preferred over repeated edit calls on the same file: one response, applied atomically, faster on large files. Partial success is allowed — any failed edits are returned with their reason so you can retry just the misses (status is edited when all apply, partial when some fail, no_changes when none do). A dry_run writes nothing and says so: the status becomes would_edit/would_partial and dry_run: true comes back with it. For edits across different files, call the tool once per file.

edits is a JSON array; each entry is one of:

  • [old, new] — exact find/replace.

  • [old, new, start_line, end_line] — find/replace confined to a range.

  • [null, new, start_line, end_line] — replace that line range wholesale.

  • {"old": ..., "new": ..., "start_line": ..., "end_line": ...} — object form.

Prefer line-range entries when you already have line numbers from read. Pass known_hash and the response carries a claimable content_hash, so no read is needed afterwards; without it, or with auto_format, you get file_hash instead.

Inputs: path (required), edits (required), dry_run, show_diff, +2 more.

batch_readBatch ReadA

Read several files at once under a shared token budget.

Cheaper than many single read calls. To make files searchable without reading them at all, use warm instead — this tool returns their text. Pass known_hashes and each file you still hold collapses to an unchanged count, or to a diff when it moved on disk; the rest come back in full with their content_hash. A file over max_size comes back as a map (see read) and carries none: a map is not the file. Smallest files are read first, and a file too big for the remaining budget is listed under skipped while smaller ones keep being read. Recover anything skipped with read using offset/limit. Paths are relative to the root the response names, when there is one worth naming.

Inputs: paths (required), priority, known_hashes, max_total_tokens.

clearClearA

Empty the cache. Does not touch any project file.

Removes every cached file entry and returns how many were dropped; the next read/batch_read re-seeds from disk. Use rarely — only to recover from stale cache state or force a cold re-seed. Normal reads already refresh changed files on their own, so this is seldom needed. Takes no arguments.

Inputs: no named parameters.

deleteDeleteA

Delete one file or symlink and evict its cache entries.

Use this for explicit single-path removal instead of shelling out. A missing path is reported as status not_found, not an error.

Statuses: deleted (removed), would_delete (dry-run preview only, and dry_run: true comes back with it), not_found (nothing was there). Constraints: one path only — no globs, no recursion, no real-directory deletes. A symlink path deletes the link itself, never its target.

Inputs: path (required), dry_run.

editEditA

Edit one file by exact text replacement.

Three modes:

  • find/replace: old_string + new_string (the default).

  • scoped: add start_line/end_line to confine the search to a range.

  • line-range: omit old_string and give both lines to replace them wholesale.

old_string must match exactly — whitespace and indentation included — and, unless replace_all=true, must be unique, or the edit fails. Use edit_preview first if you're unsure an anchor is unique. Returns the replacement count and the affected line numbers, and refreshes the cache. The diff itself is omitted unless you ask for it with show_diff; diff_state always tells you which you got. A dry_run writes nothing and says so: the status is would_edit and dry_run: true comes back with it. For several edits to one file use batch_edit; for a full rewrite use write.

Pass known_hash and the response carries a claimable content_hash, so no read is needed afterwards. Without it, or with auto_format, you get file_hash instead — editing a file is not the same as having read it.

Inputs: path (required), dry_run, end_line, show_diff, +6 more.

edit_previewEdit PreviewA

Show where old_string would match in a file, without editing it.

Returns the match count, 1-based line numbers, and short snippets so you can confirm an anchor is unique before calling edit. Read-only and cheap (kept under ~200 tokens), so use it freely as a probe. Raises an error on a binary file or an empty old_string.

Inputs: path (required), old_string (required).

globGlobA

List files matching a glob and show which are already cached.

Use it to discover files and see what search/grep can already access before you spend reads. Each match carries a cached flag; set cached_only=true to list only files already in the cache. Pair it with batch_read to pull in whatever isn't cached yet.

Inputs: pattern (required), directory, cached_only.

grepGrepA

Search cached file contents for an exact string or regex.

Fast, exact, line-numbered matching over files already in the cache — it does NOT touch disk, so index files first with warm, which costs a few dozen tokens however many files it covers (empty results usually mean the files aren't cached). A pattern that is not a valid regex is an error, never an empty result, so zero matches always means zero matches. For concept-level questions where you don't know the exact term, use search instead.

Counts are complete unless the response says otherwise: if a cap stops the scan, complete comes back false with limit_reached naming which one, so total_matches is never mistaken for the total that exists.

Each file's hits come back as "<line>:<text>" strings under lines, with context lines using - instead of :. Paths are relative to the root the response names, when there is one worth naming. The cache is shared across projects, so a relative path — or none — searches only the current project; an absolute path reaches files anywhere.

A repeated group wrapping an unbounded quantifier ((a+)+) is rejected rather than run — it can take exponential time and cannot be interrupted once started. Drop the redundant repeat, or pass fixed_string=true.

Inputs: pattern (required), path, output, max_files, +4 more.

readReadA

Read a file, returning as few tokens as possible. For 2+ files, use batch_read.

The first read returns the file's full content plus a content_hash. Echo it back as known_hash on every later read: an unchanged file then answers "unchanged": true with no body, a changed one returns a unified diff, and without it the file is always sent in full. Reading also caches the file so grep, search, and batch_read can see it.

A file larger than max_size returns a map instead of its text: the outline below, or for a file with no definitions its first and last lines under // L<a>-<b> anchors, flagged truncated with total_lines. Use offset/limit to read the exact lines it names. A read that returns only part of a file — a line range, or a map — reports file_hash (prefixed partial:) rather than content_hash, and it cannot be redeemed as known_hash. A ranged read also returns a coverage_token: pass it back as known_hash on your next ranged read and a window you already hold answers unchanged; once the windows cover the whole file you get a claimable content_hash.

For a large or unfamiliar file, outline=true is the cheap first read: one line per class/function as <line>: <signature>, and every number is an offset you can read next. An outline is a map, not the file, so it comes back as file_hash.

is_diff marks a unified diff and truncated marks a map. A binary file returns metadata instead of content; for images use read_image.

Inputs: path (required), limit, offset, outline, +3 more.

read_imageRead ImageA

Read an image file so the model can see it.

Returns an MCP image block (base64 data + mime type) plus a small JSON metadata sidecar (size, mime). Use this only when the model needs to view the image; for text or any other file type use read.

The format is detected from the file's magic bytes, not its extension, so a mis-named image still works and a non-image (e.g. text saved as .png) is rejected. Supports PNG, JPEG, GIF, TIFF, BMP, and WebP. Images are never cached — every call re-reads from disk. Oversized images are rejected before encoding; the cap is SCMCP_MAX_IMAGE_BYTES (default 5 MiB), bounded by Anthropic's ~5 MB upload limit.

Inputs: path (required).

statsStatsA

Report cache health, token savings, and runtime diagnostics.

Returns storage occupancy (files, tokens, documents, DB size), session and lifetime token savings and cache hit rates, per-tool call counts, and process memory. Use it to measure or debug — not as a routine step in read/edit loops. Takes no arguments.

Inputs: no named parameters.

warmWarmA

Index files into the cache so grep and search can see them, returning counts only.

Costs a few dozen tokens however many files it indexes: no content, no previews, no paths for the files that succeeded — just how many were indexed, how many were already current, and how many were not.

Anything not indexed is counted in skipped, and the first few come back under failures with a reason (not_found, not_a_file, binary, too_large, unreadable, timeout). If a cap stopped the walk early you get truncated or incomplete rather than a short count that looks complete.

Use it before searching an unfamiliar tree, then grep for the exact string or search for the concept, and read only what those name.

Inputs: paths (required), max_files.

writeWriteA

Create a file or replace its entire contents.

Use this for new files or full rewrites; for localized changes prefer edit or batch_edit. Status is created for a new path or updated for an existing one; an update reports diff_state, and includes the diff against the previous content only when you ask with show_diff. A dry_run writes nothing and says so: the status is would_create/would_update and dry_run: true comes back with it. Writing refreshes the cache so later reads, grep, and search see the new text.

A full write supplies the whole file, so the content_hash it returns is claimable. An append only adds a tail: pass known_hash to show you held the rest, or you get file_hash instead. auto_format reports file_hash too — the formatter's output is not what you sent.

Inputs: path (required), content (required), append, dry_run, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 14 tools

    Disambiguation4/5

    Tools are largely distinct: read vs batch_read (one vs many), edit vs batch_edit (one vs many), edit vs edit_preview (apply vs probe), search (BM25 concept) vs grep (exact/regex), read (text) vs read_image (images). The main soft spot is the discovery cluster (warm, glob, search, grep), which all deal with cached files, but the descriptions draw clear boundaries between indexing and searching.

    Naming Consistency4/5

    Names are consistently snake_case and mostly verb-led (read, write, edit, delete, search, warm, grep, clear), with predictable batch_ and edit_preview qualifiers. Minor deviations are the noun-style names stats and glob, which break the verb pattern but remain readable and unambiguous.

    Tool Count5/5

    14 tools sit comfortably in the well-scoped 3-15 range, and each earns its place by covering a distinct slice of file I/O plus cache management. No redundant or filler tools are present.

    Completeness4/5

    Core lifecycle is covered: create (write), read (read/batch_read), update (edit/batch_edit), delete, plus discovery (glob/grep/search/warm) and diagnostics (stats/clear). Gaps like directory creation, move/rename, and symlink operations are minor and workable, but agents needing those will hit dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI coding assistants with context optimization tools including targeted file analysis, intelligent terminal command execution with LLM-powered output extraction, and web research capabilities. Helps reduce token usage by extracting only relevant information instead of processing entire files and command outputs.
      5
      44 npm
      63
      TypeScript
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides intelligent code context and analysis through semantic compression, AST parsing, and multi-language support. Offers 60-80% token reduction while enabling AI assistants to understand codebases through local analysis, OpenAI-enhanced insights, and GitHub repository integration.
      6
      26 npm
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides file caching and diff tracking for AI coding agents, reducing token usage by returning changes or confirming no changes instead of full file contents on repeated reads.
      55 npm
      220
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI coding agents to query a pre-built semantic knowledge graph of code, reducing token usage and tool calls. Supports 16 tools for code exploration, analysis, and context building.
      24 npm
      9
      MIT