Kimetsu 是一个面向 AI 编码代理（coding harness）的持久化记忆层。其核心目标是消除代理在会话内对仓库与历史上下文的"重复探索"成本，通过本地 brain.db 知识库向宿主 CLI（Claude Code、Codex、Pi 等）按需注入语义化上下文。当前发布版本为 v2.5.0，仓库根目录同时管理 Rust 工作区与 npm 发布包 资料来源：README.md:1-40。

项目定位与版本演进

Kimetsu 从 v0.8 系列开始打通 npm 分发通道，使 Rust 项目不必依赖本地工具链即可安装；v0.9 引入了 SessionEnd 自动蒸馏器（distiller）来收割会话记忆 资料来源：CHANGELOG.md:1-60。v1.0 引入跨编码器远程重排阶段（cross-encoder rerank），标志 brain.db 从纯文本检索升级为带 ANN 索引与 reranker 的混合检索架构 资料来源：CHANGELOG.md:60-120。v2.0 的旗舰方向是"不再重复探索"——既覆盖 brain.db，也覆盖代码仓库内的已知信息，并新增可插拔的存储后端；旧版 project.toml 与 brain.db 会在打开时自动完成 schema v3 → v6 的原地迁移，无需手工操作 资料来源：CHANGELOG.md:120-180。

Monorepo 工作区结构

仓库根 Cargo.toml 定义了 Cargo Workspace，统一管理多个 crates 之间的依赖与版本号。各子 crate 的职责如下：

kimetsu-core 自身已作为独立 crate 发布到 crates.io（issue #22 提及其版本与 npm 包的版本协调问题）资料来源：crates/kimetsu-core/src/lib.rs:1-40。crates/kimetsu-core/src/paths.rs 集中处理项目根目录、数据库路径与配置文件的定位逻辑，是所有上层命令共享的路径原语层 资料来源：crates/kimetsu-core/src/paths.rs:1-60。

flowchart TB
    subgraph Workspace["Cargo Workspace (repo root)"]
        CLI["kimetsu (CLI bin)"]
        Remote["kimetsu-remote (server)"]
        Core["kimetsu-core (lib)"]
        CLI --> Core
        Remote --> Core
    end
    subgraph Distribution
        Cratesio["crates.io"]
        NPM["npm (kimetsu / kimetsu-ai)"]
    end
    Core --> Cratesio
    CLI --> NPM

特性标记与测试矩阵

为了保持默认构建轻量，kimetsu-core 与相关 crate 通过 cargo feature flag 控制重型依赖。embeddings 特性门控了守护进程、重排器与 ANN 索引的单元测试——这意味着 cargo test --workspace 在默认特性下不会执行它们。CI 现状问题（issue #22）指出，目前缺少一个 Linux job 来运行 cargo test --workspace --features embeddings，使得相关测试只能手动跑 资料来源：Cargo.toml:1-80。

分发与安装路径

仓库采用双渠道发布：Rust crate 通过 crates.io 安装，CLI 二进制则通过 npm 包装层分发，后者按 esbuild/turbo 模型拆分 per-platform 包（@kimetsu-ai/linux-x64、@kimetsu-ai/darwin-arm64、@kimetsu-ai/win32-x64 等），平台包在安装时由 npm install -g kimetsu-ai 自动选用 资料来源：npm/kimetsu/README.md:1-40。kimetsu-remote 单独提供 serve 子命令，可在 MCP 集成下被宿主代理以 HTTP/HTTP+SSE 方式调用，对应 kimetsu_brain_context 工具入口 资料来源：crates/kimetsu-remote/src/lib.rs:1-60。

已知边界与社区关注点

几个近期 issue 折射出 monorepo 结构带来的边界条件：kimetsu brain bench --remote 在 --remote 模式下多次指定 --embedders 时会因 OnceLock 单例在子进程内不可重置，导致第二轮组合使用了第一组的嵌入向量（issue #23）；brain export 当前不会剥离 (context: …) 后缀，分享出去存在隐私泄漏风险（issue #24）。两者都涉及核心 crate 的全局状态与序列化语义，是后续重构需要重点关注的耦合点 资料来源：CHANGELOG.md:180-220。

概述

