Codemesh MCP server

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.

Benchmarks · Quick Start · Integrations · Write-Back · How It Works · API Reference · Full Results

---

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 Compiler1	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	Swift1	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	Swift1	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	Alamofire2	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 Compiler1	$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

npm install -g @pyalwin/codemesh

Or run directly without installing:

npx -y @pyalwin/codemesh --help

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

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:

Add to your Claude Code MCP config (~/.claude/mcp-servers.json or project .mcp.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

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

Add to ~/.claude/mcp-servers.json (user-wide) or .mcp.json (project-local):

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

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.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 reads .cursor/mcp.json per project (or ~/.cursor/mcp.json for all projects):

{
  "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.

Add to ~/.continue/config.json under experimental.modelContextProtocolServers:

{
  "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.

// 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()

---

Footnotes

1. Swift Compiler's codemesh index failed to complete (indexer regression on 30k+ file codebases — see known issues). The codemesh numbers above reflect agent behavior with an empty retrieval graph, falling back to Read + LSP — still ahead of baseline, but unrepresentative of codemesh's capability on a properly-indexed Swift repo. ↩ ↩² ↩³ ↩⁴

2. Baseline for Alamofire hit a judge error (score recorded as 0 but not meaningful); excluded from the Baseline average. ↩