A surviving node takes over a failed node’s unfinished blocks after the failed node passes the dead-node threshold and the next recovery sweep runs. How long this takes depends on the heartbeat interval, dead-node threshold, recovery sweep interval, and own-lineage recovery interval. Each surviving node takes over the blocks of at most 1 failed node per recovery sweep. If more nodes fail than survive, recovery takes additional sweeps, so processing the unfinished blocks of some failed nodes may take longer.

On Managed Agent Memory, you cannot change the recovery timing.

On Self-Managed Agent Memory, to change the recovery timing, adjust the heartbeat and threshold variables in cluster mode. Lower values detect failures faster but add Couchbase traffic and restart briefly paused nodes more often. Keep AGENTMEMORY_DEAD_NODE_THRESHOLD_SECONDS at 3 times AGENTMEMORY_HEARTBEAT_INTERVAL_SECONDS or more. For example, if AGENTMEMORY_HEARTBEAT_INTERVAL_SECONDS is 30, set AGENTMEMORY_DEAD_NODE_THRESHOLD_SECONDS to 90 or more.

The requests per minute and tokens per minute limits apply to the whole cluster. On Managed Agent Memory, you set them in the Advanced settings when you deploy the server. On Self-Managed Agent Memory, you set them with AGENTMEMORY_MAX_REQUESTS_PER_MINUTE and AGENTMEMORY_MAX_TOKENS_PER_MINUTE. Each node uses an equal share, based on the number of live nodes, and recalculates its share every 30 seconds. If ingestion is uneven across nodes, the cluster uses less than the configured limits. Adding nodes does not increase extraction throughput beyond your model provider’s limits. On Self-Managed Agent Memory, to change the limits, update them on every node and restart every node.

Other limits, such as the maximum concurrent tasks and the maximum queue size, apply to each node.

In Agent Memory, a user is what interacts with your AI agent. Each user has a unique identifier that you generate. Agent Memory uses your user identifiers to isolate memory data and implement access control.

Each user can have multiple sessions.

A session represents an individual run or interaction between a user and your application. Sessions organize memory blocks for a specific user.

A session can be active or ended:

You can control the status of a user’s session through your agent application logic. Sessions persist in the Couchbase cluster you connect to Agent Memory. If your application restarts or disconnects, you can retrieve an existing session and continue adding memories.

A memory block is the basic unit of storage in Agent Memory. It captures information from a session.

This can be any important topic or fact from a session that you want to store for later recall.

Each memory block belongs to a specific session and contains:

You can use the vector embeddings for a memory block to retrieve relevant memories later, using a semantic search. Memory block timestamps help with conflict resolution and let you filter memories later by a time range.

You can set memory to decay over time to keep the agent’s working context relevant. Agent Memory uses TTL settings to automatically remove old memory blocks. TTL values follow a hierarchy with the most specific value taking precedence:

For more information, see Manage TTL.

When an agent retrieves contradictory memories, it uses the timestamp on each memory block to determine the most recent information.

You can track all memory operations to audit agent behavior and debug issues. Agent Memory records memory read and write operations in structured logs. These logs include user and session identifiers.

Agent Memory exposes operational metrics, including extraction queue depth, failure counts, and token throughput. On Managed Agent Memory, view them in Capella. For more information, see Monitor Managed Agent Memory. On Self-Managed Agent Memory, an embedded Prometheus instance exposes them. For more information, see Prometheus Metrics.

You must provide a valid Bearer token in the Authorization header of all API requests.

Authentication confirms the identity of a caller trying to access Agent Memory, while Authorization controls what an authenticated caller can do. Role-Based Access Control (RBAC) for Agent Memory restricts each operation to a minimum role. Agent Memory recognizes 3 fixed roles:

A token’s effective rank is the most privileged rank among the roles it carries. A token that carries ams_admin has full access without also carrying ams_rw or ams_ro.

Agent Memory isolates data at the user and session level. One user cannot access the memory space of another user. You can share memories across agents within the same application using annotation-based access control.