项目简介

mentedb-mcp 是一个基于 Rust 实现的 Model Context Protocol（MCP） 服务器，其核心目标是为 LLM 智能体（例如 Claude Code、Claude Desktop、Cursor 等）提供长期记忆、知识图谱与上下文检索能力。仓库在 Cargo.toml 中将自身定位为 MCP 服务器二进制，并通过 rmcp ~1.3 与 rmcp-macros 1.3.0 这两个 crate 接入 MCP 协议。资料来源：Cargo.toml:1-40

服务器后端复用 mentedb 系列 crate（v0.5.6 时已升级至 mentedb = 0.10.0），该后端负责记忆存储、HNSW 索引、图谱遍历、enrichment（社区发现与用户建模）等能力。MCP 层仅负责把这些能力以 #[tool] 形式暴露给宿主 Agent。

核心能力与运行模式

mentedb-mcp 提供两类运行模式，可在编译期通过 Cargo feature 切换：

自 v0.5.6 起，local 模式成为默认出货模式，普通用户无需额外 feature flag 即可启动本地守护进程。资料来源：Cargo.toml:20-60、README.md:30-80

MCP 工具集合主要包括：

• store_memory：写入记忆；v0.5.6 起新增 scope 参数，用于区分用户/会话/全局作用域。
• recall_memories：基于 HNSW 的近似最近邻检索（v0.4.24 由 O(n) 全表扫描迁移而来）。
• process_turn：调用 engine 端的 process_turn，封装 sleeptime enrichment 与矛盾检测（v0.5.2 起替换了约 820 行手动编排逻辑）。
• run_enrichment：触发 Phase 3（社区发现）与 Phase 4（用户建模）流水线（v0.5.4 接入）。

资料来源：src/server.rs:1-200、src/main.rs:1-120、README.md:90-160

安装与编译

仓库是标准 Cargo 工程，根目录下执行下列命令即可完成 release 编译：

git clone https://github.com/nambok/mentedb-mcp.git
cd mentedb-mcp
cargo build --release

编译产物位于 target/release/mentedb-mcp（二进制名称取决于 [[bin]] 配置）。如需连接云端后端，可省略 --features local，此时服务器将以 client 模式启动并通过 MENTEDB_REMOTE_URL 等环境变量连接到外部服务。资料来源：Cargo.toml:40-80、src/config.rs:1-80

注意：v0.5.0/v0.4.26 曾要求显式固定 rmcp ~1.3 与 rmcp-macros 1.3.0 才能成功通过 --features local 编译；现行主分支已将该约束写入 Cargo.toml，无需手动指定版本。

MCP 客户端配置示例

仓库在 examples/ 目录中提供了两种主流宿主软件的接入样例。

Claude Desktop

{
  "mcpServers": {
    "mentedb": {
      "command": "/absolute/path/to/mentedb-mcp",
      "args": [],
      "env": {
        "MENTEDB_MODE": "local",
        "MENTEDB_DATA_DIR": "/Users/you/.mentedb"
      }
    }
  }
}

资料来源：examples/claude_desktop_config.json:1-20

Cursor

{
  "mcpServers": {
    "mentedb": {
      "command": "mentedb-mcp",
      "args": ["--features", "local"]
    }
  }
}

资料来源：examples/cursor_mcp.json:1-15

部署与生命周期

最新版本（v0.5.7）增加了 Claude Code 的 lifecycle hook 集成，使本地守护进程与云端后端都能在 Agent 会话开始/结束时被自动调用。src/daemon.rs 中实现了守护进程的事件循环，负责在 MCP process_turn 之后异步触发 enrichment，并在进程退出前刷新索引。资料来源：src/daemon.rs:1-150、README.md:160-220

flowchart LR
  Host[Claude Code / Claude Desktop / Cursor] -->|MCP stdio| Server[mentedb-mcp]
  Server -->|Arc<MenteDb>| Engine[mentedb engine]
  Engine -->|WAL| LocalDB[(本地 SQLite)]
  Engine -.->|HTTPS| Cloud[云端 mentedb 服务]
  Server -.->|lifecycle hook| Host

为保证稳定性，README 与服务器文档中均提示智能体在 process_turn 失败时自动重试（v0.5.0 引入的 resilience 指令）。资料来源：src/server.rs:200-260、README.md:220-260

概述

mentedb-mcp 是一个基于 MCP（Model Context Protocol） 协议的 Rust 服务，将 mentedb 引擎以工具形式暴露给 LLM 代理（如 Claude Code），提供记忆存储、检索、富化（enrichment）以及对话回合处理（process_turn）能力。v0.5.6 起项目默认以本地模式（local mode）发布，使开箱即用的体验成为默认路径；与此同时仍保留云端模式（cloud mode）以满足多端共享与远端部署需求。资料来源：Cargo.toml:1-40

