Core memory operations

Get a memory

Fetch one memory by id, with the facts it states that are true now.

GET /v1/memories/{memory_id}

SDK: korely.get(memory_id). Returns the stored memory and the facts it states that are true now. Use it to inspect one memory, or to check its status while the facts are being extracted.

Authentication

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

Path parameter

This endpoint takes a single path parameter and no query parameters or request body.

Parameter	Type	Required	Description
`memory_id`	string	Required	The memory id from the URL path. Accepts a `mem_`-prefixed public id (`mem_` and 32 hex characters, e.g. `mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c`) or a bare UUID.

Example request

curl https://api.korely.ai/v1/memories/mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c \
  -H "Authorization: Bearer kor_live_..."

from korely_memory import Korely

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

memory = korely.get("mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c")

print(memory.content)        # "Giulia prefers async standups and works in CET."
print(len(memory.facts))     # 1

import { Korely } from "korely-memory";

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

const memory = await korely.get("mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c");

console.log(memory.content);     // "Giulia prefers async standups and works in CET."
console.log(memory.facts?.length ?? 0); // 1

Response

200 OK. The memory, plus every typed fact currently active for it.

{
  "id": "mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c",
  "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+00:00",
  "updated_at": null,
  "facts": [
    {
      "id": "fct_3b9e1d7a5c2f4e8a9d6b0c1f7a2e4d85",
      "subject": "Giulia",
      "subject_type": "person",
      "predicate": "likes",
      "predicate_raw": "prefers",
      "object": "async standups",
      "object_is_literal": true,
      "predicate_family": "preferences",
      "confidence": 0.91,
      "user_id": "customer-giulia-4812",
      "agent_id": "onboarding-bot",
      "valid_from": "2026-03-01T00:00:00+00:00",
      "invalid_at": null,
      "invalidated_by": null,
      "source_memory_id": "mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c",
      "created_at": "2026-03-01T09:14:25+00:00",
      "closed_known_at": null,
      "subject_canonical": "Giulia",
      "object_canonical": "async standups",
      "subject_link_id": null,
      "object_link_id": null,
      "tense": "current",
      "last_confirmed_at": "2026-03-01T00:00:00+00:00",
      "observation_count": 1,
      "source_memory_ids": ["mem_8f2c1a0b9d3e4f5a6b7c8d9e0f1a2b3c"]
    }
  ]
}

Field	Type	Description
`id`	string	Public memory id (`mem_` prefixed).
`content`	string	Memory content.
`user_id`	string · null	The end user this memory belongs to; `null` if none.
`agent_id`	string · null	The agent (agent_id); `null` if none.
`run_id`	string · null	The run (run_id); `null` if none.
`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.
`kind`	string	`note`, or `session` for the log of a work session (the `kind` of the write).
`metadata`	object	The metadata you stored with the memory.
`created_at`	string · null	ISO 8601 timestamp, nullable.
`updated_at`	string · null	ISO 8601 timestamp of the last edit; `null` if the memory was never edited.
`status`	string	`processing` while the facts are being extracted, `ready` once they are, `error` if extraction failed (see When extraction fails). `ready` can come with an empty `facts` list, when the text states no fact.
`facts`	array<object>	The facts this memory states that are true now, born from it or restated by it, so `source_memory_id` can name another memory. Each fact has the shape of Get facts: `id` (`fct_` prefixed), `subject`, `subject_type`, `predicate`, `predicate_raw`, `object`, `object_is_literal`, `predicate_family`, `confidence`, `user_id`, `agent_id`, `valid_from`, `invalid_at`, `invalidated_by`, `source_memory_id`, `created_at`, `closed_known_at`, `subject_canonical`, `object_canonical`, `subject_link_id` and `object_link_id` (string · null: the id of a link that makes two names one; usually `null`), `tense`, `last_confirmed_at`, `observation_count` and `source_memory_ids`.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `kor_live_` key, `Invalid or missing API key: ...`, then what is wrong.
`403`	`forbidden`	The key lacks the `memories:read` scope; `message` names it.
`404`	`not_found`	Unparseable memory id, or no live memory with that id is visible to the key: it never existed, it was forgotten, it is in another project or, for a key confined to some end users, it belongs to another end user. Message: `Memory not found`.
`429`	`quota_exceeded`	Monthly query quota exceeded.
`429`	`rate_limit_exceeded`	Past the rate limit. Wait as long as `Retry-After` says.
`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

Accepts both id forms. Pass a mem_-prefixed public id or a bare UUID, both resolve to the same memory.
Facts are the open set. The facts array holds the open facts this memory states. A closed fact is not returned here: read it in Memory history, or with include_invalidated=true on Get facts.
Counts as one read. Each get counts against your monthly query quota, a 404 for a well-formed id that matches no memory included. An id that cannot be parsed is refused before it is counted.

When extraction fails

A memory ends in status: "error", with no facts, when the model's answer about it cannot be used, or when the model refuses it or runs out of time on it five times while it goes on writing other memories. The text itself stays stored. While the model is unreachable or refuses everybody, a memory stays processing and its facts are written once the model answers again. List the memories that ended in error with GET /v1/events?status=error. On the Cloud, updating the memory puts it back in the queue, and the extraction runs again on the new text. On Self-hosted, manage reextract puts them back in the queue once the cause is fixed:

docker compose exec api python -m korely_agent.manage reextract

Search memories, find memories by semantic query.
Get context, the assembled recall block, facts plus memories.
SDK reference, the typed client methods.