项目概述

MIND-Mem 是一个用于 AI 代理的结构化记忆与推理框架，它为多代理协作场景提供持久化记忆存储、检索和治理能力。该项目基于文件系统存储，采用 Markdown 格式管理记忆块，并通过 MCP（Model Context Protocol）协议对外提供服务接口。

MIND-Mem 的核心设计理念是：记忆永不直接修改，只能通过治理流程变更。这一 invariant 确保了记忆系统的完整性和可审计性。

资料来源：SPEC.md

系统架构

整体架构图

graph TD
    subgraph 用户层
        CLI[CLI工具<br/>mm命令]
        MCP[MCP客户端]
        Web[Web控制台]
        API[REST API]
    end
    
    subgraph MCP服务层
        MS[MCP Server<br/>mcp_server.py]
        KERNEL[Kernel工具]
        GOVERNANCE[治理工具]
        AUDIT[审计工具]
        MEMORY[内存操作工具]
    end
    
    subgraph 核心存储层
        FTS[FTS5全文索引]
        BLOCKS[记忆块文件<br/>.md格式]
        CT[Compiled Truth<br/>编译真相页]
        LEDGER[多代理事实账本]
    end
    
    CLI --> MS
    MCP --> MS
    Web --> API
    API --> MS
    MS --> FTS
    MS --> BLOCKS
    MS --> CT
    MS --> LEDGER

核心组件

资料来源：mm_cli.py:1-20

核心功能

2.1 记忆检索与上下文管理

MIND-Mem 提供多种检索方式满足不同场景需求：

#### CLI命令接口

mm recall "<query>"              # BM25语义搜索
mm context "<query>"            # 生成token预算受限的片段
mm inject --agent <name> "<q>"  # 为特定代理渲染片段
mm vault scan <vault_root>      # 列出解析的vault块
mm status                       # 工作区摘要

资料来源：mm_cli.py:1-20

#### MCP资源接口

资料来源：mcp/resources.py:1-50

2.2 编译真相系统

编译真相（Compiled Truth）是 MIND-Mem 的核心知识沉淀机制：

graph LR
    subgraph 证据收集
        MD1[memory/xxx.md]
        MD2[memory/yyy.md]
        MD3[DECISIONS.md]
    end
    
    subgraph 处理流程
        SC[句子提取]
        NORM[规范化]
        COUNT[出现计数]
    end
    
    subgraph 真相页生成
        CT[Compiled Truth Page<br/>compiled/xxx.md]
        ENTRY[Evidence Entry<br/>证据条目]
    end
    
    MD1 --> SC
    MD2 --> SC
    MD3 --> SC
    SC --> NORM
    NORM --> COUNT
    COUNT -->|min_mentions≥3| CT
    CT --> ENTRY

核心特性：

• 自动从多个 Markdown 文件中提取和聚合事实
• 支持证据条目的时间戳、来源和置信度
• 提供 recompilation 重新编译功能
• 支持证据条目的 superseded 标记

资料来源：compiled_truth.py:1-100

2.3 治理与审计

MIND-Mem 遵循"记忆永不直接修改，只通过治理变更"的原则：

#### 治理工具集

资料来源：mcp/tools/governance.py:1-60

#### 审计工具集

资料来源：mcp/tools/audit.py:1-40

2.4 质量门控

质量门（Quality Gate）是预存储过滤器，确保进入系统的记忆块符合标准：

graph TD
    INPUT[候选记忆块] --> QG{质量门}
    QG --> E1{空块?}
    QG --> E2{过短?}
    QG --> E3{过大?}
    QG --> E4{UTF-8错误?}
    QG --> E5{仅停用词?}
    QG --> E6{近似重复?}
    QG --> E7{注入标记?}
    QG --> OK[通过]
    E1 -->|是| LOG1[日志记录]
    E2 -->|是| LOG2[日志记录]
    E3 -->|是| LOG3[日志记录]
    E4 -->|是| LOG4[日志记录]
    E5 -->|是| LOG5[日志记录]
    E6 -->|是| LOG6[日志记录]
    E7 -->|是| LOG7[日志记录]
    LOG1 --> OK
    LOG2 --> OK
    LOG3 --> OK
    LOG4 --> OK
    LOG5 --> OK
    LOG6 --> OK
    LOG7 --> OK

八条质量规则：

支持 strict=True 模式，所有规则均变为硬性拒绝。

资料来源：quality_gate.py:1-50

MCP工具分类

3.1 Kernel工具

提供对 .mind 内核配置文件的读写访问：

• list_mind_kernels — 列出可用内核
• get_mind_kernel — 获取特定内核配置
• compiled_truth_load — 加载真相页
• compiled_truth_add_evidence — 添加证据
• compiled_truth_contradictions — 检测矛盾

资料来源：mcp/tools/kernels.py:1-40

3.2 内存操作工具

工作区生命周期和内省接口：

• index_stats / reindex — FTS5索引状态和重建
• delete_memory_item — 原子性记忆块删除
• export_memory — JSONL格式导出
• get_block / memory_health — 块查询和健康仪表盘
• compact / stale_blocks — 压缩和陈旧块管理

资料来源：mcp/tools/memory_ops.py:1-60

3.3 架构思维工具

整合 arch-mind 二进制工具作为 MCP 工具：

• arch_baseline — 初始化基准
• arch_delta — 计算delta分数
• arch_history — 列出历史事件
• arch_check_rules — 应用规则检查
• arch_session_start / arch_session_end — 会话管理
• arch_metric_explain — 指标分解

资料来源：mcp/tools/arch_mind.py:1-50

工作区结构

{workspace}/
├── DECISIONS.md          # 活动决策
├── TASKS.md              # 任务列表
├── SIGNALS.md            # 待审查信号
├── memory/               # 记忆块存储
│   ├── *.md
│   └── ...
├── entities/
│   └── compiled/         # 编译真相页
│       └── *.md
├── .mind/                # 内核配置
│   └── *.mind
└── index.db              # FTS5全文索引

Web控制台

基于 Next.js 的可视化界面，提供三种视图：

graph TD
    subgraph Web控制台
        SUBMIT[查询提交]
        API[REST API调用]
        subgraph 三面板展示
            GRAPH[力导向图<br/>GraphView]
            TIMELINE[时间轴<br/>TimelineView]
            FACTS[事实列表<br/>FactList]
        end
    end
    
    SUBMIT --> API
    API --> GRAPH
    API --> TIMELINE
    API --> FACTS

启动方式：

cd web
pnpm install
pnpm dev  # → http://localhost:3000

资料来源：web/README.md:1-40

快速开始

安装

pip install -e .

CLI基本用法

# 初始化工作区
export MIND_MEM_WORKSPACE=/path/to/workspace

# 搜索记忆
mm recall "PostgreSQL决策历史"

# 生成上下文
mm context "最近的架构变更"

# 注入特定代理上下文
mm inject --agent claude "当前项目技术栈"

API使用

from mind_mem import recall

results = recall("/path/to/workspace", "query", limit=10)

v4.0 预览

MIND-Mem v4.0 正在开发中，带来以下新特性（当前默认关闭，需通过 mind-mem.json 开启）：

资料来源：v4/__init__.py:1-50

总结

MIND-Mem 是一个设计严谨的 AI 记忆框架，通过以下核心机制保障系统的可靠性和可追溯性：

1. 文件系统优先 — Markdown格式存储，便于版本控制和人类阅读
2. 治理驱动变更 — 记忆只能通过正式提案→审批流程修改
3. 多协议支持 — 同时提供CLI、MCP和REST API接口
4. 质量门控 — 预存储过滤器确保数据质量
5. 可审计性 — Merkle证明和哈希链验证数据完整性

1. 系统架构总览

mind-mem 采用分层架构设计，核心组件包括：

graph TD
    subgraph "接口层"
        CLI[CLI 命令行工具<br/>mm]
        MCP[MCP 服务器<br/>Model Context Protocol]
        REST[REST API<br/>v3.2.0+]
    end
    
    subgraph "功能域"
        RECALL[召回 Recall]
        GOV[治理 Governance]
        CONSOL[记忆整合 Consolidation]
        MEMOPS[记忆操作 Memory Ops]
    end
    
    subgraph "核心引擎"
        FTS[FTS5 全文索引]
        BLOCK[Block Parser]
        COMPILED[Compiled Truth]
        COGNITIVE[认知遗忘 Cognitive Forget]
    end
    
    subgraph "存储层"
        WORKSPACE[Workspace 目录]
        MIND[MIND 内核配置]
        DB[(SQLite FTS5)]
    end
    
    CLI --> RECALL
    MCP --> RECALL
    MCP --> GOV
    MCP --> CONSOL
    MCP --> MEMOPS
    
    RECALL --> FTS
    GOV --> BLOCK
    CONSOL --> COGNITIVE
    
    FTS --> DB
    BLOCK --> WORKSPACE
    COMPILED --> WORKSPACE
    COGNITIVE --> WORKSPACE

2. MCP 工具集

MCP（Model Context Protocol）服务器提供标准化工具接口，支持 Claude Code、Codex CLI、Cursor、Windsurf 等 AI 客户端直接调用记忆功能。工具按功能域分为以下类别：

