List memories

curl -G https://app.band.ai/api/v1/agent/memories \
     -H "X-API-Key: <apiKey>" \
     --data-urlencode "content_query=prefers SUV" \
     -d cursor=eyJ0IjoiMjAyNC0wMS0xNVQxMDozMDowMFoiLCJpIjoiNTUwZTg0MDAifQ \
     -d limit=20 \
     -d memory_scope=me \
     -d page=1 \
     -d page_size=20 \
     -d scope=subject \
     -d segment=user \
     -d status=active \
     -d subject_id=daca00d0-eb6b-4db1-8201-c46015c93d04 \
     -d system=long_term \
     -d type=semantic

{
  "data": [
    {
      "content": "string",
      "id": "string",
      "inserted_at": "2024-01-15T09:30:00Z",
      "scope": "agent",
      "segment": "user",
      "system": "sensory",
      "type": "iconic",
      "metadata": {},
      "organization_id": "string",
      "source_agent_id": "string",
      "status": "active",
      "subject_id": "string",
      "thought": "string"
    }
  ],
  "meta": {
    "has_more": true,
    "limit": 1,
    "next_cursor": "string",
    "page": 1,
    "page_size": 1,
    "total_count": 1,
    "total_pages": 1
  },
  "metadata": {
    "has_more": true,
    "limit": 1,
    "next_cursor": "string",
    "page": 1,
    "page_size": 1,
    "total_count": 1,
    "total_pages": 1
  }
}

Lists memories accessible to the agent. Two independent dimensions:

memory_scope — WHOSE memories. me (default) returns only the memories this agent stored, whatever their scope. org returns the organization’s shared memories, and is rejected with 422 when the agent belongs to no organization.
scope — WHICH category. Omitted at memory_scope=me it does not narrow at all. Omitted at memory_scope=org it means organization: an org-wide read returns the organization’s shared knowledge, never subject-scoped memories about unrelated people. A subject is reachable only by passing scope=subject with its subject_id.

Another agent’s agent-scoped memories are never returned, at any memory_scope.

Use content_query for full-text search across memory content.

Pagination: Use cursor + limit (recommended) OR page + page_size (deprecated, sunset 2026-10-01). Do NOT mix families.

Lists memories accessible to the agent. Two independent dimensions: - `memory_scope` — WHOSE memories. `me` (default) returns only the memories this agent stored, whatever their scope. `org` returns the organization's shared memories, and is rejected with 422 when the agent belongs to no organization. - `scope` — WHICH category. Omitted at `memory_scope=me` it does not narrow at all. Omitted at `memory_scope=org` it means `organization`: an org-wide read returns the organization's shared knowledge, never subject-scoped memories about unrelated people. A subject is reachable only by passing `scope=subject` with its `subject_id`. Another agent's `agent`-scoped memories are never returned, at any `memory_scope`. Use `content_query` for full-text search across memory content. **Pagination:** Use `cursor` + `limit` (recommended) OR `page` + `page_size` (deprecated, sunset 2026-10-01). Do NOT mix families.

Authentication

X-API-Keystring

Enter your API key for programmatic access

Query parameters

cursorstringOptional

Opaque cursor for keyset pagination

limitintegerOptional

Max results per request (1-100, default 20)

pageintegerOptionalDeprecated

Page number (offset pagination) - DEPRECATED

subject_idstringOptional

Filter by subject UUID (required for subject-scoped queries)

scopestringOptional

Filter by scope: agent, subject, organization, or all

memory_scopeenumOptional

Whose memories to return: ‘me’ (default, this agent only) or ‘org’ (all agents in the organization)

Allowed values:

systemstringOptional

Filter by memory system

typestringOptional

Filter by memory type

segmentstringOptional

Filter by segment

content_querystringOptional

Full-text search query

page_sizeintegerOptionalDeprecated

Number of results per page (max 50) - DEPRECATED

statusstringOptional

Filter by status: active, superseded, archived, or all

Response

Memories

datalist of objectsOptional

metaobjectOptional

Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path)

metadataobjectOptional

Pagination metadata (cursor fields on the keyset path, offset fields on the deprecated path)

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

Lists memories accessible to the agent. Two independent dimensions:

memory_scope — WHOSE memories. me (default) returns only the memories this agent stored, whatever their scope. org returns the organization’s shared memories, and is rejected with 422 when the agent belongs to no organization.
scope — WHICH category. Omitted at memory_scope=me it does not narrow at all. Omitted at memory_scope=org it means organization: an org-wide read returns the organization’s shared knowledge, never subject-scoped memories about unrelated people. A subject is reachable only by passing scope=subject with its subject_id.

Another agent’s agent-scoped memories are never returned, at any memory_scope.

Use content_query for full-text search across memory content.

Pagination: Use cursor + limit (recommended) OR page + page_size (deprecated, sunset 2026-10-01). Do NOT mix families.