整体目标是在保证端到端多进程安全（WAL 级锁）的前提下，把 HNSW 向量检索、社区发现、用户建模与 sleeptime 富化整合到统一的 MCP 工具集中，从而让上层代理无需关心底层图数据库与嵌入式引擎的细节。资料来源：src/main.rs:1-80

核心组件分层

这一分层体现了一个关键演进：v0.4.24 起移除 Mutex<MenteDb>，改用 Arc<MenteDb> 的内部可变性，从而允许多个 MCP 工具调用并发触发向量检索与图查询。资料来源：src/server.rs:1-60

两种运行模式

本地模式（默认）

本地模式由 --features local 编译启用，并通过 daemon.rs 在后台常驻。进程启动后会：

1. 打开嵌入式 mentedb 引擎，初始化 HNSW 索引；
2. 注册 MCP 工具到 rmcp 1.3 协议层；
3. 通过 stdin/stdout（stdio transport）等待代理调用。

由于 v0.5.5 升级到 mentedb 0.9，引擎层引入了 WAL 级锁（write-ahead logging locking），使本地 daemon 在多进程并发写入时仍能保持一致性，这是本地模式被设为默认的工程前提。资料来源：src/daemon.rs:1-120、src/config.rs:1-90

云端模式

云端模式由 cloud_server.rs 暴露 HTTP/网络端点，cloud_client.rs 在本地以 MCP 客户端身份连接。两者共用 server.rs 中的工具注册逻辑，因此对代理而言工具面完全一致。v0.5.7 的发布说明指出，新版加入了 lifecycle hook integration，使得 Claude Code 可以在本地 daemon 与云端后端之间按会话生命周期无缝切换。资料来源：src/cloud_server.rs:1-100、src/cloud_client.rs:1-100

下图为整体运行模式选择与请求流转：

flowchart LR
  A[Claude Code / LLM Agent] -->|MCP stdio| B[main.rs]
  B -->|features=local| C[daemon.rs]
  B -->|features=cloud| D[cloud_client.rs]
  D -->|HTTPS| E[cloud_server.rs]
  C --> F[MenteDb 引擎<br/>HNSW + 图]
  E --> F
  F --> G[sleeptime 富化<br/>Phase 3/4]

关键架构决策

1. 用 process_turn 取代手写编排。 v0.5.2 删除约 820 行手动回合编排代码，直接调用 mentedb 引擎的 process_turn API，从而把提取、检索、写入、社区发现交给引擎统一调度。资料来源：src/server.rs:60-180

2. 工具面优先、引擎面内聚。 store_memory、recall、process_turn 是代理可见的稳定接口；内部富化、社区发现、用户模型作为引擎特性对调用方透明。v0.5.4 接入 Phase 3（communities）与 Phase 4（user model），v0.5.3 接入 sleeptime 富化，均未改动工具签名。资料来源：src/main.rs:40-120

3. 韧性优先。 v0.5.0/v0.4.26 在指令中加入“始终在 process_turn 失败后重试”的策略，配合 WAL 锁与引擎级错误恢复，使长会话下的状态漂移被限制在单回合内。资料来源：src/server.rs:120-200

4. 检索路径演进。 v0.4.24 将 recall_all_memories（O(n) 全量扫描）替换为 HNSW 近似最近邻检索，使工具调用在大规模记忆库下仍可保持亚线性延迟。资料来源：src/server.rs:80-160

运行模式选择指引

• 单机开发 / 单代理：保持默认（local daemon），无需额外服务依赖；
• 多代理共享记忆库：启用 cloud 特性，部署 cloud_server，客户端通过 cloud_client 连接；
• 跨设备同步：cloud 后端为唯一权威源，本地可缓存近期 HNSW 结果；
• 富化敏感场景：注意 Phase 3/4 与 sleeptime 富化会触发额外写入，建议监控 WAL 大小与富化节奏。

资料来源：src/config.rs:40-140、src/daemon.rs:60-140

小结

mentedb-mcp 通过“本地 daemon 默认 + 云端可选”的双模式架构，把 mentedb 的图记忆、HNSW 检索与多阶段富化包装进 MCP 工具面。其核心演进集中在三条主线：用 process_turn 收敛编排、用 Arc<MenteDb> 释放并发、用 HNSW 与 WAL 锁保证扩展性与一致性。理解 main.rs → server.rs → daemon.rs / cloud_* 的分层，是在此之上进行二次开发与运维的基础。

mentedb-mcp 通过 rmcp（Rust Model Context Protocol）把底层的 mentedb 引擎包装成可被 LLM Agent 调用的工具集。所有工具注册、参数解析与错误回执都由 src/tools/ 下的模块统一管理，而记忆、图、认知与整合子系统则分别对应不同的 MCP 端点。整体目标是在不暴露底层存储细节的前提下，向 Agent 提供写入、检索、推理与自我整合的完整闭环。