2.1 KERNELS 域 — MIND 内核配置

负责管理和配置召回、排序和管道参数的内核文件访问。

内核配置控制项包括：

• 召回权重调优（recall tuning）
• 重排序参数（reranking）
• RM3 扩展配置
• 管道级联参数

2.2 GOVERNANCE 域 — 治理与生命周期

治理域是"记忆永不直接修改"原则的核心实现，所有变更必须经过治理流程。

治理工作流：

graph LR
    A[propose_update<br/>提案阶段] --> B{SIGNALS.md}
    B --> C[人工审核]
    C --> D{approve_apply<br/>批准应用}
    D -->|干运行 OK| E[正式应用]
    D -->|发现问题| F[rollback_proposal<br/>回滚]
    E --> G[区块更新]
    F --> H[快照恢复]

2.3 CONSOLIDATION 域 — 记忆整合

"记忆随时间沉淀"表面，实现认知遗忘和自动整合机制。

2.4 MEMORY_OPS 域 — 记忆操作

工作区生命周期和内省操作，处理索引、删除、导出等管理任务。

2.5 BENCHMARK 域 — 基准测试

2.6 ARCH_MIND 域 — 架构知识管理

包装 arch-mind 二进制工具，提供架构基线、历史记录、规则检查和会话管理。

3. CLI 命令行工具

mm 命令提供 MCP 之外的轻量级接口，适用于非 MCP 智能体。

mm recall "<query>"             # 搜索记忆
mm context "<query>"            # 生成预算限制的片段
mm inject --agent <name> "<q>"  # 为特定智能体渲染片段
mm vault scan <vault_root>      # 列出解析的 vault 块
mm vault write <vault_root> <id> --type <t> --body <b>
mm status                       # 工作区摘要
mm trace --live                  # 实时流式 MCP 调用日志
mm trace --last 20 --tool xxx    # 最近 N 次工具调用

资料来源：mm_cli.py:1-50

4. 编译事实系统

编译事实（Compiled Truth）是按实体聚合证据并重新编译权威理解的关键机制。

4.1 核心概念

graph TD
    subgraph "来源"
        SOURCE1[memory/决策A.md]
        SOURCE2[memory/任务B.md]
        SOURCE3[memory/事件C.md]
    end
    
    subgraph "候选提取"
        SENTENCE[句子提取<br/>频率≥3]
        CANDIDATE[事实候选]
    end
    
    subgraph "编译事实页"
        ENTITY[实体标识]
        EVIDENCE[证据条目列表]
        CANONICAL[权威摘要]
        VERSION[版本号]
        LAST_COMPILED[最后编译时间]
    end
    
    SOURCE1 --> SENTENCE
    SOURCE2 --> SENTENCE
    SOURCE3 --> SENTENCE
    SENTENCE --> CANDIDATE
    CANDIDATE --> EVIDENCE
    EVIDENCE --> CANONICAL
    CANONICAL --> ENTITY

4.2 编译事实数据结构

4.3 关键函数

5. MCP 资源声明

通过 @mcp.resource 暴露只读视图，提供工作区信息的统一访问：

资料来源：resources.py:1-50

6. 模型溯源系统

model_provenance.py 定义了发布商注册表和来源发现机制：

资料来源：model_provenance.py:1-80

7. v4.0 功能预览

v4.0 采用显式功能开关设计，默认关闭以保持 v3.x 行为兼容。

graph TD
    subgraph "v4.0 功能门"
        CONFIG[mind-mem.json<br/>v4 feature flag]
    end
    
    subgraph "A. 认知/模型层"
        TIER[tier-aware block schema]
        COG_KRN[Cognitive Mind Kernel API]
        SURPRISE[surprise-weighted retrieval]
    end
    
    subgraph "B. 知识图谱"
        KINDS[entity/concept kinds]
        LONG_CTX[long-context recall]
        FUSION[LLM-driven fusion]
        STREAM[streaming recall]
        CHAT[conversational chat]
        PROMPT_SCHEMA[prompt schema]
    end
    
    subgraph "C. 治理/UX"
        IDLE[idle-only ingest]
        LINT[AI lint + auto-fix]
        CONTRAD[contradiction state machine]
        SELF_HEAL[self-healing index]
    end
    
    CONFIG --> TIER
    CONFIG --> KINDS
    CONFIG --> IDLE

资料来源：v4/__init__.py:1-40

8. 智能体集成

mind-mem 支持多种 AI 编码客户端集成，通过 hook_installer.py 管理：

MCP 服务器路径解析优先级：

1. MIND_MEM_MCP_SERVER 环境变量
2. <package_dir>/../mcp_server.py（源码检出布局）
3. <package_dir>/mcp_server.py（打包安装布局）

资料来源：hook_installer.py:1-50

9. 观察压缩

observation_compress.py 实现记忆压缩专家系统，支持多种查询类型：

资料来源：observation_compress.py:1-60

10. 总结

mind-mem 的核心功能可归纳为以下维度：

所有核心功能均通过 MCP 工具接口或 CLI 提供，确保与主流 AI 编码客户端的广泛兼容性。

1. 整体架构概览

mind-mem 采用分层架构设计，核心由 MCP 服务层、记忆操作层、数据持久化层和治理审计层组成。

graph TD
    subgraph 客户端层
        CLAUDE["Claude Code"]
        COPILOT["GitHub Copilot"]
        CODY["Sourcegraph Cody"]
        QODO["Qodo Gen"]
    end
    
    subgraph 接口层
        MCP["MCP Server<br/>(mcp_server.py)"]
        CLI["CLI 工具<br/>(mm)"]
        WEB["Web 控制台<br/>(Next.js)"]
    end
    
    subgraph 服务层
        RECALL["Recall API"]
        GOVERNANCE["Governance Tools"]
        AUDIT["Audit Tools"]
        CONSOLIDATION["Consolidation Tools"]
        KERNELS["Mind Kernel Tools"]
    end
    
    subgraph 数据层
        FTS["FTS5 全文索引"]
        HASH["Hash Chain v2"]
        EVIDENCE["Evidence Chain"]
        TRUTH["Compiled Truth"]
    end
    
    subgraph 持久化层
        MARKDOWN["Markdown 记忆文件"]
        SQLITE["SQLite 数据库"]
        CORPUS["语料库目录"]
    end
    
    CLIENTS[AI 客户端] --> MCP
    CLIENTS --> CLI
    MCP --> RECALL
    MCP --> GOVERNANCE
    MCP --> AUDIT
    CLI --> RECALL
    RECALL --> FTS
    FTS --> MARKDOWN
    GOVERNANCE --> HASH
    GOVERNANCE --> EVIDENCE
    AUDIT --> TRUTH

2. MCP 服务架构

MCP (Model Context Protocol) 是 mind-mem 的核心对外接口协议。系统将 MCP 服务分解为多个工具域，每个域对应特定的功能模块。

2.1 工具域划分

2.2 MCP 资源声明

MCP 服务还暴露一组只读资源，提供对工作区记忆的查询视图：

graph LR
    R1["mind-mem://decisions<br/>决策记录"]
    R2["mind-mem://tasks<br/>任务列表"]
    R3["mind-mem://entities/{type}<br/>实体查询"]
    R4["mind-mem://signals<br/>信号数据"]
    R5["mind-mem://contradictions<br/>矛盾检测"]
    R6["mind-mem://health<br/>健康状态"]
    R7["mind-mem://recall/{query}<br/>BM25 检索"]
    R8["mind-mem://ledger<br/>多智能体账本"]

资料来源：src/mind_mem/mcp/resources.py:1-30

2.3 MCP 服务启动流程

# 资料来源：src/mind_mem/hook_installer.py
def mcp_server_spec(workspace: str) -> dict[str, Any]:
    """生成 MCP 服务调用规范"""
    return {
        "command": _sys.executable or "python3",
        "args": [_mcp_server_path()],
        "env": {"MIND_MEM_WORKSPACE": workspace},
    }

MCP 服务器路径按以下优先级解析：

1. MIND_MEM_MCP_SERVER 环境变量（显式覆盖）
2. <package_dir>/../mcp_server.py（源码 checkout 布局）
3. <package_dir>/mcp_server.py（打包安装布局）

资料来源：src/mind_mem/hook_installer.py

3. CLI 工具架构

mm 是面向非 MCP 智能体的统一 CLI 工具，提供命令行记忆操作能力。

3.1 CLI 子命令

资料来源：src/mind_mem/mm_cli.py:1-25

3.2 工作区解析

def _workspace() -> str:
    ws = os.environ.get("MIND_MEM_WORKSPACE", "").strip()
    if not ws:
        ws = os.getcwd()
    return os.path.realpath(ws)

工作区路径通过 MIND_MEM_WORKSPACE 环境变量或当前工作目录确定。

4. 记忆检索系统

4.1 Recall API

Recall 是核心检索引擎，支持 BM25 全文搜索和上下文感知记忆提取。

