Related Pages

Related topics: Memory Pipeline, Retrieval & Scoring, CLI Commands, Operations & Maintenance, Host Integration, Plugins, MCP & Remote Server

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 [email protected] on crates.io. Source: Cargo.toml:1-80 and release notes for v1.5.1.

The principal crates are:

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

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*.

Related Pages

Related topics: Repository Overview & System Architecture, CLI Commands, Operations & Maintenance

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

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.

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).

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.

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.

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.
• 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.
• 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.
• 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.

Related Pages

Related topics: Repository Overview & System Architecture, Host Integration, Plugins, MCP & Remote Server

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.

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.

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.

Related Pages

Related topics: Repository Overview & System Architecture, CLI Commands, Operations & Maintenance

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:

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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/RodCor/kimetsu

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/RodCor/kimetsu

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/RodCor/kimetsu

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/RodCor/kimetsu

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/RodCor/kimetsu

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/RodCor/kimetsu

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/RodCor/kimetsu

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using kimetsu with real data or production workflows.

• bench: process-isolate seeding in --remote mode (multi-embedder invocati - github / github_issue
• brain export --redact: strip context trails for shareable exports - github / github_issue
• CI: run the embeddings-gated test suites - github / github_issue
• Support for Pi coding harness - github / github_issue
• v2.5.0 - github / github_release
• v2.0.0 - github / github_release
• v1.5.1 - github / github_release
• v1.5.0 - github / github_release
• v1.0.0 - github / github_release
• v0.9.0 - github / github_release
• v0.8.4 - github / github_release
• v0.8.3 - github / github_release