Core operations

Add a memory

Store a text or a chat thread about one of your users. Korely saves it at once, then extracts facts from it.

add() saves a memory and replies with status processing. A language model then reads the text and extracts facts. For example: subject Northwind Hosting, predicate costs, object 50 euro per month. This usually takes about ten seconds.

Quick start

You need Python 3.9 or later, pip install korely-memory (the Python SDK), and an API key (kor_live_...). Get a free API key (Quickstart).

The code writes one memory. After a wait, it reads the memory's status and its facts.

from korely_memory import Korely
korely = Korely(api_key="kor_live_...")
memory = korely.add("Northwind Hosting costs 50 euro per month since the June upgrade.", user_id="customer-4812")
# In a Python console, run the next two lines about ten seconds later:
print(korely.get(memory.id).status)   # ready
print(korely.get_facts(entity="Northwind Hosting", user_id="customer-4812"))

entity is the subject you ask about (Glossary). You see ready and a list with one fact: predicate costs, object 50 euro per month. If the status is still processing, wait and run the last two lines again. If it is ready and the list is empty, the memory finished with no facts. If it is error, see status under Response.

Call add() after any turn where the user reveals something worth remembering: a preference, a decision, a fact about themselves.

Terms

The Glossary defines the words used across the docs. This page adds three.

• Shared memory: a memory written with no user_id. A read that passes a user_id does not find it.
• Top-up: extra writes that a paid plan buys for the current month.
• Confined key rule: a confined key writes only for its own end users, and names one with user_id. Exception: a key confined to one end user, such as customer-4812, may leave user_id out; the write goes to that end user.

Reference

The Quick start is enough for a first try. Read on when you build your integration: parameters, response, errors and limits.

What happens on a write

flowchart LR
    A([add content]) --> B[Store memory]
    B --> C[Embed memory]
    C --> I([Reply: status processing])
    C -.-> E[Extract facts]
    E --> N[Entities: subjects, named objects]
    E --> F{Contradiction?}
    F -- yes --> G[Supersede old fact]
    F -- no --> H[Record new fact]

The subject of each fact is an entity, and so is an object that names something (a company, a person, a city) rather than a value such as 50 euro per month. With entities you retrieve everything known about one person, company or product: get_facts(entity="Northwind Hosting") (The graph).

A filter then picks earlier facts that might conflict with each new fact, and a model judges them (contradiction). If the price goes from 50 to 80 euro, the 50 euro fact is superseded (closed).

Each API key belongs to a project. Each project has a region (global by default, or eu), chosen on the Projects page of the dashboard; the extraction quality can differ between regions, see Regions.

Request

Endpoint: POST /v1/memories, which answers 201 on success. SDK: korely.add(content, *, user_id=None, agent_id=None, run_id=None, metadata=None, timestamp=None, kind=None).

Any other field is refused with 422 invalid_request (for example "userId is not a field here. Did you mean user_id?"): field names are snake_case.

Example

The full example adds metadata and an agent, then waits for the facts. Its agent_id="infra-bot" takes one of your plan's agents (the free Hobby plan has 2). Node needs version 18 or later and npm install korely-memory.

import time
from korely_memory import Korely

korely = Korely(api_key="kor_live_...")

result = korely.add(
    "Northwind Hosting costs 50 euro per month since the June upgrade.",
    user_id="customer-4812",
    agent_id="infra-bot",
    metadata={"source": "slack", "channel": "#billing"},
)
print(result.id)       # mem_8f2c1a4d9b3e47a6b05e2c7d1f3a9e84
print(result.status)   # processing: the facts are extracted after the reply

# Check the status every 2 seconds, for at most one minute
status = result.status
for _ in range(30):
    if status != "processing":
        break
    time.sleep(2)
    status = korely.get(result.id).status
print(status)          # ready (or error)

facts = korely.get_facts(entity="Northwind Hosting", user_id="customer-4812")
for fact in facts:
    print(fact.predicate, fact.object)   # costs 50 euro per month

import { Korely } from "korely-memory";

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

const result = await korely.add(
  "Northwind Hosting costs 50 euro per month since the June upgrade.",
  {
    user_id: "customer-4812",
    agent_id: "infra-bot",
    metadata: { source: "slack", channel: "#billing" },
  }
);
console.log(result.id);      // mem_8f2c1a4d9b3e47a6b05e2c7d1f3a9e84
console.log(result.status);  // processing: the facts are extracted after the reply

