RodCor · RodCor · Jul 3, 2026 · Jun 24, 2026 · Jun 24, 2026 · Jun 24, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -6,9 +6,10 @@ on:
       - main
     paths:
       - 'docs/**'
-      - 'website/**'
+      - 'website-fumadocs/**'
       - 'README.md'
       - 'CHANGELOG.md'
+      - '.github/workflows/docs.yml'
   workflow_dispatch:
 
 permissions:
@@ -33,14 +34,14 @@ jobs:
         with:
           node-version: '22'
           cache: 'npm'
-          cache-dependency-path: website/package-lock.json
+          cache-dependency-path: website-fumadocs/package-lock.json
 
       - name: Install dependencies
-        working-directory: website
+        working-directory: website-fumadocs
         run: npm ci
 
       - name: Build
-        working-directory: website
+        working-directory: website-fumadocs
         run: npm run build
 
       - name: Setup Pages
@@ -49,7 +50,7 @@ jobs:
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: website/build
+          path: website-fumadocs/out
 
   deploy:
     environment:

diff --git a/.gitignore b/.gitignore
@@ -41,6 +41,8 @@
 # fastembed model cache created by tests/runs
 .fastembed_cache/
 **/.fastembed_cache/
+# test-isolation TMP dir (TMP/TEMP/GIT_CEILING override target)
+/tmp-tests/
 .claude/
 .codex/
 .mcp.json
@@ -60,3 +62,4 @@ memories-export*.json
 
 # Generated by website/scripts/sync-docs.mjs (do not edit; edit docs/ instead)
 docs-site-content/
+target-linux/
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -15,7 +15,7 @@ resolver = "3"
 # everything below except the per-crate `description`, `keywords`,
 # and `categories` which live in each `[package]` block since
 # crates.io enforces them per crate.
-version = "2.0.0"
+version = "2.5.0"
 edition = "2024"
 # Rust ecosystem dual-license (matches tokio, serde, fastembed-rs,
 # etc.). UNLICENSED would block crates.io entirely.

diff --git a/README.md b/README.md
@@ -18,99 +18,143 @@
 
 ---
 
-## 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 your host agent over MCP (Claude Code, Codex, Pi, OpenClaw, Cursor,
-Gemini CLI) or as its own terminal chat. 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 the model cites before solving a problem
-  get promoted. Silent passengers and stale advice decay and get pruned.
-- **It never explores twice.** A session-start digest and an episodic resume
-  mean the agent's first turn already knows the repo and what you were doing
-  last time. No re-deriving the basics, no "where was I."
-- **It answers, not just injects.** `kimetsu ask` composes a grounded, cited
+## What is Kimetsu
+
+Coding agents are brilliant and forgetful. Every session starts from zero: the
+same wrong turns, the same re-explained conventions, the same exploration you
+already paid for last week.
+
+Kimetsu is a sidecar brain for your agent. One Rust binary and one SQLite file
+per project, wired into Claude Code, Codex, Pi, OpenClaw, or Cursor over MCP,
+or driven from its own terminal chat. It captures the lessons an agent earns,
+learns which ones actually help, and hands them back before the next task. The
+memory pipeline calls no LLM: storage and retrieval are 100% local, free, and
+offline-capable.
+
+| | |
+|---:|---|
+| **73.3%** | BEAM 100K memory benchmark, matching the prior public state of the art, model-free |
+| **66.0%** | BEAM 1M, ahead of mem0's self-reported 62% at the same bucket |
+| **83.0%** | LongMemEval, the public long-term-memory benchmark |
+| **13x** | cheaper per solved task: $0.19 vs $2.47 on a 16-task Terminal-Bench slice |
+| **~1M** | memories held in ~3 GB RAM with sub-2s retrieval, one SQLite file |
+| **$0** | API cost to store and recall: zero LLM calls in the memory pipeline |
+
+---
+
+## Quickstart
+
+```bash
+npm install -g kimetsu-ai
+kimetsu npm-flavor embeddings        # one-time: enable semantic retrieval
+cd /your/project
+kimetsu setup --host claude-code     # or: codex | openclaw | pi
+kimetsu doctor --selftest            # records a memory and retrieves it
+```
+
+Other install paths (cargo, prebuilt archives) and host-wiring details are in
+**[the install guide](https://rodcor.github.io/kimetsu/docs/install)**.
+
+---
+
+## What it does
+
+- **Remembers what matters.** Project conventions, failure patterns, the exact
+  command that regenerates your schema. Captured once, retrieved by meaning,
+  even when you phrase it differently.
+- **Speaks first.** Most memory waits to be asked. Kimetsu is proactive: a
+  session-start digest, an episodic resume, and pre-task context mean the
+  agent's first turn already knows the repo, your conventions, and what you
+  were doing last time.
+- **Learns what helps.** Memories the model cites before solving a problem get
+  promoted. Stale advice and silent passengers decay and get pruned.
+- **Answers, not just injects.** `kimetsu ask` composes a grounded, cited
   answer from memory using a local model: zero frontier tokens, works offline.
   Lessons cited often enough graduate into runnable skills.
-- **It's cheap to be right.** On a recorded 16-task Terminal-Bench slice, runs
-  with Kimetsu cost about 13x less per win than the no-brain baseline ($0.19 vs
-  $2.47), and the ROI ledger shows the token savings on your own work.
-- **It gets smarter, not just bigger.** Semantic retrieval finds the right
-  memory even when you used different words, and it self-tunes retrieval against
-  your own query history.
-- **It's yours, on your machine.** The whole brain is one SQLite file per
-  project. No external vector DB, no cloud, no telemetry. Back it up with `cp`.
+- **Pays for itself.** ~13x cheaper per solved task than a no-brain baseline on
+  a recorded Terminal-Bench slice, and the ROI ledger shows the savings on your
+  own work.
+- **Stays yours.** The whole brain is one SQLite file per project. No external
+  vector DB, no cloud, no telemetry. Back it up with `cp`.
 
 ---
 
 ## How it works
 
-```
-  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)
-```
+<img src="docs/assets/how-it-works.svg" alt="How Kimetsu works: the host agent asks the broker for context, the broker scores candidates from brain.db by relevance, usefulness, freshness, and scope, injects the top memories into the agent run, and the run cites what helped so cited memories rise and stale ones decay" width="960" />
 
 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, scaling to ~1M memories in ~3 GB RAM, sub-2s retrieval).
