codegraph-rust: indexing a codebase into a graph for coding agents

The pipeline from source code to a queryable graph

The mechanism is laid out as a pipeline in the documentation, and reading it tells you what the project is actually doing rather than what it is calling itself:

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings

Each stage has a job. Build context works out the packages, features and targets. AST and FastML parsing produces nodes and edges with fast pattern matching and source spans. LSP resolution gives type-aware linking and the API surface, so a definition is resolved through a language server rather than a name guess. Enrichment adds the module graph and the dataflow and documentation links. The output is a graph stored with embeddings, and the search is described as hybrid, meaning graph traversal combined with semantic search. The point of the whole arrangement is stated in the documentation as follows: when you search, you do not just get similar code, you get code with its relationships intact, meaning the function that matches the query plus what calls it, what it depends on, and where it fits in the architecture. That is the difference from an embedding-only search, and it is the reason the project is worth the extra machinery.

Three indexing tiers trade graph richness for build time

Indexing is tiered, and the tier is the first decision you make. The default is fast, which gives you AST nodes and core edges with no LSP and no enrichment, and it is described as quick indexing with low storage. The balanced tier adds LSP symbols, documentation and enrichment, module linking, and the module graph, giving richer navigation with a moderate analyzer cost. The full tier enables all analyzers, LSP definitions, dataflow and architecture signals, and does no edge filtering at all. The documentation is precise about what each tier switches off. Fast disables build context, LSP, enrichment, module linking, dataflow, docs and contracts, and architecture, and it filters out the Uses and References edges. Balanced filters out the References edges. Full filters nothing. The tier can be set on the command line, through an environment variable or in the config file, and the same traversal defaults apply to the estimate command, which is the one to run first to see what a full index would cost before you commit to it. The documentation also states that agent answer accuracy is evaluated separately from the tier, so a richer tier is not automatically a better answer.

Language servers are a hard dependency on the richer tiers

This is where the project fails loudly rather than silently, and it is a design choice you should know about before you point it at a repository. When the tier enables LSP, indexing fails fast if the required external tools are missing. The required tools are listed per language: rust-analyzer for Rust, node and typescript-language-server for TypeScript and JavaScript, node and pyright-langserver for Python, gopls for Go, jdtls for Java, and clangd for C and C++. Rust gets an extra wrinkle, because indexing runs rust-analyzer --version from the target project before parsing, since an existing rustup shim does not guarantee that the active toolchain has the component. The suggested fix is to run rustup component add rust-analyzer from the project directory and then verify the version. There is more machinery behind that than it looks. Language server sessions retain versioned documents and deduplicate and pipeline definition requests, symbol and definition requests retry transient ContentModified responses up to five times with backoff inside a single 30 second deadline, and changed document versions, exhausted retries and other errors still fail indexing with the request method and file URI in the diagnostic. Failures also keep the final 4 KiB of stderr, so a startup error includes the server's own message.

Tuning the embedding calls, and the four ways to set a value

Batch sizing is the knob you will touch first, and the precedence rules are documented precisely because there are four ways to set the same value. The batch-size flag sets the maximum number of embedding texts per batch for both local and cloud providers, and an explicit value wins over the CODEGRAPH_EMBEDDINGS_BATCH_SIZE environment variable, its legacy alias CODEGRAPH_EMBEDDING_BATCH_SIZE, and the batch_size key in the embedding section of the TOML config, in that order. The default is 64. Memory-based tuning does not override an explicit value. A larger batch is a one line change:

codegraph index --languages Rust --index-tier balanced --batch-size 512 .

Two separate budgets sit above the row count. CODEGRAPH_EMBEDDING_BATCH_TOKENS sets a token request budget, defaulting to at least the resolved input context with a local floor of 8192 and a remote floor of 32768, and CODEGRAPH_EMBEDDING_BATCH_BYTES defaults to 1 MiB. Token and byte budgets, cache hits and provider API limits can all produce smaller actual requests than you ask for. Database writes are capped separately, with CODEGRAPH_CHUNK_DB_BATCH_SIZE defaulting to at most 32 rows and capped at 512, and the logs show the inference limits separately from the database write batches. The .env example file spells out the whole embedding configuration, from the provider choice of ollama, openai, jina, lmstudio or onnx to the model name, the dimension count and the chunking options.

