mind-mem 项目说明书

Doramagic 项目包 · 项目说明书

mind-mem 项目

为 Claude Code、OpenClaw 以及任何兼容 MCP 的智能体提供持久化 AI 记忆功能；采用 BM25F 与向量混合检索，具备治理感知能力，本地优先，零基础设施依赖。

概览与系统架构

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 检索与索引（Recall & Index）

继续阅读本节完整说明和来源证据。

章节 3.2 治理与提议（Governance）

继续阅读本节完整说明和来源证据。

章节 3.3 审计、血缘与编译真值（Audit / Lineage / Compiled Truth）

继续阅读本节完整说明和来源证据。

1. 项目定位与核心目标

mind-mem 是一个面向编码代理（coding agents）的"持久化、可审计、矛盾安全"（persistent, auditable, contradiction-safe）的记忆系统。它将记忆能力以 MCP（Model Context Protocol）工具的形式暴露给 AI 客户端，并通过 REST/HTTP 端点供运维侧使用。系统的核心设计哲学由 MCP 服务器的指令直接表达：代理必须通过 recall 检索记忆，通过 propose_update 提交建议，所有变更必须经由人类审核后才会写入事实源（source of truth）资料来源：[src/mind_mem/mcp/server.py:1-35](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/server.py)。

2. 分层架构

整个系统采用"服务器聚合 + 领域模块化"的二层结构：

flowchart TB
    Client["AI 客户端 / stdio / HTTP"] -->|JSON-RPC| Server["mcp/server.py<br/>FastMCP(name='mind-mem')"]
    Client2["运维 / OIDC 用户"] -->|Bearer| REST["api/rest.py<br/>FastAPI 应用"]
    Server --> Recall["tools/recall.py<br/>检索核心"]
    Server --> Gov["tools/governance.py<br/>propose / approve / rollback"]
    Server --> Audit["tools/audit.py<br/>Merkle + 哈希链"]
    Server --> Kernels["tools/kernels.py<br/>compiled-truth 页面"]
    Server --> Lineage["tools/lineage.py<br/>类型化血缘图"]
    Server --> Memory["tools/memory_ops.py<br/>导入/导出/索引统计"]
    Server --> Arch["tools/arch_mind.py<br/>架构度量"]
    Server --> Model["tools/model.py<br/>模型签名/审计"]
    Server --> Bench["tools/benchmark.py<br/>健康基准"]
    Server --> ACL["infra/acl.py<br/>工具白名单 + 作用域"]
    REST --> Gov
    REST --> ACL

mcp/server.py 仅承担装配职责：它实例化一个 FastMCP，并按"资源先、工具后"的顺序调用各领域模块的 register(mcp) 将工具挂载到服务器资料来源：[src/mind_mem/mcp/server.py:40-78](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/server.py)。REST 层则通过 _require_admin / _require_auth 依赖复用 MCP 工具函数资料来源：[src/mind_mem/api/rest.py:1-60](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/api/rest.py)。

3. 关键子系统概览

3.1 检索与索引（Recall & Index）

tools/recall.py 是所有检索类工具的汇聚点，8 个工具（recall、recall_with_axis、hybrid_search、pack_recall_budget、prefetch、intent_classify、find_similar、retrieval_diagnostics）最终都汇聚到共享实现 _recall_impl 中，在 BM25 与混合检索后端之间切换资料来源：[src/mind_mem/mcp/tools/recall.py:1-40](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/recall.py)。tools/memory_ops.py 则通过 index_stats 暴露 FTS 索引健康度，并在非 Markdown 后端（如 Postgres）下回退到块存储资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-50](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/memory_ops.py)。

3.2 治理与提议（Governance）

tools/governance.py 是写入路径的入口，提供 propose_update、scan、list_contradictions、approve_apply、reject_proposal、rollback_proposal 与 memory_evolution 共 7 个工具，确保任何变更都留下可回滚的证据资料来源：[src/mind_mem/mcp/tools/governance.py:1-30](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/governance.py)。

