Support

FAQs

The questions developers ask before they wire Korely in.

Words such as memory, fact, end user, write and quota are defined in the Glossary. Where an answer depends on how the service behaves today, it says so; the other pages of these docs give the details.

What is Korely?

A memory service for AI agents. Your agent saves what it learns with add() and reads back a block of text ready for its prompt with get_context(), across sessions, kept apart per end user. You call it from the SDK, the CLI, the REST API or MCP. For now Korely is available as Cloud, run by us on servers in Helsinki.

How do I get started?

Run pip install korely-memory and then korely init --agent: the second command creates a free account and saves its key on your machine. The Quickstart then stores and reads back a first memory, in Python, Node or plain REST. The page Sign up as an agent explains what that command does.

How is it different from a vector database?

A vector database stores embeddings and returns the stored texts closest to your query. Korely stores the memory and reads it into (subject, predicate, object) facts, each with dates. When a new fact conflicts with an older one, Korely tries to close the older one and keeps it in the history, and it links facts about the same person or thing. A read returns the facts that are true now, plus the closest memories. Which older facts get closed is decided by a model, so you can check the result with get_facts.

What is the difference between a memory and a fact?

A memory is the text you store ("Maria moved to the Pro plan"). Facts are the triples Korely reads out of it, like (Maria, plan, Pro), each with a valid_from and an invalid_at, so you can still ask what was true on a given day.

How do I keep one customer's data separate from another's?

Scope every call with user_id (your end user). agent_id names one of your apps and run_id a single session. A key belongs to one project and sees only that project's memories. Inside a project, a read with no user_id covers every end user, so always pass user_id, or give a frontend a key confined to its own end users.

Where is my data stored?

On Korely's servers in Helsinki (Hetzner), on every Cloud plan: memories, facts and their vectors sit in a Postgres database there, and the encrypted backups are kept in the EU too. To write the facts, a model reads the text of each memory, and the project's region decides which: global (the default) uses a model from Google, outside the EU; eu uses Scaleway in Paris. The last answer on this page has the detail, and Data & governance has the detail.

How do reads and writes count against my plan?

Writes count against your monthly writes quota: adding a memory, each memory in a batch, editing a memory, writing or correcting a fact directly, and declaring or removing a name for an end user. A memory counts one write for every 6,000 characters of its text, rounded up; the other writes count one each. Deleting a memory does not count. Reads count against your monthly queries quota: every call that looks something up, such as search, context, facts, get and users, is one query. The queries quota is 100 times the writes quota or more, and a read calls no language model.

Is there a free tier?

Yes, Hobby is free (250 writes and 25,000 queries a month, 2 agents). Developer (19 euro a month + VAT) and Team (79 euro a month + VAT) raise the limits. The number of end users is not limited on any plan. Pricing shows the prices where you are.

What happens when a paid plan ends?

The account moves to Hobby when the subscription ends. Your memories, facts and projects stay, and every API key keeps working, with Hobby's limits from then on. You can subscribe again at any time.

Can a person see and edit what my agent remembered?

Yes, through your product. These are calls of the SDK (and REST): get_profile shows the current facts about one end user, correct_fact replaces one wrong fact with a corrected one, forget_fact closes a fact that is no longer true, and delete_all erases an end user's memories and facts with one call. The dashboard has the same Correct and Forget actions on a fact. See Human in the loop.

Do you train models on my data?

No. Korely does not use your stored memories or facts to train or improve any model. The Terms of Service and the Privacy Policy say so; see Terms of Service and Privacy Policy.

What happens when I hit my quota (429)?

Each plan's monthly figure has a 10% grace (margin) on top. Once a write would take you past the figure plus the grace, the API answers 429, its error body has code set to quota_exceeded, and nothing is written. Reads past the queries quota get the same answer. An example body (the figures depend on your plan, and YYYY-MM-01 stands for the first day of next month):

{
  "detail": {
    "code": "quota_exceeded",
    "message": "Monthly write limit reached: 250 writes on the Hobby plan this month, plus a 10% grace. It starts again on YYYY-MM-01. To go on now, move to a paid plan at https://agent.korely.ai/usage (an account made with korely init signs in there first and adopts its key)",
    "limit": 250,
    "used": 275,
    "resets_at": "YYYY-MM-01T00:00:00Z"
  },
  "code": "quota_exceeded",
  "message": "Monthly write limit reached: ..."
}

