neo4j-agent-memory-skill

What this skill does

# 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

| Field | Value |
|-------|-------|
| Package | `neo4j-agent-memory` |
| PyPI | https://pypi.org/project/neo4j-agent-memory/ |
| GitHub | https://github.com/neo4j-labs/agent-memory |
| Canonical docs | https://neo4j.com/labs/agent-memory/ |
| Hosted service | https://memory.neo4jlabs.com (NAMS — early-access, not yet documented on official project pages) |
| Hosted MCP endpoint | https://memory.neo4jlabs.com/mcp (SSE, bearer auth) |
| License | Apache-2.0 |
| Python | 3.10+ |
| Neo4j | 5.20+ (required for vector indexes) |
| Status | Experimental (Neo4j Labs, community-supported) |
| Current version (at time of writing) | **0.1.1** — **always verify PyPI before citing** |

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

| Option | What It Is | When to Choose |
|--------|------------|----------------|
| **Self-hosted library** | `pip install neo4j-agent-memory` + your own Neo4j (local / Docker / Aura). Full Python API, local MCP server, and framework integrations run in your process. | Dev, on-prem data, custom extraction pipelines, full control, bringing your own embeddings / LLMs. |
| **Hosted (NAMS)** | Managed service at `https://memory.neo4jlabs.com`. Per-workspace isolated Neo4j Aura database, REST API, remote MCP endpoint, web console. | Zero-infra trials, sharing memory across agents / machines, demos, teams that don't want to run Neo4j. |

> ⚠️ **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.

| Memory Type | Stores | Color Convention |
|-------------|--------|------------------|
| **Short-Term** | Conversation messages, session history, sequential message chains, metadata-filtered search, LLM-powered summaries | Green (`#B2F2BB` / `#2F9E44`) |
| **Long-Term** | Entities (people, places, orgs), preferences, facts, and the relationships between them — built automatically from conversations via the POLE+O model | Orange/Yellow (`#FFEC99` / `#F08C00`) |
| **Reasoning** | Decision traces, tool call provenance, thought-action-outcome chains — so the agent can learn from its own past reasoning patterns | Purple (`#D0BFFF` / `#9C36B5`) |

**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:

- **P**erson
- **O**rganization
- **L**ocation
- **E**vent
- **+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>]`.

```bash
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.

```python
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):

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

Install-local alternative:

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

### Transports and Profiles

```bash
# 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

| Profile | Tools | Contents |
|---------|-------|----------|
| **core** | 6 | `memory_search`, `memory_get_context`, `memory_store_message`, `memory_add_enti