3.3 审计、血缘与编译真值（Audit / Lineage / Compiled Truth）

tools/audit.py 暴露 Merkle 证明、哈希链与证据链完整性校验资料来源：[src/mind_mem/mcp/tools/audit.py:1-25](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/audit.py)。tools/lineage.py 在 v3.11.0 引入"类型化血缘图"，支持 cites / implements / refines / contradicts / cooccurrence 五种边的 BFS 遍历（深度上限 3，节点上限 1000）资料来源：[src/mind_mem/mcp/tools/lineage.py:1-25](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/lineage.py)。tools/kernels.py 则管理"编译真值页面"，提供 add_evidence 与 detect_contradictions 帮助代理在累积证据时检测冲突资料来源：[src/mind_mem/mcp/tools/kernels.py:1-40](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/kernels.py)。

3.4 辅助能力

tools/arch_mind.py 暴露 7 个 arch-mind 子进程包装工具，所有路径参数在调用前都经过 _validate_arch_path 校验，禁止 NUL 字节与以 - 开头的"伪 flag"注入资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-40](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/arch_mind.py)。tools/model.py 提供本地模型检查点的 Ed25519 签名/校验，对 path 参数执行同样的 NUL 与空串拒绝资料来源：[src/mind_mem/mcp/tools/model.py:1-40](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/model.py)。tools/benchmark.py 暴露 governance_health_bench 套件资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-30](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/tools/benchmark.py)。

4. 横切关注点与已知架构风险

infra/acl.py 维护一份工具白名单（含 v3.11.1 回填的 audit_model_tool 等条目），并在 _get_request_scope 异常时返回 fail-closed 的 "deny" 作用域以避免 issue #526 所述的失败开放漏洞资料来源：[src/mind_mem/mcp/infra/acl.py:1-50](https://github.com/star-ga/mind-mem/blob/f3c3545fd89988bf8aa4b212ca89829679d76b47/src/mind_mem/mcp/infra/acl.py)。然而，社区追踪到多个仍待修复的架构级问题：

#530：sqlite_index.py:build_index 在 80KB 工作区上耗时约 55 秒，影响 CI 迭代速度 issue #530。
#526：ACL 令牌内省异常曾以"默认放行"方式 fail-open，属 Critical 安全问题。
#529 / #528 / #527：v4 引入的联邦层（v4/federation_client.py、http_transport.py）缺乏 scheme 白名单、跳转上限、响应大小上限、TLS 绑定与 vclock 推进，导致 _handle_fed_resolve 接受未校验的 merged_payload 且已解决冲突在每次 detect_conflict 时复发。
#525 / #524：Postgres 后端下 mm recall 与 mm doctor --rebuild-cache 仍依赖本地 recall.db，存在"PG 命中但 recall 为空"的不一致。

这些条目共同勾勒出 mind-mem 当前架构的两个主要张力面：检索/索引性能（#530、#525、#524）与联邦/HTTP 传输面（#527–#529）。在引入新工具或新后端时，开发者应当同时考虑 ACL 白名单回填、fail-closed 语义以及跨后端一致性这三项硬性约束。

检索管线与 Recall 核心

检索管线（Recall Pipeline）是 mind-mem 的"读取主入口"，负责把一个自然语言查询转换成命中块（block）列表，并按评分、轴（axis）、人格（persona）、令牌预算等不同维度进行再加工。所有检索面工具最终都汇聚到 recallimpl 这一个共享后端分发器上，再交由 BM25 / 混合（hybrid）后端在本地 SQLite FTS 索引上完成...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

检索管线（Recall Pipeline）是 mind-mem 的"读取主入口"，负责把一个自然语言查询转换成命中块（block）列表，并按评分、轴（axis）、人格（persona）、令牌预算等不同维度进行再加工。所有检索面工具最终都汇聚到 _recall_impl 这一个共享后端分发器上，再交由 BM25 / 混合（hybrid）后端在本地 SQLite FTS 索引上完成查询资料来源：src/mind_mem/mcp/tools/recall.py:1-30。