A CLI, a shell command, and MCP for the agent

There are three ways to reach the index, and the one for agents is the point of the project. The primary interface is the Model Context Protocol, and the documentation describes advanced agentic code analysis tools through MCP for efficient code agent context management. The same four agentic tools are also available through the CLI, with project-local Claude Code and Codex hooks, and there is a shell command for a quick question: codegraph agent context "your question". The codegraph init command offers hook setup and adds agent instructions before indexing, which is the piece that makes an agent actually use the index rather than fall back to grep. The repository topics name the intended consumers directly, including claude-code, codex, cursor and gemini-cli, and a sibling project is referenced for persistent memory across sessions, holding architectural decisions, findings, failed approaches and reusable procedures, with memory retrieval to bring that knowledge into agent workflows alongside current code evidence. The repository layout supports the same split, with crates for the core, the vector store, the parser, the graph, concurrent and zerocopy helpers, and a family of MCP crates for the server, the daemon and a rig integration, plus an HTTP MCP server build target in the Makefile.

Enrichment edges are what the graph adds over a symbol index

The enrichment stage is where the graph earns its storage cost, and the documentation lists exactly what it adds. Module nodes and module level import and containment edges support cross-file navigation. Rust local dataflow edges are named explicitly, and the set of verbs is telling: defines, uses, flows_to, returns and mutates, which is a set built for impact analysis rather than for retrieval. Document and spec nodes are linked to backticked symbols in the README, in docs markdown files and in Surreal schema files, so a specification and the code it describes end up in the same graph. Architecture signals are computed too, covering package cycles and optional boundary violations. The naming of the edges is a design decision with consequences. A graph with uses and references edges is good at recall, since it connects everything that mentions a symbol, and bad at precision, since the vast majority of those mentions are uninteresting. That is why the fast tier filters the Uses and References edges, and why the balanced tier keeps Uses but drops References. The trade is recall against precision, expressed as which edges survive the filter.

Feature flags decide how much of the stack you build

The build is a Cargo workspace with twelve member crates and a set of feature groups that make the size of the dependency stack a deliberate choice. The metadata defines mcp-minimal, which turns on ai-enhanced and embeddings-ollama and is described as the minimal build for MCP server development with the fastest build times. mcp-lmstudio adds embeddings-lmstudio for MCP development with LM Studio support. The local-stack group adds the daemon and the local embedding providers for a full local stack with no cloud dependencies. The cloud-enabled group adds cloud, embeddings-jina and server-http. And full turns on everything, described as for development and testing. The default members of the workspace are just codegraph-core, so a plain cargo build at the root does not compile the experimental crates, and the lint target is limited to the default members for the same reason. The workspace is on edition 2024 with a rust-version of 1.95, and the build scripts are separated into profiles, with the release-size profile used for an API binary that is then stripped and compressed by a script. Several shell installers sit at the repository root for different configurations, including local speed builds for macOS and a cloud build.

Editorial conclusion

codegraph-rust is a good fit for a team running Claude Code, Codex, Cursor or Gemini CLI against a large repository where the agent keeps burning tokens rediscovering the same structure, and for anyone willing to keep a local or hosted embedding model and a language server in the loop. It is the wrong choice for a small project, where an index costs more to build than the questions it answers, and it is the wrong choice if you cannot accept a database process and a model download on the developer machine. Before adopting it, read the tier documentation and start with the fast tier, because the balanced and full tiers fail fast when a language server is missing, and confirm the embedding provider and model in the .env example before your first index, since the defaults assume a local Ollama setup. The workspace Cargo.toml declares the licence as MIT OR Apache-2.0, the repository publishes no GitHub releases, and the last push was on 2026-10-12.

Frequently asked questions

Official sources

1. Issues
2. Jakedismo/codegraph-rust on GitHub
3. README