Codemesh

问题所在

AI 编码 Agent 有 40–80% 的 token 浪费在探索上——在文件中搜索、读取无关代码，以及重新构建之前会话中已经了解的上下文。

在包含 600 个文件的代码库中，Agent 执行一项典型的探索任务时，往往要先读取 10 多个文件，才能知道哪些内容相关。

Before:  Agent → Grep → 50 matches → Read 10 files → Understand → Work
After:   Agent → codemesh_map → expand chosen branches → read exact symbols → Work

Codemesh 是一个 MCP 服务，为 Agent 提供持久、可查询的知识图谱。图谱会随着时间推移变得更智能：Agent 将学到的内容写回图谱，让下一个会话一开始就掌握相关信息。

基准测试

使用 Claude Sonnet 4.6，在 6 个真实代码库（Alamofire、Excalidraw、VS Code、Swift Compiler、pydantic-validators、pydantic-basemodel）上进行基准测试，并与基准方案和基于图谱的上下文方案进行比较。

完整的方法说明、各仓库细分结果和两两比较：docs/benchmark-results.md | 早期 pydantic 评估

这些历史测试使用的是早期的答案优先工作流。下文所述的地图优先导航工作流在一项探索性 Pydantic 试点测试中进行了评估；本节中的数字 不应被视为该工作流的实测表现。

成本

耗时

工具调用（Agent 轮次）

质量（1–10 分，由大模型评判）

成本节省：Codemesh MCP 与基线的对比

说明

Codemesh MCP 在所有受测模式中成本最低、速度最快——在 6 个仓库中平均比基线便宜 71%、快 72%，且工具调用次数减少 82%（8 次对比 45 次）。质量与基线相当（7.9 对比 7.0）；Codegraph 的质量略胜 Codemesh（8.4），但成本约为其两倍（$0.45 对比 $0.22）。所有仓库都实现了成本和时间节省——包括理解类查询（Excalidraw、pydantic-basemodel），这些查询在 codemesh 的早期构建版本中表现退步。

快速开始

1. 安装

npm install -g @pyalwin/codemesh

也可以直接运行，无需安装：

npx -y @pyalwin/codemesh --help

git clone https://github.com/pyalwin/codemesh.git
cd codemesh
npm install && npm run build
npm link

验证安装：codemesh --version 应输出软件包版本。

2. 为项目建立索引

cd /your/project
codemesh index

默认的索引和检索路径会在 .codemesh/ 中使用一个 SQLite 数据库。 它不会生成嵌入向量，也不需要向量数据库。较早运行生成的现有向量 工件会保留，但此路径不会使用它们。

Indexed 656 files
  Symbols found:  16733
  Edges created:  33266
  Duration:       10009ms
  PageRank:       13843 nodes scored

3. 选择模式

Codemesh 提供两种与 AI Agent 集成的方式：

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

export CODEMESH_PROJECT_ROOT=/path/to/your/project

# Navigate one level at a time, then read a selected symbol:
codemesh explore map
codemesh explore map --node 'dir:src'
codemesh explore map --node 'file:src/server.ts'
codemesh explore source 'symbol:src/server.ts:createServer'
codemesh explore source 'symbol:src/server.ts:createServer' --mode preview
codemesh explore inspect 'symbol:src/server.ts:createServer' --depth 1 --max-symbols 4 --compact
codemesh explore hydrate --references '[{"id":"symbol:src/server.ts:createServer","bodyHash":"HASH"}]' --compact

# Other exploration commands:
codemesh explore search "request flow"
codemesh explore context Source/Core/Session.swift Source/Core/Request.swift
codemesh explore trace Session.request --depth 5
codemesh explore recall --path src/server.ts
codemesh remember --path src/server.ts --summary "Server tool registration" --session my-task

4. 使用

Agent 可以先沿着持久化图谱选择路径，再阅读代码：

You: "Find how pydantic handles validation"

Agent calls: codemesh_map({})
       gets: immediate repository directories and files, each with an ID

Agent calls: codemesh_map({ node: "dir:pydantic" })
       gets: immediate files and subdirectories

Agent calls: codemesh_map({ node: "file:pydantic/main.py" })
       gets: top-level symbols, including BaseModel

Agent calls: codemesh_map({ node: "symbol:pydantic/main.py:BaseModel" })
       gets: methods, including model_validate

