Surfaces

Korely has one memory and three ways to reach it. Every surface shares the same account, the same scoping model (user_id / agent_id / run_id), and the same permission model. You don't have to pick one, and nothing you write through one surface is invisible to another.

The three agent surfaces are: the REST API at https://api.korely.ai/v1 (the foundation everything else builds on), the SDK (korely-memory for Python and Node, wraps the REST API), and the CLI (ships inside the Python package, pipeable into any shell).

Install / connect

The REST API lives under https://api.korely.ai/v1, EU-hosted. The CLI and the SDKs take the base URL https://api.korely.ai (without /v1) and add the paths themselves. Auth is a single header on every request: Authorization: Bearer kor_live_.... Get a key from the dashboard after signup.

pip install korely-memory
# Python 3.9+; no heavy deps, embeddings and extraction run server-side

npm install korely-memory
# Node 18+; same package name, same method names (camelCase)

pip install korely-memory
# The korely command ships inside the Python package
korely auth   # verifies the key, prints base URL, tier, region and scopes

# No install, just curl or any HTTP client
# Every endpoint except POST /v1/agents/init requires the auth header
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"]}

Capability matrix

1. Typed facts, the bi-temporal core, are available on every tier, including the free Hobby tier. Reading facts costs only a query against your quota.
2. The CLI exposes korely add for writing a new memory and korely delete / korely delete-all for removal.
3. Bulk import (POST /v1/batch, up to 500 memories) works on every surface: korely batch <file> on the CLI, batch() in the SDK. Point-in-time fact queries (as_of) work on every surface, including the CLI (korely facts --as-of). See the API reference.
4. No surface generates answers, by design. Reads are retrieval, not generation: no model composes output on the read path, so your agent's own model does the reasoning and every plan includes at least a hundred times more queries than writes. Full detail in Architecture.

Python and Node.js are available now.

CLI

The scripting surface. Search, read, add, and delete memories from any terminal, pipeable into anything. Reach for it when you already know what to pull: cron jobs, CI prep, editor commands, shell pipelines.

$ korely search "pricing decisions" --limit 3
[0.920] Pricing review June
        mem_...
[0.870] Plan change approval
        mem_...
[0.810] Q2 budget retro
        mem_...

$ korely search "open action items" --json > weekly.json
$ jq '.results[0].snippet' weekly.json
"Open actions, week 24"

# Pipe results into any local model
$ korely search "customer feedback" | ollama run llama3.1 "summarize"

Read the CLI deep dive → Install, the everyday commands, --json for scripts, and their flags.

SDK / REST

The product surface. Per-customer memory inside your own application: developer API keys, user_id scoping for your end users (unlimited on every tier), agent_id namespaces for your app, run_id for sessions. One call to write, one call to read.

from korely_memory import Korely

korely = Korely(api_key="kor_live_...")  # EU-hosted, Helsinki

# Write: the call stores the memory; typed-fact extraction runs right after it
korely.add(
    "Prefers invoices as PDF, replies fastest before 10am CET",
    user_id="customer-4812",  # your end user, unlimited on every tier
    agent_id="billing-bot",    # your app's namespace
)

# Recall: fact-assembled context block, prompt-ready (the moat)
ctx = korely.get_context(query="invoice preferences", user_id="customer-4812")
print(ctx.context)  # active typed facts + relevant memories; no generative model on the read path (one query embedding)

Read the SDK deep dive → Client setup, scoping, facts, and the full REST API reference behind it.

Which surface should I use?

• You are scripting or automating (cron, CI, shell pipelines, editor commands): use the CLI. Composable, --json output, no SDK dependency in the pipeline.
• You are building a product with memory per customer: use the SDK. API keys, user_id scoping, quotas.
• You want direct HTTP control (any language, any runtime): call the REST API directly. Same auth header, same scoping model.

Use them together

The surfaces aren't competing options. They are entry points into the same account. A setup we run ourselves: the SDK embedded in a product so each customer gets their own memory under their own user_id, the CLI in a nightly cron that adds a digest memory, and the REST API hit directly from a webhook handler. Three surfaces, one memory store. The memory the cron job writes at 2am is in the agent's search results at 9am.

REST endpoints

Almost every SDK method and CLI subcommand maps to one endpoint. The exceptions are korely init --tool, which installs a coding assistant's hooks and MCP server, and korely hook, which those hooks run. The base URL is https://api.korely.ai/v1. Auth is Authorization: Bearer kor_live_... on every endpoint except POST /agents/init, which mints your first key. Memories, facts, users, agents, events, batches and the audit log are scoped to the key's project. Success is 200, except where the table says 201 or 202.

SDK method reference

Python uses snake_case; Node.js uses camelCase for the same methods. The table below uses the Python name; the Node.js equivalent is in parentheses where it differs.

Python also has AsyncKorely, with every method as a coroutine.

