---
title: "List Memories"
method: GET
path: "/v1/memories"
tags: ["v1"]
---

# List Memories

`GET /v1/memories`

## Request

- Base URL: `https://api.korely.ai`
- URL: `https://api.korely.ai/v1/memories`
- Auth: HTTP bearer

The memories of this key's project, newest first, a page at a time
(`limit`, `offset`); `total` counts them all. Narrow it with `user_id`,
`agent_id` and `run_id`. Forgotten memories are not listed.

Each memory's `status` says whether its facts are ready; the facts are on
`GET /v1/memories/{memory_id}` and `GET /v1/facts`.

## Query parameters

- `user_id` string, nullable: Filter to one end user.
- `agent_id` string, nullable: Filter to one agent namespace.
- `run_id` string, nullable: Filter to one run/session.
- `limit` integer
- `offset` integer
- `exclude_sessions` boolean: Leave out the work sessions (memories written with `kind: session`, what a coding assistant's hooks save), for a read that wants what was said and decided. Default false: everything.

## Response `200`

Successful Response

- MemoryList
  - `memories` Memory[], required
    - `id` string, required
    - `content` string, required
    - `user_id` string, nullable, required
    - `agent_id` string, nullable, required
    - `run_id` string, nullable, required
    - `client` string, nullable: The tool that wrote it: the X-Korely-Client header of the write, or the name an MCP client gave when it connected. A label, not a namespace: no read is scoped by it and the agent cap does not count it.
    - `kind` string: `note`, or `session` for the log of a work session (`kind` of the write).
    - `metadata` object, required
    - `status` string: Whether this memory's typed facts are queryable yet: 'processing', 'ready', or 'error'. Extraction runs after the write returns, so a read taken immediately can legitimately find no facts. Poll GET /v1/events or read the memory again: no webhook says that extraction finished (`memory.created` is sent when the memory is stored, before its facts).
    - `created_at` string, nullable, required
    - `updated_at` string, nullable, required
  - `total` integer, required

## Other responses

- `401`: `invalid_key`: the `Authorization: Bearer` key is missing, unknown, revoked or expired.
- `403`: `forbidden`: the key lacks the scope this operation needs; `message` names it.
- `422`: `invalid_request`: the body, a query parameter or a path parameter is malformed (`detail` is the list of fields that failed, `message` names the first), or the endpoint refuses a value (an empty content, an unreadable timestamp; `detail` is a sentence or `{code, message}`).
- `429`: `rate_limit_exceeded`: past the request ceiling, the per-minute one set on this install (`RATE_LIMIT_PER_MINUTE`) or, on the hosted service, the plan's minute, hour or day; `message` names the window and `Retry-After` the seconds until it resets. On this service also `quota_exceeded`: the plan's queries of the month are spent (`limit`, `used`, `resets_at`, and no `Retry-After`: a retry fails until `resets_at` or a bigger plan).
- `500`: `internal_error`: the server failed on this request; `message` holds no detail of it.
- `503`: A dependency did not answer: the database while the key was checked (`unavailable`, see `Retry-After`), or the one `code` names. Nothing was written; retry.

---

[API](https://skmtc.dev/korely/apis/korely-agents-api.md) · [All operations](https://skmtc.dev/korely/apis/korely-agents-api/llms.txt) · [OpenAPI document](https://skmtc.dev/korely/apis/korely-agents-api/revisions/8a40bf09eca1?raw)