// Check the status every 2 seconds, for at most one minute
let status = result.status;
for (let i = 0; i < 30 && status === "processing"; i++) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  status = (await korely.get(result.id!)).status;
}
console.log(status);         // ready (or error)

const facts = await korely.getFacts({ entity: "Northwind Hosting", user_id: "customer-4812" });
for (const fact of facts) console.log(fact.predicate, fact.object);   // costs 50 euro per month

curl -X POST https://api.korely.ai/v1/memories \
  -H "Authorization: Bearer kor_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Northwind Hosting costs 50 euro per month since the June upgrade.",
    "user_id": "customer-4812",
    "agent_id": "infra-bot",
    "metadata": {"source": "slack", "channel": "#billing"}
  }'

Over REST, read the status with GET /v1/memories/{id}. If the loop ends on processing, read the status again later.

Response

The reply of the cURL example, with HTTP status 201:

{
  "id": "mem_8f2c1a4d9b3e47a6b05e2c7d1f3a9e84",
  "content": "Northwind Hosting costs 50 euro per month since the June upgrade.",
  "user_id": "customer-4812",
  "agent_id": "infra-bot",
  "run_id": null,
  "client": null,
  "kind": "note",
  "metadata": { "source": "slack", "channel": "#billing" },
  "status": "processing",
  "created_at": "2026-06-15T09:14:00.412345+00:00",
  "updated_at": null,
  "facts": []
}

Response fields

Errors

Every error carries code (stable, shown below: branch on it) and message (for a person). detail is kept for older clients; on a 422 it lists the fields that failed.

Notes

• Calling twice writes twice. Two identical calls store two memories; their facts are counted once more (observation_count 2), not duplicated.
• Write quota. Each add() counts one write per 6,000 characters of content, rounded up, so at most 3. The quota resets on the 1st of the month, UTC.

Details

• Shared memory. korely.search("office hours") finds it; korely.search("office hours", user_id="customer-4812") does not. Leaving out user_id or agent_id on a read does not filter by it.
• Id rules. user_id and agent_id: 1 to 255 characters; not empty, not . or .., no / or control characters, not starting with erased:, which Korely reserves for the erased end users in its records.
• client. From the X-Korely-Client request header. null with cURL and no header; the SDKs always send it.
• valid_from. Korely takes the first of these that applies:
  1. the request's timestamp;
  2. a date the text states with its year, never a future one: "since March 2026" gives 2026-03-01;
  3. a day the text says it happened ("yesterday") gives that day;
  4. the time of the write.
• Reading facts back. korely.get(id) shows only the facts true now; get_facts(..., include_invalidated=True) also shows the superseded ones. predicate_raw: the verb as the text wrote it. invalidated_by: the fact that closed this one, often set but not always. predicate_family: one of preferences, people, places, work, ownership, health, financial, events, identity, other; get_facts can filter on it.
• Quota. Korely refuses a write once it would pass the plan's monthly writes plus 10%. A long memory counts up to 3 writes, so it can be refused while one or two writes are still free. Top-ups add writes (see Terms).
• Contradiction candidates. For a memory with a user_id: earlier facts of the same end user in the project, from any agent, that match the new fact in one of these ways:
  1. same subject and relation;
  2. same subject, compatible object, another relation;
  3. the same two entities, reversed;
  4. the same relation, about any subject;
  5. the closest in meaning.
  Since 1.0.12, a fact written by hand (Write a fact) is a candidate in 4 and 5 only when it has the same subject. For a memory with no user_id (an agent's own memory), the candidates are only the facts of the new fact's own entity: facts with the same subject, facts whose object is the new fact's subject, and facts whose subject is the new fact's object. A fact of another entity is not shown to the judge because it is near in meaning. See Temporal facts for the cost of that.
• Memories in error. List them with GET /v1/events?status=error (korely.events(status="error")).

Self-hosted

A Self-hosted server whose setting WRITE_ASYNC is false extracts before it answers and returns the facts in the reply, each with invalidated: the IDs of the earlier facts this write superseded. If the embedding step (see Search) gives no vector, a background worker computes it a moment later.

Related

• Get context: current facts plus relevant memories in one block.
• API reference for every /v1 endpoint.