graph TD
    Q["查询输入"] --> PARSE["查询解析"]
    PARSE --> FTS["FTS5 索引查询"]
    FTS --> RERANK["重排序"]
    RERANK --> PACK["预算打包<br/>(pack_to_budget)"]
    PACK --> RESULT["记忆片段"]
    
    subgraph 记忆来源
        MEMORY["memory/ 目录"]
        TASKS["TASKS.md"]
        DECISIONS["DECISIONS.md"]
    end
    
    FTS --> MEMORY
    FTS --> TASKS
    FTS --> DECISIONS

4.2 记忆类型映射

记忆文件使用特定前缀标识类型：

5. 治理与决策系统

5.1 治理原则

mind-mem 遵循"记忆仅通过治理修改"的不变性原则。所有记忆变更必须经过提议、审批、生效的完整治理流程。

stateDiagram-v2
    [*] --> SIGNAL: propose_update
    SIGNAL --> REVIEW: 提交提案
    REVIEW --> APPROVED: approve_apply
    REVIEW --> REJECTED: 拒绝/超时
    APPROVED --> ACTIVE: 写入记忆
    ACTIVE --> SUPERSEDED: rollback_proposal
    SUPERSEDED --> [*]

资料来源：src/mind_mem/mcp/tools/governance.py:1-30

5.2 治理工具集

6. 编译真相系统 (Compiled Truth)

6.1 系统设计

编译真相系统通过聚合证据来维护实体的规范理解，支持基于句子级出现频率的事实提取。

# 资料来源：src/mind_mem/compiled_truth.py
def extract_common_facts(workspace: str, min_mentions: int = 3) -> list[dict]:
    """从 memory/ 目录提取高频事实"""
    # 1. 遍历所有 .md 文件
    # 2. 句子级分词
    # 3. 统计归一化后的句子出现次数
    # 4. 返回出现 >= min_mentions 次的事实

6.2 真相页结构

每个真相页维护以下数据结构：

6.3 证据管理

graph LR
    E1["新证据"] --> VALIDATE["验证"]
    VALIDATE --> ADD["添加证据"]
    ADD --> COMPILE["重新编译"]
    COMPILE --> SUMMARY["生成摘要"]
    
    E2["旧证据"] --> SUPERSEDE["标记 superseded"]
    SUPERSEDE --> COMPILE

7. 完整性审计系统

7.1 审计层设计

审计系统通过哈希链和默克尔树保证记忆的不可篡改性。

7.2 验证工具

7.3 验证退出码

资料来源：src/mind_mem/verify_cli.py:1-45

8. 智能体集成系统

8.1 支持的智能体

资料来源：src/mind_mem/hook_installer.py

8.2 集成机制

graph TD
    INSTALL["hook_installer"] --> DETECT["检测智能体"]
    DETECT --> SPEC["生成 AgentSpec"]
    SPEC --> WRITE["写入配置文件"]
    WRITE --> PREPEND["注入记忆锚点"]
    
    PREPEND --> QUERY["mm inject --agent <name>"]
    QUERY --> CONTEXT["返回记忆上下文"]

8.3 智能体规范定义

@dataclass(frozen=True)
class AgentSpec:
    name: str                    # 智能体键名
    description: str             # 人类可读描述
    config_fmt: str              # 配置格式 (json-claude/path-toml/text-block)
    path_tmpl: str               # 配置文件路径模板
    content_tmpl: str            # 注入内容模板
    always_offer: bool           # 是否自动推荐
    detect_paths: tuple          # 检测路径
    detect_binaries: tuple       # 检测二进制

9. 记忆操作工具

9.1 索引操作

9.2 生命周期管理

9.3 导出功能

def export_memory(
    max_items: int = 10000,
    include_metadata: bool = True,
    max_size_mb: int = 50
) -> str:
    """导出所有记忆块为 JSONL 格式"""

资料来源：src/mind_mem/mcp/tools/memory_ops.py:1-40

10. 记忆整合系统

10.1 认知遗忘周期

graph TD
    START["开始整合"] --> CONFIG["ConsolidationConfig"]
    CONFIG --> SCORE["BlockCognition 评分"]
    SCORE --> THRESHOLD{"重要度阈值?"}
    THRESHOLD -->|高| KEEP["保留"]
    THRESHOLD -->|低| STALE["标记陈旧"]
    STALE --> AGE{"超过归档天数?"}
    AGE -->|是| ARCHIVE["归档"]
    AGE -->|否| GRACE["宽限期"]
    KEEP --> COMPLETE["完成"]
    ARCHIVE --> COMPLETE
    GRACE --> COMPLETE

10.2 整合工具

资料来源：src/mind_mem/mcp/tools/consolidation.py:1-30

11. v4.0 架构演进

v4.0 作为架构演进版本，默认关闭，通过 feature flag 启用。

11.1 功能组映射

资料来源：src/mind_mem/v4/__init__.py:1-50

11.2 特征门控

class FeatureDisabledError(Exception):
    """v4 功能未启用时抛出"""
    pass

所有 v4.0 功能均需在 mind-mem.json 配置文件的 v4 键下显式启用。

12. 完整性保护机制

12.1 关键模块保护

系统维护一份关键模块清单，用于完整性验证：

资料来源：src/mind_mem/protection.py:30-50

12.2 完整性报告

@dataclass(frozen=True)
class IntegrityReport:
    ok: bool
    module: str
    expected_hash: str
    actual_hash: str

13. Web 控制台架构

mind-mem 提供基于 Next.js 的 Web 控制台，提供可视化记忆查询界面。

graph LR
    API["REST API<br/>/v1/recall<br/>/v1/health"] --> PAGE["app/page.tsx"]
    PAGE --> GRAPH["GraphView<br/>(d3-force)"]
    PAGE --> TIMELINE["TimelineView"]
    PAGE --> FACTS["FactList"]
    
    GRAPH --> NODES["节点: 按状态着色"]
    GRAPH --> EDGES["边: 按谓词着色"]

组件说明：

资料来源：web/README.md

14. 依赖关系总览

graph BT
    subgraph 核心依赖
        BLOCK["block_parser"]
        FTS["sqlite_index<br/>(FTS5)"]
        COGNITIVE["cognitive_forget"]
    end
    
    subgraph MCP 工具
        GOVERNANCE["governance.py"]
        AUDIT["audit.py"]
        MEMORY_OPS["memory_ops.py"]
        CONSOLIDATION["consolidation.py"]
    end
    
    subgraph 基础设施
        OBSERVE["observability"]
        CONFIG["config"]
        WORKSPACE["workspace"]
    end
    
    MCP["mcp_server.py"] --> GOVERNANCE
    MCP --> AUDIT
    MCP --> MEMORY_OPS
    MCP --> CONSOLIDATION
    
    GOVERNANCE --> BLOCK
    GOVERNANCE --> FTS
    AUDIT --> BLOCK
    MEMORY_OPS --> FTS
    CONSOLIDATION --> COGNITIVE
    
    BLOCK --> FTS
    COGNITIVE --> FTS

15. 总结

mind-mem 的系统架构围绕以下核心设计原则构建：

1. 协议分离：通过 MCP 协议将核心功能暴露给 AI 客户端，CLI 作为补充
2. 治理优先：所有记忆修改必须经过治理流程，保证可追溯性
3. 完整性保证：多层审计机制（哈希链、默克尔树、证据链）确保记忆不可篡改
4. 智能体无关：通过可扩展的 hook 系统支持多种 AI 编码助手
5. 演进能力：v4.0 架构通过 feature flag 逐步引入新功能，不影响现有系统

概述

数据流与处理管道是 mind-mem 系统的核心组成部分，负责管理从数据捕获、存储、处理到检索的完整生命周期。该管道遵循"内存永不直接修改，只能通过治理机制变更"的核心不变量，确保所有数据变更都经过审批和追踪流程。

整体架构

graph TD
    subgraph 数据捕获层
        CAPT[数据捕获]
        SIG[信号生成]
    end

    subgraph 存储抽象层
        BS[BlockStore 抽象]
        MB[MarkdownBlockStore]
        PG[PostgresBlockStore]
        ES[EncryptedBlockStore]
    end

    subgraph 处理引擎层
        APPLY[ApplyEngine]
        SNAP[快照管理]
        DIFF[差异计算]
    end

    subgraph 治理层
        PROP[提案机制]
        APPROVE[审批应用]
        ROLLBACK[回滚机制]
    end

    subgraph 检索层
        RECALL[Recall 检索]
        BM25[BM25 检索]
        VECTOR[向量检索]
        HYBRID[混合检索]
    end

    CAPT --> BS
    SIG --> BS
    BS --> APPLY
    APPLY --> SNAP
    APPLY --> DIFF
    PROP --> APPROVE
    APPROVE --> ROLLBACK
    RECALL --> BM25
    RECALL --> VECTOR
    RECALL --> HYBRID

核心组件

BlockStore 抽象层

BlockStore 是数据持久化的核心抽象，支持多种后端实现：

资料来源：src/mind_mem/apply_engine.py:1-50

ApplyEngine 处理引擎

ApplyEngine 负责数据变更的实际执行，提供快照、回滚和差异对比功能：

def _store_for(ws) -> BlockStore:
    """根据配置获取对应的 BlockStore 实现"""
    
def create_snapshot(ws, ts, files_touched=None) -> str:
    """创建应用前快照，返回快照目录路径"""

