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

Every surface points at the same base URL: https://api.korely.ai/v1, EU-hosted. 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) is REST/SDK-only. 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 read quotas are an order of magnitude more generous than write quotas. 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
1.  Pricing review June         score 0.92
2.  Plan change approval        score 0.87
3.  Q2 budget retro             score 0.81

$ 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, every command, --json for scripts, and all 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: graph + typed-fact extraction included in the call
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 AI on the read path

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

Every SDK method and CLI subcommand maps to exactly one endpoint. 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 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.

Every subcommand is documented with all flags and worked examples in the CLI deep dive.

Error codes

Every error response carries the same flat envelope: {"code":"<slug>","message":"<text>"}, never an error or detail field. 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 quota you receive a quota.warning webhook. Past 100%, writes and searches that exceed the soft cap (10% above the tier limit) return 429 until the month rolls over or you upgrade. Your bill is always exactly the tier price.

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_8f2c1a
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."

# ── GDPR: 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_3d0f

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_8f2c1a
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."

// ── GDPR: 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_3d0f

# 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_8f2c1a"

# 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
# "customer-4812 prefers invoices as PDF (from 2026-06-11)\n..."

# GDPR: 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_3d0f"

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, every subcommand with all 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.