Neo4j — Context Graph & Lineage

Platform 8 of 12·OS Layer 7 (Memory & Data Layer)·Required in all deployment modes

Scope of this page. Reference material for the Neo4j platform: what it is, what it is normally used for, and how and why Synedrix OS uses it. It is descriptive, not normative — where this page and a canonical spec in docs/os/ disagree, the canonical spec wins. Platform responsibilities are set by Tech Stack §7; the lineage semantics it stores are set by Outcome Spec and Event Taxonomy Standard; the build-level mapping — per-agent Cypher/NAMS usage and the compliance checklist — is the Neo4j Implementation Guide.

What Neo4j is link

Neo4j’s Operations Manual opens with: “Neo4j is the world’s leading graph database. The architecture is designed for optimal management, storage, and traversal of nodes and relationships. The graph database takes a property graph approach, which is beneficial for both traversal performance and operations runtime.”

The data model is small and fully explicit:

Two structural rules from the Graph Database Concepts page are worth stating because a lineage model depends on them. A node “can have zero to many labels”. A relationship “must always have a start node, an end node, and exactly one type”, and “must have a direction”. So a lineage edge cannot exist without both endpoints and cannot be ambiguous about which way causality runs — the store refuses to hold a dangling or undirected causal claim.

Cypher. Queries are written as ASCII-art patterns — “Rounded brackets are used for circular nodes, and -[:ARROWS]→ for relationships. Writing a query is effectively like drawing a pattern through the data in the graph.” The Cypher Manual’s own SQL comparison makes the difference concrete: a two-JOIN SQL query becomes MATCH (actor:Actor)-[:ACTED_IN]->(movie:Movie {title: 'The Matrix'}). Cypher queries also end with the return clause rather than beginning with it, and are “schema-flexible” — nodes and relationships need not carry a property just because their neighbours do, unless a property existence constraint says so.

Traversal against joins. The Getting Started guide states the storage property directly: “Graph databases do not use JOINs. Rather, relationships are stored natively alongside the data elements (nodes) in a more flexible format, which allows the optimization of data traversing and millions of connections to be accessed per second.” The edition feature table lists “Native graph processing & storage” as a product feature of both editions.

Terminology note. The phrase index-free adjacency is widely used for this property but does not appear in the Operations Manual, the Getting Started guide, or the Graph Database Concepts page. Neo4j’s documentation states the same thing as native storage of relationships alongside nodes, and as an architecture “designed for optimal management, storage, and traversal of nodes and relationships”. This page uses Neo4j’s own wording rather than the informal term.

Editions. There are two editions of self-managed Neo4j, plus a specialised variant:

• Community Edition (CE) — “a fully functional edition of Neo4j, suitable for single-instance deployments. It fully supports key Neo4j features, such as ACID-compliant transactions, Cypher, and programming APIs. It is ideal for learning Neo4j, do-it-yourself projects, and applications in small workgroups.”
• Enterprise Edition (EE) — “extends the functionality of Community Edition to include key features for performance and scalability, such as a clustering architecture and online backup functionality. Additional security features include role-based access control and LDAP support … It is the choice for production systems with requirements for scale and availability.”
• Infinigraph — “a specialized Enterprise Edition … includes all features from Enterprise edition, as well as unlimited horizontal scaling with automatic sharding and graph analytics capabilities. Requires a separate subscription.”

The split is not cosmetic. It is covered in detail under Deployment and licensing below, because several of the Enterprise-only features are governance features.

What Neo4j is normally used for link

The cases Neo4j’s own documentation leads with:

• Modelling networks — “Whether it’s a social or a road network, all networks can be structured as an interconnected graph of relationships.”
• Answering relationship questions rather than entity questions — “Many times, a project’s questions and challenges revolve around the relationship between elements, not the elements themselves (e.g. how to get from A to B, instead of what A is and what B is).”
• Navigating deep hierarchies, finding hidden connections between distant items, and discovering inter-relationships between items — the three uses the Getting Started guide names explicitly.
• Impact and dependency analysis — the Graph Database Concepts page gives “What web services are affected if this power supply goes down?” as a canonical traversal question.
• Knowledge graphs for generative AI — Neo4j ships vector indexes and a GenAI plugin, both available in Community Edition per the edition feature table.

