Extract memory with Anthropic and local embeddings

We will store a message in AuraDB through the Bolt backend, request entity extraction using an Anthropic adapter, and retrieve context using locally computed sentence-transformer embeddings. We will inspect the actual provider classes and vector dimensions. This exercise builds a memory pipeline; a conversational agent loop is a separate lesson.

This lesson uses neo4j-agent-memory 0.7.0 from PyPI and the complete programs on this page in a POSIX shell. Create the local files shown below; the checks below verify the results in your environment.

Before you begin

  • Python 3.10 or newer and a POSIX shell.

  • A Neo4j Aura account for a dedicated lesson instance.

  • An Anthropic API key and an accessible model ID for that account.

  • Local disk space and network access for the embedding-model download.

The message text is sent to Anthropic for extraction, and messages and vectors are stored in AuraDB. Embedding computation runs locally after the model download; the exercise still requires network access.

1. Install the selected providers

Create a local folder and virtual environment for the examples on this page. The commands reuse an existing environment without changing its files:

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

Expected: ~/agent-memory-tutorials is your working directory and its virtual environment is active. Install the published SDK with the command below.

Each complete code block labelled Save as names a file to create in this folder using your editor. Copy the entire block, including imports and the entry point. Expand each helper disclosure and use Copy code to copy its full source. Keep all files together so their imports resolve.

When continuing from another tutorial or guide, retain the existing environment, configuration, session files, and .tutorial-state/. Reuse unchanged helper files; compare an existing file before replacing it, and finish any pending cleanup or recovery before changing the code that owns its state.

python -m pip install 'neo4j-agent-memory[anthropic,sentence-transformers]==0.7.0'
python -c "from importlib.metadata import version; \
import neo4j_agent_memory; \
assert version('neo4j-agent-memory') == '0.7.0'; \
print('SDK 0.7.0 import verified')"

Expected: SDK 0.7.0 import verified. Keep agent-memory-tutorials as your working directory for every command below.

Create and check the local files

Create each file below in ~/agent-memory-tutorials. All complete sources follow this manifest. On a first visit every file is new; when returning, reuse unchanged helpers and compare their contents before replacing them.

File Purpose Returning reader

aura_connection.py

Read explicit Aura credentials; the database defaults to neo4j.

Reuse unchanged

wait_for_tutorial_neo4j.py

Probe the selected database and close the driver.

Reuse unchanged

anthropic_local_memory.py

Run extraction and verify local embedding dimensions and context. This is the lesson entry point.

New for this lesson; retain it with unfinished state

The manifest above names this lesson’s entry point and its helpers. Save every file it lists, then run the offline assembly checks that follow the sources before the lesson commands.

Open the helper below and save its complete source as aura_connection.py in ~/agent-memory-tutorials.

Show aura_connection.py
Save as aura_connection.py
"""Read the Aura connection exported by the documentation setup commands."""

import os


class AuraConfigurationError(ValueError):
    """Missing or invalid tutorial settings, with no credential values in errors."""


def aura_config():
    required = ("NEO4J_URI", "NEO4J_USERNAME", "NEO4J_PASSWORD")
    missing = [name for name in required if not os.environ.get(name, "").strip()]
    if missing:
        raise AuraConfigurationError("Export the Aura connection settings: " + ", ".join(missing))
    uri = os.environ["NEO4J_URI"]
    if not uri.startswith("neo4j+s://"):
        raise AuraConfigurationError("NEO4J_URI must use the Aura neo4j+s:// connection scheme")
    database = os.environ.get("NEO4J_DATABASE", "neo4j")
    if not database.strip():
        raise AuraConfigurationError("NEO4J_DATABASE must not be empty")
    return {
        "uri": uri,
        "username": os.environ["NEO4J_USERNAME"],
        "password": os.environ["NEO4J_PASSWORD"],
        "database": database,
    }

Open the helper below and save its complete source as wait_for_tutorial_neo4j.py in ~/agent-memory-tutorials.

Show wait_for_tutorial_neo4j.py
Save as wait_for_tutorial_neo4j.py
"""Check the exported Aura connection, waiting at most three minutes."""

