Neo4j Agent Memory

https://neo4j.com/labs/agent-memory/
Admin
Neo4j Agent Memory provides graph-native memory for AI agents, offering production-grade memory...
Tokens:182,579
Snippets:1,429
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install dependencies for hooks mode example

Source: https://neo4j.com/labs/agent-memory/how-to/typescript/nams-ai-provider-hooks-mode

Sets up a Node.js ES module project and installs the required packages for the hooks mode example. Run these commands in the project directory before using the program.

```bash
npm init -y   # only if the directory has no package.json yet
npm pkg set type=module
npm install @neo4j-labs/nams-ai-provider@0.3.0 @neo4j-labs/agent-memory@0.5.0 ai@^7 @ai-sdk/openai@^4 zod@^4
npm install --save-dev tsx
```

--------------------------------

### Configure via MCP CLI: install and serve

Source: https://neo4j.com/labs/agent-memory/how-to/configure-llm-provider

Install the CLI with the required extras and run the MCP server with explicit LLM configuration. The example selects Anthropic for the LLM and keeps the default OpenAI embedding provider.

```bash
pip install 'neo4j-agent-memory[cli,mcp,anthropic,openai]==0.6.0' 'httpx>=0.27'
```

```bash
neo4j-agent-memory mcp serve \
  --backend bolt --uri "$NEO4J_URI" --user "$NEO4J_USERNAME" \
  --llm anthropic/claude-3-5-sonnet-latest \
  --llm-api-key $ANTHROPIC_API_KEY \
  --llm-api-base https://custom-endpoint.example.com  # optional
```

--------------------------------

### Install SDK and httpx

Source: https://neo4j.com/labs/agent-memory/how-to/audit-reasoning

Installs the published SDK with the OpenAI extra and httpx, which release 0.6.0 imports when connecting over Bolt.

```bash
python -m pip install 'neo4j-agent-memory[openai]==0.6.0' 'httpx>=0.27'
```

--------------------------------

### Run core memory recipes example

Source: https://neo4j.com/labs/agent-memory/how-to/messages

Executes the core memory recipes example with the 'messages' subcommand. Expect summary text, up to five search candidates with similarity values, and a verification line. The command retains example records; use the tutorial's cleanup command to remove the disposable database.

```bash
python core_memory_recipes.py messages
```

--------------------------------

### Install SDK and configure environment

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/aws-strands

Installs the SDK with the strands and bedrock extras, sets required environment variables, and verifies AWS credentials. Replace the placeholder values with your own.

```bash
python -m pip install 'neo4j-agent-memory[strands,bedrock]==0.6.0'
export AWS_REGION='us-east-1'
export AWS_DEFAULT_REGION="$AWS_REGION"
export BEDROCK_MODEL_ID='replace-with-an-authorized-model-or-inference-profile-id'
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'
aws sts get-caller-identity
```

--------------------------------

### Install SDK and set environment variables

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/aws-hybrid-memory

Installs the published Python 0.6.0 package with the openai extra and httpx, then exports the Neo4j Aura connection values and the OpenAI API key. The install command adds httpx, which release 0.6.0 imports when connecting over Bolt but declares only in the nams extra. Credentials are read from the environment and never printed by the programs.

```bash
python -m pip install 'neo4j-agent-memory[openai]==0.6.0' 'httpx>=0.27'
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 OPENAI_API_KEY='replace-with-your-provider-key'
```

--------------------------------

### Install SDK and download spaCy model

Source: https://neo4j.com/labs/agent-memory/how-to/running-without-an-llm

Installs the published SDK with extraction and sentence-transformers extras, then downloads the spaCy English model. Requires the virtual environment to be active.

```bash
pip install 'neo4j-agent-memory[extraction,sentence-transformers]==0.6.0'
python -m spacy download en_core_web_sm
```

--------------------------------

### Install provider extras

Source: https://neo4j.com/labs/agent-memory/how-to/bring-your-own-model

Install the necessary package extras for your chosen provider and ensure httpx is included for Bolt connectivity.

```bash
pip install 'neo4j-agent-memory[openai]==0.6.0' 'httpx>=0.27'
```

--------------------------------

### Install SDK and set environment variables

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/openai-agents

Installs the published 0.6.0 package with the openai-agents extra and sets environment variables for Neo4j and OpenAI. Requires Python 3.10+ and a POSIX shell.

```bash
python -m pip install 'neo4j-agent-memory[openai-agents]==0.6.0' openai-agents 'httpx>=0.27'
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 OPENAI_API_KEY='replace-with-your-provider-key'
export OPENAI_MODEL='replace-with-an-available-model-id'
```

--------------------------------

### Install neo4j-agent-memory with GLiNER extra