Every method is documented with examples in the SDK deep dive. The REST shapes are in the API reference.

CLI command reference

The korely command ships inside the Python package. All subcommands except init and hook (the command the assistant hooks run) accept --user-id, --agent-id, and --json. The facts subcommand has additional filter flags. The table shows the everyday commands; the CLI also has ping, list, update, history, events, agents, delete-agent, add-fact, correct-fact, forget-fact, batch, batch-status, audit (--all to export) and delete-account.

The everyday subcommands are documented with their flags and worked examples in the CLI deep dive; korely <command> --help lists every flag.

Error codes

Every error response carries a stable code and a human message at the top level, plus detail (kept for older clients): branch on code. The SDK raises a typed exception per status (with APIError as the base for anything else), and every exception carries the code: branch on it. The CLI exits non-zero and prints error: <message> [<code>] on stderr, or the error JSON with --json.

There is no overage billing. At 80% of the monthly write quota you receive a quota.warning webhook. Past the soft cap (10% above the tier limit), writes or queries return 429 until the month rolls over or you upgrade; on a paid plan, a top-up of writes for the month, bought from the dashboard, also lifts the write limit. Your bill is the tier price plus VAT, plus any top-up you choose to buy.

End-to-end example

A customer support agent that remembers preferences from one conversation and recalls them in the next. One agent namespace, one end user, three calls total.

from korely_memory import Korely

korely = Korely(api_key="kor_live_...", region="eu")

# ── Conversation 1: store what the customer told us ──────────────────────────
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.id)      # mem_8f2c1a6b3e0d4c7a8f1e2d3c4b5a6978
print(memory.status)  # processing: the facts land a few seconds later

# ── Conversation 2 (next day): assemble context before the model call ────────
ctx = korely.get_context(
    query="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?"},
]
# → model sees, under "## Known facts":
#   - The user prefers_format PDF (since 2026-06-11)
#   - The user replies_fastest_before 10am CET (since 2026-06-11)
# → model replies: "I'll send the invoice to you as a PDF right away."

# ── The customer asks to be forgotten ───────────────────────────────────────
receipt = korely.delete_all(user_id="customer-4812")
print(receipt.memories_deleted)    # 1
print(receipt.facts_deleted)       # 2
print(receipt.audit_id)            # aud_3d0f5e2a9c1b4d7e8f6a0b2c4d6e8f1a

import { Korely } from "korely-memory";

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

// ── Conversation 1: store what the customer told us ──────────────────────────
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" },
  },
);
console.log(memory.id);           // mem_8f2c1a6b3e0d4c7a8f1e2d3c4b5a6978
console.log(memory.status);       // processing: the facts land a few seconds later

// ── Conversation 2 (next day): assemble context before the model call ────────
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?" },
];
// → model sees, under "## Known facts":
//   - The user prefers_format PDF (since 2026-06-11)
//   - The user replies_fastest_before 10am CET (since 2026-06-11)
// → model replies: "I'll send the invoice to you as a PDF right away."

// ── The customer asks to be forgotten ───────────────────────────────────────
const receipt = await korely.deleteAll({ user_id: "customer-4812" });
console.log(receipt.memories_deleted);   // 1
console.log(receipt.facts_deleted);      // 2
console.log(receipt.audit_id);           // aud_3d0f5e2a9c1b4d7e8f6a0b2c4d6e8f1a

# Conversation 1: store a memory
curl -s -X POST https://api.korely.ai/v1/memories \
  -H "Authorization: Bearer kor_live_..." \
  -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 .id
# "mem_8f2c1a6b3e0d4c7a8f1e2d3c4b5a6978"

# Conversation 2: get a prompt-ready 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 kor_live_..." | jq .context
# "_The facts below are a compact profile of the user; ..._\n\n## Known facts\n- The user prefers_format PDF (since 2026-06-11)\n..."

# Forget everything for this customer
curl -s -X DELETE "https://api.korely.ai/v1/users/customer-4812/memories" \
  -H "Authorization: Bearer kor_live_..." | jq .audit_id
# "aud_3d0f5e2a9c1b4d7e8f6a0b2c4d6e8f1a"

Pricing

Four tiers. 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 tier.

No overage billing. A soft +10% grace period applies past the monthly quota limit; requests that exceed that cap return 429. Typed facts (get_facts, add_fact_triple, as_of queries), the bi-temporal core, are available on every tier, including the free Hobby tier. Reading them costs only a query against your quota.

Related

• SDK deep dive, every method with full signatures, scoping rules, error handling, and worked examples.
• CLI deep dive, the everyday subcommands with their flags, JSON output, and shell pipeline patterns.
• API reference, the full REST contract, request and response shapes, endpoint by endpoint.
• Memory model, how user_id, agent_id, and run_id scoping works across all surfaces.
• Temporal facts, the bi-temporal model behind get_facts and as_of.
• Architecture, why writes cost and reads are nearly free.