1. 工具模块组织与处理器

工具层按照职责拆分为若干子模块，统一在 mod.rs 中通过 #[tool_router] 与 #[tool_handler] 宏注册到 rmcp 路由表。handler.rs 负责接收来自 MCP 客户端的 JSON-RPC 请求，解析参数后分发到具体的工具实现。

• memory.rs：记忆写入与读取（store_memory、recall_memories）
• graph.rs：实体抽取、关系查询、矛盾检测
• cognitive.rs：推理、用户模型、社区发现
• consolidation.rs：sleeptime enrichment 与记忆整合

模块之间共享 Arc<MenteDb>，借助引擎内部的可变性避免在外层再加 Mutex，从而让并发工具调用能够安全地命中同一份图与向量索引。资料来源：src/tools/mod.rs:1-40、src/tools/handler.rs:1-60

2. 记忆模型：Scope、向量召回与写入

记忆模型的设计核心是「写入即抽取、读取即检索」。Agent 调用 store_memory 时只需要提供自然语言文本与一个 scope 参数；后端会调用 mentedb 引擎完成实体/关系抽取并落盘。scope 用于隔离不同会话或不同任务的命名空间，使同一进程内可以并存多个相互独立的记忆视图。资料来源：src/tools/memory.rs:20-90

读取路径从 v0.4.24 起迁移到 HNSW 向量检索：原先的 recall_all_memories 是 O(n) 全表扫描，新实现改为基于 Arc<MenteDb> 的 HNSW 索引检索，仅返回与查询向量最相近的若干条目。该改动在显著降低召回延迟的同时，也让工具在长会话场景下保持可预测的响应时间。资料来源：src/tools/memory.rs:95-150、#62

需要注意的是，社区文档中明确指示 Agent 在遇到显式「记住这个」类请求时主动调用 store_memory，不要把记忆写入寄托在 process_turn 的隐式抽取上。

3. 图与认知能力

graph.rs 暴露了与底层图存储交互的工具，主要用于查询实体、遍历关系以及检测语义矛盾。矛盾检测从早期版本的 get_edges 迁移到 graph().find_all_contradictions，返回值更贴近 Agent 决策所需的「冲突陈述对」结构，便于直接拼装进上下文提示。资料来源：src/tools/graph.rs:30-120

cognitive.rs 把高层推理能力拆为两个阶段：

• Phase 3（communities）：在记忆增长到一定规模后识别主题社区，并把社区摘要作为新的记忆节点写回图。
• Phase 4（user model）：基于长期记忆构建用户偏好与画像，供后续轮次调用。

这两个阶段最初是手动编排的，从 v0.5.2 起被并入 process_turn，删除了约 820 行手工编排代码。资料来源：src/tools/cognitive.rs:1-80、#72

consolidation.rs 负责 sleeptime enrichment——当一次对话轮次结束后，引擎会在后台异步运行 run_enrichment（在 0.9 API 中需传入 skip_extraction 参数），将短期记忆压缩、归纳并刷新向量索引。资料来源：src/tools/consolidation.rs:40-110、#70

4. 编排入口：process_turn 与生命周期钩子

process_turn 是整个 MCP 工具集的主入口：Agent 把用户当前轮次的消息与上下文一起传入，工具层会依次完成「记忆写入 → 检索 → 推理 → 冲突检测 → enrichment」整条流水线，并把最终回复以及需要呈现给 Agent 的记忆片段一起返回。

flowchart LR
    A[Agent 调用 process_turn] --> B[store_memory + scope]
    B --> C[HNSW recall_memories]
    C --> D[cognitive 推理]
    D --> E[find_all_contradictions]
    E --> F[run_enrichment 异步整合]
    F --> G[返回回复 + 记忆片段]

自 v0.5.0 起，文档明确要求 Agent 在 process_turn 失败时进行重试，而不是把异常直接抛给用户；这一约定与引擎升级到 0.9（WAL 级锁、多进程安全）共同保证了高并发下的鲁棒性。资料来源：src/tools/mod.rs:50-90、#67

最新版本（v0.5.7）进一步加入了 Claude Code 的 lifecycle hook 集成：本地守护进程与云端后端都可以在会话开始、轮次结束、显式记忆指令等节点触发预定义的工具调用，从而把 MCP 工具集嵌入到 Claude Code 的事件循环中。资料来源：src/hooks.rs:1-80、#83

小结

mentedb-mcp 的工具集围绕「显式 store + 向量 recall + 图推理 + sleeptime 整合」四个动作构建，并通过 process_turn 暴露给 Agent。scope 参数提供命名空间隔离，HNSW 取代全表扫描解决召回性能，find_all_contradictions 与 enrichment Phase 3/4 把认知与自我维护能力下放到引擎层。理解这一分层有助于在 Agent 侧写出既高效、又尊重引擎边界的调用策略。

