Code graphs and vector search for codebases

An agent finds a function that looks relevant and changes it. The function's caller relies on a detail that was absent from the retrieved snippet. Search found the code but missed the relationship that made the edit risky.

A code graph records entities such as files, symbols, tests, and packages, along with their relationships. Vector search finds text with related meaning. My approach to codebase retrieval uses each for the question it can answer.

Retrieval methods#

Method	Useful question	Limit to check
Text search	Where is this exact name or error?	Renamed symbols and different wording
Vector search	Which code or document describes this behavior?	Similar text can belong to the wrong component
Code graph traversal	What calls or depends on this symbol?	Missing edges and an outdated index
Combined retrieval	What context does this change need?	Added context can exceed the useful budget

Embeddings, the numeric representations used by vector search, help find material that uses different words. They do not establish that a function calls another function. A graph edge can state that relationship, but its value depends on how it was extracted and which revision it describes.

Graph RAG for codebases#

Retrieval-augmented generation, or RAG, gives a model source material before it answers. Graph RAG adds relationships to that retrieval step.

Microsoft's GraphRAG distinguishes local queries about entities from global queries over summaries of the dataset. Those methods address different questions.¹ Applying a graph to code does not mean that a document summary is a complete call graph.

For a code change, start from a symbol or file found by text or vector search. Expand to relevant callers, imports, tests, and interfaces. Return source locations and the revision with each result. Stop expansion when another hop adds noise rather than context for the task.

Treat a model-inferred edge differently from one produced by a compiler or parser. A suggested dependency can help exploration, but it should not silently become a fact that authorizes a change.

Graph databases for coding agents#

Choose storage from the queries the agent needs to run. A small repository index may fit in ordinary tables with joins. A graph database can help when the workload needs repeated traversal across several kinds of relationships.

Check update cost before choosing the database. A graph that takes longer to refresh than the code takes to change may supply stale answers. Measure how it handles a rename, a deleted file, a branch switch, and a partial indexing failure.

Also check access boundaries. A graph response should expose only repositories the requesting agent can read. Edges to a private dependency can reveal information even when the source text stays hidden.

Evaluation#

Build a set of real repository questions with known source locations. Include exact symbol lookup, behavior discovery, dependency analysis, and likely tests for a change.

Compare text search alone, vector search alone, and the combined method on the same tasks. Measure whether the required context was returned, how much irrelevant context came with it, response time, and indexing cost. Evaluate the resulting patch too. Better retrieval scores alone do not establish better software.

The research on graph-grounded retrieval and vector search covers why relevant text can still be the wrong evidence. The guide to ontologies for coding agents defines the types and relations that make a code graph interpretable.

Footnotes#

1. Microsoft. GraphRAG query engine overview. ↩

@online{anderson2026codegraphsvector,
  author  = {Anderson, Mac},
  title   = {Code graphs and vector search for codebases},
  year    = {2026},
  date    = {2026-10-28},
  url     = {https://macanderson.com/research/code-graphs-vector-search-graph-rag}
}