From 20063ff04c170d2d108dced8f4e4e78720147e22 Mon Sep 17 00:00:00 2001 From: RodCor Date: Wed, 10 Jun 2026 15:57:40 -0300 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20rework=20README=20=E2=80=94=20pitch?= =?UTF-8?q?-first,=20operations=20move=20to=20topic=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README had grown to 488 lines with two quickstarts, a ~100-line Remote section, benchmark detail accidentally INSIDE the install code fence (the fence opened at the cargo block never closed before it), and a How-it-works section duplicating the reference doc. Now 172 lines: tagline -> why -> compact how-it-works -> ONE quickstart (install, setup one-shot, selftest, first memory) -> 4-line benchmark blurb -> 8-line Remote teaser -> what's-in-the-box -> docs index. Operational content moved VERBATIM (numbers are audit-verified) to two new topic pages: - docs/INSTALL.md — install paths (cargo/npm/prebuilt), host wiring matrix, auto-harvest + distiller, config toggles, maintenance & lifecycle. - docs/REMOTE.md — full server setup, client wiring, retrieval quality, server-side ingest + repos.toml. Co-Authored-By: Claude Fable 5 --- README.md | 442 +++++++----------------------------------------- docs/INSTALL.md | 171 +++++++++++++++++++ docs/REMOTE.md | 92 ++++++++++ 3 files changed, 326 insertions(+), 379 deletions(-) create mode 100644 docs/INSTALL.md create mode 100644 docs/REMOTE.md diff --git a/README.md b/README.md index 5b23571..6213df6 100644 --- a/README.md +++ b/README.md @@ -39,13 +39,10 @@ win*, and lets that knowledge compound across runs. 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. + memory even when you used different words, and brain insights show you the + hit-rate, citation rate, and token economy so the value is measurable. - **It's yours, on your machine.** The whole brain is one SQLite file per - project — `.kimetsu/` is just `brain.db` plus a `project.toml`. No external - vector DB, no cloud, no telemetry. It auto-migrates forward on upgrade - (backing itself up first). Back it up with `cp`. + project. No external vector DB, no cloud, no telemetry. Back it up with `cp`. > *Kimetsu* (鬼滅) — "demon slayer." It slays the demon every agent fights: > amnesia. @@ -55,405 +52,88 @@ win*, and lets that knowledge compound across runs. ## 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 - +----------------------------+ + Host agent (Claude / Codex / Pi / OpenClaw / kimetsu chat) + │ asks for context ▲ cites what helped + ▼ │ + MCP tools ──► Broker ──► top memories ──► agent run + │ scores candidates by relevance × + │ usefulness × freshness × scope + ▼ + brain.db — one SQLite file: FTS5 + semantic ANN (usearch HNSW) ``` -1. **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. -2. **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_memory` when a memory actually helps. - Those citations are the ground truth. -3. **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](docs/HOW-KIMETSU-WORKS.md)**. +1. **Before a task**, the broker walks your project brain *and* your + cross-project user brain, scores every candidate, and injects the top few + inside an adaptive token budget. The semantic build matches by *meaning* + (O(log N) ANN — scales to ~1M memories in ~3 GB RAM, sub-2s retrieval). +2. **While it works**, Kimetsu surfaces known pitfalls *before* the first + attempt, and the model cites the memories that actually help. +3. **After the task**, cited memories get promoted, unused advice decays on a + half-life curve, and non-trivial sessions auto-harvest their lessons. ---- - -## 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`. - -```bash -# Default lean build — fast lexical (FTS) retrieval, no model download -cargo install kimetsu-cli - -# Semantic build — fastembed + ONNX; first run downloads BGE-small -cargo install kimetsu-cli --features embeddings - -# Add the Pi + OpenClaw host integrations to a source build (prebuilts already have them) -cargo install kimetsu-cli --features pi,openclaw -# Everything: -cargo install kimetsu-cli --features embeddings,pi,openclaw - -# From source -cargo install --path crates/kimetsu-cli # add --features embeddings,pi,openclaw for full build - -### Retrieval quality (benchmarked defaults) - -The embeddings build retrieves with **jina-v2-base-code** (embedder) + -**ms-marco-tinybert-l-2-v2** (cross-encoder reranker), chosen with -`kimetsu brain bench` on a 100-memory / 210-case confusable-cluster -dataset seeded from real exported memories: **recall@4 0.949, MRR 0.914 -at ~132ms per retrieval+rerank** (the fastest combo within ~2% of the -0.933 grid best; FTS-only scores MRR ~0.81 on the eval fixture). -Swap models with `kimetsu config set embedder.model|reranker …` (then -`kimetsu brain reindex`), and re-judge on your own corpus with -`kimetsu brain bench` — see "Retrieval models & benchmarking" in -[HOW-KIMETSU-WORKS](docs/HOW-KIMETSU-WORKS.md). -``` - -Prefer not to touch the Rust toolchain? Two options. - -**npm** — installs the prebuilt binary for your platform, no Rust required: - -```bash -npm install -g kimetsu-ai # lean build (all host integrations included) -kimetsu npm-flavor embeddings # one-time: switch to the semantic build — it persists -``` - -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/`](npm/) for details. - -**Pre-built archives** — for **Linux / macOS / Windows** on every -[GitHub Release](https://github.com/RodCor/kimetsu/releases). 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: - -```bash -kimetsu --version -kimetsu doctor # checks paths, brain.db, embedder, MCP, bridge -``` - -Check for updates: - -```bash -kimetsu update --check -kimetsu update # updates discovered kimetsu binaries on PATH/current install -kimetsu uninstall --dry-run -kimetsu uninstall --yes # removes discovered kimetsu binaries -``` - -`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. +Full mechanics — scoring, citations, decay, conflict detection, the daemon — +in **[HOW-KIMETSU-WORKS](docs/HOW-KIMETSU-WORKS.md)**. --- -## Quick start - -### 1. Talk to it directly - -```bash -kimetsu chat --workspace . --project . -``` - -`--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 ` 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: +## Quickstart ```bash -kimetsu plugin install claude --workspace . # writes .mcp.json + .claude/settings.json -kimetsu plugin install codex --workspace . # writes .codex/config.toml + .codex/hooks.json + skill + agent -kimetsu plugin install openclaw --workspace . # MCP server + hooks plugin + skill in .openclaw/ (requires --features openclaw on source builds) -kimetsu plugin install pi --workspace . # TS extension (Pi has no MCP) + skill in .pi/ (requires --features pi on source builds) +# 1. Install (cargo shown; npm + prebuilt archives in docs/INSTALL.md) +cargo install kimetsu-cli --features embeddings # or plain for the lean FTS build -# Install globally for every project (writes to the host's home config dir): -kimetsu plugin install claude --scope global - -# See what's wired where, or remove just the wiring (keeps the binary + brain): -kimetsu plugin status -kimetsu plugin uninstall codex --yes - -# Or do init + install + selftest in one shot: -kimetsu setup --host claude-code - -# Switched editors? Move your wiring — no reinstall (prebuilt/npm binaries -# include every host; on a source build add `--features pi`): -kimetsu plugin uninstall claude-code --yes # drop the old host's wiring -kimetsu plugin install pi # wire the new one -``` - -`--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-remote` **server is a -> separate package** — `cargo install kimetsu-cli` / `npm i -g kimetsu-ai` do -> **not** install it. Install it on the server when you want it: -> -> ```bash -> npm install -g kimetsu-remote # prebuilt server binary -> cargo install kimetsu-remote --features embeddings # or from source -> ``` -> -> (or grab the standalone `kimetsu-remote` archive from a GitHub Release). The -> `kimetsu plugin install --remote` *client* wiring is part of the normal -> `kimetsu` binary — 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: - -```bash -# On the server (build with --features embeddings for semantic retrieval): -kimetsu-remote serve --addr 0.0.0.0:8787 --data /srv/kimetsu-brains \ - --token --rate-limit 120 # 120 req/min per token (0 = off) -# one brain per repo under //; 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: -kimetsu plugin install claude-code --remote https://kimetsu.example.com:8787 -kimetsu plugin install openclaw --remote https://kimetsu.example.com:8787 -``` - -The repo id is derived from your git remote (`--repo ` to override), so the -endpoint becomes `https://…/mcp/`. 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 ` 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](docs/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): - -```toml -# repos.toml -[repos] -github-com-org-api = { url = "https://github.com/org/api.git", branch = "main" } -github-com-org-web = "https://github.com/org/web.git" -``` - -```bash -kimetsu-remote serve --data /srv/kimetsu-brains --token \ - --repos-file /etc/kimetsu/repos.toml --checkout-dir /srv/kimetsu-checkouts -``` - -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. +# 2. Wire it into your host agent — init + install + selftest in one shot +cd /your/project +kimetsu setup --host claude-code # or: codex | openclaw | pi -```bash -kimetsu brain search "build failures" -kimetsu brain context "where is auth configured?" -kimetsu brain memory top # most useful memories so far -kimetsu brain insights # is the brain actually helping? +# 3. Prove the brain works +kimetsu doctor --selftest +# ✓ recorded a memory and retrieved it — the brain works ``` -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 +From here your agent banks memories automatically — record one yourself and +watch it come back: ```bash -kimetsu config set embedder.enabled false # flip any toggle (config get reads one) -kimetsu brain export mem.json # move memories between brains (import reads them) -kimetsu brain memory edit --text "…" # fix a recording in place (undo retires the last one) -kimetsu runs prune --older-than 30d # drop old run dirs; brain compact VACUUMs brain.db -kimetsu ps # see running MCP servers; stop clears a stale one -kimetsu uninstall # tiered: binary / + plugin wiring / + brains +kimetsu brain memory add --scope project --kind convention "Use cargo nextest for all test runs" +kimetsu brain context "how do I run tests?" # broker-ranked context bundle +kimetsu brain insights # is the brain actually helping? ``` -`.kimetsu/` stays lean — just `brain.db` + `project.toml`; transient -proactive/chat/bench output lives under `~/.kimetsu/cache/`. +Prefer a standalone REPL? `kimetsu chat --workspace . --project .` is a full +terminal assistant with the same brain. Every install path (npm, prebuilt +archives), host-wiring details, the auto-harvest/distiller setup, and +maintenance commands live in **[docs/INSTALL.md](docs/INSTALL.md)**. --- -## 5-minute quickstart — prove it works - -**Step 1: Install** - -```bash -cargo install kimetsu-cli # lean build (FTS retrieval) -# or with semantic search: -cargo install kimetsu-cli --features embeddings -``` - -**Step 2: Wire it into your host agent** +## Retrieval quality — benchmarked, not vibes -```bash -cd /your/project -kimetsu init # creates .kimetsu/project.toml + brain.db -kimetsu plugin install claude --workspace . # Claude Code: writes .mcp.json + hooks -# or: codex | openclaw | pi -kimetsu plugin install codex --workspace . # Codex: writes .codex/ config + hooks -``` - -(Or collapse all three steps into one: `kimetsu setup --host claude-code`.) - -**Step 3: Verify the brain is working** - -```bash -kimetsu doctor --selftest -# prints: ✓ recorded a memory and retrieved it — the brain works -``` +The semantic build retrieves with **jina-v2-base-code** + a +**cross-encoder reranker** (`ms-marco-tinybert-l-2-v2`), chosen with +`kimetsu brain bench` on a 100-memory / 210-case dataset seeded from real +exported memories: **recall@4 0.949, MRR 0.914 at ~132ms** per +retrieval+rerank (FTS-only baseline: MRR ~0.81). Swap models with one config +key and re-judge on your own corpus — see +[Retrieval models & benchmarking](docs/HOW-KIMETSU-WORKS.md). -**Step 4: Record your first memory** - -From the command line: - -```bash -kimetsu brain memory add --scope project --kind convention "Use cargo nextest for all test runs" -``` +--- -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. +## Kimetsu Remote (beta) -**Step 5: Retrieve it** +Share one brain per repository from a server, over HTTP MCP — for a team, or +for yourself across machines: ```bash -kimetsu brain search "test runs" # lexical FTS search -kimetsu brain context "how do I run tests?" # broker-ranked context bundle -kimetsu brain memory top # most-useful memories by score -kimetsu brain insights # effectiveness analytics +# server +kimetsu-remote serve --addr 0.0.0.0:8787 --data /srv/kimetsu-brains --token +# each client +kimetsu plugin install claude-code --remote https://kimetsu.example.com:8787 ``` -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. +Bearer auth, per-repo brains, optional shared org-brain, server-side repo +ingest, TLS, Prometheus metrics, and a server-side reranker — full setup in +**[docs/REMOTE.md](docs/REMOTE.md)**. --- @@ -474,9 +154,13 @@ Built as a small Rust workspace (`kimetsu-cli`, `-chat`, `-agent`, `-brain`, ## Docs +- **[Install & host wiring](docs/INSTALL.md)** — every install path, plugin + install/uninstall/status, auto-harvest + distiller, maintenance commands. - **[How Kimetsu Works](docs/HOW-KIMETSU-WORKS.md)** — 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. + retrieval models & benchmarking, the bridge, doctor, and config. +- **[Kimetsu Remote](docs/REMOTE.md)** — server setup, org brain, server-side + ingest, TLS, client wiring. - **[CHANGELOG](CHANGELOG.md)** — what shipped in each release. - Per-crate `src/lib.rs` doc comments for module-level detail. diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..ceeb5a7 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,171 @@ +# Installing Kimetsu + +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`. + +## cargo + +```bash +# Default lean build — fast lexical (FTS) retrieval, no model download +cargo install kimetsu-cli + +# Semantic build — fastembed + ONNX; first run downloads the embedding model +cargo install kimetsu-cli --features embeddings + +# Add the Pi + OpenClaw host integrations to a source build (prebuilts already have them) +cargo install kimetsu-cli --features pi,openclaw +# Everything: +cargo install kimetsu-cli --features embeddings,pi,openclaw + +# From source +cargo install --path crates/kimetsu-cli # add --features embeddings,pi,openclaw for full build +``` + +## npm + +Installs the prebuilt binary for your platform, no Rust required: + +```bash +npm install -g kimetsu-ai # lean build (all host integrations included) +kimetsu npm-flavor embeddings # one-time: switch to the semantic build — it persists +``` + +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/`](../npm/) for details. + +## Pre-built archives + +For **Linux / macOS / Windows** on every +[GitHub Release](https://github.com/RodCor/kimetsu/releases). 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. + +## Health check, updates, uninstall + +```bash +kimetsu --version +kimetsu doctor # checks paths, brain.db, embedder, MCP, bridge + +kimetsu update --check +kimetsu update # updates discovered kimetsu binaries on PATH/current install +kimetsu uninstall --dry-run +kimetsu uninstall --yes # removes discovered kimetsu binaries +``` + +`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, source builds only) 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. + +## Wiring host agents + +Wire Kimetsu into any supported host. The built-in installers cover Claude Code, +Codex, Pi, and OpenClaw: + +```bash +kimetsu plugin install claude --workspace . # writes .mcp.json + .claude/settings.json +kimetsu plugin install codex --workspace . # writes .codex/config.toml + .codex/hooks.json + skill + agent +kimetsu plugin install openclaw --workspace . # MCP server + hooks plugin + skill in .openclaw/ (requires --features openclaw on source builds) +kimetsu plugin install pi --workspace . # TS extension (Pi has no MCP) + skill in .pi/ (requires --features pi on source builds) + +# Install globally for every project (writes to the host's home config dir): +kimetsu plugin install claude --scope global + +# See what's wired where, or remove just the wiring (keeps the binary + brain): +kimetsu plugin status +kimetsu plugin uninstall codex --yes + +# Or do init + install + selftest in one shot: +kimetsu setup --host claude-code + +# Switched editors? Move your wiring — no reinstall (prebuilt/npm binaries +# include every host; on a source build add `--features pi`): +kimetsu plugin uninstall claude-code --yes # drop the old host's wiring +kimetsu plugin install pi # wire the new one +``` + +`--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. + +## Auto-harvest and the SessionEnd distiller + +Memories 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. + +## Configuration toggles + +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 + +```bash +kimetsu config set embedder.enabled false # flip any toggle (config get reads one) +kimetsu brain export mem.json # move memories between brains (import reads them) +kimetsu brain memory edit --text "…" # fix a recording in place (undo retires the last one) +kimetsu runs prune --older-than 30d # drop old run dirs; brain compact VACUUMs brain.db +kimetsu ps # see running MCP servers; stop clears a stale one +kimetsu uninstall # tiered: binary / + plugin wiring / + brains +``` + +`.kimetsu/` stays lean — just `brain.db` + `project.toml`; transient +proactive/chat/bench output lives under `~/.kimetsu/cache/`. + +For retrieval model selection (embedder/reranker swapping, benchmarking your +own corpus), see +[Retrieval models & benchmarking in HOW-KIMETSU-WORKS](HOW-KIMETSU-WORKS.md). diff --git a/docs/REMOTE.md b/docs/REMOTE.md new file mode 100644 index 0000000..d30e10c --- /dev/null +++ b/docs/REMOTE.md @@ -0,0 +1,92 @@ +# Kimetsu Remote (beta) + +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. + +> **Beta.** Kimetsu Remote is under active testing and may have rough edges or +> breaking changes before the stable release. The `kimetsu-remote` **server is a +> separate package** — `cargo install kimetsu-cli` / `npm i -g kimetsu-ai` do +> **not** install it. Install it on the server when you want it: +> +> ```bash +> npm install -g kimetsu-remote # prebuilt server binary +> cargo install kimetsu-remote --features embeddings # or from source +> ``` +> +> (or grab the standalone `kimetsu-remote` archive from a GitHub Release). The +> `kimetsu plugin install --remote` *client* wiring is part of the normal +> `kimetsu` binary — no separate install needed to point a host at a server. + +## Server + client setup + +```bash +# On the server (build with --features embeddings for semantic retrieval): +kimetsu-remote serve --addr 0.0.0.0:8787 --data /srv/kimetsu-brains \ + --token --rate-limit 120 # 120 req/min per token (0 = off) +# one brain per repo under //; 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: +kimetsu plugin install claude-code --remote https://kimetsu.example.com:8787 +kimetsu plugin install openclaw --remote https://kimetsu.example.com:8787 +``` + +The repo id is derived from your git remote (`--repo ` to override), so the +endpoint becomes `https://…/mcp/`. 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 ` 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](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): + +```toml +# repos.toml +[repos] +github-com-org-api = { url = "https://github.com/org/api.git", branch = "main" } +github-com-org-web = "https://github.com/org/web.git" +``` + +```bash +kimetsu-remote serve --data /srv/kimetsu-brains --token \ + --repos-file /etc/kimetsu/repos.toml --checkout-dir /srv/kimetsu-checkouts +``` + +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. + +For the architecture (auth, rate limiting, org brain, the tool allowlist, the +write-tools gate), see §7a in [HOW-KIMETSU-WORKS.md](HOW-KIMETSU-WORKS.md). From 6ddaff1504a885b9d33ecefed65dc5406458e530 Mon Sep 17 00:00:00 2001 From: RodCor Date: Wed, 10 Jun 2026 16:01:11 -0300 Subject: [PATCH 2/2] fix: README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6213df6..1e83a23 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ ### 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.** +**Evidence-first memory for 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.