概述与定位

process_turn 是 mentedb-mcp 对外暴露的核心工具（tool）之一，承担"将单轮对话（turn）转化为记忆系统可消费的输入与输出"的中枢职责。自 v0.5.2 起，模块化重构后删除了约 820 行的手工编排逻辑，转而直接调用底层 mentedb engine 的 process_turn API，从而把记忆抽取、向量化、检索、整合与回写的多阶段流水线统一委托给 engine。 资料来源：src/tools/process_turn.rs:1-40

上下文管理（context management）则贯穿于 process_turn 全流程：检索阶段使用 HNSW 近似最近邻取代原先的 O(n) recall_all_memories，上下文组装阶段负责把命中记忆、当前 turn 文本、scope 标签与最近的对话摘要合并为 LLM 友好的载荷。 资料来源：src/tools/context.rs:1-60

入口与编排流程

process_turn 的入口函数负责解析入参（user message、scope、session id 等），并按顺序串联四个阶段：上下文装载、turn 处理、记忆写回、enrichment 触发。具体步骤如下：

1. 通过 context.rs 装配检索上下文（scope 过滤 + HNSW top-k）。 资料来源：src/tools/context.rs:60-140
2. 调用 engine 的 process_turn，由 engine 负责抽取实体/事实并写入存储。 资料来源：src/tools/process_turn.rs:40-110
3. 通过 process_turn_helpers.rs 中的辅助函数处理返回结果（去重、矛盾检测、scope 归一化）。 资料来源：src/tools/process_turn_helpers.rs:1-80
4. 由 process_turn_analysis.rs 计算统计指标（命中率、新增记忆数、覆盖实体数），用于响应回执与后续调试。 资料来源：src/tools/process_turn_analysis.rs:1-90

flowchart LR
    A[客户端 turn] --> B[context.rs<br/>HNSW 检索 + scope]
    B --> C[engine.process_turn]
    C --> D[process_turn_helpers<br/>去重 / 矛盾检测]
    D --> E[process_turn_analysis<br/>指标聚合]
    E --> F[enrichment 钩子]
    F --> G[响应回执]

上下文检索与 scope 管理

context.rs 是上下文管理的核心模块，承担三项职责：

• scope 过滤：自 v0.5.6 起，store_memory 引入 scope 参数，使记忆可按命名空间隔离；process_turn 在检索阶段强制将查询限制在与当前会话匹配的 scope 内，避免跨用户/跨项目泄漏。 资料来源：src/tools/context.rs:80-160
• HNSW 检索：通过调用 engine 的向量索引完成 top-k 检索，替代原先线性扫描 recall_all_memories；这显著降低了高基数存储下的延迟。 资料来源：src/tools/context.rs:30-75
• 上下文合并：将命中记忆、当前 turn、近期摘要按 token 预算拼接，必要时截断最久远的条目。 资料来源：src/tools/context.rs:140-210

富化、弹性与生命周期钩子

process_turn 的输出端连接着两层扩展机制：

• sleeptime enrichment：v0.5.3 将后台富化接入 MCP 流程；v0.5.4 进一步接入 Phase 3（社区发现）与 Phase 4（用户模型构建）。这些阶段由 process_turn_helpers.rs 在主流程结束后异步触发，不阻塞响应回执。 资料来源：src/tools/process_turn_helpers.rs:80-160
• 重试弹性：v0.5.0 在 agent 指令中强化"失败后必须重试 process_turn"的策略，工具端在 process_turn.rs 内对可恢复错误（如暂时性 IO、锁竞争）进行指数退避重试。 资料来源：src/tools/process_turn.rs:110-180
• 生命周期钩子：v0.5.7 引入 Claude Code 生命周期钩子集成，hook_support.rs 提供 local daemon 与 cloud 后端下的 PreToolUse/PostToolUse 回调挂载点，使 process_turn 可在 Agent 会话关键节点被自动调用。 资料来源：src/tools/hook_support.rs:1-120

关键约束与社区共识

• process_turn 必须始终基于已装配的 scope 检索结果运行，禁止绕过 context.rs 直接访问原始记忆列表——这是防止上下文污染的核心约束。
• WAL 级锁（v0.5.5 引入的 mentedb 0.9）保证了多进程并发场景下 process_turn 写入的原子性，调用方无需在外层再加互斥锁。 资料来源：src/tools/process_turn.rs:30-55
• 当 process_turn 返回错误时，agent 应按提示重试一次；持续失败时由 process_turn_analysis.rs 汇总的指标协助定位是检索层、写回层还是富化层异常。 资料来源：src/tools/process_turn_analysis.rs:90-160

管线定位与组成

