Get started

Glossary

The words the Korely docs use, each in one or two sentences. Every other page links here instead of repeating them.

Your agent saves text, Korely turns it into short statements, and the agent reads them back when it needs them. The terms below follow that path.

The basics

Cloud and Self-hosted: Cloud is Korely run by us at api.korely.ai, and these docs describe it. Self-hosted is Korely installed on your own computer or server: its code is on GitHub under the Apache License 2.0, and the README there says how to install it.
API key: the secret that identifies your app, written kor_live_.... You send it with every call as an Authorization: Bearer header. Quickstart gets you a free one.
Plan: the tier of your account. The tiers are Hobby (the free one), Developer, Team and Scale. A tier sets how many writes and searches you get each month, and how many agents you can name (see Write and agent_id below). Pricing lists the numbers.
SDK and CLI: two ways to call Korely besides plain HTTP. The SDKs are the korely-memory packages for Python and Node.js. The CLI is the korely command for a terminal. Surfaces compares them with MCP and the REST API.
MCP: a standard that lets an AI assistant call tools. The server at api.korely.ai/agent/mcp gives the assistant six memory tools, and it supports OAuth, the standard sign-in flow that lets an app get access to your account.
Streamable HTTP and stdio: the two ways an MCP client reaches a server. Streamable HTTP reaches a remote server by its URL, like the Korely one. stdio starts a program on your machine and talks to it through its input and output, like korely-mcp. A bridge (or proxy) such as mcp-remote is a local stdio program that forwards to a remote server.
Hook: a small script that the CLI installs in a coding assistant, so that the assistant saves its work sessions to Korely on its own.
Agent: an AI program that works toward a goal and calls tools along the way. Korely is the memory it keeps between conversations.
Tool: a function an agent's model can choose to call, such as searching Korely. When it does, that is a tool call: the model asks, your code or the server runs it, and the result goes back to the model.
Prompt and system prompt: the prompt is the text a model is given to answer. The system prompt is its fixed part, the standing instructions you write once, such as "check memory before you answer".
Model: a large language model, the kind of AI that reads and writes text. Korely uses one to write facts from what you save (see Fact). Reading back does not call a language model (see Search).

Saving

Memory: a piece of text you save by calling add(), up to 16,000 characters. Korely keeps the text as you wrote it.
End user: a person your app serves, identified by the user_id you choose, such as customer-4812. A memory can belong to one end user. Every write names a user_id or an agent_id (why). A read that passes a user_id returns only that end user's data. The number of end users does not change your quota.
agent_id: a name you give one of your own apps or agents, such as support-bot. A read that passes the same agent_id sees only that app's memories; without it, a read covers every agent of the project. Each name counts toward the agent limit of your plan once per project, so the same name in two projects is two agents. A write needs an agent_id or a user_id (why). Since 1.0.12, the model that extracts the facts treats a memory written with an agent_id and no user_id as that agent's own memory, not as a person's; pass the user_id if it is about one person (details).
run_id: a label for one chat session or one run of an agent. Searching and listing memories with the same run_id returns only that session; get_context() and get_facts() have no run_id and cover every session. It is optional.
kind: the sort of memory. note (the default) is something somebody said or decided. session is the log of a work session.
metadata: your own labels on a memory, such as {"source": "slack"}. Korely returns them unchanged, does not use them to write facts, and a search can filter on them. At most 8,192 bytes of JSON.
Write: the unit of the monthly quota. A memory counts one write for every 6,000 characters of its text, rounded up, so the longest memory counts three.
Quota, margin and top-up: your plan sets a monthly quota of writes and of queries. You can go about 10% over it; past that a call gets 429 quota_exceeded. A top-up adds 1,000 writes for the month (paid plans).
Namespace: the set of memories that belongs to one user_id or one agent_id.
Batch and job: a batch saves up to 500 memories in one call and runs as a job in the background. A finished job does not mean the facts are ready: each memory stays processing until its extraction ends.
Version check: expected_updated_at on an update. You send the updated_at you last read; if the memory has changed since, you get 409 stale_write instead of overwriting it.
Extraction: what happens after add() returns. A model reads the text and writes the facts, usually in about ten seconds. A memory in processing can already be found by a search.

Facts and time