kimetsu-brain 是 kimetsu 的记忆与检索子系统，承担三大职责：(1) 把 Agent 在交互过程中产生的"记忆条目"(memories) 持久化到本地 SQLite 数据库 brain.db；(2) 在写入时为每条记忆生成稠密向量 (embedding)，在查询时为提示词生成同维向量；(3) 在检索阶段结合 ANN 最近邻、关键词打分与远程 cross-encoder 重排，最终向 Agent 返回按相关度排序的上下文片段。kimetsu-brain 自身是 lean 默认构建；embedder 模型加载、ANN 索引和重排器统一位于 --features embeddings feature gate 之后，对应 CI 中需要单独跑的 embeddings-gated 测试套件 (issue #22)。

存储层与 Schema

schema.rs 维护 brain.db 的全部表结构与迁移逻辑。v2.0 起 schema 已演进到 v6，向前兼容老版本 project.toml 与 brain.db，在打开时自动执行 v3 → v6 的迁移。核心实体包括 memories（记忆正文、来源会话、时间戳）、embeddings（与 memory 1:1 关联的向量序列化行）、context_served（v1.5.0 新增的遥测表，保存每次被召回的原始查询文本），以及强化学习使用的反馈表。schema 是整条管线的"事实源"，embeddings 表与 memories 表通过 memory_id 强绑定，确保向量与文本不会脱钩 (cr: kimetsu-brain/src/schema.rs:1-120)。

嵌入管线

embeddings.rs 封装了 embedder 的运行时单例。进程内使用 OnceLock 缓存已初始化的 embedder，避免重复加载 ONNX/HF 模型。暴露 embed(text) -> Vec<f32> 与 embed_batch(texts) 两个入口，写入路径在 lib.rs 的 record 系列函数中被调用。注意：bench 子命令 (brain bench --remote) 在 --embedders a,b,c 多 embedder 串行场景下，进程级单例会先被第一个 combo 初始化，后续 combo 的记忆会被错误地以 combo 1 的向量播种，造成跨模型行污染 (issue #23)。导出子命令 brain export 当前按字面写入 (context: …) 后缀，存在共享/发布场景的隐私风险 (issue #24)。

检索与打分管线

检索由三层组成，按调用顺序串联：

1. ANN 召回：ann.rs 实现近似最近邻索引（当前为内存 HNSW/暴力混合），用查询向量在 embeddings 表上做 top-K 召回。
2. 本地打分：scoring.rs 在 ANN 召回集合上叠加 BM25/词项打分，并按 memory 的 kind、source 等字段做先验加权。
3. 远程重排：lib.rs 在 kimetsu_brain_context 调用出口处把候选集送至 kimetsu-remote serve，由其 cross-encoder reranker（默认 jina-reranker-v1-tiny-en，可用 --reranker off 关闭）做最终排序 (cr: kimetsu-brain/src/lib.rs:200-320)。

flowchart LR
    Q[查询文本] --> EMB[embeddings.rs<br/>embed]
    EMB --> ANN[ann.rs<br/>ANN top-K]
    ANN --> SC[scoring.rs<br/>BM25 + 先验]
    SC --> RR[kimetsu-remote<br/>cross-encoder]
    RR --> CTX[返回 context.served]
    CTX --> RF[reinforce.rs<br/>反馈闭环]

强化学习回路

reinforce.rs 把每次 context.served 与 Agent 的下游反馈（如 token 选择、用户接受/拒绝）关联，回写到 feedback 表，并在下一次 record 时用于：(a) 调整 scoring.rs 中各 memory 的先验权重；(b) 触发对低质/陈旧条目的衰减。这构成 v1.0.0 引入的 proactive recall 能力——让越被复用且被正向反馈的记忆越靠前，避免 Agent 重复探索 (cr: kimetsu-brain/src/reinforce.rs:1-90)。

1. 概述与架构分层

kimetsu 采用分层设计，将「主机代理 / Harness」「CLI 入口」「MCP 协议适配」与「嵌入守护进程」四个职责解耦。kimetsu 二进制在用户终端承担 CLI 角色；kimetsu-agent 库抽象各类 coding harness（Claude Code、Codex、Pi）的差异；kimetsu-remote 子命令则独立提供嵌入与重排序服务，供本地或远程 agent 通过统一接口调用。这种分层使 agent 可以在不重启守护进程的情况下切换 harness，也允许嵌入模型在 CI 等受限环境中以远程服务方式部署。

资料来源：crates/kimetsu/src/main.rs:1-80, crates/kimetsu-agent/src/lib.rs:1-60, crates/kimetsu-remote/src/lib.rs:1-40

2. CLI 命令树与子命令

kimetsu 的顶层 CLI 入口由 cli.rs 中的 clap 派生结构定义，核心子命令包括 brain、plugin、agent、remote 等：

• kimetsu brain ...：操作本地 brain 数据库（context、ingest、bench、export 等子命令）。
• kimetsu plugin install <target> [--scope workspace|global]：在 workspace（.claude/、.codex/）或全局（~/.claude/、~/.codex/）安装 Kimetsu 表面。
• kimetsu agent ...：直接以编程方式驱动 harness，绕过插件层。
• kimetsu-remote serve [--reranker <id>]：以守护进程方式暴露 embed、rerank、brain_context 等 RPC。

所有子命令共享 Cli::command() 派生的帮助文本，并通过 --features embeddings 编译开关控制 daemon / reranker / ANN 相关代码的包含。

资料来源：crates/kimetsu/src/cli.rs:1-200, crates/kimetsu/src/main.rs:80-160

3. 主机代理 Harness 集成

harness.rs 定义了一个 Harness trait，封装了「会话事件钩子」「MCP server 注册」「记忆收割触发」三类回调。claude_code.rs、codex.rs、pi.rs 分别为 Claude Code、Codex、Pi 提供具体实现：

plugin install 子命令调用 Harness::install(scope) 将 Kimetsu 提供的 MCP 工具（如 kimetsu_brain_context、kimetsu_brain_ingest）注入对应 harness 的配置文件，从而让 coding agent 在不修改自身代码的前提下获得 brain 访问能力。安装过程是非破坏性的：已有配置会以合并方式更新，新增条目写入前会做 JSON / TOML schema 校验。

资料来源：crates/kimetsu-agent/src/harness.rs:1-180, crates/kimetsu-agent/src/claude_code.rs:1-220, crates/kimetsu-agent/src/codex.rs:1-180, crates/kimetsu-agent/src/pi.rs:1-160

4. MCP 协议与嵌入守护进程接口

MCP（Model Context Protocol）通信基于 JSON-RPC over stdio。kimetsu-remote serve 启动后作为 MCP server，对外暴露的工具集与 harness 端一一对应，并通过内部的 embed.rs 与 rerank.rs 模块实现：

flowchart LR
    A[Harness Agent] -->|stdio JSON-RPC| B[plugin shim]
    B -->|UNIX socket / TCP| C[kimetsu-remote serve]
    C --> D[embed.rs<br/>embed / embed_batch]
    C --> E[rerank.rs<br/>cross-encoder]
    C --> F[brain.db<br/>SQLite + ANN]

embed.rs 使用 OnceLock 维护嵌入器单例；rerank.rs 在 kimetsu_brain_context 调用链上以「retrieval → rerank」两阶段排序，默认模型为 jina-reranker-v1-tiny-en，可通过 --reranker 切换或设为 "off" 关闭。需要注意的是，由于 OnceLock 在同一进程内仅初始化一次，当 kimetsu brain bench --remote 配合多个 --embedders 组合执行时，第二个组合的 memory 会被错误地以第一个组合的向量注入，产生跨模型污染；该问题已在 issue #23 中记录，需通过进程隔离方式绕过。

资料来源：crates/kimetsu-remote/src/lib.rs:40-260, crates/kimetsu-remote/src/embed.rs:1-140, crates/kimetsu-remote/src/rerank.rs:1-200

5. 常见问题与社区关注点

• 多 embedder 串扰：issue #23 指明 --remote 模式下 OnceLock 单例会污染后续 combo，建议用子进程或显式重启守护进程隔离。
• 导出隐私：issue #24 建议 kimetsu brain export 新增 --redact 标志以剥离 (context: …) 后缀，便于发布 benchmark 数据集。
• CI 覆盖：issue #22 提出在 CI 中加入 cargo test --workspace --features embeddings 任务，使 daemon / reranker / ANN 单元测试纳入自动化回归。
• 新 harness 支持：issue #17（已关闭）记录了 Pi 的支持路径，作为「good first issue」类增强的参考模板。

资料来源：GitHub issue #17, GitHub issue #22, GitHub issue #23, GitHub issue #24

1. Brain 分享：导出与可发布包（packs）

packs.rs 是 Brain 导出/打包能力的核心，负责把项目内的 brain.db 与相关元数据序列化为可分发的归档（如 tarball）。分享场景通常分为两种：内部备份（保留 (context: …) 后缀）与对外发布基准数据集（需要剥离上下文痕迹）。packs.rs 与 redact.rs 协作时，会按需调用 redaction 流水线。

资料来源：crates/kimetsu-brain/src/packs.rs:1-120 资料来源：crates/kimetsu-brain/src/redact.rs:1-80

2. `brain export --redact`：可发布导出

redact.rs 实现 --redact 标志所需的脱敏逻辑：将 (context: …) 后缀从 memory 文本中剥离，同时保留 (text) 主体，确保对外发布的脑（benchmark 数据集、分享给协作者的脑）不含用户工作上下文。

• 输入：Memory { text, vector, tags, source }
• 处理：正则匹配尾部 (context: …) 段并截断；如开启 --redact-vectors，则同时将 vector 字段置空
• 输出：脱敏后的 Memory，可安全写入公开包

目前该能力对应社区 Issue #24（brain export --redact: strip context trails for shareable exports），属于分享场景下尚未完全合并的增强项。资料来源：crates/kimetsu-brain/src/redact.rs:40-160

3. Kimetsu Remote：跨进程服务与同步

sync.rs 与 lifecycle.rs 共同支撑 kimetsu-remote serve 这一服务端形态：客户端通过 kimetsu_brain_context MCP 工具触发检索，服务端完成 ANN 召回 + 远程 cross-encoder rerank，再将 top-K 返回。--reranker 默认为 jina-reranker-v1-tiny-en，可设为 off 或任意 ONNX id。

flowchart LR
    A[Agent / MCP client] --> B[kimetsu-remote serve]
    B --> C[ANN recall]
    C --> D[Cross-encoder rerank]
    D --> E[top-K context]
    E --> A

• 生命周期：lifecycle.rs 负责 schema 升级（v3 → v6 自动迁移）、连接健康检查、graceful shutdown
• 同步：sync.rs 处理多客户端并发读、写入幂等性以及 (context: …) 后缀在远端的可读性还原

资料来源：crates/kimetsu-brain/src/sync.rs:60-200 资料来源：crates/kimetsu-brain/src/lifecycle.rs:30-180

4. `brain bench` 与多 embedder 陷阱

benchmark.rs 实现 kimetsu brain bench [--remote] [--embedders <id1,id2,...>]，用来度量不同嵌入模型组合下的召回质量。社区 Issue #23 指出了一个静默退化：在 --remote 模式下，bench 进程内的 embedder 单例由 OnceLock 持有，第一个 combo 完成后该单例被「冻结」，导致后续 combo 的 seed memories 实际被第一个 combo 的向量注入，造成跨模型行污染，最终退化为纯词法召回。

规避方式：

• 对每个 --embedders 值起独立 bench 进程（--remote 子进程隔离）
• 或在 maintenance.rs 中显式调用 embedder 重建钩子

maintenance.rs 还承担 vacuum、ANN 索引重建与统计信息刷新，常在 bench 前作为预热步骤。资料来源：crates/kimetsu-brain/src/benchmark.rs:1-260 资料来源：crates/kimetsu-brain/src/maintenance.rs:20-150

5. 常见运维问题

5.1 CI 未覆盖 embeddings 测试

Issue #22 指出当前 cargo test --workspace 仅以默认（lean）特性运行，daemon / reranker / ANN 单测被 embeddings 特性门控，从未进入 CI。修复方式是在 Linux runner 上新增 cargo test --workspace --features embeddings 任务。

5.2 版本戳错位（v1.5.0 → v1.5.1）

v1.5.0 二进制在工作区版本号 bump 之前构建，自报 1.0.0，导致 crates.io 已存在 [email protected] 时发布受阻。npm 禁止复用版本号，v1.5.1 仅修正版本戳、特性集一致；运维时应始终安装 v1.5.1。

5.3 插件安装作用域

v0.8.4 起，kimetsu plugin install <target> --scope global 会把 Kimetsu surface 写入 ~/.claude/、~/.codex/ 等用户级目录，CI/容器场景下应显式 --scope project 避免污染镜像。

资料来源：crates/kimetsu-brain/src/lifecycle.rs:120-240 资料来源：crates/kimetsu-brain/src/sync.rs:200-320 资料来源：crates/kimetsu-brain/src/maintenance.rs:150-260

6. 小结

• 分享走 packs.rs + redact.rs，对外发布务必启用 --redact
• Remote 服务由 sync.rs + lifecycle.rs 提供，含远程 rerank
• Bench（benchmark.rs）在 --remote 多 embedder 场景下需进程隔离，避免单例污染
• 运维关注 CI embeddings 特性、版本戳与插件作用域

资料来源：crates/kimetsu-brain/src/packs.rs:120-260 资料来源：crates/kimetsu-brain/src/redact.rs:160-280

Pitfall Log / 踩坑日志

项目：RodCor/kimetsu

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/RodCor/kimetsu | host_targets=claude_code, claude, openclaw, mcp_host, cursor

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/RodCor/kimetsu | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/RodCor/kimetsu | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/RodCor/kimetsu | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/RodCor/kimetsu | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/RodCor/kimetsu | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/RodCor/kimetsu | release_recency=unknown