Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Agent Memory API for Self-Managed Deployments

  • concept
The Agent Memory API is a REST API that allows your AI agents to store and retrieve persistent memory on a self-managed Agent Memory server.

This page is for self-managed Agent Memory.

The Agent Memory API is a REST API for the Couchbase Agent Memory server. It allows your AI agents to store and retrieve persistent memory across user sessions.

This page covers self-managed Agent Memory, where you deploy and run the Agent Memory server on your own infrastructure. Your Agent Memory server can store its data in a Capella operational cluster or a Couchbase Server Enterprise Edition cluster. For more information, see Agent Memory for Persistent Memory Storage.

You do not need any special tools, SDKs, or libraries to access the Agent Memory API. The Agent Memory API supports off-the-shelf HTTP clients, such as Insomnia or Postman.

To explore the Agent Memory API endpoints, you can use:

  • The Agent Memory API Reference, which you can browse without running a server.

  • The API explorers on your running Agent Memory server:

    • Swagger UI at /docs, such as http://localhost:8080/docs, where you can try any endpoint directly in the browser.

    • ReDoc at /redoc, such as http://localhost:8080/redoc, a read-only reference view of the full API spec.

The API explorers show the version of the API that your Agent Memory server runs.

Base URL

The base URL for the Agent Memory API is the hostname and port of your Agent Memory server:

http://localhost:8080
The Agent Memory server listens on port 8080 by default.

If you run your Agent Memory server on a different host or port, replace localhost:8080 with your host and port.

For more information, see Deploy Self-Managed Agent Memory for Production.

Versioning

The Agent Memory API uses semantic versioning. The full version number consists of 3 parts: major.minor.patch.

An update to the API may be a non-versioned bug fix, a patch update, a minor update, or a major update. When a non-versioned bug fix releases, the version number is not updated. When a patch, minor, or major update releases, the version number also updates.

Endpoint paths do not include the version. To check the version of your Agent Memory server, call the GET /health endpoint.

For more information about changes between versions, see The Agent Memory API Change Log.

Authentication and Authorization

Self-managed Agent Memory uses access tokens from your identity provider (IdP) for authentication, not Capella API keys.

By default, your Agent Memory server does not require authentication. To require authentication, connect your Agent Memory server to an IdP that supports OpenID Connect (OIDC). For more information, including the requirements for access tokens, see Configure Authentication for Self-Managed Agent Memory.

When your Agent Memory server requires authentication, pass the access token as a Bearer token in the HTTP Authorization header of each request.

The GET /health and GET /metrics endpoints do not require an access token.

Depending on your Agent Memory version, you can also enable role-based authorization to control which endpoints an access token can call. For more information, see Authorization in the Agent Memory API Reference.

Request Logging

Every Agent Memory API response includes an X-Request-ID header. To identify your application in the server logs, pass an optional X-Client-ID header with each request.

To download server logs for troubleshooting, call the GET /logs/collect endpoint.

Limits and Configuration

You configure your Agent Memory server’s limits with environment variables. These limits include extraction rate limits, queue size, and timeouts. For more information about the default values, see Self-Managed Agent Memory Environment Variable Reference.

For more information about endpoint-specific limits, such as page sizes, see the Agent Memory API Reference.

See Also