CLI

The korely command calls Korely from a terminal: it writes memories, reads back facts and context, and prints JSON for scripts. Use it for cron jobs, CI, shell pipelines, and to give a coding assistant (Claude Code, Codex, Cursor) a memory per repository.

Quick start

You need Python 3.9 or later. The commands install the CLI, get a free API key, write one memory for the end user customer-4812, wait for its facts, and read them back. [...] marks output shortened here.

Install in a virtual environment (python3 -m venv .venv, then . .venv/bin/activate), and use pip3 if pip is not found. If the shell then says korely: command not found, pip's scripts folder is not on your PATH: python3 -m korely_memory.cli runs the same command.

# Install: the Python package and the korely command
$ pip install korely-memory
$ korely --version
korely 0.1.28

# Get 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
[...]

# Write a memory
$ korely add "Works at Northwind Hosting as head of infrastructure." --user-id customer-4812
stored  mem_28eadb4afde24510883fd80c1d0d8239

# The facts are extracted in the background, usually in about ten seconds
$ sleep 20
$ korely facts --user-id customer-4812
  fct_11c88fe424484bf08132ca2a157630c1  customer-4812 · has_role · head of infrastructure [from 2026-06-11]
  fct_2f8790414249498e93d7097c2ff7f59f  customer-4812 · works_at · Northwind Hosting [from 2026-06-11]

# A block of text ready for your model's prompt
$ korely context "where does the customer work" --user-id customer-4812
_The facts below are a compact profile of the user; [...]_

## Known facts
- The user has_role head of infrastructure (since 2026-06-11)
- The user works_at Northwind Hosting (since 2026-06-11)

## Relevant memories
_[...]_
- [2026-06-11] Works at Northwind Hosting as head of infrastructure.

What you see. stored mem_... means the memory is saved; its facts come later. korely facts prints one line per fact, starting with its id. korely context prints a context block to paste into a prompt, and a count line on stderr. Ids, dates and wording differ in your run: the model writes predicates in its own words (role for has_role).

If you do not see it.

• no facts.: run korely events --user-id customer-4812. If it prints 1 write(s) still processing, wait ten seconds and try again. If it prints 0, the memory finished with no facts; korely search still finds it.
• error: no API key: run korely init --agent, or set KORELY_API_KEY.
• [invalid_key]: the key is wrong or revoked. Check KORELY_API_KEY and ~/.korely/config.json.

Already have a key? Set it, or save it, then check it:

export KORELY_API_KEY=kor_live_...     # for this shell
korely init --api-key kor_live_...    # or save it to ~/.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