Agent calls: codemesh_source({ id: "symbol:pydantic/main.py:BaseModel.model_validate" })
       reads: only the selected symbol's source

Agent calls: codemesh_enrich({ path: "pydantic/functional_validators.py",
               summary: "Primary V2 validator API..." })
       saves: summary for next session

客户端集成

Codemesh 支持 Model Context Protocol，因此任何兼容 MCP 的客户端都可以使用它。粘贴下面的某个代码片段，然后重启客户端，codemesh_* 工具就会出现在 Agent 的工具箱中。

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@pyalwin/codemesh"],
          "env": {
            "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
          }
        }
      }
    ]
  }
}

Agent 写回：让图谱不断变得更智能

其他代码智能工具通常只会为你的代码库建立一次索引，然后向 Agent 提供只读视图。Codemesh 让 Agent 在工作过程中为图谱提供知识——摘要、工作流和跨概念链接会在不同会话间持久保存，并在重新索引后保留。

// Session 1 — agent reads unfamiliar code, then writes back what it learned.
codemesh_enrich({
  path: "pydantic/functional_validators.py",
  summary: "Primary V2 validator API. `@field_validator` wraps "
         + "`_decorators.FieldValidatorDecoratorInfo`; `mode='before'|'after'` "
         + "toggles pre/post-coercion execution. Extends BaseValidator.",
  sessionId: "validation-investigation-1"
})

// Session 1 — agent traces a multi-file flow, records the path.
codemesh_workflow({
  name: "pydantic field validation",
  description: "Request → BaseModel.__init__ → SchemaValidator → field_validator",
  files: [
    "pydantic/main.py",
    "pydantic/_internal/_model_construction.py",
    "pydantic/functional_validators.py"
  ]
})

// Session 2 (days later) — another agent navigates the same indexed code.
codemesh_map({ node: "file:pydantic/functional_validators.py" })
// → returns stable symbol IDs without reading their bodies.
codemesh_explore({ action: "context", path: "pydantic/functional_validators.py" })
// → includes the earlier agent's concept alongside indexed relationships.

现在，图谱了解了静态分析器无法推断的信息：文件为何重要、哪些文件会一起变动，以及维护者如何称呼某个概念。重新索引会重建结构层（文件、符号、导入、调用），但会保留所有增强信息——只有引用的文件发生变化时，条目才会过时。

参见 MCP 工具中的 codemesh_enrich 和 codemesh_workflow。

工作原理

                      ┌──────────────────────────────────┐
                      │         Knowledge Graph           │
                      │                                   │
                      │  ┌──────────┐ ┌───────────────┐  │
                      │  │Structural│ │   Semantic     │  │
                      │  │  (auto)  │ │   (agents)    │  │
                      │  │          │ │               │  │
                      │  │ files    │ │ summaries     │  │
                      │  │ symbols  │ │ workflows     │  │
                      │  │ imports  │ │ concepts      │  │
                      │  │ calls    │ │ enrichments   │  │
                      │  └──────────┘ └───────────────┘  │
                      │                                   │
                      │  ┌──────────┐ ┌───────────────┐  │
                      │  │   Git    │ │   Search      │  │
                      │  │  Intel   │ │               │  │
                      │  │          │ │ FTS5 (exact)  │  │
                      │  │ hotspots │ │ Trigram (fuzzy)│  │
                      │  │ co-change│ │ notes + cache │  │
                      │  │ churn    │ │ PageRank      │  │
                      │  └──────────┘ └───────────────┘  │
                      │                                   │
                      │          SQLite only              │
                      └────────────┬──────────────────────┘
                                   │
                      ┌────────────┴──────────────────────┐
                      │    MCP Server / CLI (shared core)  │
                      │                                    │
                      │  map · source · answer · explore    │
                      │  trace · recall · enrich · workflow │
                      │  status                            │
                      └────────────────────────────────────┘

结构层（自动构建）——Tree-sitter 会将你的代码解析为文件、符号（函数、类、方法）和关系（导入、调用、继承）。每次建立索引时都会重建。

语义层（由 Agent 构建）——Agent 在处理你的代码时，会写回摘要和工作流路径。这些内容会在重新索引后保留，并在不同会话间累积。引用的文件发生变化时，相关内容会失效。

MCP 工具

命令行

codemesh index                          # structural + git intel + pagerank
codemesh rebuild                        # force re-index; preserves saved knowledge
codemesh status                         # graph statistics