import asyncio
import sys

from aura_connection import AuraConfigurationError, aura_config
from neo4j import AsyncGraphDatabase
from neo4j.exceptions import DriverError, Neo4jError, ServiceUnavailable, SessionExpired


async def wait_until_ready(timeout=180):
    if timeout <= 0:
        raise ValueError("Readiness timeout must be positive")
    config = aura_config()

    async def probe(driver):
        while True:
            try:
                await driver.verify_connectivity()
                records, _, _ = await driver.execute_query(
                    "RETURN 1 AS ready", database_=config["database"], routing_="r"
                )
                if len(records) != 1 or records[0]["ready"] != 1:
                    raise RuntimeError("Unexpected readiness query result")
                return
            except (ServiceUnavailable, SessionExpired):
                await asyncio.sleep(2)

    async with AsyncGraphDatabase.driver(
        config["uri"],
        auth=(config["username"], config["password"]),
        connection_timeout=min(10, timeout),
        connection_acquisition_timeout=min(10, timeout),
    ) as driver:
        await asyncio.wait_for(probe(driver), timeout=timeout)


def main():
    try:
        asyncio.run(wait_until_ready())
    except AuraConfigurationError as error:
        print(str(error), file=sys.stderr)
        raise SystemExit(1) from None
    except (asyncio.TimeoutError, DriverError, Neo4jError) as error:
        # Driver exceptions can include connection details. Report the category
        # and next action without echoing credentials or a raw server message.
        print(
            f"Neo4j Aura readiness failed ({type(error).__name__}). "
            "Check that the instance is Running, the exported NEO4J_* values "
            "match its credentials, and your network allows the connection.",
            file=sys.stderr,
        )
        raise SystemExit(1) from None
    print("Verified: Neo4j Aura answered the readiness query")


if __name__ == "__main__":
    main()
Save as anthropic_local_memory.py
"""Explicit Anthropic extraction with local embeddings and storage in AuraDB."""

import asyncio
import os
from uuid import uuid4

from aura_connection import aura_config


async def main():
    from neo4j_agent_memory import MemoryClient, MemorySettings
    from neo4j_agent_memory.llm import from_provider

    llm = from_provider(f"anthropic/{os.environ['ANTHROPIC_MODEL']}", kind="llm")
    embedding = from_provider("BAAI/bge-small-en-v1.5", kind="embedding")
    print(f"LLM adapter: {type(llm).__name__}")
    print(f"Embedding adapter: {type(embedding).__name__}; dimensions={embedding.dimensions}")
    settings = MemorySettings(
        backend="bolt",
        neo4j=aura_config(),
        llm=llm,
        embedding=embedding,
        extraction={"extractor_type": "llm"},
    )
    session_id = f"anthropic-tutorial-{uuid4().hex[:8]}"
    async with MemoryClient(settings) as client:
        message = await client.short_term.add_message(
            session_id=session_id,
            role="user",
            content="Maya Chen works at Northstar Robotics in Denver.",
            extract_entities=True,
        )
        history = (await client.short_term.get_conversation(session_id)).messages
        if not any(stored.id == message.id for stored in history):
            raise RuntimeError("The saved message was missing from readback")
        print(f"Verified message readback; session={session_id}")
        # Read back the entities extraction linked to this message. Ingest-time
        # resolution can merge a mention onto an entity an earlier run stored, so
        # follow the message's MENTIONS edges rather than a vector search.
        entities = await client.query.cypher(
            "MATCH (:Message {id: $message_id})-[:MENTIONS]->(entity:Entity) "
            "RETURN DISTINCT entity.name AS name, entity.type AS type ORDER BY name",
            {"message_id": str(message.id)},
        )
        if not entities:
            raise RuntimeError(
                "No entity candidates returned; inspect extraction before continuing"
            )
        for entity in entities:
            print(f"Entity candidate: {entity['name']} ({entity['type']})")
        context = await client.get_context("Maya Chen", session_id=session_id)
        if not context.strip():
            raise RuntimeError("Context assembly returned empty text")
        print("Verified: context assembly returned text")
        print(context)


