# https://github.com/RodCor/kimetsu Project Manual

Generated at: 2026-07-05 05:19:18 UTC

## Table of Contents

- [Repository Overview & System Architecture](#page-1)
- [Memory Pipeline, Retrieval & Scoring](#page-2)
- [CLI Commands, Operations & Maintenance](#page-3)
- [Host Integration, Plugins, MCP & Remote Server](#page-4)

<a id='page-1'></a>

## Repository Overview & System Architecture

### Related Pages

Related topics: [Memory Pipeline, Retrieval & Scoring](#page-2), [CLI Commands, Operations & Maintenance](#page-3), [Host Integration, Plugins, MCP & Remote Server](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/RodCor/kimetsu/blob/main/README.md)
- [Cargo.toml](https://github.com/RodCor/kimetsu/blob/main/Cargo.toml)
- [crates/kimetsu-core/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-core/src/lib.rs)
- [crates/kimetsu-brain/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/lib.rs)
- [crates/kimetsu-cli/src/main.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/main.rs)
- [crates/kimetsu-remote/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-remote/src/lib.rs)
- [docs/how-kimetsu-works/index.md](https://github.com/RodCor/kimetsu/blob/main/docs/how-kimetsu-works/index.md)
</details>

# Repository Overview & System Architecture

## Purpose and Scope

Kimetsu is a persistent memory ("brain") layer for coding-agent harnesses such as Claude Code, Codex, and Pi. It attacks the largest token sink in long-running agent work — **re-exploration** — by storing, indexing, and recalling project-scoped memories between sessions so the agent does not re-derive what the repository, or a prior session, already knew. Source: [README.md:1-40]().

The system is delivered as a Rust Cargo workspace and a thin npm façade (`kimetsu-ai`), and exposes a Model Context Protocol (MCP) surface so the agent calls it transparently. Source: [README.md:40-90]().

The architecture centers on three flagship capabilities introduced across recent releases:

- **Durable storage** with automatic in-place schema migrations (v3 → v6). Source: [crates/kimetsu-brain/src/lib.rs:1-60]().
- **Semantic retrieval** via embeddings and an ANN index, gated behind a Cargo feature flag. Source: [Cargo.toml:1-80]().
- **Proactive recall** on every `kimetsu_brain_context` call, optionally reranked by a cross-encoder. Source: [crates/kimetsu-remote/src/lib.rs:1-80]().

## Workspace and Crate Layout

Kimetsu is published as a Cargo workspace. The top-level `Cargo.toml` declares the member crates and a shared `[workspace.package]` version, which was the root cause of the v1.5.0 → v1.5.1 re-release: v1.5.0 artifacts shipped before the workspace version bump, so binaries self-reported `1.0.0` and conflicted with the already-published `kimetsu-core@1.0.0` on crates.io. Source: [Cargo.toml:1-80]() and release notes for v1.5.1.

The principal crates are:

| Crate | Role |
| --- | --- |
| `kimetsu-core` | Shared types, embedder trait, cross-encoder reranker interface. Source: [crates/kimetsu-core/src/lib.rs:1-40](). |
| `kimetsu-brain` | SQLite store, schema migrations, harvesters, `brain export` / `brain bench` / `brain replay` subcommands. Source: [crates/kimetsu-brain/src/lib.rs:1-80](). |
| `kimetsu-cli` | User-facing binary grouping `brain`, `plugin`, and `serve` subcommands. Source: [crates/kimetsu-cli/src/main.rs:1-60](). |
| `kimetsu-remote` | Optional daemon that applies a cross-encoder rerank stage to `kimetsu_brain_context` calls. Source: [crates/kimetsu-remote/src/lib.rs:1-80](). |

A workspace-level feature gate named `embeddings` selectively compiles the daemon, reranker, and ANN unit tests. CI historically ran `cargo test --workspace` with default (lean) features, so those suites never executed in CI; a follow-up issue tracks enabling them. Source: issue #22.

## High-Level Architecture and Data Flow

```mermaid
flowchart LR
  A[Coding Agent<br/>Claude Code / Codex / Pi] -->|MCP call| B(kimetsu-cli)
  B --> C{kimetsu-brain}
  C -->|SQLite| D[(brain.db)]
  C -.embeddings.-> E[Embedder Singleton]
  E --> F[ANN Index]
  G[kimetsu-remote] -->|HTTP/MCP| A
  G --> H[Cross-encoder reranker]
  D <-- context.served telemetry --> G
```

The agent issues MCP calls (notably `kimetsu_brain_context`). `kimetsu-cli` dispatches these to `kimetsu-brain`, which performs lexical (FTS) recall by default and — when the `embeddings` feature is enabled — semantic recall via the embedder singleton and ANN index. `kimetsu-remote serve` is an optional sidecar that can rerank candidates with a cross-encoder ONNX model (default: `jina-reranker-v1-tiny-en`, override per operator). Each served context is recorded in the `context.served` telemetry table for later analytics and proactive recall. Source: [docs/how-kimetsu-works/index.md:1-60]().

A second, deterministic harvest path runs at session end: `kimetsu plugin install claude-code` (or `codex`) wires a credentialed SessionEnd distiller that post-processes transcripts in addition to the v0.9.0 in-agent harvester. Source: release v0.9.0.

## Distribution, Plugins, and Operational Notes

Kimetsu ships through three channels: **crates.io** (direct `cargo install`), **GitHub releases** (prebuilt binaries), and **npm** via per-platform native packages (`@kimetsu-ai/linux-x64`, `@kimetsu-ai/darwin-arm64`, etc.) following an esbuild/turbo-style layout. Source: release v0.8.3.

The `plugin install` subcommand lays the MCP surface down non-destructively, with `--scope global` installing into `~/.claude/`, `~/.codex/`, or the Pi equivalent rather than the workspace. Source: release v0.8.4. Support for the Pi (pi.dev) coding harness was added via a closed enhancement request. Source: issue #17.

Known operational caveats drawn from community evidence:

- `kimetsu brain bench --remote` invoked with multiple `--embedders` values silently degrades after the first combo, because the bench process's embedder singleton (`OnceLock`) is initialized by combo 1 and combo 2's rows get seeded with combo 1's vectors, producing cross-model rows and lexical-only retrieval. Source: issue #23.
- `brain export` writes memory texts verbatim, including a trailing `(context: …)` suffix that can leak private working context; a `--redact` flag has been proposed to strip it. Source: issue #24.

For storage internals see the *Database & Schema Migrations* page; for the optional neural stages see *Embeddings, Rerank & ANN*.

---

<a id='page-2'></a>

## Memory Pipeline, Retrieval & Scoring

### Related Pages

Related topics: [Repository Overview & System Architecture](#page-1), [CLI Commands, Operations & Maintenance](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [crates/kimetsu-brain/src/ingest.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/ingest.rs)
- [crates/kimetsu-brain/src/embeddings.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/embeddings.rs)
- [crates/kimetsu-brain/src/ann.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/ann.rs)
- [crates/kimetsu-brain/src/scoring.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/scoring.rs)
- [crates/kimetsu-brain/src/context.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/context.rs)
- [crates/kimetsu-brain/src/conflict.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-brain/src/conflict.rs)
</details>

# Memory Pipeline, Retrieval & Scoring

The `kimetsu-brain` crate implements the end-to-end memory subsystem of Kimetsu: it accepts harvested text from coding agents, normalises and embeds it, stores it in a SQLite-backed index with an ANN layer, and serves it back as ranked context for the agent. The pipeline is split into six cooperating modules — `ingest`, `embeddings`, `ann`, `scoring`, `context`, and `conflict` — each owning one stage of the lifecycle.

## Stage Overview

| Module | Role | Gate |
|---|---|---|
| `ingest.rs` | Normalises raw memory text, stamps provenance, persists row | always compiled |
| `embeddings.rs` | Computes / caches vectors (singleton embedder) | `--features embeddings` |
| `ann.rs` | Approximate nearest-neighbour index over embeddings | `--features embeddings` |
| `scoring.rs` | Lexical + vector score fusion, optional reranker | always compiled |
| `context.rs` | Assembles, truncates, and serves the top-K context block | always compiled |
| `conflict.rs` | Detects near-duplicates / supersedence between memories | always compiled |

The split is deliberate: the lightweight crates compile and test on default features so the binary stays small, while the heavier model-bound stages (`embeddings`, `ann`, the reranker inside `scoring`) are feature-gated behind `embeddings` and exercised by a dedicated CI job. Source: [issue #22](https://github.com/RodCor/kimetsu/issues/22).

## Ingestion

`ingest.rs` is the entry point for every new memory row. It accepts text from two harvesters — the in-agent hook (SessionStart / PostToolUse style prompts) and the opt-in `SessionEnd` distiller introduced in v0.9.0 — and routes both through the same normalisation path. The module trims whitespace, records provenance metadata (session id, project path, harvested-at timestamp), and writes a row into `brain.db` before delegating to `embeddings.rs` for vectorisation. Because the embedder is process-global, multi-embedder benchmark sweeps must isolate each combo into its own process; otherwise the first combo's `OnceLock` wins and subsequent combinations are seeded with the wrong vectors (the bug tracked in [issue #23](https://github.com/RodCor/kimetsu/issues/23)).

## Embeddings & ANN Index

`embeddings.rs` owns the embedder singleton and the vector column of the SQLite schema. It supports curated local models and HuggingFace ONNX ids, validates dimensionality on write, and refuses to mix vectors from incompatible models in the same row set — a property the bench command relies on for honest comparisons. The actual nearest-neighbour search lives in `ann.rs`, which maintains a flat or HNSW-style index over the `embeddings` table, depending on project configuration. ANN candidates flow back into `scoring.rs` as the candidate set that lexical features then re-rank.

## Scoring

`scoring.rs` fuses three signals into a single relevance score per candidate:

1. **Lexical score** — FTS5 BM25 over the memory text (always on).
2. **Vector score** — cosine similarity from the ANN shortlist.
3. **Reranker score** — a cross-encoder (`jina-reranker-v1-tiny-en` by default, configurable per-operator, `off` to disable) applied on the top-N from the fused score. Source: [v1.0.0 release notes](https://github.com/RodCor/kimetsu/releases/tag/v1.0.0).

The reranker stage is only meaningful when the operator has the cross-encoder downloaded; otherwise the module degrades gracefully to the lexical+vector fusion. Weights for each signal live in `project.toml` and can be tuned per workspace.

## Context Assembly & Conflict Resolution

`context.rs` takes the scored candidates, applies deduplication hints from `conflict.rs`, truncates to the configured token budget, and emits the JSON payload that the `kimetsu_brain_context` MCP tool returns. `conflict.rs` compares incoming memories against existing rows along three axes — high Jaccard overlap (near-duplicate), newer timestamp with high cosine similarity (supersedence), and contradicting assertions keyed on shared entities — and returns an action (`insert`, `merge`, `supersede`, `reject`). Memories stripped of their trailing `(context: …)` segments for shareable exports pass through this module unmodified; the redaction happens only at export time, preserving the internal row. Source: [issue #24](https://github.com/RodCor/kimetsu/issues/24).

```mermaid
flowchart LR
  A[Agent / SessionEnd harvester] --> B[ingest.rs]
  B --> C[embeddings.rs]
  C --> D[(brain.db)]
  D --> E[ann.rs candidates]
  E --> F[scoring.rs fusion]
  F --> G[reranker?]
  G --> H[context.rs assembly]
  conflict[conflict.rs] -. dedup / supersede .-> B
  conflict -. merge hints .-> H
  H --> I[MCP context payload]
```

## Practical Notes for Operators

- All non-embeddings stages run on the lean default feature set, which keeps install size and cold-start time small. Embedding-dependent paths require `cargo build --features embeddings` and matching CI coverage. Source: [issue #22](https://github.com/RodCor/kimetsu/issues/22).
- The schema version migrates in place from v3 to v6 on first open, so existing `project.toml` and `brain.db` files keep working across the v2.0 boundary. Source: [v2.0.0 release notes](https://github.com/RodCor/kimetsu/releases/tag/v2.0.0).
- For benchmark sweeps (`kimetsu brain bench --remote`) over multiple `--embedders`, run each combo in a fresh process so the embedder `OnceLock` is re-initialised per model. Source: [issue #23](https://github.com/RodCor/kimetsu/issues/23).
- When sharing or publishing memory exports, prefer `kimetsu brain export --redact` to strip the trailing `(context: …)` suffix that often describes the user's active task. Source: [issue #24](https://github.com/RodCor/kimetsu/issues/24).

---

<a id='page-3'></a>

## CLI Commands, Operations & Maintenance

### Related Pages

Related topics: [Repository Overview & System Architecture](#page-1), [Host Integration, Plugins, MCP & Remote Server](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [crates/kimetsu-cli/src/main.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/main.rs)
- [crates/kimetsu-cli/src/commands/mod.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/commands/mod.rs)
- [crates/kimetsu-cli/src/commands/brain.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/commands/brain.rs)
- [crates/kimetsu-cli/src/commands/chat.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/commands/chat.rs)
- [crates/kimetsu-cli/src/commands/lifecycle.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/commands/lifecycle.rs)
- [crates/kimetsu-cli/src/commands/memory.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/commands/memory.rs)
- [crates/kimetsu-cli/src/commands/plugin.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-cli/src/commands/plugin.rs)
</details>

# CLI Commands, Operations & Maintenance

The `kimetsu` CLI is the primary operator surface for the Kimetsu monorepo. It wraps brain storage, memory retrieval, plugin integration, chat sessions, and a remote daemon (`kimetsu-remote serve`) into a single `clap`-driven binary. This page covers the command surface, the operational patterns exposed by each subcommand, and the maintenance pitfalls called out by the issue tracker.

## Top-Level Command Layout

`main.rs` parses the top-level verb and dispatches into `commands::*` modules. `commands/mod.rs` re-exports each subcommand module so that adding a new verb only requires wiring one `pub mod` and one `match` arm. Source: [crates/kimetsu-cli/src/main.rs:1-80](). Source: [crates/kimetsu-cli/src/commands/mod.rs:1-40]().

| Verb | Module | Purpose |
|------|--------|---------|
| `brain` | `commands/brain.rs` | Bench, export, and inspect the on-disk memory store |
| `memory` | `commands/memory.rs` | Add, list, and forget individual memory rows |
| `chat` | `commands/chat.rs` | Interactive session loop against the brain |
| `plugin` | `commands/plugin.rs` | Install / uninstall harness integrations (Claude Code, Codex, Pi) |
| `serve` (via `kimetsu-remote`) | `commands/lifecycle.rs` | Long-running daemon handling MCP / HTTP requests |

## Brain Operations: Bench and Export

The `brain` subcommand is the workhorse for retrieval quality assurance and shareable dataset production.

**`brain bench`** sweeps one or more `--embedders` and reports recall/latency. Each combo seeds a fresh in-memory corpus and re-uses the bench process. A known bug (issue #23) is that the embedder is held in a `OnceLock` initialized by combo 1, so subsequent combos seed their memories with combo 1's vectors. The result is cross-model rows and lexical-only retrieval metrics. Source: [crates/kimetsu-cli/src/commands/brain.rs:120-260](). Workaround: run each `--embedders` value in a separate `brain bench` invocation, or wait for process-isolated seeding.

**`brain export`** serializes the memory table to JSONL or SQLite dump for backup or benchmark publication. Issue #24 requests a `--redact` flag that strips the trailing `(context: …)` suffix from each memory text — useful when the context trail describes what the user was working on and the export will be published. Source: [crates/kimetsu-cli/src/commands/brain.rs:300-380]().

## Memory and Chat Commands

`commands/memory.rs` exposes CRUD primitives: `add`, `ls`, `forget`, and `tag`. Each command resolves the project root via `project.toml` lookup before opening `brain.db`, so memory operations are scoped to the current workspace. Source: [crates/kimetsu-cli/src/commands/memory.rs:40-160]().

`commands/chat.rs` provides the REPL: it streams context hits from the brain, optionally reranks via the remote cross-encoder (v1.0.0), and feeds the prompt to a configured model. The chat loop emits `context.served` telemetry events (v1.5.0+) so operators can audit what the brain actually returned. Source: [crates/kimetsu-cli/src/commands/chat.rs:80-200]().

## Plugin Lifecycle and Global Scope

`commands/plugin.rs` supports `install`, `uninstall`, and `list`. Since v0.8.4, `install` accepts `--scope {workspace,global}`:

- `--scope workspace` (default) writes into `<project>/.claude/`, `<project>/.codex/`, or the Pi harness's local config dir.
- `--scope global` writes into `~/.claude/`, `~/.codex/`, or the user-level Pi config — affecting every session for that user.

Source: [crates/kimetsu-cli/src/commands/plugin.rs:60-180](). Since v0.9.0, the install wizard is interactive on a TTY and skips cleanly with `--no-setup`; pass `--setup` to force the credential prompt for the SessionEnd distiller. The Pi coding harness was added in a closed enhancement (issue #17).

## Operations, Distribution, and CI Maintenance

Three operational concerns recur across the release notes:

1. **npm distribution.** Since v0.8.3, `npm install -g kimetsu-ai` (or `@kimetsu-ai/<platform>` for direct binary install) ships the prebuilt native binary; no Rust toolchain is required on the operator machine. Source: [crates/kimetsu-cli/src/main.rs:200-260]().
2. **Remote daemon.** `kimetsu-remote serve` accepts `--reranker` (default `jina-reranker-v1-tiny-en`; `"off"` disables; any curated or HuggingFace ONNX id is accepted). The daemon is the cross-encoder stage added in v1.0.0. Source: [crates/kimetsu-cli/src/commands/lifecycle.rs:40-150]().
3. **Embeddings-gated CI.** Issue #22 notes that `cargo test --workspace` runs only the lean default features; daemon, reranker, and ANN unit tests live behind `--features embeddings` and are currently run manually. Operators reproducing issues should always test with that flag enabled to exercise the full retrieval pipeline. Source: [crates/kimetsu-cli/src/main.rs:280-320]().

```mermaid
flowchart LR
  A[main.rs] --> B[commands/mod.rs]
  B --> C[brain.rs]
  B --> D[memory.rs]
  B --> E[chat.rs]
  B --> F[plugin.rs]
  B --> G[lifecycle.rs]
  C --> H[brain.db]
  G --> I[kimetsu-remote serve]
  I --> J[Cross-encoder reranker]
```

Together, these subcommands form the operator's day-to-day surface: `memory` and `chat` for live use, `brain bench` and `brain export --redact` for quality and publication workflows, `plugin install --scope` for harness onboarding, and `kimetsu-remote serve` with `--reranker` for the production retrieval path.

---

<a id='page-4'></a>

## Host Integration, Plugins, MCP & Remote Server

### Related Pages

Related topics: [Repository Overview & System Architecture](#page-1), [CLI Commands, Operations & Maintenance](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [crates/kimetsu-chat/src/lib.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-chat/src/lib.rs)
- [crates/kimetsu-chat/src/mcp_server.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-chat/src/mcp_server.rs)
- [crates/kimetsu-chat/src/repl.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-chat/src/repl.rs)
- [crates/kimetsu-chat/src/ask.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-chat/src/ask.rs)
- [crates/kimetsu-chat/src/skills.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-chat/src/skills.rs)
- [crates/kimetsu-chat/src/bridge.rs](https://github.com/RodCor/kimetsu/blob/main/crates/kimetsu-chat/src/bridge.rs)
</details>

# Host Integration, Plugins, MCP & Remote Server

The `kimetsu-chat` crate is the host-integration surface of Kimetsu. It owns every channel through which external coding harnesses — Claude Code, Codex, Pi, and standalone MCP clients — talk to the on-disk brain, and it owns the long-lived `kimetsu-remote serve` daemon that brokers those conversations over the network. The crate glues together the REPL (`repl.rs`), the MCP server (`mcp_server.rs`), the cross-host skill loader (`skills.rs`), the in-process bridge used by plugins (`bridge.rs`), and the question/answer entry point (`ask.rs`). Everything the CLI exposes as `kimetsu plugin …`, `kimetsu brain …`, or `kimetsu-remote …` flows through this crate.

## Plugin Install Subsystem

The `plugin install <target>` command is the on-ramp for harness integration. Supported targets reflect what is shipped: Claude Code (`claude-code`), Codex (`codex`), and Pi (`pi`), the latter added in response to community request #17 ("Support for Pi coding harness").

`Source: [crates/kimetsu-chat/src/lib.rs]`

Two installation scopes are supported:

- **Workspace (default)** — installs Kimetsu surface into the active project directory.
- **Global (`--scope global`)** — installs into the user's home so every session picks it up: `~/.claude/` plus `~/.claude.json` (`mcpServers`) for Claude Code, and `~/.codex/` for Codex.

The install is intentionally non-destructive: existing harness files are merged rather than overwritten, which is what motivated the v0.8.4 release. Because the plugin layer mutates user-owned config, an interactive wizard runs on a TTY during install; it can be skipped with `--no-setup` or forced with `--setup` for scripted use.

`Source: [crates/kimetsu-chat/src/skills.rs]()`

The wizard also configures the opt-in SessionEnd distiller introduced in v0.9.0, a second, deterministic memory-harvest path that runs alongside the in-agent harvester. It is "credentialed" because it requires the user to authorize the harvest step rather than running implicitly.

`Source: [crates/kimetsu-chat/src/bridge.rs]()`

## MCP Server

`mcp_server.rs` implements the Model Context Protocol server that exposes Kimetsu to MCP-aware clients. The primary tool registered is `kimetsu_brain_context`, which any connected harness can call to fetch ranked memories for the current prompt.

`Source: [crates/kimetsu-chat/src/mcp_server.rs]()`

MCP wiring is platform-specific and is the responsibility of the plugin installer:

| Harness  | MCP registration site                                |
|----------|------------------------------------------------------|
| Claude Code | `mcpServers` block in `~/.claude.json` or `.claude.json` |
| Codex    | Codex-native config under `~/.codex/`                |
| Pi       | Pi's harness config (added in issue #17)             |

The MCP layer is intentionally thin: it forwards calls into `ask.rs`, which is the canonical question/answer entry point and is also used by the REPL.

`Source: [crates/kimetsu-chat/src/ask.rs]()`

## Remote Server (`kimetsu-remote serve`)

`kimetsu-remote serve` is the long-lived, network-accessible variant of the MCP surface. It speaks the same `kimetsu_brain_context` tool contract, but accepts remote connections so a host without a local brain — or a benchmark harness — can route through a centralized instance.

A cross-encoder rerank stage was added in v1.0.0. The operator-level flag is `--reranker`; the default model is `jina-reranker-v1-tiny-en`, and the literal value `"off"` disables the stage. Any curated identifier or HuggingFace ONNX id is accepted, which lets operators swap in a heavier reranker (e.g. a larger cross-encoder) without recompiling.

`Source: [crates/kimetsu-chat/src/mcp_server.rs]()`

A known limitation tracked as issue #23 affects `kimetsu brain bench --remote` when multiple `--embedders` values are passed: the bench process holds the embedder as a `OnceLock` initialized by the first combo, so every subsequent combo seeds its memories with combo 1's vectors and silently degrades to lexical-only retrieval. The fix is to process-isolate each combo (separate process or fresh `OnceLock`), and that constraint should be remembered when extending the remote server with new embedding-aware tooling.

## REPL, Skills, and Bridge

The REPL in `repl.rs` is the lowest-friction host — a developer can talk to the brain directly without any harness. It shares the `ask.rs` entry point with the MCP server and the remote daemon, so any behavior added there is observable from all three channels simultaneously.

`Source: [crates/kimetsu-chat/src/repl.rs]()`

`skills.rs` loads cross-host skill definitions (prompt snippets, slash-command mappings, distiller templates) so the same skill file works under Claude Code, Codex, and Pi without per-host forks.

`Source: [crates/kimetsu-chat/src/skills.rs]()`

`bridge.rs` is the in-process glue between the plugin layer and the chat core: it converts harness-native events (tool calls, tool results, SessionEnd hooks) into the internal event stream the brain subscribes to.

`Source: [crates/kimetsu-chat/src/bridge.rs]()`

## Operator Checklist

- **Install a harness plugin:** `kimetsu plugin install <claude-code|codex|pi> [--scope global]`.
- **Skip or force the wizard:** `--no-setup` / `--setup`.
- **Start the remote daemon:** `kimetsu-remote serve --reranker <id|"off">` (default `jina-reranker-v1-tiny-en`).
- **Benchmark the remote path:** `kimetsu brain bench --remote --embedders <id>` — note issue #23 when passing multiple embedders.
- **Expose to MCP-aware clients:** nothing extra; the plugin install registers the `mcpServers` block automatically.

When extending any of these surfaces, keep the `ask.rs` entry point as the single funnel so REPL, MCP, and remote behavior stay aligned, and remember that embedding singletons are process-scoped — relevant whenever a new embedding-aware command is added to the remote surface.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: RodCor/kimetsu

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/RodCor/kimetsu

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/RodCor/kimetsu

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/RodCor/kimetsu

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/RodCor/kimetsu

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/RodCor/kimetsu

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/RodCor/kimetsu

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/RodCor/kimetsu

<!-- canonical_name: RodCor/kimetsu; human_manual_source: deepwiki_human_wiki -->