Kanerva

Coding agents start every session from zero. You explain the test command again, the deploy steps again, the bug you already fixed last week. Memory tools help, but most of them paste the top few similar notes into your context, whatever those notes cost and whether or not they are still true.

Kanerva gives your agent long-term memory that runs on your machine, makes no LLM calls, and injects only what the current step needs, under a hard token budget.

• Small context. You set the budget in tokens, and Kanerva picks the set of notes worth the most per token. Plugins estimate tokens instead of counting them exactly, so treat the limit as close, not exact.

• Facts stay current. Give a fact a key, or write a near-identical note, and the new version replaces the old one. Without a key, memory_remember shows your agent the similar notes, and it can retire one with memory_forget and replaced_by. Old versions stay in history, and every note shows its date, newest first.

• Quiet when it has nothing. A gate skips prompts the store looks unable to answer, so unrelated work gets no notes.

• Notes about the file at hand. When a session first opens a file, the notes that name it come along.

• Private by default. One SQLite file in your home folder. No account, no cloud, no API key. Known key and token formats are redacted before anything is stored. The only download is the embedding model and its runtime, once, and you can turn that off.

• No LLM of its own. Nothing calls a model on write or read, so memory costs you the tokens it injects, plus one short turn of your own agent when a session with real work ends. You can turn that off.

• Learns from your agent. At the end of a session with real work, your agent says which notes helped and which misled it. Kanerva learns from that per project and across projects. So far this has shown no measurable gain or harm, and KANERVA_LEARN=0 turns it off.

• Fits your tools. Plugins for Claude Code, Codex, OpenCode, Copilot CLI and more, plus an MCP server for everything else. The table says which ones have been run.

Install

You need uv (recommended) or python3 with NumPy. Then run this with the name of your agent, or with no name to set up every supported agent it finds:

curl -fsSL https://raw.githubusercontent.com/katolikov/kanerva/main/install.sh | sh -s -- codex

The script runs each agent's own install commands. Agents that need local files use a clone in ~/.kanerva/src, and run it again to update.

"Run" means a real session against a local stub model, with a seeded note showing up in the model's request. "Docs only" means the setup follows the agent's documentation and has not been run, so please report rough edges. Each agent's README under plugins/ has its limits.

The table is about notes on prompts. Notes about files were checked on Claude Code with a real model, and on Copilot CLI with a stub model.

If you would rather use the agent's own commands:

# Claude Code
claude plugin marketplace add katolikov/kanerva
claude plugin install kanerva@kanerva

# Codex: start Codex afterwards and run /hooks, because hooks stay off until you trust them
codex plugin marketplace add katolikov/kanerva
codex plugin add kanerva@kanerva

# Copilot CLI
copilot plugin marketplace add katolikov/kanerva
copilot plugin install kanerva@kanerva

# Hermes
hermes plugins install katolikov/kanerva/plugins/hermes --enable

# OpenCode 2.x
opencode plugin add 'github:katolikov/kanerva#main::path:plugins/opencode'

For any other MCP client:

uv tool install 'kanerva[onnx] @ git+https://github.com/katolikov/kanerva'

{
  "mcpServers": {
    "kanerva": { "command": "kanerva", "args": ["mcp"] }
  }
}

Related MCP server: LumenCore

What it looks like

There is no notes file to maintain, and everything stays readable and editable with kanerva list, kanerva show <id>, kanerva edit <id> "...", kanerva forget <id> and kanerva export memory.md.

How it works

Search engines find text that looks like your query. Kanerva also asks what is worth paying for: a small gradient-boosted model estimates how likely each candidate is to be needed, and selection packs the most expected value into your token budget. Search runs on words and on MiniLM vectors, and the model ships as a JSON file, so there is no training on your side. Each project gets its own memory, and a global scope is shared across projects.

• Changed facts. A note with a key closes the older note with that key. Without a key, a newer near-twin replaces an older fact if it covers your question at least as well, and your agent fixes what the rule cannot tell.

• The gate. A small model looks at the result list and decides whether the store can answer this prompt at all. If not, the prompt gets no notes.

• Notes about files. When a session first reads or edits a file, it gets the notes that name that file and that the prompt has not already brought.

• Learning. A note rises on questions like the ones it helped with, and falls wherever it sits idle. A shadow check decides when that starts. A project also learns when to speak: some prompts get a short wider list, and verdicts on it move the gate and the weight floor. The model itself never changes.

The name comes from Pentti Kanerva, whose sparse distributed memory showed how a few active bits out of many can recall what you need. It is also the idea behind the logo.

Benchmarks

Share of the needed evidence that made it into the context, with no LLM in the loop. "Lexical" is what runs until the model arrives. Unless noted, these figures come from version 0.5.0.

