Graft Ditches Embeddings: AI Coding Agents Need a Map, Not More Retrieval

AI coding agents today suffer from a fundamental onboarding problem: humans learn a codebase once, but agents re-explore from scratch on every task. Graft (trailhq/Graft) addresses this by pre-digesting the entire repository into a human-readable Markdown knowledge graph stored in a graft/ directory, which agents consult before acting and which auto-updates after each edit.

Core Philosophy: Rejecting Embeddings

Unlike mainstream tools (Cursor, Sourcegraph) that rely on vector embeddings and similarity search, Graft explicitly avoids embeddings, similarity search, and warm indexes. The authors argue agents already know how to read files; what they lack is a structural map telling them which files to read and how they relate. In clean, well-engineered codebases grep-style precision is near-perfect and semantic retrieval adds ~16% token overhead; but when noise rises (poor naming, duplicate functions), text-match precision drops from 1.0 to ~0.5, making structured relationships valuable. Graft adopts both layers but keeps them separate.

Node Design: Anti-Drift Choices

Each graph node is a Markdown file with five sections:

Summary – plain-language explanation of the code's purpose

Crux – the actual source lines implementing core logic (not line numbers)

Sources – traceability to original files

Links – typed relationships with verbs: depends_on, part_of, uses, implements, produces, configures, validates, extends. These map directly to engineering questions (e.g., reverse depends_on answers "what breaks if I change this?").

Notes – human-authored annotations

Storing code snippets instead of line numbers eliminates drift: adding lines at the top of a file shifts all line numbers, but a hash of the snippet remains valid.

Two-Layer Architecture: Free Deterministic Base, Optional Semantic Layer

Structural Layer (default, free) – Uses tree-sitter for local, deterministic parsing across 23 languages. Eight languages (TS/JS, Python, Go, Java, Kotlin, PHP, Swift, R) have hand-written extractors with full cross-file call resolution; others use generic tree-sitter; LSP integration (rust-analyzer, clangd, gopls) available for precise call edges. Runs via graft build with no model calls, API keys, or network.

Semantic Layer ( --deep , optional paid) – Two LLM passes: first summarizes each source file, then clusters hundreds of files into dozens of curated nodes (subsystems, APIs, core concepts) linked by typed edges. Model-agnostic (OpenAI-compatible, Anthropic, LiteLLM, local models). Structural layer remains fully functional without it.

Freshness Built Into Query, Not Operations

Traditional indexes stale quickly. Graft refreshes on every query: before each ask, grep, or callers command, it fingerprints the working tree (~3 ms) and rebuilds only changed parts. Unstaged and staged changes are included equally. The graft/ directory is auto-gitignored (like node_modules), so each developer builds locally; only the init wiring (agent config, hooks, MCP declarations) is committed.

Context Delivery: Push for Speed, Pull for Accuracy

Push – Relevant nodes injected into the prompt at task start. Fast, zero agent queries.

Pull – Agent queries via MCP tools (find code, trace call chains, view repo map) on demand. Self-reported correctness 98%, 5 points higher than push.

Hooks chain them: session start pulls map, user questions trigger push injection, each edit auto-syncs and shows blast-radius warnings, end-of-turn silent rebuild. Agent need not know Graft exists.

Benchmarks and Caveats

SWE-bench Verified: Graft-enabled Claude solves 33/50 vs 27/50 cold-start (+12 pp).

Per-task token -42%, cost -32%, latency -60%.

Marketing claims "up to 4× cheaper, 3× faster" reflect best-case; sample is only 50 instances with self-selected harness and judge model. The concrete win pattern: baseline misses sibling files when fixing an auth bug, breaking 18 passing tests; Graft-enabled agent finds all required files.

Origin, Risks, and Adoption Guidance

Graft originates from NanoNets (AI document extraction), with the old repo NanoNets/context-graph-engine redirecting here. Commercial upsell targets Trail (Trail Brain). Risk: 77% of 467 commits by two NanoNets employees (bus factor ~2); project priorities may shift with Trail's roadmap. MIT license and fully local structural layer mitigate lock-in. 6.8k stars in ~10 weeks, but npm downloads ~27k/month and 105 open issues indicate early maturity.

Best fit: engineers heavily using agents on large/unfamiliar codebases (especially monorepos), teams caring about token costs and data locality. Avoid if: small repos (exploration cost low), languages outside the 23 supported, or zero-configuration requirement (hooks and config writes are invasive).

The article concludes that context engineering's marginal returns from "feed more similar snippets" are diminishing; pre-digesting repos into structured knowledge so agents never start from zero may be the next solid lever.

GitHub: github.com/trailhq/Graft