Status: where a memory is in its extraction. processing means the facts are still being written, ready means they are done, and error means the model could not be reached or kept timing out. See Extraction.
Fact: a short statement Korely extracts from a memory, in three parts: a subject (who or what), a predicate (the relation) and an object (the other end). Example: Northwind Hosting / costs / 50 euro per month. It also carries tense (current, past or planned: what the statement says about time) and observation_count (how many times it has been said).
Source memory: the memory a fact was written from, shown as source_memory_id. If you delete a memory that was the only source of a fact, the fact closes.
Entity: a person, company or product that a fact names. The entities and the facts that join them form the knowledge graph. An amount or a date is a value, not an entity.
Valid time and known time: a fact has two clocks, called bi-temporal. Valid time is when the fact was true in the world, from valid_from to invalid_at. Known time is when Korely learned it: created_at for the fact, closed_known_at for its end.
Event time: when something happened, as opposed to when you saved it. Pass it as timestamp on add() and it sets valid_from on the facts; left out, it is the time of the write.
as_of: a date you pass when reading facts to see them as they were true on that day, ignoring what changed later. known_as_of does the same for known time: it shows what Korely knew on that day.
Contradiction: a new fact that cannot be true at the same time as an older one, such as a new price for the same item. A model decides, and the older fact is closed. For a fact you write by hand, the model compares it only with earlier facts about the same subject or the same two things (since 1.0.12; details).
Judge: the model that reads a new fact next to earlier facts that could conflict with it and decides which ones it contradicts. Those are closed. See how a new fact closes an old one.
Predicate family: the group a predicate belongs to, such as work or people. You can filter facts by family.
Open fact: a fact that is still true, so it has no invalid_at. It is the opposite of a closed fact.
Closed fact (also superseded fact): a fact that is no longer true, such as an old price. Korely sets its invalid_at and keeps it, so you can still read it. A fact closes when a newer one contradicts it, when its memory is edited to a new value, or when you forget or correct it. invalidated_by is the id of the fact that closed it, empty after a forget. invalidated is different: the ids one call closed, such as a correction.
Declared name (also name alias): a second name you tell Korely belongs to the same entity, such as maria for Maria Rossi, so facts about either are found together. Since 1.0.12 the contradiction check of a fact you write by hand also needs it to treat the two names as one.
Audit log: the record Korely keeps of sensitive actions on your account, such as erasing an end user. A call that does one returns an audit_id, a receipt number. No /v1 route reads the record behind that id, but GET /v1/audit lists the actions (kept 400 days) without the key used.
Pseudonym: after you erase an end user, the audit records keep a stand-in id, erased: followed by 32 characters, in place of the user_id. It is still personal data.
Delete, forget and erase (erasure): three different actions. delete() on a memory forgets it: it no longer appears in any read, but it stays stored, and facts that only it supported are closed, not removed. forget_fact() closes one fact and leaves the memory alone. Erasing removes the data for good: erase=true on a memory (REST API and MCP only) removes its text, vector and own facts, and delete_all() erases a whole end user. Encrypted backups keep a copy for up to 35 days.

Reading

Search: finds the memories closest in meaning to a question, not the ones that share its words. It returns a list of memories, each with a score.
Events: a call (GET /v1/events) that lists your recent writes, newest first, each with its status, and counts how many are still processing. It is the only call that filters by status, for example error.
Hit: one result of a search, a memory with its score and a snippet, a short piece of its text. A list returns the full text.
Embedding (also vector): a list of numbers that stands for the meaning of a text. Similar texts get similar numbers, which is how a search finds the closest (vector search). Korely computes them on its own server.
Score: how close in meaning a memory is to your question, from about 0 to 1. A near-identical sentence scores around 0.9, a related memory with no words in common around 0.3, and an unrelated one 0.1 to 0.25.
Context block: the ready-to-use text that get_context() returns. It holds a short note for your model, the current facts, and as many memories as fit in the size limit you set. You add it to your prompt.
Degraded: a get_context() answer marked degraded: true because the server was too busy to finish the lookup in time. It counts as a read.
Read: any call that looks something up, such as a search, get_context(), get_facts() or a list. Each read counts as one query against the monthly queries of your plan.
Rate limit: a cap on how many requests you can send per minute, per hour and per day. Past it you get a 429 error, usually with a Retry-After header.
Token budget: the size limit of the context block, counted in tokens, the pieces of text a model reads.

Accounts and keys

Project: a workspace of your account. A project holds one set of memories and keys. A key belongs to one project and reads only that project's memories.
Region: each project has a region, eu or global, set in the API as processing_region. It sets which company's model extracts the facts; eu uses a provider in Europe. Your data is always stored in the EU: the region that ping shows (such as eu-hel1) is that server location. Extraction quality can differ between the two. If you change region, up to 10 earlier memories of the end user go to the new provider. See Data and governance.
agent_caller: an optional label for your app, sent when you create a key. It is not the agent_id you set on a memory.
Default project: the project every account starts with. A key created without a project goes into it, so two such keys share the same memories. It cannot be deleted.
Admin key: a key with the admin permission, used by a person to manage projects and keys. Never give it to your agent.
Webhook: a URL of yours (an endpoint) that Korely calls when something happens, such as a fact being closed. You set webhooks up in the dashboard, not through the API.
Confined key: a key limited to some end users. A key confined to customer-4812 reads and writes only that end user, even in a call without user_id.
Permission (also scope): what a key may do, such as memories:read or memories:write. A key without the permission gets a 403 error. The dashboard, the web app where you manage your account, shows each key's permissions, and so does GET /v1/ping, as scopes.

Overview shows how the pieces fit. Quickstart saves your first memory.