Kelmo

Long-term memory for coding agents. Tell it once, and Claude Code and Codex remember.

Kelmo stores your notes and sessions in a local archive. A model you choose files them into a small wiki in Git, and your agent gets the pages that matter when a session starts.

Install

You need macOS or Linux, Python 3.12 or 3.13, Git with an author name and email, and Claude Code or Codex logged in. You can also put your own program, including a local model, behind the executor protocol.

pipx install kelmo        # or: uv tool install kelmo
cd your-repository
kelmo setup --disable-native-memory --project my-app --link "$PWD" --dry-run   # shows the plan, no model calls
kelmo setup --disable-native-memory --project my-app --link "$PWD"

Some Python builds on macOS have no SQLite extension support, which Kelmo needs. If Kelmo reports that, reinstall it with uv tool install --managed-python --python 3.13 kelmo.

Setup finds your clients, suggests a model and asks which login to use. --disable-native-memory tells the agent to use Kelmo instead of the client's built-in memory, so the two do not compete. Changed files get verified backups, and removal starts with a preview. Session capture is off unless you add --session-memory auto.

Prefer to hand it over? Tell your agent: Read https://raw.githubusercontent.com/dazaronak/kelmo/main/INSTALL_FOR_AGENTS.md and install Kelmo for me.

See it work. Tell Kelmo one thing:

kelmo create --project my-app --text 'Exports run nightly at 02:00, not hourly.' --wait
kelmo pages

Restart your agent, open a new session in that repository and ask when exports run. Codex first asks you to trust the new hooks in /hooks. Follow any note with kelmo trace OPERATION_ID.

How it works

• Archive. Every note and transcript you give it, unchanged, searchable by meaning and by words.
• Wiki. Markdown pages in Git: a map for each project plus topic pages. A new note updates the fact it matches instead of adding a duplicate, and each change is one commit.
• Hot context. Your shared pages and the current project's hub reach the agent at session start. Link a repository with kelmo link and its worktrees get the same hub. When something changes, the open session gets it on the next prompt; a hub that was fully delivered and has not changed is not sent again in that session. Claude Code accepts at most 10,000 characters from a hook, so a larger hub arrives as an excerpt with a pointer (details).

Everything runs locally under your account. Apart from the one-time embedding model download, network traffic comes from the model CLI you choose, or from a shared server if you set one up.

The wiki is plain Markdown with wikilinks, so Obsidian can open it. Browse it there and leave the editing to Kelmo: a hand edit holds back publishing until you restore the page.

_{My own wiki in Obsidian's graph view. A real screenshot, not a demo dataset: each dot is a page, each line a link.}

Ask in either language

If your notes mix two languages, asking in both helped every model measured here. The agent's memory_search tool takes the same question in English and in Russian, and Kelmo merges both result lists. Russian is the only second language so far.

The chart shows how often the right note was in the top 5, over 398 questions on one private vault of 9,530 text chunks. "One language" includes asking in one language about a note written in the other: with MiniLM, a question in the note's own language finds it 70% of the time, and a question in the other language 17%. A model wrote the questions after reading the notes, so expect lower numbers on your own.

MiniLM is the default because it is an 87 MB download and needs no GPU. e5-small and bge-m3 run behind an embedding broker. docs/MODELS.md has the full results, memory, speed and setup.

What the background editor buys you

Every note goes through the model you choose, billed to that CLI's subscription or API key. On the author's vault, from November 1 to 8, 2026, the editor processed 390 notes for $61.47 on an API key with Claude Haiku 5.5: a median of 13 cents and two model calls per note. A subscription counts the calls against its limits instead. A lighter vault costs less.

The model reads each note against the facts already stored, so a new note can update the old fact instead of sitting next to it. About half of the notes on that vault (714 of 1,417) changed no page. They stayed in the archive as evidence, which keeps the pages small. Each fact cites the archived note behind its latest version, and Git keeps every earlier version. The vault holds 6,361 archived records and 8,720 facts on 1,249 pages.

Known issues

The editor makes mistakes. An audit of the wiki layer on the author's vault found wrong text in 5 of 347 facts (1.4%) and flagged 36 of 381 as overtaken by a newer note (9.4%).

Each layer is affected differently. The archive keeps every note as written, with its date, so the newer note is still there. Search does not rank newer notes higher, so Kelmo relies on the agent to search the archive and compare dates. Hot context is built from wiki pages and carries the same lag until the wiki catches up.

The fixes are tracked in GitHub issues. They will come with a clean-up command that re-checks an existing wiki against the archive and brings it up to date. Nothing is lost in the meantime, because every note stays in the archive.

How a note becomes a fact

• Only the editor writes the wiki, through a registry of pages and facts. A hand edit to a registered page blocks the next publication until it is restored.
• A model proposes changes. Kelmo checks them against the registry, the page budget and the source before it commits anything.
• A conflict is never overwritten silently. It becomes a resolution job that an agent answers against the archived source.

The registry guarantees that pages match their records. It cannot prove the model understood the note, which is why the editor's output was audited (see Known issues).

Documentation

• Get started: setup and options, everyday commands, CLI reference, removal
• Memory: project hubs, hot context, notes, sessions, Dreaming, conflicts, work state, graph
• Models: embeddings, embedding broker, executors, executor accounts
• Operations: worker, diagnostics, shared server, SSH gate, knowledge sync, MCP reconnect, migration, adoption
• Internals: architecture, wiki file contract, runtime isolation, tests and CI, target state, releasing

License

Apache-2.0. See LICENSE.