在 MCP（Model Context Protocol）服务中，检索工具族作为独立的子模块注册到 FastMCP 实例上，遵循"Resources first, tools second"的组织约定，以便追踪输出更易读资料来源：src/mind_mem/mcp/server.py:46-83。同时，/v1/recall REST 端点与 Go/JS SDK 共享同一份语义契约，使外部代理在不同传输层上获得一致的返回结构资料来源：sdk/go/methods.go:9-37、sdk/js/README.md:11-26。

Recall 工具族

recall.py 模块声明的检索工具围绕"搜索工作区"这一心智模型收敛，共包含一个共享帮助器与八个暴露工具资料来源：src/mind_mem/mcp/tools/recall.py:18-30：

工具	主要作用	关键参数
`recall`	顶层排序检索，默认压缩负载	`query`, `limit`, `active_only`, `backend`, `explain`
`recall_with_axis`	ODC 轴感知召回（`rec/cog/aff/str`）	`query`, `axis`, `limit`
`hybrid_search`	已弃用别名，调用 `_recall_impl`	同 `recall`
`pack_recall_budget`	令牌预算约束下的回包	`query`, `max_tokens`, `limit`
`prefetch`	从会话信号预组装上下文	`query`, `limit`
`intent_classify`	9 路意图路由预览	`query`
`find_similar`	共现相似度检索	`seed_block_id`, `limit`
`retrieval_diagnostics`	每阶段拒绝直方图	`query`, `limit`

_recall_impl 作为后端分发器负责参数合法性、计时、解释模式与后端选择；上层工具只负责把"自己的语义"映射到该帮助器的统一签名上，从而避免重复实现评分逻辑资料来源：src/mind_mem/mcp/tools/recall.py:32-120。

紧邻该子模块的 walkthrough_persona.py 进一步扩展检索语义：recall_with_persona 按 brief / detailed / technical 三种人格投影返回字段；compile_truth_walkthrough 则把召回结果按时间戳前缀重排为"基础 → 上下文 → 当前"的学习路径，使用 Kahn 算法进行拓扑排序并在环处确定性打破资料来源：src/mind_mem/mcp/tools/walkthrough_persona.py:30-95。

后端与索引管线

检索的实际执行依赖本地 FTS（全文搜索）索引。index_stats 工具汇总块数量、索引陈旧度、向量覆盖率与 MIND 内核状态，为检索前的健康检查提供入口；其优先读取由 sqlite_index._db_path(ws) 解析出的 recall.db 是否存在，并对 SQLite 锁错误返回标准化的"忙"响应资料来源：src/mind_mem/mcp/tools/memory_ops.py:140-175。

当工作区为非 Markdown 后端（例如 Postgres）时，export_memory 改走 get_block_store(ws).get_all(active_only=False)，审计点 #5 显示这是修复"非 Markdown 后端块仍按 Markdown 路径导出"的关键路径资料来源：src/mind_mem/mcp/tools/memory_ops.py:90-120。

flowchart LR
  Q[Query 字符串] --> A[_recall_impl<br/>共享分发器]
  A --> B[backend 选择<br/>auto / bm25 / hybrid]
  B --> C[(recall.db<br/>SQLite FTS)]
  C --> D[原始召回列表]
  D --> E{上层包装}
  E --> R1[recall]
  E --> R2[recall_with_axis]
  E --> R3[pack_recall_budget]
  E --> R4[find_similar]
  E --> R5[retrieval_diagnostics]
  D --> P1[recall_with_persona]
  D --> P2[compile_truth_walkthrough]

索引本身的构建在 sqlite_index.py:build_index 中完成；社区报告 #530 显示，在 80KB 的全新工作区上 build_index 约需 55 秒，导致增量检测测试在 CI 中耗时膨胀资料来源：src/mind_mem/sqlite_index.py:build_index（参见 issue #530）。memory_ops.py 中的 reindex_dirty 是触发该重建的入口工具资料来源：src/mind_mem/mcp/infra/acl.py:39-55。

