Core memory operations

List memories

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

GET /v1/memories

This returns stored memories in the list shape, id, content, scope, and metadata, without the derived facts array. To read the typed facts for a scope, use Get facts.

Authentication

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

Query parameters

Parameter	Type	Required	Description
`user_id`	string	Optional	Filter to one end user. When omitted, lists across all end users.
`agent_id`	string	Optional	Filter to one agent namespace.
`run_id`	string	Optional	Filter to one run or session. 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 `id` (`mem_` prefix), `content`, `user_id` (end user, nullable), `agent_id` (nullable), `run_id` (nullable), `client` (string, nullable: the tool that wrote it, from the `X-Korely-Client` header of the write or the name an MCP client gave when it connected; a label, not a namespace), `kind` (`note` or `session`), `metadata` (object), `status` (`processing`, `ready` or `error`: whether its typed facts are queryable yet), `created_at` and `updated_at` (ISO 8601, nullable; `updated_at` stays `null` until the memory is edited). No `facts` in the list shape.
`total`	integer	Total matching memories across all pages, for paginating with `offset`.

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 (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, or `offset` below `0`.

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.

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.