The common thread is that Neo4j owns the connections between things as first-class, queryable, directed, typed objects. It is not where the authoritative record of each thing lives; it is where the shape of how those things relate is asked questions of.

How Synedrix OS uses it link

Neo4j is the context graph and lineage store of Synedrix OS and sits at Layer 7 (Memory & Data Layer) of the twelve-layer taxonomy, alongside Supabase PG17, Redis, QuestDB and Qdrant. It is required in all three deployment modes described in the Deployment Model Spec. In the Tech Stack’s Layered Truth Summary it holds the graph / lineage truth class.

flowchart LR
  n1([Neo4j]):::term
  subgraph What it owns
    n2[Workflow and outcome lineage]:::agent
    n3[Agent influence and correlation networks]:::agent
    n4[Entity relationship graphs]:::agent
    n5[Cross-system dependency context]:::agent
  end
  n1 --> n2
  subgraph What it does not own
    n6[Canonical relational truth audit records agent lineage links]:::warn
    n7[Supabase PG17]:::term
    n6 --> n7
    n8[Time-series metrics and telemetry]:::warn
    n9[QuestDB]:::term
    n8 --> n9
    n10[Hot state pub/sub deduplication]:::warn
    n11[Redis]:::term
    n10 --> n11
    n12[Semantic similarity and vector retrieval]:::warn
    n13[Qdrant]:::term
    n12 --> n13
    n14[LLM traces prompts token and cost attribution]:::warn
    n15[Langfuse]:::term
    n14 --> n15
    n16[Workflow sequencing and retries]:::warn
    n17[n8n]:::term
    n16 --> n17
  end
  n1 --> n6
  subgraph Why Neo4j
    n18[Lineage is a traversal problem]:::term
    n19[Reachability is a first-class query]:::term
    n20[Schema-optional suits an evolving graph]:::term
    n21[Self-hostable in all modes]:::term
  end
  n1 --> n18

What it owns link

Per Tech Stack §7, Neo4j owns:

• Workflow and outcome lineage
• Agent influence and correlation networks
• Entity relationship graphs
• Cross-system dependency context

Its access pattern is async write/read at low-to-medium latency. Nothing in the OS blocks on a Neo4j write.

Lineage is a governance invariant, not a reporting feature link

This is the single most important thing about Neo4j’s position in this architecture. Core Principle 7 (Explainability and audit by design) requires that “the system must always be able to answer three questions about any action: what happened, why it happened, and under whose authority it happened.” The agent that answers those questions is the Audit & Lineage Agent (os-agt-008), and Neo4j is the store it reads.

Per the Agent Registry, os-agt-008 has decision_scope: recommend, an execution scope of “None — this agent is read-only by design”, systems_allowed of Supabase (read) · Neo4j (read) · Langfuse (read) · Grafana/Loki (read), and an authority boundary that reads: “The Audit & Lineage Agent is strictly read-only and always will be. It may never modify, redact, or amend audit records.”

The registry states the enforcing invariant separately: os-agt-008 must never appear in any agent’s tools_allowed list — it is a query target, not a callable tool. The consequence for this platform is direct. No agent can be handed the audit agent as a capability, so no agent can launder a write to lineage through it; lineage is written by the outcome path and read by one read-only agent, and those are different code paths. Neo4j is the read side of that separation. A deployment in which any workflow can both write and rewrite the graph has broken the invariant regardless of what the registry says.

What is actually in the graph link

The canonical write path is defined by the Outcome Spec: “The outcome envelope is the unit of lineage. Lineage links in Neo4j are written as source_outcome_id → target_outcome_id with the relation type.” Its persistence table is the normative statement of the model:

Two things follow from that table that are easy to get wrong.

First, Neo4j is not the system of record for lineage. The links originate in Supabase, which holds canonical relational truth; Neo4j holds the traversable projection of them. Losing the graph loses query capability, not evidence.

Second, the node taxonomy beyond the outcome is now specified for agents, workflows, and tools — ADR-OS-007 and the Agent Graph Data Model add Agent, Workflow, and Tool node types and the relationships between them, written by the same non-agent-mediated projection as the outcome node below. Entity and cross-system dependency modelling beyond that remains an open modelling decision this page does not make.

