Surfaces

All surfaces

Every surface on this page reads and writes the same Korely memory, so you can pick one per job and mix them.

Korely has six surfaces: the REST API, the SDKs, the CLI, the MCP server, the hooks for coding assistants, and the dashboard for people. Each API key belongs to one project, and surfaces that use keys of the same project see the same memories.

This page is for developers choosing how to connect an app or an agent to Korely.

Terms

The Glossary defines the words used across the docs. These are the ones this page relies on.

• Surface: one way to reach Korely, such as the REST API, an SDK, the CLI or the MCP server.
• Hook: a command a coding assistant runs by itself at set moments, such as the start and the end of a session.
• Dashboard: the web app at agent.korely.ai where you manage projects, keys and webhooks.
• Base URL: the address that each call's path is added to.
• known_as_of: a date that makes a read return what Korely knew on that day, before it learned of later changes. as_of instead asks what was true in the world on that day.
• exclude_sessions: set to true, a read leaves out the session logs that coding assistants save (memories of kind session), and the facts that come only from those logs.
• Batch import: one call that saves up to 500 memories.

Quick start

Install the Python SDK with pip install korely-memory (Python 3.9 or later), then get a free API key in the Quickstart and run export KORELY_API_KEY=kor_live_.... The code saves one memory for an end user, waits for extraction, and prints the context block for a question.

import time
from korely_memory import Korely

korely = Korely()  # reads KORELY_API_KEY from the environment
mem = korely.add("Prefers invoices as PDF.", user_id="test-user-1")
while korely.get(mem.id).status == "processing":
    time.sleep(2)  # extraction usually takes about ten seconds
print(korely.get_context("invoice preferences", user_id="test-user-1").context)

Under ## Known facts the block lists the facts, such as a preference for PDF. Under ## Relevant memories it shows the memory. A model writes the facts, so their wording varies.

If the block shows the memory but no facts, print korely.get(mem.id).status. Add a memory explains each status and what to do on error.

Which surface should I use?

• You build a product with memory per customer: the Python or Node.js SDK.
• You use another language, or want plain HTTP: the REST API.
• You script a cron job, a CI step or a shell pipeline: the CLI. It has --json output and needs no code. It comes with the Python package.
• An AI assistant should call Korely as a tool, such as Claude Code or Cursor: the MCP server.
• A coding assistant should save every session without asking: the hooks, set up per assistant in Claude Code, Codex or Cursor.
• A person wants to look at memory, correct a fact or manage keys: the dashboard.

Install and connect

With curl, call https://api.korely.ai/v1/.... The SDKs and the CLI add /v1 themselves: their base URL is https://api.korely.ai. The MCP server is at https://api.korely.ai/agent/mcp.

Create a key on the API Keys page of the dashboard. Every call sends it in one header, Authorization: Bearer kor_live_.... Only POST /v1/agents/init needs no key: your code calls it to create a free account and its key, without the dashboard (how an agent signs up).

pip install korely-memory   # Python 3.9 or later
export KORELY_API_KEY=kor_live_...
python -c "from korely_memory import Korely; print(Korely().ping().tier)"
# hobby

npm install korely-memory   # Node.js 18 or later
# Method names are camelCase (getContext); options stay snake_case ({ user_id })

pip install korely-memory   # the korely command comes with the Python package
korely init --api-key kor_live_...   # saves the key in ~/.korely/config.json
korely auth
# Authenticated  key kor_live_…a1b2  base https://api.korely.ai
# tier hobby  region eu-hel1  processing global  scopes memories:read, memories:write

curl https://api.korely.ai/v1/ping \
  -H "Authorization: Bearer kor_live_..."
# {"ok":true,"tier":"hobby","region":"eu-hel1","processing_region":"global","scopes":["memories:read","memories:write"]}

claude mcp add --transport http korely https://api.korely.ai/agent/mcp \
  --header "Authorization: Bearer kor_live_..."
# then run /mcp inside Claude Code: korely is listed as connected

The fields of the answer:

• tier: your plan.
• region (eu-hel1): where your data is stored, Korely's servers in Helsinki.
• processing_region: eu or global, set per project. New projects start as global.
• processing_region picks the extraction model. With global (the default) it is a model from Google, outside the EU; with eu it is Scaleway in Paris. The two can extract facts differently. Data governance names both.
• scopes: the key's permissions.

A 401 with invalid_key means the key is wrong, revoked or expired.

Run the Node.js examples as an ES module, such as a .mjs file: they use top-level await.