• Code. On 2,148 queries over 15 repositories in Python, TypeScript, Go and Rust that nothing was tuned on, Kanerva leads hybrid search by 2.4 points over all budgets, on all 15, and the reranker by 2.6.

• C and C++. On six more repositories, run once on the current version, Kanerva leads clearly on C, 0.939 against 0.914 for hybrid search. On C++, with templates and class methods among the facts, it leads on tasks (0.414 against 0.351) but trails overall (0.816 against 0.827), mostly because a location note gives way to a newer note holding the same value, so the value still reaches the context. An earlier test of six other repositories gave a lead of 1.1 points on all 6. Notes about files add 7.7 points at equal tokens. Working CMake, make and Ninja commands are kept as notes.

• Long conversations. 0.574 against 0.440 for hybrid search. This is a check and not a test, because earlier tests saw the data.

• Stale facts. With keys, no outdated version gets in. Without keys at 1024 tokens, the current version injects one 16.4% of the time on C and C++ and 21.0% on the earlier test's repositories, against about 98.0% for hybrid search.

• Changed notes. memory_remember lists similar notes and your agent fixes the older one. Across 104 real Claude Code sessions, it fixed 10 of 12 facts in its own conversation notes, 10 of 12 in long turns and 28 of 28 in code. It sometimes retires more than it should, and one such note survived only as history.

• Learning. Over 60 real sessions on repositories nothing had seen, your agent's verdicts on notes were right 96.7% of the time, against 29.2% for matching identifiers in tool calls. Acting on them has shown no measurable gain or harm on the current build: on six more repositories, right answers were 79.2% against 81.9% and tokens per session 267 against 318, all within noise. It is on because a project's gate can move no other way.

• Where it falls short. Asked in plain words with no identifier, the shipped gate brings the needed note on only 127 of 480 questions, though it reaches the candidate list on 420 of them. Lexical search stays close to BM25 from 512 tokens up. Without keys it gives up a little on exact facts. On answers from a small local model, better recall barely helped and no difference survived correction. On 603 real prompts of one developer, the gate gave notes to 53.6% of a project's own prompts and 27.7% of other projects' prompts, far weaker than on benchmarks. RepoMem queries come from templates, and real prompts are vaguer.

A query over 10,000 notes takes about 287 ms, or 0.72 s for a whole hook, which starts a new process.

The full method, proofs and all results are in the paper.

Configuration

Everything is optional.

MiniLM

all-MiniLM-L6-v2 runs on ONNX Runtime, with no torch. With uv you do nothing: the 90 MB model and ONNX Runtime arrive in the background on first use, search stays on words until then, and no hook waits for them. Without uv, run pip install onnxruntime tokenizers. After switching embedders, give older notes vectors with:

uvx --from 'kanerva[onnx] @ git+https://github.com/katolikov/kanerva' kanerva reembed

Other languages

Russian notes get a stemmer and stopwords with no setting. KANERVA_EMBEDDER=multilingual lets a Russian question find English notes and the other way round, at the cost of a larger, slower model.

Session wrap-up

Only your agent knows what it tried and why, so when a session has done real work it gets one more turn to say which notes helped with memory_feedback and to save a short outcome with memory_remember. Kanerva calls no model, but that turn costs what any turn costs. It has been run on Claude Code, Codex, OpenCode and Gemini CLI.

Use it as a library

from kanerva import Memory

memory = Memory("memory.sqlite")
memory.write("The API timeout is 30 seconds", key="config:timeout")
memory.write("The API timeout is 60 seconds", key="config:timeout")  # supersedes the old value, keeps history
print(memory.retrieve("what is the API timeout?", budget=200).render())

For the best recall at small budgets, pass reranker=CrossEncoderReranker() with the transformers extra. It costs one local model call per query.

Compared to other memory tools

Those projects have things Kanerva does not, such as LLM extraction, graph traversal and hosted operation.

Reproduce the results

make install && make data
make reproduce
make tools && make paper && make check

make check confirms that every number in the paper comes from results/.

Contributing

Issues and pull requests are welcome, see CONTRIBUTING.md. Benchmark results on your own repositories are especially useful.

Citation

@misc{kanerva2026,
  title  = {Kanerva: Token-Budgeted, Validity-Aware Memory for Coding Agents, Without an LLM in the Loop},
  author = {Katolikov, Artem},
  year   = {2026},
  doi    = {10.5281/zenodo.23849910},
  note   = {Preprint}
}

License

Apache-2.0. The LoCoMo and BEAM benchmarks have their own licenses and are downloaded when you run the experiments, not shipped here.