Codemesh

MCP开发工具

提供方 pyalwin · 包名 @pyalwin/codemesh

开发工具 stdio · 本地进程 会话登录 社区 / 第三方 Claude DesktopClaudeCursorVS Code
查看接入方式

Intelligent code knowledge graph for AI coding agents. Gives agents a persistent, queryable knowledge graph with search, call tracing, and agent write-back. 71% cheaper, 72%

一句话选型结论

按资料字段整理

Codemesh 属于开发工具类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude Desktop、Claude、Cursor 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

grep read knowledge graph code search

支持客户端

适用场景

grepreadknowledge graph

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
npx -y @pyalwin/codemesh

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Cross-platform,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Codemesh当前 未标注 stdio · 本地进程 本地部署 有 未标注
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方pyalwin上游标注的维护方 pyalwin
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时@pyalwin/codemesh · Cross-platform本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验未标注上游最后核验时间

详细介绍

27.9 KB
来自项目仓库与上游目录的原文,未做删改

Codemesh

Intelligent code knowledge graph for AI coding agents

71% cheaper, 72% faster, 82% fewer tool calls vs baseline Grep+Read\
on 6 real-world repos (Sonnet 4.6) — from a single codemesh index.


The Problem

AI coding agents waste 40-80% of their tokens on discovery — grepping through files, reading irrelevant code, and rebuilding context they've already seen in previous sessions.

On a 600-file codebase, a typical exploration task involves 10+ file reads before the agent even knows what's relevant.```
Before: Agent → Grep → 50 matches → Read 10 files → Understand → Work
After: Agent → codemesh_map → expand chosen branches → read exact symbols → Work


Codemesh is an MCP server that gives agents a persistent, queryable knowledge graph. The graph gets smarter over time: agents write back what they learn, so the next session starts informed.

---

## Benchmarks

Benchmarked on 6 real-world codebases (Alamofire, Excalidraw, VS Code, Swift Compiler, pydantic-validators, pydantic-basemodel) with Claude Sonnet 4.6, compared alongside baseline and graph-based approaches for context.

Full methodology, per-repo breakdowns, and pairwise comparisons: `docs/benchmark-results.md` | Early pydantic evals

These historical runs used the earlier answer-first workflow. The map-first
navigation workflow described below is evaluated in an exploratory
Pydantic pilot; the figures in this
section should not be read as its measured performance.

### Cost

| Mode | Alamofire | Excalidraw | VS Code | Swift Compiler[^swift] | pydantic-validators | pydantic-basemodel | **Avg** |
|---|---:|---:|---:|---:|---:|---:|---:|
| Baseline | $0.54 | $0.89 | $0.21 | $0.83 | $1.32 | $0.78 | $0.76 |
| **Codemesh MCP** | **$0.25** | **$0.21** | **$0.16** | **$0.23** | **$0.33** | **$0.13** | **$0.22** |
| Codemesh CLI | $0.67 | $0.51 | $0.16 | $0.83 | $1.00 | $0.18 | $0.56 |
| Codegraph | $0.37 | $0.56 | $0.57 | $0.74 | $0.29 | $0.19 | $0.45 |

### Time

| Mode | Alamofire | Excalidraw | VS Code | Swift[^swift] | pydantic-v | pydantic-b | **Avg** |
|---|---:|---:|---:|---:|---:|---:|---:|
| Baseline | 180s | 191s | 87s | 199s | 352s | 232s | 207s |
| **Codemesh MCP** | **78s** | **45s** | **35s** | **87s** | **72s** | **32s** | **58s** |
| Codemesh CLI | 226s | 177s | 62s | 227s | 235s | 51s | 163s |
| Codegraph | 134s | 180s | 192s | 199s | 75s | 60s | 140s |

### Tool calls (agent turns)