From correlation_id and causation_id to a traversable graph link

The Event Taxonomy Standard is what makes the graph constructible at all. Both fields are required in the 15-field event envelope:

Its rules do the rest of the work:

• “Lineage is mandatory.” Every event carries both. “An event without lineage is non-compliant.”
• “Causation chains form lineage.” causation_id links each event to its direct cause, correlation_id ties the whole flow together, and “together they reconstruct end-to-end lineage in Neo4j and are the basis for the Audit & Lineage Agent’s read-only reconstruction.”
• correlation_id is never regenerated mid-flow. When work crosses the n8n↔LangGraph boundary, both IDs “pass through unchanged”.
• Ordering is by causation_id chain first and timestamp second; consumers “must not assume wall-clock ordering across async boundaries”.

Mapped onto the property graph, the two identifiers do different jobs. causation_id is an edge: each one names exactly one direct predecessor, which is precisely a directed, typed relationship with a start node and an end node. correlation_id is a partition key: it scopes a traversal to a single flow and is the property you index and filter on so that a variable-length path expansion terminates inside one execution rather than wandering the whole graph.

That is why the ordering rule matters here more than anywhere else. Under async execution across n8n, LangGraph, Hookdeck and the event layer, timestamps do not reliably order a causal chain — the chain of causation_id edges does, and a graph traversal walks the chain directly instead of reconstructing it by sorting a log. Reconstruction is a path query, not a join.

Escalation paths are a reachability question link

The Agent Registry sets two rules that are graph rules in all but name:

• “Every agent must have at least one entry in escalation_path.”
• “Domain agents must declare their escalation_path explicitly and the terminal node must always be reachable via an OS control agent (os-agt-001 or os-agt-004).”

escalation_path is an ordered list of escalation targets — that is, a directed edge list — and “the terminal node must always be reachable” is a reachability predicate over the union of every agent’s list. Checked one registry entry at a time it is easy to satisfy and easy to break: an agent whose path terminates at another domain agent that itself terminates somewhere unreachable passes local inspection and fails the invariant. Expressed as a traversal it is a single query. Illustratively, given agent nodes and an escalation edge type:

MATCH (a:Agent)
WHERE NOT EXISTS {
  MATCH (a)-[:`escalated-to`*1..]->(t:Agent)
  WHERE t.agent_id IN ['os-agt-001', 'os-agt-004']
}
RETURN a.agent_id AS agent_without_reachable_terminal

The same graph carries the runtime escalation record, because escalated-to is one of the four canonical relation types on the outcome graph. So the declared escalation topology and the escalations that actually occurred are both traversable, which is what makes the “escalation compliance” dimension in the Agent Evaluation Spec — “did it escalate correctly when conditions required it?” — answerable from evidence rather than from the registry’s declaration alone.

Superseded by a canonical model. The illustrative query above and this section’s framing predate ADR-OS-007, which fixes the declared and observed halves of escalation as one relationship type — Agent-[:CAN_ESCALATE_TO {declared, observed_count, last_observed_at}]->Agent — rather than reasoning about the registry’s declared topology and the outcome graph’s escalated-to edges as two separately-traversed shapes. The Agent Graph Data Model has the full schema and write patterns, including the corrected reachability query and the new undeclared-escalation compliance check this page’s illustrative version could not express.

One practical note: the canonical relation names contributed-to, escalated-to and governed-by contain hyphens, which are not valid in an unquoted Cypher relationship type and must be backtick-escaped as above. Whether the stored types are the hyphenated names or a Cypher-idiomatic mapping such as ESCALATED_TO is an implementation decision no canonical document has recorded.

What it does not own link

Neo4j ships vector indexes in both editions, which makes the Qdrant boundary the one most likely to erode by accident. Semantic memory is Qdrant’s, per the Tech Stack’s non-overlapping responsibility split; a vector index in Neo4j scoped to lineage traversal is a different thing from a second semantic memory store, and collapsing them is a decision that would need to be made deliberately rather than discovered later.

How it is operated link