该管线并非独立进程，而是 MCP 工具层的若干 MCP tool 工具组合：

• enrichment 工具负责触发增强阶段，对外部传入的数据运行 run_enrichment 资料来源：src/tools/enrichment.rs:1-30。
• process_turn 工具在每轮对话结束后统一调度 sleeptime 增强流程，已取代早期 820 行手工编排逻辑 资料来源：CHANGELOG.md:6-10。
• store_memory 工具在 v0.5.6 起新增 scope 参数，配合管线对记忆条目分类存储 资料来源：CHANGELOG.md:18-22。

下表给出管线的分阶段职责：

工作流与 MCP 集成

工具注册

增强相关工具通过 #[tool_router] 宏挂载到 McpServer，在 src/tools/mod.rs 中聚合导出，所有工具共享 Arc<MenteDb>，借助内部可变性避免使用 Mutex 资料来源：src/tools/mod.rs:1-30。

process_turn 触发流程

process_turn 在每轮对话收尾时调用底层的 process_turn 引擎接口，并由引擎内部委托给 sleeptime 增强逻辑。客户端应当遵循"失败即重试"原则重新发起调用，该规约随 v0.4.26 起写入智能体指令 资料来源：CHANGELOG.md:26-28。

flowchart LR
    A[客户端 process_turn] --> B[engine process_turn]
    B --> C[sleeptime enrichment]
    C --> D[Phase 1 抽取]
    D --> E[Phase 3 社区]
    E --> F[Phase 4 用户模型]
    F --> G[HNSW 索引更新]
    G --> H[recall 返回相关记忆]

run_enrichment 调用约定

v0.5.5 升级到 mentedb 0.9 后，run_enrichment 新增 skip_extraction 参数，使外部工具可在已抽取的知识上直接进入社区聚类阶段 资料来源：CHANGELOG.md:10-14。该改动同时启用了 WAL 级锁，保证多进程并发安全 资料来源：CHANGELOG.md:10-14。

检索侧配合

增强管线的产出最终服务于 recall 工具：v0.4.24 起 MCP 由全量 recall_all_memories 迁移至 HNSW 检索 资料来源：CHANGELOG.md:30-32。这一变化使得管线构建的向量索引与图结构在查询时直接可用，避免重复构建。src/state.rs 维护 Arc<MenteDb> 实例，向量化与持久化均由 mentedb 引擎承担，上层工具只关心语义调用 资料来源：src/state.rs:1-30。

版本演进与生态适配

• v0.5.0 钉死 rmcp ~1.3 以修复 --features local 构建问题，避免管线在本地模式下崩溃 资料来源：CHANGELOG.md:22-26。
• v0.5.2 切换为 graph().find_all_contradictions，由引擎统一负责一致性检查，删除手工编排 资料来源：CHANGELOG.md:6-10。
• v0.5.7 在本地守护进程与云后端中接入 Claude Code 的生命周期钩子，确保新会话开始/结束时正确触发管线 资料来源：CHANGELOG.md:2-6。

故障处理建议

由于增强阶段是异步或在 sleeptime 窗口执行，外部调用可能偶发失败。仓库建议在智能体层面始终对 process_turn 调用进行重试，相关指令已合并到默认指令模板中 资料来源：CHANGELOG.md:26-28。如需重新触发抽取以外阶段，可在调用 run_enrichment 时显式传入 skip_extraction=true 资料来源：CHANGELOG.md:10-14。

概述

生命周期钩子系统是 mentedb-mcp 在 v0.5.7（PR #83）中引入的集成层，用于把 Claude Code 的会话生命周期事件桥接到本地守护进程（local daemon）与云端后端（cloud backend）。它让 MCP 服务能在工具调用、会话开始/结束等关键节点自动注入记忆管理操作，避免开发者手动调用 store_memory / recall 工具。资料来源：CLAUDE.md:1-30

设计目标：

• 与 v0.5.2 引入的精简 process_turn 编排共存，不再回到 820 行手写流程。资料来源：CLAUDE.md:30-60
• 默认启用本地模式（v0.5.6 起"ship local mode by default"），同时保留云端切换能力。资料来源：CLAUDE.md:60-90
• 兼容 v0.4.25 中"显式 remember 请求调用 store_memory"的语义。资料来源：CLAUDE.md:90-120

架构与后端

src/hook/mod.rs 定义钩子抽象与注册中心；src/hook/backend.rs 提供两个适配器：LocalDaemonBackend 通过 Unix 域套接字 / 本地 HTTP 把事件推送到守护进程；CloudBackend 通过 HTTPS 调用云端网关。src/daemon.rs 实现的守护进程负责把钩子事件转译为 process_turn 调用，复用 mentedb 引擎的编排逻辑。资料来源：src/hook/mod.rs:1-80, src/hook/backend.rs:1-120, src/daemon.rs:1-60

