Skip to main content

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.

Neo4j Labs Status: Beta Community Supported PyPI version Python versions License

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

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) Retrieve recorded decisions
Vector + text search Entity resolution & dedup Similar task retrieval

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_...
  1. 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.11+
  • 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

Metadata

Release files for neo4j-agent-memory 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for neo4j-agent-memory 0.8.0
File Size Uploaded Provenance Actions
neo4j_agent_memory-0.8.0.tar.gz 509.5 kB Without provenance Details for neo4j_agent_memory-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for neo4j-agent-memory 0.8.0
File Interpreter ABI Platform Actions
neo4j_agent_memory-0.8.0-py3-none-any.whl Python 3 none any Details for neo4j_agent_memory-0.8.0-py3-none-any.whl

Total release size: 1.1 MB

Release files / neo4j_agent_memory-0.8.0.tar.gz

Download URL neo4j_agent_memory-0.8.0.tar.gz
Size 509.5 kB
Tags Source
SHA-256 checksum
How to use checksums
6e5c9c4bd7ac32e6688bb6fc1619d3c15b918b6777b122e135873f2a59ab09b2
BLAKE2b-256 checksum
How to use checksums
1447bcf31c29463923d26113ed5788029a7a1f48bb40b51b93f9b1830043fd93
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / neo4j_agent_memory-0.8.0-py3-none-any.whl

Download URL neo4j_agent_memory-0.8.0-py3-none-any.whl
Size 600.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5ebe42298fd0380d7c5079817f39bf619efefbe474bc15fe1433801c1766482d
BLAKE2b-256 checksum
How to use checksums
1d13170a3c9a97c2daf7d08c5a914f81e62d32cc414cb7db146116242d52e46b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.29 {"installer":{"name":"uv","version":"0.11.29","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for neo4j-agent-memory 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page