Neo4j Agent Memory Skill

neo4j-agent-memory

Authoritative reference for the neo4j-agent-memory Python package — a Neo4j Labs project that gives AI agents three distinct memory layers (short-term, long-term, reasoning) in a single knowledge graph.

⚠️ Verify authoritative state before writing. Version numbers, extras, tool counts, and API surface change between releases. The values in this skill reflect a specific point in time. Before publishing anything version-sensitive, confirm against PyPI (https://pypi.org/project/neo4j-agent-memory/) and the GitHub README (https://github.com/neo4j-labs/agent-memory). PyPI is the authoritative source for version numbers — never infer.

When to Use

• Building AI agents that need persistent memory (short-term, long-term, reasoning traces) backed by Neo4j
• Using the neo4j-agent-memory Python package or the hosted NAMS service at memory.neo4jlabs.com
• Integrating agent memory with LangChain, PydanticAI, CrewAI, AWS Strands, Google ADK, OpenAI Agents, LlamaIndex, or Microsoft Agent Framework
• Writing documentation, tutorials, or positioning content about graph-native agent memory
• Comparing graph-native memory against vector-only approaches

When NOT to Use

• Plain Neo4j driver connections (no memory layer needed) → use neo4j-driver-python-skill
• Writing or optimizing Cypher queries → use neo4j-cypher-skill
• GraphRAG retrieval pipelines → use neo4j-graphrag-skill

Project at a Glance

What It Is (One Sentence)

A graph-native memory system for AI agents that stores conversations, builds knowledge graphs, and records agent reasoning — all as connected nodes in a single Neo4j database.

Consumption Models

neo4j-agent-memory ships in two consumption models. They are the same underlying project — the differences are how you run it, how you authenticate, and what's managed for you.

⚠️ NAMS is reachable but not yet referenced in the GitHub README or `neo4j.com/labs/agent-memory/`. Treat it as early-access / soft-launched. Do not assert SLAs, pricing, or GA status in published content. See the Hosted Service (NAMS) section below for details.

The Three Memory Types

The defining architectural feature. Every piece of content describing the project should lead with this trinity.

Reasoning memory is the primary competitive differentiator. Most competing systems cover short-term and long-term but treat reasoning as an afterthought or omit it entirely. Lead with this when positioning.

The POLE+O Model

Long-term memory uses the POLE+O entity framework — the canonical entity classification for this project:

• Person
• Organization
• Location
• Event
• +O Object (anything that doesn't fit the core four — products, concepts, projects, etc.)

When diagramming the data model, use ellipses for entity nodes and labeled arrows (UPPER_SNAKE_CASE) for relationships, consistent with Neo4j Browser conventions.

Installation

Core install plus extras. The extras pattern is pip install neo4j-agent-memory[<extra>].

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

Full extras list (subject to change — verify PyPI): all, anthropic, aws, bedrock, cli, crewai, extraction, full, fuzzy, gliner, google, google-adk, langchain, llamaindex, mcp, microsoft-agent, observability, openai, openai-agents, opentelemetry, opik, pydantic-ai, sentence-transformers, spacy, strands, vertex-ai.

Python API (Quickstart)

Canonical import pattern and basic usage. This is the shape to reproduce in tutorials and examples.

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:
        # Short-term: 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!"
        )

        # Long-term: 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())

Note the async context manager pattern (async with MemoryClient(settings) as memory:) — this is the canonical form.

MCP Server

Exposes memory as tools for MCP-compatible AI assistants (Claude Desktop, Claude Code, Cursor, VS Code Copilot).

Invocation

The authoritative one-liner (no install needed):

uvx "neo4j-agent-memory[mcp]" mcp serve --password <neo4j-password>

Install-local alternative:

neo4j-agent-memory mcp serve --password <pw>

Transports and Profiles

# stdio (default — Claude Desktop, Claude Code)
neo4j-agent-memory mcp serve --password <pw>

# SSE (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