init --api-key saves the key without checking that it works: run korely auth to check. In the output, region eu-hel1 is where your data is stored (Korely's servers in Helsinki). processing global is the project's region, global or eu: it picks which model reads your text to write the facts (Google for global, outside the EU; Scaleway in Paris for eu).

Terms

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

• Config file: ~/.korely/config.json, where korely init saves the key (in plain text, readable by you only) and the API address.
• Profile: a second key saved under a name, with korely init --api-key ... --profile work; any command takes --profile work.
• Exit code: the number a command returns to the shell: 0, 1 or 2 (Exit codes).
• Hook: a command a coding assistant runs at fixed moments of a session.
• Compaction: when a coding assistant shortens a long conversation to fit its limit.
• Session buffer: the files in ~/.korely/sessions where hooks keep a session's messages until they send them.
• repo:<name>: the user_id of one repository's memory; <name> is its folder name.

Reference

Commands

Most commands call one endpoint, like the matching SDK method. Options use dashes (--user-id); the text and the ids are plain arguments. The everyday commands come first.

korely init does four jobs, picked by its flags: with no flag it creates a free account; --api-key saves a key you have; --name declares a name; --tool connects a coding assistant.

Flags

Every flag goes after the command (korely search "x" --limit 3).

Environment variables

The order is flag, variable, config file. With --profile the variables do not override the profile. For init the address is --base-url, KORELY_BASE_URL, then https://api.korely.ai.

Exit codes

korely hook always exits 0, except on wrong arguments (2). The CLI never retries a call by itself.

Errors

An error is one line on stderr, ending with the code in brackets, such as [invalid_key].

Details

Declare a name

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

Korely never merges two names of a person by itself, because two people can share a name. --name makes a name a declared name of the end user in --user-id (required): the facts about Maria Rossi, already written ones included, read as facts about maria. It runs in the project of the key in use; with no key, it first creates an account.

• The same name again answers the same. Names are declared in order; the first refusal stops the rest.
• Refused: a name declared for somebody else (409 conflict), a name equal to the user_id (422), a name past the account's limit (409 too_many_names).
• Each declared name counts as one write. The CLI cannot undo it.

SDK: declare_name. Endpoint: Declare a name.

Projects and keys (admin key)

korely projects and korely keys need an admin key. Use it by hand in a terminal, never in a tool your agent can call. Projects and keys are managed from the dashboard or with an admin key.

korely projects list [--archived]
korely projects create NAME [--region eu|global] [--description TEXT]
korely projects rename PROJECT NEW_NAME
korely projects archive PROJECT
korely projects unarchive PROJECT
korely projects delete PROJECT [--erase] [--yes]

korely keys list
korely keys create --name NAME [--project PROJECT] [--scopes read,write] [--users a,b*] [--expires DAYS|never] [--save-as PROFILE]
korely keys move KEY_ID --project PROJECT
korely keys revoke KEY_ID [--yes]

• A project is given by its id or its name.
• projects delete moves the project's keys, memories and facts to the Default project. With --erase it erases the memories and facts instead. Both need --yes.
• --scopes takes read, write and admin, comma separated (the permissions); read,write is the default. --users confines the key to some end users (confined key); a trailing * is a prefix.
• keys create prints the key once. --save-as writes it to a profile instead, so it stays off the screen. keys revoke needs --yes and takes effect at once.
• --json prints the raw answer. list prints one line per project or key.

Connect a coding assistant

korely init --tool gives Claude Code, Codex or Cursor one memory per repository, repo:<name>: hooks hand it to the assistant when a session starts and save the session into it, and a local MCP server reads and writes it. Every assistant you connect shares it: what Claude Code stored on Monday, Codex reads on Tuesday.

$ 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

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

• The name. <name> is the folder name of the main checkout, the same from a git worktree. Two folders named app share repo:app, and a renamed folder gets a new memory. Outside git the MCP server has no default. In these cases pass --user-id. A user_id does not count toward the agent limit.
• The key. With a key saved or in KORELY_API_KEY, it only installs; with none it first gets one (or saves --api-key). --remove needs no key. The hooks find the key when they run, and an editor started from the Dock may not see your shell's variables: save the key in the config file.

• Files. Your other hooks and settings stay; running again replaces korely's hooks. In a repository korely adds its files to .git/info/exclude (unless git ignores them) and refuses a committed file: use --global, or add the hooks by hand.
• MCP server. The local korely-mcp has four of the six tools of Korely MCP: korely_add, korely_get_context, korely_get_facts, korely_search (no korely_correct_fact or korely_forget_memory). In a git repository a call with no user_id uses repo:<name>. It is named korely and replaces a server of that name, even with --no-mcp (hooks only): give your own server another name.
• Claude Code: restart the session (hooks run in a folder you trusted). Codex: open /hooks and trust the five korely hooks. Cursor also runs Claude Code's hook files, but korely saves each turn once: you do nothing. Cursor does not wait for the session start hook, so its first answer can arrive before the memory does.

What the hooks send

The five hooks run at the session start, at each prompt, at the end of each answer, before a compaction, and at the session end.

• Session start: a context block of repo:<name> (up to 1,500 tokens) for <name>: decisions, rules, open work and next steps. Claude Code and Codex also run it when a session is resumed, cleared or compacted, and give the first prompt a block of its own (up to 1,200 tokens). Each block counts as one query of the month.
• During the session: each prompt and final answer goes to the session buffer, readable by you only, at most 3,000 characters per message (its start and end).
• Every 5 answers, before a compaction and at the end: a separate process sends the turns as one memory, so the assistant never waits. It opens with A coding session in the repository billing-service, with Claude Code, on 2026-10-18., then Developer: and Assistant: lines, at most 15,000 characters. It has kind session, the session id as run_id, metadata {"source": "claude-code", "repo": "billing-service"} and its first message's time as timestamp. A long session makes several memories, each up to 3 writes.
• Masking, before anything leaves the machine: private key blocks become [redacted private key]; credentials in URLs and long strings mixing upper case, lower case and digits become [redacted]. It works by shape: a hexadecimal token (lower case and digits only) and a short password in a sentence stay as plain text.
• A session closed without a word is sent by the next session start, once idle for two hours.
• A hook never breaks the assistant: a failure is one line in ~/.korely/hook.log, never the text, and exit 0. A failed send is tried again later; after 5 attempts in all the session is dropped, with a line in the log. A missing key, a 401 or a used-up quota lead there too.

Options of korely init --tool

--also-read-user adds one more end user of the same project; --also-read adds the whole project of a key saved under another profile.

Work sessions in reads

Saved with kind session, it stays in the same memory and still produces facts. --exclude-sessions leaves the sessions out, with the facts only they state. See Work sessions.

korely add "Session: moved the billing service to Postgres 16, tests pass." \
    --user-id repo:billing-service --kind session
korely context "how do we bill customers" --user-id repo:billing-service --exclude-sessions

A Self-hosted service older than version 0.1.42 (the service version, not the CLI version) refuses kind with a 422; the hooks then save the session as a note.

Facts over time

A fact starts at the moment of the write, unless the text says when it became true: a date written with its year, as in "costs 50 euro per month since March 2026", dates the fact from March 2026. For old data, pass --timestamp to korely add. A closed fact line ends with (superseded DATE); a fact with an end date ahead ends with (until DATE).

--as-of ignores --include-invalidated. How the two dates differ: Temporal facts.

Scripts and pipes

# JSON for jq: facts are under .facts, search hits under .results
korely facts --user-id customer-4812 --json | jq -r '.facts[] | "\(.predicate): \(.object)"'

# A context block into a local model (the count line goes to stderr, not into the pipe)
korely context "billing question" --user-id customer-4812 | ollama run llama3.1 "summarize"

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

• With --json, an exit 1 error is an object on stderr: {"code": ..., "message": ..., "status": ...}. It has no limit, used or retry fields. Exit 2 errors stay plain text.
• korely init --json prints the whole key, unmasked.
• In cron, give the full path of korely and a key (file or environment). A failed call leaves the file empty and exits 1.
• The CLI has no flag for metadata; use the SDK.

End-to-end example

The example continues the Quick start: a price, a new price, the history, then the erasure. The outputs come from one run and are illustrative: predicates and scores change from run to run.

$ korely add "Northwind Hosting costs 50 euro per month." --user-id customer-4812
stored  mem_afc0af1b012f462cb5b485310edbe230
$ sleep 30   # let the first price be read before the second arrives
$ korely add "Northwind Hosting now costs 75 euro per month after the upgrade." --user-id customer-4812
stored  mem_a6430928515f4724a634e6bca4841e1e
$ sleep 30

# The old price is closed, not deleted
$ korely facts --user-id customer-4812 --include-invalidated
  fct_fbfe23d1effd40f38b35fc352e860a49  Northwind Hosting · costs · 75 euro per month [from 2026-06-11]
  fct_eca9f2a46b1c4bbdbf39c2205f899da5  Northwind Hosting · costs · 50 euro per month [from 2026-06-11] (superseded 2026-06-11)
  fct_11c88fe424484bf08132ca2a157630c1  customer-4812 · has_role · head of infrastructure [from 2026-06-11]
  fct_2f8790414249498e93d7097c2ff7f59f  customer-4812 · works_at · Northwind Hosting [from 2026-06-11]

# Erase the end user
$ korely delete-all --user-id customer-4812 --yes
forgot user customer-4812  (3 memory(ies), 4 fact(s) erased, audit aud_44c8beba9c234f3cb577e10fdd740f00)

The new price is said in the present tense ("now costs 75 euro"), and Korely closes the old one. A change told in the past tense is not always read as a change: check with --include-invalidated.

Reads make no model call

Lookups read the database directly; search and context turn the question into an embedding on our own server. No generative model writes on the read path, which is why every plan includes at least a hundred times more queries than writes. See Architecture.

Quotas and prices

What counts as writes: each memory and each update, by length (a 15,000 character session counts 3); each add-fact and correct-fact; each declared name. Each read, including each hook block at a session start, counts as one query.

Versions

korely-memory 0.1.28. Since: --known-as-of 0.1.22, --processing-region 0.1.24, init --tool 0.1.25, init --name and session memories 0.1.26, --kind, --exclude-sessions and repeated --name 0.1.27, fact ids in facts 0.1.28.

Related

• Surfaces overview: when to reach for the CLI, the SDK or the REST API.
• SDK: the same operations from Python or Node, with typed return values.
• API reference: the REST contract the CLI calls.
• Temporal facts: the model behind korely facts and --as-of.
• Cookbook: chatbot that remembers: a working loop with context and add.