neo4j-agent-memory 0.2.1

A comprehensive memory system for AI agents using Neo4j

Neo4j Agent Memory

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.

What It Does

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.

New in v0.2 (in development on the adopt-existing-graph branch): 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.

Quick Start

Prerequisites: A running Neo4j instance (Neo4j Desktop, Docker, or Neo4j Aura for a free cloud database).

Option A: MCP Server (zero code)

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-..."
      }
    }
  }
}

Option B: Python API

neo4j-agent-memory is async-only. Every memory operation is a coroutine. From a script, wrap your entry point in asyncio.run(...) as shown below. From a notebook, prefix calls with await. From a framework that runs its own loop (FastAPI, PydanticAI, Google ADK), just use await inside your handler. There is no synchronous wrapper — by design.

import asyncio
from neo4j_agent_memory import MemoryClient, MemorySettings

async def main():
    settings = MemorySettings(
        neo4j={"uri": "bolt://localhost:7687", "password": "your-password"}
    )

    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())

Option C: Full-Stack App with create-context-graph

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.

Installation

pip install neo4j-agent-memory                  # Core
pip install neo4j-agent-memory[openai]          # + OpenAI embeddings
pip install neo4j-agent-memory[mcp]             # + MCP server
pip install neo4j-agent-memory[langchain]       # + LangChain
pip install neo4j-agent-memory[all]             # Everything

See the getting started guide for all extras (Vertex AI, Bedrock, spaCy, GLiNER, Google ADK, Strands, etc.).

Framework Integrations

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

MCP Server

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.

Examples

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

Examples currently pin neo4j-agent-memory>=0.1.0. The v0.2 demos use APIs that ship in v0.2 (in development on the adopt-existing-graph branch); pins will move to >=0.2.0 once that release lands.

Documentation

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

Development

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 + typecheck

See CONTRIBUTING.md for the full development guide, CI pipeline, and documentation guidelines.

Requirements

• Python 3.10+
• Neo4j 5.20+ (for vector indexes)

License

Apache License 2.0

---

This is a Neo4j Labs project -- community supported, not officially backed by Neo4j. Community Forum | GitHub Issues | Documentation