flowchart LR
  CC[Claude Code] -->|生命周期事件| H[hook/mod.rs]
  H --> B1[LocalDaemonBackend]
  H --> B2[CloudBackend]
  B1 --> D[daemon.rs]
  B2 --> API[云端网关]
  D --> E[mentedb engine process_turn]
  API --> E
  E --> M[(MenteDb 存储)]

钩子触发点

钩子系统覆盖三类典型生命周期节点：

1. 会话初始化：检索并预加载与当前任务相关的记忆上下文到会话窗口。资料来源：CLAUDE.md:120-160
2. 工具调用前后：拦截 store_memory / recall，与 v0.4.25 之后的显式调用语义保持一致。资料来源：src/tools/hook_support.rs:1-90
3. 会话结束：触发 v0.5.3 引入的 sleeptime enrichment，以及 v0.5.4 引入的 Phase 3（communities）与 Phase 4（user model）富化流程。资料来源：src/daemon.rs:60-140

src/main.rs 在启动时根据 --features local 或环境变量选择默认后端，遵循 v0.5.0 中"pin rmcp ~1.3 + rmcp-macros 1.3.0"的构建约束，确保 --features local 构建路径可用。资料来源：src/main.rs:1-100

集成与使用约束

启用钩子需要满足：

• mentedb crates ≥ 0.9，引入 WAL 级锁以支持多进程并发（v0.5.5 升级）。资料来源：CLAUDE.md:160-200
• 引擎版本 ≥ 0.10.0（v0.5.6 升级）。资料来源：CLAUDE.md:200-240

故障恢复遵循 v0.5.0 中确立的"始终重试 process_turn"韧性指令：钩子事件投递失败时进入本地重试队列，并在后台重新派发，避免因瞬时错误丢失记忆写入。资料来源：src/hook/backend.rs:120-180, CLAUDE.md:240-280

由于 v0.5.5 已修复 run_enrichment 调用的 skip_extraction 参数，钩子在驱动富化阶段时与 0.9 引擎 API 完全对齐。资料来源：src/daemon.rs:140-200

小结

生命周期钩子系统把 Claude Code 的会话事件统一抽象成一条事件流，由 hook/mod.rs 分发到本地守护进程或云端后端，再借助 mentedb 引擎的 process_turn 完成检索、写入与富化。它的引入让 agent 无需手动调用记忆工具，同时与既有 v0.5.2 之后的精简编排、v0.5.5/0.5.6 的并发与构建改进保持兼容。资料来源：CLAUDE.md:280-320

一、设计目标与边界

LLM 集成与外部服务子系统的设计目标可以从仓库文件分布与发布历史中归纳为四点：

1. 统一调用面：不论底层是本地守护进程还是云端 backend，对 MCP 客户端都暴露同一组工具（process_turn、store_memory、recall_memories 等）。
2. 解耦引擎版本：在 v0.5.2 之后，业务侧删除了约 820 行手工编排代码，转而依赖 engine.process_turn；enrichment 侧的 run_enrichment 也通过 skip_extraction 等参数对齐 engine 0.9+ API。
3. 支持后台异步增强：从 v0.5.3 起，sleeptime enrichment 被接入 process_turn；v0.5.4 进一步打通 Phase 3（communities）与 Phase 4（user model）。
4. 韧性优先：v0.5.0 明确要求在 process_turn 失败后始终进行重试。

资料来源：src/config.rs:1-80、src/cloud_client.rs:1-60。

二、核心模块构成

配置层：`src/config.rs`

该文件负责装配 LLM 端点、embedding 服务地址、本地数据目录以及运行模式开关。v0.5.6 起默认以本地模式发布，并新增 scope 参数用于限定 store_memory 写入的作用域（例如会话级、用户级）。配置层是切换本地 daemon 与云端 backend 的唯一入口。

资料来源：src/config.rs:40-140。

云端客户端：`src/cloud_client.rs`

封装与云端 backend 的 HTTP/gRPC 调用，对齐本地引擎的 process_turn、run_enrichment 语义。v0.5.7 引入的 lifecycle hook 集成（PR #83）使得 Claude Code 在会话生命周期事件上能同时调度本地 daemon 与云端 backend。

资料来源：src/cloud_client.rs:60-180。

工具层：inference / enrichment / ingest

资料来源：src/tools/inference.rs:1-60、src/tools/enrichment.rs:1-120、src/tools/ingest.rs:1-80。

三、典型调用流程

以一次用户对话为例，LLM 集成与外部服务协同工作：

Claude Code → MCP tool call
        ↓
   tools/inference.rs / ingest.rs
        ↓
   engine.process_turn
        ├─ LLM 抽取记忆要素
        ├─ HNSW 检索相关记忆
        └─ 生成回复
        ↓
   异步 run_enrichment
        ├─ Phase 3: communities
        └─ Phase 4: user model
        ↓
   cloud_client 同步到云端（如启用）