if __name__ == "__main__":
    asyncio.run(main())

Check the copied files before exporting credentials or making a service request:

python -m py_compile aura_connection.py wait_for_tutorial_neo4j.py anthropic_local_memory.py
python -c "import aura_connection, wait_for_tutorial_neo4j, anthropic_local_memory; assert all(callable(f) for f in [aura_connection.aura_config, wait_for_tutorial_neo4j.wait_until_ready, anthropic_local_memory.main]); print('Lesson imports verified')"

Expected: compilation exits without errors, then Lesson imports verified. These checks import the local files without calling their entry points, downloading models, or contacting Aura/providers. Compilation alone does not check imports. If a file or function is missing, recopy its entire source and repeat the checks; leave existing session/state files intact. Provider/framework calls are checked when the lesson runs.

2. Create and connect to the Aura lesson instance

This starts a new lesson with a new empty database. To return to an unfinished lesson, use Resume this lesson later instead.

  1. Sign in to the Neo4j Aura console and create an AuraDB Free instance named agent-memory-tutorial. Use an empty instance dedicated to this lesson; do not load a sample dataset.

  2. Download the generated credentials and keep them outside the tutorial folder. Wait until the instance shows Running.

  3. Copy its connection URI, username, password and database name into the exports below. Keep the neo4j+s:// scheme supplied by Aura.

Aura permits one Free instance per account. This lesson needs that slot for a dedicated tutorial instance; do not delete an existing database containing other work to make room. See Aura instance creation for account and tier requirements.

The files from the preceding assembly checkpoint read these exports and verify the selected database.

export NEO4J_URI='neo4j+s://<instance-id>.databases.neo4j.io'
export NEO4J_USERNAME='neo4j'
export NEO4J_PASSWORD='replace-with-the-generated-password'
export NEO4J_DATABASE='neo4j'
python wait_for_tutorial_neo4j.py

Expected: Verified: Neo4j Aura answered the readiness query. The helper checks connectivity and executes RETURN 1 in the selected database, retrying temporary connection failures for up to three minutes. Authentication failures stop immediately. If the check fails, confirm the instance is Running and recopy its connection settings.

The examples read these exported variables through aura_connection.py. They require the Aura URI, username and password and never fall back to a local instance. When NEO4J_DATABASE is unset, they use the neo4j database, which is the Aura default. Keep this shell and virtual environment active for the remaining commands. See Aura connection instructions for help locating the settings.

In the Aura console, open Query, select this instance and database in the connection bar, and connect using the same credentials. Run:

MATCH (n) RETURN count(n) AS node_count

Expected: 0. This confirms that the lesson starts with an empty database. The Python SDK still uses backend="bolt": Aura hosts Neo4j and accepts encrypted Bolt connections.

3. Configure Anthropic

Open the Anthropic model overview and copy the Claude API ID of the model selected for your API workspace; an AWS Bedrock ID belongs to a different provider path. Check that workspace’s API access and usage limits before continuing. The Models API can confirm model metadata using the same API key without making a completion request. Metadata visibility does not prove inference permission or quota. Extraction below is a real provider operation and may incur usage charges.

export ANTHROPIC_API_KEY="replace-with-your-key"
export ANTHROPIC_MODEL="replace-with-your-accessible-Anthropic-model-id"
python -c "import os; \
assert os.environ['ANTHROPIC_API_KEY']; \
model = os.environ['ANTHROPIC_MODEL']; \
assert model.strip() and not model.startswith('replace-with-'); \
print('Provider variables present')"

Expected: Provider variables present. This confirms presence only; the extraction request below verifies actual model access. If access fails, check missing exports first, then the exact API model ID and workspace permission, then billing/quota. Fix those before another extraction attempt. A failed run can already have stored a message; inspect its reported session or dispose of the dedicated instance before intentionally starting over.

4. Read the complete program