Reads and writes go through the Bolt driver under a fixed discipline, not ad hoc access: os-agt-008 opens read transactions only; os-agt-010 is the only agent that writes, and only through the NAMS client in bolt mode, never through hand-written Cypher issued from an agent node. There is no path by which an operator runs Cypher against a live instance as part of normal operation.

Community Edition ships no Prometheus metrics endpoint (see Deployment and licensing below), so operational health is inferred indirectly — Bolt connectivity checks and Grafana/Loki ingestion of driver-level errors and timeouts, rather than a native /metrics scrape.

Community Edition’s lack of online backup turns “wipe and rebuild from Postgres” from a disaster scenario into the routine, tested runbook: because Supabase is write-authoritative for every fabric projection this store holds (a domain pack’s operational graphs are rebuilt from the source the pack declares, per the Memory Fabric Spec §3.6), rebuilding the graph from agent_lineage_links, the Agent Registry (for the Agent/Workflow/Tool nodes and their PRODUCED/CAN_ESCALATE_TO/AUTHORIZED_FOR/OWNS_WORKFLOW edges added by ADR-OS-007), and the NAMS-owned entity records is the operational default. The runbook must project all three sources, in that order — a rebuild that stops at lineage links and NAMS entities silently omits the registry-derived elements and leaves agent-centric and reachability queries failing on an otherwise “complete” rebuild. The Memory Runtime Integration Guide §2.3 already requires this rebuild to be behaviour-identical as a correctness test — running it periodically as an operational drill is the same test, exercised on a schedule.

Community Edition’s single standard database means one Neo4j instance serves every domain pack that touches the graph tier — trading and art alike — as well as OS-level lineage traffic. Connection-pool sizing and query timeout budgets should assume that shared load rather than a dedicated instance per tenant or per pack.

The graph memory tier and the NAMS client link

Neo4j backs the graph memory tier in the Memory Fabric Spec, and it does so through a library rather than through hand-written Cypher: NAMS (neo4j-labs/agent-memory, Apache 2.0), adopted in ADR-OS-002 as a library over this Neo4j, not a platform row — the same position LangChain holds relative to the Layer 4 runtime.

What it contributes is a typed ontology the OS never specified for itself. NAMS models long-term memory as a POLE+O graph (Person, Organization, Location, Event, plus other objects) and records agent reasoning as AgentStep and ToolCall nodes joined to the entities they affected by explicit :TOUCHED edges. That last piece is the interesting one: reasoning-to-entity lineage is one of the two memory kinds the Academy identifies as having no framework primitive anywhere, and :TOUCHED is a concrete answer to it — the missing link between an Outcome Envelope and the business state it moved.

Four constraints keep it inside the stack’s rules:

• Self-hosted bolt mode only. The client auto-detects a hosted backend when MEMORY_API_KEY is set, so that variable must be unset in every deployment mode. The hosted memory.neo4jlabs.com service is proprietary SaaS and is rejected on Principle 11, the same ground as LangSmith.
• Its vector index is scoped to entity resolution. NAMS ships its own vector search. Left enabled as a general retrieval path it would duplicate Qdrant, which remains the single semantic substrate at Layer 7.
• Writes go through the control plane. The client can write to Neo4j directly; from an agent graph it must not. Every NAMS write is issued by the Memory Curator (os-agt-010) after the Memory Access Broker (os-agt-012) has resolved scope. A NAMS call from an arbitrary agent node is a governance bypass even though the data lands in the right store.
• Its MCP server is governed. NAMS exposes 6–16 memory tools over MCP. They are subject to mcp_tool_policy, and the read-only Cypher tool is not exposed by default — an ungoverned Cypher path would sidestep both the broker and the tier model.

Lineage ownership is unchanged by any of this: Postgres remains write-authoritative for lineage links and Neo4j remains the queryable projection. What NAMS adds sits alongside that, in the entity and reasoning half of the tier.

The NAMS requirement — verified against Community Edition. NAMS requires Neo4j 5.20+ vector indexes, and those are available in Community Edition. The Operations Manual’s per-edition feature table lists vector indexes under “Indexes and constraints” with Community Edition ticked, and the Neo4j 5 changelog attaches no edition restriction to their introduction (5.11.0), the vector-2.0 provider (5.18.0), or quantization (5.23.0). The graph tier is therefore satisfiable on a Community deployment in all three modes — this was the open question and it is now closed.

