--- name: neo4j-agent-memory-skill description: Authoritative reference for the neo4j-agent-memory Python package — a graph-native memory system for AI agents built on Neo4j — and for the hosted service (NAMS) at memory.neo4jlabs.com. Use this skill whenever the user mentions neo4j-agent-memory, agent memory with Neo4j, context graphs, the POLE+O model, MemoryClient/MemorySettings, the memory MCP server, or any of the framework integrations (LangChain, PydanticAI, CrewAI, AWS Strands, Google ADK, Microsoft Agent Framework, OpenAI Agents, LlamaIndex). Also use when the user mentions the hosted service at memory.neo4jlabs.com, NAMS, the Neo4j Agent Memory Service, the `nams_` API key prefix, or the hosted MCP endpoint. Also use when writing documentation, blog posts, tutorials, PRDs, or code samples for the project, when comparing agent memory approaches, or when positioning graph-native memory against vector-only approaches — even if the user doesn't explicitly name the package. version: 1.0.6 ---

# 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_entity`, `memory_add_preference`, `memory_add_fact` | | **extended** (default) | 16 | Core + conversation history, entity details, graph export, relationship creation, reasoning traces, observations, read-only Cypher |

As of v0.1.1, `memory_add_fact` accepts a `metadata` parameter, bringing it to parity with `memory_add_entity`.

### Claude Code Registration

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

### 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-..." } } } } ```

> For the **hosted** MCP endpoint at `memory.neo4jlabs.com/mcp`, see the **Hosted Service (NAMS)** section below — it uses SSE transport and bearer-token auth, not a local `uvx` invocation.

## Hosted Service (NAMS)

**NAMS** — Neo4j Agent Memory Service — is the managed deployment of `neo4j-agent-memory` at `https://memory.neo4jlabs.com`. It bundles the REST API, the MCP server, a web console, and per-workspace Neo4j Aura databases.

> ⚠️ **Verify against the live service before citing.** NAMS is not documented on the GitHub README or `neo4j.com/labs/agent-memory/`. Endpoint shapes, tool counts, auth flows, and limits can change without a release note. Before publishing anything NAMS-specific, re-check the live site and the OpenAPI spec at `/openapi.json`.

### Surface

- **Base URL:** `https://memory.neo4jlabs.com` - **Web console:** root URL — workspace management, memory browsing, entity visualization - **REST API:** `https://memory.neo4jlabs.com/v1/` — OpenAPI spec at `/openapi.json`; covers conversations, entities, observations, reasoning traces, and read-only Cypher - **MCP endpoint:** `https://memory.neo4jlabs.com/mcp` — SSE transport, exposes the hosted tool set, bearer-token auth

### Auth

- **API keys**, prefixed `nams_`, created and rotated from the web console — used as a bearer token for REST and MCP - **Auth0 OAuth2 (PKCE)** + scoped JWTs for interactive user flows

Don't mix these with the self-hosted library's `--password` Neo4j credential — they serve different sides of the stack.

### Storage Model

Each workspace is backed by an **isolated Neo4j Aura database**, provisioned on demand. Bring-your-own-Neo4j is supported as an alternative, configured per workspace.

### Rate Limits

Usage counters are tracked per API key / workspace. Exact limits are not publicly documented — check the console or re-verify against the service before committing customers to numbers.

### Claude Code Registration (Hosted MCP)

```bash claude mcp add --transport sse neo4j-agent-memory-hosted \ https://memory.neo4jlabs.com/mcp \ --header "Authorization: Bearer <nams_api_key>" ```

### Claude Desktop Config (Hosted MCP)

```json { "mcpServers": { "neo4j-agent-memory-hosted": { "url":

--- name: neo4j-agent-memory-skill description: Authoritative reference for the neo4j-agent-memory Python package — a graph-native memory system for AI agents built on Neo4j — and for the hosted service (NAMS) at memory.neo4jlabs.com. Use this skill whenever the user mentions neo4j-agent-memory, agent memory with Neo4j, context graphs, the POLE+O model, MemoryClient/MemorySettings, the memory MCP server, or any of the framework integrations (LangChain, PydanticAI, CrewAI, AWS Strands, Google ADK, Microsoft Agent Framework, OpenAI Agents, LlamaIndex). Also use when the user mentions the hosted service at memory.neo4jlabs.com, NAMS, the Neo4j Agent Memory Service, the `nams_` API key prefix, or the hosted MCP endpoint. Also use when writing documentation, blog posts, tutorials, PRDs, or code samples for the project, when comparing agent memory approaches, or when positioning graph-native memory against vector-only approaches — even if the user doesn't explicitly name the package. version: 1.0.6 ---

# 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_entity`, `memory_add_preference`, `memory_add_fact` | | **extended** (default) | 16 | Core + conversation history, entity details, graph export, relationship creation, reasoning traces, observations, read-only Cypher |

