Home / Projects / Orchestrata Ultimate / Decisions / ADR index / ADR-0003

ADR-0003: Neo4j is the fact system of record; Memgraph deferred

← ADR-0002 · ADR-0004 →

The record

• Status: Accepted
• Date: 2026-07-23
• Spec: SPEC-033 §4 (ADR-033-01)
• Supersedes: the undocumented v0.1 choice of "one Memgraph graph per project"

Context

SPEC-033 v0.1 declared Memgraph the per-project system of record for all facts (AST, traceability, design fact base, provenance). Review found this contradicted the running system on three counts:

• The live AST sync targets Neo4j (scripts/sync_ast_to_neo4j.py, with schema/full/incremental/ map/verify/stats subcommands); ~208 Neo4j references across the repo, zero for Memgraph in this path.
• SPEC-008 — a declared dependency — specifies Neo4j 5.0+, with Memgraph only as a semantic-chunk store bridged into Neo4j.
• SPEC-033's own REQ-033-T2 named "Redis/Neo4j" — the document contradicted itself.

A Memgraph cluster ("orchgraph") does exist and is operational, but currently serves vector/semantic search, not AST/design facts. Per-project partitioning does not exist as such, though a project property already scopes every sync and query.

A spec that demands decision-complete designs cannot itself ship with an undecided datastore.

Decision

Neo4j is the system of record for facts, now. Build on the existing sync. Per-project graph partitioning beyond the current project property, and any Neo4j → Memgraph migration, are scoped tasks (SPEC-033 B11), not preconditions. SPEC-008 is amended by this ADR to record the direction. All SPEC-033 requirements name Neo4j consistently.

The invariant that does hold regardless of engine: the graph is the single fact store; Prolog owns no durable facts and reasons over a projection (see ADR-0005).

Alternatives rejected

• Memgraph now — would require migrating a live system-of-record before any of the thesis is proven; front-loads a one-way door for no near-term benefit.
• Dual-write during transition — two fact stores is precisely the drift this design exists to eliminate.

Consequences

• Phase 1 can run against the existing graph; per-commit full sync is acceptable, so the hard incremental-extraction work (B4b) is not on the Phase-1 critical path.
• Read replicas are Enterprise-only, and the repo runs neo4j:5 Community (CI + docker/docker-compose.yml). Any liveness design depending on replica reads is unavailable on this engine — resolved separately (see ADR-0019).
• Memgraph remains available for its current vector/semantic role without forcing a fact migration.

Provenance

Round-2 review: Fable ("the land registry names two different owners"), Sonnet and Opus both code-verified the Neo4j reality. This ADR exists because the original Memgraph decision was recorded only as spec prose, was overwritten by the v0.3 rewrite, and left no trace of what was decided or why — the failure that motivated this ADR log.

Related ADRs

• Also mentioned: ADR-0005, ADR-0019

Rulings cited

None.

Specs cited

• SPEC-033
• SPEC-008