Neo4j Agent Memory (Python SDK)

A graph-native memory system for AI agents. Store conversations, build knowledge graphs, and record and retrieve application-supplied reasoning — backed either by the hosted NAMS service (zero infrastructure) or your own Neo4j.

This is the Python SDK. A TypeScript SDK with the same memory model ships from the same repository as @neo4j-labs/agent-memory.

Neo4j Labs project

This project is part of Neo4j Labs and is actively maintained, but not officially supported. There are no SLAs or guarantees around backwards compatibility and deprecation. For questions and support, please use the Neo4j Community Forum.

The Python and TypeScript packages in this repository are versioned and released independently; the status badge above reflects this package's own maturity, not the other SDK's.

What it does

Plus: multi-stage entity extraction (spaCy / GLiNER2.5 / LLM) with typed relations decoded in the same pass, background enrichment (Wikipedia / Diffbot), geospatial queries, an MCP server with 16 extended-profile tools on Bolt (20 registered on NAMS; backend limitations apply), and integrations with LangChain, Pydantic AI, Google ADK, Strands, CrewAI, and more.

Backend capabilities

Select the backend at configuration time, then use its supported operations. Preferences, facts, client-created relationships and extraction configuration are Bolt-only. See Bolt vs NAMS for the full capability matrix.

• Hosted (NAMS) — a managed REST service. Just an API key; embedding, extraction, and dedup run server-side. Use workspace authentication for the tenancy boundary; conversation user metadata is distinct.
• Direct Neo4j (bolt) — connect to your AuraDB instance with client-side providers. Unlocks write-Cypher, geospatial queries, adopt_existing_graph, and deployments with locally configured providers.

Python release: These Python instructions use the published neo4j-agent-memory==0.7.0 package. The Python tutorials show the complete example programs and helpers to copy into local files, so running them does not require a repository clone or code download. TypeScript tutorials retain their documented source setup; Python and npm release versions are independent.

Quick start — Hosted (NAMS)

The fastest path: no database to run.

1. Sign up at memory.neo4jlabs.com and copy your nams_... API key.
2. Install and export the key:

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

3. The backend auto-selects NAMS when MEMORY_API_KEY is set:

import asyncio
from neo4j_agent_memory import MemoryClient

async def main():
    # Reads MEMORY_API_KEY from the environment; backend auto-selects NAMS.
    async with MemoryClient() as memory:
        conversation = await memory.short_term.create_conversation("quickstart")
        conversation_id = str(conversation.id)
        await memory.short_term.add_message(
            session_id=conversation_id, role="user",
            content="Hi, I'm John and I love Italian food!",
        )
        saved = await memory.short_term.get_conversation(conversation_id)
        print(saved.messages[-1].content)
        print("Save this conversation ID to resume it:", conversation_id)

asyncio.run(main())

neo4j-agent-memory is async-only — every operation is a coroutine. On NAMS, extraction is asynchronous; call await memory.long_term.wait_for_extraction(...) before asserting on freshly-extracted entities. See Use NAMS.

Quick start — Neo4j Aura (bolt)

Use a dedicated AuraDB instance and copy its connection values. Aura uses the bolt backend. Install the selected adapters with pip install 'neo4j-agent-memory[anthropic,openai]==0.7.0' and set their keys:

export NEO4J_URI="neo4j+s://<instance-id>.databases.neo4j.io"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="replace-with-your-Aura-password"
export NEO4J_DATABASE="neo4j"
export ANTHROPIC_API_KEY="replace-with-your-Anthropic-key"
export ANTHROPIC_MODEL="claude-sonnet-4-6"  # or any Claude API model ID your workspace can use
export OPENAI_API_KEY="replace-with-your-OpenAI-key"

The complete example reads those variables directly:

import asyncio
import os
from neo4j_agent_memory import MemoryClient, MemorySettings

async def main():
    settings = MemorySettings(
        backend="bolt",
        neo4j={
            "uri": os.environ["NEO4J_URI"],
            "username": os.environ["NEO4J_USERNAME"],
            "password": os.environ["NEO4J_PASSWORD"],
            "database": os.getenv("NEO4J_DATABASE", "neo4j"),
        },
        llm=f"anthropic/{os.environ['ANTHROPIC_MODEL']}",
        embedding="openai/text-embedding-3-small",
    )
    async with MemoryClient(settings) 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")
        print(await memory.get_context("Recommend a restaurant?", session_id="user-123"))

asyncio.run(main())

Installation

pip install 'neo4j-agent-memory==0.7.0'                                 # Core
pip install 'neo4j-agent-memory[nams]==0.7.0'                           # + hosted NAMS backend
pip install 'neo4j-agent-memory[openai]==0.7.0'                         # + OpenAI native adapter
pip install 'neo4j-agent-memory[anthropic]==0.7.0'                      # + Anthropic native adapter
pip install 'neo4j-agent-memory[bedrock]==0.7.0'                        # + AWS Bedrock native adapter
pip install 'neo4j-agent-memory[sentence-transformers]==0.7.0'          # + local HF embeddings
pip install 'neo4j-agent-memory[litellm]==0.7.0'                        # + LiteLLM universal fallback (100+ providers)
pip install 'neo4j-agent-memory[mcp,openai]==0.7.0'                     # + MCP server
pip install 'neo4j-agent-memory[all]==0.7.0'                            # Everything except heavy local ML
pip install 'neo4j-agent-memory[gliner2]==0.7.0'                        # + GLiNER2.5 local entity + relation extraction
pip install 'neo4j-agent-memory[full]==0.7.0'                           # Everything including spaCy, GLiNER2.5, sentence-transformers

Release 0.7.0 connects over Bolt without httpx; only the [nams] extra installs it, for the hosted backend.

MCP Server

Give any MCP-compatible assistant (Claude Desktop, Claude Code, Cursor) persistent graph-backed memory. Use the Aura and OpenAI environment variables from the quickstart above; the explicit --user maps the exported Aura username to the CLI option:

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

See the MCP tools reference.

Documentation

Full documentation: neo4j.com/labs/agent-memory

• Tutorials — build your first memory-enabled agent
• How-To Guides — NAMS, extraction, dedup, integrations
• Reference — configuration, CLI, REST API, MCP tools
• Concepts — POLE+O model, memory types, Bolt vs NAMS

Requirements

• Python 3.10+
• A Neo4j AuraDB instance for the bolt quickstart, or a NAMS workspace for the hosted path
• Self-managed Neo4j 5.26+ (including 2025.x) for the bolt backend

License

Apache License 2.0

A Neo4j Labs project — community supported, not officially backed by Neo4j. Community Forum · GitHub · Issues