def restore_snapshot(ws, snap_dir) -> None:
    """从快照目录恢复工作空间"""

def snapshot_diff(ws, snap_dir) -> list[str]:
    """返回当前工作空间与快照的差异文件列表"""

资料来源：src/mind_mem/apply_engine.py:30-55

数据流阶段

阶段一：数据捕获

数据捕获层负责收集外部信号和用户输入，生成标准化的 Block 结构：

graph LR
    A[外部输入] --> B[Capture 模块]
    B --> C[Block 结构化]
    C --> D[信号写入]
    D --> E[SIGNALS.md]

关键流程：

1. 接收外部数据源（CLI、API、MCP 工具）
2. 解析为标准 Block 格式
3. 写入 SIGNALS.md 待审批队列

阶段二：存储抽象

存储层根据配置选择合适的持久化后端：

graph TD
    A[写入请求] --> B{配置检查}
    B -->|passphrase 设置| C[EncryptedBlockStore]
    B -->|postgres 配置| D[PostgresBlockStore]
    B -->|默认| E[MarkdownBlockStore]
    C --> F[加密后写入]
    D --> G[SQL 写入]
    E --> H[Markdown 文件写入]

资料来源：src/mind_mem/block_store.py:1-80

阶段三：检索与召回

Recall 模块提供多种检索策略：

资料来源：src/mind_mem/recall.py:1-60

治理与变更流程

提案-审批模式

所有数据变更必须通过治理机制：

sequenceDiagram
    participant U as 用户
    participant P as 提案模块
    participant A as ApplyEngine
    participant S as 快照
    participant R as 检索系统

    U->>P: propose_update(block_type, statement)
    P->>P: 生成 SIGNAL
    P->>S: create_snapshot(ws, timestamp)
    Note over S: 创建预应用快照
    U->>A: approve_apply(signal_id)
    A->>S: snapshot_diff()
    A->>R: 更新索引
    Note over A: 应用变更

回滚机制

当变更需要撤销时，系统通过快照恢复：

# 回滚流程
snap_dir = create_snapshot(ws, ts)  # 变更前创建快照
# ... 执行变更 ...
restore_snapshot(ws, snap_dir)      # 需要回滚时恢复

资料来源：src/mind_mem/apply_engine.py:40-50

编译真相机制

Compiled Truth 模块负责证据聚合和事实编译：

graph TD
    A[原始证据] --> B[EvidenceEntry 解析]
    B --> C[证据池累积]
    C --> D[检测矛盾]
    D -->|无矛盾| E[recompile_truth]
    D -->|存在矛盾| F[矛盾标记]
    E --> G[CompiledTruthPage]

关键函数：

• add_evidence(): 向真相页添加新证据
• recompile_truth(): 重新编译真相摘要
• detect_contradictions(): 检测证据矛盾

资料来源：src/mind_mem/compiled_truth.py:1-100

MCP 工具集成

MCP 工具层提供外部系统交互接口：

资料来源：src/mind_mem/mcp/tools/kernels.py:1-50

配置参数

BlockStore 配置

在 mind-mem.json 中的配置结构：

{
  "block_store": {
    "backend": "markdown|postgres|encrypted",
    "passphrase": "<加密密钥>",
    "connection": "<Postgres 连接字符串>"
  }
}

检索配置

错误处理与容错

系统采用分层错误处理策略：

1. BlockStore 层：异常时回退到 MarkdownBlockStore 默认实现
2. ApplyEngine 层：快照操作失败时记录日志但不阻断主流程
3. Recall 层：单一检索失败时尝试降级到其他策略

try:
    return get_block_store(ws)
except Exception:
    return MarkdownBlockStore(ws)  # 降级保底

资料来源：src/mind_mem/apply_engine.py:40-45

性能考量

• 快照开销：create_snapshot 在变更频繁场景下可能产生 IO 压力
• 检索延迟：混合检索模式需要并行执行 BM25 和向量检索
• 存储选择：Postgres 后端适合高并发写入场景，Markdown 适合简单部署

架构概述

存储后端系统采用工厂模式（Factory Pattern）进行后端实例化。get_block_store() 工厂函数根据工作区配置动态选择合适的存储实现。

graph TD
    A[应用层代码] --> B[get_block_store 工厂函数]
    B --> C{mind-mem.json 配置}
    C -->|backend: markdown| D[MarkdownBlockStore]
    C -->|backend: encrypted| E[EncryptedBlockStore 包装器]
    C -->|backend: postgres| F[PostgresBlockStore]
    E --> D
    F --> G[(PostgreSQL 数据库)]
    D --> H[/workspace/memory/\*.md]

资料来源：src/mind_mem/storage/__init__.py:53-70

支持的后端类型

资料来源：src/mind_mem/storage/__init__.py:55-68

工厂函数 API

get_block_store(workspace, config=None)

storage/__init__.py 中定义的工厂函数，负责根据配置实例化正确的后端。

函数签名：

def get_block_store(workspace: str, config: dict[str, Any] | None = None) -> BlockStore:

参数说明：

返回值：

返回 BlockStore 实例（MarkdownBlockStore、EncryptedBlockStore 或 PostgresBlockStore）。

异常处理：

资料来源：src/mind_mem/storage/__init__.py:30-50

配置读取逻辑

工厂函数首先尝试从工作区目录加载 mind-mem.json 配置文件：

def _load_workspace_config(workspace: str) -> dict[str, Any]:
    config_path = os.path.join(workspace, "mind-mem.json")
    if os.path.isfile(config_path):
        with open(config_path, encoding="utf-8") as f:
            return json.load(f)
    return {}

如果配置文件不存在或解析失败，返回空字典，工厂函数将使用默认值 markdown。

资料来源：src/mind_mem/storage/__init__.py:16-28

核心接口：BlockStore

BlockStore 是所有存储后端的基类，定义了统一的存储操作接口。关键方法包括快照管理，这是实现"内存永不直接修改"治理不变量的基础。

快照操作

快照机制是 apply_engine 实现回滚功能的核心。当需要修改工作区内容时，系统首先创建快照，然后对快照进行操作，验证通过后才正式应用。

sequenceDiagram
    participant AE as ApplyEngine
    participant BS as BlockStore
    participant WS as Workspace
    participant SNAP as Snapshot Dir

    AE->>BS: create_snapshot(ws, ts)
    BS->>WS: 读取当前文件
    WS-->>BS: 文件内容
    BS->>SNAP: 写入快照目录
    Note over BS: Markdown: 复制文件树<br/>Postgres: SQL 转储
    BS-->>AE: snap_dir 路径

资料来源：src/mind_mem/apply_engine.py:26-38

Markdown 后端

MarkdownBlockStore 是默认存储后端，将每个块存储为独立的 Markdown 文件。

存储结构

workspace/
├── memory/
│   ├── decisions/
│   │   └── D-20260213-001.md
│   ├── tasks/
│   │   └── T-20260213-001.md
│   └── signals/
│       └── S-20260213-001.md
└── intelligence/
    └── applied/
        └── 20260213-120000/  # 快照目录

块格式规范

每个 Markdown 块遵循固定格式，包含标识头和键值对字段：

[ID]
Statement: 决策内容描述
Date: 2026-02-13
Status: active
Confidence: high
Tags: architecture, backend

[ID]

CANONICAL_FIELD_ORDER 定义了字段的标准顺序，确保块序列化的一致性：

_CANONICAL_FIELD_ORDER: tuple[str, ...] = (
    "Statement", "Date", "Status", "Priority", "Risk",
    "Type", "Subject", "Object", "Tags", "Rationale",
    "Evidence", "Source", "Confidence", "ContentHash",
    "Excerpt", "Action",
)

资料来源：src/mind_mem/block_store.py:75-90

PostgreSQL 后端

PostgresBlockStore 为企业级部署提供关系数据库存储能力。适用于需要事务支持、并发访问和高可用性的生产环境。

配置示例

{
  "block_store": {
    "backend": "postgres",
    "dsn": "postgresql://user:password@localhost:5432/mindmem"
  }
}

与 Markdown 后端的差异

加密存储包装器

EncryptedBlockStore 是一个包装器后端，它在底层 Markdown 后端基础上添加加密功能。当设置了 MIND_MEM_ENCRYPTION_PASSPHRASE 环境变量时，存储模块会自动返回加密包装后的实例。

资料来源：src/mind_mem/storage/__init__.py:65-67

在 Apply Engine 中的应用

apply_engine 模块通过 _store_for(ws) 函数获取当前配置的 BlockStore 实例，所有存储操作都通过该实例进行路由：

def _store_for(ws):
    try:
        from .storage import get_block_store
        return get_block_store(ws)
    except Exception:
        return MarkdownBlockStore(ws)  # 容错降级

这种设计确保了 apply_engine 的韧性：在首次运行或配置错误的工作区，系统会优雅降级到默认的 Markdown 后端。

资料来源：src/mind_mem/apply_engine.py:20-26

删除日志

当块被删除时，后端会将删除收据写入 memory/deleted_blocks.jsonl 文件：

{"block_id": "D-20260213-001", "deleted_at": "2026-02-13T12:00:00+00:00", "content": "..."}

