Neo4j Agent Memory: Graph Recall Without Losing Source of Truth

Neo4j agent memory is a strong fit when an agent must remember relationships, not merely retrieve similar text. A support agent may need to connect a customer, contract, incident, product, and previous tool call. A coding agent may need to traverse services, owners, migrations, and decisions. Neo4j can represent those links directly and combine graph traversal with semantic search.

But a memory graph and a source of truth are different things. Extracted entities are excellent retrieval aids; approved architecture decisions and runbooks should often remain files your team can read, edit, diff, and self-host. A practical design uses Neo4j for connected recall and a readable wiki such as Meshnote for canonical project knowledge exposed to any MCP-compatible agent.

What the leading Neo4j agent memory pages cover

The three leading results are Neo4j's Agent Memory documentation, the neo4j-labs/agent-memory repository, and Neo4j's NAMS product tour. Together they explain the three-layer model: short-term conversations, long-term entities and relationships, and application-recorded reasoning traces. They cover Python and TypeScript SDKs, hosted NAMS and direct Bolt backends, entity extraction and resolution, Cypher, framework integrations, and MCP setup.

The current repository documents Python package neo4j-agent-memory==0.7.0 and TypeScript package @neo4j-labs/agent-memory@0.5.0. Its self-hosted Python MCP server exposes a six-tool core profile or a 16-tool extended profile on Bolt; backend capabilities differ on NAMS. The June 2026 NAMS tour adds useful operational detail: extraction, embedding, deduplication, observations, and reflections run asynchronously, while provenance connects messages, entities, traces, and tool calls.

Those pages explain how to store and query memory. What they do not provide is a clear authority boundary between machine-extracted graph facts and human-approved project truth, followed by a drift-and-exit test. That is the gap this guide fills.

Choose the memory shape before the product

System	Best at	Trade-off
Neo4j Agent Memory / NAMS	Connected entities, graph traversal, ontology-shaped extraction, and traceable tool activity	You must operate or buy a graph service and govern extraction, identity, and scopes
Mem0 or Zep	Application-facing conversational memory with compact retrieval APIs; Zep's Graphiti emphasizes temporal relationships	Canonical wording and correction semantics still need an explicit policy
Letta	Stateful agents whose memory blocks are part of the runtime	The agent runtime becomes a larger architectural commitment
Readable Markdown over MCP	Approved decisions, runbooks, portability, review, and cross-agent sharing	Relationships and high-volume conversational recall are less automatic

Native ChatGPT or Claude memory is convenient for personal preferences and continuity inside that product. It is usually the wrong authority for team deployment rules because another agent cannot reliably inspect, version, or reuse it. For more detail on storage trade-offs, see vector memory vs readable memory and the broader persistent agent memory architecture.

A two-layer architecture that stays correct

Record observations in Neo4j. Store messages, extracted entities, relationships, and application-supplied traces. Treat extraction confidence as evidence quality, not truth.
Promote only durable knowledge. A reviewer or constrained agent turns a verified observation into a short Markdown page: decision, date, owner, evidence, and superseded rule.
Retrieve both layers. Query Neo4j to discover relevant people, services, incidents, and relationships; read the canonical page before taking an irreversible action.
Correct at the authority layer. Update the readable page first. Then repair or annotate derived graph nodes so retrieval does not keep surfacing stale claims.
Rebuild derived state. Your graph export is valuable, but your operational knowledge should remain understandable if the extraction pipeline or agent framework disappears.

This is the same boundary used in a good codebase memory MCP architecture: generated structure answers “what is connected?” while reviewed files answer “what must we do?”

Working setup: give Claude Code both memories

Neo4j's documented Bolt path requires an AuraDB or compatible Neo4j database, uvx, and any model-provider key needed for extraction. Keep secrets in environment variables, then add its stdio MCP server:

export NEO4J_URI='neo4j+s://INSTANCE.databases.neo4j.io'
export NEO4J_USER='neo4j'
export NEO4J_PASSWORD='replace-locally'
export OPENAI_API_KEY='replace-locally'

claude mcp add neo4j-agent-memory -- \
  uvx --from 'neo4j-agent-memory[mcp,openai]==0.7.0' \
  neo4j-agent-memory mcp serve --backend bolt --user "$NEO4J_USER"

Next, create a Meshnote API key and add the hosted MCP endpoint. The shell expands the variable before Claude Code stores the header; never commit the populated configuration:

export MESHNOTE_API_KEY='mnk_replace_with_your_key'
claude mcp add --transport http meshnote https://meshnote.io/mcp \
  --scope user \
  --header "Authorization: Bearer $MESHNOTE_API_KEY"

claude mcp list

Create a project and put the policy in its schema: Neo4j observations may suggest knowledge, but deployment rules become authoritative only after they are written to a reviewed wiki page with a source. Meshnote is agent-agnostic, so Claude Code, Cursor, Codex, and other MCP clients can work from the same Markdown rather than separate native memories.

The six-case authority-and-drift drill

Run this before trusting either layer in production. Use a harmless test rule such as “staging deploys happen Tuesday,” then record the actual IDs and files created.

Persistence: store the statement through Neo4j memory, start a new client session, and verify it can be retrieved.
Promotion: write a sourced Markdown page that labels the statement provisional. Confirm a second MCP client can read the exact text.
Correction: change the approved rule to Wednesday. The next answer must prefer the page and identify Tuesday as stale rather than blend both values.
Scope: repeat the query from another user or project. It must not retrieve the test rule unless access was explicitly granted. Conversation IDs are selectors, not authorization boundaries.
Provenance and drift: require the answer to cite both the graph observation and canonical page. Delete or alter the graph relationship, then confirm the canonical rule still works and the discrepancy is visible.
Exit: export the graph, disconnect Neo4j, and ask a different MCP client to reconstruct the current rule, owner, and evidence from Markdown alone.

A pass means the graph improves discovery without silently becoming the final authority. A failure tells you exactly which contract is missing: precedence, isolation, correction, provenance, or portability. This test is more useful than a generic recall score because it exercises the operational failures that cause agents to take wrong actions.

When Neo4j is worth the complexity

Choose graph memory when multi-hop questions are central: which incidents involved services owned by a team, which tool calls changed an entity, or what relationships were valid at a given point. Prefer a simpler memory API when you mostly retrieve user preferences or summaries. Prefer readable files when the dominant requirement is reviewed project truth.

The hybrid becomes compelling when all three matter. Neo4j finds connected evidence; Markdown states the approved rule; MCP lets multiple agents use both without being tied to one model. If that boundary matches your workload, Start syncing — $8/mo. Teams that need to own the deployment can choose Self-hosted for teams from $10/seat/month.