Metadata-Version: 2.4
Name: couchbase-agent-memory
Version: 1.1.0
Summary: Python SDK for the Couchbase Agent Memory API
Home-page: https://docs.couchbase.com/ai/build/agent-memory/about-agent-mem.html
Author: Couchbase Engineering
Keywords: couchbase,agent-memory,ai,memory,agents,llm,sdk
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.4.0
Requires-Dist: python-dotenv
Requires-Dist: h11>=0.16.0
Requires-Dist: anyio>=4.14.2
Provides-Extra: hermes
Dynamic: home-page
Dynamic: requires-python

# Couchbase Agent Memory Python SDK

[![Docs](https://img.shields.io/badge/docs-couchbase.com-blue)](https://docs.couchbase.com/agent-mem/current/about-agent-mem.html)
[![Python versions](https://img.shields.io/pypi/pyversions/couchbase-agent-memory)](https://pypi.org/project/couchbase-agent-memory/)

The official Python SDK for Couchbase Agent Memory, an enterprise-ready memory layer for AI agents.

Agent Memory allows AI agents to maintain persistent context and personalize interactions across sessions.
It stores conversation history and facts, and handles embeddings, summarization, and semantic retrieval, so you don't need to build session tables or retrieval logic.

The Agent Memory server runs fully managed on Couchbase Capella, or self-managed as a Docker container backed by a Capella or Couchbase Server Enterprise Edition cluster.

Before using the SDK, [request a trial of Couchbase Agent Memory](https://www.couchbase.com/downloads/?family=agent-memory).

## Prerequisites

- Python 3.12 or later.
- A running Agent Memory server, version 1.1.0 or later.
  To set up a server, see the [Agent Memory documentation](https://docs.couchbase.com/agent-mem/current/about-agent-mem.html).

## Installation

```bash
pip install couchbase-agent-memory
```

## Quickstart

```python
from agentmemory import AgentMemoryClient, ChatMessage

with AgentMemoryClient(base_url="http://localhost:8080") as client:
    user = client.create_user(user_id="customer-42", name="Example Customer")
    session = user.create_session(session_id="conv-100")

    # Store a conversation exchange, tagged with the agent that handled it
    session.add_memory(
        messages=[
            ChatMessage(
                user_content="My order hasn't arrived.",
                assistant_content="I'll look into that. What's your order number?",
            )
        ],
        annotations={"agent": "support-bot"},
    )

    # Store a standalone fact
    session.add_memory(
        facts=["Customer is in the EU timezone."],
        annotations={"agent": "support-bot"},
    )

    # Recall relevant context before the agent's next turn
    results = session.search_memory(query="shipping delay")
    for block in results.memory_blocks:
        print(block.fact or block.message.user_content)
```

If your server requires authentication, pass a token:

```python
AgentMemoryClient(base_url="<your-server-url>", token="<your-token>")
```

On managed Agent Memory, the token is an Agent Memory API key that you create in Capella.
You must also add your IP address to the server's allowed IP addresses.

On a self-managed server with authentication enabled, the token is a JSON Web Token (JWT) from your OpenID Connect (OIDC) identity provider.

## Features

- **Multiple memory types**, including conversational, semantic, and profile memory, in a single retrieval system, to enable scalable, context-aware multi-agent systems.
- **Semantic search** within a session or across all of a user's sessions.
- **Annotations** that tag memory blocks so you can filter recall by exact match.
- **Memory decay** through time to live (TTL) settings per block, per session, or server-wide.
- **Time-range filtering** that recalls memories by when they were created or stored.
- **Conflict resolution** through timestamps on every memory, so your agent can prefer the most recent of conflicting memories.
- **Custom extraction prompts** that steer what Agent Memory extracts for each use case.
- **High availability** through cluster mode, which runs multiple nodes behind a load balancer to handle more traffic and keep processing memories if a node fails.
- **Enterprise-grade security**, with token authentication and Role-Based Access Control.
- **Full traceability** for governance and debugging, through structured logs of memory operations and operational metrics.
- **Sync and async clients**, with `AsyncAgentMemoryClient` for asyncio applications.

## Framework Integrations

Agent Memory works with any agent framework, including LangGraph, CrewAI, LlamaIndex, and Strands Agents.
Call `search_memory()` before each agent turn to add relevant context to the prompt, and `add_memory()` after the turn to store the exchange.

### Hermes Agent

The SDK includes a memory-provider plug-in for [Hermes Agent](https://github.com/NousResearch/hermes-agent) 0.7.0 (v2026.4.3) or later.
The plug-in recalls relevant memories before each turn and captures each exchange in the background.

To install the plug-in:

```bash
pip install "couchbase-agent-memory[hermes]"
agentmemory-hermes install
```

Then activate and configure the plug-in in Hermes Agent.
Hermes Agent supports only 1 external memory provider at a time.
If you use another provider, turn it off before you activate this plug-in.

For further instructions, see [Install the Agent Memory Plug-in for Hermes Agent](https://docs.couchbase.com/agent-mem/current/develop/install-hermes-agent-mem.html#install).

## Documentation
For more details about this SDK, see:

- [About Agent Memory](https://docs.couchbase.com/agent-mem/current/about-agent-mem.html)
- [Develop with the Agent Memory SDK](https://docs.couchbase.com/agent-mem/current/develop/develop-agent-mem.html)
- [Agent Memory REST API Reference](https://docs.couchbase.com/agent-mem/current/agent-memory-api-reference/rest-api.html)

## Licensing and Support

Couchbase Agent Memory use and enterprise support is exclusively available by licensing Couchbase AI Data Plane, which also entitles use and enterprise support of Couchbase Agent Catalog and Couchbase MCP Server.

Licensed customers can raise issues through the [Couchbase support portal](https://support.couchbase.com/).

## Privacy

For information about how Couchbase collects, protects, and processes information, see the [Couchbase Privacy Policy](https://www.couchbase.com/privacy-policy).
