krouter
KRouter: a shared, plain-Markdown memory for coding agents.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/matata2017--dsh-krouter)HTML
<a href="/listings/matata2017--dsh-krouter"><img src="/api/listings/matata2017--dsh-krouter/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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`](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](docs/OVERVIEW.md#a-writers-vault-in-claude-desktop).
Mention it and it comes to mind
Two layers. **Each message:** the prompt hook looks it up on this machine (no model call, nothing sent out) and hands over a page when the message names the page or an alias, or its words match one page clearly ahead of the others; for an unrelated message it says nothing. **Each session start:** an index of what has been settled goes in front of the agent, which then fetches the page itself; the way people actually talk, naming nothing, is caught mostly by this layer. It needs a host with those hooks and a model that goes and looks: Claude Code and Codex have both layers, Cursor only the session-start one, and an app that only runs the MCP server has the lookup tools and nothing automatic ([Works with](#works-with)). On 120 invented, spoken-style messages ([set 45](bench/memory_honesty/HELDOUT.md#set-45-mention-it-the-way-people-actually-say-it--does-the-prompt-hook-bring-the-right-page-when-the-message-does-not-use-the-pages-words-registered-2026-11-13-before-any-case-existed), development half, not held out) the hook alone recalled **7 of 48** mentions (1 of 42 that name nothing); with both layers **Sonnet 5.5 recalled 44 of 48 and Haiku 5.5 42** (38 when the index could not list every topic); changed rules **23 of 24**; no old page; of 48 messages that should change nothing, 4 to 6 moved something. Read with: a lookup counts as moving it; the test vault holds each handbook page in Chinese and English, so fetching the other language's twin counts as a wrong page or a miss, which makes wrong pages and English recall look worse than they are; the messages are invented, the vault small, each condition run once. Set 35 (held out, 24 mentions of things the vault holds, both layers together) is higher: **24 / 24 and 23 / 24**, and messages that should change nothing moved it 1 / 24 and 2 / 24 ([set 35](bench/memory_honesty/HELDOUT.md#set-35-the-subconscious-as-a-whole--the-prompt-hook-then-the-host-reading-a-standing-index-registered-2026-11-10-before-any-case-existed)).
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](bench/memory_honesty/HELDOUT.md#set-18-does-following-the-vaults-own-connections-bring-the-whole-answer-registered-2026-11-10-before-the-associative-path-was-written-or-any-held-out-question-was-run)).
The lessons carry over
A lesson from one task is offered on another in the same situation; lessons that keep coming back grow into skills,
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 13 lines
- {
- "name": "krouter",
- "owner": { "name": "398894496-arch", "url": "https://github.com/398894496-arch" },
- "description": "KRouter: a shared, plain-Markdown memory for coding agents.",
- "plugins": [
- {
- "name": "krouter",
- "source": "./",
- "description": "Your agents remember what you decided and what you changed, with the source of every answer.",
- "category": "productivity"
- }
- ]
- }
README.md · README · 356 lines
- # KRouter
- <!-- mcp-name: io.github.398894496-arch/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; an experimental 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.
- <details>
- <summary>What the agent was actually handed (the prompt hook's raw output on the English sample memory)</summary>
- ```text
- 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)
- ```
- </details>
- ## Install
- ```bash
- 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`](docs/INSTALL.md).
- **See it in a few seconds, nothing installed, no key:** the same story on a throwaway memory, deleted afterwards.
- ```bash
- 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](docs/OVERVIEW.md#a-writers-vault-in-claude-desktop).
- ### Mention it and it comes to mind
- Two layers. **Each message:** the prompt hook looks it up on this machine (no model call, nothing sent out) and hands over a page when the message names the page or an alias, or its words match one page clearly ahead of the others; for an unrelated message it says nothing. **Each session start:** an index of what has been settled goes in front of the agent, which then fetches the page itself; the way people actually talk, naming nothing, is caught mostly by this layer. It needs a host with those hooks and a model that goes and looks: Claude Code and Codex have both layers, Cursor only the session-start one, and an app that only runs the MCP server has the lookup tools and nothing automatic ([Works with](#works-with)). On 120 invented, spoken-style messages ([set 45](bench/memory_honesty/HELDOUT.md#set-45-mention-it-the-way-people-actually-say-it--does-the-prompt-hook-bring-the-right-page-when-the-message-does-not-use-the-pages-words-registered-2026-11-13-before-any-case-existed), development half, not held out) the hook alone recalled **7 of 48** mentions (1 of 42 that name nothing); with both layers **Sonnet 5.5 recalled 44 of 48 and Haiku 5.5 42** (38 when the index could not list every topic); changed rules **23 of 24**; no old page; of 48 messages that should change nothing, 4 to 6 moved something. Read with: a lookup counts as moving it; the test vault holds each handbook page in Chinese and English, so fetching the other language's twin counts as a wrong page or a miss, which makes wrong pages and English recall look worse than they are; the messages are invented, the vault small, each condition run once. Set 35 (held out, 24 mentions of things the vault holds, both layers together) is higher: **24 / 24 and 23 / 24**, and messages that should change nothing moved it 1 / 24 and 2 / 24 ([set 35](bench/memory_honesty/HELDOUT.md#set-35-the-subconscious-as-a-whole--the-prompt-hook-then-the-host-reading-a-standing-index-registered-2026-11-10-before-any-case-existed)).
- ### 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](bench/memory_honesty/HELDOUT.md#set-18-does-following-the-vaults-own-connections-bring-the-whole-answer-registered-2026-11-10-before-the-associative-path-was-written-or-any-held-out-question-was-run)).
- ### The lessons carry over
- A lesson from one task is offered on another in the same situation; lessons that keep coming back grow into skills,
- and lessons or hook triggers unused for 60 days step back (`hot_days`, never your rules). 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`](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](https://obsidian.md) 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](#it-is-also-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`](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 at 2.1.1's pages (set 22: 449 of 500, held-out half 201 of 235) has no keyword-search row at the same page count.
- - 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; on one real vault, tuned on half of it, 0.4% of
- the owner's pages were taken for reference (sets 40, 42); `krouter kb mine PAGE` corrects a wrong call.
- [](https://github.com/398894496-arch/KRouter/actions/workflows/ci.yml) [](https://github.com/398894496-arch/KRouter/releases/latest) [](LICENSE) · 中文:[`README.zh.md`](README.zh.md)
- **Engineering facts**, each one checkable now: created 2026-08, one maintainer so far ([`MAINTAINERS.md`](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`](.github/workflows/ci.yml)).
- - Each release carries SHA-256 sums and a GitHub build-provenance attestation (`gh attestation verify <package> --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`](scripts/release_smoke.py), [`release.yml`](.github/workflows/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`](docs/NUMBERS.md)); question sets and scripts are in the repo ([`HELDOUT.md`](bench/memory_honesty/HELDOUT.md), [rerun them](#check-it-yourself)).
- - [`SECURITY.md`](SECURITY.md), [`CHANGELOG.md`](CHANGELOG.md), `./scripts/install.sh --upgrade`, `./scripts/uninstall.sh`, and any earlier release with `KROUTER_TAG=` ([`DETAILS.md`](docs/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](docs/INSTALL.md#without-an-api-key)).
- | I want to… | Start here |
- |---|---|
- | see it answer, correct itself and refuse, before installing anything | `krouter demo` (above) |
- | see what it remembers, and why it answered the way it did | [`krouter view`, `krouter why`](#see-what-it-remembers) |
- | give the AI apps I already use a memory | [Install](#install): one line, asks nothing, wires every app it finds (`--minimal`: lookup only, the apps you name) |
- | check which apps it connects to | [Works with](#works-with) |
- | have it read the notes and documents I already have | [Your knowledge base](#it-is-also-your-knowledge-base) |
- | run one memory for my team: a token each, who changed what | [For a team](#for-a-team) |
- | call it from my own code | [From your own code](#from-your-own-code) |
- | check the numbers myself | [Check it yourself](#check-it-yourself) |
- | know exactly what leaves my machine | [What leaves your machine](#what-leaves-your-machine) |
- | read everything this page leaves out (a writer's example, every benchmark section, each app's notes) | [`docs/OVERVIEW.md`](docs/OVERVIEW.md) |
- ## For a team
- **Experimental. Tested on one machine only; no real team has used it over weeks; the Kubernetes manifest and the systemd unit are checked by tests and have never been run on a cluster or a host.** 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 in force and the earlier one
- is kept as replaced, named in the reply. Ten people's agents on one laptop (set 27): 0 errors in 440 calls at each of
- three sizes, all 204 writes per size under the right person's name, none lost; 30 minutes at 10,136 pages: 21,218
- calls, 0 errors. Deployment, tokens, TLS and the
- numbers: [`docs/TEAM.md`](docs/TEAM.md#5-ten-people-at-once).
- ## It is also your knowledge base
- Point KRouter at a folder of Markdown you already have (an Obsidian vault, a docs repository, a notes directory) and
- every page in it can be found with the page it came from. The folder holds two kinds of page: **your memory** (what you
- decided, your rules and corrections, what sessions were distilled into) and **your knowledge base** (reference
- material: articles, clippings, research, documents someone else wrote). Both are searched; only your memory counts as
- what you decided.
- ```bash
- krouter kb add "Research" # declare a folder as the knowledge base (one line in krouter-kb.txt, next to your pages)
- krouter kb mine "Notes/essay.md" # a page (or folder) taken for reference material that is yours
- krouter kb import report.pdf # a PDF, Word or HTML file → a Markdown page in the knowledge base
- ```
- Clipping folders (`Clippings`, `剪藏`, `Web clips`) and pages with a web clipper's frontmatter count without being
- declared. A lookup lists knowledge-base pages in a block of their own, each with its title, source and the matching
- line, and they never set the confidence; when only they match, the receipt starts with `memory: none`:
- ```text
- memory: none (your memory has nothing on this; only reference material in your knowledge base matched, listed under knowledge_base)
- …
- recall: none (no page covers enough of the question; do not guess)
- knowledge_base: reference material in your knowledge base (articles, clippings, documents: someone else's writing, not something you decided). Cite it as a source with its path; never give it as your decision
- - Research/Billing outage at a fintech.md kb=declared score=…
- title: Billing outage at a fintech
- L5: The billing service database ran out of connections during a schema migration. …
- ```
- **What it does not do:** it searches Markdown only; `import` converts other files with a tool already on your machine
- (`markitdown`, `pandoc`, or `pdftotext` for PDF; plain HTML needs none) and says which one to install when there is
- none. There is no vector search ([measured, not shipped](docs/DENSE-OPTIN.md)). Undeclared pages are sorted by where
- they came from and how they read (a source line, a byline, an article's shape); `krouter why` says why
- ([details](docs/DETAILS.md#clipped-pages-and-other-peoples-writing)).
- ## From your own code
- `pipx install "git+https://github.com/398894496-arch/KRouter"`, then in Python `krouter.ask("how do we ship a
- release?")` gives the page, the one-line answer and whether the memory refused, and `krouter.note(…)` writes a line.
- LangGraph can keep its long-term memory in the folder (`krouter.integrations.langgraph.KRouterStore`, experimental); JavaScript,
- LlamaIndex and the MCP clients of other frameworks: [`docs/INSTALL.md`](docs/INSTALL.md#from-your-own-code) and
- [`docs/FRAMEWORKS.md`](docs/FRAMEWORKS.md).
- ## Works with
- One install wires every app it finds, in each app's own documented settings format; it keeps the rest of each file and
- a copy of it, and `uninstall.sh` takes out only its own entries. Each app's full test notes:
- [`docs/OVERVIEW.md`](docs/OVERVIEW.md#works-with-in-full).
- | App | How it connects | Tested so far |
- |---|---|---|
- | Claude Code | plugin (session hooks, the per-message layer included) and MCP, both by the installer | in the app, and in real sessions ([`VERIFY.md`](docs/VERIFY.md#platforms-and-real-sessions-200-candidate-2026-11-10)) |
- | Codex | MCP and session hooks (`~/.codex/hooks.json`; trust them once with `/hooks`), the per-message layer included | codex-cli 0.155.0-alpha.9.2 (2026-11-09): tools found, an answer with its page, a refusal, the hooks ran; 20 real tasks |
- | Cursor | rule and skill, MCP, session hooks; no per-message layer (its hook cannot add context), the session-start index instead | Cursor agent CLI 2026.11.05 (2026-11-09): tools listed, an answer with its page, a refusal, the hooks wrote the session pages; 3 real tasks |
- | DeepSeek Harness | plugin: `dsh plugin --profile web add github:398894496-arch/KRouter` | tested |
- | Hermes | MCP: `hermes mcp add krouter --command python3 --args …/mcp_server.py` ([how](docs/INSTALL.md#hermes-and-openclaw)); the lookup tools only, no hooks | Hermes Agent 0.18.2 (2026-11-10), in a separate config folder: connected, its 5 tools listed; no question asked there (no model logged in) |
- | OpenClaw | the skill folder: OpenClaw reads `~/.agents/skills`, where the installer puts KRouter ([how](docs/INSTALL.md#hermes-and-openclaw)); MCP also possible | run in real use as a skill (1.2.x); 2.x not yet run in OpenClaw; its MCP route not tried |
- | Claude Desktop | double-click [`KRouter.mcpb`](https://github.com/398894496-arch/KRouter/releases/latest/download/KRouter.mcpb) and press Install; or the installer writes its settings file while the app is closed | the extension inside the app (4.23118.1, macOS, 2026-11-10): tools connected, an answer with its page, an unknown question refused; built with the full Python path, as the installer builds it |
- | VS Code (Copilot) · Copilot CLI · Gemini CLI · Kiro · Zed · Cline CLI | MCP: the installer writes each app's settings file; restart the app once | settings checked by tests against each app's documented format |
- | Any other app that runs a local MCP server (Windsurf, opencode, Continue, Roo Code, …) | add the server below to its MCP settings | not run by us: [tell us](https://github.com/398894496-arch/KRouter/issues) |
- | LangGraph long-term memory (no MCP) | `krouter.integrations.langgraph.KRouterStore` ([`FRAMEWORKS.md`](docs/FRAMEWORKS.md#langgraph-store-long-term-memory)) | experimental: real graphs, langgraph 1.0 and 1.2, in CI only; not run by us in a deployed agent |
- | LlamaIndex, LangChain, OpenAI Agents SDK, Pydantic AI, Google ADK, CrewAI, Vercel AI SDK | a LlamaIndex retriever; the others through their own MCP client ([`FRAMEWORKS.md`](docs/FRAMEWORKS.md)) | against the server in CI; three through their whole agent loop |
- | Your own code | a Python package and `krouter` command; a dependency-free JavaScript / TypeScript client | tested |
- ```json
- { "mcpServers": { "krouter": { "command": "python3",
- "args": ["/Users/you/.agents/skills/krouter/scripts/mcp_server.py"] } } }
- ```
- In the official MCP Registry as `io.github.398894496-arch/krouter` ([entry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.398894496-arch/krouter)), pointing at the release's
- `KRouter.mcpb`, so apps that browse the registry can find it.
- Use the full path to your home folder (on Windows, `C:\\Users\\you\\.agents\\…` and often `python`). The server is
- standard-library Python over stdio with three tools: `krouter_ask` and `krouter_status` read; `krouter_note` lets
- your AI write one line down (a decision, a correction, a fact). A note lands on that day's notes page as a clue,
- never on a rule page, as one git commit you can revert.
- ## Next to MemOS and Hindsight
- Their cells say what their own pages say; the "Recalls without being asked" row also reads the documentation pages linked in it (read 2026-11-13).
- | | KRouter | MemOS | Hindsight |
- |---|---|---|---|
- | Runs as | a Markdown folder and a local index; standard-library Python, one install line, no server, no key | cloud (API key), self-hosted (Neo4j + Qdrant) or a local plugin (Node.js) | a server on PostgreSQL + pgvector with an LLM key, or Hindsight Cloud |
- | Recalls without being asked | Two layers. **Per message:** the hook looks the message up on the machine, no model call, nothing sent out; it hands over a page when the message names the page or an alias, or its words match one page clearly ahead of the others, stays quiet when the message is unrelated, and a replaced page does not come back. **At session start:** an index of what was settled, which the host model reads and fetches from itself; spoken wording that names nothing is caught mostly here. This needs a host with those hooks and a model that goes and looks: Claude Code and Codex have both, Cursor only the session-start one, an app with only the MCP server has the lookup tools and nothing automatic (see Works with). The other two also recall automatically, at the start of a task or a turn (next two cells). Measured ([set 45](bench/memory_honesty/HELDOUT.md#set-45-mention-it-the-way-people-actually-say-it--does-the-prompt-hook-bring-the-right-page-when-the-message-does-not-use-the-pages-words-registered-2026-11-13-before-any-case-existed), 120 invented spoken-style messages, development half, not held out): the hook alone 7 of 48 mentions (1 of 42 that name nothing); both layers together Sonnet 5.5 44 of 48 and Haiku 5.5 42 (38 when the index could not list every topic); changed rules 23 of 24; no old page; of 48 messages that should change nothing, 4 to 6 moved something. Read with: a lookup counts as moving it; the test vault holds each handbook page in Chinese and English, so fetching the other language's twin counts as a wrong page or a miss, which makes wrong pages and English recall look worse than they are; messages invented, vault small, each condition run once. Set 35 (held out, 24 mentions of things the vault holds, both layers together): Sonnet 5.5 24 and Haiku 5.5 23; all 12 changed rules got the new page; of 24 messages that should change nothing, 1 (Sonnet) and 2 (Haiku) moved it ([set 35](bench/memory_honesty/HELDOUT.md#set-35-the-subconscious-as-a-whole--the-prompt-hook-then-the-host-reading-a-standing-index-registered-2026-11-10-before-any-case-existed)). Time: 116–126 ms warm median at 10,000 pages (details in [`NUMBERS`](docs/NUMBERS.md)) | Plugins recall "before a task" / "before each agent run" and save after it (README: OpenClaw, DeepSeek Harness, Hermes). Its docs, read 2026-11-13: the DeepSeek Harness cloud plugin retrieves before the first model step of each turn and writes back after a successful turn ([OpenClaw guide](https://memos-docs.openmem.net/openclaw/guide)); the local plugin retrieves and injects before each task, from data on your machine ([Local Plugin](https://memos-docs.openmem.net/openclaw/local_plugin)); the OpenClaw plugin is said to retrieve only 3–5 relevant memories at a time, keeping context within 2,000–3,000 tokens (OpenClaw guide) | Its docs page "Coding Agents" ([read 2026-11-13](https://hindsight.vectorize.io/sdks/integrations/coding-agents)): the memory is put in front of the agent as it starts working; `autoInject` is what gets injected once, on the session's first prompt (default a low-budget reflect; `pages` and `recall` are retrieval only, no LLM, and retry on the next prompt, up to 5, if nothing was found); `pageRefreshEveryTurns` (default 1) refetches the pages and re-injects the page roster and tool guide every N user turns; for Qwen Code the page says interactive sessions "recall once per prompt", and the page does not explain how that fits injecting once on the first prompt; memory lives in Hindsight Cloud by default, or a server you run, or a local daemon. LLM wrapper (README): memories stored and retrieved on every call. The numbers on the docs page (corrections and cost per task) measure the memory as a whole, not when it recalls |
- | Answers name their source | every answer, with a receipt | not stated on its page | observations keep quotes and a proof count |
- | Knowledge base | reference pages recognised by themselves (or declared), listed apart, importable from PDF / Word / HTML; no vector search | "Multi-Cube Knowledge Base Management" | not stated as a separate layer |
- | Says it does not know | **whole chain (set 41, 2026-11-12), reader model Claude Opus 5.5 (one of three readers run): of 30 LongMemEval unanswerable questions 24 said the memory does not have it (80.0%); of 60 LoCoMo adversarial ones 47 (78.3%); on 40 answerable controls 5 wrongly refused (12.5%); the bar set beforehand was met. The other readers' results, the parts that missed the bar and the given-nothing comparison: [`docs/NUMBERS.md`](docs/NUMBERS.md). The others' numbers are for other questions and other models and cannot be ranked against these.** Retrieval layer: receipt 9 / 30 `none`, 21 `related` (only related pages), 0 `direct`; with a reader 29 / 30 earlier, but 30 / 30 given nothing | no figure on its page | no figure on its page |
- | Benchmarks | LongMemEval S answer accuracy: 449 of 500 right (89.8%), held-out half 201 of 235 (85.5%); Sonnet 5.5 as reader and judge, a run of our own; plain BM25 not rerun at the same page count; not a third-party side-by-side evaluation | self-reported (OmniMemEval): LongMemEval 89.20, LoCoMo 88.83 | LongMemEval state of the art (vendor chart, January 2026), partly reproduced by others |
- | Size (GitHub, 2026-11-11) | 49 stars, one maintainer | 12,352 stars | 60,340 stars; hosted, 99.9% SLA |
- Every cell's source and date, and why these numbers cannot be ranked against each other: [`docs/COMPARE.md`](docs/COMPARE.md).
- ## Ten projects side by side
- Ten open-source memory projects, each cell only what that project's own GitHub page says (fetched 2026-11-11; the Hindsight and MemOS "Recall without being asked" cells also read their documentation pages, 2026-11-13); "not stated" means the README does not say it, not that the project cannot.
- | | How it runs | Key for core function? | Recall without being asked | Answer carries a source | Evaluation numbers on the page | Stars |
- |---|---|---|---|---|---|---|
- | **basic-memory** | Local `uv tool install`, files on disk; cloud version too | Local: page names no key; cloud: sign-in | Claude Code plugin: session-start briefing; others: not stated | Not stated | No numbers | 4,550 |
- | **claude-mem** | `npx claude-mem install`; local SQLite | Pick a provider: its own observer (30-day trial), your OpenRouter/Gemini key, or your Anthropic plan | "Automatically appear in new sessions" | Each observation has an ID you can cite | No benchmark numbers (only "~10x token savings") | 115,909 |
- | **cognee** | pip install; Docker; cloud | Local quickstart: none; a key only for generated answers | Not stated (Claude Code and Codex plugins listed) | "Can inspect the retrieved evidence" | Self-reported BEAM: 0.79 (100K, 20 questions), 0.67 (10M, exploratory) | 33,232 |
- | **graphiti** | Python framework; bring your own graph DB (Neo4j, FalkorDB, Neptune) and LLM | OpenAI by default; `OPENAI_API_KEY` | Not stated | Each fact traces to its source episode | No numbers (paper link) | 32,727 |
- | **Hindsight** | Server (Docker, pip, Helm), Python embedded, cloud | Quick start needs an LLM key; page says local models work | Coding-agent package: injects once on the session's first prompt (default a low-budget reflect; `pages` / `recall` are retrieval only) and refetches the page roster every user turn by default; LLM wrapper: stores and retrieves each call (docs page read 2026-11-13) | Observations keep exact quotes and a proof count | Chart only (LongMemEval, 2026-01); says reproduced by others; no numbers | 60,340 |
- | **KRouter** | A folder of Markdown + SQLite; one install line; no server | Lookup needs none; only optional distilling uses a model | Two layers. Where the host has a per-message hook (not Cursor, see Works with), every message is looked up on the machine, no model, nothing sent out, and a page is handed over when the message names the page or an alias, or its words match one page clearly ahead of the others; at session start an index of what was settled, from which the host fetches for itself (mostly what catches spoken wording; it needs a host that goes and looks). Measured: set 45, 120 invented spoken-style messages, development half: the hook alone 7 of 48 mentions, both layers 44 (Sonnet 5.5) and 42 (Haiku 5.5), changed rules 23 of 24, 4 to 6 of 48 quiet messages moved (a lookup counts); set 35, held out, mentions of things the vault holds, both layers: 24 of 24 and 23 of 24; 116–126 ms warm median at 10,000 pages (details in [`NUMBERS`](docs/NUMBERS.md)) | Every answer names its page, with a receipt | Self-reported: LongMemEval held-out half 210/235 (BM25 198, retrieval only); LongMemEval answer accuracy 449/500, held-out half 201/235 (2.1.1, Sonnet 5.5 reader and judge, set 22); LoCoMo 991/1,540 | 49 |
- | **Letta** | npm install of a terminal tool; `letta server`; cloud | Not stated | Not stated | Not stated | No numbers | 25,413 |
- | **mem0** | Library (pip/npm), self-hosted (docker compose), cloud | Needs an LLM (OpenAI by default); cloud needs a key | Not stated (example searches by hand in code) | Not stated | Self-reported (managed platform): LoCoMo 92.5, LongMemEval 94.4, BEAM 64.1/48.6 | 68,777 |
- | **MemOS** | Four entry points: cloud API, self-host (Neo4j+Qdrant), cloud plugin, local plugin (Node.js, SQLite) | Cloud: key; self-host: keys in .env; local plugin: not stated | Plugins recall before a task / each agent run; docs: DeepSeek Harness cloud plugin before the first model step of each turn, local plugin before each task, OpenClaw plugin 3–5 memories at a time (docs read 2026-11-13) | Not stated | Self-reported (OmniMemEval): LoCoMo 88.83, LongMemEval 89.20 and eight more | 12,352 |
- | **Supermemory** | Cloud (plugins, hosted MCP), local single binary, Docker | Local: embeddings need no key, first boot makes a local key; cloud: not stated | "Runs in the background; next conversation your AI already knows you" | Not stated | Self-reported: "#1" on three benchmarks (no scores); LongMemEval Recall@15 95% | 31,592 |
- Every cell's source and date, and the full version: [`docs/COMPARE-ALL.md`](docs/COMPARE-ALL.md). The others' numbers are for other questions and other models, so they cannot be ranked against each other or against KRouter's; this table does not rank and does not say who is first.
- ## Day one: bring in your past sessions
- Once, if you like, bring in your past sessions, so on day one your agent knows what you settled before. The first two
- steps never call a model and nothing leaves the machine; the third uses your agent's subscription (at least one call per
- session, the newest 40 by default): [`docs/INSTALL.md`](docs/INSTALL.md#bring-in-your-past-sessions).
- ```bash
- python3 ~/.agents/skills/krouter/scripts/import_sessions.py --days 3650 --dry-run --distill # how many; writes nothing
- python3 ~/.agents/skills/krouter/scripts/import_sessions.py --days 3650 --local # import all, no model
- python3 ~/.agents/skills/krouter/scripts/import_sessions.py --days 3650 --distill --distill-max 40 # distill the newest 40
- ```
- ## See what it remembers
- Nothing is hidden, and there is a page to look at it with. Both commands only read.
- ```bash
- krouter why "when do we ship releases" # how that lookup came out, in words
- krouter view # a page on this machine only: prints http://127.0.0.1:<port>/, opens nothing
- krouter view --demo # the same page on a throwaway sample memory (add --open to open it in your browser)
- ```
- 
- `why` says which alias or words matched, why each page sits where it does, why the confidence is that one, which pages came along a connection and from which page, which page replaced which, and, when the memory does not know, which word it could not find. `view` adds the pages with search (it pages through tens of thousands), the connections around a page with why each one exists, the experience cards with how often each was offered and taken, what the last nights did, and a box that runs `why`. It listens on 127.0.0.1 only, answers GET only so nothing in it can change the memory, loads nothing from the internet, and works in English and Chinese, light and dark, on a phone-width screen. [How to read it](docs/DETAILS.md#see-what-it-remembers-krouter-why-and-krouter-view).
- ## What leaves your machine
- Queries never do: lookup is a local SQLite full-text index (83–87 ms warm median on the 110-page test vault, 116–126 ms at 10,000 pages (whole hook process, p95 up to 144 ms; set 34, before 2.1.0; the 2.1.0 prompt hook's warm p95 at 10,000 pages is 129–131 ms, set 39)). Session import is local. Text goes to a
- model only for the two steps you said yes to (distilling sessions, nightly upkeep), to the CLI or API key you already
- use, and `--dry-run` shows the size first. Keys and pages marked secret are never sent or quoted. What each model
- lane can read: [`SECURITY.md`](SECURITY.md).
- **Backups.** `backup.py init --dir <a folder that syncs elsewhere>` turns on a nightly encrypted archive of the whole
- vault, history included; KRouter itself talks to no cloud ([details](docs/DETAILS.md#backing-up-your-vault)).
- ## Measured, not claimed
- Held out, hosts Claude Sonnet 5.5 and Haiku 5.5. Mention it and it comes to mind ([set 35](bench/memory_honesty/HELDOUT.md#set-35-the-subconscious-as-a-whole--the-prompt-hook-then-the-host-reading-a-standing-index-registered-2026-11-10-before-any-case-existed)): of 24 mentions, two thirds without the page's names, the right page for **24 and 23**; all 12 changed rules brought the new page; messages that should change nothing moved it 1 and 2 of 24 (both layers together, on messages that mention something the vault holds; on spoken-style invented messages, set 45's development half, the hook alone recalled 7 of 48 and both layers 44 and 42). The lessons carry over (sets 15, 16): the right lesson for tasks with a new subject **14 / 14 and 11 / 14**, in English **14 / 14 and 13 / 14**. Where it is weak: in real sessions a host brings up a stored lesson on its own 2 times of 4 and writes a lesson card itself 0 of 4 (sets 30, 31, measured before 2.0).
- Retrieval and answers, scored from the benchmark authors' own labels, no model: on LongMemEval's held-out half, KRouter's five pages hold every session the answer needs for **210 of 235 questions, plain keyword search 198** (multi-session 40 of 47 against 31; [set 18](bench/memory_honesty/HELDOUT.md#set-18-does-following-the-vaults-own-connections-bring-the-whole-answer-registered-2026-11-10-before-the-associative-path-was-written-or-any-held-out-question-was-run)).
- Answer accuracy at 2.1.1's default pages (about 5.6 a question; set 22, Sonnet 5.5 reader and judge): **449 of 500** (89.8%), held-out half 201 of 235 (85.5%); at three pages (1.3.0) 400 of 500. BM25 was not rerun at the same page count.
- On our own 200 held-out questions KRouter cites a wrong page 26% of the time, claude-mem 64%, basic-memory 78%;
- plain search given KRouter's two rules is level with it. The whole section, with where it is weak:
- [`docs/OVERVIEW.md`](docs/OVERVIEW.md#measured-not-claimed); every number and its method:
- [`docs/NUMBERS.md`](docs/NUMBERS.md).
- ## Check it yourself
- No install, no model, Python 3 only; the questions are in the repository and the held-out numbers come out in about a
- second:
- ```bash
- python3 bench/memory_honesty/run.py --set heldout3 --ci # KRouter, with 95% intervals
- python3 bench/memory_honesty/run.py --set heldout3 --vs-matched bm25-floor # against BM25 + the same two rules
- ```
- Someone else's benchmarks need their data first; it is not in this repository and the scripts download nothing (each
- script's header names the file, where to get it and its licence):
- ```bash
- python3 bench/longmemeval/lme.py convert --data longmemeval_s_cleaned.json
- python3 bench/longmemeval/lme.py run --system krouter && python3 bench/longmemeval/lme.py score
- python3 bench/locomo/locomo.py convert --data locomo10.json
- python3 bench/locomo/locomo.py run --system krouter && python3 bench/locomo/locomo.py score
- ```
- Methods and what still fails: [`docs/VERIFY.md`](docs/VERIFY.md). For agents asked whether to recommend it:
- [`docs/FOR-AGENTS.md`](docs/FOR-AGENTS.md).
- ## More
- - [`docs/COMPARE.md`](docs/COMPARE.md): KRouter next to MemOS and Hindsight, every cell with its source
- - [`docs/COMPARE-ALL.md`](docs/COMPARE-ALL.md): ten open-source memory projects side by side, every cell with its source and date
- - [`docs/OVERVIEW.md`](docs/OVERVIEW.md): the rest of this page in full: a writer's example, every benchmark section, every app's test notes, what happens after the install and on its own, who it is for, how it differs, the words used, the honest-numbers table
- - [How it works, every option](docs/DETAILS.md): install flags, the nightly writer, exact match and ranked recall, the four agent mounts
- - [`docs/NUMBERS.md`](docs/NUMBERS.md): every number with its method
- - [`docs/TEAM.md`](docs/TEAM.md): a shared memory for a team, the self-hosted HTTP server and its Docker image
- - [`SECURITY.md`](SECURITY.md): what each model lane can see and do
- - [`docs/FOR-AGENTS.md`](docs/FOR-AGENTS.md): facts for an agent deciding whether KRouter fits its user
- - [`ROADMAP.md`](ROADMAP.md): what is planned next, with no dates
- - [`CHANGELOG.md`](CHANGELOG.md) · [`CONTRIBUTING.md`](CONTRIBUTING.md): good first issues are labeled
- **Maintenance.** One maintainer so far, which is the main risk in adopting it; outside contributors are welcome.
- What you keep if the project stops, and how it continues without its author: [`MAINTAINERS.md`](MAINTAINERS.md).
- Minor releases come at most once a week and patches when ready; `KROUTER_TAG=v2.1.2` (any tag) pins one. What counts
- as the stable surface: [`DETAILS.md` → Stability and versions](docs/DETAILS.md#stability-and-versions). Bugs and
- questions: [issues](https://github.com/398894496-arch/KRouter/issues); security reports: [`SECURITY.md`](SECURITY.md).
- *Formerly DSH-KRouter. Old links, clone URLs and install lines still redirect.* MIT.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.