A graph-native memory system for AI agents. Store conversations, build knowledge graphs, and let your agents learn from their own reasoning -- all backed by Neo4j.
| Short-Term Memory | Long-Term Memory | Reasoning Memory |
|---|---|---|
| Conversations & messages | Entities, preferences, facts | Reasoning traces & tool usage |
| Per-session history | Knowledge graph (POLE+O model) | Learn from past decisions |
| Vector + text search | Entity resolution & dedup | Similar task retrieval |
Plus: multi-stage entity extraction (spaCy / GLiNER / LLM), relationship extraction (GLiREL), background enrichment (Wikipedia / Diffbot), geospatial queries, MCP server with 16 tools, and integrations with LangChain, Pydantic AI, Google ADK, Strands, CrewAI, and more.
v0.2: adopt an existing Neo4j graph as long-term memory (client.schema.adopt_existing_graph(...)), multi-tenant scoping (user_identifier=), fire-and-forget buffered writes (client.buffered.submit(...)), consolidation primitives (client.consolidation.dedupe_entities(...)), an eval harness (client.eval.run(suite)), and explicit :TOUCHED audit edges from reasoning steps to entities.
New in v0.3 (pluggable providers): bring your own model. MemorySettings.embedding and MemorySettings.llm now accept a provider-string shorthand ("anthropic/claude-3-5-sonnet-latest", "BAAI/bge-small-en-v1.5") or a Provider instance. Native adapters for OpenAI, Anthropic, Bedrock, Vertex AI, and sentence-transformers; LiteLLM universal fallback covers 100+ providers (Cohere, Voyage, Groq, Together, Mistral, Ollama, ...). Existing EmbeddingConfig/LLMConfig users keep working with a one-time deprecation warning — full migration guide at migrate-to-v0.3.
neo4j-labs/agent-memory ships two SDKs with the same memory model, both
backed by the NAMS
hosted service. Pick the one that matches your stack — mixed Python +
TypeScript agents read and write the same memory.
| Language | Package | Install | Docs |
|---|---|---|---|
| Python | neo4j-agent-memory |
pip install neo4j-agent-memory |
Python SDK docs |
| TypeScript | @neo4j-labs/agent-memory |
npm install @neo4j-labs/agent-memory |
TypeScript SDK docs |
The Python SDK lives at the repo root (src/neo4j_agent_memory/,
examples/); the TypeScript SDK lives at typescript/. The two SDKs are
versioned and released independently — python-v* tags publish to PyPI,
typescript-v* tags publish to npm. Cross-language behavioral conformance
is enforced by the
agent-memory-tck
spec suite, which consumes both SDKs as external dependencies.
Prerequisites: A running Neo4j instance (Neo4j Desktop, Docker, or Neo4j Aura for a free cloud database).
Give any MCP-compatible AI assistant (Claude Desktop, Claude Code, Cursor, VS Code Copilot) persistent memory backed by a knowledge graph:
# Run directly with uvx (no install needed)
uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>
Claude Code:
claude mcp add neo4j-agent-memory -- \
uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"neo4j-agent-memory": {
"command": "uvx",
"args": ["neo4j-agent-memory[mcp]", "mcp", "serve", "--password", "your-password"],
"env": {
"OPENAI_API_KEY": "sk-..."
}
}
}
}
neo4j-agent-memoryis async-only. Every memory operation is a coroutine. From a script, wrap your entry point inasyncio.run(...)as shown below. From a notebook, prefix calls withawait. From a framework that runs its own loop (FastAPI, PydanticAI, Google ADK), just useawaitinside your handler. There is no synchronous wrapper — by design.
import asyncio
from neo4j_agent_memory import MemoryClient, MemorySettings
async def main():
# v0.3+: pass the model as a provider-prefixed string. Swap in
# "openai/...", "bedrock/...", "vertex_ai/...", or any of the 100+
# LiteLLM-supported providers. Defaults to a working OpenAI setup
# when llm/embedding are omitted, for v0.2 compatibility.
settings = MemorySettings(
neo4j={"uri": "bolt://localhost:7687", "password": "your-password"},
llm="anthropic/claude-3-5-sonnet-latest",
embedding="openai/text-embedding-3-small",
)
async with MemoryClient(settings) as memory:
# Store a conversation message
await memory.short_term.add_message(
session_id="user-123", role="user",
content="Hi, I'm John and I love Italian food!"
)
# Build the knowledge graph
await memory.long_term.add_entity("John", "PERSON")
await memory.long_term.add_preference(
category="food", preference="Loves Italian cuisine"
)
# Get combined context for an LLM prompt
context = await memory.get_context(
"What restaurant should I recommend?",
session_id="user-123"
)
print(context)
asyncio.run(main())Already using
EmbeddingConfig/LLMConfig? It still works — you'll just see a one-timeDeprecationWarningat construction. See the v0.3 migration guide.
Scaffold a complete full-stack AI application with built-in context graph memory:
uvx create-context-graph
This generates a ready-to-run project with a FastAPI backend, Next.js frontend, Neo4j knowledge graph, and neo4j-agent-memory pre-configured. See create-context-graph.dev for details.
pip install neo4j-agent-memory # Core
pip install neo4j-agent-memory[openai] # + OpenAI native adapter
pip install neo4j-agent-memory[anthropic] # + Anthropic native adapter
pip install neo4j-agent-memory[bedrock] # + AWS Bedrock native adapter
pip install neo4j-agent-memory[sentence-transformers]# + local HF embeddings
pip install neo4j-agent-memory[litellm] # + LiteLLM universal fallback (100+ providers)
pip install neo4j-agent-memory[mcp] # + MCP server
pip install neo4j-agent-memory[langchain] # + LangChain
pip install neo4j-agent-memory[all] # Everything except heavy local ML
pip install neo4j-agent-memory[full] # Everything including spaCy, GLiNER, sentence-transformers, instructorProvider extras follow native-first resolution: with both [openai] and [litellm] installed, an "openai/..." model uses the native adapter; an unsupported provider like "groq/..." falls through to LiteLLM. See Bring your own model for details.
| Framework | Extra | Import |
|---|---|---|
| LangChain | [langchain] |
from neo4j_agent_memory.integrations.langchain import Neo4jAgentMemory |
| Pydantic AI | [pydantic-ai] |
from neo4j_agent_memory.integrations.pydantic_ai import MemoryDependency |
| Google ADK | [google-adk] |
from neo4j_agent_memory.integrations.google_adk import Neo4jMemoryService |
| Strands (AWS) | [strands] |
from neo4j_agent_memory.integrations.strands import context_graph_tools |
| CrewAI | [crewai] |
from neo4j_agent_memory.integrations.crewai import Neo4jCrewMemory |
| LlamaIndex | [llamaindex] |
from neo4j_agent_memory.integrations.llamaindex import Neo4jLlamaIndexMemory |
| OpenAI Agents | [openai-agents] |
from neo4j_agent_memory.integrations.openai_agents import ... |
| Microsoft Agent | [microsoft-agent] |
from neo4j_agent_memory.integrations.microsoft_agent import Neo4jMicrosoftMemory |
The MCP server exposes memory capabilities as tools for AI assistants.
# stdio transport (Claude Desktop, Claude Code)
neo4j-agent-memory mcp serve --password <pw>
# SSE transport (network deployment)
neo4j-agent-memory mcp serve --transport sse --port 8080 --password <pw>
# Core profile (fewer tools, less context overhead)
neo4j-agent-memory mcp serve --profile core --password <pw>
# Session continuity across conversations
neo4j-agent-memory mcp serve --session-strategy per_day --user-id alice --password <pw>Tool Profiles:
| Profile | Tools | Description |
|---|---|---|
| core | 6 | Essential read/write: memory_search, memory_get_context, memory_store_message, memory_add_entity, memory_add_preference, memory_add_fact |
| extended (default) | 16 | Full surface adding: conversation history, entity details, graph export, relationship creation, reasoning traces, observations, read-only Cypher |
See the MCP tools reference for full details.
See examples/README.md for the full index. Highlights:
Full-stack reference apps
| Example | Framework | Description |
|---|---|---|
| Lenny's Podcast Memory Explorer | PydanticAI | Flagship demo: 299 podcast episodes, knowledge graph, geospatial maps, Wikipedia enrichment |
| Full-Stack Chat Agent | PydanticAI | News research assistant with NVL graph visualization and auto-preference detection |
| AWS Financial Advisor | Strands (AWS) | Multi-agent KYC/AML compliance with Bedrock and reasoning trace audit trails |
| Google Cloud Financial Advisor | Google ADK | Multi-agent compliance with Vertex AI embeddings and real-time SSE streaming |
| Microsoft Retail Assistant | Microsoft Agent | Shopping recommendations with GDS algorithms, entity deduplication, and context providers |
v0.2 feature demos (small, single-purpose, no LLM required)
| Example | Demonstrates |
|---|---|
existing-graph/ |
client.schema.adopt_existing_graph(...) — layer the library over a graph you already have in production |
buffered-writes/ |
write_mode="buffered", client.buffered.submit(...), client.flush() — agent responses unblocked from Neo4j round-trips |
audit-trail/ |
Explicit :TOUCHED edges from reasoning steps to entities, plus TraceOutcome for indexable audit queries |
eval-harness/ |
client.eval.run(EvalSuite(...)) — labelled regression tests for memory quality |
Tooling & extraction
| Example | Framework | Description |
|---|---|---|
no_llm/ |
Standalone | Run with llm=None plus local sentence-transformers + spaCy/GLiNER (air-gapped, deterministic) |
| Domain Schema Examples | Standalone | 8 GLiNER2 extraction scripts with factory pattern, batch extraction, streaming, and GLiREL relations |
| Google Cloud Integration | Google ADK | Progressive tutorial: Vertex AI, ADK, MCP server, and MemoryIntegration with session strategies |
| Google ADK Demo | Google ADK | Standalone demo of Neo4jMemoryService with session storage, search, and preferences |
Most examples pin neo4j-agent-memory>=0.4.0 (the NAMS-capable release). TypeScript examples pin @neo4j-labs/agent-memory@^0.3.0. See each example's pyproject.toml / package.json for the exact pin.
Full documentation at neo4j.com/labs/agent-memory
- Tutorials -- Build your first memory-enabled agent
- How-To Guides -- Entity extraction, deduplication, enrichment, integrations
- API Reference -- Configuration, CLI, MCP tools
- Concepts -- POLE+O model, memory types, extraction pipeline
git clone https://github.com/neo4j-labs/agent-memory.git
cd agent-memory/neo4j-agent-memory
uv sync --group dev
make test-unit # Run unit tests
make check # Lint + format + typecheckSee CONTRIBUTING.md for the full development guide, CI pipeline, and documentation guidelines.
- Python 3.10+
- Neo4j 5.20+ (for vector indexes)
Apache License 2.0
This is a Neo4j Labs project -- community supported, not officially backed by Neo4j. Community Forum | GitHub Issues | Documentation | TypeScript SDK