+   inside an adaptive token budget.
 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.
 
-Full mechanics, scoring, citations, decay, conflict detection, and the daemon
-are in **[How Kimetsu Works](https://rodcor.github.io/kimetsu/docs/how-kimetsu-works)**.
+Full mechanics: scoring, citations, decay, conflict detection, retrieval
+levels, and the daemon, in
+**[How Kimetsu Works](https://rodcor.github.io/kimetsu/docs/how-kimetsu-works)**.
 
 ---
 
-## Benchmarks
-
-Every number is reproducible with `kimetsu brain bench` and the
-`kimetsu brain roi` ledger.
+## Share your brain
 
-| Metric | Result | How it's measured |
-|--------|--------|-------------------|
-| Cost per win | **$0.19 vs $2.47** (~13x cheaper) | 16-task Terminal-Bench slice, Kimetsu vs no-brain baseline |
-| Retrieval quality | **recall@4 0.949, MRR 0.914 at ~138 ms** (default), up to 0.975 / 0.933 | `kimetsu brain bench`, 100-memory / 210-case dataset, jina-v2-base-code + cross-encoder rerank |
-| Scale | ~1M memories in ~3 GB RAM, sub-2s retrieval | usearch HNSW ANN, O(log N) |
-| Footprint | one SQLite file per project, no cloud, no telemetry | back it up with `cp` |
+A brain is a portable file. Export it as a pack, hand it to a teammate, merge
+theirs into yours, or swap a whole brain in and out. Onboard a new machine or a
+new hire with one import.
 
-The semantic build retrieves with jina-v2-base-code and a cross-encoder
-reranker, tuned with `kimetsu brain bench` on a 100-memory / 210-case dataset of
-real exported memories. The latency-optimized default (ms-marco-tinybert-l-2-v2)
-lands recall@4 0.949, MRR 0.914 at ~138 ms; the quality-best rerankers reach
-recall@4 0.975, MRR 0.933. Swap embedder and reranker with one config key each
-and re-judge on your own corpus. Full grid in
-**[How Kimetsu Works](https://rodcor.github.io/kimetsu/docs/how-kimetsu-works)**.
+```bash
+# export a shareable pack (always gzip-compressed, always security-scrubbed)
+kimetsu brain export onboarding.json.gz --name rust-conventions --version 1.0.0
 
----
+# merge a pack into your brain (additive, dedups against what you already know)
+kimetsu brain import onboarding.json.gz
 
-## Quickstart
+# install straight from a URL
+kimetsu brain import https://example.com/packs/rust-conventions.json.gz
 
-```bash
-npm install -g kimetsu-ai
-kimetsu npm-flavor embeddings        # one-time: enable semantic retrieval
-cd /your/project
-kimetsu setup --host claude-code     # or: codex | openclaw | pi
-kimetsu doctor --selftest            # records a memory and retrieves it
+# swap: replace your current memories in the pack's scope (reversible)
+kimetsu brain import other-brain.json.gz --mode replace --yes
 ```
 
-Other install paths (cargo, prebuilt archives) and host-wiring details are in
-**[the install guide](https://rodcor.github.io/kimetsu/docs/install)**.
+Every export is scrubbed before it leaves your machine: credentials and PII
+are redacted automatically, and `--strict` aborts the export if anything was
+found. Merge is idempotent, so re-importing is safe. Replace supersedes rather
+than deletes, so a swap can always be undone. For continuous sharing,
+`kimetsu brain sync` replicates a brain across machines with no server, and
+**[Kimetsu Remote](https://rodcor.github.io/kimetsu/docs/remote)** serves one
+brain per repository to a whole team.
+
+---
+
+## Benchmarks vs other memory systems
+
+Kimetsu's memory pipeline (ingest, store, retrieve, rerank) makes **zero LLM
+calls**: FTS5 + local embeddings + a local cross-encoder. mem0 / Cognee / Zep /
+Letta call a model to distill memories at write time **and** keep an LLM in the
+retrieval loop (mem0's own 2026 figures report ~7,000 tokens per retrieval
+call, a metered cost on every question). Kimetsu lands in the same accuracy
+band without the LLM, the bill, or the cloud.
+
+| benchmark | Kimetsu (local, model-free) | mem0 | Cognee |
+|-----------|-----------------------------|------|--------|
+| **BEAM 1M** (matched bucket) | **66.0%** | 62% | not reported |
+| BEAM 100K | **73.3%** | n/a | 79% |
+| BEAM 10M | future work | 48.6% | 67% |
+| LongMemEval (`_s`) | **83.0%** (200-q) · ~80.9% weighted | 94.4% (full set, their reader) | not reported |
+
+Honest, not cherry-picked: our LongMemEval is a 200-question slice (not the
+full 500), our BEAM-1M is 15 of 35 conversations with a Codex reader vs mem0's
+full set on their own harness, Cognee (a knowledge-graph system with an LLM in
+the loop) leads at 100K/10M, and vendor numbers are self-reported. We ship the
+exact harness, reader, and settings so ours can be checked. Per-ability tables,
+caveats, and reproduction steps:
+**[the memory benchmark](https://rodcor.github.io/kimetsu/docs/memory-benchmark)**.
+
+Retrieval itself is benchmarked too: recall@4 0.949 and MRR 0.914 at ~138 ms
+with the default reranker (up to 0.975 / 0.933 with the quality-best one), on a
+210-case dataset of real exported memories. Reproduce or re-tune on your own
+corpus with `kimetsu brain bench`.
 
 ---
 
@@ -124,10 +168,11 @@ Other install paths (cargo, prebuilt archives) and host-wiring details are in
 | `kimetsu brain context "<q>"` | Broker-ranked context bundle for a query |
 | `kimetsu ask "<q>"` | Grounded, cited answer from memory (local model) |
 | `kimetsu resume` / `kimetsu checkpoint` | Pick up where the last session left off |
+| `kimetsu brain export` / `import` | Share brains: scrubbed packs, merge or replace, file or URL |
+| `kimetsu brain sync` | Replicate your brain across machines, no server |
 | `kimetsu brain skills` | Turn often-cited lessons into runnable skills |
 | `kimetsu brain insights` / `roi` | Is the brain helping, and did it pay for itself |
 | `kimetsu brain tune` | Self-tune retrieval against your own query history |
-| `kimetsu brain sync` | Replicate your brain across machines, no server |
 | `kimetsu brain bench` | Benchmark retrieval on your own corpus |
 
 The full command surface, configuration keys, and maintenance commands are in
@@ -154,20 +199,6 @@ ingest, TLS, Prometheus metrics, and a server-side reranker. Full setup in
 
 ---
 
-## What's in the box
-
-| Component | What it is |
-|-----------|------------|
-| **The brain** | Durable project + user memory in one auto-migrating SQLite file: FTS + semantic retrieval, citations, decay, conflict detection, self-tuning, and effectiveness analytics. |
-| **`kimetsu ask` + warm-start** | Grounded answers from memory, and a session-start digest plus episodic resume so the first turn already knows your work. |
-| **`kimetsu chat`** | A full terminal coding assistant running against your workspace. |
-| **MCP sidecar** | `kimetsu mcp serve` exposes the brain to any MCP host as `kimetsu_*` tools. |
-| **Kimetsu Remote** *(beta)* | The brain over HTTP MCP, one per repository, shared from a server. |
-
-Built as a small Rust workspace. Lint and tests run clean on every change.
-
----
-
 ## Docs
 
 - **[Install & host wiring](https://rodcor.github.io/kimetsu/docs/install)**: every install path, host

diff --git a/crates/kimetsu-agent/Cargo.toml b/crates/kimetsu-agent/Cargo.toml
@@ -27,8 +27,8 @@ aws-sigv4.workspace = true
 aws-smithy-runtime-api.workspace = true
 blake3.workspace = true
 http.workspace = true
-kimetsu-brain = { path = "../kimetsu-brain", version = "2.0.0" }
-kimetsu-core = { path = "../kimetsu-core", version = "2.0.0" }
+kimetsu-brain = { path = "../kimetsu-brain", version = "2.5.0" }
+kimetsu-core = { path = "../kimetsu-core", version = "2.5.0" }
 regex.workspace = true
 reqwest.workspace = true
 rusqlite.workspace = true