The Community Edition limits that reach this tier are the general ones catalogued in Deployment and licensing below — single database, no property existence/type/key constraints, offline-only backup — read together with two NAMS-specific consequences:

• Database naming. The NAMS client’s database= parameter must be neo4j on Community, not a dedicated name; per-tenant database isolation inside one instance is unavailable. Tenant separation in the graph tier is therefore enforced entirely above the database, by the tenant-first scope tuple and the Memory Access Broker (os-agt-012).
• Entity validation. The POLE+O entity schema can enforce that an entity is unique, but not — at the database — that its required properties are present or correctly typed. That validation moves into the control plane: the Memory Curator (os-agt-010) checks it before commit.

Open item. NAMS remains an experimental Neo4j Labs project with community support and no SLA, so the dependency must be version-pinned and carry an exit path.

Why Neo4j link

• Lineage is a traversal problem. “What happened, why, and under whose authority” is a variable-length path over causal edges. In a relational store that is recursive self-joins over an event table; in a property graph it is one MATCH pattern. Neo4j’s documentation makes exactly this comparison against SQL.
• Reachability is a first-class query. The escalation-path invariant is a reachability check. Nothing else in the stack answers it natively.
• Directed, typed edges refuse to hold an ambiguous causal claim. A relationship “must always have a start node, an end node, and exactly one type” and “must have a direction”. A causal edge that does not say which way causality runs cannot be stored.
• Schema-optional suits an evolving graph. The node taxonomy beyond outcomes is still open. Neo4j is “schema optional”, so the lineage graph can be extended with new node labels and relationship types without a migration, while constraints can be added later once the model settles.
• Self-hostable in all modes. Community Edition is open source under GPLv3 and runs as a single instance under Docker, which is what Modes 2 and 3 require — with the significant caveats below.

Deployment and licensing link

Self-hosting. Documented install paths are Linux, macOS and Windows, plus Docker as an “installation-free option”. Neo4j AuraDB is the fully managed alternative and is not applicable to Modes 2 or 3.

Licence. Per the README.asciidoc in the official neo4j/neo4j repository, which Neo4j’s own Legal Terms page links to as the Community Edition licence:

• “Neo4j Community Edition is an open source product licensed under GPLv3.”
• “Neo4j Enterprise Edition includes additional closed-source components not available in this repository and requires a commercial license from Neo4j or one of its affiliates.”

The repository LICENSE.txt is the GNU General Public License version 3, and the edition feature table marks “Open source under GPLv3” as a Community Edition row only.

Community Edition limitations. Taken directly from the Operations Manual’s per-edition feature table, these are Enterprise-only:

Community Edition does get ACID transactions, Cypher, the Bolt protocol and official drivers, APOC core, full-text and vector indexes, property uniqueness constraints, offline import, and offline backup by dump.

Three of those exclusions bear directly on this architecture:

1. No role-based access control. The Operations Manual’s authentication and authorization chapter is marked Enterprise Edition; “a limited set of user management functions are also available in Community Edition.” The built-in roles table is explicit about where the line falls: in Community Edition you can create and delete users and change passwords, but create/drop roles, assign/remove role to/from user, and grant/deny/revoke privileges are all unavailable. Every authenticated Community Edition user therefore holds full read and write access to the graph. The read-only guarantee for os-agt-008 cannot be enforced at the database in Community Edition — it is enforced only by the registry invariant and the tool layer above it.
2. No metrics endpoint. The entire Metrics chapter is marked Enterprise Edition, covering Prometheus, Graphite, JMX and CSV export alike. Against the OS invariant that every workflow must be observable end-to-end, the Layer 7 graph store in Community Edition exports no operational metrics to the Layer 10 Grafana LGTM stack by the documented path.
3. No online backup and no multi-database. Community Edition backup is the offline dump, which means taking the store down; and there is one database beyond system, so per-tenant or per-domain-pack database isolation inside one Neo4j instance is not available. For the graph memory tier above, this is mitigated structurally rather than operationally: Supabase is write-authoritative for the memory fabric, so the Neo4j entity projection is rebuilt from memory_records rather than restored — the same rebuild-from-Postgres property the Memory Fabric Spec already requires as a correctness test.
4. No property existence, type or key constraints. Only uniqueness constraints are available in Community Edition. The graph tier’s POLE+O schema (via NAMS) can therefore enforce that an entity is unique, but not that its required properties are present or correctly typed — see the note above; that validation lives in the control plane rather than at the database.

