What It Is
The symbol graph is a per-workspace pgvector index of the codebase at function/class/interface/enum granularity. Rows live insymbol_graph_nodes. Each row carries the symbol’s kind, file, line range, neighbour symbols (who calls whom), and a semantic embedding of its signature + leading docstring.
How It Stays Fresh
A lightweightts-morph extractor runs on every agent write via the postToolUse hook. It re-parses only the file that changed and upserts its top-level declarations. The graph is eventually consistent with the repo state within a few hundred milliseconds of an edit.
What It Powers
| Feature | How the graph helps |
|---|---|
| Symbol-level file reservations | Narrow a lock to createUser instead of the whole src/users.ts |
| Affected-test discovery | The test gate traces symbol-to-test edges to decide what to run |
| Living decisions | Decisions auto-link to the symbols they mention; staleness is detected when those symbols change |
| Negotiations | negotiate_open targets specific symbols by id or name |
| Knowledge graph UI | The dashboard visualization renders nodes + call edges |
Reservations vs Graph
File reservations are a coordination primitive — a lock. The symbol graph is a data structure — a map. They interact viagranularity='symbol' on a reservation: the lock scopes down to the symbol’s line range. The graph decides what counts as a symbol; reservations enforce the lock.
Language Support
Today: TypeScript and JavaScript (viats-morph). The extractor is pluggable; Python and Go are next on the roadmap.
For languages without an extractor yet, file-level reservations still work — you just lose symbol-level precision.