Source: https://neo4j.com/labs/agent-memory/how-to/entity-extraction-batch

Installs the published SDK with the GLiNER extra. Requires Python 3.10 or newer and a POSIX shell.

```bash
python -m pip install 'neo4j-agent-memory[gliner]==0.6.0'
```

--------------------------------

### Install neo4j-agent-memory with CLI and MCP extras

Source: https://neo4j.com/labs/agent-memory/how-to/configure-embedding-provider

Install the CLI and MCP extras along with the sentence-transformers and OpenAI providers. Required before running the MCP server.

```bash
pip install 'neo4j-agent-memory[cli,mcp,sentence-transformers,openai]==0.6.0'
```

--------------------------------

### Install SDK and set environment variables

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/llamaindex

Installs the neo4j-agent-memory package with LlamaIndex and OpenAI extras, then exports Neo4j connection details and OpenAI API key. Requires access to text-embedding-3-small for embeddings.

```bash
python -m pip install 'neo4j-agent-memory[llamaindex,openai]==0.6.0'
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 OPENAI_API_KEY='replace-with-your-provider-key'
```

--------------------------------

### Install the SDK and set environment variables

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/langchain

Installs the neo4j-agent-memory package with LangChain agents and OpenAI support, then sets the required environment variables for Neo4j and OpenAI. Requires access to text-embedding-3-small for embeddings.

```bash
python -m pip install 'neo4j-agent-memory[langchain-agents,openai]==0.6.0' langchain-openai
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 OPENAI_API_KEY='replace-with-your-provider-key'
export OPENAI_MODEL='replace-with-an-available-model-id'
```

--------------------------------

### Install SDK and set environment variables

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/crewai

Installs the published Python 0.6.0 SDK with CrewAI and OpenAI extras, then exports Neo4j AuraDB and OpenAI credentials from the environment. Requires access to text-embedding-3-small for 1536-dimensional vectors.

```bash
python -m pip install 'neo4j-agent-memory[crewai,openai]==0.6.0'
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 OPENAI_API_KEY='replace-with-your-provider-key'
export CREWAI_MODEL='openai/replace-with-an-available-model-id'
```

--------------------------------

### Install SDK and configure test database

Source: https://neo4j.com/labs/agent-memory/how-to/evaluation

Installs the published SDK and sets environment variables for a dedicated test Aura database. The first run downloads the local all-MiniLM-L6-v2 embedding model; no model API key is required.

```bash
python -m pip install 'neo4j-agent-memory[sentence-transformers]==0.6.0'
export NEO4J_URI="neo4j+s://YOUR-TEST-INSTANCE.databases.neo4j.io"
export NEO4J_USERNAME="YOUR-AURA-USERNAME"
export NEO4J_PASSWORD="YOUR-AURA-PASSWORD"
export NEO4J_DATABASE="neo4j"
mkdir -p eval-harness
```

--------------------------------

### Install neo4j-agent-memory with CLI, MCP, and provider extras

Source: https://neo4j.com/labs/agent-memory/how-to/bring-your-own-model

Install the CLI and MCP extras along with the Anthropic and sentence-transformers provider extras. Required before using the neo4j-agent-memory command or mcp serve.

```bash
pip install 'neo4j-agent-memory[cli,mcp,anthropic,sentence-transformers]==0.6.0'
```

--------------------------------

### Python LangGraph MemoryCheckpointSaver setup

Source: https://neo4j.com/labs/agent-memory/how-to/typescript/integrations-overview

Install the hosted Python client from a checkout of the agent-memory-tck repository with `pip install ./clients/python`. Use `MemoryCheckpointSaver` to add memory checkpointing to a LangGraph state graph.

```python
from neo4j_agent_memory_client import MemoryClient
from neo4j_agent_memory_client.integrations.langgraph import MemoryCheckpointSaver

client = MemoryClient(endpoint="https://memory.neo4jlabs.com/v1", api_key=...)
saver = MemoryCheckpointSaver(client)

graph = StateGraph(MyState)
graph.compile(checkpointer=saver)
```

--------------------------------

### Create working directory and virtual environment

Source: https://neo4j.com/labs/agent-memory/how-to/audit-reasoning

Commands to create a local folder and virtual environment for the tutorials. Reuses an existing environment if present.

```bash
mkdir -p ~/agent-memory-tutorials
cd ~/agent-memory-tutorials
if [ -e .venv ]; then
  printf '%s\n' 'Using the existing virtual environment.'
else
  python3 -m venv .venv
fi
source .venv/bin/activate
```

--------------------------------

### Use local sentence-transformers with MemorySettings

Source: https://neo4j.com/labs/agent-memory/how-to/configure-embedding-provider

