Get Started with Managed Agent Memory

how-to

Deploy a Managed Agent Memory server in Capella and store and retrieve memory using its Python SDK.

Use this quickstart to get a Managed Agent Memory server running in Capella. Then, write a Python script that stores and retrieves memories.

To run the Agent Memory server on your own infrastructure instead, see Get Started with Self-Managed Agent Memory.

Prerequisites

You have the Organization Owner role, or the Project Owner role in the project where you want to deploy your server.
You have a healthy operational cluster in Capella that meets all of the following requirements:
- Runs Couchbase Server 8.0 or later.
- Runs the Data, Index, Query, and Search services.
- Runs on AWS in 1 of the following regions:
  - US East (N. Virginia), us-east-1
  - Europe (London), eu-west-2
- Does not already have an Agent Memory server.
For more information about creating a cluster, see Create A Paid Cluster.
You have a bucket on that cluster for Agent Memory to store its data in. For more information, see Create a Bucket.
You have added an OpenAI API key to the AI Data Plane as an integration. For more information, see Manage AI Integration Settings.
You have Python 3.12 or later installed.

For the full list of requirements, see Prerequisites.

Step 1: Deploy Your Agent Memory Server

This step uses the default settings for your server. For every setting you can choose, see Deploy Managed Agent Memory.

To deploy your server:

Go to AI Data Plane Services Agent Memory.
Click Deploy Agent Memory.
In the Cluster list, choose your cluster, and click Continue.
In the Bucket list, choose the bucket for Agent Memory.
Accept the generated name, the default Small compute tier, and the default node count. Click Next.
On the Models step, for both the embedding model and the LLM, choose OpenAI as the Model Source, choose a model, and choose your OpenAI integration.
Click Next.
On the Advanced step, accept the default settings, and click Next.
On the Review step, click Deploy Agent Memory.
Wait until your server has the Healthy status in the AI Data Plane Services Agent Memory list.

Step 2: Allow Requests from Your Machine

Your server blocks all requests until you add an allowed IP address.

To allow requests from your development machine:

Next to your Agent Memory server, click the More Options (⋮) menu.
Click Add Allowed IP.
In the Select Allowed IP list, select Add Current IP Address.
Click Add Allowed IP Address.

Step 3: Create an API Key and Copy Your Endpoint

To get the API key token and endpoint your script needs:

Next to your Agent Memory server, click the More Options (⋮) menu.
Click Generate API Key.
In the API Key Name field, enter a name for the API key.
Under Access, select Write.
Click Generate API Key.
Save the API key token. Click Download Key to save it to a file, or copy the API Key Token and paste it somewhere. It’s required for Step 5.

You cannot copy or download the API key token again after you leave this page.
Click Close.
Click the name of your Agent Memory server.
In the Connect section, copy the Endpoint and save it with your API key token.

For other access levels and expiry options, see Generate Agent Memory API Keys.

You now have the endpoint and API key token for the script in Step 5.

Step 4: Install the Python SDK

To install the Python SDK on the machine where you want to develop with Agent Memory:

Create and activate a virtual environment in your project directory:
```
python -m venv .venv
source .venv/bin/activate
```
You can also use Conda or another virtual environment manager.

Install the Agent Memory Python SDK:

python -m pip install --upgrade pip
python -m pip install couchbase-agent-memory

Step 5: Store and Retrieve Memory

You can use the following quickstart example to learn how to store and retrieve memories from Agent Memory:

Create a file called quickstart.py and add the following code. This code demonstrates creating a user and session, storing memory blocks, and retrieving them by semantic search:

from agentmemory import AgentMemoryClient, ChatMessage

with AgentMemoryClient(base_url="<your-agent-memory-endpoint>", token="<your-api-key-token>") as client:

    # Create a persistent user identity
    user = client.create_user(user_id="customer-42", name="Example Customer")
    print(f"Created user: {user.user_id}")

    # Open a session — the container for this conversation's memory blocks
    session = user.create_session(session_id="ticket-4821")
    print(f"Created session: {session.session_id}")

    # Store a conversation exchange.
    # async_processing=False waits for semantic extraction to finish;
    # all returned blocks are in ready status on return.
    r1 = session.add_memory(
        messages=[
            ChatMessage(
                user_content="My payments keep failing at checkout.",
                assistant_content="I can help with that. Are you seeing a specific error code?",
            )
        ],
        async_processing=False,
    )
    print(f"Stored message block(s): {r1.block_ids}")

    # Store a discrete fact extracted from the conversation
    r2 = session.add_memory(
        facts=["Customer is on the free tier and has not added a payment method."],
        async_processing=False,
    )
    print(f"Stored fact block(s):    {r2.block_ids}")

    # Retrieve memory blocks relevant to a query via semantic search
    print("\nRetrieving memories relevant to 'billing issues'...")
    results = session.search_memory(query="billing issues")

    for block in results.memory_blocks:
        if block.message:
            print(f"  User:      {block.message.user_content}")
            print(f"  Assistant: {block.message.assistant_content}")
        if block.fact:
            print(f"  Fact: {block.fact}")

    session.end()
    print("Session ended.")

add_memory() always generates embeddings before it returns, so stored blocks are searchable as soon as the call completes. async_processing=False also makes add_memory() wait for semantic extraction to finish, which adds latency per call. In production, use the default async_processing=True, which runs extraction in the background.

Replace <your-agent-memory-endpoint> with your Agent Memory server endpoint, and <your-api-key-token> with your API key token.

Run the file:
```
python quickstart.py
```

Review your expected output:

Created user: customer-42
Created session: ticket-4821
Stored message block(s): ['<block-id-1>']
Stored fact block(s):    ['<block-id-2>']

Retrieving memories relevant to 'billing issues'...
  User:      My payments keep failing at checkout.
  Assistant: I can help with that. Are you seeing a specific error code?
  Fact: Customer is on the free tier and has not added a payment method.
Session ended.

Agent Memory stored both blocks, generated a vector embedding for each, and returned them based on semantic similarity to the search query. The order of the results can vary.

If you run the script again, create_user() raises ConflictError because the user already exists. To run it again, change the user_id and session_id values.

Step 6: Explore the API Interactively

Your Agent Memory server serves 2 API explorers. Replace <your-agent-memory-endpoint> with your Agent Memory server endpoint in the following URLs:

<your-agent-memory-endpoint>/docs: Swagger UI. Try any endpoint directly in the browser, with request and response schemas auto-populated from the OpenAPI spec.
<your-agent-memory-endpoint>/redoc: ReDoc. A read-only reference view of the full API spec.

You can also browse the same endpoints without running a server, in the Agent Memory API Reference.

Troubleshooting

If requests from your machine are blocked: Check that the IP address you’re connecting from is on your server’s allowed IP address list. For more information, see Allowed IP Addresses.
If you receive AuthenticationError with the error code INVALID_TOKEN: Check that you passed the API key token, not the API key ID, and that the key belongs to this server and has not expired or been deleted.
If you receive AuthorizationError: Your API key’s access level is too low for the operation. This quickstart needs the Write access level. For more information, see API Key Access Levels.

For more troubleshooting, see Troubleshooting.

For AI agents: