CLI

The Korely memory API from a shell. The CLI is what you reach for when you already know what to pull: cron jobs, CI prep, editor commands, shell pipelines, and any workflow where you drive the query yourself instead of waiting for an agent to.

Almost every subcommand maps to one REST endpoint and the matching SDK method, so anything you learn on one surface transfers to the other: memories (add, search, list, get, update, history, delete), facts (read, write, correct, forget), context and profiles, end users and agents, batch import, the audit log, and the account itself. Output is human-readable by default and JSON with --json when you want to script. The same three scoping keys (--user-id, --agent-id, --run-id) mean the same thing here as in the SDK.

Install and authenticate

The CLI ships inside the Python package. One install gives you both the korely_memory import and the korely command. Get a key with one command: korely init --agent mints a free Hobby key and saves it to ~/.korely/config.json, so every command just works. Key precedence is --api-key > KORELY_API_KEY > ~/.korely/config.json, and the API address follows the same order: --base-url > KORELY_BASE_URL > the config file.

# Install: gives you both the Python package and the korely command
$ pip install korely-memory

$ korely --version
korely 0.1.28

# Sign up: mint a free Hobby key, saved to ~/.korely/config.json
$ korely init --agent
You're set: a free hobby key was minted and saved to /Users/you/.korely/config.json (chmod 600).
  key     kor_live_…a1b2
  tier    hobby    region eu-hel1  processing global
  quotas  250 writes / 25000 queries per month · 2 agents
  terms   creating the account accepts the Terms and the Privacy Policy:
          https://korely.ai/legal/terms-of-service
          https://korely.ai/legal/privacy-policy

Next:
  korely add "I am using Korely"
  korely search "am I using Korely"

# Already have a key? Set it in the environment instead
$ export KORELY_API_KEY=kor_live_...
$ korely auth
Authenticated  key kor_live_…a1b2  base https://api.korely.ai
tier hobby  region eu-hel1  processing global  scopes memories:read, memories:write

# Or pass the key inline for one-off commands
$ korely search "any topic" --api-key kor_live_... --limit 3

Command map

Almost every subcommand maps to a REST endpoint and the matching SDK method. Scoping options use --dashes; positional arguments (query text, memory ID) are plain words.

Declare a name

# The end user maria is Maria Rossi in the memories
$ korely init --name "Maria Rossi" --user-id maria
name     "Maria Rossi" is maria: what the memories say about it is theirs, the facts already written included

# The facts about Maria Rossi now come back under maria
$ korely facts --user-id maria --subject maria

# A full name and a short one, declared in one command
$ korely init --name "Tomas Radek" --name Tomas --user-id tomas-r

Your memories may call one person by an id (maria) and by a full name (Maria Rossi). Korely never merges two names of a person by itself, because two people can share a name. --name declares that the name belongs to the end user given by --user-id: from then on the facts about Maria Rossi in that user's memory are facts about maria, the ones already written included. It runs in the project of the saved key. With a key already saved (or in KORELY_API_KEY) it only declares the name; on a machine with no key it gets one first, as korely init does, then declares it. --user-id is required: a name belongs to a person's memory. Declaring the same name again answers the same; a name already declared for somebody else is refused. Since korely-memory 0.1.26. From 0.1.27, --name can be given more than once, for every name the person is called by: each is declared once, in order, and the first refusal stops the rest. The SDK method is declare_name, the endpoint Declare a name.

Connect a coding assistant

# In the repository: hooks and an MCP server for Claude Code
$ cd ~/code/billing-service
$ korely init --tool claude-code
Korely is connected to Claude Code (this repository).
  hooks in /Users/you/code/billing-service/.claude/settings.local.json
  MCP server korely (local scope) added with `claude mcp add`
  .claude/settings.local.json added to .git/info/exclude

  memory   user_id repo:billing-service: every assistant you connect reads and writes it
  start    the assistant is handed what Korely holds for the repository, and on the first prompt what matches it
  saving   every 5 answers, before a compaction and at the end, as one memory; what looks like a key is masked first

Claude Code runs hooks in a folder you trusted. Restart the session to load them.

See what it holds:  korely context "what did we decide" --user-id repo:billing-service

# The same for Cursor or Codex
$ korely init --tool cursor
$ korely init --tool codex

# Every repository, from your user settings, each with its own memory
$ korely init --tool claude-code --global

# Take the hooks and the MCP server out again
$ korely init --tool claude-code --remove

korely init --tool connects Claude Code, Codex or Cursor to one memory per repository: the end user repo:<name>, where <name> is the folder name of the repository's main checkout (the same from a git worktree). Outside a git repository the hooks use the current folder's name as <name>, but the MCP server has no default user_id there, so name one with --user-id. Every assistant you connect reads and writes the same one, so what Claude Code stored on Monday, Codex reads on Tuesday. A user_id does not count against the agent cap. With a key already saved (or in KORELY_API_KEY) it only installs; on a machine with no key it first gets one, as korely init does (or saves the one you pass with --api-key), then installs. --remove needs no key. Since korely-memory 0.1.25; the sessions are saved with kind session since 0.1.26.

What it writes

Each hook runs korely hook <event> --tool <tool> on five moments of a session: the start, a prompt, the end of an answer, before a compaction, and the end. Your other hooks and settings in those files stay as they are; running the command again replaces korely's hooks instead of adding a second set. In the repository the files are personal: korely adds them to .git/info/exclude unless git ignores them already, and refuses to write to a file that is committed to the repository (use --global, or add the hooks by hand). The MCP server is the local korely-mcp with the same four tools as Korely MCP; inside a git repository, a tool call that names no user_id reads and writes repo:<name>. It takes the name korely and replaces a server of that name in the same place. With --no-mcp korely writes the hooks only, and it still removes a server named korely if one is there. To keep a server you configured yourself, give it another name.

• Claude Code runs hooks in a folder you trusted: restart the session to load them.
• Codex runs a new hook once you trust it: open /hooks in Codex and trust the five korely hooks.
• Cursor also runs Claude Code's hook files. korely's Claude Code hooks step aside inside Cursor, so a turn is stored once. Cursor does not wait for its session start hook, so the first answer can come before the context does.

What the hooks send

• At the start of a session the assistant is handed a context block of repo:<name> (up to 1,500 tokens) for the query <name>: decisions, rules, open work and next steps. In Claude Code and Codex the first prompt of a session also gets a block for the prompt itself (up to 1,200 tokens).
• During the session each prompt and each final answer goes to a local buffer in ~/.korely/sessions, readable by you only. A message keeps at most 3,000 characters, its start and its end.
• Every 5 answers, before a compaction and at the end, a process of its own sends the buffered turns as one memory, so the assistant never waits for the network. The memory opens with A coding session in the repository billing-service, with Claude Code, on 2026-10-18., then one Developer: or Assistant: line per message, at most 15,000 characters in all. It goes to user_id repo:<name> with kind: "session", the assistant's session id as run_id, metadata {"source": "claude-code", "repo": "billing-service"} and the time of the first message as timestamp. The X-Korely-Client header names the assistant.
• Before anything leaves the machine, private key blocks (replaced by [redacted private key]), credentials inside URLs and long strings that look randomly generated are masked as [redacted]. It works by shape: a short password typed in a sentence still reads as a word.
• A session that ended without a word (a closed terminal) is sent by the next session start, once nothing has been added to its buffer for two hours.
• A hook never breaks the assistant. A failure is one line in ~/.korely/hook.log, never the text of the session, and the hook exits 0. A send that fails stays in the buffer and is tried again by a later send, such as the next session start, up to 5 attempts in all.

Sessions are kept apart from notes because a session log mixes what was decided with everything else that was said while working. Saved with kind session, it stays in the same memory and still produces facts, and a read with --exclude-sessions (in the SDK, exclude_sessions) leaves the sessions out, together with the facts only they state, so the answer comes from what was said and decided. See Work sessions. A Self-hosted install older than Korely 0.1.42 refuses kind with a 422; the hooks then save the session as a note.

# Save the log of a work session by hand, as a session
korely add "Session: moved the billing service to Postgres 16, tests pass." \
    --user-id repo:billing-service --kind session

# Read without the work sessions and the facts only they state
korely context "how do we bill customers" --user-id repo:billing-service --exclude-sessions
korely search "billing currency" --user-id repo:billing-service --exclude-sessions
korely facts --user-id repo:billing-service --exclude-sessions
korely profile --user-id repo:billing-service --exclude-sessions
korely list --user-id repo:billing-service --exclude-sessions

korely add --kind takes note (the default) or session. --exclude-sessions works on search, context, facts, profile and list; it is off by default, and every read covers everything. Since korely-memory 0.1.27.

Options of korely init --tool

Write a memory and search it