The same flow on three surfaces

A support agent saves what a customer said, recalls it in the next conversation, then erases the customer on request. It uses one agent_id and one end user. Run it with KORELY_API_KEY set. Its last step erases what it saved. The curl version also needs jq, a command-line JSON tool.

import time
from korely_memory import Korely

korely = Korely()

# Conversation 1: store what the customer said.
memory = korely.add(
    "Prefers invoices as PDF, replies fastest before 10am CET",
    user_id="customer-4812",
    agent_id="support-bot",
    metadata={"source": "support-chat"},
)
print(memory.status)  # processing
while korely.get(memory.id).status == "processing":
    time.sleep(2)  # usually about ten seconds

# Conversation 2: build the context block before calling your model.
ctx = korely.get_context(
    "billing preferences",
    user_id="customer-4812",
    agent_id="support-bot",
    token_budget=400,
)
messages = [
    {"role": "system", "content": f"You are a helpful billing assistant.\n\n{ctx.context}"},
    {"role": "user", "content": "Can you send me the invoice?"},
]
# Under "## Known facts" the block lists facts such as
# "The user prefers PDF (since <the day of the write>)".

# The customer asks to be forgotten: erase this end user.
receipt = korely.delete_all(user_id="customer-4812")
print(receipt.memories_deleted, receipt.facts_deleted, receipt.audit_id)
# For example: 1 1 aud_3d0f5e2a... (memories erased, facts erased, receipt id)

import { Korely } from "korely-memory";

const korely = new Korely({ apiKey: process.env.KORELY_API_KEY });

// Conversation 1: store what the customer said.
const memory = await korely.add(
  "Prefers invoices as PDF, replies fastest before 10am CET",
  { user_id: "customer-4812", agent_id: "support-bot", metadata: { source: "support-chat" } },
);
const id = String(memory.id); // the type marks id as optional
while ((await korely.get(id)).status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 2000)); // usually about ten seconds
}

// Conversation 2: build the context block before calling your model.
const ctx = await korely.getContext({
  query: "billing preferences",
  user_id: "customer-4812",
  agent_id: "support-bot",
  token_budget: 400,
});
const messages = [
  { role: "system", content: `You are a helpful billing assistant.\n\n${ctx.context}` },
  { role: "user", content: "Can you send me the invoice?" },
];
// Under "## Known facts" the block lists facts such as
// "The user prefers PDF (since <the day of the write>)".

// The customer asks to be forgotten: erase this end user.
const receipt = await korely.deleteAll({ user_id: "customer-4812" });
console.log(receipt.memories_deleted, receipt.facts_deleted, receipt.audit_id);
// For example: 1 1 aud_3d0f5e2a... (memories erased, facts erased, receipt id)

# Conversation 1: store a memory and keep its id
ID=$(curl -s -X POST https://api.korely.ai/v1/memories \
  -H "Authorization: Bearer $KORELY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Prefers invoices as PDF, replies fastest before 10am CET","user_id":"customer-4812","agent_id":"support-bot"}' | jq -r .id)

# Wait while extraction runs
while [ "$(curl -s https://api.korely.ai/v1/memories/$ID -H "Authorization: Bearer $KORELY_API_KEY" | jq -r .status)" = "processing" ]; do sleep 2; done

# Conversation 2: get the context block
curl -s "https://api.korely.ai/v1/context?query=billing+preferences&user_id=customer-4812&agent_id=support-bot&token_budget=400" \
  -H "Authorization: Bearer $KORELY_API_KEY" | jq -r .context

# Erase this end user
curl -s -X DELETE https://api.korely.ai/v1/users/customer-4812/memories \
  -H "Authorization: Bearer $KORELY_API_KEY" | jq .audit_id

The receipt's audit_id is its id in the audit log.

Reference

What each surface can do

No surface writes answers for you: reads return memories and facts, and your own model writes the reply.

