Skip to main content
GET
List memory entries
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

GET /api/v2/memory/list answers one page of memory entries. Pass limit (1 to 100, default 50; a larger value is 400 too_big) and, after the first page, cursor set to the previous page’s meta.nextCursor. Continue while meta.hasMore is true; meta.nextCursor is null on the last page.
  • layer=longterm (requires agentId): the agent’s ACTIVE long-term entries, newest first.
  • layer=channel with agentId: the agent’s channel entries in channelId order. With channelId alone (platform keys only): every agent’s entry for that channel, in creation order. With both: at most one entry, in a single page.
A page can be short, or empty, before the end, because entries the caller may not read are omitted after the page is read. Follow meta.hasMore, not the page size. An agentId outside the caller’s reach (an External App’s owner-scope chain; for an API key, memory:read at the agent’s home), or a Personal Agent, answers an empty list, and a listing by channelId alone leaves out such agents’ entries.

Errors

An unsupported layer (layer_not_supported); a limit of 0, a negative or non-integer value, or a repeated limit (Invalid limit); a malformed or repeated cursor, or one issued for another listing (Invalid cursor); a malformed channelId (Invalid channelId); or a missing agentId where one is required.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Query Parameters

layer
enum<string>
default:channel

Memory layer: channel (per-channel institutional memory) or longterm (RAG-indexed durable archive). Defaults to channel when omitted. Any other value answers 400 layer_not_supported.

Available options:
channel,
longterm
agentId
string

Only entries for this agent.

channelId
string

Only entries for this channel (layer=channel).

limit
integer
default:50

Entries per page, 1 to 100. A value above 100 is 400 too_big; zero, a negative or non-integer value, or a repeated parameter answers 400.

Required range: 1 <= x <= 100
cursor
string

The meta.nextCursor of the previous page. A cursor is valid only for the same layer and filters it was issued for; any other value answers 400.

Response

One page of memory entries

data
object[]
required
meta
object
required

A list page's continuation. While hasMore is true, nextCursor is a string: pass it as cursor for the next page. hasMore: false ends the list; with truncated: true, more exist past what this list reads, and no cursor reaches them.