CodeGraph (with updates)

Your codebase, understood.

[!TIP] Give your coding agents lasting project memory.

Meet CodeGraph Agent Memory, our sibling project that builds on CodeGraph with persistent memory for architectural decisions, findings, failed approaches, and reusable procedures. Enable memory retrieval to bring that knowledge into agent workflows alongside current code evidence across sessions.

Explore the agent memory guide →

CodeGraph transforms your entire codebase into a semantically searchable knowledge graph that AI agents can actually reason about—not just grep through.

Ready to get started? Jump to the Installation Guide for step-by-step setup instructions.

Already set up? See the Usage Guide for tips on getting the most out of CodeGraph with your AI assistant.

Prefer shell commands? Run codegraph agent context "your question". The same four agentic tools are available through the CLI, with project-local Claude Code/Codex hooks. codegraph init offers hook setup and adds agent instructions before indexing.

The Problem

AI coding assistants are powerful, but they're flying blind. They see files one at a time, grep for patterns, and burn tokens trying to understand your architecture. Every conversation starts from zero.

What if your AI assistant already knew your codebase?

What CodeGraph Does Differently

1. Graph + Embeddings = True Understanding

Most semantic search tools create embeddings and call it a day. CodeGraph builds a real knowledge graph:

Your Code → Build Context → AST + FastML → LSP Resolution → Enrichment → Graph + Embeddings
              ↓               ↓              ↓              ↓              ↓         ↓
          Packages        Nodes/edges    Type-aware     API surface      Graph    Semantic
          Features        Fast patterns  linking        Module graph   traversal   search
          Targets         Spans          Definitions    Dataflow/Docs             (hybrid)

When you search, you don't just get "similar code"—you get code with its relationships intact. The function that matches your query, plus what calls it, what it depends on, and where it fits in the architecture.

Indexing enrichment adds:

• Module nodes and module-level import/containment edges for cross-file navigation
• Rust-local dataflow edges (defines, uses, flows_to, returns, mutates) for impact analysis
• Document/spec nodes linked to backticked symbols in README.md, docs/**/*.md, and schema/**/*.surql
• Architecture signals (package cycles + optional boundary violations)

Indexing tiers (speed vs richness)

Indexing is tiered so you can choose between speed/storage and graph richness. The default is fast.

Agent answer accuracy is evaluated separately; see the CLI accuracy results.

Tier behavior details:

• fast: disables build context, LSP, enrichment, module linking, dataflow, docs/contracts, and architecture; filters out Uses/References edges.
• balanced: enables build context, LSP symbols, enrichment, module linking, and docs/contracts; filters out References edges.
• full: enables all analyzers and LSP definitions; no edge filtering.

Configure the tier:

• CLI: codegraph index /path/to/project --index-tier balanced
• Env: CODEGRAPH_INDEX_TIER=balanced
• Config: [indexing] tier = "balanced"

Directory indexing scans subdirectories by default, so codegraph index --languages Rust --index-tier balanced . finds Rust sources in workspace crates. Use --no-recursive for an intentional root-only scan; -r/--recursive remain accepted. codegraph estimate uses the same traversal defaults.

Indexing prerequisites (LSP-enabled tiers)

When the tier enables LSP (balanced/full), indexing fails fast if required external tools are missing. Rust indexing also runs rust-analyzer --version from the target project before parsing: an existing rustup shim does not guarantee that its active toolchain has the component. With rustup, run rustup component add rust-analyzer from that project directory, then verify rust-analyzer --version. Language-server failures retain the final 4 KiB of stderr so startup and runtime errors include the server's diagnostic.

Required tools by language:

• Rust: rust-analyzer
• TypeScript/JavaScript: node and typescript-language-server
• Python: node and pyright-langserver
• Go: gopls
• Java: jdtls
• C/C++: clangd

Warm language-server sessions retain versioned documents and deduplicate/pipeline definition requests. Symbol and definition requests retry transient ContentModified (-32801) responses up to five times with backoff within one 30-second deadline. Changed document versions, exhausted retries and other errors still fail indexing, with the request method and file URI in the diagnostic. CODEGRAPH_LSP_REQUESTS bounds outstanding requests per server (default 32). CODEGRAPH_ANALYZERS=0 disables analyzers independently of tier. CODEGRAPH_SCIP_INDEX=/path/index.scip can substitute a compiler index for LSP; source validation and sidecar requirements are described in the indexing implementation guide.

Incremental indexing and inference policies

--batch-size sets the maximum number of embedding texts per batch for both local and cloud providers. An explicit value wins over CODEGRAPH_EMBEDDINGS_BATCH_SIZE, its legacy alias CODEGRAPH_EMBEDDING_BATCH_SIZE, and [embedding] batch_size in TOML, in that order; the default is 64. Memory-based tuning does not change explicit values, including --batch-size 100.

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

Token/byte budgets, cache hits and provider API limits can produce smaller actual requests. For larger requests, adjust CODEGRAPH_EMBEDDING_BATCH_TOKENS (default at least the resolved input context, with local/remote floors of 8192/32768) and CODEGRAPH_EMBEDDING_BATCH_BYTES (default 1 MiB) as needed. Logs show these inference limits separately from database write batches; CODEGRAPH_CHUNK_DB_BATCH_SIZE defaults to at most 32 rows and is capped at 512. Ollama and LM Studio have no extra fixed 256-text cap.

Full, single-file and watch indexing share complete-project reconciliation. Unchanged sources reuse cached AST/analyzer artifacts while the full catalog retains callers across edits, renames and deletions. Only changed graph records and file metadata are written. Source snapshots, parsing, inference and writer queues have independent resource bounds; completion follows durable acknowledgements and final input checks. --force prepares and reconciles again without trusting the previous catalog.

Embedding and semantic-resolution work is independent of extraction tier. Each accepts sync (default when its feature is compiled), deferred or off:

CODEGRAPH_EMBEDDING_POLICY=deferred CODEGRAPH_SEMANTIC_RESOLUTION=off \
  codegraph index /path/to/project --index-tier fast --stats-json indexing.json
codegraph index /path/to/project --complete-deferred --stats-json completed.json

Deferred runs persist a resumable job and distinguish graph readiness from pending inference. Prepared-text embedding caches include model/task/tokenizer/runtime identity; chunking preserves Unicode and enforces provider token budgets. Mutable model aliases expire; CODEGRAPH_MODEL_REVISION declares an immutable revision.

Embedding inputs and chunking

Chunk planning starts from AST node source spans, such as functions and classes. A unit that fits the complete input budget stays intact. Oversized units split at Tree-sitter statement/block boundaries, then merge adjacent pieces while they fit. Oversized leaves and unsupported syntax use UTF-8-safe line/token splitting. Unicode and structural whitespace are preserved; overlap uses token counts.

For Ollama, the budget follows model metadata and serving context. Qwen3 embedding models support 32K inputs; nomic-embed-text-v2-moe supports 512 tokens. Counting includes document/query prefixes and special tokens. Nomic text models receive search_document: / search_query: ; Qwen3 queries receive a retrieval instruction. Every Ollama request uses truncate=false: context mismatch fails visibly instead of silently dropping source.

Recognized models automatically load their matching publisher tokenizer, caching tokenizer.json and downloading it on first use if absent. Model weights are not downloaded. Custom/offline models can supply CODEGRAPH_TOKENIZER_PATH; an unknown model requires that path or CODEGRAPH_TOKENIZER_REPO.