| Mode | Alamofire | Excalidraw | VS Code | Swift[^swift] | pydantic-v | pydantic-b | **Avg** |
|---|---:|---:|---:|---:|---:|---:|---:|
| Baseline | 31 | 48 | 12 | 29 | 84 | 65 | 45 |
| **Codemesh MCP** | **9** | **5** | **3** | **14** | **14** | **3** | **8** |
| Codemesh CLI | 30 | 32 | 12 | 56 | 64 | 9 | 34 |
| Codegraph | 31 | 35 | 44 | 44 | 20 | 12 | 31 |

### Quality (1–10, LLM-as-judge)

| Mode | Alamofire[^alamo] | Excalidraw | VS Code | Swift Compiler | pydantic-validators | pydantic-basemodel | **Avg** |
|---|---:|---:|---:|---:|---:|---:|---:|
| Baseline | n/a | 9 | 8 | 7 | 2 | 9 | 7.0 |
| **Codemesh MCP** | 9 | 9 | 7 | 8 | 7 | 7.8 | **7.9** |
| Codemesh CLI | 9 | 7 | 7 | 9 | 1 | 8.4 | 6.9 |
| Codegraph | 8 | 9 | 8.7 | 8 | 8 | 9 | **8.4** |

### Cost savings: Codemesh MCP vs Baseline

| Repo | Baseline | Codemesh MCP | **Cost saved** | **Time saved** |
|---|---:|---:|---:|---:|
| Alamofire | $0.54 | $0.25 | **−54%** | **−57%** (180s → 78s) |
| Excalidraw | $0.89 | $0.21 | **−76%** | **−76%** (191s → 45s) |
| VS Code | $0.21 | $0.16 | **−24%** | **−60%** (87s → 35s) |
| Swift Compiler[^swift] | $0.83 | $0.23 | **−72%** | **−56%** (199s → 87s) |
| pydantic-validators | $1.32 | $0.33 | **−75%** | **−79%** (352s → 72s) |
| pydantic-basemodel | $0.78 | $0.13 | **−83%** | **−86%** (232s → 32s) |
| **Average** | **$0.76** | **$0.22** | **−71%** | **−72%** |

> [!NOTE]
> **Codemesh MCP** achieves the lowest cost and fastest time of any mode tested — **71% cheaper and 72% faster than baseline** on average across 6 repos, using **82% fewer tool calls** (8 vs 45). Quality is comparable to baseline (7.9 vs 7.0); Codegraph edges Codemesh on quality (8.4) but at roughly double the cost ($0.45 vs $0.22). Every repo shows cost and time savings — including the comprehension-heavy queries (Excalidraw, pydantic-basemodel) that regressed in prior builds of codemesh.

---

## Quick Start

### 1. Install```bash
npm install -g @pyalwin/codemesh

Or run directly without installing:```bash
npx -y @pyalwin/codemesh --help


Build from source```bash
git clone https://github.com/pyalwin/codemesh.git
cd codemesh
npm install && npm run build
npm link

> Verify the install: codemesh --version should print the package version.

2. Index your project```bash

cd /your/project
codemesh index


The default index and retrieval path uses one SQLite database in `.codemesh/`.
It does not generate embeddings or require a vector database. Existing vector
artifacts from older runs are left untouched but are not used by this path.```
Indexed 656 files
  Symbols found:  16733
  Edges created:  33266
  Duration:       10009ms
  PageRank:       13843 nodes scored

3. Choose your mode

Codemesh offers two ways to integrate with AI agents:

Option A: MCP Server (structured tool calls)

Add to your Claude Code MCP config (~/.claude/mcp-servers.json or project .mcp.json):```json
{
"mcpServers": {
"codemesh": {
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "/path/to/your/project"
}
}
}
}


The agent gets native MCP tools:

- `codemesh_map` — browse one level of the indexed repository or follow a link
- `codemesh_source` — read a revision-checked source view by symbol ID; `ifHash` avoids repeat delivery
- `codemesh_inspect` — inspect an exact symbol and its direct calls with bounded, exact source blocks
- `codemesh_hydrate` — verify saved symbol references and reopen exact source after a handoff
- `codemesh_answer` — optional ranked context assembly
- `codemesh_explore` — search, context (multi-target), impact
- `codemesh_trace` — follow call chains
- `codemesh_enrich` / `codemesh_workflow` — write back
- `codemesh_recall` — retrieve notes and workflows with freshness status
- `codemesh_status` — health check

**Best for:** Opus, structured workflows, enrichment/write-back

Option B: CLI Mode (via Bash — zero MCP overhead)

No MCP config needed. The agent calls codemesh directly via Bash:```bash
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

