Core memory operations

Add a memory

Store a memory. Korely extracts typed facts and resolves contradictions server-side; you just send the text and a scope.

POST /v1/memories

SDK: korely.add(content, ...). The write path runs the intelligence, embeddings, entity and typed-fact extraction, contradiction checking with bi-temporal validity, server-side. You never write supersede logic.

Authentication

HTTP header, required: Authorization: Bearer kor_live_....

Request body

Field	Type	Required	Description
`content`	string	Required	The memory text. 1-16,000 characters.
`user_id`	string	Optional	The end user this memory belongs to. Max 255 chars.
`agent_id`	string	Optional	Your application's namespace. Max 255 chars.
`run_id`	string	Optional	One session or conversation. Max 255 chars.
`metadata`	object	Optional	Arbitrary JSON stored alongside the memory and echoed back on reads.
`timestamp`	string	Optional	ISO 8601 event time. Sets the bi-temporal `valid_from` on facts extracted from this memory, use it when backfilling historical memories so the timeline stays correct.

Example request

curl -X POST https://api.korely.ai/v1/memories \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers email follow-ups, not phone",
    "user_id": "customer-giulia-4812",
    "agent_id": "support-bot"
  }'

from korely_memory import Korely

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

memory = korely.add(
    "User prefers email follow-ups, not phone",
    user_id="customer-giulia-4812",
    agent_id="support-bot",
)

print(memory.id)   # "mem_8f2c1a"

import { Korely } from "korely-memory";

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

const memory = await korely.add(
  "User prefers email follow-ups, not phone",
  { user_id: "customer-giulia-4812", agent_id: "support-bot" },
);

console.log(memory.id); // "mem_8f2c1a"

Response

201 Created. The stored memory, plus the typed facts derived from it.

{
  "id": "mem_8f2c1a",
  "content": "User prefers email follow-ups, not phone",
  "user_id": "customer-giulia-4812",
  "agent_id": "support-bot",
  "run_id": null,
  "metadata": {},
  "created_at": "2026-06-17T10:22:00Z",
  "updated_at": "2026-06-17T10:22:00Z",
  "facts": []
}

Field	Type	Description
`id`	string	The memory id, e.g. `mem_8f2c1a`.
`content`	string	The text you stored, echoed back.
`user_id` / `agent_id` / `run_id`	string · null	The scope you sent, echoed back (`null` if omitted).
`metadata`	object	The metadata you sent (`{}` if omitted).
`created_at` / `updated_at`	string	ISO 8601 timestamps.
`facts`	array	Typed `(subject, predicate, object)` facts extracted from this memory. See the note on async extraction below.

Facts extract asynchronously. In production the add returns sub-second with facts: []; the extraction pipeline (entity + typed-fact extraction, contradiction checking) lands the facts a few seconds later. Read them back with Get facts or Get context on the next turn, don't block on them in the same request.

Errors

Status	Code	Cause
`401`	`invalid_key`	Missing or invalid `Authorization` header.
`422`	`invalid_request`	Validation failed, most often empty `content` or a field over its length limit.
`429`	`quota_exceeded`	Monthly write quota reached. No `Retry-After`; resets at the next billing cycle, or upgrade.

Notes

Counts as one write. Each add counts against your monthly write quota, regardless of how many facts it produces.
Contradictions are automatic. If this memory conflicts with an earlier fact (same predicate, different object), the old fact is superseded, invalidated, not deleted, and stays queryable via as_of.
Messages, too. The SDKs accept a list of chat messages as content and join them into one block before sending.

Add a memory, guide, the narrative walkthrough with context.
Search memories, read them back.
Get context, the assembled recall block.