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.
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.
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.
[!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.
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):
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:
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.
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
--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
Copy skills/codemesh.md to ~/.claude/skills/ or your project's .claude/skills/.
# 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.
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:
# 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
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.
Agent adoption — Better patterns for agents to prefer graph tools naturally
License
MIT
Footnotes
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↩3↩4
Baseline for Alamofire hit a judge error (score recorded as 0 but not meaningful); excluded from the Baseline average. ↩