Exploration and write commands return JSON to stdout. No MCP server process is required.

Best for: Sonnet/Haiku, speed-sensitive workflows, simpler setup

Which mode should I use?

MCP Server CLI Mode
Setup MCP config file Just export CODEMESH_PROJECT_ROOT
Invocation Persistent MCP process CLI subprocess
Enrichment Native codemesh_enrich tool codemesh remember ...
Retrieval Shared SQLite-backed handlers Same handlers and JSON data
Recommended Hosts with reliable MCP tool use Deterministic shell workflows

4. Use it

The agent can choose a path through the persistent graph before reading code:```
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


---

## Client Integrations

Codemesh speaks the Model Context Protocol, so any MCP-compatible client can use it. Paste one of the snippets below, restart the client, and the `codemesh_*` tools show up in the agent's toolbox.

Claude Code (CLI)

Add to `~/.claude/mcp-servers.json` (user-wide) or `.mcp.json` (project-local):```json
{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}

Claude Desktop (macOS / Windows app)

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: `%APPDATA%\Claude\claude_desktop_config.json````json
    {
    "mcpServers": {
    "codemesh": {
    "command": "npx",
    "args": ["-y", "@pyalwin/codemesh"],
    "env": {
    "CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
    }
    }
    }
    }

Restart Claude Desktop. Codemesh's tools will appear in the tool picker (hammer icon).

Cursor — stop the agent from wandering your codebase

Cursor reads `.cursor/mcp.json` per project (or `~/.cursor/mcp.json` for all projects):```json
{
  "mcpServers": {
    "codemesh": {
      "command": "npx",
      "args": ["-y", "@pyalwin/codemesh"],
      "env": {
        "CODEMESH_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Open Settings → MCP, confirm codemesh is green, then mention it in a prompt (@codemesh how does auth work?) to nudge the agent toward graph queries instead of recursive Grep.

Windsurf / VS Code (Continue)

Add to ~/.continue/config.json under experimental.modelContextProtocolServers:```json
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@pyalwin/codemesh"],
"env": {
"CODEMESH_PROJECT_ROOT": "/absolute/path/to/your/project"
}
}
}
]
}
}


---

## Agent Write-Back: the graph that gets smarter

Every other code-intelligence tool indexes your repo once and hands the agent a read-only view. Codemesh lets the agent **teach the graph** as it works — summaries, workflows, and cross-concept links persist across sessions and survive re-indexing.```ts
// 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.

The graph now knows things no static analyzer could infer: why a file matters, which files move together, what a maintainer called a concept. Re-indexing rebuilds the structural layer (files, symbols, imports, calls) but preserves every enrichment — entries only go stale when their referenced files change.

See codemesh_enrich and codemesh_workflow under MCP Tools.


How It Works```

                  ┌──────────────────────────────────┐
                  │         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                            │
                  └────────────────────────────────────┘

**Structural layer** (automatic) — Tree-sitter parses your code into files, symbols (functions, classes, methods), and relationships (imports, calls, extends). Rebuilt on each index.

**Semantic layer** (agent-built) — As agents work with your code, they write back summaries and workflow paths. These survive re-indexing and accumulate across sessions. Invalidated when referenced files change.

---

## MCP Tools

| Tool | Purpose | Example |
|---|---|---|
| `codemesh_map` | Bounded, one-level navigation through directories, files, symbols, and graph links | `codemesh_map({ node: "dir:src", limit: 30 })` |
| `codemesh_source` | Exact source for a selected symbol ID | `codemesh_source({ id: "symbol:src/auth.ts:login" })` |
| `codemesh_inspect` | Exact source for a symbol plus direct call evidence, within a byte and symbol budget | `codemesh_inspect({ id: "symbol:src/auth.ts:login", depth: 1 })` |
| `codemesh_hydrate` | Verify saved symbol references and reopen exact source after context loss | `codemesh_hydrate({ references: [{ id: "symbol:src/auth.ts:login", bodyHash: "..." }] })` |
| `codemesh_answer` | Optional ranked context assembly with source snippets | `codemesh_answer({ question: "How does auth work?" })` |
| `codemesh_explore` | Search, context (multi-target), impact analysis | `codemesh_explore({ action: "search", query: "auth" })` |
| `codemesh_trace` | Follow call chains with source code | `codemesh_trace({ symbol: "login", depth: 5 })` |
| `codemesh_enrich` | Write back what you learned for future sessions | `codemesh_enrich({ path: "src/auth.py", summary: "..." })` |
| `codemesh_workflow` | Record multi-file workflow paths | `codemesh_workflow({ name: "login flow", files: [...] })` |
| `codemesh_status` | Graph health check | `codemesh_status()` |

---

## CLI```bash
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 is available for map, search, source, recall, inspect, and hydrate. It removes
repeated metadata from CLI JSON; source still includes the exact requested code
and a content hash. Navigation maps, search, inspect, and hydrate emit bounded JSON without
pretty printing; their compact form preserves exact source and freshness hashes.
hydrate also accepts --references-file PATH for a JSON array saved on disk.
Bounded responses omit the extra project-root wrapper so the final JSON stays
within the requested budget. Other commands retain their existing response format.

For handoffs, save a symbol's exact ID and bodyHash from a fresh source result.
codemesh_hydrate checks that hash against live source before returning full code.
If a saved hash came from fold or preview, include its mode; that hash
checks only the rendered view, so include bodyHash to verify the whole symbol.
Inspect and hydrate report omitted blocks explicitly when a budget is reached.
Both default to four source blocks and a 24 KiB JSON response budget. inspect
follows at most one hop of conservatively resolved local Python functions and
imports. Use --direction incoming or both to inspect candidate callers too;
--max-candidates bounds caller verification (default 32, maximum 128). Indexed
edges are hints: each delivered caller is checked against its current Python
binding. Incoming discovery is explicitly incomplete when edges are missing;
an empty result never proves that a symbol has no callers. Dynamic receivers,
ambiguous names, and uncertain bindings remain
explicitly unresolved; other languages expose unverified graph candidates.
These are static bindings, not guarantees about runtime behavior. Hydration
returns live-checked code; clients decide when to invoke it after a handoff and
which evidence to retain in their model context.

--mode auto is an explicit navigation view: symbols up to 120 lines and 12KiB
are returned in full; larger symbols return a bounded preview with omitted ranges
and a hint to map their members. Explicit --mode full always returns exact source.
Search ranks exact identifiers and exact qualified/leaf names first, then query
term coverage and lexical relevance, with popularity used only to break ties.
For an opt-in structural hint, --exact-tie-break path-depth prefers shallower
paths before popularity on equally ranked exact-name/leaf matches. MCP exposes
the same exactTieBreak option on codemesh_explore. Explicit IDs and path
filters still select deeper implementations; depth does not establish which
implementation is canonical. The default remains pagerank.
--path restricts candidates to a file or directory before SQLite result caps;
src does not match src-other. Compact search includes signatures and spans.
Search and navigation default to an 8192-byte JSON budget; --max-bytes accepts
512..65536. Omitted results are explicit. Navigation's cursor always points at
the first unreturned entry; if that entry alone exceeds the budget, increase
--max-bytes and reuse the cursor. Source code remains behind source/inspect.

The deterministic Graphify follow-up
documents the single-agent design and focused context policy. Context replacement
belongs to the harness: MCP/CLI tools cannot remove earlier client messages.
The controlled next iteration documents lean eval
instructions, optional search ranking, and two multi-file handoff fixtures.

Source retrieval also accepts a unique symbol name, such as MyType.myMethod.
An ambiguous name returns exact candidate IDs and spans; it never guesses an
overload from its size. Exact IDs remain the preferred reference across sessions.
adapt reads a native tool observation from stdin. Search folding preserves every
match and falls back for unsupported formats. Read outlining requires a complete
byte-exact match with a fresh indexed file and explicit navigation intent; edit
reads and partial reads pass through unchanged. --json reports the route and
reason instead of emitting only the adapted observation.


Optional: Hooks & Skills

Skill — teaches agents the graph-first workflow

Copy skills/codemesh.md to ~/.claude/skills/ or your project's .claude/skills/.```bash

Install the skill so Claude Code loads the workflow automatically

cp /path/to/codemesh/skills/codemesh.md /your/project/.claude/skills/


The skill instructs agents to query the graph before using Grep/Read, and to write back via `codemesh_enrich` after reading code.

Hooks — automatic pre-read context injection

Add to `.claude/settings.json`:```json
{
  "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"
      }]
    }]
  }
}
  • Pre-read — Adds a cached summary marked non-stale alongside the pending Read result
  • Post-read — Nudges the agent to enrich after reading unfamiliar files

Supported Languages

TypeScriptJavaScriptPythonGoRustJavaC#

RubyPHPCC++SwiftKotlinDart

Any language with a tree-sitter grammar can be added.


Graph Data Model

Nodes

Type Source Key Fields
file Static (tree-sitter) path, hash, last_indexed_at
symbol Static (tree-sitter) name, kind, file_path, line_start, line_end, signature
concept Agent-written summary, last_updated_by, stale
workflow Agent-written description, file_sequence, last_walked_at

Edges

Type Direction Source
contains file → symbol Static
imports file → file Static
calls symbol → symbol Static
extends symbol → symbol Static
describes concept → file/symbol Agent
related_to concept → concept Agent
traverses workflow → file Agent

Architecture```

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)


Storage is **backend-agnostic**. The `StorageBackend` interface abstracts all persistence. v1 uses SQLite with FTS5 for zero-dependency local operation. The interface supports swapping to Memgraph, Neo4j, or other graph databases.

---

## Eval Framework

Reproducible evaluation harness with LLM-as-judge scoring:```bash
# 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

See docs/benchmark-results.md for full methodology and results. Early pydantic evals are archived in docs/experiments/.

The SQLite-only CLI has a separate vNext contract and agent workflow eval on a pinned Pydantic checkout. Its correctness checks and model cost/quality comparison are reported separately from the historical benchmarks.
The vNext Pydantic results record the first full paired run.


vs. Existing Tools

Feature CodeGraph Graphify Axon Codemesh
Structural indexing Yes Yes Yes Yes
FTS search Yes — Yes Yes
Agent write-back — — — Yes
Workflow memory — — — Yes
Hook interception — — — Yes
Backend-swappable — — — Yes
Eval framework — — — Yes
Published benchmarks — — — Yes

Development```bash

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
```


Contributing

Contributions welcome. Areas for improvement:

  • More languages — Add tree-sitter grammars and language-specific extractors
  • AST-diff invalidation — Function-level instead of file-level staleness detection
  • Graph backends — Memgraph/Neo4j adapters for StorageBackend
  • Semantic search — Embedding columns alongside FTS5
  • Agent adoption — Better patterns for agents to prefer graph tools naturally

License

MIT

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Codemesh 怎么安装?

在客户端按下面的安装命令接入:npx -y @pyalwin/codemesh。对应的包名是 @pyalwin/codemesh。装完在客户端配置里引用同一个包或端点。

Codemesh 怎么在 Claude Desktop、Claude、Cursor 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Codemesh 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Codemesh 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Codemesh 支持哪些客户端?

资料标注支持 Claude Desktop、Claude、Cursor、VS Code、Windsurf、Codex;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Codemesh 能提供哪些能力?

资料显示能力标签包括 grep、read、knowledge graph、code search。具体工具清单以官方文档为准。

Codemesh 需要什么运行环境?

运行时为 Cross-platform;属于本地进程,需要在本机装好运行环境。

Codemesh 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 未标注。