Air-gapped (Mode 3) note. “By default, Neo4j Community Edition (CE) and Neo4j Enterprise Edition (EE) report a small amount of usage data,” including system database ID, version, edition, node/relationship/label/property counts, store size and server IP address, sent every 24 hours. Reporting “can be turned off with the configuration setting dbms.usage_report.enabled=false”. This must be set explicitly for Mode 3.

Open item. Tech Stack §7 records only that “Neo4j Community Edition is open source under GPL3. Enterprise features require Neo4j Enterprise licence,” and the same document states that every component in the stack is open source. That is accurate as far as it goes and incomplete for production. Three points need an explicit decision. (a) Enterprise Edition is not open source — it “includes additional closed-source components” and requires a commercial licence — so any Enterprise-dependent deployment breaks the all-open-source claim. (b) The Enterprise-only feature list includes role-based access control, online backup and the metrics endpoint, which are governance and observability features, not scale features; in particular Community Edition cannot enforce read-only database access for os-agt-008, so the read-only invariant is an OS-layer guarantee with no database-level backstop. (c) Community Edition’s GPLv3 copyleft is material to any deployment model where Synedrix OS is delivered to a customer as a product, and Neo4j’s Legal Terms page lists Community Edition under “Developer Offerings”, described as “generally provided for free and internal, non-production use, but the specific terms of each linked license define the full permitted usage”. Note also that the Deployment Model Spec component inventory already carries a narrower caveat (“Enterprise licence required for clustering”) which understates the same gap. This needs a decision and a correction to the canonical stack document — it is not resolved by this page.

Official documentation link

• Neo4j documentation home
• Operations Manual → Introduction — editions and the full per-edition feature comparison table
• Getting Started → What is a graph database
• Getting Started → Graph database concepts — nodes, labels, relationships, properties, traversals, schema
• Cypher Manual → Overview — Cypher against SQL
• Operations Manual → Installation
• Operations Manual → Authentication and authorization — Enterprise Edition; Community Edition limits
• Operations Manual → Built-in roles — the “Available in Community Edition” column
• Operations Manual → Metrics — Enterprise Edition
• Usage data report — what is reported and how to disable it
• Neo4j Legal Terms — agreements governing each offering
• neo4j/neo4j repository — LICENSE.txt (GPLv3) and the licensing section of README.asciidoc

Related Synedrix OS documents link

• Neo4j Implementation Guide — Per-agent use-case catalog, worked Cypher, and the compliance checklist for the three agents with direct access.
• Agent Graph Data Model — The Agent/Workflow/Tool node schema and the CAN_ESCALATE_TO relationship this page’s escalation-reachability section now defers to.
• Memory Fabric Spec — The graph tier this store backs, and the lifecycle its records move through.
• ADR-OS-002 — The NAMS-as-library decision and the rejection of the hosted service.
• Synedrix OS Tech Stack — normative platform responsibilities; §7 covers Neo4j, and the Layered Truth Summary assigns it the graph / lineage truth class.
• Agent Registry — os-agt-008 (Audit & Lineage Agent), the read-only authority boundary, the tools_allowed invariant, and the escalation-path rules.
• Event Taxonomy Standard — the event envelope, correlation_id and causation_id, and the rule that causation chains form lineage.
• Outcome Spec — the outcome envelope as the unit of lineage, the Supabase → Neo4j projection, and the four canonical relation types.
• Layer Taxonomy Table — Layer 7 definition and platform mapping.
• Agent Evaluation Spec — escalation compliance and error-rate dimensions evaluated against lineage evidence.
• Core Principles — Principle 7 (Explainability and audit by design), the requirement lineage exists to satisfy.
• Deployment Model Spec — the three modes, the open-source component inventory, and the air-gapped checklist.

Synedrix OS · Platform reference · Neo4j