Core memory operations

List memories

Page through the memories in the key's project, newest first. Filter by end user, by agent, or both; omit them to list across every end user.

GET /v1/memories

This returns stored memories in the list shape: id, content, the scope, metadata and status, without a facts array. To read the facts, use Get facts. Forgotten memories are not listed, and total does not count them.

Authentication

HTTP header, required: Authorization: Bearer kor_live_.... The key must carry the memories:read permission.

Query parameters

Parameter	Type	Required	Description
`user_id`	string	Optional	Filter to one end user. 1 to 255 characters; an empty string is refused (leave the field out instead). When omitted, lists across all end users the key can read.
`agent_id`	string	Optional	Filter to one agent (agent_id). Same rule as `user_id`.
`run_id`	string	Optional	Filter to one run or session (run_id). Max 255 chars.
`limit`	integer	Optional	Page size. Default `50`, min `1`, max `200`.
`offset`	integer	Optional	Pagination offset. Default `0`, min `0`. At most `9223372036854775807` (2^63-1); a larger one answers `422`.
`exclude_sessions`	boolean	Optional	Leave out the work sessions, the memories written with `kind: "session"` (what a coding assistant's hooks save), for a list of what was said and decided. Default `false`: everything. See Work sessions.

Example request

curl -X GET "https://api.korely.ai/v1/memories?user_id=customer-giulia-4812&agent_id=onboarding-bot&limit=50&offset=0" \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

page = korely.get_all(
    user_id="customer-giulia-4812",
    agent_id="onboarding-bot",
    limit=50,
    offset=0,
)

print(page.total)              # 1
for memory in page.memories:
    print(memory.id, memory.content)

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: "kor_live_..." });

const page = await korely.getAll({
  user_id: "customer-giulia-4812",
  agent_id: "onboarding-bot",
  limit: 50,
  offset: 0,
});

console.log(page.total); // 1
for (const memory of page.memories) {
  console.log(memory.id, memory.content);
}

Response

200 OK. A page of memories plus the total count of matches across all pages.

{
  "memories": [
    {
      "id": "mem_8f2c1a",
      "content": "Giulia prefers async standups and works in CET.",
      "user_id": "customer-giulia-4812",
      "agent_id": "onboarding-bot",
      "run_id": null,
      "client": null,
      "kind": "note",
      "metadata": {"source": "slack"},
      "status": "ready",
      "created_at": "2026-03-01T09:14:22.418093+00:00",
      "updated_at": null
    }
  ],
  "total": 1
}

Field	Type	Description
`memories`	array<Memory>	A page of Memory objects, newest first. Each has the fields below. There is no `facts` field in the list shape.
`memories[].id`	string	The memory id (`mem_` prefix).
`memories[].content`	string	The text you stored, in full (a search returns a snippet).
`memories[].user_id` / `agent_id` / `run_id`	string · null	The scope the memory was written with; `null` if none.
`memories[].client`	string · null	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.
`memories[].kind`	string	`note` or `session` (kind).
`memories[].metadata`	object	The metadata you stored.
`memories[].status`	string	`processing`, `ready` or `error`: whether the facts are readable yet (status).
`memories[].created_at` / `updated_at`	string · null	ISO 8601 timestamps. `updated_at` stays `null` until the memory is edited.
`total`	integer	Total matching memories across all pages, for paginating with `offset`. It does not count forgotten memories.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key, `Invalid or missing API key: ...`, then what is wrong.
`403`	`forbidden`	Key lacks the `memories:read` scope, `API key missing required scope(s): memories:read`.
`429`	`quota_exceeded`	Monthly query quota reached. Resets on the 1st of the month (UTC), or upgrade.
`429`	`rate_limit_exceeded`	The account's request ceiling (rate limit; on the Cloud, the plan's minute, hour or day window), shared by every key of the account. Retry after the `Retry-After` header.
`422`	`invalid_request`	`limit` out of the `1..200` range, `offset` below `0` or above 2^63-1, or an id filter (`user_id`, `agent_id`, `run_id`) that is empty or longer than 255 characters.
`500`	`internal_error`	The server failed on this request; the message holds no detail.
`503`	`unavailable`	The database did not answer while the key was checked. Retry after the seconds in `Retry-After`.

Notes

Defaults. limit=50, max 200, offset=0. Page by advancing offset until you have read total items.
Omit user_id to list across all end users. Add it to scope the page to a single end user; add agent_id to scope to one namespace.
List shape only. Items are Memory objects without the facts array, read typed facts with Get facts.
Counts as a read. Each call counts against your monthly query quota.
No status filter. To find the memories whose extraction failed, use List events with status=error.

Search memories, semantic recall instead of a flat page.
Get facts, the typed bi-temporal facts for a scope.
SDK reference, the typed client methods.