Branch on code, never on the message. detail.limit is the plan's monthly figure (top-ups included), detail.used what the month has used, detail.resets_at when the count starts again (00:00 UTC on the 1st). The quota 429 carries no Retry-After header: read detail.resets_at. A write quota never blocks a read: reads have their own, larger queries quota. A batch import refused for the quota is the same 429, with the same detail.limit, detail.used and detail.resets_at; the whole batch is refused and nothing is queued.

A different 429, the rate limit (too many requests in a minute, hour or day), does carry a Retry-After header in whole seconds: wait that long and try again. All Korely errors carry code and message at the top level next to detail.

To go on after a quota 429, on a paid plan you can add 1,000 writes to the month once, from the Usage page of the dashboard; past that, upgrade your plan. Current limits per plan: Hobby 250 writes / 25k queries, Developer 2k / 250k, Team 8k / 1M, Scale 25k / 10M. See Pricing.

What is the agent_id cap and how does its 429 work?

Each plan allows a fixed number of distinct agent_id values, counted across all the projects of your account (Hobby: 2, Developer: 10, Team: 100, Scale: 500). A write that brings a new agent_id past that ceiling returns 429 with code agent_cap_exceeded (detail carries limit and used), and the memory is not written. It carries no Retry-After: waiting does not help. Agents you already use keep working, and a memory with no agent_id does not count. To add a new agent, upgrade or delete an unused agent with DELETE /v1/agents/{id}. There is no cap on the number of end users (user_id) or sessions (run_id) on any plan. This is how the service is built to work; it has not been tried on a live Hobby account.

Can I import a large history in bulk?

Yes, use the batch endpoint. Submit up to 500 memories in a single request; the server imports them in the background and returns a job id (e.g. job_4e1aa0) with its received count. Poll GET /v1/batch/{id} until status is completed or failed; a failed job is tried again from where it stopped until its attempts are used, so it may still become completed. The result reports how many items were imported and how many failed; when failed is above zero, errors says which item failed and why, and you can send those items again. A job that is completed has tried every item, but the facts of each memory are still extracted afterwards, like for any write: watch the memories' status with GET /v1/events. Imported memories get their facts the same way as single writes, including the check against earlier facts.

Both calls need your key in an Authorization: Bearer kor_live_... header and go to https://api.korely.ai:

POST /v1/batch
{
  "memories": [
    { "content": "Alice prefers dark mode", "user_id": "customer-4812" },
    { "content": "Bob is on the Team plan", "user_id": "customer-7203" }
  ]
}

Response (202 Accepted): { "id": "job_4e1aa0", "status": "pending", "received": 2 }

GET /v1/batch/job_4e1aa0
Response: {
  "id": "job_4e1aa0",
  "status": "completed",
  "received": 2,
  "imported": 2,
  "failed": 0,
  "errors": []
}

Batch writes count against the same monthly writes quota as individual add() calls. A batch that needs more writes than the plan has left is refused whole; on Hobby, a batch of 500 memories never fits.

Do reads call a language model?

No generative model runs on a read. What each read does:

• GET /v1/facts and GET /v1/memories/{id}: a database query, no model call at all.
• POST /v1/memories/search: the query becomes a vector on our server, then a vector search in the database. No third party sees the query.
• GET /v1/context (the main way to recall): the facts that are true now plus the same query vector and vector search, assembled into one block.

Adding is different from reading, because it does call a model. POST /v1/memories (add) does more work. The memory is stored and normally given its vector before the 201, so a search finds it right away (if the server is busy, the vector follows a moment later). Its facts are extracted in the background after the 201, usually within about ten seconds, so your agent does not wait for extraction.

Can I install Korely on my own computer?

Not at the moment. For now Korely is available as Cloud: you use it with a key from the dashboard, on one of the plans on the pricing page. On every plan, including Hobby, your memories, facts and their vectors are stored on Korely's servers in Helsinki. To extract facts, the text of each memory you write (and the words of a fact you write or correct directly, for the checks on it) goes to the language model of your project's region: in the default global region it is read by a model from Google (the Gemini API), outside the EU, and in the eu region it goes to gpt-oss-120b on Scaleway, in Paris. Searches and context queries run no language model. See Data & governance and, for the list of companies that process data on our behalf, the sub-processors on the Security page.