Llmcache

llmcache

别再为 Claude 已经在昨天理解过的同一份代码付费。

llmcache 是一个可缓存 AI 生成的源代码理解结果的 MCP 服务。Claude 只需读取每个文件一次，此后的每次会话都会从缓存的理解结果开始，从而为你节省 Token 和费用。

为什么重要

Claude Code 使用无状态 API。每一轮都会将完整的对话历史（包括 Claude 已读取的每个文件）重新作为输入 Token 发送。一个在第 1 轮读取的 1,000 Token 文件，在本次会话之后的每一轮都会让你付出 1,000 个输入 Token。

llmcache 会用一份 50 Token 的摘要替代这个 1,000 Token 的文件。每一轮都能为你节省 950 个 Token，而不只是一次。

此外，Claude 还会生成输出 Token 来处理每个文件。有了缓存摘要，Claude 就可以完全跳过这部分工作。输出 Token 的费用是输入 Token 的 5 倍。

Without llmcache:
  Turn 1: prompt + file.go (1,000 tokens)        > you pay for 1,000
  Turn 5: prompt + file.go still in history       > you pay for 1,000 again
  Turn 10: still carrying it                      > and again

With llmcache:
  Turn 1: prompt + summary (50 tokens)            > you pay for 50
  Turn 5: summary still in history                > you pay for 50
  Turn 10: still just 50 tokens                   > 95% smaller

前提条件

• Claude Code（唯一支持的客户端）
• Git（用于使缓存失效）
• 以下任一项：
  • Anthropic API 密钥（ANTHROPIC_API_KEY）
  • 已启用 Vertex AI API 的 GCP 项目，以及 gcloud auth application-default login

安装

下载适用于你平台的二进制文件：

# macOS (Apple Silicon)
curl -L -o llmcache https://github.com/sp98/llmcache-site/releases/latest/download/llmcache-darwin-arm64

# macOS (Intel)
curl -L -o llmcache https://github.com/sp98/llmcache-site/releases/latest/download/llmcache-darwin-amd64

# Linux (x86_64)
curl -L -o llmcache https://github.com/sp98/llmcache-site/releases/latest/download/llmcache-linux-amd64

chmod +x llmcache
sudo mv llmcache /usr/local/bin/

工作原理

1. Claude Code 调用 understand_file（通过 MCP），而不是 Read
2. llmcache 检查是否存在缓存摘要，且摘要是否仍然有效（Git 哈希匹配）
3. 缓存命中：返回精简摘要（通常比完整文件小 90% 以上）
4. 缓存未命中：调用 Claude Haiku 生成摘要，将其缓存后返回

文件的 Git 哈希发生变化时，摘要会自动失效。

设置

本地缓存存储在 SQLite 中。无需服务器，也无需许可证密钥。

1. 添加 MCP 服务

claude mcp add --transport stdio llmcache -- llmcache mcp

Vertex AI 用户请传入区域：

claude mcp add \
  --env CLOUD_ML_REGION=us-east5 \
  --transport stdio llmcache -- llmcache mcp

2. 添加 Read hook

此 hook 会指示 Claude 使用 understand_file，而不是直接读取源文件。将以下内容添加到 ~/.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "F=$(cat | grep -o '\"file_path\":\"[^\"]*\"' | head -1 | cut -d'\"' -f4); B=${F##*/}; E=${F##*.}; case \"$B\" in Makefile|makefile|GNUmakefile) echo '{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Use understand_file from llmcache instead.\"}';; *) case \"$E\" in go|py|js|ts|tsx|jsx|rs|java|c|cpp|cc|h|hpp|rb|sh|proto|sql|md) echo '{\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"Use understand_file or understand_package from llmcache instead.\"}';; esac;; esac"
          }
        ]
      }
    ]
  }
}

3. 添加 CLAUDE.md 指令

将以下内容附加到 ~/.claude/CLAUDE.md：

MANDATORY: ALWAYS use understand_file or understand_package from the
llmcache MCP server instead of Read to understand source files.
Only use Read when you need exact line numbers for editing.

4. 验证

重启 Claude Code，在某个项目中使用它，然后检查节省情况：

llmcache stats
llmcache stats --detail    # per-file breakdown
llmcache stats --monthly   # month-by-month

配置

可通过环境变量或 ~/.llmcache/config.yaml 设置可选配置：

环境变量	默认值	说明
LLMCACHE_DB	~/.llmcache/data.db	SQLite 数据库路径
LLMCACHE_LOG_DIR	~/.llmcache/	日志目录
LLMCACHE_SUMMARY_MODEL	claude-haiku-4-5@20251001	用于生成摘要的模型

团队模式（即将推出）

在单人模式下，每位开发者都要从头构建自己的缓存。当开发者 A 理解了某个文件后，开发者 B 仍需花费完整的 Token 来理解同一个文件。团队模式会共享摘要：一位开发者支付生成成本，其他人则可立即命中缓存。团队中的开发者越多，缓存预热得越快，节省也越多。

CLI 命令

命令	说明
llmcache mcp	启动 MCP 服务（由 Claude Code 自动启动）。
llmcache stats	显示缓存命中次数，以及节省的输入/输出 Token。使用 --detail 查看每个文件的明细，使用 --monthly 查看趋势。
llmcache index <repo>	为仓库预先建立索引，让首次会话就能使用已预热的缓存。使用 -w 10 设置并行工作线程，使用 --include "*.go" 进行筛选。
llmcache gc	移除过期摘要。使用 --max-age 720h 设置保留期限，使用 --dry-run 预览。

MCP 工具（由 Claude Code 自动使用）

工具	描述
understand_file	返回源文件的缓存摘要。如果文件已更改（git 哈希不匹配），则生成新的摘要。如果文件尚未提交，则提示 Claude 直接读取。
understand_package	汇总目录中的所有源文件，让 Claude 一次调用即可了解包级概况。
get_file_detail	从文件中提取特定函数或类型。Go 文件使用 Go AST，其他文件使用模式搜索。
list_summaries	列出仓库的所有缓存摘要，并显示命中次数和新鲜度。

问题与反馈

发现问题或有功能请求？在 GitHub 上提交 issue。