neo4j-labs/agent-memory: a graph-native memory layer for agents, with a hosted backend and an MCP server

What neo4j-labs/agent-memory solves, and who it is aimed at

Most agent frameworks give you a message list and a vector index. That covers recall of similar text. It does not cover the questions that arrive later: which person is this, what did they tell us last month, which tool call produced the answer we gave, and which earlier decisions resemble this one. neo4j-labs/agent-memory models those as graph structure. The README splits memory into three stores. Short-term memory holds conversations and messages with per-session history and vector plus text search. Long-term memory holds entities, preferences and facts in a knowledge graph that follows the POLE+O model, with entity resolution and deduplication. Reasoning memory holds reasoning traces and tool usage, so an agent can retrieve similar tasks it has handled before. The intended reader is a developer already building an agent that has to remember across sessions and across users, and who is willing to run or pay for a graph database to get that. It is published under Apache-2.0 by Neo4j Labs, carries an Experimental status badge and Community support, and the PyPI classifier says Development Status 4 - Beta. Treat that labelling as the project's own statement about where it sits, not as a maturity claim.

How the graph memory model and extraction pipeline fit together

The write path in the self-hosted configuration is a pipeline. A message goes into short-term memory under a session_id. Entity extraction then runs in multiple stages, and the README names the options: spaCy, GLiNER or an LLM, with relationship extraction handled by GLiREL. Background enrichment can pull from Wikipedia or Diffbot. Extracted entities are resolved and deduplicated before landing in the long-term graph, which is the step that keeps "John" in one session from becoming a second node for the same person in the next. Reasoning steps write explicit :TOUCHED audit edges to the entities they used, which is what makes a later question like "why did you recommend this" answerable by traversal rather than by re-reading a transcript. On the hosted NAMS backend the same model applies but embedding and extraction run server-side, and the README warns that extraction is asynchronous there: call await memory.long_term.wait_for_extraction(...) before asserting on freshly extracted entities. That difference is the single most likely source of confusion when moving code between the two backends, and it is documented rather than hidden. The data model is illustrated in the repository under img/memory-graph-model.png and img/extraction-pipeline.png.

Installing neo4j-agent-memory and a first session

The fastest documented path is the hosted NAMS service. You sign up at memory.neo4jlabs.com, copy an API key, and install the SDK with the nams extra. Setting MEMORY_API_KEY makes the backend auto-select NAMS, so there is no Neo4j instance to run.

pip install "neo4j-agent-memory[nams]"
export MEMORY_API_KEY=nams_...

The README's quick-start script then writes a message, adds an entity, and asks for context. The MemoryClient is an async context manager and reads the key from the environment.

import asyncio
from neo4j_agent_memory import MemoryClient

async def main():
    async with MemoryClient() as memory:
        await memory.short_term.add_message(
            session_id="user-123", role="user",
            content="Hi, I'm John and I love Italian food!",
        )
        await memory.long_term.add_entity("John", "PERSON")
        context = await memory.get_context(
            "What restaurant should I recommend?", session_id="user-123",
        )
        print(context)

asyncio.run(main())

What you should see is the printed context assembled from the session history and the graph. On NAMS, entity extraction is asynchronous, so call wait_for_extraction before checking that "John" exists as a node. If you would rather not write code at all, the MCP server path runs through uvx and exposes the memory to Claude Desktop, Claude Code, Cursor or VS Code Copilot; the README shows a claude mcp add line and a claude_desktop_config.json block with the command uvx and args ["neo4j-agent-memory[mcp]", "mcp", "serve", "--password", "your-password"]. The TypeScript SDK installs separately with npm install @neo4j-labs/agent-memory.

Where the design costs you: extraction, dependencies and the two backends

The graph model is not free. Entities have to be extracted and resolved before the long-term store is useful, and the README's own options for that are a spaCy or GLiNER model or an LLM call. Choosing the LLM path means every message can trigger model spend, and choosing the local path means carrying model dependencies and accepting their accuracy. Neither is documented here with latency or cost figures, and the repository does not publish them in the README, so you have to measure on your own traffic. The second cost is operational. The self-hosted path needs a Neo4j instance, and the dependency floor in pyproject.toml is neo4j>=5.20,<7, deliberately kept at 5.20 so deployments on the 5.x line are not stranded. The hosted path removes the database but adds a vendor and an API key, and the README does not document data residency, retention or pricing for NAMS, so those are questions for Neo4j rather than for the repository. The third case is simply the wrong tool: if your retrieval problem is "find the passage most similar to this question" over a document set, a vector index is less machinery, and the entity resolution and audit edges here buy you nothing. The project also carries an Experimental badge, which is a statement about support expectations rather than about code quality, and teams that need a supported product should weigh it accordingly.

How this differs from Mem0 and from plain retrieval-augmented generation

The useful comparison is with Mem0, which the search data shows people asking about. Both projects extract facts from conversations and store them for later retrieval, and both offer an API that sits between your agent and the storage layer. The difference is the storage model. Mem0's documented approach centres on extracted memories retrieved by similarity, which answers "what do we know that is close to this query". neo4j-labs/agent-memory puts the same extracted facts into a property graph with typed relationships, then adds entity resolution, multi-tenant scoping through user_identifier=, and audit edges from reasoning steps to the entities they touched. That makes traversal queries possible: walk from a person to their preferences to the sessions that produced them, or from a past reasoning trace to the entities it used. The price is that you are now operating a graph database, or paying for one. Against plain RAG the split is sharper still. RAG over a document corpus is a read-mostly index built once and queried many times; this system is written to on every turn, and its quality depends on extraction that runs at write time. If your agent only needs to quote documents, RAG wins on simplicity. If it needs to accumulate a model of a user across months, the graph is the part that carries the value.

Maintenance, upgrade cost and what Apache-2.0 means here

The last push to the default branch was on 2026-09-10, and the repository is not archived. The most recent release listed is v0.4.0 from 2026-05-21, while pyproject.toml declares version 0.6.0, so the version in the repository is ahead of the last tagged release. That gap matters if you install from PyPI expecting the features described in the README: check which version you actually get before relying on a specific API. The two SDKs are versioned and released independently, with python-v* tags publishing to PyPI and typescript-v* tags publishing to npm, so a Python upgrade does not imply a matching TypeScript upgrade. Cross-language behaviour is checked by the separate agent-memory-tck conformance suite, which consumes both SDKs as external dependencies; that is the mechanism you would watch when upgrading one language and not the other. The Apache-2.0 licence permits commercial use and modification, and the repository ships a LICENSE file at the root. It does not settle what the hosted NAMS service's terms are, because that is a separate service agreement and not a code licence. Nothing here is legal advice; if you are embedding this in a product, read the licence text and the NAMS terms yourself. Development dependencies are grouped behind Makefile targets such as make install, make install-all and make test, which is convenient for contributors and irrelevant to runtime cost.

Editorial conclusion

Adopt it when your agents need relationships between remembered facts, not just nearest-neighbour lookup: entity resolution, per-user scoping, reasoning traces you can query, and an existing Neo4j graph you want to reuse as long-term memory. Do not adopt it if you want a single pip install with no database and no provider keys, or if a flat vector index over chat history already answers your retrieval questions. Before committing, verify what the README does not state: whether NAMS pricing and data-retention terms fit your use case, how extraction latency behaves on your own message volume, and whether the experimental status badge is acceptable for the environment you are deploying into.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. neo4j-labs/agent-memory on GitHub
3. Project website
4. README
5. Releases