Scope every call with --user-id (your end user, unlimited on every tier) and --agent-id (your application's namespace). Filters are additive: a search scoped to a --user-id never sees another user's memories.

# 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 --agent-id billing-bot
stored  mem_8f3a21c...

# Facts are extracted asynchronously: typed triples land a few seconds later
# Read it back, scoped to the same end user
$ korely search "invoice preferences" --user-id customer-4812
[0.930] Prefers invoices as PDF, replies fastest before 10am CET
        mem_8f3a21c...
[0.810] Asked for a consolidated monthly invoice, finance@ in CC
        mem_3b1d90a...

Query facts

korely facts returns typed (subject, predicate, object) triples with bi-temporal validity as a flat list. A facts read is deterministic and makes no model call. Works on every tier, including the free Hobby plan. For the same facts grouped by predicate family, use korely profile. Every fact line starts with the fact's id (fct_ and 32 hexadecimal characters), the id that korely forget-fact and korely correct-fact take. Since korely-memory 0.1.28; --json is unchanged.

# Current state only: invalidated facts are excluded by default
$ korely facts --user-id customer-4812
  fct_2a05d671a61124357f1c629adf5b0da5  customer-4812 · replies_fastest_before · 10am CET [from 2026-06-11]
  fct_9f27707355092477fc6006e6c00ce2c9  customer-4812 · prefers_format · PDF [from 2026-06-11]

# JSON for scripts: pipe straight into jq (facts are under .facts)
$ korely facts --user-id customer-4812 --json \
    | jq -r '.facts[] | "\(.predicate): \(.object)"'
replies_fastest_before: 10am CET
prefers_format: PDF

Add --include-invalidated to see the full history, with superseded facts included. --as-of DATE shows what was true on a date, and --known-as-of DATE what Korely knew on it:

korely facts --user-id customer-4812 --known-as-of 2026-09-20
korely context "where does the customer live" --user-id customer-4812 --known-as-of 2026-09-20

How invalidation works, why the stale fact never reaches your agent by default, and how the two dates differ are covered in Temporal facts.

Search, retrieve, pipe

The pattern for "answer a question from memory" from a shell: assemble a compact, prompt-ready block with context, the recall path that stitches together your end user's active typed facts, then hand it to whatever model you already run, local or hosted. Reach for raw search when you want the underlying memories instead of the assembled view. Either way you pull exactly what you need instead of letting an agent explore, and with --token-budget (default 800, from 50 to 8000) you choose how much memory goes into your model's context.

$ korely search "EU pricing decision" --user-id alice --limit 3
[0.920] Approved the move to the 50 euro per month plan, effective July.
Marco signs off on the renewal quote; finance updates the forecast...
        mem_9f2c1a6b3e0d4c7a8f1e2d3c4b5a6978
[0.870] Plan change approval signed by finance.
        mem_3b1d9...
[0.810] Q2 budget retro: EU contracts renewed.
        mem_7a4c2...

$ korely get mem_9f2c1a6b3e0d4c7a8f1e2d3c4b5a6978
mem_9f2c1a6b3e0d4c7a8f1e2d3c4b5a6978  (2026-06-11T09:12:44)
Approved the move to the 50 euro per month plan, effective July.
Marco signs off on the renewal quote; finance updates the forecast...

# Hand a compact context block to a local model
$ korely context "EU pricing decision" --user-id alice | ollama run llama3.1 "summarize the decision"
The team approved moving to the 50 euro per month plan, effective
July, with Marco signing off on the renewal quote.

Scoping and output flags

A worked example for scripts: a cron job that dumps open action items every Monday, ready for any pipeline.

# crontab: every Monday at 07:00
0 7 * * 1  korely search "open action items" --user-id team --json > /var/data/weekly.json

End-to-end: onboard, enrich, and query a customer

This example walks the full lifecycle of one end user from a shell: write memories during onboarding, extract and inspect the typed facts, search by topic, assemble a prompt-ready context block, and erase everything on request. Each step is a single command.

# ── 1. Authenticate ───────────────────────────────────────────────
$ export KORELY_API_KEY=kor_live_...
$ korely auth
Authenticated  key kor_live_…a1b2  base https://api.korely.ai
tier hobby  region eu-hel1  processing global  scopes memories:read, memories:write

# ── 2. Store onboarding context ───────────────────────────────────
$ korely add "Works at Northwind Hosting as head of infrastructure." \
    --user-id customer-4812 --agent-id support-bot
stored  mem_065290ddd6184f3c849d2661b904ab42

$ korely add "Northwind Hosting costs 50 euro per month." \
    --user-id customer-4812 --agent-id support-bot
stored  mem_5ed6d938b8d5440a8926a073ce101273

# ── 3. Write a contradicting fact ─────────────────────────────────
#    Facts extract asynchronously, a few seconds after each write;
#    the old price is superseded once the new one lands.
$ korely add "Northwind Hosting now costs 75 euro per month after the upgrade." \
    --user-id customer-4812 --agent-id support-bot
stored  mem_7101bf8975bd43e9ba537d65e847eead

# ── 4. Inspect current typed facts ────────────────────────────────
$ korely facts --user-id customer-4812 --subject customer-4812
  fct_7740ddcf6b5697a82dfcd4f29954e67b  customer-4812 · role · head of infrastructure [from 2026-06-11]
  fct_4ea127aed85ec58ffdc9fe84ed78c9f8  customer-4812 · works_at · Northwind Hosting [from 2026-06-11]

$ korely facts --user-id customer-4812 --entity "Northwind Hosting"
  fct_40da93ff067189b01f77e8b412ba2d28  Northwind Hosting · costs · 75 euro per month [from 2026-06-11]
  fct_4ea127aed85ec58ffdc9fe84ed78c9f8  customer-4812 · works_at · Northwind Hosting [from 2026-06-11]

# ── 5. History: the old price is closed, not deleted ──────────────
$ korely facts --user-id customer-4812 \
    --entity "Northwind Hosting" --include-invalidated
  fct_40da93ff067189b01f77e8b412ba2d28  Northwind Hosting · costs · 75 euro per month [from 2026-06-11]
  fct_feaf2e51f84c601de45b54ad3f37a3fb  Northwind Hosting · costs · 50 euro per month [from 2026-06-11] (superseded 2026-06-11)
  fct_4ea127aed85ec58ffdc9fe84ed78c9f8  customer-4812 · works_at · Northwind Hosting [from 2026-06-11]

# ── 6. Semantic vector search ─────────────────────────────────────
$ korely search "plan pricing" --user-id customer-4812 --limit 3
[0.654] Northwind Hosting costs 50 euro per month.
        mem_5ed6d938b8d5440a8926a073ce101273
[0.638] Northwind Hosting now costs 75 euro per month after the upgrade.
        mem_7101bf8975bd43e9ba537d65e847eead
[0.540] Works at Northwind Hosting as head of infrastructure.
        mem_065290ddd6184f3c849d2661b904ab42

# ── 7. One-call context block, ready to paste into a system prompt
#    (the notes for the reader model are shortened here)
$ korely context "billing question" --user-id customer-4812
_The facts below are a compact profile of the user; the memories are the verbatim source of truth. Ground your answer in this context. [...] do not abstain when it is present._

## Known facts
- Northwind Hosting costs 75 euro per month (since 2026-06-11)
- The user works_at Northwind Hosting (since 2026-06-11)
- The user has_job_title head of infrastructure (since 2026-06-11)

## Relevant memories
_A time in square brackets after a relative expression [...] was already resolved from the day that memory was written [...]. The date at the start of a memory [...] is the day it was said._
- [2026-06-11] Northwind Hosting now costs 75 euro per month after the upgrade.
- [2026-06-11] (true when said, changed later) Northwind Hosting costs 50 euro per month.
- [2026-06-11] Works at Northwind Hosting as head of infrastructure.

(279 tokens, 6 source(s))

# ── 8. Erase one end user in full ─────────────────────────────────
$ korely delete-all --user-id customer-4812 --yes
forgot user customer-4812  (3 memory(ies), 4 fact(s) erased, audit aud_44c8beba9c234f3cb577e10fdd740f00)

A fact starts at the moment of the write, unless the text says when it became true and writes the year: "costs 50 euro per month since March 2026" dates the fact from March 2026, while "upgraded on June 15" (no year) or "last week" does not. None of the memories above carries a date, so every fact reads the day of the write, and step 5 shows the history with --include-invalidated rather than an --as-of date between the two prices. To date facts yourself, for example when importing history, pass the timestamp field of Add a memory (or of a batch item) through the API or the SDK, or --timestamp on korely add.

Error reference

The CLI exits non-zero and prints a one-line error on stderr. Pass --json to get a machine-readable object with a code field for scripts.

Related

• Surfaces overview: when to reach for the CLI versus the SDK versus the REST API directly.
• SDK: the same operations from Python or Node, with typed return values and structured exceptions.
• API reference: the REST contract the CLI calls under the hood, with full request and response shapes.
• Temporal facts: the bi-temporal model behind korely facts and --as-of.
• Cookbook: chatbot that remembers: a working loop using context and add.
• Architecture: why every plan includes at least a hundred times more queries than writes.