• Forget, erase: forgetting hides a memory from every read and closes the facts only it stated. Erasing removes it for good. Only REST and MCP erase one memory; the MCP tool forgets unless you pass erase=true. See delete, forget and erase.
• Declared names on the CLI: there is no separate command. Run korely init --name "Maria Rossi" --user-id maria, repeating --name for each name.
• Projects and keys: the dashboard manages them with your login. An admin key manages them outside it. Never give an admin key to a tool your agent can call.
• Dashboard: it also shows usage, sells the monthly top-up of writes, and lets you correct or forget a fact.
• When the dashboard cannot reach the server (since 1.0.22). Only a 401, the server saying the session is over, signs you out. Any other failure of the check the dashboard makes when it opens (a 500, a 429, a 503, a service that is restarting) keeps your session: the page says why the session could not be checked, with Try again and Sign out. On the Cloud, an account that no longer exists also ends the session, and the sign-in page says so. A refusal that names a wait (Retry-After) is shown as "Try again after 14:32 (in 12 minutes)" on your clock, and Try again comes back at that moment. A 403 is shown as a refusal, with no Try again, because asking again would not change it. A page that stops while drawing leaves a note in its place and the rest of the dashboard keeps working; the Memory Graph says so when the browser has no WebGL 2.

Coding assistants: hooks and the MCP server

A hook gives a coding assistant the repository's context block when a session starts, and saves the session as a memory of kind session when it ends.

korely init --tool claude-code (or codex, cursor) installs these hooks and korely-mcp, a local MCP server with four tools: korely_get_context, korely_add, korely_search, korely_get_facts. It runs on your machine and calls the Cloud with your key.

For Claude Code, Codex or Cursor, run korely init --tool. For any other agent or MCP client, connect the hosted server at https://api.korely.ai/agent/mcp: it has the six tools of the MCP column.

Other calls

These exist on REST, both SDKs and the CLI; each link opens the call's reference.

• GET /v1/memories, get_all() / getAll(), korely list: list memories.
• PATCH /v1/memories/{id}, update(), korely update: change a memory's text.
• GET /v1/memories/{id}/history, history(), korely history: the history of one memory.
• GET /v1/events, events(), korely events: which writes finished processing.
• POST /v1/facts, add_fact_triple() / addFactTriple(), korely add-fact: write a fact directly.
• GET /v1/profile, get_profile() / getProfile(), korely profile: one end user's facts, grouped by family.
• GET /v1/batch/{id}, batch_status() / batchStatus(), korely batch-status: the status of a batch.
• GET /v1/users, users(), korely users: end users with stored data.
• GET /v1/agents, list_agents() / listAgents(), korely agents: agent names and the agent limit.
• DELETE /v1/agents/{id}, delete_agent() / deleteAgent(), korely delete-agent: erase one agent's data.
• GET /v1/audit, audit() and iter_audit() / iterAudit(), korely audit: the audit log.
• DELETE /v1/account?confirm=true, delete_account() / deleteAccount(), korely delete-account: close an account created with POST /v1/agents/init; an unconfined key of that account with the admin permission (every init key since 1.0.5) closes the whole account.

Python options after the first argument are keyword-only. Node.js takes an options object with snake_case keys, such as deleteAll({ user_id }). The SDK guide and the CLI guide list every signature and flag.

Error codes

Every error answer carries a stable code and a readable message: branch on code, which each SDK exception also carries. StaleWriteError is a kind of ConflictError.

The CLI prints error: <message> [<code>] on stderr and exits with 1, or 2 for a wrong command line. With --json it prints an object with code, message and status. On MCP, the same refusals come back as tool errors.

Limits and pricing

Four plans. The prices in this table are in euro, and Pricing shows them where you are. Quotas reset monthly. End users (user_id values) are unlimited on every plan. Every plan includes facts.

• The quotas count writes (a long memory counts several) and reads. A batch counts the writes of all its memories at once, and is refused with a 429 if they do not fit in what is left of the month.
• The rate limits count every call of the account, from every surface.
• There is no overage billing. Past the quota plus 10%, writes or queries answer 429 until the month rolls over or you upgrade.
• On a paid plan, a top-up adds 1,000 writes to the current month for €10, once a month, from the dashboard.
• At 80% of the monthly write quota, a quota.warning event goes to the webhook endpoints registered on the Webhooks page of the dashboard.

Details

Use them together

For example, an app writes with the SDK, a nightly cron job adds a digest with the CLI, and a coding assistant reads through MCP. With keys of one project and the same user_id, each sees what the others wrote.

What a read costs

Reads do not call a language model. Search and get_context turn the question into an embedding on our own server. Each read still counts as one query of the month and toward the rate limit. The model runs on the write, to extract facts and check contradictions (Architecture). A read without user_id covers every end user of the key's project.

See also

• SDK guide: every method, with examples.
• CLI guide: every command and flag, and coding-assistant setup.
• MCP server: setup and the six tools.
• API reference: every REST call.
• Memory model: how user_id, agent_id and run_id scope memory.