codemesh explore map                    # repository root
codemesh explore map --node 'dir:src'   # expand one branch
codemesh explore map --node 'symbol:src/auth.ts:login' --relation calls
codemesh explore source 'symbol:src/auth.ts:login'
codemesh explore source 'symbol:src/auth.ts:login' --if-hash HASH  # unchanged reference if bytes match
codemesh explore source 'symbol:src/auth.ts:login' --force         # rehydrate exact source
codemesh explore inspect 'symbol:src/auth.ts:login' --depth 1 --compact
codemesh explore hydrate --references '[{"id":"symbol:src/auth.ts:login","bodyHash":"HASH"}]' --compact
codemesh explore answer "question"      # optional ranked context assembly
codemesh explore search "query"         # SQLite FTS5 + trigram
codemesh explore search get_default --path pydantic --scope symbols --max-bytes 4096
codemesh explore inspect 'symbol:src/auth.py:login' --direction both --max-candidates 16
codemesh explore recall --path file     # prior notes with freshness
codemesh explore context file1 file2    # multi-target context
codemesh explore trace symbol --depth 5 # follow call chains
codemesh explore impact file            # reverse dependencies
codemesh remember --path file --summary "note" --session task-id
codemesh workflow --name flow --description "flow description" --file first.ts --file second.ts
codemesh explore search "query" --compact  # 8 candidates with IDs and match reasons
codemesh explore source 'symbol:src/auth.ts:login' --mode full --compact
codemesh explore source 'symbol:src/auth.ts:login' --mode auto --compact
rg -n 'login' src | codemesh adapt search  # reversible fold when smaller
cat src/auth.ts | codemesh adapt read --path src/auth.ts --intent navigate

--compact 可用于 map、search、source、recall、inspect 和 hydrate。它会从命令行 JSON 中移除重复的元数据；source 仍会包含请求的精确代码和内容哈希。导航映射、搜索、inspect 和 hydrate 会输出有界 JSON，不进行美化排版；其精简形式会保留精确源代码和新鲜度哈希。hydrate 还接受 --references-file PATH，用于指定保存在磁盘上的 JSON 数组。 有界响应会省略额外的项目根目录包装，以确保最终 JSON 不超出请求的预算。其他命令仍沿用现有响应格式。

交接时，请保存新鲜 source 结果中的符号精确 ID 和 bodyHash。codemesh_hydrate 会在返回完整代码前，将该哈希与实时源代码进行校验。如果已保存的 hash 来自 fold 或 preview，请包含其 mode；该哈希只校验渲染后的视图，因此还需包含 bodyHash 才能验证整个符号。达到预算限制时，Inspect 和 hydrate 会明确报告省略的代码块。两者默认最多返回 4 个源代码块，JSON 响应预算为 24 KiB。inspect 最多跟踪一跳，并保守地解析本地 Python 函数和导入。使用 --direction incoming 或 both 也可检查候选调用方；--max-candidates 限制调用方验证数量（默认值为 32，最大值为 128）。索引边仅供参考：每个返回的调用方都会根据其当前 Python 绑定进行检查。如果缺少边，传入方向的发现结果会明确标注为不完整；结果为空并不能证明某个符号没有调用方。动态接收方、名称歧义和不确定的绑定会明确标记为未解析；其他语言则会提供未经验证的图候选项。这些是静态绑定，并不保证运行时行为。Hydration 返回经过实时校验的代码；客户端决定在交接后何时调用它，以及在其模型上下文中保留哪些证据。 --mode auto 是一种显式导航视图：长度不超过 120 行且大小不超过 12KiB 的符号会完整返回；更大的符号会返回有界预览，标出省略的范围，并提示映射其成员。显式指定 --mode full 时始终返回精确源码。 搜索会优先排列精确标识符以及精确限定名称／叶名称，其次考虑查询词覆盖率和词法相关性，仅在平局时使用热门度作为决胜依据。 若要选择性启用结构提示，--exact-tie-break path-depth 会在排名相同的精确名称／叶名称匹配项中，优先选择路径较浅的项，再以热门度作为决胜依据。MCP 在 codemesh_explore 上提供相同的 exactTieBreak 选项。 显式 ID 和路径过滤器仍可选择更深层的实现；深度并不能决定哪个实现是规范实现。默认值仍为 pagerank。 --path 会在 SQLite 结果上限生效前，将候选项限制在某个文件或目录内；src 不会匹配 src-other。精简搜索包含签名和范围。 搜索和导航的 JSON 预算默认为 8192 字节；--max-bytes 接受 512..65536。省略的结果会明确标出。导航游标始终指向第一个未返回的条目；如果仅该条目就超出预算，请增大 --max-bytes 并重用该游标。源码仍需通过 source／inspect 获取。

