Architecture¶
How the engine works
These pages are the engineering deep-dives, drawn from the normative design specs in .ai/specs/ and verified against the code as built. They explain not just what each subsystem does but why it is built that way and what invariants it upholds.
Spec-first
Every subsystem here has a normative spec (a 14-section design manual) that is the source of truth. Where a spec's prose and the code disagree, the spec's as-built changelog is the record. Each page links back to its spec.
The system in one picture¶
flowchart TB
subgraph api["API surfaces"]
REST["REST /v1"]
GRPC["gRPC (app + worker)"]
MCP["MCP server"]
end
subgraph query["Query & generation"]
EXEC["Query executor"]
PLAN["Memory planner"]
GEN["Generation orchestration"]
VER["Claim verification"]
end
subgraph engine["Temporal engine"]
NODE["Node/Edge ops"]
SCAN["Global temporal scan"]
TRAV["Traversal"]
SCHEMA["Schema inference"]
BITMAP["Bitmap index"]
end
subgraph vec["Vector engine"]
VSTORE["Vector storage"]
HNSW["HNSW partitions"]
end
subgraph store["Storage"]
KEYS["Composite key layout"]
ROCKS["RocksDB · 13 column families"]
end
subgraph jobs["Async"]
QUEUE["Job queue + leases"]
WORK["Format workers"]
end
api --> query
api --> engine
query --> engine
query --> vec
engine --> store
vec --> store
jobs --> engine
query --> jobs