Semantic Cache MCP

Semantic Cache MCP

别再为同一个文件重复付费。
面向 AI 编码 Agent 的 MCP 文件缓存：重新读取一次约需 40 个 token，而不是整个文件。

 

---

编码 Agent 会反复读取相同的文件：编辑前、编辑后，以及每次上下文压缩后。内置的 Read 每次都会发送整个文件。Semantic Cache MCP 知道 Agent 已经持有哪些内容。对一个含 7,891 个 token 的文件进行测量：

读取	内置 Read	Semantic Cache MCP
首次读取	7,891 个 token	完整文件，另加一个哈希值
重新读取，文件未变	7,891 个 token	77 个 token
修改一行后重新读取	7,891 个 token	137 个 token（差异内容）

在一个包含 48 个文件的项目中，重新读取的 token 可减少 98.7%，读取未变文件耗时 0.17 ms。它还为 Agent 提供针对缓存的 grep、BM25 搜索和 glob、支持 dry_run 的原子编辑，以及按 token 预算读取的批量操作。仅有三个运行时依赖，无需 API 密钥或 GPU。

快速开始

你需要安装 uv。在 Claude Code 中：

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

其他客户端（Cursor、Claude Desktop，以及其他支持 mcpServers JSON 的客户端）：

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

VS Code、Codex 和 OpenCode 的配置，以及如何关闭内置文件工具以便 Agent 使用缓存：docs/clients.md。

工作原理

服务发送的每个文件都附带一个 content_hash。Agent 会在下一次读取时将其作为 known_hash 传回：

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"]

• 不会返回过时内容。 每次读取前都会先检查磁盘上的文件。只有哈希值与当前字节内容一致时，才会返回 unchanged。
• 忘记内容也安全。 上下文压缩后，Agent 不带哈希值读取，就会重新获得完整文件。
• 大文件会转换为索引。 超过 max_size 的文件会返回其定义的概要，而不是盲目截断。
• 所有内容都保留在本地。 缓存是一个 SQLite 文件。一个后台守护进程即可为你机器上的所有客户端提供服务。

工具

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

参数和示例：docs/tools.md。

常见问题

搜索在嵌入意义上是“语义搜索”吗？ 不是。search 使用 BM25 关键词排序，grep 则进行精确匹配。无需下载模型、无需 GPU，也无需 API 密钥。

它会把我的代码发送到别处吗？ 不会。唯一的网络请求是一次性下载 o200k 分词器文件，并通过 SHA-256 哈希值进行校验。

它能在 Windows 上运行吗？ 可以。CI 在 Linux 和 macOS 上运行。

文档

指南	内容
客户端	各客户端的设置、关闭内置文件工具
工具	所有工具及其参数和示例
环境变量	所有设置及其默认值
性能	基准测试和方法
架构	存储、算法、共享守护进程
安全	威胁模型、大小限制、路径处理
故障排除	常见问题、调试日志
高级用法	Python API

贡献

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

请参阅 CONTRIBUTING.md。欢迎提交问题和拉取请求。

许可证

MIT。