确定性 Graphify 后续方案介绍了单 Agent 设计和聚焦上下文策略。上下文替换由框架负责：MCP／CLI 工具无法移除客户端先前发送的消息。受控的下一轮迭代介绍了精简的评估指令、可选的搜索排序，以及两个多文件交接测试样例。

源码检索也接受唯一的符号名称，例如 MyType.myMethod。 遇到名称不明确时，会返回精确的候选 ID 和范围；绝不会根据大小猜测重载。跨会话引用时，仍应优先使用精确 ID。 adapt 从标准输入读取原生工具观测结果。搜索折叠会保留每个匹配项，并在不支持的格式下回退。读取大纲要求内容与新近索引的文件完全按字节匹配，且明确指定导航意图；编辑读取和部分读取则保持原样传递。--json 会报告路由和原因，而不是只输出转换后的观测结果。

可选：Hooks 和技能

# Install the skill so Claude Code loads the workflow automatically
cp /path/to/codemesh/skills/codemesh.md /your/project/.claude/skills/

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "/path/to/codemesh/hooks/pre-read.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Read",
      "hooks": [{
        "type": "command",
        "command": "/path/to/codemesh/hooks/post-read.sh"
      }]
    }]
  }
}

支持的语言

任何具有 tree-sitter 语法的语言都可以添加。

图数据模型

节点

边

架构

codemesh/
├── src/
│   ├── index.ts              # MCP server entry (stdio transport)
│   ├── server.ts             # Tool registration (zod schemas)
│   ├── graph/
│   │   ├── types.ts          # Node/edge type definitions
│   │   ├── storage.ts        # StorageBackend interface (swappable)
│   │   └── sqlite.ts         # SQLite + FTS5 implementation
│   ├── indexer/
│   │   ├── indexer.ts        # File walking, hashing, incremental indexing
│   │   ├── parser.ts         # Tree-sitter AST extraction
│   │   └── languages.ts      # Language registry (ext → grammar)
│   ├── tools/                # 6 MCP tool handlers
│   └── cli.ts                # CLI entry point
├── skills/codemesh.md        # Agent education skill
├── hooks/                    # Pre/post read hooks
└── eval/                     # Eval framework (5 tasks, 3 models)

存储与后端无关。StorageBackend 接口抽象了所有持久化操作。v1 使用 SQLite 和 FTS5，实现零依赖的本地运行。该接口支持切换到 Memgraph、Neo4j 或其他图数据库。

评测框架

可复现的评测工具，使用 LLM-as-judge 评分：

# Setup
npm install -g @pyalwin/codemesh
git clone --depth 1 https://github.com/Alamofire/Alamofire.git /tmp/alamofire
# ... clone other repos ...

# Index
CODEMESH_PROJECT_ROOT=/tmp/alamofire codemesh index

# Run benchmarks
python3 eval/head_to_head.py --model sonnet alamofire excalidraw vscode swift-compiler

完整的方法和结果请参见 docs/benchmark-results.md。早期的 pydantic 评测已归档在 docs/experiments/。

仅使用 SQLite 的 CLI 还有一套独立的 vNext 契约与 Agent 工作流评测，基于固定版本的 Pydantic 代码库。其正确性检查及模型成本/质量对比与历史基准测试分开报告。 vNext Pydantic 结果记录了首轮完整配对运行。

与现有工具对比

开发

bun install          # Install dependencies
bun run build        # Compile TypeScript
bun run test         # Run 102 tests
bun run dev          # Watch mode
bun run lint         # Type check

贡献

欢迎贡献。可改进的方面：

• 更多语言 — 添加 tree-sitter 语法和特定语言的提取器
• AST 差异失效 — 按函数而非按文件检测过时内容
• 图后端 — 为 StorageBackend 添加 Memgraph/Neo4j 适配器
• 语义搜索 — 在 FTS5 之外添加嵌入列
• Agent 采用 — 改进模式，让 Agent 自然地优先使用图工具

许可证

MIT