这一机制与 MCP 工具 delete_memory_item 保持一致，两条删除路径最终汇聚到同一恢复日志。

资料来源：src/mind_mem/block_store.py:45-60

配置建议

概述

检索管道（Retrieval Pipeline）是 mind-mem 系统中的核心组件，负责从工作空间内存中定位和召回与用户查询相关的记忆块。该管道采用多阶段架构，结合了稀疏检索（BM25）、密集检索（向量检索）和重排序（Re-ranking）等多种技术，以实现高质量的检索结果。

检索管道的主要职责包括：

• 解析用户查询并执行多路召回
• 对多条召回路径的结果进行融合排序
• 应用质量过滤和后处理逻辑
• 返回符合置信度和活跃状态要求的结果集

架构概览

检索管道采用三层架构设计，各层职责分明：

graph TD
    A[用户查询] --> B[查询扩展层]
    B --> C[多路召回层]
    C --> D[结果融合层]
    D --> E[重排序层]
    E --> F[最终结果]
    
    C --> C1[BM25 稀疏检索]
    C --> C2[向量检索]
    C --> C3[RM3 扩展检索]
    
    D --> D1[RRF 融合]
    D --> D2[加权融合]

查询扩展层

查询扩展机制

查询扩展（Query Expansion）是检索管道的入口阶段，负责增强原始查询的语义表达能力。通过分析查询意图，系统可以引入相关术语和同义词，从而扩大检索范围。

查询扩展支持多种策略：

• RM3 扩展：基于伪相关反馈的扩展方法，从初始检索结果中提取高权重词项
• 同义词扩展：利用预定义的同义词库进行术语扩展
• 概念扩展：识别查询中的实体概念并引入相关概念

配置参数

查询扩展的行为可以通过 .mind 内核配置文件进行调优，主要参数包括：

多路召回层

多路召回是检索管道的核心阶段，通过并行执行多种检索算法来最大化召回率。

BM25 稀疏检索

BM25（Best Matching 25）是一种经典的稀疏检索算法，基于词项频率和文档频率的统计模型计算相关性评分。

BM25 的核心公式：

Score(D, Q) = Σ IDF(qi) × (f(qi, D) × (k1 + 1)) / (f(qi, D) + k1 × (1 - b + b × |D|/avgdl))

其中：

• f(qi, D)：词项 qi 在文档 D 中的频率
• |D|：文档长度
• avgdl：平均文档长度
• k1, b：可调参数（通常 k1=1.2, b=0.75）

BM25 内核配置文件（mind/bm25.mind）允许调整以下参数：

向量检索

向量检索（Vector Recall）使用密集嵌入表示进行语义级别的相似度匹配。系统将记忆块和查询都编码为高维向量，然后通过最近邻搜索找到相关结果。

向量检索的流程：

graph LR
    A[记忆块文本] --> B[Embedding 模型]
    B --> C[向量索引]
    C --> D[查询向量]
    D --> E[向量相似度计算]
    E --> F[Top-K 结果]

向量检索的主要配置参数：

RM3 扩展检索

RM3 是一种伪相关反馈方法，通过以下步骤扩展查询：

1. 执行初始检索获取 Top-N 结果
2. 从结果中提取高权重词项和词组
3. 将扩展词项加入原始查询
4. 执行二次检索

RM3 扩展检索的实现位于 query_expansion.py，其核心逻辑包括：

• 词项权重计算：基于文档内频率和逆文档频率
• 词组提取：识别连续的高频词序列
• 权重融合：将扩展词项与原始查询词项按权重合并

结果融合层

多路召回产生多个候选结果集，融合层负责将这些结果合并为一个统一的排序列表。

倒数排序融合（RRF）

倒数排序融合（Reciprocal Rank Fusion）是一种简单而有效的多路召回结果融合算法。RRF 不依赖各路召回的绝对分数，而是利用相对排名信息进行融合。

RRF 公式：

RRF_score(d) = Σ 1 / (k + rank(d, Ri))

其中：

• d：目标文档
• Ri：第 i 路召回的排名列表
• k：常量平滑因子（通常 k=60）
• rank(d, Ri)：文档 d 在第 i 路召回中的排名

RRF 内核配置文件（mind/rrf.mind）定义融合参数：

加权融合

除了 RRF，系统还支持基于分数的加权融合方法：

fusion_score(d) = Σ wi × norm(scorei(d))

其中 wi 是各路召回的可配置权重，norm() 是归一化函数。

重排序层

重排序（Re-ranking）阶段对融合后的候选结果进行精细化排序，以提高最终结果的相关性。

重排序策略

重排序器（rerank_ensemble.py）支持多种重排序策略：

1. Cross-Encoder 重排序：使用更强大的模型对 Top-K 候选进行精确评分
2. Learning-to-Rank：基于特征的训练模型进行排序
3. 级联重排序：多轮渐进式重排序

排序特征

重排序阶段考虑的特征包括：

混合检索流程

完整的混合检索流程如下：

sequenceDiagram
    participant 用户
    participant 管道
    participant BM25
    participant 向量引擎
    participant 融合器
    participant 重排序器
    participant 结果
    
    用户->>管道: 提交查询
    管道->>BM25: 发起 BM25 检索
    管道->>向量引擎: 发起向量检索
    管道->>BM25: 获取 Top-K 结果
    管道->>向量引擎: 获取 Top-K 结果
    BM25-->>管道: BM25 结果集
    向量引擎-->>管道: 向量结果集
    管道->>融合器: 合并多路结果
    融合器-->>管道: 融合排序列表
    管道->>重排序器: 精细化重排序
    重排序器-->>管道: 最终排序结果
    管道-->>用户: 返回 Top-N 结果

集成接口

Python API

检索管道通过 recall 模块提供核心检索接口：

from mind_mem.recall import recall

results = recall(
    workspace,
    query,
    limit=10,
    active_only=True,
    format="blocks"
)

MCP 工具接口

在 MCP 服务器中，检索管道通过以下工具暴露：

CLI 接口

命令行工具 mm 提供检索访问：

mm recall "查询内容" --limit 10 --active-only
mm context "查询内容" --budget 4096

配置管理

内核配置文件

检索管道的各项参数通过 .mind 内核配置文件进行管理：

mind/
├── bm25.mind      # BM25 检索参数
├── rrf.mind       # RRF 融合参数
└── rerank.mind    # 重排序参数

运行时配置

检索管道支持运行时配置覆盖：

recall(
    workspace,
    query,
    backend="auto",  # auto/bm25/hybrid
    format="json",   # json/blocks/bundle
)

性能优化

索引优化

• FTS5 索引：使用 SQLite FTS5 实现高效的全文搜索
• 向量索引：采用近似最近邻（ANN）算法加速向量检索
• 缓存策略：对高频查询结果进行缓存

查询优化

• 早停机制：当累计分数达到阈值时提前终止
• 分层检索：先用轻量级方法过滤，再用重排序精细化
• 并行执行：多路召回并行执行以降低延迟

故障排除

常见问题

扩展阅读

• 内核配置系统
• 记忆块解析
• 证据捆绑

概述

MCP服务器（Model Context Protocol Server）是mind-mem项目提供的AI记忆管理服务接口，通过MCP协议为AI智能体（Agent）提供记忆存储、检索和上下文管理能力。该服务器使AI应用能够持久化存储对话上下文和记忆数据，并在后续对话中动态加载相关记忆，实现跨会话的上下文连续性。

核心架构

架构组件

数据流架构

graph TD
    A[AI Agent] -->|MCP Protocol| B[MCP Server]
    B --> C[记忆存储引擎]
    C --> D[向量数据库]
    C --> E[键值存储]
    B --> F[检索引擎]
    F --> D
    F --> E
    G[外部应用] -->|REST/gRPC| B

服务启动

启动方式

MCP服务器支持两种启动方式：

1. 直接启动脚本：mcp_server.py 提供了独立运行的入口点
2. 模块导入启动：通过 src/mind_mem/mcp_entry.py 导入并初始化

启动配置

服务器启动时需要配置以下参数：

MCP协议接口

核心工具

MCP服务器通过MCP协议暴露以下核心工具：

资源管理

服务器提供以下MCP资源：