The shared aura_config() helper reads the required Aura connection variables. The explicit backend="bolt" prevents a NAMS environment key from changing this lesson’s backend. extractor_type="llm" selects the Anthropic extraction path rather than relying on an optional local NER model. The imports and event-loop entry point are already included.

Excerpt of the MemorySettings construction from anthropic_local_memory.py:

settings = MemorySettings(
    backend="bolt",
    neo4j=aura_config(),
    llm=llm,
    embedding=embedding,
    extraction={"extractor_type": "llm"},
)

5. Run and verify the selected providers

python anthropic_local_memory.py

Expected milestones:

  1. LLM adapter: AnthropicProvider.

  2. Embedding adapter: SentenceTransformersProvider; dimensions=384.

  3. Verified message readback; session=…​ with the created session identifier.

  4. One or more Entity candidate: lines, one for each entity this message mentions, then Verified: context assembly returned text.

Read the candidate names and context; model output is variable. A schema-valid response can still misidentify the source. Empty results stop the exercise rather than being presented as verified extraction.

The program reads the entities back by following the message’s MENTIONS edges rather than with search_entities(). In 0.7.0, entities created by automatic extraction are embedded with the same local model, so a semantic entity search can return them. It can also return similar entities from earlier runs, and ingest-time resolution can link a mention to an entity an earlier run stored, so the edges from this message are the exact record of this run. Messages are embedded too, which the next step checks.

6. Inspect the stored vectors

In the Aura console, open Query, select this lesson’s instance, connect with its credentials, and run:

MATCH (message:Message)
WHERE message.embedding IS NOT NULL
RETURN message.role, message.content, size(message.embedding) AS dimensions
LIMIT 10

Expected: each stored message vector has 384 dimensions. Then inspect the indexes:

SHOW VECTOR INDEXES YIELD name, options
RETURN name, options.indexConfig.`vector.dimensions` AS dimensions

The managed indexes for this fresh database should agree with that dimension. Inspect any mismatch before writing further records.

What we learned

The program selected an Anthropic completion/structured-output adapter and a separate local embedding adapter. It verified storage and retrieval without claiming a particular extraction result or universal first-call success.

Switching embedding models requires a migration even when dimensions happen to match. Follow the migration guide rather than changing a string against existing vectors.

Resume this lesson later

A new Python process keeps the same shell exports; a new terminal does not. If this lesson’s Aura instance still exists, resume it without creating another instance or asserting that its database is empty:

  1. Return to the existing folder and activate its environment:

    cd ~/agent-memory-tutorials
source .venv/bin/activate

  2. Re-export the original instance’s NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, and NEO4J_DATABASE from its saved credentials. Restore this page’s provider key/model/region settings too. Keep secrets out of the Python files.

  3. Check the same database:

    python wait_for_tutorial_neo4j.py

  4. Use the readback or inspection step described below. Do not repeat the seed/record/write command just to recover context. Preserve existing IDs and state until you know which operations completed.

If the instance was already destroyed, its stored results cannot be resumed; complete local cleanup and start a new empty lesson instance. A different lesson also starts with a fresh instance, while keeping the folder and environment.

Use the Aura vector/index queries from this page to inspect existing results. The main program creates a new session on every run; rerunning it is a new extraction/write operation, not a read-only resume.

Cleanup and next steps

Cleanup ends this lesson and removes its stored results. To keep working with those results later, follow Resume this lesson later before cleanup.

In the Aura console, select only the agent-memory-tutorial instance created for this lesson. Use its trashcan action, enter its exact name and confirm Destroy.

Expected: the tutorial instance disappears from the instance list. This removes its data and snapshots, so verify the instance name before confirming. See Aura instance deletion for the console procedure.

Remove the downloaded credentials for that deleted instance and clear its connection variables:

unset NEO4J_URI NEO4J_USERNAME NEO4J_PASSWORD NEO4J_DATABASE

Keep the tutorial folder and virtual environment. Start each Aura tutorial with a new empty lesson instance and its new credentials; this also avoids carrying over vector indexes from a lesson using a different embedding dimension.

Continue with the conversation lesson for an agent loop, or provider configuration for other deployments.