Kimetsu
Give your coding agent a memory that gets sharper every run.
Evidence-first memory for MCP-capable coding agents and Kimetsu's own terminal chat. Kimetsu sits beside your AI agent, watches what actually solves problems, remembers it, and feeds the high-signal context back — so the next run starts where the last one left off.
Why Kimetsu
LLM coding agents are brilliant and forgetful. Every session starts from zero — the same wrong turns, the same re-explaining of your conventions, the same expensive exploration you already paid for last week.
Kimetsu fixes the forgetting. It's a sidecar brain: a single Rust binary that runs next to any supported host agent through MCP (Claude Code, Codex, Pi, OpenClaw) or as its own terminal chat — or, in beta, server-hosted over HTTP MCP and shared across a team. It learns which memories the model actually used to win, and lets that knowledge compound across runs.
- It remembers. Project conventions, failure patterns, the exact command that regenerates your schema — captured once, retrieved automatically.
- It learns what helps. Memories that the model cites before solving a problem get promoted. Silent passengers and stale advice decay and get pruned.
- It's cheap to be right. On a recorded 16-task Terminal-Bench slice, Kimetsu-enabled runs cost ~13x less per win than the no-brain host-agent baseline: $0.19/win vs $2.47/win.
- It gets smarter, not just bigger. Semantic retrieval finds the right memory even when you used different words; the agent surfaces known pitfalls before it repeats them; and brain insights show you the hit-rate, citation rate, and token economy so the value is measurable, not a vibe.
- It's yours, on your machine. The whole brain is one SQLite file per
project —
.kimetsu/is justbrain.dbplus aproject.toml. No external vector DB, no cloud, no telemetry. It auto-migrates forward on upgrade (backing itself up first). Back it up withcp.
Kimetsu (鬼滅) — "demon slayer." It slays the demon every agent fights: amnesia.
How it works
+----------------------------+
| Host agent |
| Claude / Codex / Pi / |
| OpenClaw / chat |
+-------------+--------------+
|
| asks for context
v
+-------------+--------------+ +------------------------------+
| MCP tool surface | | Kimetsu brain |
| kimetsu_brain_context | -----> | brain.db |
| cite_memory / record | | SQLite + FTS5 + embeddings |
+-------------+--------------+ +---------------+--------------+
| ^
| candidates |
v |
+-------------+--------------+ |
| Broker | |
| scores + ranks by: | |
| relevance, usefulness, | |
| freshness, scope | |
+-------------+--------------+ |
| |
| top context |
v |
+-------------+--------------+ |
| Agent run | |
| uses context, cites memory | -----------------------+
| outcomes update ranking | citations + outcomes
+----------------------------+
- Before a task, the agent asks Kimetsu for context. The broker walks your project brain and your cross-project user brain, scores every candidate memory (relevance × usefulness × freshness × scope), de-duplicates, and injects the top few inside an adaptive token budget. On the semantic build it also runs an approximate-nearest-neighbour index (usearch HNSW) so a memory surfaces even when the query shares no words with it — O(log N) per query, scaling to ~1M memories in ~3 GB RAM with sub-2s retrieval.
- While it works, Kimetsu is proactive: it surfaces "known pitfalls"
before the first attempt, classifies the task to bias which kinds of memory
it recalls, and the model calls
cite_memorywhen a memory actually helps. Those citations are the ground truth. - After the task, Kimetsu rewards cited memories, lightly nudges the "silent passengers," and lets old advice decay on a half-life curve. The brain gets sharper with every run — automatically.
The whole brain is one auto-migrating SQLite file: brain.db's events table
is the durable log, so .kimetsu/ stays lean (just brain.db + project.toml)
and upgrades migrate forward with a backup taken first.
Want the full mechanics — scoring weights, semantic retrieval, the proactive agent brain, citation deltas, decay, conflict detection? See docs/HOW-KIMETSU-WORKS.md.
Install
Kimetsu is a single Rust binary. There's really only one choice to make at
install time — lean vs semantic (embeddings) — because that's the only part
baked into the binary. Which host agents you use (Claude Code, Codex, Pi,
OpenClaw) is a runtime choice you change anytime with kimetsu plugin install/uninstall — no reinstall. The official prebuilt + npm binaries
include all four host integrations; a bare source cargo install is minimal and
adds them with --features pi,openclaw.
# Default lean build — fast lexical (FTS) retrieval, no model download
# Semantic build — fastembed + ONNX; first run downloads BGE-small
# Add the Pi + OpenClaw host integrations to a source build (prebuilts already have them)
# Everything:
# From source
### Retrieval quality (benchmarked defaults)
)
)
; )
)
)
Prefer not to touch the Rust toolchain? Two options.
npm — installs the prebuilt binary for your platform, no Rust required:
npm pulls only the matching per-platform package (@kimetsu-ai/*) via
optionalDependencies — there's no postinstall download, so it works under
npm install --ignore-scripts. kimetsu npm-flavor embeddings fetches the
semantic build once and remembers the choice (no env var to keep exported);
kimetsu npm-flavor lean switches back, and kimetsu npm-flavor status shows
the current one. (The KIMETSU_NPM_FLAVOR env var still works as a per-run
override.) The embeddings build is available where ONNX Runtime prebuilts exist
(Linux x64, macOS Apple Silicon, Windows x64); elsewhere it stays lean. See
npm/ for details.
Pre-built archives — for Linux / macOS / Windows on every
GitHub Release. Extract the archive and put
kimetsu / kimetsu.exe somewhere on PATH (~/.local/bin, /usr/local/bin,
or %USERPROFILE%\.cargo\bin). Every prebuilt archive — lean and embeddings —
bundles all four host integrations, so switching hosts never needs a reinstall.
Lean archives are published for Linux,
macOS Intel, macOS Apple Silicon, and Windows. Embeddings archives are
published where ONNX Runtime prebuilts are available: Linux x86_64,
macOS Apple Silicon, and Windows x86_64.
Confirm it's healthy:
Check for updates:
kimetsu update downloads the matching GitHub Release archive for your
platform and flavor, then updates the current executable plus verified
kimetsu copies in known install locations such as Cargo bin, ~/.local/bin,
/usr/local/bin, or %USERPROFILE%\.cargo\bin. It does not scan the whole
disk. kimetsu uninstall removes those same verified binaries; it leaves
project .kimetsu/ directories and the user brain intact unless you explicitly
pass --delete-user-data.
Prerequisites: Rust 1.85+ (stable) and a model credential for the surface
you use (CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY, or OPENAI_API_KEY).
On AWS Bedrock, set [model] provider = "bedrock" and authenticate with
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (+ optional AWS_SESSION_TOKEN)
and AWS_REGION — the agent and the auto-harvester both support it, and can be
pointed at different providers. That's it for chat — Docker, Harbor, and Python
are only needed for benchmark runs.
Quick start
1. Talk to it directly
--project . turns on memory: Kimetsu keeps one brain session open for the
whole conversation and injects retrieved context into every turn. Inside chat,
/help lists everything; favorites: /plan, /run, /verify, /review,
/skills, /cost, and $skill <prompt> to apply a skill.
2. Or bolt it onto a host agent
Wire Kimetsu into any supported host. The built-in installers cover Claude Code, Codex, Pi, and OpenClaw:
# Install globally for every project (writes to the host's home config dir):
# See what's wired where, or remove just the wiring (keeps the binary + brain):
# Or do init + install + selftest in one shot:
# Switched editors? Move your wiring — no reinstall (prebuilt/npm binaries
# include every host; on a source build add `--features pi`):
--scope defaults to workspace. The installer merges into existing
config: if you already have hooks — even on the same events Kimetsu uses
(UserPromptSubmit, PreToolUse, …) — your hooks are kept and Kimetsu's are
added alongside them. Re-running is idempotent and never needs --force.
Now your host agent gets the kimetsu_* MCP tools (brain context, memory
add/list, citations, repo ingest, the cross-harness skill bridge) and starts
banking memories across every session.
Memories also get auto-harvested: when you fix a command that was failing,
or finish a non-trivial session without recording anything, a Kimetsu hook cues
the agent to dispatch a background kimetsu-memory-harvester subagent (a cheap
in-agent distiller) that records the lesson for next time — no extra API key.
Turn it off with [learning] auto_harvest = false in .kimetsu/project.toml.
For a deterministic harvest that doesn't depend on the agent, kimetsu plugin install claude-code and kimetsu plugin install codex offer to set up a
SessionEnd distiller: a cheap configured model (Anthropic
claude-haiku-4-5, OpenAI gpt-5.4-mini, or a compatible endpoint via
ANTHROPIC_BASE_URL / OPENAI_BASE_URL) that distills each session itself at
the end and records the lessons. Claude Code runs it from SessionEnd; Codex
runs it from the supported Stop hook with --distill-on-stop. The wizard
stores the key in a gitignored .env; skip it with --no-setup. Run it with
--scope global to configure the distiller once in
~/.kimetsu/ — it then distills every project's sessions into your user brain
(available everywhere), unless that project has its own distiller.
3. Or share one brain from a server (Kimetsu Remote — beta)
Beta. Kimetsu Remote is under active testing and may have rough edges or breaking changes before the stable release. The
kimetsu-remoteserver is a separate package —cargo install kimetsu-cli/npm i -g kimetsu-aido not install it. Install it on the server when you want it:(or grab the standalone
kimetsu-remotearchive from a GitHub Release). Thekimetsu plugin install --remoteclient wiring is part of the normalkimetsubinary — no separate install needed to point a host at a server.
Run the brain on a server and connect over HTTP MCP, so a team — or you across machines — shares one brain per repository, with no local checkout:
# On the server (build with --features embeddings for semantic retrieval):
# one brain per repo under <data>/<repo-id>/; bearer-auth; plain HTTP — put a
# TLS proxy (nginx/Caddy) in front, or build `--features tls` and pass
# --tls-cert/--tls-key for in-process HTTPS. `GET /healthz` and `GET /metrics`
# (Prometheus text, aggregate-only) are unauthenticated. Prebuilt
# kimetsu-remote binaries are built with embeddings + TLS support.
#
# Add --org-brain /srv/kimetsu-org for a shared team brain: memories recorded
# at `global_user` scope land there and merge into EVERY repo's retrieval
# (project-scoped memories stay per-repo). Must be outside --data.
#
# Add --repos-file repos.toml --checkout-dir /srv/checkouts to let the server
# clone registered repos and ingest their files (remote file-capsule retrieval).
# On each client — wire a host at the remote instead of the local stdio command:
The repo id is derived from your git remote (--repo <id> to override), so the
endpoint becomes https://…/mcp/<repo-id>. By default the host config
references ${KIMETSU_REMOTE_TOKEN} (set that env var where your agent runs)
rather than writing the token to disk; pass --token <t> to embed a literal.
The remote surfaces the memory/retrieval/curation tools by default.
Retrieval quality. The server reranks kimetsu_brain_context results with a
cross-encoder (--reranker, default jina-reranker-v1-tiny-en, operator-level —
"off" disables, any curated/HF id accepted). Benchmark results on the 100-memory
dataset (production floors active, jina-tiny reranker):
| embedder | MRR | seq mean | rps | peak RSS |
|---|---|---|---|---|
| jina-v2-base-code | 0.906 | 416ms | 5.0 | 1.2 GB |
| bge-small-en-v1.5 | 0.909 | 700ms | 3.8 | 697 MB |
The embedder is set per-repo via config or KIMETSU_BRAIN_EMBEDDER; the reranker
is operator-owned and cannot be overridden by a repo's project.toml.
See §7a "Retrieval models on the server" in
HOW-KIMETSU-WORKS.md for the full table and
how to re-run the benchmark.
Server-side ingest (optional). To make file-capsule retrieval work remotely, let the server keep a managed clone of each repo. The operator pre-registers repos in a TOML file (so clients can't make the server clone arbitrary URLs):
# repos.toml
[]
= { = "https://github.com/org/api.git", = "main" }
= "https://github.com/org/web.git"
Then kimetsu_brain_ingest_repo clones/refreshes the registered repo and indexes
its files into that repo's brain, so context retrieval includes file capsules.
Private repos use the server's own git auth (credential helper / SSH / a token in
the URL). The repo-id keys must match the ids clients connect with.
Every optional feature is turn-off-able in .kimetsu/project.toml —
embeddings ([embedder] enabled), ambient workspace context
([broker] ambient), the global user brain ([kimetsu] use_user_brain),
auto-harvest, the distiller, secret redaction. The precedence is
env override > config > default, and kimetsu config edit opens the file
in $EDITOR and re-validates on save. Re-installing merges, so your toggles
survive.
Maintenance & lifecycle
.kimetsu/ stays lean — just brain.db + project.toml; transient
proactive/chat/bench output lives under ~/.kimetsu/cache/.
5-minute quickstart — prove it works
Step 1: Install
# or with semantic search:
Step 2: Wire it into your host agent
# or: codex | openclaw | pi
(Or collapse all three steps into one: kimetsu setup --host claude-code.)
Step 3: Verify the brain is working
# prints: ✓ recorded a memory and retrieved it — the brain works
Step 4: Record your first memory
From the command line:
Or let the agent record it — inside Claude Code or Codex, the agent calls
kimetsu_brain_record after any non-trivial solve. The Stop hook prints a
summary at the end of each session.
Step 5: Retrieve it
From this point your agent automatically retrieves the top context capsules
before each task. Cite a memory to give it a +1 usefulness signal;
memories the agent never reaches for decay slowly and can be pruned
with kimetsu brain memory prune.
Troubleshoot: kimetsu doctor checks paths, brain.db schema, embedder,
MCP wiring, and installed hooks. kimetsu doctor --selftest is the one-shot
"confirm it works end-to-end" check.
What's in the box
| Surface | What it is |
|---|---|
kimetsu chat |
A full terminal coding assistant — slash commands, skills, hooks, background tasks, MCP, agents. Runs against your workspace, no Harbor required. |
kimetsu brain |
Durable, auto-migrating project + user memory in a single SQLite file. Citations, decay, conflict detection, FTS + optional semantic (usearch HNSW ANN, scales to ~1M memories) retrieval, and kimetsu brain insights effectiveness analytics. |
kimetsu bridge |
Cross-harness skill portability — import/export skills between supported hosts such as Claude Code, Codex, Agents, and Kimetsu. |
| MCP sidecar | kimetsu mcp serve exposes the brain to any MCP host as kimetsu_* tools. |
| Kimetsu Remote (beta) | kimetsu-remote — the brain over HTTP MCP, one per repository, shared from a server (separate package). |
Built as a small Rust workspace (kimetsu-cli, -chat, -agent, -brain,
-core, and -remote). Lint + tests run clean on every change.
Docs
- How Kimetsu Works — the conceptual reference: the brain, the broker, citations, decay, conflict detection, the MCP surface, Kimetsu Remote, the bridge, doctor, and config. Start here for depth.
- CHANGELOG — what shipped in each release.
- Per-crate
src/lib.rsdoc comments for module-level detail.
License
Dual-licensed under MIT or Apache-2.0 — your choice.