Configure neo4j-agent-memory to use a local sentence-transformers model. No API key is needed and embeddings stay on your machine. The example sets up the backend and Neo4j connection using environment variables, with a default database of 'neo4j'. Install with `pip install 'neo4j-agent-memory[sentence-transformers]==0.6.0'`. The first call downloads the model (~50-500 MB depending on choice); subsequent calls hit the local cache.

```python
import os
from neo4j_agent_memory import MemorySettings

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"),
    },
    embedding="BAAI/bge-small-en-v1.5",      # 384 dims
)
```

--------------------------------

### Install @ai-sdk/mcp optional peer

Source: https://neo4j.com/labs/agent-memory/how-to/typescript/nams-ai-provider-tools-mode

Install the optional peer dependency @ai-sdk/mcp@^2. npm does not install optional peers automatically; toolsWithMcp loads it only when an MCP config is passed.

```bash
npm install @ai-sdk/mcp@^2
```

--------------------------------

### Run no_llm/main.py

Source: https://neo4j.com/labs/agent-memory/how-to/running-without-an-llm

Runs the example script from the agent-memory-tutorials directory, keeping the exported Aura connection values in the process environment.

```bash
# Keep the exported Aura connection values in this process environment.
python no_llm/main.py
```

--------------------------------

### Install the SDK and set environment variables

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/google-adk

Installs the published Python 0.6.0 package with the google-adk and openai extras, then sets the required environment variables for Neo4j Aura, OpenAI embeddings, and the Google AI API. The recipe uses BoltSettings to select Neo4j explicitly and disables entity extraction. Credentials are read from the environment and never printed by the programs.

```bash
python -m pip install 'neo4j-agent-memory[google-adk,openai]==0.6.0'
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 OPENAI_API_KEY='replace-with-your-provider-key'
export GOOGLE_API_KEY='replace-with-your-Google-AI-key'
unset GOOGLE_GENAI_USE_VERTEXAI
export ADK_MODEL='replace-with-an-available-Gemini-model-id'
```

--------------------------------

### Install neo4j-agent-memory package

Source: https://neo4j.com/labs/agent-memory/how-to/team-memory-in-your-editor

Installs the published Python 0.6.0 package with the nams and mcp extras. Requires Python 3.10+ and a POSIX shell.

```bash
python -m pip install 'neo4j-agent-memory[nams,mcp]==0.6.0'
```

--------------------------------

### Install SDK and configure credentials

Source: https://neo4j.com/labs/agent-memory/how-to/integrations/aws-bedrock-embeddings

Installs the neo4j-agent-memory SDK with the bedrock extra and httpx, then sets AWS region and Neo4j connection environment variables. The final command checks AWS identity; the identity must be allowed to invoke amazon.titan-embed-text-v2:0 in the selected region.

```bash
python -m pip install 'neo4j-agent-memory[bedrock]==0.6.0' 'httpx>=0.27'
export AWS_REGION='us-east-1'
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'
aws sts get-caller-identity
```

--------------------------------

### Configure local stdio MCP server for context-graph

Source: https://neo4j.com/labs/agent-memory/how-to/create-context-graph-mcp

MCP client configuration for a local stdio process using the Aura connection setup. Replace the executable path, database settings, and secrets with your application values. The client configuration file location depends on the installed host. Copy the Aura username into NEO4J_USER; JSON values are literal strings, not shell expressions. Store secrets using the host's supported configuration mechanism and do not commit this populated file.

```json
{
  "mcpServers": {
    "context-graph": {
      "command": "/absolute/path/to/project/.venv/bin/neo4j-agent-memory",
      "args": [
        "mcp", "serve", "--backend", "bolt",
        "--database", "neo4j", "--profile", "extended"
      ],
      "env": {
        "NEO4J_URI": "neo4j+s://<instance-id>.databases.neo4j.io",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "replace-with-your-Aura-password",
        "OPENAI_API_KEY": "replace-with-provider-key"
      }
    }
  }
}
```

--------------------------------

### Install GLiREL dependencies and spaCy model

Source: https://neo4j.com/labs/agent-memory/how-to/entity-extraction-schemas

Install the required packages for GLiREL extraction with the neo4j-agent-memory SDK. The SDK does not define a glirel extra, so glirel and loguru must be installed explicitly; GLiREL 1.2.1 also requires protobuf and huggingface-hub below 1.0. The second command downloads the spaCy tokenizer model en_core_web_sm.

```bash
python -m pip install 'neo4j-agent-memory[gliner,spacy]==0.6.0' glirel 'loguru>=0.7,<1' 'huggingface-hub<1' protobuf
python -m spacy download en_core_web_sm
```
Tokens:
Raw