Semantic Code Graph
The Semantic Code Graph builds a relationship layer on top of the symbol index (SymbolIndex), supplemented by local vector retrieval, so AI understands cross-file call relationships and module dependencies before planning and rewriting. When a project grows to hundreds of files and the context window alone can no longer show the full picture, the code graph becomes the AI's "global view".
Index Building
Indexes are built and queried per project root, isolated between projects. The kernel builds two kinds of indexes for each project:
- Symbol relationship index: parses symbols in the code and their relationships, covering three relation types — Calls, Implements, and DependsOn. Every relationship record contains a source symbol, a target symbol, and a relation type.
- Vector index: encodes code snippets into vectors using a local embedding model (L2 normalization enabled by default), and retrieves semantically similar code by cosine similarity. Every vector record carries its source file and a text preview, so results can be located to a specific file directly.
The embedding model runs entirely locally — indexing and retrieval complete without your code ever leaving the machine:
| Model | Dimensions | Use case |
|---|---|---|
static-code-embed | 256 | Code snippets (normalization enabled by default) |
static-bert-tiny | 128 | General text |
The two scenarios use different dimensions, fixed at index creation time; retrieval is ranked by cosine distance — smaller means more similar.
Cross-File Reference Queries
All queries are bounded by the project root and initiated by symbol name:
| Query | Description |
|---|---|
| Callers | Who calls this symbol |
| Callees | Who this symbol calls |
| Implementations | All implementations of an interface / trait |
| Module dependencies | Which downstreams a module depends on |
| Relationship subgraph | The relationship network expanding layer by layer around a symbol to depth N |
The two index types work together: vector retrieval handles fuzzy "semantically related" lookup, while the relationship graph handles precise tracking along "definite reference chains". Subgraph queries start from a central symbol and expand depth-first toward both callers and callees — commonly used to assess the blast radius of a change.
The relationship layer is the core deliverable of Semantic Code Graph Phase 1: the symbol index first extracts functions, types, and modules, then three kinds of relationship edges are built on top of it. All queries are read-only and never modify project code. Query implementation borrows the symbol index directly for read-only access; subgraph expansion deduplicates visited nodes, so even cyclic calls cannot cause an infinite loop.
The graph is built in sync with LSP integration, providing a unified foundation for upcoming diagnostics, navigation, and completion capabilities.
Working with RUSH
During the planning stage, the Planner of a RUSH Deep Task queries the code graph to assess the blast radius of a change and outputs an affected-file list plus potential risks — this is the foundation that lets RUSH safely execute cross-file refactoring. Every subtask in the plan carries dependencies and a risk level, which determine the execution order. Typical scenarios:
- Before renaming a function called in many places, confirm all its callers first.
- Before changing a module's interface, list every downstream that depends on it.
- Assess the blast radius of a change: take a two-layer relationship subgraph around the target symbol.
- When getting familiar with an unfamiliar codebase, expand the relationship subgraph layer by layer from an entry symbol.
Tip for large projects: for cross-repo work or a large project being used for the first time, let index building finish before launching a RUSH task — planning quality improves significantly.
The graph's query interfaces are also exposed through the kernel API. Related docs:
- RUSH Deep Task: the graph's biggest consumer.
- Kernel API: the HTTP form of the query interfaces.