已知问题与性能观察

PG 后端召回空集：issue #525 报告在 Postgres 后端工作区上，mm recall <query> 返回空，但直接 psql 的 FTS 查询命中；根因与 issue #524 共因——mm doctor --rebuild-cache 把块数记入 sqlite_count_error，本地 recall.db 实际不含块资料来源：src/mind_mem/mcp/tools/memory_ops.py:150-170（issue #524、#525）。
ACL 白名单与速率限制：检索类工具需出现在 _ADMIN_SCOPES 与 tool 白名单中才能被 check_tool_acl 放行，issue #526 关注的 _get_request_scope 异常吞咽是检索接口被全员拒绝或全员放行的根因资料来源：src/mind_mem/mcp/infra/acl.py:90-150。
性能回归：增量构建超过 64KB 阈值后，build_index 退化为全量重建，CI 单测耗时从秒级跳到 55 秒，建议关注 issue #530 的复现与修复提交资料来源：src/mind_mem/sqlite_index.py:build_index。

治理、MCP 工具与联邦

mind-mem 的"治理"指对记忆工作区（workspace）的所有写操作都必须经过提议 → 审批 → 应用 → 回滚的显式审计链，而不是直接修改 Markdown 源文件。"MCP 工具"是该治理入口的标准化承载层（基于 FastMCP），同时承载只读类操作（recall、lineage、kernels、walkthrough 等）。"联邦"则是 v4.0 引入的跨工作...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 访问控制（ACL）

继续阅读本节完整说明和来源证据。

章节 工具域划分

继续阅读本节完整说明和来源证据。

章节 REST 暴露

继续阅读本节完整说明和来源证据。

概述

mind-mem 的"治理"指对记忆工作区（workspace）的所有写操作都必须经过提议 → 审批 → 应用 → 回滚的显式审计链，而不是直接修改 Markdown 源文件。"MCP 工具"是该治理入口的标准化承载层（基于 FastMCP），同时承载只读类操作（recall、lineage、kernels、walkthrough 等）。"联邦"则是 v4.0 引入的跨工作区同步与冲突解决能力，是治理流程在分布式场景下的延伸。

MCP 服务端的注册顺序由 src/mind_mem/mcp/server.py 统一编排，资源（resources）先注册、工具（tools）后注册。FastMCP 实例在启动时强制执行 v3.7.0 H4 安全约束：除非认证（MIND_MEM_TOKEN / MIND_MEM_ADMIN_TOKEN / OIDC_ISSUER+OIDC_AUDIENCE）已配置，或显式传入 --allow-unauthenticated-localhost 且绑定到回环接口，否则 HTTP 传输不会启动。

治理工作流

治理工具集中在 src/mind_mem/mcp/tools/governance.py，覆盖六类操作：

工具	作用	关键约束
`propose_update`	将新决策/任务以 SIGNAL 形式暂存到 `SIGNALS.md`	`statement` 限 500 字符
`approve_apply`	应用已暂存提案，默认 `dry_run=True`	需要 admin scope
`rollback_proposal`	从预应用快照恢复工作区	接收 `receipt_ts` 与 `reason`
`scan`	完整性扫描（矛盾/漂移/挂起）	区分 Markdown 与非 Markdown 后端
`list_contradictions`	列出带解析建议的矛盾	通过 `src/mind_mem/mcp/tools/audit.py` 校验证据链
`memory_evolution`	返回某块（block）的 A-MEM 元数据	—

flowchart LR
  A[Agent: propose_update] --> B[SIGNALS.md 暂存]
  B --> C[人类/管理员审批]
  C --> D[approve_apply]
  D -->|dry_run| E[生成快照]
  D -->|真实应用| F[写入 DECISIONS.md]
  F --> G[scan/list_contradictions 巡检]
  G -->|发现漂移| H[rollback_proposal]