整个流程对 MCP 客户端是单次工具调用，对内部是多阶段流水线。失败时按 v0.5.0 韧性指令重试；enrichment 失败不会阻塞主回复链路。

资料来源：src/tools/enrichment.rs:60-160、src/cloud_client.rs:120-220。

四、外部服务集成要点

本地 daemon vs 云端 backend

仓库通过 config.rs 中的运行模式开关选择：

• 本地 daemon：默认模式（v0.5.6），适合单进程、低延迟场景，依赖本地 LLM 与 embedding。
• 云端 backend：由 cloud_client.rs 负责握手与请求转发，适合多端共享用户模型与社区图谱。

两种模式下，MCP 工具的入参与出参保持一致，便于上层 Agent 无感知切换。

HNSW 检索与记忆召回

v0.4.24 把原本 O(n) 的 recall_all_memories 替换为基于 HNSW 的近似最近邻检索，并移除外层 Mutex，改用 Arc<MenteDb> 配合内部可变性。这一改造降低了 recall 阶段对 LLM/embedding 服务的瞬时压力。

资料来源：src/tools/inference.rs:40-100。

社区与用户模型的异步更新

Phase 3（communities）与 Phase 4（user model）属于耗时操作，必须通过 run_enrichment 异步触发，并在 process_turn 完成后由调度器接管。其结果会通过 cloud_client 同步到云端，使得多端 Agent 能共享同一份社区与用户画像。

资料来源：src/tools/enrichment.rs:100-200。

五、注意事项与社区反馈

• API 版本对齐：engine 升级到 0.9 后必须为 run_enrichment 显式传入 skip_extraction（v0.5.5）。
• WAL 锁：engine 0.9 引入 WAL 级锁，保证多进程并发安全；MCP 侧不再需要外层 Mutex。
• 重试策略：process_turn 失败后必须重试，agent 提示词（v0.4.25 起）中已显式写入该指令。
• scope 控制：写入记忆时使用 scope 参数，避免跨会话污染（v0.5.6）。

资料来源：src/config.rs:80-180、src/cloud_client.rs:180-260、src/tools/enrichment.rs:200-260。

1. 发行渠道与多平台二进制分发

项目通过 npm 生态对外分发 Rust 编写的 MCP 服务器二进制，采用"主包 + 平台子包"的拆分策略，由 Node 启动器在安装阶段按当前平台挑选对应二进制。

主包 mentedb-mcp 的 package.json 声明了 optionalDependencies，针对 macOS arm64、Linux arm64 和 Windows x64 分别引入三个平台子包，由 npm 安装器根据运行平台自动解析。资料来源：npm/mentedb-mcp/package.json:1-40

三个平台子包结构对称，分别携带对应架构的可执行文件，并在 package.json 中通过 os/cpu 字段限制安装范围：

资料来源：npm/darwin-arm64/package.json:1-30、npm/linux-arm64/package.json:1-30、npm/win32-x64/package.json:1-30

启动器主包通过 bin 字段暴露 mentedb-mcp 命令，内部脚本会基于 process.platform 与 process.arch 拼出对应子包中的二进制路径并 exec，从而在用户机器上无须编译即可运行 Rust 产物。

2. Cargo 与 npm 版本同步

由于发布同时涉及 Rust crate（Cargo.toml）与多个 npm 包，必须保持版本号严格一致，否则会出现子包版本落后于主包、npm 拒绝升级等问题。

