neo4j-agent-memory 0.1.0

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.

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

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

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 installation 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.

Demo

The Lenny's Podcast Memory Explorer loads 299 podcast episodes into a searchable knowledge graph with an AI chat agent, interactive graph visualization, geospatial map view, and Wikipedia-enriched entity cards.

Documentation

Full documentation at neo4j-agent-memory.vercel.app

• 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.x (5.11+ recommended 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