社区反馈指出 mcp/tools/public.py 中的 staged_change(phase="rollback") 会静默丢弃 rationale 字段（#511），而 propose_update 的 rationale 与 tags 字段未经长度校验即写入 SIGNALS.md（#512）。

MCP 工具基础设施

访问控制（ACL）

src/mind_mem/mcp/infra/acl.py 维护了一张工具白名单，覆盖 recall、kernels、lineage、arch-mind、model、walkthrough、quality、pipeline 等 50+ 工具。check_tool_acl(tool_name, scope) 在 scope 为 "deny" 时对所有工具返回失败，这正是 token introspection 异常的 fail-closed 哨兵——若 _get_request_scope 抛异常被吞掉（#526），攻击者可绕过 ACL。_ADMIN_SCOPES 集合为 {"admin", "full", "mind-mem:admin"}。

工具域划分

mcp_server.py 按 v3.2.0 分解计划将工具拆分到独立模块，每个工具由其 register(mcp) 钩入。值得注意的几个：

recall 域 src/mind_mem/mcp/tools/recall.py：_recall_impl 是 BM25/hybrid 后端的中央调度点，recall / hybrid_search / pack_recall_budget / prefetch / intent_classify / find_similar 全部委托于此。
lineage 域 src/mind_mem/mcp/tools/lineage.py：BFS 遍历块谱系图（cites/implements/refines/contradicts/cooccurrence），max_depth 被夹紧到 [1, 3]，节点上限 1000。
kernels 域 src/mind_mem/mcp/tools/kernels.py：暴露 .mind 内核配置（recall、rerank、RM3 展开），以及 compiled_truth_* 系列（load / add_evidence / contradictions）。
walkthrough 域 src/mind_mem/mcp/tools/walkthrough_persona.py：compile_truth_walkthrough 将 topic 召回结果按时间前缀与共现图重新排序为 foundation → context → current 学习路径。

REST 暴露