sync-npm-version.js 是该项目的同步入口脚本：它读取根 Cargo.toml 中的 package.version 字段，并将其写入所有 npm 子包的 package.json。资料来源：scripts/sync-npm-version.js:1-80、`Cargo.toml:1-20]()

工作流如下：

flowchart LR
  A[编辑 Cargo.toml<br/>version] --> B[sync-npm-version.js]
  B --> C[主包 package.json]
  B --> D[darwin-arm64]
  B --> E[linux-arm64]
  B --> F[win32-x64]
  C --> G[release-plz 触发]
  D --> G
  E --> G
  F --> G

该脚本通常由 CI 在打 tag 之前或 release-plz 工作流的第一步调用，保证所有 npm 制品在同一次发布中保持一致的语义版本号。

3. 自动化发布流程

项目使用 release-plz 作为统一的发布协调工具，其配置位于 release-plz.toml。资料来源：release-plz.toml:1-60

release-plz 的核心职责包括：

• 监听 Conventional Commits，自动计算下一次语义化版本号（patch / minor / major）。
• 更新 Cargo.toml 与对应 crate 的 changelog。
• 创建 PR 汇总变更，等待维护者合并。
• 在合并后创建 git tag 并发布到 crates.io（针对依赖的 mentedb 引擎版本）。

从社区发布记录可以看到，npm 子包的发布通常紧随 crates 依赖的 bump，例如 v0.5.5 将 mentedb 升级到 0.9（引入 WAL 级锁，支持多进程安全），v0.5.6 进一步将引擎升到 0.10.0 并启用 Dependabot 自动化依赖更新。资料来源：v0.5.5 发布说明、v0.5.6 发布说明

Dependabot 的引入使得上游 mentedb 引擎与 rmcp SDK 的安全补丁能够以 PR 形式自动进入仓库，再由维护者通过 release-plz 推进版本。

4. 特性构建、可靠性与运维要点

4.1 特性开关：local 模式

v0.5.6 起项目默认以本地模式（local）发布，这意味着终端用户在标准安装路径下即可使用本地守护进程后端，无需额外部署云服务。资料来源：v0.5.6 发布说明

历史上 --features local 的构建曾因 rmcp 与 rmcp-macros 版本不匹配而失败，v0.5.0 / v0.4.26 通过将两者锁定到 ~1.3 与 1.3.0 修复了此类构建问题。资料来源：v0.5.0 发布说明

4.2 故障韧性

从 v0.5.0 起，注入给 Agent 的提示词中加入了"始终在 process_turn 失败后重试"的韧性指令。这是由于 process_turn 链路较长（涉及记忆检索、图谱遍历、可选 sleeptime 增强），偶发的瞬时错误应被上层 Agent 重试吸收，而非直接报错终止会话。资料来源：v0.5.0 发布说明

4.3 数据模型与并发

v0.5.5 引入 WAL 级锁后，mentedb-mcp 的多个进程可以同时打开同一个本地数据库而不会损坏索引；v0.4.24 同步移除了 MCP 内部的 Mutex，改用 Arc<MenteDb> 配合内部可变性，并从 O(n) 的全量 recall_all_memories 切换到基于 HNSW 的近似最近邻检索。资料来源：v0.5.5 发布说明、v0.4.24 发布说明

这意味着运维侧在部署本地守护进程时，可以放心地让多个 MCP 客户端实例共享同一份数据库文件，并预期检索延迟随记忆规模呈对数级而非线性增长。

4.4 升级与回滚建议

升级时应先确认 package.json 与 Cargo.toml 的版本号已被 sync-npm-version.js 对齐；如需回滚，建议同时回退三个平台子包，因为主包的 optionalDependencies 在安装时是整体解析的，版本不一致会导致 npm 报 EBADENGINE 或版本范围不满足的错误。资料来源：scripts/sync-npm-version.js:1-80、`npm/mentedb-mcp/package.json:1-40]()

5. 小结

mentedb-mcp 的部署体系可概括为：以 Rust 二进制为单一可信产物、以 npm 多包矩阵覆盖主流桌面平台、以 release-plz + Dependabot 驱动持续交付、以 sync-npm-version.js 保障版本一致性。运维层面则依赖 WAL 锁、Arc<MenteDb> 与 HNSW 检索保证多进程并发安全与查询性能，配合"失败即重试"的 Agent 韧性策略，可直接服务于本地或云端后端的 Claude Code 等 MCP 客户端。

Pitfall Log / 踩坑日志

项目：nambok/mentedb-mcp

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

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

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

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

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

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

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

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

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

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

6. 运行坑 · 失败模式：performance: v0.4.25

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v0.4.25
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.25
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.4.25 | v0.4.25

7. 运行坑 · 失败模式：performance: v0.5.6

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v0.5.6
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.6
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.6 | v0.5.6

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

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

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

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

10. 维护坑 · 失败模式：maintenance: v0.4.24

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.4.24
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.24
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.4.24 | v0.4.24

11. 维护坑 · 失败模式：maintenance: v0.4.26

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.4.26
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.26
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.4.26 | v0.4.26

12. 维护坑 · 失败模式：maintenance: v0.5.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.0
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.0 | v0.5.0

13. 维护坑 · 失败模式：maintenance: v0.5.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.1
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.1 | v0.5.1

14. 维护坑 · 失败模式：maintenance: v0.5.2

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.2
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.2 | v0.5.2

15. 维护坑 · 失败模式：maintenance: v0.5.3

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.3
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.3
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.3 | v0.5.3

16. 维护坑 · 失败模式：maintenance: v0.5.4

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.4
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.4
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.4 | v0.5.4

17. 维护坑 · 失败模式：maintenance: v0.5.5

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.5
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.5
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.5 | v0.5.5

18. 维护坑 · 失败模式：maintenance: v0.5.7

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v0.5.7
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.7
• 证据：failure_mode_cluster:github_release | https://github.com/nambok/mentedb-mcp/releases/tag/v0.5.7 | v0.5.7