graph LR
    A[Resources] --> B[memory://user/{user_id}]
    A --> C[memory://conversation/{conv_id}]
    A --> D[memory://summary/{user_id}]

集成方式

客户端集成

项目文档 docs/mcp-integration.md 描述了与AI智能体的集成方式：

sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Client
    participant Server as MCP Server
    
    Agent->>MCP: 连接服务器
    MCP->>Server: 握手协商
    Server-->>MCP: 连接确认
    MCP-->>Agent: 就绪状态
    
    Agent->>MCP: 发送记忆存储请求
    MCP->>Server: store_memory()
    Server-->>MCP: 存储成功
    MCP-->>Agent: 确认响应
    
    Agent->>MCP: 发送检索请求
    MCP->>Server: retrieve_memories()
    Server-->>MCP: 相关记忆
    MCP-->>Agent: 返回上下文

集成配置示例

{
  "mcp_servers": {
    "mind-mem": {
      "command": "python",
      "args": ["mcp_server.py", "--port", "8080"],
      "env": {
        "MEMORY_STORAGE_PATH": "./data/memory"
      }
    }
  }
}

记忆管理机制

存储策略

检索机制

服务器支持多种检索模式：

1. 语义检索：基于向量相似度匹配相关记忆
2. 关键词检索：精确匹配关键词
3. 时间范围检索：按时间筛选记忆
4. 混合检索：结合语义和关键词的混合搜索

安全特性

使用示例

存储记忆

from mind_mem import MCPClient

client = MCPClient("http://localhost:8080")
client.store_memory(
    user_id="user123",
    content="用户偏好使用中文交流",
    metadata={"source": "conversation", "timestamp": "2024-01-01"}
)

检索记忆

memories = client.retrieve_memories(
    query="用户偏好",
    user_id="user123",
    limit=5
)
for memory in memories:
    print(memory.content)

配置选项

环境变量配置

运行时配置

server:
  host: 0.0.0.0
  port: 8080
  workers: 4
  
storage:
  backend: sqlite
  path: ./data/memory.db
  
vector:
  model: text-embedding-ada-002
  dimension: 1536

相关文档

• MCP集成指南
• 主入口模块
• 服务器实现

概述

MCP工具集（Model Context Protocol Tools）是mind-mem项目为非MCP智能体提供的统一命令行接口（CLI）以及MCP服务端工具集。该工具集涵盖了记忆管理的完整生命周期，包括记忆召回、上下文打包、记忆操作、治理、归档和基准测试等核心功能。

MCP工具集的设计遵循以下核心原则：

• 记忆不可直接修改原则：记忆只能通过治理流程进行修改
• 自愈式遗忘：记忆通过认知遗忘机制自动衰减和归档
• 知识核调优：通过.mind内核文件调整召回和排序策略

资料来源：src/mind_mem/mcp/tools/memory_ops.py:1-30

架构总览

MCP工具集采用模块化架构，按功能域划分为多个工具子模块：

graph TD
    subgraph MCP服务端
        A[mcp_server.py] --> B[tools/]
        B --> C[memory_ops]
        B --> D[governance]
        B --> E[consolidation]
        B --> F[kernels]
        B --> G[core]
        B --> H[arch_mind]
        B --> I[benchmark]
        B --> J[recall]
        B --> K[graph]
    end
    
    subgraph 基础设施层
        L[infra/observability]
        M[infra/workspace]
        N[infra/config]
    end
    
    C --> L
    D --> L
    E --> L
    G --> M
    H --> M
    I --> M

工具域分类

记忆操作工具域（memory_ops）

记忆操作工具域提供了记忆的索引重建、生命周期管理和健康检查功能。

资料来源：src/mind_mem/mcp/tools/memory_ops.py:1-50

#### 核心工具

#### 块前缀映射表

工具内部维护了_BLOCK_PREFIX_MAP，用于快速定位不同类型记忆块的文件路径：

资料来源：src/mind_mem/mcp/tools/memory_ops.py:100-150

治理工具域（governance）

治理工具域是mind-mem的核心模块，遵循"记忆只能通过治理流程修改"的不变式。

资料来源：src/mind_mem/mcp/tools/governance.py:1-40

#### 治理工具集

#### 治理工作流

graph LR
    A[propose_update] --> B{SIGNALS.md}
    B --> C[人工审核]
    C --> D{approve_apply}
    D -->|干跑模式| E[预览变更]
    D -->|执行模式| F[应用变更]
    F --> G[快照记录]
    G --> H[rollback可用]

记忆整合工具域（consolidation）

记忆整合工具域实现了"记忆随时间沉淀"的能力，通过认知遗忘循环维护记忆健康度。

资料来源：src/mind_mem/mcp/tools/consolidation.py:1-35

#### 整合工具集

#### 整合配置参数

知识核工具域（kernels）

知识核工具域提供了对.mind内核配置文件的只读访问，用于调整召回、排序和RM3扩展策略。

资料来源：src/mind_mem/mcp/tools/kernels.py:1-40

#### 内核工具集

上下文核心工具域（core）

上下文核心工具域封装了CoreRegistry单例，管理.mmcore便携式块的打包和知识图归档。

资料来源：src/mind_mem/mcp/tools/core.py:1-45

#### 核心工具集

#### mmcore包结构

graph TD
    A[.mmcore归档] --> B[manifest.json]
    A --> C[blocks/]
    A --> D[edges/]
    A --> E[retrieval_policies.json]
    A --> F[ontology.json]
    
    C --> C1[block_001.json]
    C --> C2[block_002.json]
    D --> D1[edge_001.json]
    D --> D2[edge_002.json]

Arch-Mind工具域（arch_mind）

Arch-Mind工具域将arch-mind二进制程序封装为7个MCP工具，提供架构基线管理和会话级指标追踪。

资料来源：src/mind_mem/mcp/tools/arch_mind.py:1-50

#### Arch工具集

基准测试工具域（benchmark）

基准测试工具域提供了治理健康度和类别摘要的评估工具。

资料来源：src/mind_mem/mcp/tools/benchmark.py:1-40

#### 基准工具集

MCP工具元数据

所有MCP工具均通过以下装饰器实现统一观测：

装饰器链

@mcp_tool_observe  # 观测性装饰器
@_traced("tool_name")  # 追踪装饰器
def tool_function(args):
    ...

返回格式

所有工具返回JSON格式字符串，包含标准模式版本头：

{
  "_schema_version": "3.2.0",
  "tool_name": "result_data"
}

资料来源：src/mind_mem/mcp/tools/governance.py:40-80

工作区感知

MCP工具集通过统一的_workspace()函数解析工作区路径：

graph LR
    A[MIND_MEM_WORKSPACE环境变量] -->|优先级1| B[显式覆盖]
    A -->|未设置| C[当前工作目录]
    C --> D[realpath解析]
    B --> D
    D --> E[工作区根目录]

工作区检查通过_check_workspace()验证：

1. 工作区目录存在
2. 必需的子目录结构完整
3. 必要的配置文件可读

资料来源：src/mind_mem/mcp/tools/consolidation.py:20-50

CLI命令映射

MCP工具集同时提供命令行接口（CLI），位于mm_cli.py：

资料来源：src/mind_mem/mm_cli.py:1-80

错误处理

MCP工具集采用统一的错误处理模式：

错误类型

错误响应格式

{
  "_schema_version": "3.2.0",
  "error": "error_description"
}

配置集成

MCP工具集通过基础设施层获取配置：

from ..infra.config import _get_limits, _load_extra_categories
from ..infra.workspace import _workspace, _check_workspace

可配置项包括：

• 最大类别结果数
• 额外类别定义
• 全文索引限制
• 导出大小上限

扩展机制

自定义工具域

新增工具域需要：

1. 在mcp/tools/目录下创建新模块
2. 实现工具函数并添加装饰器
3. 在mcp_server.py中注册
4. 更新本文档

观测性扩展

工具函数通过mcp_tool_observe装饰器自动集成到观测系统：

• 调用计数（metrics.inc）
• 日志记录（_log.info）
• 追踪（traced decorator）

相关文档

• MCP工具示例
• MCP服务端架构

概述

治理与矛盾检测是 mind-mem 系统的核心安全机制，确保记忆体的变更遵循"记忆永不直接修改，只能通过治理流程变更"的不变式。该模块涵盖了从提议、审批、应用到回滚的完整生命周期，同时提供矛盾检测、漂移检测和审计链验证等多层次防护。

核心设计原则：

• 治理驱动变更：所有决策和任务的修改必须通过提议-审批流程
• 证据链完整：每条证据都有时间戳、来源和可信度标记
• 矛盾优先检测：在编译真理页面时自动检测冲突证据
• 可审计可回滚：所有操作记录在案，支持快照回滚

资料来源：src/mind_mem/mcp/tools/governance.py:1-20

架构总览

graph TD
    subgraph 治理层
        A[提议 Propose] --> B[审批 Apply]
        B --> C[回滚 Rollback]
        C --> D[扫描 Scan]
        D --> E[矛盾列表]
    end
    
    subgraph 证据层
        F[CompiledTruthPage] --> G[detect_contradictions]
        G --> H[EvidenceEntry]
        H --> I[superseded 标记]
    end
    
    subgraph 审计层
        J[verify_merkle] --> K[Merkle Tree]
        L[verify_chain] --> M[SHA3-512 Hash Chain]
        N[verify_evidence] --> O[Evidence Chain]
    end
    
    B --> J
    B --> L
    F --> G

核心组件

1. 治理门 (Governance Gate)

治理门是记忆修改的守门人，确保所有变更必须通过标准流程。

# 伪代码展示治理门工作流程
def governance_check(block):
    if is_proposal(block) and is_approved(block):
        return APPLY
    elif is_contradiction_detected(block):
        return REJECT_CONFLICT
    else:
        return QUEUE_FOR_REVIEW

治理门配置参数：

资料来源：src/mind_mem/governance_gate.py

2. 矛盾检测器 (Contradiction Detector)

矛盾检测器分析编译真理页面的证据条目，识别相互冲突的陈述。

graph LR
    A[Evidence Entry 1] --> D{矛盾检测}
    B[Evidence Entry 2] --> D
    C[Evidence Entry 3] --> D
    D --> E[冲突报告]
    E --> F[标记为 superseded]

核心检测逻辑：

def detect_contradictions(page: CompiledTruthPage) -> list[Contradiction]:
    """检测证据条目间的矛盾"""
    contradictions = []
    for i, entry_i in enumerate(page.evidence_entries):
        for j, entry_j in enumerate(page.evidence_entries[i+1:], i+1):
            if _is_contradictory(entry_i, entry_j):
                contradictions.append(Contradiction(
                    entry_a=i,
                    entry_b=j,
                    severity=_calculate_severity(entry_i, entry_j)
                ))
    return contradictions

检测维度：

资料来源：src/mind_mem/contradiction_detector.py

3. 漂移检测器 (Drift Detector)

漂移检测器监控决策或任务的实际执行与原始声明之间的偏离。

graph TD
    A[原始声明] --> B[版本化快照]
    C[当前状态] --> D{漂移计算}
    B --> D
    D --> E{超出容忍度?}
    E -->|是| F[触发告警]
    E -->|否| G[继续监控]

漂移检测触发条件：

• 决策状态与预期不符
• 任务优先级发生非预期变更
• 截止日期与原计划偏差超过阈值
• 关联实体发生未记录变更

资料来源：src/mind_mem/drift_detector.py

4. 审计链 (Audit Chain)

审计链提供加密可验证的完整性证明，确保记忆体的历史不可篡改。

graph LR
    A[Block 1] -->|SHA3-512| B[Block 2]
    B -->|SHA3-512| C[Block 3]
    C -->|SHA3-512| D[Block N]
    D --> E[Merkle Root]
    
    F[Merkle Proof] --> G[验证包含性]

审计工具清单：

资料来源：src/mind_mem/mcp/tools/audit.py:1-50

MCP 治理工具

propose_update - 提议更新

创建新的决策或任务提议，写入 SIGNALS.md 待人工审核。

函数签名：

def propose_update(
    block_type: str,
    statement: str,
    rationale: str = "",
    tags: str = "",
    confidence: str = "medium"
) -> str

参数说明：

返回值示例：

{
  "_schema_version": "3.2.0",
  "signal_id": "SIG-20260115-001",
  "message": "Proposal queued for review"
}

资料来源：src/mind_mem/mcp/tools/governance.py:50-80

approve_apply - 审批应用

应用已通过的提议，支持干运行模式。

核心流程：

graph TD
    A[加载提议] --> B[干运行验证]
    B --> C{验证通过?}
    C -->|否| D[返回错误]
    C -->|是| E[创建快照]
    E --> F[应用变更]
    F --> G[更新索引]
    G --> H[清理信号]

关键特性：

• 默认干运行 (dry_run=True)
• 自动快照回滚点
• 原子性事务保证

资料来源：src/mind_mem/mcp/tools/governance.py:100-150

rollback_proposal - 回滚提案

从预应用快照恢复工作区状态。

graph LR
    A[当前状态] --> B[快照恢复]
    B --> C[索引回退]
    C --> D[信号重建]

约束条件：

• 只能回滚处于待应用状态的提案
• 快照必须在有效期内（默认7天）
• 回滚本身会产生新的治理记录

资料来源：src/mind_mem/mcp/tools/governance.py:150-200

scan - 完整性扫描

执行综合健康检查，覆盖矛盾检测、漂移检测和待处理项。

def scan(workspace: str) -> dict:
    return {
        "contradictions": detect_all_contradictions(workspace),
        "drift": detect_drift(workspace),
        "pending": list_pending_signals(workspace),
        "health_score": calculate_health_score(workspace)
    }

扫描子项：

资料来源：src/mind_mem/mcp/tools/governance.py:200-250

list_contradictions - 矛盾列表

返回枚举的矛盾详情，支持富文本输出。

输出格式：

{
  "contradictions": [
    {
      "entity_id": "PRJ-alpha",
      "severity": "high",
      "entries": [
        {
          "index": 0,
          "timestamp": "2026-01-10T09:00:00Z",
          "observation": "项目截止日期为 Q1",
          "confidence": "HIGH",
          "source": "decisions.md"
        },
        {
          "index": 3,
          "timestamp": "2026-01-12T14:30:00Z",
          "observation": "项目截止日期为 Q2",
          "confidence": "MEDIUM",
          "source": "tasks.md"
        }
      ]
    }
  ]
}

资料来源：src/mind_mem/mcp/tools/governance.py:250-300

governance_health_bench - 健康基准测试

运行治理健康基准测试套件，验证矛盾检测、审计完整性、漂移检测和可扩展性。

测试子项：

返回值结构：

{
  "_schema_version": "3.2.0",
  "tests_run": 12,
  "passed": 11,
  "failed": 1,
  "results": [...]
}

资料来源：src/mind_mem/mcp/tools/benchmark.py:20-60

编译真理页面 (Compiled Truth Page)

编译真理页面是矛盾检测的核心载体，聚合实体的所有证据并自动编译权威理解。

数据结构

@dataclass
class CompiledTruthPage:
    entity_id: str              # 实体标识符
    entity_type: str            # 实体类型 (PER/PRJ/TOOL/INC)
    compiled_section: str       # 编译后的权威理解
    evidence_entries: list[EvidenceEntry]  # 证据条目列表
    last_compiled: str          # ISO时间戳
    version: int                # 版本号

证据条目

@dataclass
class EvidenceEntry:
    timestamp: str       # ISO 8601 时间戳
    source: str          # 来源文件
    observation: str     # 观察内容
    confidence: str      # HIGH/MEDIUM/LOW
    superseded: bool     # 是否已被取代

矛盾检测集成

编译真理页面在重新编译时自动调用矛盾检测：

def recompile_truth(page: CompiledTruthPage) -> CompiledTruthPage:
    """从非取代证据重新生成编译部分"""
    # 过滤非取代证据
    active_entries = [e for e in page.evidence_entries if not e.superseded]
    
    # 检测矛盾
    contradictions = detect_contradictions(page)
    
    # 生成报告
    for conflict in contradictions:
        _log.warning(
            "contradiction_detected",
            entity_id=page.entity_id,
            entry_a=conflict.entry_a,
            entry_b=conflict.entry_b
        )
    
    # 按时间戳排序，生成摘要
    ...

资料来源：src/mind_mem/compiled_truth.py:100-150

证据取代机制

当检测到矛盾时，可通过治理流程标记旧证据为 superseded：

def supersede_evidence(
    page: CompiledTruthPage,
    entry_index: int,
    reason: str
) -> CompiledTruthPage:
    """将证据标记为已取代"""
    new_entry = dataclasses.replace(
        page.evidence_entries[entry_index],
        superseded=True
    )
    new_entries = list(page.evidence_entries)
    new_entries[entry_index] = new_entry
    return dataclasses.replace(page, evidence_entries=new_entries)

取代规则：

• 被取代证据仍保留在历史中，但计算时忽略
• 取代操作本身产生新的治理记录
• 新版本触发重新编译

资料来源：src/mind_mem/compiled_truth.py:150-200

工作流示例

决策变更完整流程

sequenceDiagram
    participant Agent
    participant MCP as MCP Server
    participant Store as Block Store
    participant Audit as Audit Chain
    participant Truth as Compiled Truth

    Agent->>MCP: propose_update(DECISION, "变更X")
    MCP->>Store: 写入SIGNALS.md
    Note over MCP: 状态: PENDING

    Agent->>MCP: approve_apply(SIG-xxx, dry_run=true)
    MCP->>Truth: 检查矛盾
    Truth-->>MCP: 无冲突

    Agent->>MCP: approve_apply(SIG-xxx, dry_run=false)
    MCP->>Store: 创建快照
    MCP->>Store: 应用变更
    MCP->>Audit: 更新哈希链
    Note over MCP: 状态: APPLIED

    Agent->>MCP: scan()
    MCP-->>Agent: 健康报告

矛盾处理流程

graph TD
    A[检测到矛盾] --> B{自动解决可能?}
    B -->|否| C[人工审核]
    C --> D[审查证据]
    D --> E[选择保留哪条]
    E --> F[取代旧证据]
    B -->|是| G[自动取代低可信度]
    G --> F
    F --> H[重新编译]
    H --> I[生成新版本]
    I --> J[更新审计链]

配置选项

矛盾检测配置

审计配置

漂移检测配置

相关命令

mm CLI 治理命令

# 提议新决策
mm governance propose --type DECISION --statement "采用新技术栈"

# 应用审批
mm governance approve SIG-20260115-001

# 回滚操作
mm governance rollback SIG-20260115-001

# 运行健康扫描
mm governance scan

# 列出矛盾
mm governance contradictions --entity PRJ-alpha

# 验证审计链
mm verify --type chain

MCP 工具调用

{
  "tool": "propose_update",
  "arguments": {
    "block_type": "DECISION",
    "statement": "迁移至微服务架构",
    "rationale": "提升可扩展性",
    "tags": "architecture, refactor",
    "confidence": "high"
  }
}

最佳实践

1. 矛盾预防

• 在添加新证据前先查询现有编译真理页面
• 使用高可信度来源标注证据
• 避免重复提交相似陈述

2. 治理流程

• 干运行优先，正式应用前验证
• 保持提议的原子性描述
• 定期运行健康扫描

3. 审计合规

• 验证哈希链完整性作为CI/CD环节
• 保留足够的快照以支持回滚
• 监控审计链验证失败事件

总结

治理与矛盾检测模块为 mind-mem 提供了企业级的记忆管理安全保障。通过"提议-审批-应用-回滚"的完整生命周期管理，确保了所有变更的可追溯性和可控性。矛盾检测与编译真理页面的深度集成，使得知识库的权威性得到持续维护，而审计链则为整个系统提供了密码学级别的完整性保证。

质量门禁（Quality Gate）

质量门禁是记忆块写入前的第一道防线，位于 src/mind_mem/quality_gate.py。它是一个确定性、基于内容的预存储过滤器，对候选块进行检查并返回结构化裁决。

核心规则

质量门禁包含八条规则，全部为确定性规则，不依赖外部服务：

裁决模式

质量门禁支持两种裁决模式：

• 顾问模式（默认）：每条规则都会被记录，但裁决仍返回 accept
• 严格模式（strict）：任何规则触发都导致 reject

严格模式可通过以下方式启用：

1. 调用时传入 strict=True 关键字参数
2. 工作区 QualityGateConfig(mode="strict")
3. 工作区配置 mind-mem.json 中的 quality_gate_mode = "strict"

工作流程

graph TD
    A[接收候选块] --> B[执行 8 条规则检查]
    B --> C{触发任何规则?}
    C -->|否| D[裁决: accept]
    C -->|是| E{strict 模式?}
    E -->|否| F[记录日志]
    F --> D
    E -->|是| G[裁决: reject]
    D --> H[写入存储]
    G --> I[返回错误信息]

返回数据结构

@dataclass
class Verdict:
    decision: Literal["accept", "reject"]
    fired_rules: list[str]      # 触发的规则列表
    score: float                 # 质量分数 0.0-1.0
    reason: Optional[str]       # 拒绝原因描述

资料来源：src/mind_mem/quality_gate.py:1-100

块解析质量控制

src/mind_mem/block_parser.py 负责从文本中解析记忆块，解析过程内置了多项质量验证机制。

UTF-8 BOM 处理

解析器首先检查并处理 UTF-8 BOM（Byte Order Mark）：

if text.startswith(''):
    text = text[1:]

这确保第一个块头不会被 BOM 字符遮挡，保证解析的一致性。

否定块识别

系统内置否定块检测正则表达式，用于识别语义反转的声明：

_NEGATION_RE = re.compile(
    r"\b(not|never|don't|won't|shouldn't|cannot|can't|..."
    r"|no\s+\w+|none)\b",
    re.IGNORECASE,
)

这对于矛盾检测和语义理解具有重要意义。

ConstraintSignature 解析

v2.0 版本支持结构化的 ConstraintSignature 解析，识别以下嵌套字段：

解析器维护内部状态机，正确处理嵌套结构和操作符列表。

资料来源：src/mind_mem/block_parser.py:1-80

编译真相与矛盾检测

编译真相（Compiled Truth）是 mind-mem 的核心概念之一，位于 src/mind_mem/compiled_truth.py。它通过聚合证据来维护实体的规范理解。

证据条目结构

@dataclass
class EvidenceEntry:
    timestamp: str           # ISO 时间戳
    source: str              # 来源标识
    observation: str         # 观察内容
    confidence: str          # 置信度: high/medium/low
    superseded: bool          # 是否已被替代

编译真相页面结构

矛盾检测

系统提供 detect_contradictions() 函数用于检测编译真相页面中的矛盾：

def detect_contradictions(page: CompiledTruthPage) -> list[ContradictionPair]:
    """检测页面中的矛盾证据对"""

矛盾检测通过以下步骤工作：

1. 遍历所有未废弃的证据条目
2. 比较语义相反的陈述
3. 识别否定关系（如 "应该使用 X" vs "不应该使用 X"）
4. 返回矛盾对列表

证据替代机制

当新证据与旧证据矛盾时，系统支持标记旧证据为已废弃：

def supersede_evidence(
    page: CompiledTruthPage,
    entry_index: int,
    reason: str
) -> CompiledTruthPage:

替代后的旧证据保留在历史中，但不影响规范理解的生成。

资料来源：src/mind_mem/compiled_truth.py:1-150

治理工具与矛盾扫描

MCP 工具提供程序化的质量保障能力，位于 src/mind_mem/mcp/tools/governance.py。

可用工具

扫描操作

scan 工具执行三类检查：

1. 矛盾检测：识别同一实体的相互冲突的证据
2. 漂移检测：检测规范理解与实际证据的不一致
3. 待处理检测：列出未处理的信号和提案

SQLite 锁处理

扫描操作使用 SQLite 数据库，工具内置锁冲突处理：

def _is_db_locked(exc: Exception) -> bool:
    return "database is locked" in str(exc)

def _sqlite_busy_error(result: str, exc: Exception) -> str:
    return json.dumps({"error": f"DB locked: {exc}", "retry": True})

资料来源：src/mind_mem/mcp/tools/governance.py:1-100

模型溯源验证

src/mind_mem/model_provenance.py 提供模型出处检查能力，确保引用的模型信息准确。

支持的发布商

ProvenanceFinding 结果

@dataclass
class ProvenanceFinding:
    passed: bool                    # 检查是否通过
    publisher: Optional[str]        # 识别的发布商
    model_family: Optional[str]     # 模型家族
    confidence: float               # 置信度 0.0-1.0

资料来源：src/mind_mem/model_provenance.py:1-100

删除恢复与审计

系统维护删除操作的全量审计日志，支持误删恢复。

删除收据格式

删除块时，系统将删除收据写入 memory/deleted_blocks.jsonl：

{
  "block_id": "D-20260213-001",
  "deleted_at": "2026-03-15T10:30:00+00:00",
  "content": "原始块内容..."
}

块定位逻辑

删除收据记录使用与 mcp.tools.memory_ops.delete_memory_item 相同的边界规则：

• 块从 [<id>] 行开始
• 块结束于下一个 [<ID>] 头行、孤立的 --- 分隔符或 EOF

这确保两个删除路径收敛到同一恢复日志格式。

资料来源：src/mind_mem/block_store.py:1-100

配置与指标

质量门禁配置优先级

1. 函数调用 strict=True 参数（最高优先级）
2. QualityGateConfig(mode="strict") 对象
3. mind-mem.json 中的 quality_gate_mode 设置
4. 默认值（advisory 模式）

质量指标

系统通过 metrics.inc() 追踪质量事件：

日志记录

质量事件通过结构化日志记录：

_log.info(
    "evidence_superseded",
    entity_id=page.entity_id,
    index=entry_index,
    reason=reason,
)

日志输出到 MIND_MEM_LOG_FILE 或标准输出。

最佳实践

启用严格模式

对于生产环境，建议在工作区配置中启用严格模式：

{
  "quality_gate_mode": "strict"
}

定期扫描

使用 MCP 工具 scan 定期检查工作区一致性：

mm mcp call scan --scan-type full

矛盾审查

当检测到矛盾时，通过 list_contradictions 工具获取详细信息：

mm mcp call list_contradictions

删除恢复

误删块后，可通过 deleted_blocks.jsonl 恢复内容：

# 查看最近删除
tail -n 10 memory/deleted_blocks.jsonl

Pitfall Log / 踩坑日志

项目：star-ga/mind-mem

摘要：发现 21 个潜在踩坑项，其中 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 | cevd_366d8c18c1aa45ffb07174af516285d4 | 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 | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | 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
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor

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

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1160652179 | 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 | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing

8. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1160652179 | 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 | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | 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 | cevd_1e9c9207806f46a6a90a83828e99c173 | 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 | cevd_ea39fdeb939e484a9be8751555483fc5 | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。

13. 安全/权限坑 · 来源证据：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d71f093408f04636bc91f85df44c811d | https://github.com/star-ga/mind-mem/issues/508 | 来源类型 github_issue 暴露的待验证使用条件。

14. 安全/权限坑 · 来源证据：[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 | cevd_7bf148881d754982a8b6bbb0959436d0 | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。

15. 安全/权限坑 · 来源证据：[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 | cevd_afb67087422e43678c941140da7019de | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：[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 | cevd_0917cf4b43b34ffe8d43e599d353665c | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。

17. 安全/权限坑 · 来源证据：[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 | cevd_ad9e7a85457041afbc88c886568b2657 | https://github.com/star-ga/mind-mem/issues/511 | 来源类型 github_issue 暴露的待验证使用条件。

18. 安全/权限坑 · 来源证据：[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 | cevd_32106da2cae04c0185f7a6331cd1ef8a | https://github.com/star-ga/mind-mem/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。

19. 安全/权限坑 · 来源证据：`_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 | cevd_7bba956cb937439b85b35fb2c150b7e2 | https://github.com/star-ga/mind-mem/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | issue_or_pr_quality=unknown

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

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | release_recency=unknown