src/mind_mem/api/rest.py 通过 FastAPI 把治理工具一对一暴露为 /v1/* 端点（/v1/approve_proposal、/v1/rollback_proposal、/v1/scan、/v1/contradictions 等），所有写端点依赖 _require_admin 并经 _rate_limit 限流。限流在 stdio 模式下退化为单一 "default" 桶（#513）。

联邦与冲突解决

联邦（federation）在 v4.0 引入，由 src/mind_mem/v4/federation_client.py 与 src/mind_mem/http_transport.py 实现。客户端使用 urllib.request.urlopen 直连运营者提供的 base_url（#529），但缺少：scheme 白名单、重定向上限、响应大小上限与 TLS pinning 保护。http_transport._handle_fed_resolve 接收调用方传入的 merged_payload 而不与冲突基线校验（#528），属严重安全问题。

detect_conflict → THREE_WAY_MERGE 流程在 federation.py:359-360 存在功能正确性缺陷：合并完成后未推进 vclock（#527），导致已解决冲突在下一轮 detect_conflict 中被重复识别。

已知问题摘要

Issue	严重度	组件	现象
#530	Medium	`sqlite_index.py:build_index`	80KB 工作区索引构建 ~55s
#529	High	`federation_client.py:240-251`	无 scheme/重定向/大小/TLS 保护
#528	Critical	`http_transport.py:687-694`	`_handle_fed_resolve` 不校验 merged_payload
#527	Critical	`federation.py:359-360`	THREE_WAY_MERGE 未推进 vclock
#526	Critical	`acl.py:139-142`	`_get_request_scope` 异常 fail-open
#515	—	`test_apply_engine.py:152`	macOS/Windows 上 rollback 测试失败
#513	Medium	`rate_limit.py:95-103`	stdio 共享单 bucket
#512	Medium	`governance.py`	`rationale`/`tags` 无长度上限
#511	Medium	`public.py:192`	rollback 静默丢弃 `reason`

存储后端、部署与运维

mind-mem 的存储层围绕一个可插拔的"块存储"(block store)抽象构建,工作区在初始化时根据配置选择一种后端类型,并通过统一的 getblockstore(ws) 接口对外暴露。memoryops.py 中的 ismarkdownbackend() 与 backendname() 是判断后端类型的核心工具:MARKDOWNBACKENDS 是合法 Markd...

章节 相关页面

继续阅读本节完整说明和来源证据。

1. 存储后端体系

mind-mem 的存储层围绕一个可插拔的"块存储"(block store)抽象构建,工作区在初始化时根据配置选择一种后端类型,并通过统一的 get_block_store(ws) 接口对外暴露。memory_ops.py 中的 _is_markdown_backend() 与 _backend_name() 是判断后端类型的核心工具:_MARKDOWN_BACKENDS 是合法 Markdown 后端名集合,凡是不在该集合内的后端(例如 Postgres)会被路由到存储层而非本地 .md 文件资料来源:[src/mind_mem/mcp/tools/memory_ops.py:1-60]。index_stats() 的统计逻辑也按这一分叉工作:Markdown 后端统计 CORPUS_DIRS 下的 .md 文件块数,而非 Markdown 后端则调用 store.get_all(active_only=False) 返回存储层活跃块数资料来源:[src/mind_mem/mcp/tools/memory_ops.py:60-120]。这一抽象使得同一份工具代码(MCP export_memory、index_stats、recall 等)既能运行在本地文件系统模式,也能运行在集中式数据库模式。

2. 索引与运维常见故障

工作区的全文检索能力依赖 fts_db_path(ws) 指向的本地 SQLite FTS 数据库;当该文件存在时,index_stats() 通过 sqlite_index.index_status(ws) 读取块数、最近构建时间、脏文件数和数据库大小,若 FTS 索引不存在则回退到目录扫描或存储层计数资料来源:[src/mind_mem/mcp/tools/memory_ops.py:60-120]。社区已报告两类与该层相关的运维问题:

构建性能回退:在 80KB 工作区上 sqlite_index.build_index 的 test_incremental_detects_in_place_edit_past_64kb 用例耗时约 55 秒,显著影响 CI 与开发迭代速度(Issue #530,影响 v4.0.8)。该回归位于 src/mind_mem/sqlite_index.py:build_index,根因仍在排查中。
Postgres 后端下的索引失效:在 PG 后端工作区上,mm recall 返回空集(#525)且 mm doctor --rebuild-cache 因本地 recall.db 缺少 blocks 表而对每个活跃块报错(#524)。底层根因是部分维护命令默认重建本地 SQLite 索引,而 PG 后端的真实数据源在远端。规避办法是先切换回 Markdown 后端或显式指定 --store=postgres 运行维护。

运维侧的 mm doctor/mm rebuild-cache 命令以及 index_stats MCP 工具应在任何后端类型变更后优先运行,以确认索引与底层存储一致。

3. 部署表面

mind-mem 通过三种主要表面向外提供能力:

表面	入口点	鉴权	适用场景
MCP stdio	`FastMCP("mind-mem")` (server.py)	ACL 白名单	AI 代理进程内调用
REST API	`api/rest.py` 的 `/v1/*`	Bearer token + `_require_auth`/`_require_admin`	跨进程/跨主机集成
CLI	`mm <subcommand>`	工作区文件权限	运维与一次性任务

server.py 在启动时按"资源先、工具后"的顺序注册所有 MCP 工具域(recall、audit、core、governance、arch_mind、benchmark、memory_ops 等) 资料来源:[src/mind_mem/mcp/server.py:40-80]。REST 端点通过 Depends(_rate_limit) 与 Depends(_require_admin) 实现限流与最小权限控制,例如 /v1/rollback_proposal 仅限管理员调用资料来源:[src/mind_mem/api/rest.py:1-60]。所有 MCP 工具调用前都会经过 mcp/infra/acl.py:check_tool_acl 检查 TOOL_WHITELIST 与 _ADMIN_SCOPES 集合资料来源:[src/mind_mem/mcp/infra/acl.py:1-80]。

4. 安全加固与失败模式

运维者必须了解几个已知的高优先级缺陷,以正确配置部署:

ACL 失败开放:_get_request_scope 在令牌内省异常时返回 "deny" 哨兵字符串,check_tool_acl 据此拒绝所有调用(Issue #526)。在补丁落地前,运维者应启用审计日志并监控异常令牌,以确保 fail-closed 语义资料来源:[src/mind_mem/mcp/infra/acl.py:80-160]。
arch-mind 子进程注入防护:所有传入 arch_* 工具的路径参数都会被 _validate_arch_path 检查非空、非 NUL、且不以 - 开头,防御参数被解析为标志位资料来源:[src/mind_mem/mcp/tools/arch_mind.py:1-80]。
模型签名路径:sign_model_tool 与 audit_model_tool 同样对 path 参数执行空值与 NUL 字节检查,签名操作要求显式提供 key_file 或 generate_key_prefix 之一,拒绝匿名临时密钥资料来源:[src/mind_mem/mcp/tools/model.py:1-100]。
平台相关测试:test_rollback_removes_new_files 在 macOS 与 Windows 上失败(仅 Linux 通过,Issue #515),表明涉及快照回滚的运维操作在非 Linux 环境需额外验证。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)

可能增加新用户试用和生产接入成本。

medium 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches

可能增加新用户试用和生产接入成本。

medium 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s

可能增加新用户试用和生产接入成本。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。

Pitfall Log / 踩坑日志

项目：star-ga/mind-mem

摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：PG-backed: mm doctor --rebuild-cache errors=263 (no such table: blocks)。

1. 安装坑 · 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: mm doctor --rebuild-cache errors=263 (no such table: blocks)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: mm recall returns [] despite direct PG FTS finding matches
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安装坑 · 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

6. 维护坑 · 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

严重度：medium
证据强度：source_linked
发现：no_demo
证据：downstream_validation.risk_items | https://github.com/star-ga/mind-mem | no_demo; severity=medium

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

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

10. 安全/权限坑 · 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL _get_request_scope fail-open on token-introspection exception (acl.py:139-142)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-251)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/529 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。

16. 安全/权限坑 · 来源证据：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/511 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)
对用户的影响：可能增加新用户试用和生产接入成本。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport…

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：_handle_fed_resolve accepts caller-supplied merged_payload without validating it against the conflict (http_transport.py:687-694)
对用户的影响：可能影响授权、密钥配置或安全边界。
证据：community_evidence:github | https://github.com/star-ga/mind-mem/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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

来源：Doramagic 发现、验证与编译记录

mind-mem 项目

概览与系统架构

1. 项目定位与核心目标

2. 分层架构

3. 关键子系统概览

3.1 检索与索引（Recall & Index）

3.2 治理与提议（Governance）

3.3 审计、血缘与编译真值（Audit / Lineage / Compiled Truth）

3.4 辅助能力

4. 横切关注点与已知架构风险

See Also

检索管线与 Recall 核心

概述

Recall 工具族

后端与索引管线

已知问题与性能观察

See Also

治理、MCP 工具与联邦

概述

治理工作流

MCP 工具基础设施

访问控制（ACL）

工具域划分

REST 暴露

联邦与冲突解决

已知问题摘要

See Also

存储后端、部署与运维

1. 存储后端体系

2. 索引与运维常见故障

3. 部署表面

4. 安全加固与失败模式

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安装坑 · 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)

2. 安装坑 · 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches

3. 安装坑 · 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s

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

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

6. 维护坑 · 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)

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

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

10. 安全/权限坑 · 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)

11. 安全/权限坑 · 来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…

12. 安全/权限坑 · 来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)

13. 安全/权限坑 · 来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)

14. 安全/权限坑 · 来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field

15. 安全/权限坑 · 来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket

16. 安全/权限坑 · 来源证据：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'

17. 安全/权限坑 · 来源证据：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)

18. 安全/权限坑 · 来源证据：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport…

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

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