As of v0.1.1, `memory_add_fact` accepts a `metadata` parameter, bringing it to parity with `memory_add_entity`.

### Claude Code Registration

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

### 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-..." } } } } ```

> For the **hosted** MCP endpoint at `memory.neo4jlabs.com/mcp`, see the **Hosted Service (NAMS)** section below — it uses SSE transport and bearer-token auth, not a local `uvx` invocation.

## Hosted Service (NAMS)

**NAMS** — Neo4j Agent Memory Service — is the managed deployment of `neo4j-agent-memory` at `https://memory.neo4jlabs.com`. It bundles the REST API, the MCP server, a web console, and per-workspace Neo4j Aura databases.

> ⚠️ **Verify against the live service before citing.** NAMS is not documented on the GitHub README or `neo4j.com/labs/agent-memory/`. Endpoint shapes, tool counts, auth flows, and limits can change without a release note. Before publishing anything NAMS-specific, re-check the live site and the OpenAPI spec at `/openapi.json`.

### Surface

- **Base URL:** `https://memory.neo4jlabs.com` - **Web console:** root URL — workspace management, memory browsing, entity visualization - **REST API:** `https://memory.neo4jlabs.com/v1/` — OpenAPI spec at `/openapi.json`; covers conversations, entities, observations, reasoning traces, and read-only Cypher - **MCP endpoint:** `https://memory.neo4jlabs.com/mcp` — SSE transport, exposes the hosted tool set, bearer-token auth

### Auth

- **API keys**, prefixed `nams_`, created and rotated from the web console — used as a bearer token for REST and MCP - **Auth0 OAuth2 (PKCE)** + scoped JWTs for interactive user flows

Don't mix these with the self-hosted library's `--password` Neo4j credential — they serve different sides of the stack.

### Storage Model

Each workspace is backed by an **isolated Neo4j Aura database**, provisioned on demand. Bring-your-own-Neo4j is supported as an alternative, configured per workspace.

### Rate Limits

Usage counters are tracked per API key / workspace. Exact limits are not publicly documented — check the console or re-verify against the service before committing customers to numbers.

### Claude Code Registration (Hosted MCP)

```bash claude mcp add --transport sse neo4j-agent-memory-hosted \ https://memory.neo4jlabs.com/mcp \ --header "Authorization: Bearer <nams_api_key>" ```

### Claude Desktop Config (Hosted MCP)

```json { "mcpServers": { "neo4j-agent-memory-hosted": { "url":

--- name: neo4j-agent-memory-skill description: Authoritative reference for the neo4j-agent-memory Python package — a graph-native memory system for AI agents built on Neo4j — and for the hosted service (NAMS) at memory.neo4jlabs.com. Use this skill whenever the user mentions neo4j-agent-memory, agent memory with Neo4j, context graphs, the POLE+O model, MemoryClient/MemorySettings, the memory MCP server, or any of the framework integrations (LangChain, PydanticAI, CrewAI, AWS Strands, Google ADK, Microsoft Agent Framework, OpenAI Agents, LlamaIndex). Also use when the user mentions the hosted service at memory.neo4jlabs.com, NAMS, the Neo4j Agent Memory Service, the `nams_` API key prefix, or the hosted MCP endpoint. Also use when writing documentation, blog posts, tutorials, PRDs, or code samples for the project, when comparing agent memory approaches, or when positioning graph-native memory against vector-only approaches — even if the user doesn't explicitly name the package. version: 1.0.6 ---

# 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_entity`, `memory_add_preference`, `memory_add_fact` | | **extended** (default) | 16 | Core + conversation history, entity details, graph export, relationship creation, reasoning traces, observations, read-only Cypher |

As of v0.1.1, `memory_add_fact` accepts a `metadata` parameter, bringing it to parity with `memory_add_entity`.

### Claude Code Registration

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

### 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-..." } } } } ```

> For the **hosted** MCP endpoint at `memory.neo4jlabs.com/mcp`, see the **Hosted Service (NAMS)** section below — it uses SSE transport and bearer-token auth, not a local `uvx` invocation.

## Hosted Service (NAMS)

**NAMS** — Neo4j Agent Memory Service — is the managed deployment of `neo4j-agent-memory` at `https://memory.neo4jlabs.com`. It bundles the REST API, the MCP server, a web console, and per-workspace Neo4j Aura databases.

> ⚠️ **Verify against the live service before citing.** NAMS is not documented on the GitHub README or `neo4j.com/labs/agent-memory/`. Endpoint shapes, tool counts, auth flows, and limits can change without a release note. Before publishing anything NAMS-specific, re-check the live site and the OpenAPI spec at `/openapi.json`.

### Surface

- **Base URL:** `https://memory.neo4jlabs.com` - **Web console:** root URL — workspace management, memory browsing, entity visualization - **REST API:** `https://memory.neo4jlabs.com/v1/` — OpenAPI spec at `/openapi.json`; covers conversations, entities, observations, reasoning traces, and read-only Cypher - **MCP endpoint:** `https://memory.neo4jlabs.com/mcp` — SSE transport, exposes the hosted tool set, bearer-token auth

