Code Cache

A lightweight, tree-sitter-backed code knowledge cache for AI agents — delivered as an MCP server.

轻量级代码知识缓存 MCP 服务，基于 tree-sitter 语法分析，专为 AI 编码助手设计。

---

Overview / 概述

AI agents repeatedly read source files to answer code questions — burning tokens every time. code-cache-mcp changes this: the agent queries the cache first, gets symbol positions + inheritance + call graph, and only reads the specific line range on a true miss.

Code structure is parsed once using tree-sitter and stored in SQLite. Only structure is persisted — symbol names, kinds, line ranges, inheritance edges, call graph. No raw source code is ever stored.

AI 助手反复读源文件查符号，每次都烧 token。code-cache-mcp 先查缓存：返回符号位置 + 继承关系 + 调用图，仅在 miss 时才按行范围精确读取。代码结构用 tree-sitter 一次解析存入 SQLite，仅存结构不存源码。

---

Features / 功能特性

• Symbol cache — classes, interfaces, enums, methods, functions, fields with line ranges
• Inheritance graph — extends / implements relationships, resolved lazily
• Call graph — method invocation edges (caller → callee)
• AI location memory — auto-persisted when query hits, instant retrieval in future sessions
• Auto-invalidation — FileWatcher detects file changes, re-parses automatically
• Cold-start auto-index — indexes cwd in background when cache is empty
• Multi-language — Java, TypeScript/JavaScript, Python, Go, Rust
• Zero infrastructure — single SQLite file, no server process
• Lightweight — 66MB node_modules (vs 389MB in v0.1), lazy WASM loading

---

MCP Tools / MCP 工具

v0.2 provides 3 tools (v0.1 had 8):

Tool	Description	Parameters
query_code_cache	FAST symbol lookup: file:line + hierarchy + call graph	symbol, file_path, kinds, include_relationships
store_code_context	Parse and cache a source file's structure	file_path, language
index_directory	Batch-index all source files in a directory	directory, force

query_code_cache auto-indexes on miss and retries — no manual setup needed. Cache hits automatically persist as AI locations for future sessions.

query_code_cache 在 miss 时自动索引并重试——无需手动 setup。命中自动存储为 AI location，供后续会话直接命中。

---

Supported Languages / 支持语言

Language	Extension
Java	.java
TypeScript / TSX	.ts .tsx
JavaScript / JSX	.js .mjs .jsx
Python	.py
Go	.go
Rust	.rs

---

Setup / 安装配置

Prerequisites / 前提条件

• Node.js ≥ 18

Install / 安装

cd /path/to/code-cache-mcp
npm install

Register with Claude Code / 注册到 Claude Code

claude mcp add code-cache-mcp npx tsx "$(pwd)/packages/server/src/index.ts"

Or add manually to ~/.claude.json under mcpServers:

"code-cache-mcp": {
  "type": "stdio",
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/code-cache-mcp/packages/server/src/index.ts"]
}

Environment Variables / 环境变量

Variable	Default	Description
CODE_CACHE_DIR	.code-cache	Directory for the SQLite database

---

Architecture / 架构

code-cache-mcp/
├── packages/
│   ├── sdk/                  # Core library (no MCP dependency)
│   │   └── src/
│   │       ├── types.ts      # Shared interfaces
│   │       ├── db.ts         # SQLite schema + queries
│   │       ├── code-cache.ts # CodeCacheStore — orchestrator
│   │       ├── parser-*.ts   # Language-specific parsers
│   │       ├── parser-registry.ts  # Lazy language dispatcher
│   │       └── watcher.ts    # FileWatcher (debounced fs.watch)
│   ├── server/               # MCP server entry point
│   │   └── src/
│   │       ├── index.ts      # CLI entry
│   │       └── mcp.ts        # 3 tool registrations
│   └── wasm/                 # tree-sitter WASM grammar binaries

Database schema / 数据库结构

Table	Contents
file_versions	File path, hash, language, line count
symbols	Every class / method / field with line range
class_relationships	Inheritance / implementation edges
call_edges	Method invocation graph
ai_locations	Auto-persisted AI query hits with reason
stats	Global cache hit/miss counters, tokens saved

---

v0.2 Changes from v0.1 / v0.2 相比 v0.1 的变化

Metric	v0.1	v0.2	Change
MCP tools	8	3	-62%
query parameters	11	4	-64%
node_modules	389MB	66MB	-83%
mcp.ts lines	783	~290	-64%
DB tables	10	6	-40%
Dependencies	~200+	~102	-50%

Removed in v0.2

• Semantic search (@xenova/transformers, 45MB + 23MB model cache)
• TokenTracker (@anthropic-ai/sdk)
• PostgreSQL metrics (pg dual-write)
• Cross-session query history (SHA-256 hashing, diff computation)
• Code snippet similarity (Jaccard token matching, unified diff)
• Session dedup cache and session stats table
• AST nodes table and include_ast parameter
• 5 MCP tools: cache_hotness, invalidate_cache, store_ai_location, get_ai_locations, cache_clear
• report.ts and claude-log-reader.ts

---

Tech Stack / 技术栈

Component	Technology
Language	TypeScript (ESM)
Runtime	Node.js + npx tsx
Database	SQLite via @tursodatabase/database (libSQL)
Code parsing	web-tree-sitter + language WASM grammars (lazy)
MCP SDK	@modelcontextprotocol/sdk
Validation	zod

---

Guiding AI to Use the Cache / 引导 AI 使用缓存

AI agents default to Read / grep / LSP because they're familiar. To increase adoption:

1. SessionStart hook — Add to ~/.claude/settings.json:

"SessionStart": [{ "hooks": [{ "type": "command", "command": "cat ~/.claude/code-cache-hint.txt" }] }]

Create ~/.claude/code-cache-hint.txt:

When navigating code, prefer query_code_cache over Read/grep for symbol lookups. It returns file:line positions, inheritance, and call graph — faster than reading whole files. After reading a source file, call store_code_context to cache it.

2. Cold-start auto-index — Built-in. When cache is empty, indexes cwd in background automatically.

3. Teaching tip — Built-in. Cache hits include: "tip": "3 symbols found via cache. Use Read with offset/limit for the specific line ranges above."

4. CLAUDE.md — Add to project root:

## Code Navigation
- Use `query_code_cache` BEFORE `Read` to find symbols. Returns file:line + hierarchy + call graph.
- After `Read` on a source file, call `store_code_context` to build cache.

---

License / 许可证

MIT