---
title: "List memories"
method: GET
path: "/api/v1/agent/memories"
tags: ["agentApiMemories"]
---

# List memories

`GET /api/v1/agent/memories`

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.

## Query parameters

- `cursor` string
- `limit` integer
- `page` integer
- `subject_id` string
- `scope` string
- `memory_scope` 'me' | 'org'
- `system` string
- `type` string
- `segment` string
- `content_query` string
- `page_size` integer
- `status` string

## Headers

- `X-API-Key` string, required

## Response `200`

Memories

- MemoriesListAgentMemoriesResponse200 — unresolved $ref

## Other responses

- `401` — Unauthorized
- `422` — Invalid pagination params (invalid/unsupported cursor, or mixed cursor + offset families)

## Changes

- **2026-08-26** `3cff423845a2` — 1 info
  - added the new optional `query` request parameter `memory_scope`
- **2026-08-22** `d4b03725c5d7` — 2 info
  - `query` request parameter `page` was deprecated
  - `query` request parameter `page_size` was deprecated

[Change history](https://skmtc.dev/band/apis/request-api/changes/api/v1/agent/memories/get.md)

---

[API](https://skmtc.dev/band/apis/request-api.md) · [All operations](https://skmtc.dev/band/apis/request-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/band/request-api/revisions/3cff423845a2/schema)