# https://github.com/star-ga/mind-mem 项目说明书
生成时间：2026-05-16 01:43:31 UTC
## 目录
- [MIND-Mem简介](#page-introduction)
- [核心功能一览](#page-features)
- [系统架构](#page-architecture)
- [数据流与处理管道](#page-data-flow)
- [存储后端](#page-storage)
- [检索管道](#page-recall)
- [MCP服务器](#page-mcp-server)
- [MCP工具集](#page-mcp-tools)
- [治理与矛盾检测](#page-governance)
- [质量保障与验证](#page-quality)
## MIND-Mem简介
### 相关页面
相关主题：[核心功能一览](#page-features), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/star-ga/mind-mem/blob/main/README.md)
- [SPEC.md](https://github.com/star-ga/mind-mem/blob/main/SPEC.md)
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)
- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)
# MIND-Mem简介
## 项目概述
MIND-Mem 是一个用于 AI 代理的**结构化记忆与推理框架**，它为多代理协作场景提供持久化记忆存储、检索和治理能力。该项目基于文件系统存储，采用 Markdown 格式管理记忆块，并通过 MCP（Model Context Protocol）协议对外提供服务接口。
MIND-Mem 的核心设计理念是：**记忆永不直接修改，只能通过治理流程变更**。这一 invariant 确保了记忆系统的完整性和可审计性。
资料来源：[SPEC.md](https://github.com/star-ga/mind-mem/blob/main/SPEC.md)
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph 用户层
CLI[CLI工具
mm命令]
MCP[MCP客户端]
Web[Web控制台]
API[REST API]
end
subgraph MCP服务层
MS[MCP Server
mcp_server.py]
KERNEL[Kernel工具]
GOVERNANCE[治理工具]
AUDIT[审计工具]
MEMORY[内存操作工具]
end
subgraph 核心存储层
FTS[FTS5全文索引]
BLOCKS[记忆块文件
.md格式]
CT[Compiled Truth
编译真相页]
LEDGER[多代理事实账本]
end
CLI --> MS
MCP --> MS
Web --> API
API --> MS
MS --> FTS
MS --> BLOCKS
MS --> CT
MS --> LEDGER
```
### 核心组件
| 组件名称 | 文件路径 | 功能描述 |
|---------|---------|---------|
| MCP Server | `src/mind_mem/mcp_server.py` | MCP协议服务核心，处理所有MCP工具调用 |
| CLI工具 | `src/mind_mem/mm_cli.py` | 统一命令行接口，支持recall、context、inject等命令 |
| 记忆块解析器 | `src/mind_mem/block_parser.py` | 解析和管理.md格式的记忆块文件 |
| 编译真相 | `src/mind_mem/compiled_truth.py` | 实体真相页面的聚合和编译 |
| 质量门 | `src/mind_mem/quality_gate.py` | 预存储过滤器，验证记忆块质量 |
| Web控制台 | `web/` | 基于Next.js的可视化界面 |
资料来源：[mm_cli.py:1-20](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
## 核心功能
### 2.1 记忆检索与上下文管理
MIND-Mem 提供多种检索方式满足不同场景需求：
#### CLI命令接口
```bash
mm recall "" # BM25语义搜索
mm context "" # 生成token预算受限的片段
mm inject --agent "" # 为特定代理渲染片段
mm vault scan # 列出解析的vault块
mm status # 工作区摘要
```
资料来源：[mm_cli.py:1-20](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
#### MCP资源接口
| 资源标识 | 功能 |
|---------|------|
| `mind-mem://decisions` | 活动决策列表（DECISIONS.md） |
| `mind-mem://tasks` | 所有任务（TASKS.md） |
| `mind-mem://entities/{type}` | 项目、人员、工具、事件实体 |
| `mind-mem://signals` | 自动捕获的信号 |
| `mind-mem://contradictions` | 检测到的矛盾 |
| `mind-mem://health` | 工作区健康摘要 |
| `mind-mem://recall/{query}` | BM25召回搜索 |
| `mind-mem://ledger` | 共享多代理事实账本 |
资料来源：[mcp/resources.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
### 2.2 编译真相系统
编译真相（Compiled Truth）是 MIND-Mem 的核心知识沉淀机制：
```mermaid
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
compiled/xxx.md]
ENTRY[Evidence Entry
证据条目]
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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
### 2.3 治理与审计
MIND-Mem 遵循"**记忆永不直接修改，只通过治理变更**"的原则：
#### 治理工具集
| 工具名称 | 功能 |
|---------|------|
| `propose_update` | 将新决策/任务暂存为 SIGNAL |
| `approve_apply` | 应用暂存的提案（默认dry-run） |
| `rollback_proposal` | 从预应用快照恢复工作区 |
| `scan` | 完整性扫描（矛盾/漂移/待处理） |
| `list_contradictions` | 枚举检测到的矛盾 |
| `memory_evolution` | 获取记忆块的A-MEM元数据 |
资料来源：[mcp/tools/governance.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
#### 审计工具集
| 工具名称 | 功能 |
|---------|------|
| `verify_merkle` | 验证块的Merkle包含证明 |
| `verify_chain` | 验证SHA3-512哈希链完整性 |
| `list_evidence` | 枚举治理证据对象 |
| `mind_mem_verify` | 暴露独立验证CLI |
资料来源：[mcp/tools/audit.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)
### 2.4 质量门控
质量门（Quality Gate）是预存储过滤器，确保进入系统的记忆块符合标准：
```mermaid
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
```
**八条质量规则：**
| 规则ID | 规则名称 | 判定条件 | 默认行为 |
|-------|---------|---------|---------|
| 1 | `empty` | 块内容为空或仅空白 | 接受+日志 |
| 2 | `too_short` | 少于32个非空白字符 | 接受+日志 |
| 3 | `oversize` | 超过64KB UTF-8字节 | 拒绝 |
| 4 | `malformed_utf8` | 包含孤立代理符 | 拒绝 |
| 5 | `stopwords_only` | 所有token都是停用词 | 接受+日志 |
| 6 | `near_duplicate` | 与24h内块相似度≥0.97 | 接受+日志 |
| 7 | `injection_marker` | 匹配已知注入模式 | 拒绝 |
| 8 | `ok` | 无规则触发 | 接受 |
支持 `strict=True` 模式，所有规则均变为硬性拒绝。
资料来源：[quality_gate.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)
## 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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
### 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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
### 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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)
## 工作区结构
```
{workspace}/
├── DECISIONS.md # 活动决策
├── TASKS.md # 任务列表
├── SIGNALS.md # 待审查信号
├── memory/ # 记忆块存储
│ ├── *.md
│ └── ...
├── entities/
│ └── compiled/ # 编译真相页
│ └── *.md
├── .mind/ # 内核配置
│ └── *.mind
└── index.db # FTS5全文索引
```
## Web控制台
基于 Next.js 的可视化界面，提供三种视图：
```mermaid
graph TD
subgraph Web控制台
SUBMIT[查询提交]
API[REST API调用]
subgraph 三面板展示
GRAPH[力导向图
GraphView]
TIMELINE[时间轴
TimelineView]
FACTS[事实列表
FactList]
end
end
SUBMIT --> API
API --> GRAPH
API --> TIMELINE
API --> FACTS
```
**启动方式：**
```bash
cd web
pnpm install
pnpm dev # → http://localhost:3000
```
资料来源：[web/README.md:1-40](https://github.com/star-ga/mind-mem/blob/main/web/README.md)
## 快速开始
### 安装
```bash
pip install -e .
```
### CLI基本用法
```bash
# 初始化工作区
export MIND_MEM_WORKSPACE=/path/to/workspace
# 搜索记忆
mm recall "PostgreSQL决策历史"
# 生成上下文
mm context "最近的架构变更"
# 注入特定代理上下文
mm inject --agent claude "当前项目技术栈"
```
### API使用
```python
from mind_mem import recall
results = recall("/path/to/workspace", "query", limit=10)
```
## v4.0 预览
MIND-Mem v4.0 正在开发中，带来以下新特性（当前默认关闭，需通过 `mind-mem.json` 开启）：
| 功能组 | 特性 | 状态 |
|-------|------|------|
| A. 认知/模型层 | 分层记忆、认知内核、惊喜权重检索 | 规划中 |
| B. 知识图谱 | 实体/概念提取、长上下文召回、LLM融合、流式检索、对话层 | 规划中 |
| C. 知识治理 | 空闲后台摄入、AI lint、矛盾状态机、自愈索引 | 规划中 |
资料来源：[v4/__init__.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)
## 总结
MIND-Mem 是一个设计严谨的 AI 记忆框架，通过以下核心机制保障系统的可靠性和可追溯性：
1. **文件系统优先** — Markdown格式存储，便于版本控制和人类阅读
2. **治理驱动变更** — 记忆只能通过正式提案→审批流程修改
3. **多协议支持** — 同时提供CLI、MCP和REST API接口
4. **质量门控** — 预存储过滤器确保数据质量
5. **可审计性** — Merkle证明和哈希链验证数据完整性
---
## 核心功能一览
### 相关页面
相关主题：[MIND-Mem简介](#page-introduction), [检索管道](#page-recall)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)
- [src/mind_mem/mcp/tools/arch_mind.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)
- [src/mind_mem/model_provenance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)
# 核心功能一览
mind-mem 是一个多智能体记忆管理系统，提供了完整的信息召回、治理、压缩和长期记忆维护能力。本页概述系统的核心功能模块，包括 MCP 工具、CLI 接口、编译事实系统和 v4.0 特性预览。
## 1. 系统架构总览
mind-mem 采用分层架构设计，核心组件包括：
```mermaid
graph TD
subgraph "接口层"
CLI[CLI 命令行工具
mm]
MCP[MCP 服务器
Model Context Protocol]
REST[REST API
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 内核配置
负责管理和配置召回、排序和管道参数的内核文件访问。
| 工具名称 | 功能描述 | 资料来源 |
|---------|---------|----------|
| `list_mind_kernels` | 列出所有可用的 .mind 内核配置文件 | [kernels.py:28-48](src/mind_mem/mcp/tools/kernels.py) |
| `get_mind_kernel` | 获取指定内核配置详情 | [kernels.py:28-48](src/mind_mem/mcp/tools/kernels.py) |
内核配置控制项包括：
- 召回权重调优（recall tuning）
- 重排序参数（reranking）
- RM3 扩展配置
- 管道级联参数
### 2.2 GOVERNANCE 域 — 治理与生命周期
治理域是"记忆永不直接修改"原则的核心实现，所有变更必须经过治理流程。
| 工具名称 | 功能描述 | 资料来源 |
|---------|---------|----------|
| `propose_update` | 提案新决策或任务，写入 SIGNALS.md 待人工审核 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |
| `approve_apply` | 应用已批准提案（默认干运行模式） | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |
| `rollback_proposal` | 从预应用快照恢复工作区 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |
| `scan` | 完整性扫描（矛盾检测/漂移检测/待处理项） | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |
| `list_contradictions` | 列出检测到的矛盾项 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |
| `memory_evolution` | 获取区块的 A-MEM 元数据 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |
**治理工作流：**
```mermaid
graph LR
A[propose_update
提案阶段] --> B{SIGNALS.md}
B --> C[人工审核]
C --> D{approve_apply
批准应用}
D -->|干运行 OK| E[正式应用]
D -->|发现问题| F[rollback_proposal
回滚]
E --> G[区块更新]
F --> H[快照恢复]
```
### 2.3 CONSOLIDATION 域 — 记忆整合
"记忆随时间沉淀"表面，实现认知遗忘和自动整合机制。
| 工具名称 | 功能描述 | 资料来源 |
|---------|---------|----------|
| `plan_consolidation` | 认知遗忘周期干运行 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |
| `propagate_staleness` | 跨引用扩散陈旧度分数 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |
| `project_profile` | 会话启动情报摘要 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |
| `dream_cycle` | 自主记忆丰富（实体发现/断裂引用扫描/整合候选/自动修复） | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |
### 2.4 MEMORY_OPS 域 — 记忆操作
工作区生命周期和内省操作，处理索引、删除、导出等管理任务。
| 工具名称 | 功能描述 | 资料来源 |
|---------|---------|----------|
| `index_stats` | FTS5 索引状态查询 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `reindex` | 重建全文索引 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `delete_memory_item` | 原子化管理员范围区块移除 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `export_memory` | JSONL 格式完整导出 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `get_block` | 单区块查询 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `memory_health` | 健康状态仪表盘 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `compact` | 存储压缩 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
| `stale_blocks` | 陈旧区块标记管理 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |
### 2.5 BENCHMARK 域 — 基准测试
| 工具名称 | 功能描述 | 资料来源 |
|---------|---------|----------|
| `governance_health_bench` | 矛盾检测/审计完整性/漂移/可扩展性探测 | [benchmark.py:24-50](src/mind_mem/mcp/tools/benchmark.py) |
| `category_summary` | 类别蒸馏器查询 | [benchmark.py:52-75](src/mind_mem/mcp/tools/benchmark.py) |
### 2.6 ARCH_MIND 域 — 架构知识管理
包装 `arch-mind` 二进制工具，提供架构基线、历史记录、规则检查和会话管理。
| 工具名称 | 功能描述 | 资料来源 |
|---------|---------|----------|
| `arch_baseline` | 初始化架构基线 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
| `arch_delta` | 计算当前扫描与基线的差异 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
| `arch_history` | 列出架构历史事件 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
| `arch_check_rules` | 应用规则文件检查 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
| `arch_session_start` | 开启会话证据节点 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
| `arch_session_end` | 关闭会话并写入增量证据 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
| `arch_metric_explain` | 单指标详细分解 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |
## 3. CLI 命令行工具
`mm` 命令提供 MCP 之外的轻量级接口，适用于非 MCP 智能体。
```bash
mm recall "" # 搜索记忆
mm context "" # 生成预算限制的片段
mm inject --agent "" # 为特定智能体渲染片段
mm vault scan # 列出解析的 vault 块
mm vault write --type --body
mm status # 工作区摘要
mm trace --live # 实时流式 MCP 调用日志
mm trace --last 20 --tool xxx # 最近 N 次工具调用
```
资料来源：[mm_cli.py:1-50](src/mind_mem/mm_cli.py)
## 4. 编译事实系统
编译事实（Compiled Truth）是按实体聚合证据并重新编译权威理解的关键机制。
### 4.1 核心概念
```mermaid
graph TD
subgraph "来源"
SOURCE1[memory/决策A.md]
SOURCE2[memory/任务B.md]
SOURCE3[memory/事件C.md]
end
subgraph "候选提取"
SENTENCE[句子提取
频率≥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 编译事实数据结构
| 字段 | 类型 | 说明 |
|-----|------|------|
| `entity_id` | str | 实体唯一标识 |
| `evidence_entries` | list | 证据条目列表 |
| `compiled_summary` | str | 权威摘要文本 |
| `version` | int | 编译版本号 |
| `last_compiled` | datetime | 最后编译时间 |
| `superseded_entries` | list | 已废弃条目 |
### 4.3 关键函数
| 函数 | 功能 | 资料来源 |
|-----|------|----------|
| `extract_compiled_truth_candidates` | 从 memory/ 目录提取候选事实 | [compiled_truth.py:30-80](src/mind_mem/compiled_truth.py) |
| `supersede_evidence_entry` | 标记证据条目为已废弃 | [compiled_truth.py:150-175](src/mind_mem/compiled_truth.py) |
| `recompile_truth` | 从非废弃证据重新生成摘要 | [compiled_truth.py:180-200](src/mind_mem/compiled_truth.py) |
## 5. MCP 资源声明
通过 `@mcp.resource` 暴露只读视图，提供工作区信息的统一访问：
| 资源 URI | 内容描述 |
|---------|----------|
| `mind-mem://decisions` | 活动决策（DECISIONS.md） |
| `mind-mem://tasks` | 所有任务（TASKS.md） |
| `mind-mem://entities/{type}` | 项目/人员/工具/事件实体 |
| `mind-mem://signals` | 自动捕获信号 |
| `mind-mem://contradictions` | 检测到的矛盾 |
| `mind-mem://health` | 工作区健康摘要 |
| `mind-mem://recall/{query}` | BM25 召回搜索 |
| `mind-mem://ledger` | 共享多智能体事实账本 |
资料来源：[resources.py:1-50](src/mind_mem/mcp/resources.py)
## 6. 模型溯源系统
`model_provenance.py` 定义了发布商注册表和来源发现机制：
| 发布商 | Slugs | 描述 |
|-------|-------|------|
| Mistral | `mistralai` | Mistral / Mixtral / Codestral 家族 |
| Google Gemma | `google` | Gemma / Gemma-2 / PaLM 家族 |
| IBM Granite | `ibm-granite`, `ibm` | Granite-3 / Granite-Code 家族 |
| OpenAI | `openai` | Whisper / CLIP 及开源模型 |
| Anthropic | `anthropic` | Anthropic 发布产物 |
| DeepSeek | `deepseek-ai` | DeepSeek-V2 / V3 / R1 家族 |
| Microsoft Phi | `microsoft` | Phi-2 / Phi-3 / Phi-4 家族 |
| TII Falcon | `tiiuae` | Falcon-7B / 40B / 180B 家族 |
资料来源：[model_provenance.py:1-80](src/mind_mem/model_provenance.py)
## 7. v4.0 功能预览
v4.0 采用显式功能开关设计，默认关闭以保持 v3.x 行为兼容。
```mermaid
graph TD
subgraph "v4.0 功能门"
CONFIG[mind-mem.json
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](src/mind_mem/v4/__init__.py)
## 8. 智能体集成
mind-mem 支持多种 AI 编码客户端集成，通过 `hook_installer.py` 管理：
| 智能体 | 配置格式 | 说明 |
|-------|---------|------|
| Claude | JSON | Anthropic Claude 家族 |
| Claude Code | JSON block | 支持 MCP 配置 |
| Codex CLI | JSON block | OpenAI Codex |
| Cursor | JSON block | Cursor IDE |
| Windsurf | mcp-json-windsurf | Codeium Windsurf |
| aider | YAML block | aider CLI (paul-gauthier) |
| OpenClaw | JSON hooks | 开源 AI 助手 |
| NanoClaw | JSON hooks | 紧凑型 Claw 变体 |
| NemoClaw | JSON hooks | 记忆聚焦型 Claw |
MCP 服务器路径解析优先级：
1. `MIND_MEM_MCP_SERVER` 环境变量
2. `/../mcp_server.py`（源码检出布局）
3. `/mcp_server.py`（打包安装布局）
资料来源：[hook_installer.py:1-50](src/mind_mem/hook_installer.py)
## 9. 观察压缩
`observation_compress.py` 实现记忆压缩专家系统，支持多种查询类型：
| 类型 | 用途 |
|-----|------|
| `direct` | 直接事实查询 |
| `comparative` | 对比分析 |
| `denial` | 否定证据识别 |
| `temporal` | 时序/因果关系 |
| `multi-hop` | 多跳推理连接 |
资料来源：[observation_compress.py:1-60](src/mind_mem/observation_compress.py)
## 10. 总结
mind-mem 的核心功能可归纳为以下维度：
| 维度 | 核心能力 |
|-----|---------|
| **召回** | BM25/混合检索、FTS5 全文索引、长上下文模式 |
| **治理** | 提案-审批-回滚流程、矛盾检测、快照恢复 |
| **整合** | 认知遗忘周期、陈旧度扩散、自主丰富 |
| **操作** | 索引管理、原子删除、JSONL 导出、健康监控 |
| **事实** | 编译事实页、证据聚合、版本化管理 |
| **可观测性** | 结构化日志、MCP 调用追踪、trace 工具 |
所有核心功能均通过 MCP 工具接口或 CLI 提供，确保与主流 AI 编码客户端的广泛兼容性。
---
## 系统架构
### 相关页面
相关主题：[MIND-Mem简介](#page-introduction), [数据流与处理管道](#page-data-flow)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)
- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-gag/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)
- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)
- [src/mind_mem/protection.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/protection.py)
- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)
# 系统架构
mind-mem 是一个面向多智能体协作的持久化记忆系统，旨在为 AI 编码助手提供持久化上下文记忆能力。该系统通过 Model Context Protocol (MCP) 向各类 AI 客户端暴露统一的记忆接口，支持记忆检索、上下文注入、治理决策追踪和完整性审计等核心功能。
## 1. 整体架构概览
mind-mem 采用分层架构设计，核心由 MCP 服务层、记忆操作层、数据持久化层和治理审计层组成。
```mermaid
graph TD
subgraph 客户端层
CLAUDE["Claude Code"]
COPILOT["GitHub Copilot"]
CODY["Sourcegraph Cody"]
QODO["Qodo Gen"]
end
subgraph 接口层
MCP["MCP Server
(mcp_server.py)"]
CLI["CLI 工具
(mm)"]
WEB["Web 控制台
(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 工具域划分
| 工具域 | 文件路径 | 核心工具 |
|--------|----------|----------|
| governance | `mcp/tools/governance.py` | propose_update, approve_apply, rollback_proposal, scan |
| audit | `mcp/tools/audit.py` | verify_merkle, verify_chain, list_evidence, mind_mem_verify |
| kernels | `mcp/tools/kernels.py` | list_mind_kernels, get_mind_kernel, compiled_truth_* |
| memory_ops | `mcp/tools/memory_ops.py` | index_stats, reindex, delete_memory_item, export_memory |
| consolidation | `mcp/tools/consolidation.py` | plan_consolidation, propagate_staleness, dream_cycle |
| benchmark | `mcp/tools/benchmark.py` | governance_health_bench, category_summary |
| arch_mind | `mcp/tools/arch_mind.py` | arch_baseline, arch_delta, arch_session_* |
### 2.2 MCP 资源声明
MCP 服务还暴露一组只读资源，提供对工作区记忆的查询视图：
```mermaid
graph LR
R1["mind-mem://decisions
决策记录"]
R2["mind-mem://tasks
任务列表"]
R3["mind-mem://entities/{type}
实体查询"]
R4["mind-mem://signals
信号数据"]
R5["mind-mem://contradictions
矛盾检测"]
R6["mind-mem://health
健康状态"]
R7["mind-mem://recall/{query}
BM25 检索"]
R8["mind-mem://ledger
多智能体账本"]
```
资料来源：[src/mind_mem/mcp/resources.py:1-30]()
### 2.3 MCP 服务启动流程
```python
# 资料来源：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. `/../mcp_server.py`（源码 checkout 布局）
3. `/mcp_server.py`（打包安装布局）
资料来源：[src/mind_mem/hook_installer.py]()
## 3. CLI 工具架构
`mm` 是面向非 MCP 智能体的统一 CLI 工具，提供命令行记忆操作能力。
### 3.1 CLI 子命令
| 子命令 | 功能描述 |
|--------|----------|
| `mm recall ""` | BM25 记忆检索 |
| `mm context ""` | 生成符 合 token 预算的上下文片段 |
| `mm inject --agent ""` | 为指定智能体渲染记忆片段 |
| `mm vault scan ` | 列出解析的 vault 块（JSON 格式）|
| `mm vault write ` | 写入 vault 记忆块 |
| `mm status` | 工作区状态摘要 |
资料来源：[src/mind_mem/mm_cli.py:1-25]()
### 3.2 工作区解析
```python
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 全文搜索和上下文感知记忆提取。
```mermaid
graph TD
Q["查询输入"] --> PARSE["查询解析"]
PARSE --> FTS["FTS5 索引查询"]
FTS --> RERANK["重排序"]
RERANK --> PACK["预算打包
(pack_to_budget)"]
PACK --> RESULT["记忆片段"]
subgraph 记忆来源
MEMORY["memory/ 目录"]
TASKS["TASKS.md"]
DECISIONS["DECISIONS.md"]
end
FTS --> MEMORY
FTS --> TASKS
FTS --> DECISIONS
```
### 4.2 记忆类型映射
记忆文件使用特定前缀标识类型：
| 前缀 | 类型 | 说明 |
|------|------|------|
| `[[` | Obsidian 风格链接 | 跨块引用 |
| `TASK` | 任务块 | 任务追踪 |
| `DECISION` | 决策块 | 架构决策记录 |
| `SIGNAL` | 信号块 | 待审批提案 |
## 5. 治理与决策系统
### 5.1 治理原则
mind-mem 遵循"记忆仅通过治理修改"的不变性原则。所有记忆变更必须经过提议、审批、生效的完整治理流程。
```mermaid
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 治理工具集
| 工具 | 功能 |
|------|------|
| `propose_update` | 提议新决策或任务，写入 SIGNALS.md |
| `approve_apply` | 应用已审批提案（默认 dry-run）|
| `rollback_proposal` | 从预应用快照恢复工作区 |
| `scan` | 完整性扫描（矛盾/漂移/待处理）|
| `list_contradictions` | 矛盾列表查询 |
## 6. 编译真相系统 (Compiled Truth)
### 6.1 系统设计
编译真相系统通过聚合证据来维护实体的规范理解，支持基于句子级出现频率的事实提取。
```python
# 资料来源：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 真相页结构
每个真相页维护以下数据结构：
| 字段 | 说明 |
|------|------|
| `entity_id` | 实体唯一标识 |
| `evidence_entries` | 证据条目列表 |
| `compiled_summary` | 编译后的摘要 |
| `version` | 版本号 |
| `last_compiled` | 最后编译时间 |
### 6.3 证据管理
```mermaid
graph LR
E1["新证据"] --> VALIDATE["验证"]
VALIDATE --> ADD["添加证据"]
ADD --> COMPILE["重新编译"]
COMPILE --> SUMMARY["生成摘要"]
E2["旧证据"] --> SUPERSEDE["标记 superseded"]
SUPERSEDE --> COMPILE
```
## 7. 完整性审计系统
### 7.1 审计层设计
审计系统通过哈希链和默克尔树保证记忆的不可篡改性。
| 组件 | 用途 |
|------|------|
| Hash Chain v2 | SHA3-512 追加式账本 |
| Evidence Chain | 结构化治理证据 |
| Merkle Tree | 块级包含证明 |
| Integrity Manifest | 发布完整性清单 |
### 7.2 验证工具
| 工具 | 功能 |
|------|------|
| `verify_merkle` | 验证块的默克尔包含证明 |
| `verify_chain` | 验证哈希链和证据链完整性 |
| `list_evidence` | 枚举治理证据对象 |
| `mind_mem_verify` | 独立验证 CLI |
### 7.3 验证退出码
| 退出码 | 含义 |
|--------|------|
| 0 | 所有检查通过 |
| 1 | 通用失败（路径缺失）|
| 2 | 哈希链完整性违规 |
| 3 | 规范哈希绑定漂移 |
| 4 | 证据链完整性违规 |
| 5 | 默克尔根不匹配 |
| 6 | 链头/快照锚点不匹配 |
资料来源：[src/mind_mem/verify_cli.py:1-45]()
## 8. 智能体集成系统
### 8.1 支持的智能体
| 智能体 | 配置格式 | 配置路径 | 说明 |
|--------|----------|----------|------|
| claude | JSON | `~/.claude/settings.json` | Anthropic Claude Code |
| copilot | Text Block | `.github/copilot-instructions.md` | GitHub Copilot |
| cody | JSON | `.cody/config.json` | Sourcegraph Cody |
| qodo | Text Block | `.codium/ai-rules.md` | Qodo Gen |
资料来源：[src/mind_mem/hook_installer.py]()
### 8.2 集成机制
```mermaid
graph TD
INSTALL["hook_installer"] --> DETECT["检测智能体"]
DETECT --> SPEC["生成 AgentSpec"]
SPEC --> WRITE["写入配置文件"]
WRITE --> PREPEND["注入记忆锚点"]
PREPEND --> QUERY["mm inject --agent "]
QUERY --> CONTEXT["返回记忆上下文"]
```
### 8.3 智能体规范定义
```python
@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 索引操作
| 工具 | 功能 |
|------|------|
| `index_stats` | 查询 FTS5 索引状态 |
| `reindex` | 重建全文索引 |
### 9.2 生命周期管理
| 工具 | 功能 |
|------|------|
| `delete_memory_item` | 原子性记忆块删除（带追加式恢复日志）|
| `get_block` | 块内容查询 |
| `memory_health` | 健康状态仪表盘 |
| `compact` | 存储压缩 |
| `stale_blocks` | 陈旧块标记管理 |
### 9.3 导出功能
```python
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 认知遗忘周期
```mermaid
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 整合工具
| 工具 | 功能 |
|------|------|
| `plan_consolidation` | 认知遗忘周期预演 |
| `propagate_staleness` | 陈旧度跨引用扩散 |
| `project_profile` | 会话启动情报摘要 |
| `dream_cycle` | 自主记忆丰富化 |
资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-30]()
## 11. v4.0 架构演进
v4.0 作为架构演进版本，默认关闭，通过 feature flag 启用。
### 11.1 功能组映射
| 组别 | 功能 | 模块 |
|------|------|------|
| A | 认知层/模型层 | tier_memory, cognitive_kernel, surprise_retrieval |
| B | 知识图谱 | block_kinds, long_context_recall, fusion, streaming_recall, chat, prompt_schema |
| C | 知识图谱治理 | idle_ingest, lint, contradiction_states, self_heal |
| D | 基准测试 | arch_baseline, arch_delta |
| E | 高级记忆 | block_cognition, consolidation |
| F | 多租户 | tenant_audit, tenant_kms |
资料来源：[src/mind_mem/v4/__init__.py:1-50]()
### 11.2 特征门控
```python
class FeatureDisabledError(Exception):
"""v4 功能未启用时抛出"""
pass
```
所有 v4.0 功能均需在 `mind-mem.json` 配置文件的 `v4` 键下显式启用。
## 12. 完整性保护机制
### 12.1 关键模块保护
系统维护一份关键模块清单，用于完整性验证：
| 关键模块 | 说明 |
|----------|------|
| recall.py | 检索核心 |
| recall_vector.py | 向量检索 |
| apply_engine.py | 治理应用引擎 |
| audit_chain.py | 审计链 |
| encryption.py | 加密模块 |
| graph_recall.py | 图检索 |
| consensus_vote.py | 共识投票 |
| tenant_audit.py | 租户审计 |
资料来源：[src/mind_mem/protection.py:30-50]()
### 12.2 完整性报告
```python
@dataclass(frozen=True)
class IntegrityReport:
ok: bool
module: str
expected_hash: str
actual_hash: str
```
## 13. Web 控制台架构
mind-mem 提供基于 Next.js 的 Web 控制台，提供可视化记忆查询界面。
```mermaid
graph LR
API["REST API
/v1/recall
/v1/health"] --> PAGE["app/page.tsx"]
PAGE --> GRAPH["GraphView
(d3-force)"]
PAGE --> TIMELINE["TimelineView"]
PAGE --> FACTS["FactList"]
GRAPH --> NODES["节点: 按状态着色"]
GRAPH --> EDGES["边: 按谓词着色"]
```
组件说明：
| 组件 | 功能 |
|------|------|
| GraphView.tsx | 力导向图可视化 |
| TimelineView.tsx | 时间线视图 |
| FactList.tsx | 提取的事实列表 |
| lib/api.ts | 类型化 API 客户端 |
资料来源：[web/README.md]()
## 14. 依赖关系总览
```mermaid
graph BT
subgraph 核心依赖
BLOCK["block_parser"]
FTS["sqlite_index
(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 逐步引入新功能，不影响现有系统
---
## 数据流与处理管道
### 相关页面
相关主题：[系统架构](#page-architecture), [存储后端](#page-storage), [检索管道](#page-recall)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/capture.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/capture.py)
- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
- [src/mind_mem/ingestion_pipeline.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/ingestion_pipeline.py)
- [src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)
- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
# 数据流与处理管道
## 概述
数据流与处理管道是 mind-mem 系统的核心组成部分，负责管理从数据捕获、存储、处理到检索的完整生命周期。该管道遵循"内存永不直接修改，只能通过治理机制变更"的核心不变量，确保所有数据变更都经过审批和追踪流程。
## 整体架构
```mermaid
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 是数据持久化的核心抽象，支持多种后端实现：
| 组件 | 类名 | 用途 | 配置键 |
|------|------|------|--------|
| 默认后端 | `MarkdownBlockStore` | Markdown 文件存储 | `block_store.backend: markdown` |
| Postgres 后端 | `PostgresBlockStore` | 关系型数据库存储 | `block_store.backend: postgres` |
| 加密包装器 | `EncryptedBlockStore` | 加密数据存储 | `mind-mem.json` passphrase 设置 |
资料来源：[src/mind_mem/apply_engine.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
### ApplyEngine 处理引擎
ApplyEngine 负责数据变更的实际执行，提供快照、回滚和差异对比功能：
```python
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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
## 数据流阶段
### 阶段一：数据捕获
数据捕获层负责收集外部信号和用户输入，生成标准化的 Block 结构：
```mermaid
graph LR
A[外部输入] --> B[Capture 模块]
B --> C[Block 结构化]
C --> D[信号写入]
D --> E[SIGNALS.md]
```
关键流程：
1. 接收外部数据源（CLI、API、MCP 工具）
2. 解析为标准 Block 格式
3. 写入 SIGNALS.md 待审批队列
### 阶段二：存储抽象
存储层根据配置选择合适的持久化后端：
```mermaid
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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
### 阶段三：检索与召回
Recall 模块提供多种检索策略：
| 检索模式 | 参数 | 说明 |
|----------|------|------|
| BM25 | `strategy: bm25` | 基于词频的稀疏检索 |
| 向量检索 | `strategy: vector` | 密集向量相似度检索 |
| 混合模式 | `strategy: hybrid` | BM25 + 向量加权融合 |
| 自动模式 | `strategy: auto` | 根据查询特征自动选择 |
资料来源：[src/mind_mem/recall.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)
## 治理与变更流程
### 提案-审批模式
所有数据变更必须通过治理机制：
```mermaid
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: 应用变更
```
### 回滚机制
当变更需要撤销时，系统通过快照恢复：
```python
# 回滚流程
snap_dir = create_snapshot(ws, ts) # 变更前创建快照
# ... 执行变更 ...
restore_snapshot(ws, snap_dir) # 需要回滚时恢复
```
资料来源：[src/mind_mem/apply_engine.py:40-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
## 编译真相机制
Compiled Truth 模块负责证据聚合和事实编译：
```mermaid
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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
## MCP 工具集成
MCP 工具层提供外部系统交互接口：
| 工具类别 | 工具名称 | 功能 |
|----------|----------|------|
| 内核管理 | `list_mind_kernels` | 列出可用内核配置 |
| 内核管理 | `get_mind_kernel` | 获取指定内核详情 |
| 真相管理 | `compiled_truth_add_evidence` | 添加证据到真相页 |
| 真相管理 | `compiled_truth_contradictions` | 检测真相矛盾 |
| 治理工具 | `propose_update` | 提交变更提案 |
| 治理工具 | `approve_apply` | 审批并应用变更 |
| 治理工具 | `rollback_proposal` | 回滚提案 |
资料来源：[src/mind_mem/mcp/tools/kernels.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
## 配置参数
### BlockStore 配置
在 `mind-mem.json` 中的配置结构：
```json
{
"block_store": {
"backend": "markdown|postgres|encrypted",
"passphrase": "<加密密钥>",
"connection": ""
}
}
```
### 检索配置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `strategy` | string | `auto` | 检索策略选择 |
| `limit` | int | 20 | 结果数量限制 |
| `active_only` | bool | false | 仅返回活跃块 |
## 错误处理与容错
系统采用分层错误处理策略：
1. **BlockStore 层**：异常时回退到 MarkdownBlockStore 默认实现
2. **ApplyEngine 层**：快照操作失败时记录日志但不阻断主流程
3. **Recall 层**：单一检索失败时尝试降级到其他策略
```python
try:
return get_block_store(ws)
except Exception:
return MarkdownBlockStore(ws) # 降级保底
```
资料来源：[src/mind_mem/apply_engine.py:40-45](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
## 性能考量
- **快照开销**：create_snapshot 在变更频繁场景下可能产生 IO 压力
- **检索延迟**：混合检索模式需要并行执行 BM25 和向量检索
- **存储选择**：Postgres 后端适合高并发写入场景，Markdown 适合简单部署
---
## 存储后端
### 相关页面
相关主题：[数据流与处理管道](#page-data-flow), [检索管道](#page-recall)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
- [src/mind_mem/storage/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/storage/__init__.py)
- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
# 存储后端
mind-mem 采用插件化的存储后端架构，支持多种持久化方案以适应不同的部署场景。所有存储操作通过统一的 BlockStore 接口抽象，确保上层逻辑与具体存储技术解耦。
## 架构概述
存储后端系统采用工厂模式（Factory Pattern）进行后端实例化。`get_block_store()` 工厂函数根据工作区配置动态选择合适的存储实现。
```mermaid
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]()
## 支持的后端类型
| 后端类型 | 配置值 | 说明 | 依赖 |
|---------|--------|------|------|
| Markdown | `markdown` | 默认后端，将块存储为 Markdown 文件 | 无 |
| 加密存储 | `encrypted` | 在 Markdown 后端基础上添加加密层 | `MIND_MEM_ENCRYPTION_PASSPHRASE` 环境变量 |
| PostgreSQL | `postgres` | 企业级关系数据库存储 | `psycopg[binary]`、`dsn` 配置 |
资料来源：[src/mind_mem/storage/__init__.py:55-68]()
## 工厂函数 API
### get_block_store(workspace, config=None)
`storage/__init__.py` 中定义的工厂函数，负责根据配置实例化正确的后端。
**函数签名：**
```python
def get_block_store(workspace: str, config: dict[str, Any] | None = None) -> BlockStore:
```
**参数说明：**
| 参数 | 类型 | 必填 | 说明 |
|-----|------|------|------|
| `workspace` | str | 是 | mind-mem 工作区根目录路径 |
| `config` | dict \| None | 否 | 完整配置字典，为空时自动从 `mind-mem.json` 加载 |
**返回值：**
返回 `BlockStore` 实例（`MarkdownBlockStore`、`EncryptedBlockStore` 或 `PostgresBlockStore`）。
**异常处理：**
| 异常类型 | 触发条件 |
|---------|----------|
| `ValueError` | `backend` 值无法识别 |
| `ValueError` | 使用 `encrypted` 后端但未设置环境变量 |
| `ValueError` | 使用 `postgres` 后端但配置中缺少 `dsn` |
| `ImportError` | 使用 `postgres` 后端但未安装 `psycopg` |
资料来源：[src/mind_mem/storage/__init__.py:30-50]()
### 配置读取逻辑
工厂函数首先尝试从工作区目录加载 `mind-mem.json` 配置文件：
```python
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 实现回滚功能的核心。当需要修改工作区内容时，系统首先创建快照，然后对快照进行操作，验证通过后才正式应用。
| 方法 | 功能 |
|-----|------|
| `snapshot(snap_dir, files_touched)` | 创建预应用快照 |
| `restore(snap_dir)` | 从快照目录恢复工作区 |
| `diff(snap_dir)` | 比较当前工作区与快照的差异 |
```mermaid
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: 复制文件树
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 块遵循固定格式，包含标识头和键值对字段：
```markdown
[ID]
Statement: 决策内容描述
Date: 2026-02-13
Status: active
Confidence: high
Tags: architecture, backend
[ID]
```
`CANONICAL_FIELD_ORDER` 定义了字段的标准顺序，确保块序列化的一致性：
```python
_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 为企业级部署提供关系数据库存储能力。适用于需要事务支持、并发访问和高可用性的生产环境。
### 配置示例
```json
{
"block_store": {
"backend": "postgres",
"dsn": "postgresql://user:password@localhost:5432/mindmem"
}
}
```
### 与 Markdown 后端的差异
| 特性 | Markdown | PostgreSQL |
|-----|----------|------------|
| 快照方式 | 文件复制 | SQL 转储 |
| 并发支持 | 文件锁 | 数据库事务 |
| 查询能力 | 全文搜索 | SQL 查询 |
| 部署复杂度 | 简单 | 需要数据库服务 |
## 加密存储包装器
EncryptedBlockStore 是一个包装器后端，它在底层 Markdown 后端基础上添加加密功能。当设置了 `MIND_MEM_ENCRYPTION_PASSPHRASE` 环境变量时，存储模块会自动返回加密包装后的实例。
资料来源：[src/mind_mem/storage/__init__.py:65-67]()
## 在 Apply Engine 中的应用
apply_engine 模块通过 `_store_for(ws)` 函数获取当前配置的 BlockStore 实例，所有存储操作都通过该实例进行路由：
```python
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` 文件：
```json
{"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]()
## 配置建议
| 场景 | 推荐后端 | 原因 |
|-----|---------|------|
| 本地开发 / 个人使用 | Markdown | 简单、无依赖、易于调试 |
| 小团队协作 | Markdown + Git | 利用版本控制进行协作 |
| 企业级生产环境 | PostgreSQL | 事务支持、并发控制、备份恢复 |
| 安全敏感数据 | Encrypted | 静态数据加密保护 |
---
## 检索管道
### 相关页面
相关主题：[存储后端](#page-storage), [治理与矛盾检测](#page-governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)
- [src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/query_expansion.py)
- [src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)
- [src/mind_mem/rerank_ensemble.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/rerank_ensemble.py)
- [mind/bm25.mind](https://github.com/star-ga/mind-mem/blob/main/mind/bm25.mind)
- [mind/rrf.mind](https://github.com/star-ga/mind-mem/blob/main/mind/rrf.mind)
# 检索管道
## 概述
检索管道（Retrieval Pipeline）是 mind-mem 系统中的核心组件，负责从工作空间内存中定位和召回与用户查询相关的记忆块。该管道采用多阶段架构，结合了稀疏检索（BM25）、密集检索（向量检索）和重排序（Re-ranking）等多种技术，以实现高质量的检索结果。
检索管道的主要职责包括：
- 解析用户查询并执行多路召回
- 对多条召回路径的结果进行融合排序
- 应用质量过滤和后处理逻辑
- 返回符合置信度和活跃状态要求的结果集
## 架构概览
检索管道采用三层架构设计，各层职责分明：
```mermaid
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` 内核配置文件进行调优，主要参数包括：
| 参数名 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `rm3_expansion_terms` | int | 10 | RM3 扩展的词项数量 |
| `rm3_collection_weight` | float | 0.9 | 文档权重系数 |
| `expansion_enabled` | bool | true | 是否启用扩展 |
## 多路召回层
多路召回是检索管道的核心阶段，通过并行执行多种检索算法来最大化召回率。
### 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`）允许调整以下参数：
| 参数 | 说明 | 典型值 |
|------|------|--------|
| `k1` | 词频饱和参数 | 1.2 |
| `b` | 文档长度归一化参数 | 0.75 |
| `avgdl` | 平均文档长度基准 | - |
### 向量检索
向量检索（Vector Recall）使用密集嵌入表示进行语义级别的相似度匹配。系统将记忆块和查询都编码为高维向量，然后通过最近邻搜索找到相关结果。
向量检索的流程：
```mermaid
graph LR
A[记忆块文本] --> B[Embedding 模型]
B --> C[向量索引]
C --> D[查询向量]
D --> E[向量相似度计算]
E --> F[Top-K 结果]
```
向量检索的主要配置参数：
| 参数 | 类型 | 说明 |
|------|------|------|
| `model_name` | str | 嵌入模型名称 |
| `dimension` | int | 向量维度 |
| `similarity_metric` | str | 相似度度量（cosine/dot/euclidean） |
| `top_k` | int | 返回的最近邻数量 |
### 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`）定义融合参数：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `k` | 60 | RRF 平滑因子 |
| `enabled` | true | 是否启用 RRF |
### 加权融合
除了 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. **级联重排序**：多轮渐进式重排序
### 排序特征
重排序阶段考虑的特征包括：
| 特征类别 | 具体特征 |
|----------|----------|
| 相关性特征 | BM25 分数、向量相似度、语义匹配度 |
| 质量特征 | 块完整性、置信度评分、来源权重 |
| 时效性特征 | 创建时间、最后更新时间、活跃状态 |
| 关联性特征 | 引用次数、依赖关系、实体匹配 |
## 混合检索流程
完整的混合检索流程如下：
```mermaid
sequenceDiagram
participant 用户
participant 管道
participant BM25
participant 向量引擎
participant 融合器
participant 重排序器
participant 结果
用户->>管道: 提交查询
管道->>BM25: 发起 BM25 检索
管道->>向量引擎: 发起向量检索
管道->>BM25: 获取 Top-K 结果
管道->>向量引擎: 获取 Top-K 结果
BM25-->>管道: BM25 结果集
向量引擎-->>管道: 向量结果集
管道->>融合器: 合并多路结果
融合器-->>管道: 融合排序列表
管道->>重排序器: 精细化重排序
重排序器-->>管道: 最终排序结果
管道-->>用户: 返回 Top-N 结果
```
## 集成接口
### Python API
检索管道通过 `recall` 模块提供核心检索接口：
```python
from mind_mem.recall import recall
results = recall(
workspace,
query,
limit=10,
active_only=True,
format="blocks"
)
```
### MCP 工具接口
在 MCP 服务器中，检索管道通过以下工具暴露：
| 工具名称 | 功能描述 |
|----------|----------|
| `recall` | 基础检索接口 |
| `recall_with_persona` | 带角色投影的检索 |
| `list_mind_kernels` | 列出可用的检索内核配置 |
| `get_mind_kernel` | 获取特定内核配置详情 |
### CLI 接口
命令行工具 `mm` 提供检索访问：
```bash
mm recall "查询内容" --limit 10 --active-only
mm context "查询内容" --budget 4096
```
## 配置管理
### 内核配置文件
检索管道的各项参数通过 `.mind` 内核配置文件进行管理：
```
mind/
├── bm25.mind # BM25 检索参数
├── rrf.mind # RRF 融合参数
└── rerank.mind # 重排序参数
```
### 运行时配置
检索管道支持运行时配置覆盖：
```python
recall(
workspace,
query,
backend="auto", # auto/bm25/hybrid
format="json", # json/blocks/bundle
)
```
## 性能优化
### 索引优化
- **FTS5 索引**：使用 SQLite FTS5 实现高效的全文搜索
- **向量索引**：采用近似最近邻（ANN）算法加速向量检索
- **缓存策略**：对高频查询结果进行缓存
### 查询优化
- **早停机制**：当累计分数达到阈值时提前终止
- **分层检索**：先用轻量级方法过滤，再用重排序精细化
- **并行执行**：多路召回并行执行以降低延迟
## 故障排除
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 检索结果为空 | 索引未建立 | 执行 `reindex` 工具 |
| 结果不相关 | 查询扩展过度 | 调整 `expansion_enabled` |
| 延迟过高 | 向量索引未优化 | 检查 ANN 参数配置 |
| 排名异常 | 内核参数冲突 | 检查 `.mind` 配置文件 |
## 扩展阅读
- [内核配置系统](./内核配置系统.md)
- [记忆块解析](./记忆块解析.md)
- [证据捆绑](./证据捆绑.md)
---
## MCP服务器
### 相关页面
相关主题：[MCP工具集](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mcp/server.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py)
- [src/mind_mem/mcp_entry.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_entry.py)
- [mcp_server.py](https://github.com/star-ga/mind-mem/blob/main/mcp_server.py)
- [docs/mcp-integration.md](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-integration.md)
# MCP服务器
## 概述
MCP服务器（Model Context Protocol Server）是mind-mem项目提供的AI记忆管理服务接口，通过MCP协议为AI智能体（Agent）提供记忆存储、检索和上下文管理能力。该服务器使AI应用能够持久化存储对话上下文和记忆数据，并在后续对话中动态加载相关记忆，实现跨会话的上下文连续性。
## 核心架构
### 架构组件
| 组件 | 职责 | 文件位置 |
|------|------|----------|
| MCP Server | MCP协议服务端实现，处理客户端请求 | `src/mind_mem/mcp/server.py` |
| MCP Entry | 服务入口点，负责初始化和启动 | `src/mind_mem/mcp_entry.py` |
| 记忆存储引擎 | 管理记忆数据的持久化存储 | 内部模块 |
| 检索引擎 | 支持语义检索和关键词匹配 | 内部模块 |
### 数据流架构
```mermaid
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` 导入并初始化
### 启动配置
服务器启动时需要配置以下参数：
| 参数 | 说明 | 默认值 |
|------|------|--------|
| host | 服务监听地址 | 0.0.0.0 |
| port | 服务监听端口 | 8080 |
| storage_path | 记忆存储路径 | ./memory_data |
| vector_dim | 向量维度 | 768 |
## MCP协议接口
### 核心工具
MCP服务器通过MCP协议暴露以下核心工具：
| 工具名称 | 功能 | 输入参数 |
|----------|------|----------|
| store_memory | 存储记忆 | user_id, content, metadata |
| retrieve_memories | 检索记忆 | query, user_id, limit |
| update_memory | 更新记忆 | memory_id, content |
| delete_memory | 删除记忆 | memory_id |
| list_memories | 列出记忆 | user_id, filters |
### 资源管理
服务器提供以下MCP资源：
```mermaid
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智能体的集成方式：
```mermaid
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: 返回上下文
```
### 集成配置示例
```json
{
"mcp_servers": {
"mind-mem": {
"command": "python",
"args": ["mcp_server.py", "--port", "8080"],
"env": {
"MEMORY_STORAGE_PATH": "./data/memory"
}
}
}
}
```
## 记忆管理机制
### 存储策略
| 策略类型 | 说明 | 适用场景 |
|----------|------|----------|
| 即时存储 | 实时保存每次交互 | 重要对话记录 |
| 批量存储 | 定时批量写入 | 低优先级日志 |
| 压缩存储 | 自动摘要后存储 | 长对话历史 |
### 检索机制
服务器支持多种检索模式：
1. **语义检索**：基于向量相似度匹配相关记忆
2. **关键词检索**：精确匹配关键词
3. **时间范围检索**：按时间筛选记忆
4. **混合检索**：结合语义和关键词的混合搜索
## 安全特性
| 安全措施 | 说明 |
|----------|------|
| 用户隔离 | 不同用户记忆严格隔离 |
| 访问控制 | 基于用户ID的访问验证 |
| 数据加密 | 敏感数据加密存储 |
| 审计日志 | 记录所有操作日志 |
## 使用示例
### 存储记忆
```python
from mind_mem import MCPClient
client = MCPClient("http://localhost:8080")
client.store_memory(
user_id="user123",
content="用户偏好使用中文交流",
metadata={"source": "conversation", "timestamp": "2024-01-01"}
)
```
### 检索记忆
```python
memories = client.retrieve_memories(
query="用户偏好",
user_id="user123",
limit=5
)
for memory in memories:
print(memory.content)
```
## 配置选项
### 环境变量配置
| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| MEMORY_STORAGE_PATH | 存储路径 | /data/memory |
| MCP_PORT | 服务端口 | 8080 |
| MCP_HOST | 服务地址 | localhost |
| VECTOR_DB_TYPE | 向量数据库类型 | qdrant/chroma |
| MAX_MEMORY_SIZE | 最大记忆大小 | 10000 |
### 运行时配置
```yaml
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集成指南](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-integration.md)
- [主入口模块](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_entry.py)
- [服务器实现](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py)
---
## MCP工具集
### 相关页面
相关主题：[MCP服务器](#page-mcp-server)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/mcp/tools/memory_ops.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)
- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)
- [src/mind_mem/mcp/tools/core.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/core.py)
- [src/mind_mem/mcp/tools/arch_mind.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)
- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)
# MCP工具集
## 概述
MCP工具集（Model Context Protocol Tools）是mind-mem项目为非MCP智能体提供的统一命令行接口（CLI）以及MCP服务端工具集。该工具集涵盖了记忆管理的完整生命周期，包括记忆召回、上下文打包、记忆操作、治理、归档和基准测试等核心功能。
MCP工具集的设计遵循以下核心原则：
- **记忆不可直接修改原则**：记忆只能通过治理流程进行修改
- **自愈式遗忘**：记忆通过认知遗忘机制自动衰减和归档
- **知识核调优**：通过`.mind`内核文件调整召回和排序策略
资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-30]()
## 架构总览
MCP工具集采用模块化架构，按功能域划分为多个工具子模块：
```mermaid
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]()
#### 核心工具
| 工具名称 | 功能描述 |
|---------|---------|
| `index_stats` | 获取FTS5全文索引状态 |
| `reindex` | 重建全文索引 |
| `delete_memory_item` | 原子性记忆块删除 |
| `export_memory` | 导出记忆为JSONL格式 |
| `get_block` | 获取单个记忆块 |
| `memory_health` | 记忆健康状态仪表板 |
| `compact` | 记忆压缩 |
| `stale_blocks` | 陈旧记忆块管理 |
#### 块前缀映射表
工具内部维护了`_BLOCK_PREFIX_MAP`，用于快速定位不同类型记忆块的文件路径：
| 前缀 | 文件路径 |
|-----|---------|
| `DEC` | `decisions/DECISIONS.md` |
| `TSK` | `tasks/TASKS.md` |
| `SIG` | `signals/SIGNALS.md` |
| `ENT` | `entities/*.md` |
资料来源：[src/mind_mem/mcp/tools/memory_ops.py:100-150]()
### 治理工具域（governance）
治理工具域是mind-mem的核心模块，遵循"记忆只能通过治理流程修改"的不变式。
资料来源：[src/mind_mem/mcp/tools/governance.py:1-40]()
#### 治理工具集
| 工具名称 | 功能描述 |
|---------|---------|
| `propose_update` | 将新决策/任务暂存为SIGNAL |
| `approve_apply` | 应用暂存的提案（默认干跑） |
| `rollback_proposal` | 从预应用快照恢复工作区 |
| `scan` | 完整性扫描（矛盾/漂移/待处理） |
| `list_contradictions` | 矛盾列表枚举 |
| `memory_evolution` | 获取记忆块的A-MEM元数据 |
#### 治理工作流
```mermaid
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]()
#### 整合工具集
| 工具名称 | 功能描述 |
|---------|---------|
| `plan_consolidation` | 认知遗忘周期干跑 |
| `propagate_staleness` | 跨引用扩散陈旧度评分 |
| `project_profile` | 会话启动智能摘要 |
| `dream_cycle` | 自主记忆富化（实体发现、损坏引用扫描、整合候选） |
#### 整合配置参数
| 参数 | 类型 | 默认值 | 说明 |
|-----|-----|-------|------|
| `importance_threshold` | float | 0.25 | 重要性阈值 |
| `stale_days` | int | 14 | 陈旧天数 |
| `archive_after_days` | int | 60 | 归档天数 |
| `grace_days` | int | 30 | 宽限期 |
### 知识核工具域（kernels）
知识核工具域提供了对`.mind`内核配置文件的只读访问，用于调整召回、排序和RM3扩展策略。
资料来源：[src/mind_mem/mcp/tools/kernels.py:1-40]()
#### 内核工具集
| 工具名称 | 功能描述 |
|---------|---------|
| `list_mind_kernels` | 列出可用内核配置文件 |
| `get_mind_kernel` | 获取指定内核配置详情 |
| `compiled_truth_load` | 加载实体真值页面 |
| `compiled_truth_add_evidence` | 添加证据到真值页面 |
| `compiled_truth_contradictions` | 检测真值页面的矛盾 |
### 上下文核心工具域（core）
上下文核心工具域封装了CoreRegistry单例，管理`.mmcore`便携式块的打包和知识图归档。
资料来源：[src/mind_mem/mcp/tools/core.py:1-45]()
#### 核心工具集
| 工具名称 | 功能描述 |
|---------|---------|
| `build_core` | 从活跃工作区构建.mmcore包 |
| `load_core` | 加载.mmcore包到内存 |
| `unload_core` | 卸载已加载的核心 |
| `list_cores` | 列出已注册的核心 |
#### mmcore包结构
```mermaid
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工具集
| 工具名称 | 功能描述 |
|---------|---------|
| `arch_baseline` | 初始化架构基线 |
| `arch_delta` | 计算当前扫描与基线的差异 |
| `arch_history` | 列出架构事件历史 |
| `arch_check_rules` | 应用规则到新扫描 |
| `arch_session_start` | 打开会话证据节点 |
| `arch_session_end` | 关闭会话并写入增量证据 |
| `arch_metric_explain` | 逐指标解释 |
### 基准测试工具域（benchmark）
基准测试工具域提供了治理健康度和类别摘要的评估工具。
资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-40]()
#### 基准工具集
| 工具名称 | 功能描述 |
|---------|---------|
| `governance_health_bench` | 治理健康基准测试（矛盾检测、审计完整性、漂移检测、可扩展性探测） |
| `category_summary` | 类别摘要蒸馏查找 |
## MCP工具元数据
所有MCP工具均通过以下装饰器实现统一观测：
### 装饰器链
```python
@mcp_tool_observe # 观测性装饰器
@_traced("tool_name") # 追踪装饰器
def tool_function(args):
...
```
### 返回格式
所有工具返回JSON格式字符串，包含标准模式版本头：
```json
{
"_schema_version": "3.2.0",
"tool_name": "result_data"
}
```
资料来源：[src/mind_mem/mcp/tools/governance.py:40-80]()
## 工作区感知
MCP工具集通过统一的`_workspace()`函数解析工作区路径：
```mermaid
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`：
| CLI命令 | 对应工具域 |
|--------|----------|
| `mm recall` | 记忆召回 |
| `mm context` | 上下文打包 |
| `mm inject` | 智能体上下文注入 |
| `mm vault` | 知识库扫描/写入 |
| `mm status` | 工作区摘要 |
| `mm explain` | 指标解释 |
| `mm trace` | MCP调用日志追踪 |
资料来源：[src/mind_mem/mm_cli.py:1-80]()
## 错误处理
MCP工具集采用统一的错误处理模式：
### 错误类型
| 错误类型 | 说明 | 处理方式 |
|---------|-----|---------|
| `WorkspaceError` | 工作区路径无效 | 返回错误JSON |
| `BlockCorruptedError` | 记忆块损坏 | 隔离并记录 |
| `CoreLoadError` | mmcore包解析失败 | 验证并报告 |
| `SQLiteBusyError` | 数据库锁定 | 重试或等待 |
### 错误响应格式
```json
{
"_schema_version": "3.2.0",
"error": "error_description"
}
```
## 配置集成
MCP工具集通过基础设施层获取配置：
```python
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工具示例](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-tool-examples.md)
- [MCP服务端架构](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_server.py)
---
## 治理与矛盾检测
### 相关页面
相关主题：[质量保障与验证](#page-quality), [检索管道](#page-recall)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)
- [src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)
- [src/mind_mem/governance_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py)
- [src/mind_mem/audit_chain.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)
# 治理与矛盾检测
## 概述
治理与矛盾检测是 mind-mem 系统的核心安全机制，确保记忆体的变更遵循"记忆永不直接修改，只能通过治理流程变更"的不变式。该模块涵盖了从提议、审批、应用到回滚的完整生命周期，同时提供矛盾检测、漂移检测和审计链验证等多层次防护。
核心设计原则：
- **治理驱动变更**：所有决策和任务的修改必须通过提议-审批流程
- **证据链完整**：每条证据都有时间戳、来源和可信度标记
- **矛盾优先检测**：在编译真理页面时自动检测冲突证据
- **可审计可回滚**：所有操作记录在案，支持快照回滚
资料来源：[src/mind_mem/mcp/tools/governance.py:1-20]()
## 架构总览
```mermaid
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)
治理门是记忆修改的守门人，确保所有变更必须通过标准流程。
```python
# 伪代码展示治理门工作流程
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
```
**治理门配置参数**：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `require_approval` | bool | true | 是否要求审批 |
| `contradiction_threshold` | float | 0.7 | 矛盾检测阈值 |
| `drift_tolerance` | int | 3 | 漂移容忍度 |
资料来源：[src/mind_mem/governance_gate.py]()
### 2. 矛盾检测器 (Contradiction Detector)
矛盾检测器分析编译真理页面的证据条目，识别相互冲突的陈述。
```mermaid
graph LR
A[Evidence Entry 1] --> D{矛盾检测}
B[Evidence Entry 2] --> D
C[Evidence Entry 3] --> D
D --> E[冲突报告]
E --> F[标记为 superseded]
```
**核心检测逻辑**：
```python
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)
漂移检测器监控决策或任务的实际执行与原始声明之间的偏离。
```mermaid
graph TD
A[原始声明] --> B[版本化快照]
C[当前状态] --> D{漂移计算}
B --> D
D --> E{超出容忍度?}
E -->|是| F[触发告警]
E -->|否| G[继续监控]
```
**漂移检测触发条件**：
- 决策状态与预期不符
- 任务优先级发生非预期变更
- 截止日期与原计划偏差超过阈值
- 关联实体发生未记录变更
资料来源：[src/mind_mem/drift_detector.py]()
### 4. 审计链 (Audit Chain)
审计链提供加密可验证的完整性证明，确保记忆体的历史不可篡改。
```mermaid
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[验证包含性]
```
**审计工具清单**：
| 工具 | 功能 | 输入 | 输出 |
|------|------|------|------|
| `verify_merkle` | Merkle包含证明 | block_id, content_hash | 证明 + ok标志 |
| `verify_chain` | 哈希链验证 | workspace路径 | 完整性报告 |
| `list_evidence` | 证据枚举 | block_id, action过滤 | 证据列表 |
| `mind_mem_verify` | CLI审计入口 | snapshot路径 | 验证结果 |
资料来源：[src/mind_mem/mcp/tools/audit.py:1-50]()
## MCP 治理工具
### propose_update - 提议更新
创建新的决策或任务提议，写入 SIGNALS.md 待人工审核。
**函数签名**：
```python
def propose_update(
block_type: str,
statement: str,
rationale: str = "",
tags: str = "",
confidence: str = "medium"
) -> str
```
**参数说明**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `block_type` | str | 是 | 块类型 (DECISION/TASK) |
| `statement` | str | 是 | 核心陈述 |
| `rationale` | str | 否 | 变更理由 |
| `tags` | str | 否 | 逗号分隔标签 |
| `confidence` | str | 否 | 可信度 (low/medium/high) |
**返回值示例**：
```json
{
"_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 - 审批应用
应用已通过的提议，支持干运行模式。
**核心流程**：
```mermaid
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 - 回滚提案
从预应用快照恢复工作区状态。
```mermaid
graph LR
A[当前状态] --> B[快照恢复]
B --> C[索引回退]
C --> D[信号重建]
```
**约束条件**：
- 只能回滚处于待应用状态的提案
- 快照必须在有效期内（默认7天）
- 回滚本身会产生新的治理记录
资料来源：[src/mind_mem/mcp/tools/governance.py:150-200]()
### scan - 完整性扫描
执行综合健康检查，覆盖矛盾检测、漂移检测和待处理项。
```python
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)
}
```
**扫描子项**：
| 子项 | 说明 | 阈值 |
|------|------|------|
| 矛盾数量 | 检测到的冲突证据对 | > 0 需关注 |
| 漂移事件 | 偏离原声明的变更 | > 3 需关注 |
| 待审批 | 队列中的提案数 | 无限制 |
| 审计完整性 | 哈希链连续性 | 必须完整 |
资料来源：[src/mind_mem/mcp/tools/governance.py:200-250]()
### list_contradictions - 矛盾列表
返回枚举的矛盾详情，支持富文本输出。
**输出格式**：
```json
{
"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 - 健康基准测试
运行治理健康基准测试套件，验证矛盾检测、审计完整性、漂移检测和可扩展性。
**测试子项**：
| 测试 | 覆盖范围 | 预期结果 |
|------|----------|----------|
| 矛盾检测探针 | 人工构造的矛盾场景 | 100%检出 |
| 审计完整性探针 | 哈希链断裂注入 | 正确检测 |
| 漂移探针 | 状态偏离注入 | 正确识别 |
| 可扩展性探针 | 大规模数据压力 | 性能可接受 |
**返回值结构**：
```json
{
"_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)
编译真理页面是矛盾检测的核心载体，聚合实体的所有证据并自动编译权威理解。
### 数据结构
```python
@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 # 版本号
```
### 证据条目
```python
@dataclass
class EvidenceEntry:
timestamp: str # ISO 8601 时间戳
source: str # 来源文件
observation: str # 观察内容
confidence: str # HIGH/MEDIUM/LOW
superseded: bool # 是否已被取代
```
### 矛盾检测集成
编译真理页面在重新编译时自动调用矛盾检测：
```python
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：
```python
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]()
## 工作流示例
### 决策变更完整流程
```mermaid
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: 健康报告
```
### 矛盾处理流程
```mermaid
graph TD
A[检测到矛盾] --> B{自动解决可能?}
B -->|否| C[人工审核]
C --> D[审查证据]
D --> E[选择保留哪条]
E --> F[取代旧证据]
B -->|是| G[自动取代低可信度]
G --> F
F --> H[重新编译]
H --> I[生成新版本]
I --> J[更新审计链]
```
## 配置选项
### 矛盾检测配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `contradiction_min_confidence_gap` | 0.3 | 最低可信度差距 |
| `auto_supersede_low_confidence` | true | 自动取代低可信度 |
| `contradiction_alert_threshold` | 2 | 告警阈值 |
### 审计配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `hash_algorithm` | SHA3-512 | 哈希算法 |
| `merkle_update_on_write` | true | 写入时更新Merkle树 |
| `audit_retention_days` | 365 | 审计保留天数 |
### 漂移检测配置
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `drift_check_interval_hours` | 24 | 检查间隔 |
| `drift_tolerance_priority` | 2 | 优先级容差 |
| `drift_tolerance_date_days` | 7 | 日期容差 |
## 相关命令
### mm CLI 治理命令
```bash
# 提议新决策
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 工具调用
```json
{
"tool": "propose_update",
"arguments": {
"block_type": "DECISION",
"statement": "迁移至微服务架构",
"rationale": "提升可扩展性",
"tags": "architecture, refactor",
"confidence": "high"
}
}
```
## 最佳实践
### 1. 矛盾预防
- 在添加新证据前先查询现有编译真理页面
- 使用高可信度来源标注证据
- 避免重复提交相似陈述
### 2. 治理流程
- 干运行优先，正式应用前验证
- 保持提议的原子性描述
- 定期运行健康扫描
### 3. 审计合规
- 验证哈希链完整性作为CI/CD环节
- 保留足够的快照以支持回滚
- 监控审计链验证失败事件
## 总结
治理与矛盾检测模块为 mind-mem 提供了企业级的记忆管理安全保障。通过"提议-审批-应用-回滚"的完整生命周期管理，确保了所有变更的可追溯性和可控性。矛盾检测与编译真理页面的深度集成，使得知识库的权威性得到持续维护，而审计链则为整个系统提供了密码学级别的完整性保证。
---
## 质量保障与验证
### 相关页面
相关主题：[治理与矛盾检测](#page-governance)
相关源码文件
以下源码文件用于生成本页说明：
- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)
- [src/mind_mem/block_parser.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)
- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
- [src/mind_mem/model_provenance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)
- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
# 质量保障与验证
mind-mem 采用多层次的质量保障体系，确保记忆块的可靠性、一致性和安全性。系统从内容存储前的预处理、解析时的验证、到运行时的矛盾检测，形成了完整的质量闭环。
## 质量门禁（Quality Gate）
质量门禁是记忆块写入前的第一道防线，位于 `src/mind_mem/quality_gate.py`。它是一个确定性、基于内容的预存储过滤器，对候选块进行检查并返回结构化裁决。
### 核心规则
质量门禁包含八条规则，全部为确定性规则，不依赖外部服务：
| 规则标识 | 规则名称 | 检查条件 | 处理方式 |
|---------|---------|---------|---------|
| `empty` | 空块检测 | 块内容为纯空白字符 | 标记并可拒绝 |
| `too_short` | 过短检测 | 非空白字符少于 32 个 | 标记并可拒绝 |
| `oversize` | 超大检测 | UTF-8 编码超过 64 KiB | 标记并可拒绝 |
| `malformed_utf8` | UTF-8 损坏检测 | 包含孤立代理或无法通过 UTF-8 往返 | 标记并可拒绝 |
| `stopwords_only` | 停用词检测 | 所有 token 均为停用词，无语义内容 | 标记并可拒绝 |
| `near_duplicate` | 近似重复检测 | 与 24 小时内块编辑距离相似度 ≥ 0.97 | 标记并可拒绝 |
| `injection_marker` | 注入标记检测 | 匹配已知提示注入模式 | 标记并可拒绝 |
| `ok` | 通过 | 无规则触发 | 接受 |
### 裁决模式
质量门禁支持两种裁决模式：
- **顾问模式（默认）**：每条规则都会被记录，但裁决仍返回 `accept`
- **严格模式（strict）**：任何规则触发都导致 `reject`
严格模式可通过以下方式启用：
1. 调用时传入 `strict=True` 关键字参数
2. 工作区 `QualityGateConfig(mode="strict")`
3. 工作区配置 `mind-mem.json` 中的 `quality_gate_mode = "strict"`
### 工作流程
```mermaid
graph TD
A[接收候选块] --> B[执行 8 条规则检查]
B --> C{触发任何规则?}
C -->|否| D[裁决: accept]
C -->|是| E{strict 模式?}
E -->|否| F[记录日志]
F --> D
E -->|是| G[裁决: reject]
D --> H[写入存储]
G --> I[返回错误信息]
```
### 返回数据结构
```python
@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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)
## 块解析质量控制
`src/mind_mem/block_parser.py` 负责从文本中解析记忆块，解析过程内置了多项质量验证机制。
### UTF-8 BOM 处理
解析器首先检查并处理 UTF-8 BOM（Byte Order Mark）：
```python
if text.startswith(''):
text = text[1:]
```
这确保第一个块头不会被 BOM 字符遮挡，保证解析的一致性。
### 否定块识别
系统内置否定块检测正则表达式，用于识别语义反转的声明：
```python
_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 解析，识别以下嵌套字段：
| 字段名 | 用途 |
|-------|------|
| `scope` | 约束作用范围 |
| `axis` | 约束维度 |
| `lifecycle` | 生命周期阶段 |
解析器维护内部状态机，正确处理嵌套结构和操作符列表。
资料来源：[src/mind_mem/block_parser.py:1-80](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)
## 编译真相与矛盾检测
编译真相（Compiled Truth）是 mind-mem 的核心概念之一，位于 `src/mind_mem/compiled_truth.py`。它通过聚合证据来维护实体的规范理解。
### 证据条目结构
```python
@dataclass
class EvidenceEntry:
timestamp: str # ISO 时间戳
source: str # 来源标识
observation: str # 观察内容
confidence: str # 置信度: high/medium/low
superseded: bool # 是否已被替代
```
### 编译真相页面结构
| 字段 | 说明 |
|-----|------|
| `entity_id` | 实体唯一标识符 |
| `entity_type` | 实体类型 |
| `compiled_section` | 当前规范理解（摘要） |
| `evidence_entries` | 证据条目列表 |
| `last_compiled` | 最后编译时间 |
| `version` | 版本号 |
### 矛盾检测
系统提供 `detect_contradictions()` 函数用于检测编译真相页面中的矛盾：
```python
def detect_contradictions(page: CompiledTruthPage) -> list[ContradictionPair]:
"""检测页面中的矛盾证据对"""
```
矛盾检测通过以下步骤工作：
1. 遍历所有未废弃的证据条目
2. 比较语义相反的陈述
3. 识别否定关系（如 "应该使用 X" vs "不应该使用 X"）
4. 返回矛盾对列表
### 证据替代机制
当新证据与旧证据矛盾时，系统支持标记旧证据为已废弃：
```python
def supersede_evidence(
page: CompiledTruthPage,
entry_index: int,
reason: str
) -> CompiledTruthPage:
```
替代后的旧证据保留在历史中，但不影响规范理解的生成。
资料来源：[src/mind_mem/compiled_truth.py:1-150](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)
## 治理工具与矛盾扫描
MCP 工具提供程序化的质量保障能力，位于 `src/mind_mem/mcp/tools/governance.py`。
### 可用工具
| 工具名称 | 功能 |
|---------|------|
| `propose_update` | 提议新决策或任务，写入 SIGNALS.md 待人工审核 |
| `approve_apply` | 应用已提议的更新（默认干跑模式） |
| `rollback_proposal` | 从预应用快照恢复工作区 |
| `scan` | 完整性扫描（矛盾/漂移/待处理） |
| `list_contradictions` | 矛盾列表的富文本展示 |
| `memory_evolution` | 获取块的 A-MEM 元数据 |
### 扫描操作
`scan` 工具执行三类检查：
1. **矛盾检测**：识别同一实体的相互冲突的证据
2. **漂移检测**：检测规范理解与实际证据的不一致
3. **待处理检测**：列出未处理的信号和提案
### SQLite 锁处理
扫描操作使用 SQLite 数据库，工具内置锁冲突处理：
```python
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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)
## 模型溯源验证
`src/mind_mem/model_provenance.py` 提供模型出处检查能力，确保引用的模型信息准确。
### 支持的发布商
| 发布商 | Slug 标识 | 模型家族 |
|-------|----------|---------|
| Meta Llama | `meta-llama` | Llama 2/3/4 |
| Mistral | `mistralai` | Mistral/Mixtral/Codestral |
| Google Gemma | `google` | Gemma/Gemma-2/PaLM |
| IBM Granite | `ibm-granite`, `ibm` | Granite-3/Granite-Code |
| DeepSeek | `deepseek-ai` | DeepSeek-V2/V3/R1 |
| Microsoft Phi | `microsoft` | Phi-2/Phi-3/Phi-4 |
| TII Falcon | `tiiuae` | Falcon-7B/40B/180B |
### ProvenanceFinding 结果
```python
@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](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)
## 删除恢复与审计
系统维护删除操作的全量审计日志，支持误删恢复。
### 删除收据格式
删除块时，系统将删除收据写入 `memory/deleted_blocks.jsonl`：
```json
{
"block_id": "D-20260213-001",
"deleted_at": "2026-03-15T10:30:00+00:00",
"content": "原始块内容..."
}
```
### 块定位逻辑
删除收据记录使用与 `mcp.tools.memory_ops.delete_memory_item` 相同的边界规则：
- 块从 `[]` 行开始
- 块结束于下一个 `[]` 头行、孤立的 `---` 分隔符或 EOF
这确保两个删除路径收敛到同一恢复日志格式。
资料来源：[src/mind_mem/block_store.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)
## 配置与指标
### 质量门禁配置优先级
```
1. 函数调用 strict=True 参数（最高优先级）
2. QualityGateConfig(mode="strict") 对象
3. mind-mem.json 中的 quality_gate_mode 设置
4. 默认值（advisory 模式）
```
### 质量指标
系统通过 `metrics.inc()` 追踪质量事件：
| 指标名称 | 触发场景 |
|---------|---------|
| `truth_pages_loaded` | 编译真相页面加载 |
| `evidence_entries_superseded` | 证据被替代 |
| `mcp_compiled_truth_add_evidence` | 添加新证据 |
| `contradictions_detected` | 检测到矛盾 |
### 日志记录
质量事件通过结构化日志记录：
```python
_log.info(
"evidence_superseded",
entity_id=page.entity_id,
index=entry_index,
reason=reason,
)
```
日志输出到 `MIND_MEM_LOG_FILE` 或标准输出。
## 最佳实践
### 启用严格模式
对于生产环境，建议在工作区配置中启用严格模式：
```json
{
"quality_gate_mode": "strict"
}
```
### 定期扫描
使用 MCP 工具 `scan` 定期检查工作区一致性：
```bash
mm mcp call scan --scan-type full
```
### 矛盾审查
当检测到矛盾时，通过 `list_contradictions` 工具获取详细信息：
```bash
mm mcp call list_contradictions
```
### 删除恢复
误删块后，可通过 `deleted_blocks.jsonl` 恢复内容：
```bash
# 查看最近删除
tail -n 10 memory/deleted_blocks.jsonl
---
---
## Doramagic 踩坑日志
项目：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