Code graph

The code graph is a read-mostly index of a project's code and docs as nodes and typed edges. It is not the source tree, not git, and not a substitute for opening a file when you need the body.

It exists so an agent or a human can ask what calls this, what implements that, and which doc mentions this symbol, without grepping the repo on every turn.

Docs and code live in one graph. A doc reference whose target no longer resolves is drift, not a separate product. Edge provenance uses the same axis as memories and facts: asserted, inferred, or ambiguous.

All endpoints require authentication. Responses are wrapped in ApiEnvelope<T>. Canonical host: https://api.atamaia.ai. Every query takes projectId.

What it indexes

Source symbols: file, directory, module, class, interface, struct, enum, function, method, property, field, constant, variable, parameter, type alias.

Documentation: document and doc section. A doc mirrored from the docs table carries docId.

Nodes and edges

A node is one symbol or doc unit: id, kind, name, qualifiedName, language, filePath, line span, signature, and the commit it was extracted at.

An edge is directed: from, to, kind, provenance, and sourceLine when known.

Edge kinds: Contains, Calls, Imports, Inherits, Implements, Uses, References, Returns, HasParameter, Overrides, Documents, Mentions.

Contains is the tree. Calls, Inherits, and Implements are how you find who uses a symbol. Documents and Mentions link docs to code. Mentions are often inferred or ambiguous.

Graph edges are not Hebbian. They do not strengthen with use. See Standing rules for a different non-Hebbian link.

Staleness

Search, neighbors, drift, and node results can carry graphCommit, repoCommit, stale, and populated.

populated: false means the project has no nodes. That is not the same as a search with no matches, and not the same as stale. stale: true means the index commit and the repo HEAD disagree. Line numbers may not match the working tree. Re-ingest before trusting spans.

Query

GET /api/graph/search?projectId=&query=&kind=&language=&limit=
GET /api/graph/neighbors?projectId=&symbol=&direction=both&edgeKind=&limit=
GET /api/graph/node?projectId=&symbol=
GET /api/graph/stats?projectId=
GET /api/graph/drift?projectId=&doc=&limit=
POST /api/graph/rebuild

Search matches name or qualifiedName, case-insensitive. An exact name ranks first. If lexical hits are under the limit and embeddings exist, a semantic fallback (cosine above 0.3) fills the rest. It does not outrank an exact name. limit is 1 to 200.

direction is out (what this node calls or contains), in (callers and parents), or both. symbol is a node id or a name. Prefer a qualified name. A short name can hit the wrong kind.

Drift lists names that docs reference and that resolved to no code node at ingest. Rebuild regenerates that projection.

Rebuild body: { "projectId": 1, "repoPath": "optional override" }. It returns file, node, and edge counts. Rebuild is not an MCP tool. Agents query. Operators rebuild.

MCP tools: graph_search, graph_neighbors, graph_node, graph_drift. Stats is REST or atamaia_call.

GET /api/demo/memory-graph is a demo memory visualization. It is not this graph.

Limits

  • Nodes carry a path and a line span, not the file body.
  • Asserted edges are strong. Inferred and ambiguous edges are not a typechecker.
  • Semantic search is secondary. Name search is the reliable path.
  • Always pass projectId. There is no cross-project search.
  • Check staleness in any session that depends on line numbers.

Last updated