Codemesh

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 → WorkAfter:   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

Time

Tool calls (agent turns)

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

Cost savings: Codemesh MCP vs Baseline

[!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.gitcd codemeshnpm install && npm run buildnpm link

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

2. Index your project

cd /your/projectcodemesh 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:

{  "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 mapcodemesh 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 previewcodemesh explore inspect 'symbol:src/server.ts:createServer' --depth 1 --max-symbols 4 --compactcodemesh 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.swiftcodemesh explore trace Session.request --depth 5codemesh explore recall --path src/server.tscodemesh remember --path src/server.ts --summary "Server tool registration" --session my-task

Which mode should I use?

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.

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

CLI

codemesh index                          # structural + git intel + pagerankcodemesh rebuild                        # force re-index; preserves saved knowledgecodemesh status                         # graph statistics
codemesh explore map                    # repository rootcodemesh explore map --node 'dir:src'   # expand one branchcodemesh explore map --node 'symbol:src/auth.ts:login' --relation callscodemesh explore source 'symbol:src/auth.ts:login'codemesh explore source 'symbol:src/auth.ts:login' --if-hash HASH  # unchanged reference if bytes matchcodemesh explore source 'symbol:src/auth.ts:login' --force         # rehydrate exact sourcecodemesh explore inspect 'symbol:src/auth.ts:login' --depth 1 --compactcodemesh explore hydrate --references '[{"id":"symbol:src/auth.ts:login","bodyHash":"HASH"}]' --compactcodemesh explore answer "question"      # optional ranked context assemblycodemesh explore search "query"         # SQLite FTS5 + trigramcodemesh explore search get_default --path pydantic --scope symbols --max-bytes 4096codemesh explore inspect 'symbol:src/auth.py:login' --direction both --max-candidates 16codemesh explore recall --path file     # prior notes with freshnesscodemesh explore context file1 file2    # multi-target contextcodemesh explore trace symbol --depth 5 # follow call chainscodemesh explore impact file            # reverse dependenciescodemesh remember --path file --summary "note" --session task-idcodemesh workflow --name flow --description "flow description" --file first.ts --file second.tscodemesh explore search "query" --compact  # 8 candidates with IDs and match reasonscodemesh explore source 'symbol:src/auth.ts:login' --mode full --compactcodemesh explore source 'symbol:src/auth.ts:login' --mode auto --compactrg -n 'login' src | codemesh adapt search  # reversible fold when smallercat 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

# Install the skill so Claude Code loads the workflow automaticallycp /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"      }]    }]  }}

Supported Languages

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

Graph Data Model

Nodes

Edges

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:

# Setupnpm install -g @pyalwin/codemeshgit clone --depth 1 https://github.com/Alamofire/Alamofire.git /tmp/alamofire# ... clone other repos ...
# IndexCODEMESH_PROJECT_ROOT=/tmp/alamofire codemesh index
# Run benchmarkspython3 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

Development

bun install          # Install dependenciesbun run build        # Compile TypeScriptbun run test         # Run 102 testsbun run dev          # Watch modebun 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