KRouter

KRouter

Give your agent a subconscious: mention it and it comes to mind, with what is connected to it, and the lessons carry over.

*"Subconscious" is a figure of speech: recall that happens without you asking. A lookup on your machine, no model, nothing sent.*

KRouter is a local Markdown memory for coding agents (Claude Code, Codex, Cursor, DeepSeek Harness, Hermes, OpenClaw) and for any app that speaks MCP, Claude Desktop for one. When something you mention was settled before, the agent recalls it, with what is connected to it; a lesson from one task is offered on another; a change of mind replaces the old answer; every answer names the page it came from. For one person it needs no API key and no server; a team server and model distilling are optional (below).

You: Going to move the clippings originals into the archive folder this afternoon.

Agent: That note says not to move the Clippings originals (from your "User preferences" page under 02 Methods/Agent), so I'd hold off on moving them to the archive this afternoon. If you meant a copy or a different set of files, tell me and we can sort out a safe way to do it.

You: The coffee machine on our floor is broken again.

Agent: Sorry to hear that, it's annoying when it keeps happening. I can't fix it from here, but I can help you draft a quick message to facilities if you'd like.

You only mentioned it in passing; KRouter recognised something already settled in what you said and handed it to the agent with the page it came from. The second remark touches nothing in the memory, so nothing was added and the agent answered as usual. Both agent replies are real: Claude Sonnet 5.5 (a Claude Code subagent, no tools), 2026-11-10, given exactly what the collapsed block below shows, copied as it answered; with another agent, the reply is up to that agent.

