What is a code knowledge graph? (And why it beats grep for AI agents)

A code knowledge graph is a queryable map of a codebase in which functions, classes, files, tables, and configuration are nodes, and their relationships — calls, imports, defines, references — are typed edges an AI agent can traverse to answer structural questions.

That's the whole idea in forty words. The rest of this post is what those words buy you in practice — and an honest account of when plain grep is still the better tool.

Things, not strings

The framing comes from web search: when Google launched its Knowledge Graph in 2012, it described the shift as "things, not strings" — modeling entities and their relationships instead of matching text. Applied to code, the same shift turns PaymentService from a string that appears in 40 files into a node with edges: calls StripeClient, reads STRIPE_KEY, is deployed by a specific Terraform resource. The knowledge graph entry in our glossary covers the general concept; the code-specific version adds one crucial ingredient — the edges are extracted from the AST by a parser, not guessed from text.

Why agents outgrow grep

Grep answers 'which files contain this string?' — and AI agents lean on it for everything, including questions it can't actually answer. 'What calls this function?' via grep returns every occurrence of the name: real call sites, but also comments, test fixtures, docstrings, and unrelated variables that shadow it. The agent then reads all of those files into context to separate signal from noise, paying tokens for the sorting grep couldn't do.

Multi-hop questions make it worse. 'What breaks if I change this signature?' is function → callers → their callers → the schemas they serialize — three or four chained searches, each multiplying the files read and the chances of a missed link. A graph answers the same question as a single traversal: follow the typed edges, return the path. The answer is a handful of nodes, each one a real file, and hop three is exactly as reliable as hop one.

Where grep still wins

Honesty first: grep is unbeatable for exact-string questions. Finding a literal error message, a config key, a TODO, or every use of a deprecated flag needs no structure — string search is instant, needs zero setup, and never goes stale. A knowledge graph, by contrast, is a snapshot: it must be rebuilt when the code changes meaningfully, and building it takes minutes, not milliseconds. If your questions are all single-hop string lookups, a graph is overhead you don't need.

The right mental model isn't replacement; it's division of labor. Agents keep grep for strings and gain a graph for structure, and the two cover each other's blind spots. The same split, argued against embeddings instead of string search, is laid out in graph vs RAG.

How agents actually use one

Graphify builds the graph on-device: tree-sitter parses your code across 36 languages (edges tagged EXTRACTED — deterministic, straight from the AST), your model folds in docs, SQL, and Terraform (tagged INFERRED), and unresolved evidence is kept and tagged AMBIGUOUS rather than dressed up as fact. Assistants query it natively through MCP tools; humans use graphify query, graphify path, and graphify explain. Every answer arrives with its path and its provenance.

Trying it takes two minutes on a real repo: uv tool install graphifyy, then graphify install, then /graphify . in your next session. You get an interactive map, a written report, and the raw graph — all local. The deeper mechanics live in concepts, and the full command reference in the docs.