### Auth

- **API keys**, prefixed `nams_`, created and rotated from the web console — used as a bearer token for REST and MCP - **Auth0 OAuth2 (PKCE)** + scoped JWTs for interactive user flows

Don't mix these with the self-hosted library's `--password` Neo4j credential — they serve different sides of the stack.

### Storage Model

Each workspace is backed by an **isolated Neo4j Aura database**, provisioned on demand. Bring-your-own-Neo4j is supported as an alternative, configured per workspace.

### Rate Limits

Usage counters are tracked per API key / workspace. Exact limits are not publicly documented — check the console or re-verify against the service before committing customers to numbers.

### Claude Code Registration (Hosted MCP)

```bash claude mcp add --transport sse neo4j-agent-memory-hosted \ https://memory.neo4jlabs.com/mcp \ --header "Authorization: Bearer <nams_api_key>" ```

### Claude Desktop Config (Hosted MCP)

```json { "mcpServers": { "neo4j-agent-memory-hosted": { "url":

--- name: neo4j-agent-memory-skill description: Authoritative reference for the neo4j-agent-memory Python package — a graph-native memory system for AI agents built on Neo4j — and for the hosted service (NAMS) at memory.neo4jlabs.com. Use this skill whenever the user mentions neo4j-agent-memory, agent memory with Neo4j, context graphs, the POLE+O model, MemoryClient/MemorySettings, the memory MCP server, or any of the framework integrations (LangChain, PydanticAI, CrewAI, AWS Strands, Google ADK, Microsoft Agent Framework, OpenAI Agents, LlamaIndex). Also use when the user mentions the hosted service at memory.neo4jlabs.com, NAMS, the Neo4j Agent Memory Service, the `nams_` API key prefix, or the hosted MCP endpoint. Also use when writing documentation, blog posts, tutorials, PRDs, or code samples for the project, when comparing agent memory approaches, or when positioning graph-native memory against vector-only approaches — even if the user doesn't explicitly name the package. version: 1.0.6 ---

# 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_entity`, `memory_add_preference`, `memory_add_fact` | | **extended** (default) | 16 | Core + conversation history, entity details, graph export, relationship creation, reasoning traces, observations, read-only Cypher |

As of v0.1.1, `memory_add_fact` accepts a `metadata` parameter, bringing it to parity with `memory_add_entity`.

### Claude Code Registration

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

### 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-..." } } } } ```

> For the **hosted** MCP endpoint at `memory.neo4jlabs.com/mcp`, see the **Hosted Service (NAMS)** section below — it uses SSE transport and bearer-token auth, not a local `uvx` invocation.

## Hosted Service (NAMS)

**NAMS** — Neo4j Agent Memory Service — is the managed deployment of `neo4j-agent-memory` at `https://memory.neo4jlabs.com`. It bundles the REST API, the MCP server, a web console, and per-workspace Neo4j Aura databases.

> ⚠️ **Verify against the live service before citing.** NAMS is not documented on the GitHub README or `neo4j.com/labs/agent-memory/`. Endpoint shapes, tool counts, auth flows, and limits can change without a release note. Before publishing anything NAMS-specific, re-check the live site and the OpenAPI spec at `/openapi.json`.

### Surface

- **Base URL:** `https://memory.neo4jlabs.com` - **Web console:** root URL — workspace management, memory browsing, entity visualization - **REST API:** `https://memory.neo4jlabs.com/v1/` — OpenAPI spec at `/openapi.json`; covers conversations, entities, observations, reasoning traces, and read-only Cypher - **MCP endpoint:** `https://memory.neo4jlabs.com/mcp` — SSE transport, exposes the hosted tool set, bearer-token auth

### Auth

- **API keys**, prefixed `nams_`, created and rotated from the web console — used as a bearer token for REST and MCP - **Auth0 OAuth2 (PKCE)** + scoped JWTs for interactive user flows

Don't mix these with the self-hosted library's `--password` Neo4j credential — they serve different sides of the stack.

### Storage Model

Each workspace is backed by an **isolated Neo4j Aura database**, provisioned on demand. Bring-your-own-Neo4j is supported as an alternative, configured per workspace.

### Rate Limits

Usage counters are tracked per API key / workspace. Exact limits are not publicly documented — check the console or re-verify against the service before committing customers to numbers.

### Claude Code Registration (Hosted MCP)

```bash claude mcp add --transport sse neo4j-agent-memory-hosted \ https://memory.neo4jlabs.com/mcp \ --header "Authorization: Bearer <nams_api_key>" ```

### Claude Desktop Config (Hosted MCP)

```json { "mcpServers": { "neo4j-agent-memory-hosted": { "url":