What the agent was actually handed (the prompt hook's raw output on the English sample memory)

you  > Going to move the clippings originals into the archive folder this afternoon.

hook > KRouter memory note (recalled from the user's vault, not typed by the user; it may not bear on this message):

• "clippings originals" → Do not move Clippings originals [02 Methods/Agent/User preferences.md, alias] If you use it, cite the page.

you > The coffee machine on our floor is broken again. hook > (nothing)

Install

curl -fsSL https://github.com/398894496-arch/KRouter/releases/latest/download/bootstrap.sh -o /tmp/krouter-install.sh && sh /tmp/krouter-install.sh

~/.dsh-krouter/current/scripts/krouter doctor # OK, or what is missing and how to fix it ~/.dsh-krouter/current/scripts/krouter search "what did we decide about X?" # your first question

It asks nothing and connects the AI apps it finds. An existing folder keeps every file; only missing ones are added, and uninstalling never touches your memory. Windows, the Claude Code plugin, --minimal, every file it changes, what works without a key, and uninstalling: docs/INSTALL.md.

See it in a few seconds, nothing installed, no key: the same story on a throwaway memory, deleted afterwards.

uvx --from git+https://github.com/398894496-arch/KRouter krouter demo      # or, in a clone: PYTHONPATH=sdk python3 -m krouter.cli demo

Your own vault, Claude Desktop and Obsidian: a writer's example.

Mention it and it comes to mind

Every message is looked up locally, and the session starts with an index of what has been settled, so the agent also catches a thing said in other words. Held out, 24 mentions (two thirds without the page's names): Sonnet 5.5 24 / 24, Haiku 5.5 23 / 24; messages that should change nothing moved it 1 / 24 and 2 / 24 (set 35).

With what is connected to it

A lookup gives five pages: three that match, then up to two the memory connects to them (a link, a replacement, the same session, rare words they share, being cited together). Held-out half of LongMemEval, five pages each: every session the answer needs for 210 of 235 questions, keyword search 198; multi-session 40 against 31 (set 18).

The lessons carry over

A lesson from one task is offered on another in the same situation, and lessons that keep coming back grow into skills the agent fetches when they fit. Held out: the right lesson for 14 / 14 (Sonnet 5.5) and 11 / 14 (Haiku 5.5) tasks with a new subject, 14 / 14 and 13 / 14 in English (sets 15, 16); skills drafted right 16 / 16 and fetched and followed 12 / 12 (sets 24, 25; bench/memory_honesty/HELDOUT.md).

Underneath, what you can check

Every answer comes with the page it came from; when your memory has nothing on a question, the receipt says so outright, when it has only something close it says how sure it is instead of passing that off as the answer, and reference material you keep never stands in for what you decided; a correction replaces the old answer instead of competing with it; and you can see all of it: the memory is a folder of plain Markdown you can open and edit, in Obsidian or any editor, and krouter view / krouter why show what it holds and why it answered. It works with the AI you already use, and one is enough.

Refusing comes in two layers, and only the first is KRouter's. On LongMemEval's 30 unanswerable questions KRouter's own receipt says recall: none for 9. With a reader model on top, 29 of the 30 were answered "not mentioned", but the same reader given nothing at all said so for all 30, so that second number is mostly the model's doing. What KRouter does: when nothing in the memory matches, it says so outright; when only something close matches, it hands the model the page and a confidence level instead of passing a near match off as the answer. Not a guarantee without exceptions: for 22 of those 30 the best page is a real session about something near what was asked. Reference material you declare as your knowledge base never counts as the memory's answer: when only it matches, the receipt's first line is memory: none. A rule to refuse more near matches was looked for on development data (set 37) and none was good enough, so the numbers above stand. Instead the receipt's first line says which case it is: memory: direct, memory: related (only related pages: answer only from a sentence that states it outright, else say the memory does not have it) or memory: none; for the 30, 0 / 21 / 9. Strict mode (KROUTER_STRICT=1, off by default) treats related as none; on a memory of session pages that means it answers almost nothing (set 38). Method and the other benches: docs/NUMBERS.md.

What it does not do

• The samples are small: a few dozen cases per set.
• In these evaluations the host wrote down which page it would fetch; it did not call the tools for real.
• In real sessions hosts almost never write a lesson card on their own (0 of 4 on both hosts, sets 30 and 31): learning comes from the hooks and the nightly run.
• On Cursor the per-message layer is not available (its hook cannot add context); it gets the session-start index.
• Answer accuracy has not been rerun for the five-page version (set 22 is registered, not run).
• Windows was not tested for 2.0.
• A question about something near what your memory holds still gets an answer, usually at low or medium. Paragraph evidence (set 39) refuses more on LoCoMo (18 → 61 of 223) but not on LongMemEval (9 → 10 of 30): off by default.
• Reference material is recognised page by page without declaring (set 40: 30 of 32 held-out articles, 0 of 43 of your own pages taken for one), on a synthetic vault only; krouter kb mine PAGE corrects a wrong call.

· 中文：README.zh.md

Engineering facts, each one checkable now: created 2026-08, one maintainer so far (MAINTAINERS.md).

• Every push runs the full suite (687 tests as of 2.1.0; python3 -m pytest -q) on Linux, macOS and Windows, and a container smoke test (ci.yml).
• Each release carries SHA-256 sums and a GitHub build-provenance attestation (gh attestation verify --repo 398894496-arch/KRouter); the one-line install uses a tag, never main, and checks the sum before running anything.
• After a release, a job runs every install command this README gives against the published addresses (release_smoke.py, release.yml); the container image is ghcr.io/398894496-arch/krouter.
• In the official MCP Registry as io.github.398894496-arch/krouter.
• Evaluations are registered before they are run (rows that were not say so in NUMBERS.md); question sets and scripts are in the repo (HELDOUT.md, rerun them).
• SECURITY.md, CHANGELOG.md, ./scripts/install.sh --upgrade, ./scripts/uninstall.sh, and any earlier release with KROUTER_TAG= (DETAILS.md). What you ask never leaves your machine.

No key is needed to start: lookup, sources and refusals run with no model, and the newer page of a changed decision is listed first and flagged (what works without a model).

For a team

Tested on one machine only; no real team has used it over weeks. One server holds your team's memory: a folder of Markdown in a git repository, run by you (there is no KRouter cloud). Each person gets their own token, every write is recorded under the writer's name, and "who changed this, and when" can be asked (krouter_changes); when two people correct the same decision, the last to arrive is i