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.

SDK: korely.add(content, ...). Korely saves the memory and replies at once. A model then extracts typed facts from the text and checks them against the facts already stored (contradiction). You never write supersede logic. The guide walks through the same call with a runnable example.

Authentication

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

Request body

Any other field is refused with 422 invalid_request (for example userId: Extra inputs are not permitted): field names are snake_case.

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_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b"

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_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b"

Response

201 Created. The stored memory, with status processing and an empty facts list: the facts arrive a few seconds later (see the note below).

{
  "id": "mem_8f2c1aab4d7e4f0c9a1b2c3d4e5f6a7b",
  "content": "User prefers email follow-ups, not phone",
  "user_id": "customer-giulia-4812",
  "agent_id": "support-bot",
  "run_id": null,
  "client": null,
  "kind": "note",
  "metadata": {},
  "status": "processing",
  "created_at": "2026-06-17T10:22:00.412345+00:00",
  "updated_at": null,
  "facts": []
}

Work sessions

curl -X POST https://api.korely.ai/v1/memories \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Session: moved the billing service to Postgres 16, tests pass, rollback script in ops/.",
    "user_id": "dev-team",
    "kind": "session"
  }'

korely.add(
    "Session: moved the billing service to Postgres 16, tests pass, rollback script in ops/.",
    user_id="dev-team",
    kind="session",
)

await korely.add(
  "Session: moved the billing service to Postgres 16, tests pass, rollback script in ops/.",
  { user_id: "dev-team", kind: "session" },
);

A memory with kind: "session" is stored, embedded and read into facts like any other. The difference is on the read side: pass exclude_sessions=true to Search memories, List memories, Get facts, Get profile or Get context, and the work sessions drop out, with the facts that only they state. A coding agent can keep its session logs in the same memory as the team's decisions, and a read that wants what was said and decided gets only that. The SDKs take kind from Python 0.1.26 and Node 0.1.16, and hand it back on every memory they return (Memory.kind) from Python 0.1.27 and Node 0.1.17.

Errors

Notes

• Who the memory is about (since 1.0.12). It depends on the ids you pass.
  • With a user_id, with or without an agent_id: the memory belongs to that end user, and "user" in its facts means that person.
  • With an agent_id and no user_id: the memory is the agent's own, such as a team's shared memory or an agent's own notes. Korely tells the model that no end user owns the memory and gives it three rules. First, "I" in the text is the agent that wrote it. Second, the subject of a procedure, a rule or a decision is the thing it describes ("Deploys run on Fridays" is about deploys). Third, a procedure, a rule in force, a habit or the result of something done that still holds (an approval, a revocation) is current from the date in the text, and past only when the text says it ended. Then Korely itself, not the model, drops any fact whose subject or object is user unless the text contains the English word "user" as a whole word ("The user prefers TypeScript" keeps it; "user_id" or "users" does not count). Up to 1.0.11 such a memory was read as an end user's, so a procedure could come back as user follows_procedure deploy. A confined key limited to one end user fills in that user_id when you leave it out, so its memories stay that person's.
  • With neither id, for example one person using the MCP or an SDK without ids: the memory is stored in the shared namespace, as before, and its facts are read as if an end user named "user" had said it, as in 1.0.11.
  If the memories you write with an agent_id are about one person, pass that person's user_id too. Moving to 1.0.12 does not change facts already written. A memory written or edited on 1.0.12, or still waiting for its facts when your install or the Cloud moves to 1.0.12, follows the new rules: editing an old memory that has an agent_id and no user_id can change its facts. This changes what the model is asked; the tests use a fake model with fixed answers, and how often a real model now gets the subject and the tense right is not measured yet.
• One write per 6,000 characters. An add of up to 6,000 characters counts one write against your monthly write quota, however many facts it produces. A longer one counts one write per 6,000 characters, rounded up: 16,000 characters, the most a memory can hold, count 3. The engine may make more extraction calls than that (its windows overlap); you pay only the writes. A memory that does not fit in the writes left this month is refused whole with 429 quota_exceeded.
• Contradictions are checked automatically. A model compares each new fact with the open facts it could conflict with and closes the ones the new fact replaces (a new address closes the old one; a second hobby does not). A closed fact is not deleted and stays readable with as_of. Write a change as a state (“costs 55 euro per month”), not as a story (“the price went up”): a story can leave the old fact open, most often when the project's region is eu.
• No idempotency. A retried write can store the memory twice and count two writes. An Idempotency-Key header is ignored.
• Messages, too. The SDKs accept a list of chat messages as content and join them into one block before sending.

Related

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