{
"canonical_name": "star-ga/mind-mem",
"compilation_id": "pack_72c4805f48fc4900bfde2aee65daa082",
"created_at": "2026-05-16T06:24:16.209446+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install mind-mem` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install mind-mem",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_91588807859145a8bfc972a96935c790"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_fcb16e23f2652babd81f42ac72b888a8",
"canonical_name": "star-ga/mind-mem",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/star-ga/mind-mem",
"slug": "mind-mem",
"source_packet_id": "phit_af10547ef6174d4bbcb9e3b2477a5991",
"source_validation_id": "dval_70536ae0c26943dab978c2fbdfba0cd9"
},
"merchandising": {
"best_for": "需要安全审查与权限治理能力，并使用 mcp_host的用户",
"github_forks": 1,
"github_stars": 6,
"one_liner_en": "Persistent AI memory for Claude Code, OpenClaw, and any MCP-compatible agent. v4.0.8 — closes #526-#529 (ACL fail-closed, vclock bump, merge audit, FederationClient hardening). BM25F+vector hybrid, governance-aware, 5428+ tests, 84 MCP tools, 15 clients.",
"one_liner_zh": "Persistent AI memory for Claude Code, OpenClaw, and any MCP-compatible agent. v4.0.8 — closes #526-#529 (ACL fail-closed, vclock bump, merge audit, FederationClient hardening). BM25F+vector hybrid, governance-aware, 5428+ tests, 84 MCP tools, 15 clients.",
"primary_category": {
"category_id": "security-permissions",
"confidence": "high",
"name_en": "Security & Permissions",
"name_zh": "安全审查与权限治理",
"reason": "strong category phrase match from project identity and outcome"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "mind-mem",
"title_zh": "mind-mem 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_af10547ef6174d4bbcb9e3b2477a5991",
"page_model": {
"artifacts": {
"artifact_slug": "mind-mem",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install mind-mem",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/star-ga/mind-mem#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "安全审查与权限治理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要安全审查与权限治理能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Persistent AI memory for Claude Code, OpenClaw, and any MCP-compatible agent. v4.0.8 — closes #526-#529 (ACL fail-closed, vclock bump, merge audit, FederationClient hardening). BM25F+vector hybrid, governance-aware, 5428+ tests, 84 MCP tools, 15 clients."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code, cursor",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_366d8c18c1aa45ffb07174af516285d4 | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-251)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_1e9c9207806f46a6a90a83828e99c173 | https://github.com/star-ga/mind-mem/issues/529 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ea39fdeb939e484a9be8751555483fc5 | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d71f093408f04636bc91f85df44c811d | https://github.com/star-ga/mind-mem/issues/508 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7bf148881d754982a8b6bbb0959436d0 | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_afb67087422e43678c941140da7019de | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_0917cf4b43b34ffe8d43e599d353665c | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 5,
"forks": 1,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 6
},
"source_url": "https://github.com/star-ga/mind-mem",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Persistent AI memory for Claude Code, OpenClaw, and any MCP-compatible agent. v4.0.8 — closes #526-#529 (ACL fail-closed, vclock bump, merge audit, FederationClient hardening). BM25F+vector hybrid, governance-aware, 5428+ tests, 84 MCP tools, 15 clients.",
"title": "mind-mem 能力包",
"trial_prompt": "# mind-mem - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mind-mem 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client / claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：MIND-Mem简介。围绕“MIND-Mem简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-features：核心功能一览。围绕“核心功能一览”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-data-flow：数据流与处理管道。围绕“数据流与处理管道”模拟一次用户任务，不展示安装或运行结果。\n5. page-storage：存储后端。围绕“存储后端”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“MIND-Mem简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-features\n输入：用户提供的“核心功能一览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-data-flow\n输入：用户提供的“数据流与处理管道”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-storage\n输入：用户提供的“存储后端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“MIND-Mem简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-features：Step 2 必须围绕“核心功能一览”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-data-flow：Step 4 必须围绕“数据流与处理管道”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-storage：Step 5 必须围绕“存储后端”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/star-ga/mind-mem\n- https://github.com/star-ga/mind-mem#readme\n- .agents/skills/mind-mem-development/SKILL.md\n- skills/apply-proposal/SKILL.md\n- skills/integrity-scan/SKILL.md\n- skills/memory-recall/SKILL.md\n- README.md\n- SPEC.md\n- mind/recall.mind\n- mind/governance.mind\n- mind/mic_map_quickstart.py\n- docs/architecture.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mind-mem 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Perf regression: build_index on a fresh 80KB workspace takes ~55s（https://github.com/star-ga/mind-mem/issues/530）；github/github_issue: FederationClient: no scheme allowlist, no redirect cap, no response-size（https://github.com/star-ga/mind-mem/issues/529）；github/github_issue: `_handle_fed_resolve` accepts caller-supplied merged_payload without val（https://github.com/star-ga/mind-mem/issues/528）；github/github_issue: THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every （https://github.com/star-ga/mind-mem/issues/527）；github/github_issue: ACL `_get_request_scope` fail-open on token-introspection exception (acl（https://github.com/star-ga/mind-mem/issues/526）；github/github_issue: PG-backed: `mm recall` returns [] despite direct PG FTS finding matches（https://github.com/star-ga/mind-mem/issues/525）；github/github_issue: PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks（https://github.com/star-ga/mind-mem/issues/524）；github/github_issue: test_rollback_removes_new_files fails on macOS + Windows runners (passes（https://github.com/star-ga/mind-mem/issues/515）；github/github_issue: [MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' b（https://github.com/star-ga/mind-mem/issues/513）；github/github_issue: [MEDIUM] T-003: propose_update input bounds bypass (rationale/tags writt（https://github.com/star-ga/mind-mem/issues/512）；github/github_issue: [MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'（https://github.com/star-ga/mind-mem/issues/511）；github/github_issue: [MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field（https://github.com/star-ga/mind-mem/issues/510）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Perf regression: build_index on a fresh 80KB workspace takes ~55s",
"url": "https://github.com/star-ga/mind-mem/issues/530"
},
{
"kind": "github_issue",
"source": "github",
"title": "FederationClient: no scheme allowlist, no redirect cap, no response-size",
"url": "https://github.com/star-ga/mind-mem/issues/529"
},
{
"kind": "github_issue",
"source": "github",
"title": "`_handle_fed_resolve` accepts caller-supplied merged_payload without val",
"url": "https://github.com/star-ga/mind-mem/issues/528"
},
{
"kind": "github_issue",
"source": "github",
"title": "THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every ",
"url": "https://github.com/star-ga/mind-mem/issues/527"
},
{
"kind": "github_issue",
"source": "github",
"title": "ACL `_get_request_scope` fail-open on token-introspection exception (acl",
"url": "https://github.com/star-ga/mind-mem/issues/526"
},
{
"kind": "github_issue",
"source": "github",
"title": "PG-backed: `mm recall` returns [] despite direct PG FTS finding matches",
"url": "https://github.com/star-ga/mind-mem/issues/525"
},
{
"kind": "github_issue",
"source": "github",
"title": "PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks",
"url": "https://github.com/star-ga/mind-mem/issues/524"
},
{
"kind": "github_issue",
"source": "github",
"title": "test_rollback_removes_new_files fails on macOS + Windows runners (passes",
"url": "https://github.com/star-ga/mind-mem/issues/515"
},
{
"kind": "github_issue",
"source": "github",
"title": "[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' b",
"url": "https://github.com/star-ga/mind-mem/issues/513"
},
{
"kind": "github_issue",
"source": "github",
"title": "[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags writt",
"url": "https://github.com/star-ga/mind-mem/issues/512"
},
{
"kind": "github_issue",
"source": "github",
"title": "[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'",
"url": "https://github.com/star-ga/mind-mem/issues/511"
},
{
"kind": "github_issue",
"source": "github",
"title": "[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field",
"url": "https://github.com/star-ga/mind-mem/issues/510"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "安全审查与权限治理",
"desc": "Persistent AI memory for Claude Code, OpenClaw, and any MCP-compatible agent. v4.0.8 — closes #526-#529 (ACL fail-closed, vclock bump, merge audit, FederationClient hardening). BM25F+vector hybrid, governance-aware, 5428+ tests, 84 MCP tools, 15 clients.",
"effort": "安装已验证",
"forks": 1,
"icon": "shield",
"name": "mind-mem 能力包",
"risk": "可发布",
"slug": "mind-mem",
"stars": 6,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "purple",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/star-ga/mind-mem 项目说明书\n\n生成时间：2026-05-16 01:43:31 UTC\n\n## 目录\n\n- [MIND-Mem简介](#page-introduction)\n- [核心功能一览](#page-features)\n- [系统架构](#page-architecture)\n- [数据流与处理管道](#page-data-flow)\n- [存储后端](#page-storage)\n- [检索管道](#page-recall)\n- [MCP服务器](#page-mcp-server)\n- [MCP工具集](#page-mcp-tools)\n- [治理与矛盾检测](#page-governance)\n- [质量保障与验证](#page-quality)\n\n\n\n## MIND-Mem简介\n\n### 相关页面\n\n相关主题：[核心功能一览](#page-features), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/star-ga/mind-mem/blob/main/README.md)\n- [SPEC.md](https://github.com/star-ga/mind-mem/blob/main/SPEC.md)\n- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n \n\n# MIND-Mem简介\n\n## 项目概述\n\nMIND-Mem 是一个用于 AI 代理的**结构化记忆与推理框架**，它为多代理协作场景提供持久化记忆存储、检索和治理能力。该项目基于文件系统存储，采用 Markdown 格式管理记忆块，并通过 MCP（Model Context Protocol）协议对外提供服务接口。\n\nMIND-Mem 的核心设计理念是：**记忆永不直接修改，只能通过治理流程变更**。这一 invariant 确保了记忆系统的完整性和可审计性。\n\n资料来源：[SPEC.md](https://github.com/star-ga/mind-mem/blob/main/SPEC.md)\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 用户层\n CLI[CLI工具
mm命令]\n MCP[MCP客户端]\n Web[Web控制台]\n API[REST API]\n end\n \n subgraph MCP服务层\n MS[MCP Server
mcp_server.py]\n KERNEL[Kernel工具]\n GOVERNANCE[治理工具]\n AUDIT[审计工具]\n MEMORY[内存操作工具]\n end\n \n subgraph 核心存储层\n FTS[FTS5全文索引]\n BLOCKS[记忆块文件
.md格式]\n CT[Compiled Truth
编译真相页]\n LEDGER[多代理事实账本]\n end\n \n CLI --> MS\n MCP --> MS\n Web --> API\n API --> MS\n MS --> FTS\n MS --> BLOCKS\n MS --> CT\n MS --> LEDGER\n```\n\n### 核心组件\n\n| 组件名称 | 文件路径 | 功能描述 |\n|---------|---------|---------|\n| MCP Server | `src/mind_mem/mcp_server.py` | MCP协议服务核心，处理所有MCP工具调用 |\n| CLI工具 | `src/mind_mem/mm_cli.py` | 统一命令行接口，支持recall、context、inject等命令 |\n| 记忆块解析器 | `src/mind_mem/block_parser.py` | 解析和管理.md格式的记忆块文件 |\n| 编译真相 | `src/mind_mem/compiled_truth.py` | 实体真相页面的聚合和编译 |\n| 质量门 | `src/mind_mem/quality_gate.py` | 预存储过滤器，验证记忆块质量 |\n| Web控制台 | `web/` | 基于Next.js的可视化界面 |\n\n资料来源：[mm_cli.py:1-20](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n## 核心功能\n\n### 2.1 记忆检索与上下文管理\n\nMIND-Mem 提供多种检索方式满足不同场景需求：\n\n#### CLI命令接口\n\n```bash\nmm recall \"\" # BM25语义搜索\nmm context \"\" # 生成token预算受限的片段\nmm inject --agent \"\" # 为特定代理渲染片段\nmm vault scan # 列出解析的vault块\nmm status # 工作区摘要\n```\n\n资料来源：[mm_cli.py:1-20](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n#### MCP资源接口\n\n| 资源标识 | 功能 |\n|---------|------|\n| `mind-mem://decisions` | 活动决策列表（DECISIONS.md） |\n| `mind-mem://tasks` | 所有任务（TASKS.md） |\n| `mind-mem://entities/{type}` | 项目、人员、工具、事件实体 |\n| `mind-mem://signals` | 自动捕获的信号 |\n| `mind-mem://contradictions` | 检测到的矛盾 |\n| `mind-mem://health` | 工作区健康摘要 |\n| `mind-mem://recall/{query}` | BM25召回搜索 |\n| `mind-mem://ledger` | 共享多代理事实账本 |\n\n资料来源：[mcp/resources.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n\n### 2.2 编译真相系统\n\n编译真相（Compiled Truth）是 MIND-Mem 的核心知识沉淀机制：\n\n```mermaid\ngraph LR\n subgraph 证据收集\n MD1[memory/xxx.md]\n MD2[memory/yyy.md]\n MD3[DECISIONS.md]\n end\n \n subgraph 处理流程\n SC[句子提取]\n NORM[规范化]\n COUNT[出现计数]\n end\n \n subgraph 真相页生成\n CT[Compiled Truth Page
compiled/xxx.md]\n ENTRY[Evidence Entry
证据条目]\n end\n \n MD1 --> SC\n MD2 --> SC\n MD3 --> SC\n SC --> NORM\n NORM --> COUNT\n COUNT -->|min_mentions≥3| CT\n CT --> ENTRY\n```\n\n**核心特性：**\n- 自动从多个 Markdown 文件中提取和聚合事实\n- 支持证据条目的时间戳、来源和置信度\n- 提供 `recompilation` 重新编译功能\n- 支持证据条目的 `superseded` 标记\n\n资料来源：[compiled_truth.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n### 2.3 治理与审计\n\nMIND-Mem 遵循\"**记忆永不直接修改，只通过治理变更**\"的原则：\n\n#### 治理工具集\n\n| 工具名称 | 功能 |\n|---------|------|\n| `propose_update` | 将新决策/任务暂存为 SIGNAL |\n| `approve_apply` | 应用暂存的提案（默认dry-run） |\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理） |\n| `list_contradictions` | 枚举检测到的矛盾 |\n| `memory_evolution` | 获取记忆块的A-MEM元数据 |\n\n资料来源：[mcp/tools/governance.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n\n#### 审计工具集\n\n| 工具名称 | 功能 |\n|---------|------|\n| `verify_merkle` | 验证块的Merkle包含证明 |\n| `verify_chain` | 验证SHA3-512哈希链完整性 |\n| `list_evidence` | 枚举治理证据对象 |\n| `mind_mem_verify` | 暴露独立验证CLI |\n\n资料来源：[mcp/tools/audit.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)\n\n### 2.4 质量门控\n\n质量门（Quality Gate）是预存储过滤器，确保进入系统的记忆块符合标准：\n\n```mermaid\ngraph TD\n INPUT[候选记忆块] --> QG{质量门}\n QG --> E1{空块?}\n QG --> E2{过短?}\n QG --> E3{过大?}\n QG --> E4{UTF-8错误?}\n QG --> E5{仅停用词?}\n QG --> E6{近似重复?}\n QG --> E7{注入标记?}\n QG --> OK[通过]\n E1 -->|是| LOG1[日志记录]\n E2 -->|是| LOG2[日志记录]\n E3 -->|是| LOG3[日志记录]\n E4 -->|是| LOG4[日志记录]\n E5 -->|是| LOG5[日志记录]\n E6 -->|是| LOG6[日志记录]\n E7 -->|是| LOG7[日志记录]\n LOG1 --> OK\n LOG2 --> OK\n LOG3 --> OK\n LOG4 --> OK\n LOG5 --> OK\n LOG6 --> OK\n LOG7 --> OK\n```\n\n**八条质量规则：**\n\n| 规则ID | 规则名称 | 判定条件 | 默认行为 |\n|-------|---------|---------|---------|\n| 1 | `empty` | 块内容为空或仅空白 | 接受+日志 |\n| 2 | `too_short` | 少于32个非空白字符 | 接受+日志 |\n| 3 | `oversize` | 超过64KB UTF-8字节 | 拒绝 |\n| 4 | `malformed_utf8` | 包含孤立代理符 | 拒绝 |\n| 5 | `stopwords_only` | 所有token都是停用词 | 接受+日志 |\n| 6 | `near_duplicate` | 与24h内块相似度≥0.97 | 接受+日志 |\n| 7 | `injection_marker` | 匹配已知注入模式 | 拒绝 |\n| 8 | `ok` | 无规则触发 | 接受 |\n\n支持 `strict=True` 模式，所有规则均变为硬性拒绝。\n\n资料来源：[quality_gate.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n\n## MCP工具分类\n\n### 3.1 Kernel工具\n\n提供对 `.mind` 内核配置文件的读写访问：\n\n- `list_mind_kernels` — 列出可用内核\n- `get_mind_kernel` — 获取特定内核配置\n- `compiled_truth_load` — 加载真相页\n- `compiled_truth_add_evidence` — 添加证据\n- `compiled_truth_contradictions` — 检测矛盾\n\n资料来源：[mcp/tools/kernels.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n\n### 3.2 内存操作工具\n\n工作区生命周期和内省接口：\n\n- `index_stats` / `reindex` — FTS5索引状态和重建\n- `delete_memory_item` — 原子性记忆块删除\n- `export_memory` — JSONL格式导出\n- `get_block` / `memory_health` — 块查询和健康仪表盘\n- `compact` / `stale_blocks` — 压缩和陈旧块管理\n\n资料来源：[mcp/tools/memory_ops.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)\n\n### 3.3 架构思维工具\n\n整合 `arch-mind` 二进制工具作为 MCP 工具：\n\n- `arch_baseline` — 初始化基准\n- `arch_delta` — 计算delta分数\n- `arch_history` — 列出历史事件\n- `arch_check_rules` — 应用规则检查\n- `arch_session_start` / `arch_session_end` — 会话管理\n- `arch_metric_explain` — 指标分解\n\n资料来源：[mcp/tools/arch_mind.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)\n\n## 工作区结构\n\n```\n{workspace}/\n├── DECISIONS.md # 活动决策\n├── TASKS.md # 任务列表\n├── SIGNALS.md # 待审查信号\n├── memory/ # 记忆块存储\n│ ├── *.md\n│ └── ...\n├── entities/\n│ └── compiled/ # 编译真相页\n│ └── *.md\n├── .mind/ # 内核配置\n│ └── *.mind\n└── index.db # FTS5全文索引\n```\n\n## Web控制台\n\n基于 Next.js 的可视化界面，提供三种视图：\n\n```mermaid\ngraph TD\n subgraph Web控制台\n SUBMIT[查询提交]\n API[REST API调用]\n subgraph 三面板展示\n GRAPH[力导向图
GraphView]\n TIMELINE[时间轴
TimelineView]\n FACTS[事实列表
FactList]\n end\n end\n \n SUBMIT --> API\n API --> GRAPH\n API --> TIMELINE\n API --> FACTS\n```\n\n**启动方式：**\n```bash\ncd web\npnpm install\npnpm dev # → http://localhost:3000\n```\n\n资料来源：[web/README.md:1-40](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n\n## 快速开始\n\n### 安装\n\n```bash\npip install -e .\n```\n\n### CLI基本用法\n\n```bash\n# 初始化工作区\nexport MIND_MEM_WORKSPACE=/path/to/workspace\n\n# 搜索记忆\nmm recall \"PostgreSQL决策历史\"\n\n# 生成上下文\nmm context \"最近的架构变更\"\n\n# 注入特定代理上下文\nmm inject --agent claude \"当前项目技术栈\"\n```\n\n### API使用\n\n```python\nfrom mind_mem import recall\n\nresults = recall(\"/path/to/workspace\", \"query\", limit=10)\n```\n\n## v4.0 预览\n\nMIND-Mem v4.0 正在开发中，带来以下新特性（当前默认关闭，需通过 `mind-mem.json` 开启）：\n\n| 功能组 | 特性 | 状态 |\n|-------|------|------|\n| A. 认知/模型层 | 分层记忆、认知内核、惊喜权重检索 | 规划中 |\n| B. 知识图谱 | 实体/概念提取、长上下文召回、LLM融合、流式检索、对话层 | 规划中 |\n| C. 知识治理 | 空闲后台摄入、AI lint、矛盾状态机、自愈索引 | 规划中 |\n\n资料来源：[v4/__init__.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n\n## 总结\n\nMIND-Mem 是一个设计严谨的 AI 记忆框架，通过以下核心机制保障系统的可靠性和可追溯性：\n\n1. **文件系统优先** — Markdown格式存储，便于版本控制和人类阅读\n2. **治理驱动变更** — 记忆只能通过正式提案→审批流程修改\n3. **多协议支持** — 同时提供CLI、MCP和REST API接口\n4. **质量门控** — 预存储过滤器确保数据质量\n5. **可审计性** — Merkle证明和哈希链验证数据完整性\n\n---\n\n\n\n## 核心功能一览\n\n### 相关页面\n\n相关主题：[MIND-Mem简介](#page-introduction), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)\n- [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)\n- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)\n- [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)\n- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n- [src/mind_mem/model_provenance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)\n \n\n# 核心功能一览\n\nmind-mem 是一个多智能体记忆管理系统，提供了完整的信息召回、治理、压缩和长期记忆维护能力。本页概述系统的核心功能模块，包括 MCP 工具、CLI 接口、编译事实系统和 v4.0 特性预览。\n\n## 1. 系统架构总览\n\nmind-mem 采用分层架构设计，核心组件包括：\n\n```mermaid\ngraph TD\n subgraph \"接口层\"\n CLI[CLI 命令行工具
mm]\n MCP[MCP 服务器
Model Context Protocol]\n REST[REST API
v3.2.0+]\n end\n \n subgraph \"功能域\"\n RECALL[召回 Recall]\n GOV[治理 Governance]\n CONSOL[记忆整合 Consolidation]\n MEMOPS[记忆操作 Memory Ops]\n end\n \n subgraph \"核心引擎\"\n FTS[FTS5 全文索引]\n BLOCK[Block Parser]\n COMPILED[Compiled Truth]\n COGNITIVE[认知遗忘 Cognitive Forget]\n end\n \n subgraph \"存储层\"\n WORKSPACE[Workspace 目录]\n MIND[MIND 内核配置]\n DB[(SQLite FTS5)]\n end\n \n CLI --> RECALL\n MCP --> RECALL\n MCP --> GOV\n MCP --> CONSOL\n MCP --> MEMOPS\n \n RECALL --> FTS\n GOV --> BLOCK\n CONSOL --> COGNITIVE\n \n FTS --> DB\n BLOCK --> WORKSPACE\n COMPILED --> WORKSPACE\n COGNITIVE --> WORKSPACE\n```\n\n## 2. MCP 工具集\n\nMCP（Model Context Protocol）服务器提供标准化工具接口，支持 Claude Code、Codex CLI、Cursor、Windsurf 等 AI 客户端直接调用记忆功能。工具按功能域分为以下类别：\n\n### 2.1 KERNELS 域 — MIND 内核配置\n\n负责管理和配置召回、排序和管道参数的内核文件访问。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `list_mind_kernels` | 列出所有可用的 .mind 内核配置文件 | [kernels.py:28-48](src/mind_mem/mcp/tools/kernels.py) |\n| `get_mind_kernel` | 获取指定内核配置详情 | [kernels.py:28-48](src/mind_mem/mcp/tools/kernels.py) |\n\n内核配置控制项包括：\n- 召回权重调优（recall tuning）\n- 重排序参数（reranking）\n- RM3 扩展配置\n- 管道级联参数\n\n### 2.2 GOVERNANCE 域 — 治理与生命周期\n\n治理域是\"记忆永不直接修改\"原则的核心实现，所有变更必须经过治理流程。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `propose_update` | 提案新决策或任务，写入 SIGNALS.md 待人工审核 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `approve_apply` | 应用已批准提案（默认干运行模式） | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `rollback_proposal` | 从预应用快照恢复工作区 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `scan` | 完整性扫描（矛盾检测/漂移检测/待处理项） | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `list_contradictions` | 列出检测到的矛盾项 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `memory_evolution` | 获取区块的 A-MEM 元数据 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n\n**治理工作流：**\n\n```mermaid\ngraph LR\n A[propose_update
提案阶段] --> B{SIGNALS.md}\n B --> C[人工审核]\n C --> D{approve_apply
批准应用}\n D -->|干运行 OK| E[正式应用]\n D -->|发现问题| F[rollback_proposal
回滚]\n E --> G[区块更新]\n F --> H[快照恢复]\n```\n\n### 2.3 CONSOLIDATION 域 — 记忆整合\n\n\"记忆随时间沉淀\"表面，实现认知遗忘和自动整合机制。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `plan_consolidation` | 认知遗忘周期干运行 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n| `propagate_staleness` | 跨引用扩散陈旧度分数 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n| `project_profile` | 会话启动情报摘要 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n| `dream_cycle` | 自主记忆丰富（实体发现/断裂引用扫描/整合候选/自动修复） | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n\n### 2.4 MEMORY_OPS 域 — 记忆操作\n\n工作区生命周期和内省操作，处理索引、删除、导出等管理任务。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `index_stats` | FTS5 索引状态查询 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `reindex` | 重建全文索引 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `delete_memory_item` | 原子化管理员范围区块移除 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `export_memory` | JSONL 格式完整导出 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `get_block` | 单区块查询 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `memory_health` | 健康状态仪表盘 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `compact` | 存储压缩 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `stale_blocks` | 陈旧区块标记管理 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n\n### 2.5 BENCHMARK 域 — 基准测试\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `governance_health_bench` | 矛盾检测/审计完整性/漂移/可扩展性探测 | [benchmark.py:24-50](src/mind_mem/mcp/tools/benchmark.py) |\n| `category_summary` | 类别蒸馏器查询 | [benchmark.py:52-75](src/mind_mem/mcp/tools/benchmark.py) |\n\n### 2.6 ARCH_MIND 域 — 架构知识管理\n\n包装 `arch-mind` 二进制工具，提供架构基线、历史记录、规则检查和会话管理。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `arch_baseline` | 初始化架构基线 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_delta` | 计算当前扫描与基线的差异 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_history` | 列出架构历史事件 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_check_rules` | 应用规则文件检查 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_session_start` | 开启会话证据节点 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_session_end` | 关闭会话并写入增量证据 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_metric_explain` | 单指标详细分解 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n\n## 3. CLI 命令行工具\n\n`mm` 命令提供 MCP 之外的轻量级接口，适用于非 MCP 智能体。\n\n```bash\nmm recall \"\" # 搜索记忆\nmm context \"\" # 生成预算限制的片段\nmm inject --agent \"\" # 为特定智能体渲染片段\nmm vault scan # 列出解析的 vault 块\nmm vault write --type --body \nmm status # 工作区摘要\nmm trace --live # 实时流式 MCP 调用日志\nmm trace --last 20 --tool xxx # 最近 N 次工具调用\n```\n\n资料来源：[mm_cli.py:1-50](src/mind_mem/mm_cli.py)\n\n## 4. 编译事实系统\n\n编译事实（Compiled Truth）是按实体聚合证据并重新编译权威理解的关键机制。\n\n### 4.1 核心概念\n\n```mermaid\ngraph TD\n subgraph \"来源\"\n SOURCE1[memory/决策A.md]\n SOURCE2[memory/任务B.md]\n SOURCE3[memory/事件C.md]\n end\n \n subgraph \"候选提取\"\n SENTENCE[句子提取
频率≥3]\n CANDIDATE[事实候选]\n end\n \n subgraph \"编译事实页\"\n ENTITY[实体标识]\n EVIDENCE[证据条目列表]\n CANONICAL[权威摘要]\n VERSION[版本号]\n LAST_COMPILED[最后编译时间]\n end\n \n SOURCE1 --> SENTENCE\n SOURCE2 --> SENTENCE\n SOURCE3 --> SENTENCE\n SENTENCE --> CANDIDATE\n CANDIDATE --> EVIDENCE\n EVIDENCE --> CANONICAL\n CANONICAL --> ENTITY\n```\n\n### 4.2 编译事实数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `entity_id` | str | 实体唯一标识 |\n| `evidence_entries` | list | 证据条目列表 |\n| `compiled_summary` | str | 权威摘要文本 |\n| `version` | int | 编译版本号 |\n| `last_compiled` | datetime | 最后编译时间 |\n| `superseded_entries` | list | 已废弃条目 |\n\n### 4.3 关键函数\n\n| 函数 | 功能 | 资料来源 |\n|-----|------|----------|\n| `extract_compiled_truth_candidates` | 从 memory/ 目录提取候选事实 | [compiled_truth.py:30-80](src/mind_mem/compiled_truth.py) |\n| `supersede_evidence_entry` | 标记证据条目为已废弃 | [compiled_truth.py:150-175](src/mind_mem/compiled_truth.py) |\n| `recompile_truth` | 从非废弃证据重新生成摘要 | [compiled_truth.py:180-200](src/mind_mem/compiled_truth.py) |\n\n## 5. MCP 资源声明\n\n通过 `@mcp.resource` 暴露只读视图，提供工作区信息的统一访问：\n\n| 资源 URI | 内容描述 |\n|---------|----------|\n| `mind-mem://decisions` | 活动决策（DECISIONS.md） |\n| `mind-mem://tasks` | 所有任务（TASKS.md） |\n| `mind-mem://entities/{type}` | 项目/人员/工具/事件实体 |\n| `mind-mem://signals` | 自动捕获信号 |\n| `mind-mem://contradictions` | 检测到的矛盾 |\n| `mind-mem://health` | 工作区健康摘要 |\n| `mind-mem://recall/{query}` | BM25 召回搜索 |\n| `mind-mem://ledger` | 共享多智能体事实账本 |\n\n资料来源：[resources.py:1-50](src/mind_mem/mcp/resources.py)\n\n## 6. 模型溯源系统\n\n`model_provenance.py` 定义了发布商注册表和来源发现机制：\n\n| 发布商 | Slugs | 描述 |\n|-------|-------|------|\n| Mistral | `mistralai` | Mistral / Mixtral / Codestral 家族 |\n| Google Gemma | `google` | Gemma / Gemma-2 / PaLM 家族 |\n| IBM Granite | `ibm-granite`, `ibm` | Granite-3 / Granite-Code 家族 |\n| OpenAI | `openai` | Whisper / CLIP 及开源模型 |\n| Anthropic | `anthropic` | Anthropic 发布产物 |\n| DeepSeek | `deepseek-ai` | DeepSeek-V2 / V3 / R1 家族 |\n| Microsoft Phi | `microsoft` | Phi-2 / Phi-3 / Phi-4 家族 |\n| TII Falcon | `tiiuae` | Falcon-7B / 40B / 180B 家族 |\n\n资料来源：[model_provenance.py:1-80](src/mind_mem/model_provenance.py)\n\n## 7. v4.0 功能预览\n\nv4.0 采用显式功能开关设计，默认关闭以保持 v3.x 行为兼容。\n\n```mermaid\ngraph TD\n subgraph \"v4.0 功能门\"\n CONFIG[mind-mem.json
v4 feature flag]\n end\n \n subgraph \"A. 认知/模型层\"\n TIER[tier-aware block schema]\n COG_KRN[Cognitive Mind Kernel API]\n SURPRISE[surprise-weighted retrieval]\n end\n \n subgraph \"B. 知识图谱\"\n KINDS[entity/concept kinds]\n LONG_CTX[long-context recall]\n FUSION[LLM-driven fusion]\n STREAM[streaming recall]\n CHAT[conversational chat]\n PROMPT_SCHEMA[prompt schema]\n end\n \n subgraph \"C. 治理/UX\"\n IDLE[idle-only ingest]\n LINT[AI lint + auto-fix]\n CONTRAD[contradiction state machine]\n SELF_HEAL[self-healing index]\n end\n \n CONFIG --> TIER\n CONFIG --> KINDS\n CONFIG --> IDLE\n```\n\n资料来源：[v4/__init__.py:1-40](src/mind_mem/v4/__init__.py)\n\n## 8. 智能体集成\n\nmind-mem 支持多种 AI 编码客户端集成，通过 `hook_installer.py` 管理：\n\n| 智能体 | 配置格式 | 说明 |\n|-------|---------|------|\n| Claude | JSON | Anthropic Claude 家族 |\n| Claude Code | JSON block | 支持 MCP 配置 |\n| Codex CLI | JSON block | OpenAI Codex |\n| Cursor | JSON block | Cursor IDE |\n| Windsurf | mcp-json-windsurf | Codeium Windsurf |\n| aider | YAML block | aider CLI (paul-gauthier) |\n| OpenClaw | JSON hooks | 开源 AI 助手 |\n| NanoClaw | JSON hooks | 紧凑型 Claw 变体 |\n| NemoClaw | JSON hooks | 记忆聚焦型 Claw |\n\nMCP 服务器路径解析优先级：\n1. `MIND_MEM_MCP_SERVER` 环境变量\n2. `/../mcp_server.py`（源码检出布局）\n3. `/mcp_server.py`（打包安装布局）\n\n资料来源：[hook_installer.py:1-50](src/mind_mem/hook_installer.py)\n\n## 9. 观察压缩\n\n`observation_compress.py` 实现记忆压缩专家系统，支持多种查询类型：\n\n| 类型 | 用途 |\n|-----|------|\n| `direct` | 直接事实查询 |\n| `comparative` | 对比分析 |\n| `denial` | 否定证据识别 |\n| `temporal` | 时序/因果关系 |\n| `multi-hop` | 多跳推理连接 |\n\n资料来源：[observation_compress.py:1-60](src/mind_mem/observation_compress.py)\n\n## 10. 总结\n\nmind-mem 的核心功能可归纳为以下维度：\n\n| 维度 | 核心能力 |\n|-----|---------|\n| **召回** | BM25/混合检索、FTS5 全文索引、长上下文模式 |\n| **治理** | 提案-审批-回滚流程、矛盾检测、快照恢复 |\n| **整合** | 认知遗忘周期、陈旧度扩散、自主丰富 |\n| **操作** | 索引管理、原子删除、JSONL 导出、健康监控 |\n| **事实** | 编译事实页、证据聚合、版本化管理 |\n| **可观测性** | 结构化日志、MCP 调用追踪、trace 工具 |\n\n所有核心功能均通过 MCP 工具接口或 CLI 提供，确保与主流 AI 编码客户端的广泛兼容性。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[MIND-Mem简介](#page-introduction), [数据流与处理管道](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-gag/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)\n- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [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)\n- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)\n- [src/mind_mem/protection.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/protection.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n \n\n# 系统架构\n\nmind-mem 是一个面向多智能体协作的持久化记忆系统，旨在为 AI 编码助手提供持久化上下文记忆能力。该系统通过 Model Context Protocol (MCP) 向各类 AI 客户端暴露统一的记忆接口，支持记忆检索、上下文注入、治理决策追踪和完整性审计等核心功能。\n\n## 1. 整体架构概览\n\nmind-mem 采用分层架构设计，核心由 MCP 服务层、记忆操作层、数据持久化层和治理审计层组成。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n CLAUDE[\"Claude Code\"]\n COPILOT[\"GitHub Copilot\"]\n CODY[\"Sourcegraph Cody\"]\n QODO[\"Qodo Gen\"]\n end\n \n subgraph 接口层\n MCP[\"MCP Server
(mcp_server.py)\"]\n CLI[\"CLI 工具
(mm)\"]\n WEB[\"Web 控制台
(Next.js)\"]\n end\n \n subgraph 服务层\n RECALL[\"Recall API\"]\n GOVERNANCE[\"Governance Tools\"]\n AUDIT[\"Audit Tools\"]\n CONSOLIDATION[\"Consolidation Tools\"]\n KERNELS[\"Mind Kernel Tools\"]\n end\n \n subgraph 数据层\n FTS[\"FTS5 全文索引\"]\n HASH[\"Hash Chain v2\"]\n EVIDENCE[\"Evidence Chain\"]\n TRUTH[\"Compiled Truth\"]\n end\n \n subgraph 持久化层\n MARKDOWN[\"Markdown 记忆文件\"]\n SQLITE[\"SQLite 数据库\"]\n CORPUS[\"语料库目录\"]\n end\n \n CLIENTS[AI 客户端] --> MCP\n CLIENTS --> CLI\n MCP --> RECALL\n MCP --> GOVERNANCE\n MCP --> AUDIT\n CLI --> RECALL\n RECALL --> FTS\n FTS --> MARKDOWN\n GOVERNANCE --> HASH\n GOVERNANCE --> EVIDENCE\n AUDIT --> TRUTH\n```\n\n## 2. MCP 服务架构\n\nMCP (Model Context Protocol) 是 mind-mem 的核心对外接口协议。系统将 MCP 服务分解为多个工具域，每个域对应特定的功能模块。\n\n### 2.1 工具域划分\n\n| 工具域 | 文件路径 | 核心工具 |\n|--------|----------|----------|\n| governance | `mcp/tools/governance.py` | propose_update, approve_apply, rollback_proposal, scan |\n| audit | `mcp/tools/audit.py` | verify_merkle, verify_chain, list_evidence, mind_mem_verify |\n| kernels | `mcp/tools/kernels.py` | list_mind_kernels, get_mind_kernel, compiled_truth_* |\n| memory_ops | `mcp/tools/memory_ops.py` | index_stats, reindex, delete_memory_item, export_memory |\n| consolidation | `mcp/tools/consolidation.py` | plan_consolidation, propagate_staleness, dream_cycle |\n| benchmark | `mcp/tools/benchmark.py` | governance_health_bench, category_summary |\n| arch_mind | `mcp/tools/arch_mind.py` | arch_baseline, arch_delta, arch_session_* |\n\n### 2.2 MCP 资源声明\n\nMCP 服务还暴露一组只读资源，提供对工作区记忆的查询视图：\n\n```mermaid\ngraph LR\n R1[\"mind-mem://decisions
决策记录\"]\n R2[\"mind-mem://tasks
任务列表\"]\n R3[\"mind-mem://entities/{type}
实体查询\"]\n R4[\"mind-mem://signals
信号数据\"]\n R5[\"mind-mem://contradictions
矛盾检测\"]\n R6[\"mind-mem://health
健康状态\"]\n R7[\"mind-mem://recall/{query}
BM25 检索\"]\n R8[\"mind-mem://ledger
多智能体账本\"]\n```\n\n资料来源：[src/mind_mem/mcp/resources.py:1-30]()\n\n### 2.3 MCP 服务启动流程\n\n```python\n# 资料来源：src/mind_mem/hook_installer.py\ndef mcp_server_spec(workspace: str) -> dict[str, Any]:\n \"\"\"生成 MCP 服务调用规范\"\"\"\n return {\n \"command\": _sys.executable or \"python3\",\n \"args\": [_mcp_server_path()],\n \"env\": {\"MIND_MEM_WORKSPACE\": workspace},\n }\n```\n\nMCP 服务器路径按以下优先级解析：\n\n1. `MIND_MEM_MCP_SERVER` 环境变量（显式覆盖）\n2. `/../mcp_server.py`（源码 checkout 布局）\n3. `/mcp_server.py`（打包安装布局）\n\n资料来源：[src/mind_mem/hook_installer.py]()\n\n## 3. CLI 工具架构\n\n`mm` 是面向非 MCP 智能体的统一 CLI 工具，提供命令行记忆操作能力。\n\n### 3.1 CLI 子命令\n\n| 子命令 | 功能描述 |\n|--------|----------|\n| `mm recall \"\"` | BM25 记忆检索 |\n| `mm context \"\"` | 生成符 合 token 预算的上下文片段 |\n| `mm inject --agent \"\"` | 为指定智能体渲染记忆片段 |\n| `mm vault scan ` | 列出解析的 vault 块（JSON 格式）|\n| `mm vault write ` | 写入 vault 记忆块 |\n| `mm status` | 工作区状态摘要 |\n\n资料来源：[src/mind_mem/mm_cli.py:1-25]()\n\n### 3.2 工作区解析\n\n```python\ndef _workspace() -> str:\n ws = os.environ.get(\"MIND_MEM_WORKSPACE\", \"\").strip()\n if not ws:\n ws = os.getcwd()\n return os.path.realpath(ws)\n```\n\n工作区路径通过 `MIND_MEM_WORKSPACE` 环境变量或当前工作目录确定。\n\n## 4. 记忆检索系统\n\n### 4.1 Recall API\n\nRecall 是核心检索引擎，支持 BM25 全文搜索和上下文感知记忆提取。\n\n```mermaid\ngraph TD\n Q[\"查询输入\"] --> PARSE[\"查询解析\"]\n PARSE --> FTS[\"FTS5 索引查询\"]\n FTS --> RERANK[\"重排序\"]\n RERANK --> PACK[\"预算打包
(pack_to_budget)\"]\n PACK --> RESULT[\"记忆片段\"]\n \n subgraph 记忆来源\n MEMORY[\"memory/ 目录\"]\n TASKS[\"TASKS.md\"]\n DECISIONS[\"DECISIONS.md\"]\n end\n \n FTS --> MEMORY\n FTS --> TASKS\n FTS --> DECISIONS\n```\n\n### 4.2 记忆类型映射\n\n记忆文件使用特定前缀标识类型：\n\n| 前缀 | 类型 | 说明 |\n|------|------|------|\n| `[[` | Obsidian 风格链接 | 跨块引用 |\n| `TASK` | 任务块 | 任务追踪 |\n| `DECISION` | 决策块 | 架构决策记录 |\n| `SIGNAL` | 信号块 | 待审批提案 |\n\n## 5. 治理与决策系统\n\n### 5.1 治理原则\n\nmind-mem 遵循\"记忆仅通过治理修改\"的不变性原则。所有记忆变更必须经过提议、审批、生效的完整治理流程。\n\n```mermaid\nstateDiagram-v2\n [*] --> SIGNAL: propose_update\n SIGNAL --> REVIEW: 提交提案\n REVIEW --> APPROVED: approve_apply\n REVIEW --> REJECTED: 拒绝/超时\n APPROVED --> ACTIVE: 写入记忆\n ACTIVE --> SUPERSEDED: rollback_proposal\n SUPERSEDED --> [*]\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-30]()\n\n### 5.2 治理工具集\n\n| 工具 | 功能 |\n|------|------|\n| `propose_update` | 提议新决策或任务，写入 SIGNALS.md |\n| `approve_apply` | 应用已审批提案（默认 dry-run）|\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理）|\n| `list_contradictions` | 矛盾列表查询 |\n\n## 6. 编译真相系统 (Compiled Truth)\n\n### 6.1 系统设计\n\n编译真相系统通过聚合证据来维护实体的规范理解，支持基于句子级出现频率的事实提取。\n\n```python\n# 资料来源：src/mind_mem/compiled_truth.py\ndef extract_common_facts(workspace: str, min_mentions: int = 3) -> list[dict]:\n \"\"\"从 memory/ 目录提取高频事实\"\"\"\n # 1. 遍历所有 .md 文件\n # 2. 句子级分词\n # 3. 统计归一化后的句子出现次数\n # 4. 返回出现 >= min_mentions 次的事实\n```\n\n### 6.2 真相页结构\n\n每个真相页维护以下数据结构：\n\n| 字段 | 说明 |\n|------|------|\n| `entity_id` | 实体唯一标识 |\n| `evidence_entries` | 证据条目列表 |\n| `compiled_summary` | 编译后的摘要 |\n| `version` | 版本号 |\n| `last_compiled` | 最后编译时间 |\n\n### 6.3 证据管理\n\n```mermaid\ngraph LR\n E1[\"新证据\"] --> VALIDATE[\"验证\"]\n VALIDATE --> ADD[\"添加证据\"]\n ADD --> COMPILE[\"重新编译\"]\n COMPILE --> SUMMARY[\"生成摘要\"]\n \n E2[\"旧证据\"] --> SUPERSEDE[\"标记 superseded\"]\n SUPERSEDE --> COMPILE\n```\n\n## 7. 完整性审计系统\n\n### 7.1 审计层设计\n\n审计系统通过哈希链和默克尔树保证记忆的不可篡改性。\n\n| 组件 | 用途 |\n|------|------|\n| Hash Chain v2 | SHA3-512 追加式账本 |\n| Evidence Chain | 结构化治理证据 |\n| Merkle Tree | 块级包含证明 |\n| Integrity Manifest | 发布完整性清单 |\n\n### 7.2 验证工具\n\n| 工具 | 功能 |\n|------|------|\n| `verify_merkle` | 验证块的默克尔包含证明 |\n| `verify_chain` | 验证哈希链和证据链完整性 |\n| `list_evidence` | 枚举治理证据对象 |\n| `mind_mem_verify` | 独立验证 CLI |\n\n### 7.3 验证退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| 0 | 所有检查通过 |\n| 1 | 通用失败（路径缺失）|\n| 2 | 哈希链完整性违规 |\n| 3 | 规范哈希绑定漂移 |\n| 4 | 证据链完整性违规 |\n| 5 | 默克尔根不匹配 |\n| 6 | 链头/快照锚点不匹配 |\n\n资料来源：[src/mind_mem/verify_cli.py:1-45]()\n\n## 8. 智能体集成系统\n\n### 8.1 支持的智能体\n\n| 智能体 | 配置格式 | 配置路径 | 说明 |\n|--------|----------|----------|------|\n| claude | JSON | `~/.claude/settings.json` | Anthropic Claude Code |\n| copilot | Text Block | `.github/copilot-instructions.md` | GitHub Copilot |\n| cody | JSON | `.cody/config.json` | Sourcegraph Cody |\n| qodo | Text Block | `.codium/ai-rules.md` | Qodo Gen |\n\n资料来源：[src/mind_mem/hook_installer.py]()\n\n### 8.2 集成机制\n\n```mermaid\ngraph TD\n INSTALL[\"hook_installer\"] --> DETECT[\"检测智能体\"]\n DETECT --> SPEC[\"生成 AgentSpec\"]\n SPEC --> WRITE[\"写入配置文件\"]\n WRITE --> PREPEND[\"注入记忆锚点\"]\n \n PREPEND --> QUERY[\"mm inject --agent \"]\n QUERY --> CONTEXT[\"返回记忆上下文\"]\n```\n\n### 8.3 智能体规范定义\n\n```python\n@dataclass(frozen=True)\nclass AgentSpec:\n name: str # 智能体键名\n description: str # 人类可读描述\n config_fmt: str # 配置格式 (json-claude/path-toml/text-block)\n path_tmpl: str # 配置文件路径模板\n content_tmpl: str # 注入内容模板\n always_offer: bool # 是否自动推荐\n detect_paths: tuple # 检测路径\n detect_binaries: tuple # 检测二进制\n```\n\n## 9. 记忆操作工具\n\n### 9.1 索引操作\n\n| 工具 | 功能 |\n|------|------|\n| `index_stats` | 查询 FTS5 索引状态 |\n| `reindex` | 重建全文索引 |\n\n### 9.2 生命周期管理\n\n| 工具 | 功能 |\n|------|------|\n| `delete_memory_item` | 原子性记忆块删除（带追加式恢复日志）|\n| `get_block` | 块内容查询 |\n| `memory_health` | 健康状态仪表盘 |\n| `compact` | 存储压缩 |\n| `stale_blocks` | 陈旧块标记管理 |\n\n### 9.3 导出功能\n\n```python\ndef export_memory(\n max_items: int = 10000,\n include_metadata: bool = True,\n max_size_mb: int = 50\n) -> str:\n \"\"\"导出所有记忆块为 JSONL 格式\"\"\"\n```\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-40]()\n\n## 10. 记忆整合系统\n\n### 10.1 认知遗忘周期\n\n```mermaid\ngraph TD\n START[\"开始整合\"] --> CONFIG[\"ConsolidationConfig\"]\n CONFIG --> SCORE[\"BlockCognition 评分\"]\n SCORE --> THRESHOLD{\"重要度阈值?\"}\n THRESHOLD -->|高| KEEP[\"保留\"]\n THRESHOLD -->|低| STALE[\"标记陈旧\"]\n STALE --> AGE{\"超过归档天数?\"}\n AGE -->|是| ARCHIVE[\"归档\"]\n AGE -->|否| GRACE[\"宽限期\"]\n KEEP --> COMPLETE[\"完成\"]\n ARCHIVE --> COMPLETE\n GRACE --> COMPLETE\n```\n\n### 10.2 整合工具\n\n| 工具 | 功能 |\n|------|------|\n| `plan_consolidation` | 认知遗忘周期预演 |\n| `propagate_staleness` | 陈旧度跨引用扩散 |\n| `project_profile` | 会话启动情报摘要 |\n| `dream_cycle` | 自主记忆丰富化 |\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-30]()\n\n## 11. v4.0 架构演进\n\nv4.0 作为架构演进版本，默认关闭，通过 feature flag 启用。\n\n### 11.1 功能组映射\n\n| 组别 | 功能 | 模块 |\n|------|------|------|\n| A | 认知层/模型层 | tier_memory, cognitive_kernel, surprise_retrieval |\n| B | 知识图谱 | block_kinds, long_context_recall, fusion, streaming_recall, chat, prompt_schema |\n| C | 知识图谱治理 | idle_ingest, lint, contradiction_states, self_heal |\n| D | 基准测试 | arch_baseline, arch_delta |\n| E | 高级记忆 | block_cognition, consolidation |\n| F | 多租户 | tenant_audit, tenant_kms |\n\n资料来源：[src/mind_mem/v4/__init__.py:1-50]()\n\n### 11.2 特征门控\n\n```python\nclass FeatureDisabledError(Exception):\n \"\"\"v4 功能未启用时抛出\"\"\"\n pass\n```\n\n所有 v4.0 功能均需在 `mind-mem.json` 配置文件的 `v4` 键下显式启用。\n\n## 12. 完整性保护机制\n\n### 12.1 关键模块保护\n\n系统维护一份关键模块清单，用于完整性验证：\n\n| 关键模块 | 说明 |\n|----------|------|\n| recall.py | 检索核心 |\n| recall_vector.py | 向量检索 |\n| apply_engine.py | 治理应用引擎 |\n| audit_chain.py | 审计链 |\n| encryption.py | 加密模块 |\n| graph_recall.py | 图检索 |\n| consensus_vote.py | 共识投票 |\n| tenant_audit.py | 租户审计 |\n\n资料来源：[src/mind_mem/protection.py:30-50]()\n\n### 12.2 完整性报告\n\n```python\n@dataclass(frozen=True)\nclass IntegrityReport:\n ok: bool\n module: str\n expected_hash: str\n actual_hash: str\n```\n\n## 13. Web 控制台架构\n\nmind-mem 提供基于 Next.js 的 Web 控制台，提供可视化记忆查询界面。\n\n```mermaid\ngraph LR\n API[\"REST API
/v1/recall
/v1/health\"] --> PAGE[\"app/page.tsx\"]\n PAGE --> GRAPH[\"GraphView
(d3-force)\"]\n PAGE --> TIMELINE[\"TimelineView\"]\n PAGE --> FACTS[\"FactList\"]\n \n GRAPH --> NODES[\"节点: 按状态着色\"]\n GRAPH --> EDGES[\"边: 按谓词着色\"]\n```\n\n组件说明：\n\n| 组件 | 功能 |\n|------|------|\n| GraphView.tsx | 力导向图可视化 |\n| TimelineView.tsx | 时间线视图 |\n| FactList.tsx | 提取的事实列表 |\n| lib/api.ts | 类型化 API 客户端 |\n\n资料来源：[web/README.md]()\n\n## 14. 依赖关系总览\n\n```mermaid\ngraph BT\n subgraph 核心依赖\n BLOCK[\"block_parser\"]\n FTS[\"sqlite_index
(FTS5)\"]\n COGNITIVE[\"cognitive_forget\"]\n end\n \n subgraph MCP 工具\n GOVERNANCE[\"governance.py\"]\n AUDIT[\"audit.py\"]\n MEMORY_OPS[\"memory_ops.py\"]\n CONSOLIDATION[\"consolidation.py\"]\n end\n \n subgraph 基础设施\n OBSERVE[\"observability\"]\n CONFIG[\"config\"]\n WORKSPACE[\"workspace\"]\n end\n \n MCP[\"mcp_server.py\"] --> GOVERNANCE\n MCP --> AUDIT\n MCP --> MEMORY_OPS\n MCP --> CONSOLIDATION\n \n GOVERNANCE --> BLOCK\n GOVERNANCE --> FTS\n AUDIT --> BLOCK\n MEMORY_OPS --> FTS\n CONSOLIDATION --> COGNITIVE\n \n BLOCK --> FTS\n COGNITIVE --> FTS\n```\n\n## 15. 总结\n\nmind-mem 的系统架构围绕以下核心设计原则构建：\n\n1. **协议分离**：通过 MCP 协议将核心功能暴露给 AI 客户端，CLI 作为补充\n2. **治理优先**：所有记忆修改必须经过治理流程，保证可追溯性\n3. **完整性保证**：多层审计机制（哈希链、默克尔树、证据链）确保记忆不可篡改\n4. **智能体无关**：通过可扩展的 hook 系统支持多种 AI 编码助手\n5. **演进能力**：v4.0 架构通过 feature flag 逐步引入新功能，不影响现有系统\n\n---\n\n\n\n## 数据流与处理管道\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [存储后端](#page-storage), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/capture.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/capture.py)\n- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/ingestion_pipeline.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/ingestion_pipeline.py)\n- [src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n \n\n# 数据流与处理管道\n\n## 概述\n\n数据流与处理管道是 mind-mem 系统的核心组成部分，负责管理从数据捕获、存储、处理到检索的完整生命周期。该管道遵循\"内存永不直接修改，只能通过治理机制变更\"的核心不变量，确保所有数据变更都经过审批和追踪流程。\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph 数据捕获层\n CAPT[数据捕获]\n SIG[信号生成]\n end\n\n subgraph 存储抽象层\n BS[BlockStore 抽象]\n MB[MarkdownBlockStore]\n PG[PostgresBlockStore]\n ES[EncryptedBlockStore]\n end\n\n subgraph 处理引擎层\n APPLY[ApplyEngine]\n SNAP[快照管理]\n DIFF[差异计算]\n end\n\n subgraph 治理层\n PROP[提案机制]\n APPROVE[审批应用]\n ROLLBACK[回滚机制]\n end\n\n subgraph 检索层\n RECALL[Recall 检索]\n BM25[BM25 检索]\n VECTOR[向量检索]\n HYBRID[混合检索]\n end\n\n CAPT --> BS\n SIG --> BS\n BS --> APPLY\n APPLY --> SNAP\n APPLY --> DIFF\n PROP --> APPROVE\n APPROVE --> ROLLBACK\n RECALL --> BM25\n RECALL --> VECTOR\n RECALL --> HYBRID\n```\n\n## 核心组件\n\n### BlockStore 抽象层\n\nBlockStore 是数据持久化的核心抽象，支持多种后端实现：\n\n| 组件 | 类名 | 用途 | 配置键 |\n|------|------|------|--------|\n| 默认后端 | `MarkdownBlockStore` | Markdown 文件存储 | `block_store.backend: markdown` |\n| Postgres 后端 | `PostgresBlockStore` | 关系型数据库存储 | `block_store.backend: postgres` |\n| 加密包装器 | `EncryptedBlockStore` | 加密数据存储 | `mind-mem.json` passphrase 设置 |\n\n资料来源：[src/mind_mem/apply_engine.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n### ApplyEngine 处理引擎\n\nApplyEngine 负责数据变更的实际执行，提供快照、回滚和差异对比功能：\n\n```python\ndef _store_for(ws) -> BlockStore:\n \"\"\"根据配置获取对应的 BlockStore 实现\"\"\"\n \ndef create_snapshot(ws, ts, files_touched=None) -> str:\n \"\"\"创建应用前快照，返回快照目录路径\"\"\"\n\ndef restore_snapshot(ws, snap_dir) -> None:\n \"\"\"从快照目录恢复工作空间\"\"\"\n\ndef snapshot_diff(ws, snap_dir) -> list[str]:\n \"\"\"返回当前工作空间与快照的差异文件列表\"\"\"\n```\n\n资料来源：[src/mind_mem/apply_engine.py:30-55](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## 数据流阶段\n\n### 阶段一：数据捕获\n\n数据捕获层负责收集外部信号和用户输入，生成标准化的 Block 结构：\n\n```mermaid\ngraph LR\n A[外部输入] --> B[Capture 模块]\n B --> C[Block 结构化]\n C --> D[信号写入]\n D --> E[SIGNALS.md]\n```\n\n关键流程：\n1. 接收外部数据源（CLI、API、MCP 工具）\n2. 解析为标准 Block 格式\n3. 写入 SIGNALS.md 待审批队列\n\n### 阶段二：存储抽象\n\n存储层根据配置选择合适的持久化后端：\n\n```mermaid\ngraph TD\n A[写入请求] --> B{配置检查}\n B -->|passphrase 设置| C[EncryptedBlockStore]\n B -->|postgres 配置| D[PostgresBlockStore]\n B -->|默认| E[MarkdownBlockStore]\n C --> F[加密后写入]\n D --> G[SQL 写入]\n E --> H[Markdown 文件写入]\n```\n\n资料来源：[src/mind_mem/block_store.py:1-80](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n### 阶段三：检索与召回\n\nRecall 模块提供多种检索策略：\n\n| 检索模式 | 参数 | 说明 |\n|----------|------|------|\n| BM25 | `strategy: bm25` | 基于词频的稀疏检索 |\n| 向量检索 | `strategy: vector` | 密集向量相似度检索 |\n| 混合模式 | `strategy: hybrid` | BM25 + 向量加权融合 |\n| 自动模式 | `strategy: auto` | 根据查询特征自动选择 |\n\n资料来源：[src/mind_mem/recall.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n\n## 治理与变更流程\n\n### 提案-审批模式\n\n所有数据变更必须通过治理机制：\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant P as 提案模块\n participant A as ApplyEngine\n participant S as 快照\n participant R as 检索系统\n\n U->>P: propose_update(block_type, statement)\n P->>P: 生成 SIGNAL\n P->>S: create_snapshot(ws, timestamp)\n Note over S: 创建预应用快照\n U->>A: approve_apply(signal_id)\n A->>S: snapshot_diff()\n A->>R: 更新索引\n Note over A: 应用变更\n```\n\n### 回滚机制\n\n当变更需要撤销时，系统通过快照恢复：\n\n```python\n# 回滚流程\nsnap_dir = create_snapshot(ws, ts) # 变更前创建快照\n# ... 执行变更 ...\nrestore_snapshot(ws, snap_dir) # 需要回滚时恢复\n```\n\n资料来源：[src/mind_mem/apply_engine.py:40-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## 编译真相机制\n\nCompiled Truth 模块负责证据聚合和事实编译：\n\n```mermaid\ngraph TD\n A[原始证据] --> B[EvidenceEntry 解析]\n B --> C[证据池累积]\n C --> D[检测矛盾]\n D -->|无矛盾| E[recompile_truth]\n D -->|存在矛盾| F[矛盾标记]\n E --> G[CompiledTruthPage]\n```\n\n关键函数：\n- `add_evidence()`: 向真相页添加新证据\n- `recompile_truth()`: 重新编译真相摘要\n- `detect_contradictions()`: 检测证据矛盾\n\n资料来源：[src/mind_mem/compiled_truth.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## MCP 工具集成\n\nMCP 工具层提供外部系统交互接口：\n\n| 工具类别 | 工具名称 | 功能 |\n|----------|----------|------|\n| 内核管理 | `list_mind_kernels` | 列出可用内核配置 |\n| 内核管理 | `get_mind_kernel` | 获取指定内核详情 |\n| 真相管理 | `compiled_truth_add_evidence` | 添加证据到真相页 |\n| 真相管理 | `compiled_truth_contradictions` | 检测真相矛盾 |\n| 治理工具 | `propose_update` | 提交变更提案 |\n| 治理工具 | `approve_apply` | 审批并应用变更 |\n| 治理工具 | `rollback_proposal` | 回滚提案 |\n\n资料来源：[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)\n\n## 配置参数\n\n### BlockStore 配置\n\n在 `mind-mem.json` 中的配置结构：\n\n```json\n{\n \"block_store\": {\n \"backend\": \"markdown|postgres|encrypted\",\n \"passphrase\": \"<加密密钥>\",\n \"connection\": \"\"\n }\n}\n```\n\n### 检索配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `strategy` | string | `auto` | 检索策略选择 |\n| `limit` | int | 20 | 结果数量限制 |\n| `active_only` | bool | false | 仅返回活跃块 |\n\n## 错误处理与容错\n\n系统采用分层错误处理策略：\n\n1. **BlockStore 层**：异常时回退到 MarkdownBlockStore 默认实现\n2. **ApplyEngine 层**：快照操作失败时记录日志但不阻断主流程\n3. **Recall 层**：单一检索失败时尝试降级到其他策略\n\n```python\ntry:\n return get_block_store(ws)\nexcept Exception:\n return MarkdownBlockStore(ws) # 降级保底\n```\n\n资料来源：[src/mind_mem/apply_engine.py:40-45](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## 性能考量\n\n- **快照开销**：create_snapshot 在变更频繁场景下可能产生 IO 压力\n- **检索延迟**：混合检索模式需要并行执行 BM25 和向量检索\n- **存储选择**：Postgres 后端适合高并发写入场景，Markdown 适合简单部署\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[数据流与处理管道](#page-data-flow), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n- [src/mind_mem/storage/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/storage/__init__.py)\n- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n \n\n# 存储后端\n\nmind-mem 采用插件化的存储后端架构，支持多种持久化方案以适应不同的部署场景。所有存储操作通过统一的 BlockStore 接口抽象，确保上层逻辑与具体存储技术解耦。\n\n## 架构概述\n\n存储后端系统采用工厂模式（Factory Pattern）进行后端实例化。`get_block_store()` 工厂函数根据工作区配置动态选择合适的存储实现。\n\n```mermaid\ngraph TD\n A[应用层代码] --> B[get_block_store 工厂函数]\n B --> C{mind-mem.json 配置}\n C -->|backend: markdown| D[MarkdownBlockStore]\n C -->|backend: encrypted| E[EncryptedBlockStore 包装器]\n C -->|backend: postgres| F[PostgresBlockStore]\n E --> D\n F --> G[(PostgreSQL 数据库)]\n D --> H[/workspace/memory/\\*.md]\n```\n\n资料来源：[src/mind_mem/storage/__init__.py:53-70]()\n\n## 支持的后端类型\n\n| 后端类型 | 配置值 | 说明 | 依赖 |\n|---------|--------|------|------|\n| Markdown | `markdown` | 默认后端，将块存储为 Markdown 文件 | 无 |\n| 加密存储 | `encrypted` | 在 Markdown 后端基础上添加加密层 | `MIND_MEM_ENCRYPTION_PASSPHRASE` 环境变量 |\n| PostgreSQL | `postgres` | 企业级关系数据库存储 | `psycopg[binary]`、`dsn` 配置 |\n\n资料来源：[src/mind_mem/storage/__init__.py:55-68]()\n\n## 工厂函数 API\n\n### get_block_store(workspace, config=None)\n\n`storage/__init__.py` 中定义的工厂函数，负责根据配置实例化正确的后端。\n\n**函数签名：**\n\n```python\ndef get_block_store(workspace: str, config: dict[str, Any] | None = None) -> BlockStore:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|------|------|\n| `workspace` | str | 是 | mind-mem 工作区根目录路径 |\n| `config` | dict \\| None | 否 | 完整配置字典，为空时自动从 `mind-mem.json` 加载 |\n\n**返回值：**\n\n返回 `BlockStore` 实例（`MarkdownBlockStore`、`EncryptedBlockStore` 或 `PostgresBlockStore`）。\n\n**异常处理：**\n\n| 异常类型 | 触发条件 |\n|---------|----------|\n| `ValueError` | `backend` 值无法识别 |\n| `ValueError` | 使用 `encrypted` 后端但未设置环境变量 |\n| `ValueError` | 使用 `postgres` 后端但配置中缺少 `dsn` |\n| `ImportError` | 使用 `postgres` 后端但未安装 `psycopg` |\n\n资料来源：[src/mind_mem/storage/__init__.py:30-50]()\n\n### 配置读取逻辑\n\n工厂函数首先尝试从工作区目录加载 `mind-mem.json` 配置文件：\n\n```python\ndef _load_workspace_config(workspace: str) -> dict[str, Any]:\n config_path = os.path.join(workspace, \"mind-mem.json\")\n if os.path.isfile(config_path):\n with open(config_path, encoding=\"utf-8\") as f:\n return json.load(f)\n return {}\n```\n\n如果配置文件不存在或解析失败，返回空字典，工厂函数将使用默认值 `markdown`。\n\n资料来源：[src/mind_mem/storage/__init__.py:16-28]()\n\n## 核心接口：BlockStore\n\n`BlockStore` 是所有存储后端的基类，定义了统一的存储操作接口。关键方法包括快照管理，这是实现\"内存永不直接修改\"治理不变量的基础。\n\n### 快照操作\n\n快照机制是 apply_engine 实现回滚功能的核心。当需要修改工作区内容时，系统首先创建快照，然后对快照进行操作，验证通过后才正式应用。\n\n| 方法 | 功能 |\n|-----|------|\n| `snapshot(snap_dir, files_touched)` | 创建预应用快照 |\n| `restore(snap_dir)` | 从快照目录恢复工作区 |\n| `diff(snap_dir)` | 比较当前工作区与快照的差异 |\n\n```mermaid\nsequenceDiagram\n participant AE as ApplyEngine\n participant BS as BlockStore\n participant WS as Workspace\n participant SNAP as Snapshot Dir\n\n AE->>BS: create_snapshot(ws, ts)\n BS->>WS: 读取当前文件\n WS-->>BS: 文件内容\n BS->>SNAP: 写入快照目录\n Note over BS: Markdown: 复制文件树
Postgres: SQL 转储\n BS-->>AE: snap_dir 路径\n```\n\n资料来源：[src/mind_mem/apply_engine.py:26-38]()\n\n## Markdown 后端\n\nMarkdownBlockStore 是默认存储后端，将每个块存储为独立的 Markdown 文件。\n\n### 存储结构\n\n```\nworkspace/\n├── memory/\n│ ├── decisions/\n│ │ └── D-20260213-001.md\n│ ├── tasks/\n│ │ └── T-20260213-001.md\n│ └── signals/\n│ └── S-20260213-001.md\n└── intelligence/\n └── applied/\n └── 20260213-120000/ # 快照目录\n```\n\n### 块格式规范\n\n每个 Markdown 块遵循固定格式，包含标识头和键值对字段：\n\n```markdown\n[ID]\nStatement: 决策内容描述\nDate: 2026-02-13\nStatus: active\nConfidence: high\nTags: architecture, backend\n\n[ID]\n```\n\n`CANONICAL_FIELD_ORDER` 定义了字段的标准顺序，确保块序列化的一致性：\n\n```python\n_CANONICAL_FIELD_ORDER: tuple[str, ...] = (\n \"Statement\", \"Date\", \"Status\", \"Priority\", \"Risk\",\n \"Type\", \"Subject\", \"Object\", \"Tags\", \"Rationale\",\n \"Evidence\", \"Source\", \"Confidence\", \"ContentHash\",\n \"Excerpt\", \"Action\",\n)\n```\n\n资料来源：[src/mind_mem/block_store.py:75-90]()\n\n## PostgreSQL 后端\n\nPostgresBlockStore 为企业级部署提供关系数据库存储能力。适用于需要事务支持、并发访问和高可用性的生产环境。\n\n### 配置示例\n\n```json\n{\n \"block_store\": {\n \"backend\": \"postgres\",\n \"dsn\": \"postgresql://user:password@localhost:5432/mindmem\"\n }\n}\n```\n\n### 与 Markdown 后端的差异\n\n| 特性 | Markdown | PostgreSQL |\n|-----|----------|------------|\n| 快照方式 | 文件复制 | SQL 转储 |\n| 并发支持 | 文件锁 | 数据库事务 |\n| 查询能力 | 全文搜索 | SQL 查询 |\n| 部署复杂度 | 简单 | 需要数据库服务 |\n\n## 加密存储包装器\n\nEncryptedBlockStore 是一个包装器后端，它在底层 Markdown 后端基础上添加加密功能。当设置了 `MIND_MEM_ENCRYPTION_PASSPHRASE` 环境变量时，存储模块会自动返回加密包装后的实例。\n\n资料来源：[src/mind_mem/storage/__init__.py:65-67]()\n\n## 在 Apply Engine 中的应用\n\napply_engine 模块通过 `_store_for(ws)` 函数获取当前配置的 BlockStore 实例，所有存储操作都通过该实例进行路由：\n\n```python\ndef _store_for(ws):\n try:\n from .storage import get_block_store\n return get_block_store(ws)\n except Exception:\n return MarkdownBlockStore(ws) # 容错降级\n```\n\n这种设计确保了 apply_engine 的韧性：在首次运行或配置错误的工作区，系统会优雅降级到默认的 Markdown 后端。\n\n资料来源：[src/mind_mem/apply_engine.py:20-26]()\n\n## 删除日志\n\n当块被删除时，后端会将删除收据写入 `memory/deleted_blocks.jsonl` 文件：\n\n```json\n{\"block_id\": \"D-20260213-001\", \"deleted_at\": \"2026-02-13T12:00:00+00:00\", \"content\": \"...\"}\n```\n\n这一机制与 MCP 工具 `delete_memory_item` 保持一致，两条删除路径最终汇聚到同一恢复日志。\n\n资料来源：[src/mind_mem/block_store.py:45-60]()\n\n## 配置建议\n\n| 场景 | 推荐后端 | 原因 |\n|-----|---------|------|\n| 本地开发 / 个人使用 | Markdown | 简单、无依赖、易于调试 |\n| 小团队协作 | Markdown + Git | 利用版本控制进行协作 |\n| 企业级生产环境 | PostgreSQL | 事务支持、并发控制、备份恢复 |\n| 安全敏感数据 | Encrypted | 静态数据加密保护 |\n\n---\n\n\n\n## 检索管道\n\n### 相关页面\n\n相关主题：[存储后端](#page-storage), [治理与矛盾检测](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)\n- [src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/query_expansion.py)\n- [src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)\n- [src/mind_mem/rerank_ensemble.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/rerank_ensemble.py)\n- [mind/bm25.mind](https://github.com/star-ga/mind-mem/blob/main/mind/bm25.mind)\n- [mind/rrf.mind](https://github.com/star-ga/mind-mem/blob/main/mind/rrf.mind)\n \n\n# 检索管道\n\n## 概述\n\n检索管道（Retrieval Pipeline）是 mind-mem 系统中的核心组件，负责从工作空间内存中定位和召回与用户查询相关的记忆块。该管道采用多阶段架构，结合了稀疏检索（BM25）、密集检索（向量检索）和重排序（Re-ranking）等多种技术，以实现高质量的检索结果。\n\n检索管道的主要职责包括：\n- 解析用户查询并执行多路召回\n- 对多条召回路径的结果进行融合排序\n- 应用质量过滤和后处理逻辑\n- 返回符合置信度和活跃状态要求的结果集\n\n## 架构概览\n\n检索管道采用三层架构设计，各层职责分明：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询扩展层]\n B --> C[多路召回层]\n C --> D[结果融合层]\n D --> E[重排序层]\n E --> F[最终结果]\n \n C --> C1[BM25 稀疏检索]\n C --> C2[向量检索]\n C --> C3[RM3 扩展检索]\n \n D --> D1[RRF 融合]\n D --> D2[加权融合]\n```\n\n## 查询扩展层\n\n### 查询扩展机制\n\n查询扩展（Query Expansion）是检索管道的入口阶段，负责增强原始查询的语义表达能力。通过分析查询意图，系统可以引入相关术语和同义词，从而扩大检索范围。\n\n查询扩展支持多种策略：\n- **RM3 扩展**：基于伪相关反馈的扩展方法，从初始检索结果中提取高权重词项\n- **同义词扩展**：利用预定义的同义词库进行术语扩展\n- **概念扩展**：识别查询中的实体概念并引入相关概念\n\n### 配置参数\n\n查询扩展的行为可以通过 `.mind` 内核配置文件进行调优，主要参数包括：\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `rm3_expansion_terms` | int | 10 | RM3 扩展的词项数量 |\n| `rm3_collection_weight` | float | 0.9 | 文档权重系数 |\n| `expansion_enabled` | bool | true | 是否启用扩展 |\n\n## 多路召回层\n\n多路召回是检索管道的核心阶段，通过并行执行多种检索算法来最大化召回率。\n\n### BM25 稀疏检索\n\nBM25（Best Matching 25）是一种经典的稀疏检索算法，基于词项频率和文档频率的统计模型计算相关性评分。\n\nBM25 的核心公式：\n\n```\nScore(D, Q) = Σ IDF(qi) × (f(qi, D) × (k1 + 1)) / (f(qi, D) + k1 × (1 - b + b × |D|/avgdl))\n```\n\n其中：\n- `f(qi, D)`：词项 qi 在文档 D 中的频率\n- `|D|`：文档长度\n- `avgdl`：平均文档长度\n- `k1`, `b`：可调参数（通常 k1=1.2, b=0.75）\n\nBM25 内核配置文件（`mind/bm25.mind`）允许调整以下参数：\n\n| 参数 | 说明 | 典型值 |\n|------|------|--------|\n| `k1` | 词频饱和参数 | 1.2 |\n| `b` | 文档长度归一化参数 | 0.75 |\n| `avgdl` | 平均文档长度基准 | - |\n\n### 向量检索\n\n向量检索（Vector Recall）使用密集嵌入表示进行语义级别的相似度匹配。系统将记忆块和查询都编码为高维向量，然后通过最近邻搜索找到相关结果。\n\n向量检索的流程：\n\n```mermaid\ngraph LR\n A[记忆块文本] --> B[Embedding 模型]\n B --> C[向量索引]\n C --> D[查询向量]\n D --> E[向量相似度计算]\n E --> F[Top-K 结果]\n```\n\n向量检索的主要配置参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model_name` | str | 嵌入模型名称 |\n| `dimension` | int | 向量维度 |\n| `similarity_metric` | str | 相似度度量（cosine/dot/euclidean） |\n| `top_k` | int | 返回的最近邻数量 |\n\n### RM3 扩展检索\n\nRM3 是一种伪相关反馈方法，通过以下步骤扩展查询：\n\n1. 执行初始检索获取 Top-N 结果\n2. 从结果中提取高权重词项和词组\n3. 将扩展词项加入原始查询\n4. 执行二次检索\n\nRM3 扩展检索的实现位于 `query_expansion.py`，其核心逻辑包括：\n\n- 词项权重计算：基于文档内频率和逆文档频率\n- 词组提取：识别连续的高频词序列\n- 权重融合：将扩展词项与原始查询词项按权重合并\n\n## 结果融合层\n\n多路召回产生多个候选结果集，融合层负责将这些结果合并为一个统一的排序列表。\n\n### 倒数排序融合（RRF）\n\n倒数排序融合（Reciprocal Rank Fusion）是一种简单而有效的多路召回结果融合算法。RRF 不依赖各路召回的绝对分数，而是利用相对排名信息进行融合。\n\nRRF 公式：\n\n```\nRRF_score(d) = Σ 1 / (k + rank(d, Ri))\n```\n\n其中：\n- `d`：目标文档\n- `Ri`：第 i 路召回的排名列表\n- `k`：常量平滑因子（通常 k=60）\n- `rank(d, Ri)`：文档 d 在第 i 路召回中的排名\n\nRRF 内核配置文件（`mind/rrf.mind`）定义融合参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `k` | 60 | RRF 平滑因子 |\n| `enabled` | true | 是否启用 RRF |\n\n### 加权融合\n\n除了 RRF，系统还支持基于分数的加权融合方法：\n\n```\nfusion_score(d) = Σ wi × norm(scorei(d))\n```\n\n其中 `wi` 是各路召回的可配置权重，`norm()` 是归一化函数。\n\n## 重排序层\n\n重排序（Re-ranking）阶段对融合后的候选结果进行精细化排序，以提高最终结果的相关性。\n\n### 重排序策略\n\n重排序器（`rerank_ensemble.py`）支持多种重排序策略：\n\n1. **Cross-Encoder 重排序**：使用更强大的模型对 Top-K 候选进行精确评分\n2. **Learning-to-Rank**：基于特征的训练模型进行排序\n3. **级联重排序**：多轮渐进式重排序\n\n### 排序特征\n\n重排序阶段考虑的特征包括：\n\n| 特征类别 | 具体特征 |\n|----------|----------|\n| 相关性特征 | BM25 分数、向量相似度、语义匹配度 |\n| 质量特征 | 块完整性、置信度评分、来源权重 |\n| 时效性特征 | 创建时间、最后更新时间、活跃状态 |\n| 关联性特征 | 引用次数、依赖关系、实体匹配 |\n\n## 混合检索流程\n\n完整的混合检索流程如下：\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant 管道\n participant BM25\n participant 向量引擎\n participant 融合器\n participant 重排序器\n participant 结果\n \n 用户->>管道: 提交查询\n 管道->>BM25: 发起 BM25 检索\n 管道->>向量引擎: 发起向量检索\n 管道->>BM25: 获取 Top-K 结果\n 管道->>向量引擎: 获取 Top-K 结果\n BM25-->>管道: BM25 结果集\n 向量引擎-->>管道: 向量结果集\n 管道->>融合器: 合并多路结果\n 融合器-->>管道: 融合排序列表\n 管道->>重排序器: 精细化重排序\n 重排序器-->>管道: 最终排序结果\n 管道-->>用户: 返回 Top-N 结果\n```\n\n## 集成接口\n\n### Python API\n\n检索管道通过 `recall` 模块提供核心检索接口：\n\n```python\nfrom mind_mem.recall import recall\n\nresults = recall(\n workspace,\n query,\n limit=10,\n active_only=True,\n format=\"blocks\"\n)\n```\n\n### MCP 工具接口\n\n在 MCP 服务器中，检索管道通过以下工具暴露：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `recall` | 基础检索接口 |\n| `recall_with_persona` | 带角色投影的检索 |\n| `list_mind_kernels` | 列出可用的检索内核配置 |\n| `get_mind_kernel` | 获取特定内核配置详情 |\n\n### CLI 接口\n\n命令行工具 `mm` 提供检索访问：\n\n```bash\nmm recall \"查询内容\" --limit 10 --active-only\nmm context \"查询内容\" --budget 4096\n```\n\n## 配置管理\n\n### 内核配置文件\n\n检索管道的各项参数通过 `.mind` 内核配置文件进行管理：\n\n```\nmind/\n├── bm25.mind # BM25 检索参数\n├── rrf.mind # RRF 融合参数\n└── rerank.mind # 重排序参数\n```\n\n### 运行时配置\n\n检索管道支持运行时配置覆盖：\n\n```python\nrecall(\n workspace,\n query,\n backend=\"auto\", # auto/bm25/hybrid\n format=\"json\", # json/blocks/bundle\n)\n```\n\n## 性能优化\n\n### 索引优化\n\n- **FTS5 索引**：使用 SQLite FTS5 实现高效的全文搜索\n- **向量索引**：采用近似最近邻（ANN）算法加速向量检索\n- **缓存策略**：对高频查询结果进行缓存\n\n### 查询优化\n\n- **早停机制**：当累计分数达到阈值时提前终止\n- **分层检索**：先用轻量级方法过滤，再用重排序精细化\n- **并行执行**：多路召回并行执行以降低延迟\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 检索结果为空 | 索引未建立 | 执行 `reindex` 工具 |\n| 结果不相关 | 查询扩展过度 | 调整 `expansion_enabled` |\n| 延迟过高 | 向量索引未优化 | 检查 ANN 参数配置 |\n| 排名异常 | 内核参数冲突 | 检查 `.mind` 配置文件 |\n\n## 扩展阅读\n\n- [内核配置系统](./内核配置系统.md)\n- [记忆块解析](./记忆块解析.md)\n- [证据捆绑](./证据捆绑.md)\n\n---\n\n\n\n## MCP服务器\n\n### 相关页面\n\n相关主题：[MCP工具集](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/mcp/server.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py)\n- [src/mind_mem/mcp_entry.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_entry.py)\n- [mcp_server.py](https://github.com/star-ga/mind-mem/blob/main/mcp_server.py)\n- [docs/mcp-integration.md](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-integration.md)\n \n\n# MCP服务器\n\n## 概述\n\nMCP服务器（Model Context Protocol Server）是mind-mem项目提供的AI记忆管理服务接口，通过MCP协议为AI智能体（Agent）提供记忆存储、检索和上下文管理能力。该服务器使AI应用能够持久化存储对话上下文和记忆数据，并在后续对话中动态加载相关记忆，实现跨会话的上下文连续性。\n\n## 核心架构\n\n### 架构组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| MCP Server | MCP协议服务端实现，处理客户端请求 | `src/mind_mem/mcp/server.py` |\n| MCP Entry | 服务入口点，负责初始化和启动 | `src/mind_mem/mcp_entry.py` |\n| 记忆存储引擎 | 管理记忆数据的持久化存储 | 内部模块 |\n| 检索引擎 | 支持语义检索和关键词匹配 | 内部模块 |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[MCP Server]\n B --> C[记忆存储引擎]\n C --> D[向量数据库]\n C --> E[键值存储]\n B --> F[检索引擎]\n F --> D\n F --> E\n G[外部应用] -->|REST/gRPC| B\n```\n\n## 服务启动\n\n### 启动方式\n\nMCP服务器支持两种启动方式：\n\n1. **直接启动脚本**：`mcp_server.py` 提供了独立运行的入口点\n2. **模块导入启动**：通过 `src/mind_mem/mcp_entry.py` 导入并初始化\n\n### 启动配置\n\n服务器启动时需要配置以下参数：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| host | 服务监听地址 | 0.0.0.0 |\n| port | 服务监听端口 | 8080 |\n| storage_path | 记忆存储路径 | ./memory_data |\n| vector_dim | 向量维度 | 768 |\n\n## MCP协议接口\n\n### 核心工具\n\nMCP服务器通过MCP协议暴露以下核心工具：\n\n| 工具名称 | 功能 | 输入参数 |\n|----------|------|----------|\n| store_memory | 存储记忆 | user_id, content, metadata |\n| retrieve_memories | 检索记忆 | query, user_id, limit |\n| update_memory | 更新记忆 | memory_id, content |\n| delete_memory | 删除记忆 | memory_id |\n| list_memories | 列出记忆 | user_id, filters |\n\n### 资源管理\n\n服务器提供以下MCP资源：\n\n```mermaid\ngraph LR\n A[Resources] --> B[memory://user/{user_id}]\n A --> C[memory://conversation/{conv_id}]\n A --> D[memory://summary/{user_id}]\n```\n\n## 集成方式\n\n### 客户端集成\n\n项目文档 `docs/mcp-integration.md` 描述了与AI智能体的集成方式：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant MCP as MCP Client\n participant Server as MCP Server\n \n Agent->>MCP: 连接服务器\n MCP->>Server: 握手协商\n Server-->>MCP: 连接确认\n MCP-->>Agent: 就绪状态\n \n Agent->>MCP: 发送记忆存储请求\n MCP->>Server: store_memory()\n Server-->>MCP: 存储成功\n MCP-->>Agent: 确认响应\n \n Agent->>MCP: 发送检索请求\n MCP->>Server: retrieve_memories()\n Server-->>MCP: 相关记忆\n MCP-->>Agent: 返回上下文\n```\n\n### 集成配置示例\n\n```json\n{\n \"mcp_servers\": {\n \"mind-mem\": {\n \"command\": \"python\",\n \"args\": [\"mcp_server.py\", \"--port\", \"8080\"],\n \"env\": {\n \"MEMORY_STORAGE_PATH\": \"./data/memory\"\n }\n }\n }\n}\n```\n\n## 记忆管理机制\n\n### 存储策略\n\n| 策略类型 | 说明 | 适用场景 |\n|----------|------|----------|\n| 即时存储 | 实时保存每次交互 | 重要对话记录 |\n| 批量存储 | 定时批量写入 | 低优先级日志 |\n| 压缩存储 | 自动摘要后存储 | 长对话历史 |\n\n### 检索机制\n\n服务器支持多种检索模式：\n\n1. **语义检索**：基于向量相似度匹配相关记忆\n2. **关键词检索**：精确匹配关键词\n3. **时间范围检索**：按时间筛选记忆\n4. **混合检索**：结合语义和关键词的混合搜索\n\n## 安全特性\n\n| 安全措施 | 说明 |\n|----------|------|\n| 用户隔离 | 不同用户记忆严格隔离 |\n| 访问控制 | 基于用户ID的访问验证 |\n| 数据加密 | 敏感数据加密存储 |\n| 审计日志 | 记录所有操作日志 |\n\n## 使用示例\n\n### 存储记忆\n\n```python\nfrom mind_mem import MCPClient\n\nclient = MCPClient(\"http://localhost:8080\")\nclient.store_memory(\n user_id=\"user123\",\n content=\"用户偏好使用中文交流\",\n metadata={\"source\": \"conversation\", \"timestamp\": \"2024-01-01\"}\n)\n```\n\n### 检索记忆\n\n```python\nmemories = client.retrieve_memories(\n query=\"用户偏好\",\n user_id=\"user123\",\n limit=5\n)\nfor memory in memories:\n print(memory.content)\n```\n\n## 配置选项\n\n### 环境变量配置\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| MEMORY_STORAGE_PATH | 存储路径 | /data/memory |\n| MCP_PORT | 服务端口 | 8080 |\n| MCP_HOST | 服务地址 | localhost |\n| VECTOR_DB_TYPE | 向量数据库类型 | qdrant/chroma |\n| MAX_MEMORY_SIZE | 最大记忆大小 | 10000 |\n\n### 运行时配置\n\n```yaml\nserver:\n host: 0.0.0.0\n port: 8080\n workers: 4\n \nstorage:\n backend: sqlite\n path: ./data/memory.db\n \nvector:\n model: text-embedding-ada-002\n dimension: 1536\n```\n\n## 相关文档\n\n- [MCP集成指南](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-integration.md)\n- [主入口模块](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_entry.py)\n- [服务器实现](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py)\n\n---\n\n\n\n## MCP工具集\n\n### 相关页面\n\n相关主题：[MCP服务器](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)\n- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n- [src/mind_mem/mcp/tools/core.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/core.py)\n- [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)\n- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)\n \n\n# MCP工具集\n\n## 概述\n\nMCP工具集（Model Context Protocol Tools）是mind-mem项目为非MCP智能体提供的统一命令行接口（CLI）以及MCP服务端工具集。该工具集涵盖了记忆管理的完整生命周期，包括记忆召回、上下文打包、记忆操作、治理、归档和基准测试等核心功能。\n\nMCP工具集的设计遵循以下核心原则：\n\n- **记忆不可直接修改原则**：记忆只能通过治理流程进行修改\n- **自愈式遗忘**：记忆通过认知遗忘机制自动衰减和归档\n- **知识核调优**：通过`.mind`内核文件调整召回和排序策略\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-30]()\n\n## 架构总览\n\nMCP工具集采用模块化架构，按功能域划分为多个工具子模块：\n\n```mermaid\ngraph TD\n subgraph MCP服务端\n A[mcp_server.py] --> B[tools/]\n B --> C[memory_ops]\n B --> D[governance]\n B --> E[consolidation]\n B --> F[kernels]\n B --> G[core]\n B --> H[arch_mind]\n B --> I[benchmark]\n B --> J[recall]\n B --> K[graph]\n end\n \n subgraph 基础设施层\n L[infra/observability]\n M[infra/workspace]\n N[infra/config]\n end\n \n C --> L\n D --> L\n E --> L\n G --> M\n H --> M\n I --> M\n```\n\n## 工具域分类\n\n### 记忆操作工具域（memory_ops）\n\n记忆操作工具域提供了记忆的索引重建、生命周期管理和健康检查功能。\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-50]()\n\n#### 核心工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `index_stats` | 获取FTS5全文索引状态 |\n| `reindex` | 重建全文索引 |\n| `delete_memory_item` | 原子性记忆块删除 |\n| `export_memory` | 导出记忆为JSONL格式 |\n| `get_block` | 获取单个记忆块 |\n| `memory_health` | 记忆健康状态仪表板 |\n| `compact` | 记忆压缩 |\n| `stale_blocks` | 陈旧记忆块管理 |\n\n#### 块前缀映射表\n\n工具内部维护了`_BLOCK_PREFIX_MAP`，用于快速定位不同类型记忆块的文件路径：\n\n| 前缀 | 文件路径 |\n|-----|---------|\n| `DEC` | `decisions/DECISIONS.md` |\n| `TSK` | `tasks/TASKS.md` |\n| `SIG` | `signals/SIGNALS.md` |\n| `ENT` | `entities/*.md` |\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:100-150]()\n\n### 治理工具域（governance）\n\n治理工具域是mind-mem的核心模块，遵循\"记忆只能通过治理流程修改\"的不变式。\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-40]()\n\n#### 治理工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `propose_update` | 将新决策/任务暂存为SIGNAL |\n| `approve_apply` | 应用暂存的提案（默认干跑） |\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理） |\n| `list_contradictions` | 矛盾列表枚举 |\n| `memory_evolution` | 获取记忆块的A-MEM元数据 |\n\n#### 治理工作流\n\n```mermaid\ngraph LR\n A[propose_update] --> B{SIGNALS.md}\n B --> C[人工审核]\n C --> D{approve_apply}\n D -->|干跑模式| E[预览变更]\n D -->|执行模式| F[应用变更]\n F --> G[快照记录]\n G --> H[rollback可用]\n```\n\n### 记忆整合工具域（consolidation）\n\n记忆整合工具域实现了\"记忆随时间沉淀\"的能力，通过认知遗忘循环维护记忆健康度。\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-35]()\n\n#### 整合工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `plan_consolidation` | 认知遗忘周期干跑 |\n| `propagate_staleness` | 跨引用扩散陈旧度评分 |\n| `project_profile` | 会话启动智能摘要 |\n| `dream_cycle` | 自主记忆富化（实体发现、损坏引用扫描、整合候选） |\n\n#### 整合配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|-----|-------|------|\n| `importance_threshold` | float | 0.25 | 重要性阈值 |\n| `stale_days` | int | 14 | 陈旧天数 |\n| `archive_after_days` | int | 60 | 归档天数 |\n| `grace_days` | int | 30 | 宽限期 |\n\n### 知识核工具域（kernels）\n\n知识核工具域提供了对`.mind`内核配置文件的只读访问，用于调整召回、排序和RM3扩展策略。\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:1-40]()\n\n#### 内核工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_mind_kernels` | 列出可用内核配置文件 |\n| `get_mind_kernel` | 获取指定内核配置详情 |\n| `compiled_truth_load` | 加载实体真值页面 |\n| `compiled_truth_add_evidence` | 添加证据到真值页面 |\n| `compiled_truth_contradictions` | 检测真值页面的矛盾 |\n\n### 上下文核心工具域（core）\n\n上下文核心工具域封装了CoreRegistry单例，管理`.mmcore`便携式块的打包和知识图归档。\n\n资料来源：[src/mind_mem/mcp/tools/core.py:1-45]()\n\n#### 核心工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `build_core` | 从活跃工作区构建.mmcore包 |\n| `load_core` | 加载.mmcore包到内存 |\n| `unload_core` | 卸载已加载的核心 |\n| `list_cores` | 列出已注册的核心 |\n\n#### mmcore包结构\n\n```mermaid\ngraph TD\n A[.mmcore归档] --> B[manifest.json]\n A --> C[blocks/]\n A --> D[edges/]\n A --> E[retrieval_policies.json]\n A --> F[ontology.json]\n \n C --> C1[block_001.json]\n C --> C2[block_002.json]\n D --> D1[edge_001.json]\n D --> D2[edge_002.json]\n```\n\n### Arch-Mind工具域（arch_mind）\n\nArch-Mind工具域将`arch-mind`二进制程序封装为7个MCP工具，提供架构基线管理和会话级指标追踪。\n\n资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-50]()\n\n#### Arch工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `arch_baseline` | 初始化架构基线 |\n| `arch_delta` | 计算当前扫描与基线的差异 |\n| `arch_history` | 列出架构事件历史 |\n| `arch_check_rules` | 应用规则到新扫描 |\n| `arch_session_start` | 打开会话证据节点 |\n| `arch_session_end` | 关闭会话并写入增量证据 |\n| `arch_metric_explain` | 逐指标解释 |\n\n### 基准测试工具域（benchmark）\n\n基准测试工具域提供了治理健康度和类别摘要的评估工具。\n\n资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-40]()\n\n#### 基准工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `governance_health_bench` | 治理健康基准测试（矛盾检测、审计完整性、漂移检测、可扩展性探测） |\n| `category_summary` | 类别摘要蒸馏查找 |\n\n## MCP工具元数据\n\n所有MCP工具均通过以下装饰器实现统一观测：\n\n### 装饰器链\n\n```python\n@mcp_tool_observe # 观测性装饰器\n@_traced(\"tool_name\") # 追踪装饰器\ndef tool_function(args):\n ...\n```\n\n### 返回格式\n\n所有工具返回JSON格式字符串，包含标准模式版本头：\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"tool_name\": \"result_data\"\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:40-80]()\n\n## 工作区感知\n\nMCP工具集通过统一的`_workspace()`函数解析工作区路径：\n\n```mermaid\ngraph LR\n A[MIND_MEM_WORKSPACE环境变量] -->|优先级1| B[显式覆盖]\n A -->|未设置| C[当前工作目录]\n C --> D[realpath解析]\n B --> D\n D --> E[工作区根目录]\n```\n\n工作区检查通过`_check_workspace()`验证：\n\n1. 工作区目录存在\n2. 必需的子目录结构完整\n3. 必要的配置文件可读\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:20-50]()\n\n## CLI命令映射\n\nMCP工具集同时提供命令行接口（CLI），位于`mm_cli.py`：\n\n| CLI命令 | 对应工具域 |\n|--------|----------|\n| `mm recall` | 记忆召回 |\n| `mm context` | 上下文打包 |\n| `mm inject` | 智能体上下文注入 |\n| `mm vault` | 知识库扫描/写入 |\n| `mm status` | 工作区摘要 |\n| `mm explain` | 指标解释 |\n| `mm trace` | MCP调用日志追踪 |\n\n资料来源：[src/mind_mem/mm_cli.py:1-80]()\n\n## 错误处理\n\nMCP工具集采用统一的错误处理模式：\n\n### 错误类型\n\n| 错误类型 | 说明 | 处理方式 |\n|---------|-----|---------|\n| `WorkspaceError` | 工作区路径无效 | 返回错误JSON |\n| `BlockCorruptedError` | 记忆块损坏 | 隔离并记录 |\n| `CoreLoadError` | mmcore包解析失败 | 验证并报告 |\n| `SQLiteBusyError` | 数据库锁定 | 重试或等待 |\n\n### 错误响应格式\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"error\": \"error_description\"\n}\n```\n\n## 配置集成\n\nMCP工具集通过基础设施层获取配置：\n\n```python\nfrom ..infra.config import _get_limits, _load_extra_categories\nfrom ..infra.workspace import _workspace, _check_workspace\n```\n\n可配置项包括：\n\n- 最大类别结果数\n- 额外类别定义\n- 全文索引限制\n- 导出大小上限\n\n## 扩展机制\n\n### 自定义工具域\n\n新增工具域需要：\n\n1. 在`mcp/tools/`目录下创建新模块\n2. 实现工具函数并添加装饰器\n3. 在`mcp_server.py`中注册\n4. 更新本文档\n\n### 观测性扩展\n\n工具函数通过`mcp_tool_observe`装饰器自动集成到观测系统：\n\n- 调用计数（metrics.inc）\n- 日志记录（_log.info）\n- 追踪（traced decorator）\n\n## 相关文档\n\n- [MCP工具示例](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-tool-examples.md)\n- [MCP服务端架构](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_server.py)\n\n---\n\n\n\n## 治理与矛盾检测\n\n### 相关页面\n\n相关主题：[质量保障与验证](#page-quality), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)\n- [src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)\n- [src/mind_mem/governance_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py)\n- [src/mind_mem/audit_chain.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)\n \n\n# 治理与矛盾检测\n\n## 概述\n\n治理与矛盾检测是 mind-mem 系统的核心安全机制，确保记忆体的变更遵循\"记忆永不直接修改，只能通过治理流程变更\"的不变式。该模块涵盖了从提议、审批、应用到回滚的完整生命周期，同时提供矛盾检测、漂移检测和审计链验证等多层次防护。\n\n核心设计原则：\n- **治理驱动变更**：所有决策和任务的修改必须通过提议-审批流程\n- **证据链完整**：每条证据都有时间戳、来源和可信度标记\n- **矛盾优先检测**：在编译真理页面时自动检测冲突证据\n- **可审计可回滚**：所有操作记录在案，支持快照回滚\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-20]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph 治理层\n A[提议 Propose] --> B[审批 Apply]\n B --> C[回滚 Rollback]\n C --> D[扫描 Scan]\n D --> E[矛盾列表]\n end\n \n subgraph 证据层\n F[CompiledTruthPage] --> G[detect_contradictions]\n G --> H[EvidenceEntry]\n H --> I[superseded 标记]\n end\n \n subgraph 审计层\n J[verify_merkle] --> K[Merkle Tree]\n L[verify_chain] --> M[SHA3-512 Hash Chain]\n N[verify_evidence] --> O[Evidence Chain]\n end\n \n B --> J\n B --> L\n F --> G\n```\n\n## 核心组件\n\n### 1. 治理门 (Governance Gate)\n\n治理门是记忆修改的守门人，确保所有变更必须通过标准流程。\n\n```python\n# 伪代码展示治理门工作流程\ndef governance_check(block):\n if is_proposal(block) and is_approved(block):\n return APPLY\n elif is_contradiction_detected(block):\n return REJECT_CONFLICT\n else:\n return QUEUE_FOR_REVIEW\n```\n\n**治理门配置参数**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `require_approval` | bool | true | 是否要求审批 |\n| `contradiction_threshold` | float | 0.7 | 矛盾检测阈值 |\n| `drift_tolerance` | int | 3 | 漂移容忍度 |\n\n资料来源：[src/mind_mem/governance_gate.py]()\n\n### 2. 矛盾检测器 (Contradiction Detector)\n\n矛盾检测器分析编译真理页面的证据条目，识别相互冲突的陈述。\n\n```mermaid\ngraph LR\n A[Evidence Entry 1] --> D{矛盾检测}\n B[Evidence Entry 2] --> D\n C[Evidence Entry 3] --> D\n D --> E[冲突报告]\n E --> F[标记为 superseded]\n```\n\n**核心检测逻辑**：\n\n```python\ndef detect_contradictions(page: CompiledTruthPage) -> list[Contradiction]:\n \"\"\"检测证据条目间的矛盾\"\"\"\n contradictions = []\n for i, entry_i in enumerate(page.evidence_entries):\n for j, entry_j in enumerate(page.evidence_entries[i+1:], i+1):\n if _is_contradictory(entry_i, entry_j):\n contradictions.append(Contradiction(\n entry_a=i,\n entry_b=j,\n severity=_calculate_severity(entry_i, entry_j)\n ))\n return contradictions\n```\n\n**检测维度**：\n\n| 维度 | 说明 | 优先级 |\n|------|------|--------|\n| 时间矛盾 | 同一事件的时间陈述不一致 | 高 |\n| 属性矛盾 | 实体属性值冲突 | 高 |\n| 因果矛盾 | 因果关系陈述相反 | 中 |\n| 语义矛盾 | 否定/肯定陈述冲突 | 中 |\n| 数值矛盾 | 数值范围或精度不匹配 | 低 |\n\n资料来源：[src/mind_mem/contradiction_detector.py]()\n\n### 3. 漂移检测器 (Drift Detector)\n\n漂移检测器监控决策或任务的实际执行与原始声明之间的偏离。\n\n```mermaid\ngraph TD\n A[原始声明] --> B[版本化快照]\n C[当前状态] --> D{漂移计算}\n B --> D\n D --> E{超出容忍度?}\n E -->|是| F[触发告警]\n E -->|否| G[继续监控]\n```\n\n**漂移检测触发条件**：\n\n- 决策状态与预期不符\n- 任务优先级发生非预期变更\n- 截止日期与原计划偏差超过阈值\n- 关联实体发生未记录变更\n\n资料来源：[src/mind_mem/drift_detector.py]()\n\n### 4. 审计链 (Audit Chain)\n\n审计链提供加密可验证的完整性证明，确保记忆体的历史不可篡改。\n\n```mermaid\ngraph LR\n A[Block 1] -->|SHA3-512| B[Block 2]\n B -->|SHA3-512| C[Block 3]\n C -->|SHA3-512| D[Block N]\n D --> E[Merkle Root]\n \n F[Merkle Proof] --> G[验证包含性]\n```\n\n**审计工具清单**：\n\n| 工具 | 功能 | 输入 | 输出 |\n|------|------|------|------|\n| `verify_merkle` | Merkle包含证明 | block_id, content_hash | 证明 + ok标志 |\n| `verify_chain` | 哈希链验证 | workspace路径 | 完整性报告 |\n| `list_evidence` | 证据枚举 | block_id, action过滤 | 证据列表 |\n| `mind_mem_verify` | CLI审计入口 | snapshot路径 | 验证结果 |\n\n资料来源：[src/mind_mem/mcp/tools/audit.py:1-50]()\n\n## MCP 治理工具\n\n### propose_update - 提议更新\n\n创建新的决策或任务提议，写入 SIGNALS.md 待人工审核。\n\n**函数签名**：\n\n```python\ndef propose_update(\n block_type: str,\n statement: str,\n rationale: str = \"\",\n tags: str = \"\",\n confidence: str = \"medium\"\n) -> str\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `block_type` | str | 是 | 块类型 (DECISION/TASK) |\n| `statement` | str | 是 | 核心陈述 |\n| `rationale` | str | 否 | 变更理由 |\n| `tags` | str | 否 | 逗号分隔标签 |\n| `confidence` | str | 否 | 可信度 (low/medium/high) |\n\n**返回值示例**：\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"signal_id\": \"SIG-20260115-001\",\n \"message\": \"Proposal queued for review\"\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:50-80]()\n\n### approve_apply - 审批应用\n\n应用已通过的提议，支持干运行模式。\n\n**核心流程**：\n\n```mermaid\ngraph TD\n A[加载提议] --> B[干运行验证]\n B --> C{验证通过?}\n C -->|否| D[返回错误]\n C -->|是| E[创建快照]\n E --> F[应用变更]\n F --> G[更新索引]\n G --> H[清理信号]\n```\n\n**关键特性**：\n- 默认干运行 (`dry_run=True`)\n- 自动快照回滚点\n- 原子性事务保证\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:100-150]()\n\n### rollback_proposal - 回滚提案\n\n从预应用快照恢复工作区状态。\n\n```mermaid\ngraph LR\n A[当前状态] --> B[快照恢复]\n B --> C[索引回退]\n C --> D[信号重建]\n```\n\n**约束条件**：\n- 只能回滚处于待应用状态的提案\n- 快照必须在有效期内（默认7天）\n- 回滚本身会产生新的治理记录\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:150-200]()\n\n### scan - 完整性扫描\n\n执行综合健康检查，覆盖矛盾检测、漂移检测和待处理项。\n\n```python\ndef scan(workspace: str) -> dict:\n return {\n \"contradictions\": detect_all_contradictions(workspace),\n \"drift\": detect_drift(workspace),\n \"pending\": list_pending_signals(workspace),\n \"health_score\": calculate_health_score(workspace)\n }\n```\n\n**扫描子项**：\n\n| 子项 | 说明 | 阈值 |\n|------|------|------|\n| 矛盾数量 | 检测到的冲突证据对 | > 0 需关注 |\n| 漂移事件 | 偏离原声明的变更 | > 3 需关注 |\n| 待审批 | 队列中的提案数 | 无限制 |\n| 审计完整性 | 哈希链连续性 | 必须完整 |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:200-250]()\n\n### list_contradictions - 矛盾列表\n\n返回枚举的矛盾详情，支持富文本输出。\n\n**输出格式**：\n\n```json\n{\n \"contradictions\": [\n {\n \"entity_id\": \"PRJ-alpha\",\n \"severity\": \"high\",\n \"entries\": [\n {\n \"index\": 0,\n \"timestamp\": \"2026-01-10T09:00:00Z\",\n \"observation\": \"项目截止日期为 Q1\",\n \"confidence\": \"HIGH\",\n \"source\": \"decisions.md\"\n },\n {\n \"index\": 3,\n \"timestamp\": \"2026-01-12T14:30:00Z\",\n \"observation\": \"项目截止日期为 Q2\",\n \"confidence\": \"MEDIUM\",\n \"source\": \"tasks.md\"\n }\n ]\n }\n ]\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:250-300]()\n\n### governance_health_bench - 健康基准测试\n\n运行治理健康基准测试套件，验证矛盾检测、审计完整性、漂移检测和可扩展性。\n\n**测试子项**：\n\n| 测试 | 覆盖范围 | 预期结果 |\n|------|----------|----------|\n| 矛盾检测探针 | 人工构造的矛盾场景 | 100%检出 |\n| 审计完整性探针 | 哈希链断裂注入 | 正确检测 |\n| 漂移探针 | 状态偏离注入 | 正确识别 |\n| 可扩展性探针 | 大规模数据压力 | 性能可接受 |\n\n**返回值结构**：\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"tests_run\": 12,\n \"passed\": 11,\n \"failed\": 1,\n \"results\": [...]\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/benchmark.py:20-60]()\n\n## 编译真理页面 (Compiled Truth Page)\n\n编译真理页面是矛盾检测的核心载体，聚合实体的所有证据并自动编译权威理解。\n\n### 数据结构\n\n```python\n@dataclass\nclass CompiledTruthPage:\n entity_id: str # 实体标识符\n entity_type: str # 实体类型 (PER/PRJ/TOOL/INC)\n compiled_section: str # 编译后的权威理解\n evidence_entries: list[EvidenceEntry] # 证据条目列表\n last_compiled: str # ISO时间戳\n version: int # 版本号\n```\n\n### 证据条目\n\n```python\n@dataclass\nclass EvidenceEntry:\n timestamp: str # ISO 8601 时间戳\n source: str # 来源文件\n observation: str # 观察内容\n confidence: str # HIGH/MEDIUM/LOW\n superseded: bool # 是否已被取代\n```\n\n### 矛盾检测集成\n\n编译真理页面在重新编译时自动调用矛盾检测：\n\n```python\ndef recompile_truth(page: CompiledTruthPage) -> CompiledTruthPage:\n \"\"\"从非取代证据重新生成编译部分\"\"\"\n # 过滤非取代证据\n active_entries = [e for e in page.evidence_entries if not e.superseded]\n \n # 检测矛盾\n contradictions = detect_contradictions(page)\n \n # 生成报告\n for conflict in contradictions:\n _log.warning(\n \"contradiction_detected\",\n entity_id=page.entity_id,\n entry_a=conflict.entry_a,\n entry_b=conflict.entry_b\n )\n \n # 按时间戳排序，生成摘要\n ...\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:100-150]()\n\n### 证据取代机制\n\n当检测到矛盾时，可通过治理流程标记旧证据为 superseded：\n\n```python\ndef supersede_evidence(\n page: CompiledTruthPage,\n entry_index: int,\n reason: str\n) -> CompiledTruthPage:\n \"\"\"将证据标记为已取代\"\"\"\n new_entry = dataclasses.replace(\n page.evidence_entries[entry_index],\n superseded=True\n )\n new_entries = list(page.evidence_entries)\n new_entries[entry_index] = new_entry\n return dataclasses.replace(page, evidence_entries=new_entries)\n```\n\n**取代规则**：\n- 被取代证据仍保留在历史中，但计算时忽略\n- 取代操作本身产生新的治理记录\n- 新版本触发重新编译\n\n资料来源：[src/mind_mem/compiled_truth.py:150-200]()\n\n## 工作流示例\n\n### 决策变更完整流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP as MCP Server\n participant Store as Block Store\n participant Audit as Audit Chain\n participant Truth as Compiled Truth\n\n Agent->>MCP: propose_update(DECISION, \"变更X\")\n MCP->>Store: 写入SIGNALS.md\n Note over MCP: 状态: PENDING\n\n Agent->>MCP: approve_apply(SIG-xxx, dry_run=true)\n MCP->>Truth: 检查矛盾\n Truth-->>MCP: 无冲突\n\n Agent->>MCP: approve_apply(SIG-xxx, dry_run=false)\n MCP->>Store: 创建快照\n MCP->>Store: 应用变更\n MCP->>Audit: 更新哈希链\n Note over MCP: 状态: APPLIED\n\n Agent->>MCP: scan()\n MCP-->>Agent: 健康报告\n```\n\n### 矛盾处理流程\n\n```mermaid\ngraph TD\n A[检测到矛盾] --> B{自动解决可能?}\n B -->|否| C[人工审核]\n C --> D[审查证据]\n D --> E[选择保留哪条]\n E --> F[取代旧证据]\n B -->|是| G[自动取代低可信度]\n G --> F\n F --> H[重新编译]\n H --> I[生成新版本]\n I --> J[更新审计链]\n```\n\n## 配置选项\n\n### 矛盾检测配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `contradiction_min_confidence_gap` | 0.3 | 最低可信度差距 |\n| `auto_supersede_low_confidence` | true | 自动取代低可信度 |\n| `contradiction_alert_threshold` | 2 | 告警阈值 |\n\n### 审计配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `hash_algorithm` | SHA3-512 | 哈希算法 |\n| `merkle_update_on_write` | true | 写入时更新Merkle树 |\n| `audit_retention_days` | 365 | 审计保留天数 |\n\n### 漂移检测配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `drift_check_interval_hours` | 24 | 检查间隔 |\n| `drift_tolerance_priority` | 2 | 优先级容差 |\n| `drift_tolerance_date_days` | 7 | 日期容差 |\n\n## 相关命令\n\n### mm CLI 治理命令\n\n```bash\n# 提议新决策\nmm governance propose --type DECISION --statement \"采用新技术栈\"\n\n# 应用审批\nmm governance approve SIG-20260115-001\n\n# 回滚操作\nmm governance rollback SIG-20260115-001\n\n# 运行健康扫描\nmm governance scan\n\n# 列出矛盾\nmm governance contradictions --entity PRJ-alpha\n\n# 验证审计链\nmm verify --type chain\n```\n\n### MCP 工具调用\n\n```json\n{\n \"tool\": \"propose_update\",\n \"arguments\": {\n \"block_type\": \"DECISION\",\n \"statement\": \"迁移至微服务架构\",\n \"rationale\": \"提升可扩展性\",\n \"tags\": \"architecture, refactor\",\n \"confidence\": \"high\"\n }\n}\n```\n\n## 最佳实践\n\n### 1. 矛盾预防\n- 在添加新证据前先查询现有编译真理页面\n- 使用高可信度来源标注证据\n- 避免重复提交相似陈述\n\n### 2. 治理流程\n- 干运行优先，正式应用前验证\n- 保持提议的原子性描述\n- 定期运行健康扫描\n\n### 3. 审计合规\n- 验证哈希链完整性作为CI/CD环节\n- 保留足够的快照以支持回滚\n- 监控审计链验证失败事件\n\n## 总结\n\n治理与矛盾检测模块为 mind-mem 提供了企业级的记忆管理安全保障。通过\"提议-审批-应用-回滚\"的完整生命周期管理，确保了所有变更的可追溯性和可控性。矛盾检测与编译真理页面的深度集成，使得知识库的权威性得到持续维护，而审计链则为整个系统提供了密码学级别的完整性保证。\n\n---\n\n\n\n## 质量保障与验证\n\n### 相关页面\n\n相关主题：[治理与矛盾检测](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n- [src/mind_mem/block_parser.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/model_provenance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n \n\n# 质量保障与验证\n\nmind-mem 采用多层次的质量保障体系，确保记忆块的可靠性、一致性和安全性。系统从内容存储前的预处理、解析时的验证、到运行时的矛盾检测，形成了完整的质量闭环。\n\n## 质量门禁（Quality Gate）\n\n质量门禁是记忆块写入前的第一道防线，位于 `src/mind_mem/quality_gate.py`。它是一个确定性、基于内容的预存储过滤器，对候选块进行检查并返回结构化裁决。\n\n### 核心规则\n\n质量门禁包含八条规则，全部为确定性规则，不依赖外部服务：\n\n| 规则标识 | 规则名称 | 检查条件 | 处理方式 |\n|---------|---------|---------|---------|\n| `empty` | 空块检测 | 块内容为纯空白字符 | 标记并可拒绝 |\n| `too_short` | 过短检测 | 非空白字符少于 32 个 | 标记并可拒绝 |\n| `oversize` | 超大检测 | UTF-8 编码超过 64 KiB | 标记并可拒绝 |\n| `malformed_utf8` | UTF-8 损坏检测 | 包含孤立代理或无法通过 UTF-8 往返 | 标记并可拒绝 |\n| `stopwords_only` | 停用词检测 | 所有 token 均为停用词，无语义内容 | 标记并可拒绝 |\n| `near_duplicate` | 近似重复检测 | 与 24 小时内块编辑距离相似度 ≥ 0.97 | 标记并可拒绝 |\n| `injection_marker` | 注入标记检测 | 匹配已知提示注入模式 | 标记并可拒绝 |\n| `ok` | 通过 | 无规则触发 | 接受 |\n\n### 裁决模式\n\n质量门禁支持两种裁决模式：\n\n- **顾问模式（默认）**：每条规则都会被记录，但裁决仍返回 `accept`\n- **严格模式（strict）**：任何规则触发都导致 `reject`\n\n严格模式可通过以下方式启用：\n1. 调用时传入 `strict=True` 关键字参数\n2. 工作区 `QualityGateConfig(mode=\"strict\")`\n3. 工作区配置 `mind-mem.json` 中的 `quality_gate_mode = \"strict\"`\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[接收候选块] --> B[执行 8 条规则检查]\n B --> C{触发任何规则?}\n C -->|否| D[裁决: accept]\n C -->|是| E{strict 模式?}\n E -->|否| F[记录日志]\n F --> D\n E -->|是| G[裁决: reject]\n D --> H[写入存储]\n G --> I[返回错误信息]\n```\n\n### 返回数据结构\n\n```python\n@dataclass\nclass Verdict:\n decision: Literal[\"accept\", \"reject\"]\n fired_rules: list[str] # 触发的规则列表\n score: float # 质量分数 0.0-1.0\n reason: Optional[str] # 拒绝原因描述\n```\n\n资料来源：[src/mind_mem/quality_gate.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n\n## 块解析质量控制\n\n`src/mind_mem/block_parser.py` 负责从文本中解析记忆块，解析过程内置了多项质量验证机制。\n\n### UTF-8 BOM 处理\n\n解析器首先检查并处理 UTF-8 BOM（Byte Order Mark）：\n\n```python\nif text.startswith(''):\n text = text[1:]\n```\n\n这确保第一个块头不会被 BOM 字符遮挡，保证解析的一致性。\n\n### 否定块识别\n\n系统内置否定块检测正则表达式，用于识别语义反转的声明：\n\n```python\n_NEGATION_RE = re.compile(\n r\"\\b(not|never|don't|won't|shouldn't|cannot|can't|...\"\n r\"|no\\s+\\w+|none)\\b\",\n re.IGNORECASE,\n)\n```\n\n这对于矛盾检测和语义理解具有重要意义。\n\n### ConstraintSignature 解析\n\nv2.0 版本支持结构化的 ConstraintSignature 解析，识别以下嵌套字段：\n\n| 字段名 | 用途 |\n|-------|------|\n| `scope` | 约束作用范围 |\n| `axis` | 约束维度 |\n| `lifecycle` | 生命周期阶段 |\n\n解析器维护内部状态机，正确处理嵌套结构和操作符列表。\n\n资料来源：[src/mind_mem/block_parser.py:1-80](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)\n\n## 编译真相与矛盾检测\n\n编译真相（Compiled Truth）是 mind-mem 的核心概念之一，位于 `src/mind_mem/compiled_truth.py`。它通过聚合证据来维护实体的规范理解。\n\n### 证据条目结构\n\n```python\n@dataclass\nclass EvidenceEntry:\n timestamp: str # ISO 时间戳\n source: str # 来源标识\n observation: str # 观察内容\n confidence: str # 置信度: high/medium/low\n superseded: bool # 是否已被替代\n```\n\n### 编译真相页面结构\n\n| 字段 | 说明 |\n|-----|------|\n| `entity_id` | 实体唯一标识符 |\n| `entity_type` | 实体类型 |\n| `compiled_section` | 当前规范理解（摘要） |\n| `evidence_entries` | 证据条目列表 |\n| `last_compiled` | 最后编译时间 |\n| `version` | 版本号 |\n\n### 矛盾检测\n\n系统提供 `detect_contradictions()` 函数用于检测编译真相页面中的矛盾：\n\n```python\ndef detect_contradictions(page: CompiledTruthPage) -> list[ContradictionPair]:\n \"\"\"检测页面中的矛盾证据对\"\"\"\n```\n\n矛盾检测通过以下步骤工作：\n1. 遍历所有未废弃的证据条目\n2. 比较语义相反的陈述\n3. 识别否定关系（如 \"应该使用 X\" vs \"不应该使用 X\"）\n4. 返回矛盾对列表\n\n### 证据替代机制\n\n当新证据与旧证据矛盾时，系统支持标记旧证据为已废弃：\n\n```python\ndef supersede_evidence(\n page: CompiledTruthPage,\n entry_index: int,\n reason: str\n) -> CompiledTruthPage:\n```\n\n替代后的旧证据保留在历史中，但不影响规范理解的生成。\n\n资料来源：[src/mind_mem/compiled_truth.py:1-150](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## 治理工具与矛盾扫描\n\nMCP 工具提供程序化的质量保障能力，位于 `src/mind_mem/mcp/tools/governance.py`。\n\n### 可用工具\n\n| 工具名称 | 功能 |\n|---------|------|\n| `propose_update` | 提议新决策或任务，写入 SIGNALS.md 待人工审核 |\n| `approve_apply` | 应用已提议的更新（默认干跑模式） |\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理） |\n| `list_contradictions` | 矛盾列表的富文本展示 |\n| `memory_evolution` | 获取块的 A-MEM 元数据 |\n\n### 扫描操作\n\n`scan` 工具执行三类检查：\n\n1. **矛盾检测**：识别同一实体的相互冲突的证据\n2. **漂移检测**：检测规范理解与实际证据的不一致\n3. **待处理检测**：列出未处理的信号和提案\n\n### SQLite 锁处理\n\n扫描操作使用 SQLite 数据库，工具内置锁冲突处理：\n\n```python\ndef _is_db_locked(exc: Exception) -> bool:\n return \"database is locked\" in str(exc)\n\ndef _sqlite_busy_error(result: str, exc: Exception) -> str:\n return json.dumps({\"error\": f\"DB locked: {exc}\", \"retry\": True})\n```\n\n资料来源：[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)\n\n## 模型溯源验证\n\n`src/mind_mem/model_provenance.py` 提供模型出处检查能力，确保引用的模型信息准确。\n\n### 支持的发布商\n\n| 发布商 | Slug 标识 | 模型家族 |\n|-------|----------|---------|\n| Meta Llama | `meta-llama` | Llama 2/3/4 |\n| Mistral | `mistralai` | Mistral/Mixtral/Codestral |\n| Google Gemma | `google` | Gemma/Gemma-2/PaLM |\n| IBM Granite | `ibm-granite`, `ibm` | Granite-3/Granite-Code |\n| DeepSeek | `deepseek-ai` | DeepSeek-V2/V3/R1 |\n| Microsoft Phi | `microsoft` | Phi-2/Phi-3/Phi-4 |\n| TII Falcon | `tiiuae` | Falcon-7B/40B/180B |\n\n### ProvenanceFinding 结果\n\n```python\n@dataclass\nclass ProvenanceFinding:\n passed: bool # 检查是否通过\n publisher: Optional[str] # 识别的发布商\n model_family: Optional[str] # 模型家族\n confidence: float # 置信度 0.0-1.0\n```\n\n资料来源：[src/mind_mem/model_provenance.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)\n\n## 删除恢复与审计\n\n系统维护删除操作的全量审计日志，支持误删恢复。\n\n### 删除收据格式\n\n删除块时，系统将删除收据写入 `memory/deleted_blocks.jsonl`：\n\n```json\n{\n \"block_id\": \"D-20260213-001\",\n \"deleted_at\": \"2026-03-15T10:30:00+00:00\",\n \"content\": \"原始块内容...\"\n}\n```\n\n### 块定位逻辑\n\n删除收据记录使用与 `mcp.tools.memory_ops.delete_memory_item` 相同的边界规则：\n- 块从 `[]` 行开始\n- 块结束于下一个 `[]` 头行、孤立的 `---` 分隔符或 EOF\n\n这确保两个删除路径收敛到同一恢复日志格式。\n\n资料来源：[src/mind_mem/block_store.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n## 配置与指标\n\n### 质量门禁配置优先级\n\n```\n1. 函数调用 strict=True 参数（最高优先级）\n2. QualityGateConfig(mode=\"strict\") 对象\n3. mind-mem.json 中的 quality_gate_mode 设置\n4. 默认值（advisory 模式）\n```\n\n### 质量指标\n\n系统通过 `metrics.inc()` 追踪质量事件：\n\n| 指标名称 | 触发场景 |\n|---------|---------|\n| `truth_pages_loaded` | 编译真相页面加载 |\n| `evidence_entries_superseded` | 证据被替代 |\n| `mcp_compiled_truth_add_evidence` | 添加新证据 |\n| `contradictions_detected` | 检测到矛盾 |\n\n### 日志记录\n\n质量事件通过结构化日志记录：\n\n```python\n_log.info(\n \"evidence_superseded\",\n entity_id=page.entity_id,\n index=entry_index,\n reason=reason,\n)\n```\n\n日志输出到 `MIND_MEM_LOG_FILE` 或标准输出。\n\n## 最佳实践\n\n### 启用严格模式\n\n对于生产环境，建议在工作区配置中启用严格模式：\n\n```json\n{\n \"quality_gate_mode\": \"strict\"\n}\n```\n\n### 定期扫描\n\n使用 MCP 工具 `scan` 定期检查工作区一致性：\n\n```bash\nmm mcp call scan --scan-type full\n```\n\n### 矛盾审查\n\n当检测到矛盾时，通过 `list_contradictions` 工具获取详细信息：\n\n```bash\nmm mcp call list_contradictions\n```\n\n### 删除恢复\n\n误删块后，可通过 `deleted_blocks.jsonl` 恢复内容：\n\n```bash\n# 查看最近删除\ntail -n 10 memory/deleted_blocks.jsonl\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：star-ga/mind-mem\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)。\n\n## 1. 安装坑 · 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_366d8c18c1aa45ffb07174af516285d4 | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing\n\n## 8. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-251)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e9c9207806f46a6a90a83828e99c173 | https://github.com/star-ga/mind-mem/issues/529 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ea39fdeb939e484a9be8751555483fc5 | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d71f093408f04636bc91f85df44c811d | https://github.com/star-ga/mind-mem/issues/508 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7bf148881d754982a8b6bbb0959436d0 | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_afb67087422e43678c941140da7019de | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0917cf4b43b34ffe8d43e599d353665c | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad9e7a85457041afbc88c886568b2657 | https://github.com/star-ga/mind-mem/issues/511 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_32106da2cae04c0185f7a6331cd1ef8a | https://github.com/star-ga/mind-mem/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport.py:687-694)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7bba956cb937439b85b35fb2c150b7e2 | https://github.com/star-ga/mind-mem/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | release_recency=unknown\n\n\n",
"markdown_key": "mind-mem",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1160652179",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/star-ga/mind-mem"
},
{
"evidence_id": "art_32f595081d75424fa883dd916bfe51ca",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/star-ga/mind-mem#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mind-mem 说明书",
"toc": [
"https://github.com/star-ga/mind-mem 项目说明书",
"目录",
"MIND-Mem简介",
"项目概述",
"系统架构",
"核心功能",
"MCP工具分类",
"工作区结构",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "e26fae773e925f06c4dca2651333860ddf7d482e",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"docs/workspace-structure.md",
"docs/hf-mind-mem-4b-v2-README.md",
"docs/changelog-format.md",
"docs/security-audit-sow.md",
"docs/migration-guide.md",
"docs/SECURITY_AUDIT_SELF_2026_04.md",
"docs/integrations.md",
"docs/architecture.md",
"docs/security-model.md",
"docs/mind-kernels.md",
"docs/mind-mem-4b-training-runbook.md",
"docs/protection.md",
"docs/review-tests-v3.2.0.md",
"docs/scoring.md",
"docs/v3.3.0-release-notes.md",
"docs/review-database-v3.2.0.md",
"docs/glossary.md",
"docs/troubleshooting.md",
"docs/v3.4.0-release-notes.md",
"docs/roadmap.md",
"docs/api-reference.md",
"docs/v3.11.0-implementation-plan.md",
"docs/docker-deployment.md",
"docs/governance.md",
"docs/mcp-integration.md",
"docs/cli-reference.md",
"docs/quickstart.md",
"docs/v3.1.9-self-audit.md",
"docs/supply-chain-security.md",
"docs/locomo-v3.4-conv0-results.md",
"docs/v4-release.md",
"docs/getting-started.md",
"docs/configuration.md",
"docs/review-architecture-v3.2.0.md",
"docs/usage.md",
"docs/claude-desktop-setup.md",
"docs/competitive-analysis-persistent-memory-2026.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @mind-mem/sdk - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @mind-mem/sdk 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `skills/apply-proposal/SKILL.md`, `skills/integrity-scan/SKILL.md`, `skills/memory-recall/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `skills/apply-proposal/SKILL.md`, `skills/integrity-scan/SKILL.md`, `skills/memory-recall/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/star-ga/mind-mem.git` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0008` supported 0.86\n- `pip install mind-mem` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pipx install \"mind-mem[mcp]\"` 证据：`README.md` Claim：`clm_0007` supported 0.86, `clm_0009` supported 0.86\n- `git clone https://github.com/star-ga/mind-mem.git .mind-mem` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pipx install \"mind-mem[mcp]\" # preferred — isolated venv with mind-mem-mcp on PATH` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install --user \"mind-mem[mcp]\"` 证据：`README.md` Claim：`clm_0010` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `skills/apply-proposal/SKILL.md`, `skills/integrity-scan/SKILL.md`, `skills/memory-recall/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `skills/apply-proposal/SKILL.md`, `skills/integrity-scan/SKILL.md`, `skills/memory-recall/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0008` supported 0.86\n\n### 现在还不能相信\n\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `skills/apply-proposal/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `skills/apply-proposal/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `README.md`, `ROADMAP.md`, `SECURITY.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0012` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.agents/skills/mind-mem-development/SKILL.md`, `skills/apply-proposal/SKILL.md`, `skills/integrity-scan/SKILL.md`, `skills/memory-recall/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：827\n- 重要文件覆盖：40/827\n- 证据索引条目：80\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @mind-mem/sdk 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @mind-mem/sdk 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @mind-mem/sdk 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **mind-mem-development**（skill）：MIND-Mem Python development guide 激活提示：当用户任务与“mind-mem-development”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.agents/skills/mind-mem-development/SKILL.md`\n- **/apply — Apply Proposals**（skill）：Review and apply intelligence proposals generated by /scan. Uses atomic operations with rollback safety. 激活提示：当用户任务与“/apply — Apply Proposals”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/apply-proposal/SKILL.md`\n- **/scan — Memory Integrity Scan**（skill）：Run the intelligence scanner to detect contradictions, drift, dead decisions, and missing cross-references across the entire memory workspace. 激活提示：当用户任务与“/scan — Memory Integrity Scan”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/integrity-scan/SKILL.md`\n- **/recall — Memory Search**（skill）：Search across all structured memory files. Default backend: BM25 scoring with Porter stemming and domain-aware query expansion. Optional: graph-based cross-reference boosting --graph . Optional: vector/embedding backend configure in mind-mem.json . Returns ranked results with block ID, type, score, excerpt, and file path. 激活提示：当用户任务与“/recall — Memory Search”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`skills/memory-recall/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **mind-mem: agent instructions auto-written**（documentation）：mind-mem: agent instructions auto-written 证据：`AGENTS.md`\n- **MIND-Mem — Persistent AI Memory System**（documentation）：MIND-Mem — Persistent AI Memory System 证据：`CLAUDE.md`\n- **Shared Memory Across All Your AI Agents**（documentation）：MIND-Mem Drop-in memory for Claude Code, OpenClaw, and any MCP-compatible agent. OpenClaw is an open-source AI assistant platform with multi-channel support. Local-first • Zero-infrastructure • Governance-aware • MIND-accelerated 证据：`README.md`\n- **MIND-Mem Examples**（documentation）：Demonstrates workspace initialization, block creation, and BM25 recall. 证据：`examples/README.md`\n- **MIND Kernels**（documentation）：Numerical hot paths for MIND-Mem, written in the MIND programming language https://mindlang.dev . 证据：`mind/README.md`\n- **mind-mem-4b training pipeline**（documentation）：Scripts to retrain the star-ga/mind-mem-4b https://huggingface.co/star-ga/mind-mem-4b governance-aware memory-assistant model on a fresh checkout of the MIND-Mem repo. 证据：`train/README.md`\n- **MIND-Mem web console**（documentation）：Thin Next.js client for the MIND-Mem REST API v3.2.0+ . Shows a force-directed graph of blocks + their cross-references, a chronological timeline of dated events, and a facts panel — all derived from a single recall format=\"bundle\" call. 证据：`web/README.md`\n- **mind-mem-edge — single-binary distribution v4.0 prep**（documentation）：mind-mem-edge — single-binary distribution v4.0 prep 证据：`deploy/edge/README.md`\n- **MIND-Mem Go SDK**（documentation）：Go client for the MIND-Mem https://github.com/star-ga/mind-mem REST API. Stdlib-only — no external dependencies. 证据：`sdk/go/README.md`\n- **@mind-mem/sdk**（documentation）：JavaScript / TypeScript client for the MIND-Mem https://github.com/star-ga/mind-mem REST API. 证据：`sdk/js/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@star-ga/mind-mem-web\", \"version\": \"0.1.0\", \"private\": true, \"description\": \"mind-mem governance web console — graph + timeline + drift heatmap over the v3.2.0 REST API\", \"license\": \"Apache-2.0\", \"scripts\": { \"dev\": \"next dev\", \"build\": \"next build\", \"start\": \"next start\", \"lint\": \"next lint\", \"typecheck\": \"tsc --noEmit\" }, \"dependencies\": { \"next\": \"^15.0.0\", \"react\": \"^19.0.0\", \"react-dom\": \"^19.0.0\", \"d3\": \"^7.9.0\", \"react-flow-renderer\": \"^11.0.0\" }, \"devDependencies\": { \"@types/d3\": \"^7.4.3\", \"@types/node\": \"^22.0.0\", \"@types/react\": \"^19.0.0\", \"@types/react-dom\": \"^19.0.0\", \"eslint\": \"^9.0.0\", \"eslint-config-next\": \"^15.0.0\", \"typescript\": \"^5.6.0\" } } 证据：`web/package.json`\n- **Contributing to MIND-Mem**（documentation）：Thank you for your interest in contributing to MIND-Mem! 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@mind-mem/sdk\", \"version\": \"0.1.0\", \"description\": \"JS/TS client SDK for the mind-mem REST API\", \"license\": \"Apache-2.0\", \"type\": \"module\", \"main\": \"dist/index.js\", \"types\": \"dist/index.d.ts\", \"exports\": { \".\": { \"import\": \"./dist/index.js\", \"types\": \"./dist/index.d.ts\" } }, \"files\": \"dist\" , \"scripts\": { \"build\": \"tsc\", \"test\": \"node --test test/ .test.js\", \"test:ts\": \"npx --yes tsx --test test/ .test.ts\", \"clean\": \"rm -rf dist\", \"prepublishOnly\": \"npm run clean && npm run build\" }, \"engines\": { \"node\": \" =18\" }, \"devDependencies\": { \"@types/node\": \"^20.19.39\", \"typescript\": \"^5.9.3\" }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/star-ga/mind-mem.git\", \"directory\":… 证据：`sdk/js/package.json`\n- **MIND-Mem Development**（skill_instruction）：Package - PyPI: pip install mind-mem - Source layout: src/mind mem/ - Tests: pytest, 3610 passing - CI: GitHub Actions, 3 OS × 4 Python versions 16 matrix jobs 证据：`.agents/skills/mind-mem-development/SKILL.md`\n- **/apply — Apply Proposals**（skill_instruction）：Review and apply intelligence proposals generated by /scan. Uses atomic operations with rollback safety. 证据：`skills/apply-proposal/SKILL.md`\n- **/scan — Memory Integrity Scan**（skill_instruction）：Run the intelligence scanner to detect contradictions, drift, dead decisions, and missing cross-references across the entire memory workspace. 证据：`skills/integrity-scan/SKILL.md`\n- **/recall — Memory Search**（skill_instruction）：Search across all structured memory files. Default backend: BM25 scoring with Porter stemming and domain-aware query expansion. Optional: graph-based cross-reference boosting --graph . Optional: vector/embedding backend configure in mind-mem.json . Returns ranked results with block ID, type, score, excerpt, and file path. 证据：`skills/memory-recall/SKILL.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **MIND-Mem v3.2.0 — Self-Audit Plan Post-Release Deliverable**（documentation）：MIND-Mem v3.2.0 — Self-Audit Plan Post-Release Deliverable 证据：`docs/SECURITY_AUDIT_SELF_2026_04.md`\n- **Agent Memory Protocol — canonical system-prompt snippet**（documentation）：Agent Memory Protocol — canonical system-prompt snippet 证据：`docs/agent-memory-protocol.md`\n- **API Reference**（documentation）：recall workspace: str, query: str, limit: int = 10, kwargs - list dict Search blocks using BM25F scoring with graph boost, fact card aggregation, and knee cutoff. 证据：`docs/api-reference.md`\n- **Architecture**（documentation）：MIND-Mem is a persistent, auditable, contradiction-safe memory system for coding agents. It provides BM25F-based retrieval with graph boost, fact indexing, and adaptive cutoff. 证据：`docs/architecture.md`\n- **MIND-Mem — response to the 2026-05-02 ecosystem audit**（documentation）：MIND-Mem — response to the 2026-05-02 ecosystem audit 证据：`docs/audit_response.md`\n- **Benchmarks**（documentation）：Latest checked-in benchmark snapshot from the v1.9.0 evaluation with Mistral Large LoCoMo, 10 conversations . Current release 3.1.1 is feature-additive and does not invalidate these scores; a fresh benchmark artifact against v3.x is planned for the next release cycle: 证据：`docs/benchmarks.md`\n- **Block Format**（documentation）：MIND-Mem stores information as structured blocks in markdown files. Each block represents a discrete unit of knowledge. 证据：`docs/block-format.md`\n- **Changelog Format Guide**（documentation）：MIND-Mem follows Keep a Changelog https://keepachangelog.com/ format. 证据：`docs/changelog-format.md`\n- **CI Workflows**（documentation）：MIND-Mem uses GitHub Actions for continuous integration. 证据：`docs/ci-workflows.md`\n- **Claude Desktop Setup Guide**（documentation）：Step-by-step guide to connect MIND-Mem to Claude Desktop as an MCP server. 证据：`docs/claude-desktop-setup.md`\n- **CLI Reference**（documentation）：The mm command is the unified MIND-Mem CLI for non-MCP agents. 证据：`docs/cli-reference.md`\n- **Client Integrations**（documentation）：MIND-Mem works with 16 AI coding clients out of the box. Every client reads and writes to the same shared workspace default ~/.openclaw/workspace/ , so a fact captured in one tool is immediately visible to every other. 证据：`docs/client-integrations.md`\n- **Comparison with Alternatives**（documentation）：Feature MIND-Mem Mem0 --------- ---------- ------ Dependencies Zero Redis, PostgreSQL Retrieval BM25F + vector hybrid Vector only Audit trail Full proposal system Limited LoCoMo benchmark 77.9 mean 66.88 mean Contradiction detection Built-in No 证据：`docs/comparison.md`\n- **Comprehensive Competitive Analysis: Persistent Memory Systems for AI Coding Agents 2025–2026**（documentation）：Comprehensive Competitive Analysis: Persistent Memory Systems for AI Coding Agents 2025–2026 证据：`docs/competitive-analysis-persistent-memory-2026.md`\n- **Configuration Reference**（documentation）：MIND-Mem is configured via mind-mem.json in your workspace root. This file is created automatically by init workspace.py with sensible defaults. All keys are optional -- missing keys fall back to their documented defaults. 证据：`docs/configuration.md`\n- **Development Guide**（documentation）：Specific module pytest tests/test recall edge cases.py 证据：`docs/development.md`\n- **Docker Deployment**（documentation）：Self-hosted MIND-Mem with Postgres+pgvector and Ollama in one command. 证据：`docs/docker-deployment.md`\n- **FAQ**（documentation）：What is MIND-Mem? MIND-Mem is a persistent, auditable, contradiction-safe memory system for AI coding agents. It provides BM25F-based retrieval with graph boost, fact indexing, and adaptive cutoff. 证据：`docs/faq.md`\n- **Getting Started**（documentation）：python from mind mem.init workspace import init 证据：`docs/getting-started.md`\n- **Glossary**（documentation）：Term Definition ------ ----------- Block A discrete unit of knowledge stored as structured markdown BM25F Best Matching 25 with field weights — the primary scoring algorithm Co-retrieval graph Graph linking blocks frequently returned together Fact card Atomic 10-20 word sub-block indexed from Statements Graph boost Score propagation from co-retrieval graph neighbors Hard negative Block scoring high on BM25 but low on reranking Knee cutoff Adaptive truncation at steepest score drop MCP Model Context Protocol — standard for AI tool integration MIND kernel Configuration file for customizing scoring behavior Proposal A staged memory change awaiting human approval Recall The primary search opera… 证据：`docs/glossary.md`\n- **MIND-Mem — governance design 5 layers**（documentation）：MIND-Mem — governance design 5 layers 证据：`docs/governance.md`\n- **mind-mem-4b v2 2026-04-21**（documentation）：A governance-aware memory-assistant model for MIND-Mem https://github.com/star-ga/mind-mem — an auditable, contradiction-safe memory layer for coding agents MCP-compatible . 证据：`docs/hf-mind-mem-4b-v2-README.md`\n- **Installation guide — every step + every option**（documentation）：Installation guide — every step + every option 证据：`docs/install-guide.md`\n- **Integrations**（documentation）：Honest positioning. Every claim below is verifiable from the source tree, the public PyPI artifact, or a published benchmark file in benchmarks/ . Nothing here is a customer-relationship claim about any AI vendor — the integrations described are software-level the named tool talks to MIND-Mem via the Model Context Protocol , not commercial. 证据：`docs/integrations.md`\n- **LoCoMo v3.4.0 conv-0 results 2026-04-22**（documentation）：LoCoMo v3.4.0 conv-0 results 2026-04-22 证据：`docs/locomo-v3.4-conv0-results.md`\n- **maintenance/ namespaces**（documentation）：v3.2.0 splits maintenance/ into two sibling subdirectories so the apply-engine's snapshot scope can categorise each file correctly. 证据：`docs/maintenance-namespaces.md`\n- **MCP Integration Guide**（documentation）：MIND-Mem exposes 81 MCP tools for integration with AI coding assistants like Claude Code, Codex, Gemini, Cursor, Windsurf, Continue, Cline, Roo, and Zed v3.1.0+ . 证据：`docs/mcp-integration.md`\n- **MCP Tool Examples**（documentation）：Practical examples for each MIND-Mem MCP tool. 证据：`docs/mcp-tool-examples.md`\n- **MIC/MAP — MIND IR Graph Serialization**（documentation）：MIC/MAP — MIND IR Graph Serialization 证据：`docs/mic-map.md`\n- **Migration Guide**（documentation）：MIND-Mem is the successor to mem-os. This guide covers the migration path. 证据：`docs/migration-guide.md`\n- **Migration Guide: mem-os to MIND-Mem**（documentation）：Migration Guide: mem-os to MIND-Mem 证据：`docs/migration.md`\n- **MIND Kernels**（documentation）：MIND kernels are configuration files .mind extension that customize scoring and retrieval behavior. They live in the .mind/ subdirectory of the workspace. 证据：`docs/mind-kernels.md`\n- **Setting up the mind-mem-4b model**（documentation）：star-ga/mind-mem-4b is the fully trained mind-mem:4b model — all ~4.2B parameters trained on the MIND-Mem domain not a LoRA adapter . The current revision v4 weights, shipped alongside the v4.0.0 library release on 2026-05-11 knows the 84 MCP tools incl. compile truth walkthrough , recall with persona , pipeline status , reindex dirty , validate block , block lineage , add block edge , MIC/MAP serialization, governance hooks , block schemas including the v3.9 TransformHash field and v3.12 block staleness table, governance workflows, the v3.11 typed lineage edges cites/implements/refines/contradicts/cooccurrence , the v3.12 strict quality gate + lineage→staleness BFS propagator, and all the… 证据：`docs/mind-mem-4b-setup.md`\n- **mind-mem-4b training runbook post-v3.10.2 lessons**（documentation）：mind-mem-4b training runbook post-v3.10.2 lessons 证据：`docs/mind-mem-4b-training-runbook.md`\n- **mind-mem-4b v2 training recipe — Runpod H200**（documentation）：mind-mem-4b v2 training recipe — Runpod H200 证据：`docs/mind-mem-4b-v2-training-recipe.md`\n- **Observer-Dependent Cognition in MIND-Mem**（documentation）：Observer-Dependent Cognition in MIND-Mem 证据：`docs/odc-retrieval.md`\n- **Performance Tuning**（documentation）：Guide to optimizing MIND-Mem for large workspaces and high-throughput usage. 证据：`docs/performance-tuning.md`\n- **MIND-Mem Library Protection**（documentation）：Defence-in-depth layers for the shipped mind-mem PyPI wheel. Protection here means tamper-detection + provenance , not unbreakable DRM — Python semantics make that impossible without native compilation — but it raises the cost of silent modifications to the memory + governance layer that downstream agents trust. 证据：`docs/protection.md`\n- **Quality Gate — Operator Runbook**（documentation）：The quality gate is a deterministic pre-write filter that inspects every propose update statement before it lands in SIGNALS.md . It runs zero external dependencies no network, no LLM and completes in microseconds. 证据：`docs/quality-gate.md`\n- **MIND-Mem Quickstart**（documentation）：Get MIND-Mem running in under 2 minutes. 证据：`docs/quickstart.md`\n- **Behavioral Audit — Operator Runbook**（documentation）：Behavioral Audit — Operator Runbook 证据：`docs/red-team-audit.md`\n- **MIND-Mem REST API**（documentation）：The REST API mirrors the MCP tool surface over HTTP/JSON. Start it with: 证据：`docs/rest-api.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **MIND-Mem简介**：importance `high`\n - source_paths: README.md, SPEC.md\n- **核心功能一览**：importance `high`\n - source_paths: mind/recall.mind, mind/governance.mind, mind/mic_map_quickstart.py\n- **系统架构**：importance `high`\n - source_paths: docs/architecture.md, ANATOMY.md, src/mind_mem/__init__.py\n- **数据流与处理管道**：importance `high`\n - source_paths: src/mind_mem/capture.py, src/mind_mem/apply_engine.py, src/mind_mem/ingestion_pipeline.py, src/mind_mem/recall.py\n- **存储后端**：importance `high`\n - source_paths: src/mind_mem/block_store.py, src/mind_mem/block_store_postgres.py, docs/storage-backends.md, docs/block-format.md\n- **检索管道**：importance `high`\n - source_paths: src/mind_mem/hybrid_recall.py, src/mind_mem/query_expansion.py, src/mind_mem/recall_vector.py, src/mind_mem/rerank_ensemble.py, mind/bm25.mind\n- **MCP服务器**：importance `high`\n - source_paths: src/mind_mem/mcp/server.py, src/mind_mem/mcp_entry.py, mcp_server.py, docs/mcp-integration.md\n- **MCP工具集**：importance `high`\n - source_paths: src/mind_mem/mcp/tools/memory_ops.py, src/mind_mem/mcp/tools/recall.py, src/mind_mem/mcp/tools/governance.py, src/mind_mem/mcp/tools/graph.py, docs/mcp-tool-examples.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `e26fae773e925f06c4dca2651333860ddf7d482e`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docs/workspace-structure.md`, `docs/hf-mind-mem-4b-v2-README.md`, `docs/changelog-format.md`, `docs/security-audit-sow.md`, `docs/migration-guide.md`, `docs/SECURITY_AUDIT_SELF_2026_04.md`, `docs/integrations.md`, `docs/architecture.md`, `docs/security-model.md`, `docs/mind-kernels.md`, `docs/mind-mem-4b-training-runbook.md`, `docs/protection.md`, `docs/review-tests-v3.2.0.md`, `docs/scoring.md`, `docs/v3.3.0-release-notes.md`, `docs/review-database-v3.2.0.md`, `docs/glossary.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_366d8c18c1aa45ffb07174af516285d4 | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：star-ga/mind-mem\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code, cursor\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/star-ga/mind-mem 项目说明书\n\n生成时间：2026-05-16 01:43:31 UTC\n\n## 目录\n\n- [MIND-Mem简介](#page-introduction)\n- [核心功能一览](#page-features)\n- [系统架构](#page-architecture)\n- [数据流与处理管道](#page-data-flow)\n- [存储后端](#page-storage)\n- [检索管道](#page-recall)\n- [MCP服务器](#page-mcp-server)\n- [MCP工具集](#page-mcp-tools)\n- [治理与矛盾检测](#page-governance)\n- [质量保障与验证](#page-quality)\n\n\n\n## MIND-Mem简介\n\n### 相关页面\n\n相关主题：[核心功能一览](#page-features), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/star-ga/mind-mem/blob/main/README.md)\n- [SPEC.md](https://github.com/star-ga/mind-mem/blob/main/SPEC.md)\n- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n \n\n# MIND-Mem简介\n\n## 项目概述\n\nMIND-Mem 是一个用于 AI 代理的**结构化记忆与推理框架**，它为多代理协作场景提供持久化记忆存储、检索和治理能力。该项目基于文件系统存储，采用 Markdown 格式管理记忆块，并通过 MCP（Model Context Protocol）协议对外提供服务接口。\n\nMIND-Mem 的核心设计理念是：**记忆永不直接修改，只能通过治理流程变更**。这一 invariant 确保了记忆系统的完整性和可审计性。\n\n资料来源：[SPEC.md](https://github.com/star-ga/mind-mem/blob/main/SPEC.md)\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph 用户层\n CLI[CLI工具
mm命令]\n MCP[MCP客户端]\n Web[Web控制台]\n API[REST API]\n end\n \n subgraph MCP服务层\n MS[MCP Server
mcp_server.py]\n KERNEL[Kernel工具]\n GOVERNANCE[治理工具]\n AUDIT[审计工具]\n MEMORY[内存操作工具]\n end\n \n subgraph 核心存储层\n FTS[FTS5全文索引]\n BLOCKS[记忆块文件
.md格式]\n CT[Compiled Truth
编译真相页]\n LEDGER[多代理事实账本]\n end\n \n CLI --> MS\n MCP --> MS\n Web --> API\n API --> MS\n MS --> FTS\n MS --> BLOCKS\n MS --> CT\n MS --> LEDGER\n```\n\n### 核心组件\n\n| 组件名称 | 文件路径 | 功能描述 |\n|---------|---------|---------|\n| MCP Server | `src/mind_mem/mcp_server.py` | MCP协议服务核心，处理所有MCP工具调用 |\n| CLI工具 | `src/mind_mem/mm_cli.py` | 统一命令行接口，支持recall、context、inject等命令 |\n| 记忆块解析器 | `src/mind_mem/block_parser.py` | 解析和管理.md格式的记忆块文件 |\n| 编译真相 | `src/mind_mem/compiled_truth.py` | 实体真相页面的聚合和编译 |\n| 质量门 | `src/mind_mem/quality_gate.py` | 预存储过滤器，验证记忆块质量 |\n| Web控制台 | `web/` | 基于Next.js的可视化界面 |\n\n资料来源：[mm_cli.py:1-20](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n## 核心功能\n\n### 2.1 记忆检索与上下文管理\n\nMIND-Mem 提供多种检索方式满足不同场景需求：\n\n#### CLI命令接口\n\n```bash\nmm recall \"\" # BM25语义搜索\nmm context \"\" # 生成token预算受限的片段\nmm inject --agent \"\" # 为特定代理渲染片段\nmm vault scan # 列出解析的vault块\nmm status # 工作区摘要\n```\n\n资料来源：[mm_cli.py:1-20](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n#### MCP资源接口\n\n| 资源标识 | 功能 |\n|---------|------|\n| `mind-mem://decisions` | 活动决策列表（DECISIONS.md） |\n| `mind-mem://tasks` | 所有任务（TASKS.md） |\n| `mind-mem://entities/{type}` | 项目、人员、工具、事件实体 |\n| `mind-mem://signals` | 自动捕获的信号 |\n| `mind-mem://contradictions` | 检测到的矛盾 |\n| `mind-mem://health` | 工作区健康摘要 |\n| `mind-mem://recall/{query}` | BM25召回搜索 |\n| `mind-mem://ledger` | 共享多代理事实账本 |\n\n资料来源：[mcp/resources.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n\n### 2.2 编译真相系统\n\n编译真相（Compiled Truth）是 MIND-Mem 的核心知识沉淀机制：\n\n```mermaid\ngraph LR\n subgraph 证据收集\n MD1[memory/xxx.md]\n MD2[memory/yyy.md]\n MD3[DECISIONS.md]\n end\n \n subgraph 处理流程\n SC[句子提取]\n NORM[规范化]\n COUNT[出现计数]\n end\n \n subgraph 真相页生成\n CT[Compiled Truth Page
compiled/xxx.md]\n ENTRY[Evidence Entry
证据条目]\n end\n \n MD1 --> SC\n MD2 --> SC\n MD3 --> SC\n SC --> NORM\n NORM --> COUNT\n COUNT -->|min_mentions≥3| CT\n CT --> ENTRY\n```\n\n**核心特性：**\n- 自动从多个 Markdown 文件中提取和聚合事实\n- 支持证据条目的时间戳、来源和置信度\n- 提供 `recompilation` 重新编译功能\n- 支持证据条目的 `superseded` 标记\n\n资料来源：[compiled_truth.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n### 2.3 治理与审计\n\nMIND-Mem 遵循\"**记忆永不直接修改，只通过治理变更**\"的原则：\n\n#### 治理工具集\n\n| 工具名称 | 功能 |\n|---------|------|\n| `propose_update` | 将新决策/任务暂存为 SIGNAL |\n| `approve_apply` | 应用暂存的提案（默认dry-run） |\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理） |\n| `list_contradictions` | 枚举检测到的矛盾 |\n| `memory_evolution` | 获取记忆块的A-MEM元数据 |\n\n资料来源：[mcp/tools/governance.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n\n#### 审计工具集\n\n| 工具名称 | 功能 |\n|---------|------|\n| `verify_merkle` | 验证块的Merkle包含证明 |\n| `verify_chain` | 验证SHA3-512哈希链完整性 |\n| `list_evidence` | 枚举治理证据对象 |\n| `mind_mem_verify` | 暴露独立验证CLI |\n\n资料来源：[mcp/tools/audit.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)\n\n### 2.4 质量门控\n\n质量门（Quality Gate）是预存储过滤器，确保进入系统的记忆块符合标准：\n\n```mermaid\ngraph TD\n INPUT[候选记忆块] --> QG{质量门}\n QG --> E1{空块?}\n QG --> E2{过短?}\n QG --> E3{过大?}\n QG --> E4{UTF-8错误?}\n QG --> E5{仅停用词?}\n QG --> E6{近似重复?}\n QG --> E7{注入标记?}\n QG --> OK[通过]\n E1 -->|是| LOG1[日志记录]\n E2 -->|是| LOG2[日志记录]\n E3 -->|是| LOG3[日志记录]\n E4 -->|是| LOG4[日志记录]\n E5 -->|是| LOG5[日志记录]\n E6 -->|是| LOG6[日志记录]\n E7 -->|是| LOG7[日志记录]\n LOG1 --> OK\n LOG2 --> OK\n LOG3 --> OK\n LOG4 --> OK\n LOG5 --> OK\n LOG6 --> OK\n LOG7 --> OK\n```\n\n**八条质量规则：**\n\n| 规则ID | 规则名称 | 判定条件 | 默认行为 |\n|-------|---------|---------|---------|\n| 1 | `empty` | 块内容为空或仅空白 | 接受+日志 |\n| 2 | `too_short` | 少于32个非空白字符 | 接受+日志 |\n| 3 | `oversize` | 超过64KB UTF-8字节 | 拒绝 |\n| 4 | `malformed_utf8` | 包含孤立代理符 | 拒绝 |\n| 5 | `stopwords_only` | 所有token都是停用词 | 接受+日志 |\n| 6 | `near_duplicate` | 与24h内块相似度≥0.97 | 接受+日志 |\n| 7 | `injection_marker` | 匹配已知注入模式 | 拒绝 |\n| 8 | `ok` | 无规则触发 | 接受 |\n\n支持 `strict=True` 模式，所有规则均变为硬性拒绝。\n\n资料来源：[quality_gate.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n\n## MCP工具分类\n\n### 3.1 Kernel工具\n\n提供对 `.mind` 内核配置文件的读写访问：\n\n- `list_mind_kernels` — 列出可用内核\n- `get_mind_kernel` — 获取特定内核配置\n- `compiled_truth_load` — 加载真相页\n- `compiled_truth_add_evidence` — 添加证据\n- `compiled_truth_contradictions` — 检测矛盾\n\n资料来源：[mcp/tools/kernels.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n\n### 3.2 内存操作工具\n\n工作区生命周期和内省接口：\n\n- `index_stats` / `reindex` — FTS5索引状态和重建\n- `delete_memory_item` — 原子性记忆块删除\n- `export_memory` — JSONL格式导出\n- `get_block` / `memory_health` — 块查询和健康仪表盘\n- `compact` / `stale_blocks` — 压缩和陈旧块管理\n\n资料来源：[mcp/tools/memory_ops.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)\n\n### 3.3 架构思维工具\n\n整合 `arch-mind` 二进制工具作为 MCP 工具：\n\n- `arch_baseline` — 初始化基准\n- `arch_delta` — 计算delta分数\n- `arch_history` — 列出历史事件\n- `arch_check_rules` — 应用规则检查\n- `arch_session_start` / `arch_session_end` — 会话管理\n- `arch_metric_explain` — 指标分解\n\n资料来源：[mcp/tools/arch_mind.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)\n\n## 工作区结构\n\n```\n{workspace}/\n├── DECISIONS.md # 活动决策\n├── TASKS.md # 任务列表\n├── SIGNALS.md # 待审查信号\n├── memory/ # 记忆块存储\n│ ├── *.md\n│ └── ...\n├── entities/\n│ └── compiled/ # 编译真相页\n│ └── *.md\n├── .mind/ # 内核配置\n│ └── *.mind\n└── index.db # FTS5全文索引\n```\n\n## Web控制台\n\n基于 Next.js 的可视化界面，提供三种视图：\n\n```mermaid\ngraph TD\n subgraph Web控制台\n SUBMIT[查询提交]\n API[REST API调用]\n subgraph 三面板展示\n GRAPH[力导向图
GraphView]\n TIMELINE[时间轴
TimelineView]\n FACTS[事实列表
FactList]\n end\n end\n \n SUBMIT --> API\n API --> GRAPH\n API --> TIMELINE\n API --> FACTS\n```\n\n**启动方式：**\n```bash\ncd web\npnpm install\npnpm dev # → http://localhost:3000\n```\n\n资料来源：[web/README.md:1-40](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n\n## 快速开始\n\n### 安装\n\n```bash\npip install -e .\n```\n\n### CLI基本用法\n\n```bash\n# 初始化工作区\nexport MIND_MEM_WORKSPACE=/path/to/workspace\n\n# 搜索记忆\nmm recall \"PostgreSQL决策历史\"\n\n# 生成上下文\nmm context \"最近的架构变更\"\n\n# 注入特定代理上下文\nmm inject --agent claude \"当前项目技术栈\"\n```\n\n### API使用\n\n```python\nfrom mind_mem import recall\n\nresults = recall(\"/path/to/workspace\", \"query\", limit=10)\n```\n\n## v4.0 预览\n\nMIND-Mem v4.0 正在开发中，带来以下新特性（当前默认关闭，需通过 `mind-mem.json` 开启）：\n\n| 功能组 | 特性 | 状态 |\n|-------|------|------|\n| A. 认知/模型层 | 分层记忆、认知内核、惊喜权重检索 | 规划中 |\n| B. 知识图谱 | 实体/概念提取、长上下文召回、LLM融合、流式检索、对话层 | 规划中 |\n| C. 知识治理 | 空闲后台摄入、AI lint、矛盾状态机、自愈索引 | 规划中 |\n\n资料来源：[v4/__init__.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n\n## 总结\n\nMIND-Mem 是一个设计严谨的 AI 记忆框架，通过以下核心机制保障系统的可靠性和可追溯性：\n\n1. **文件系统优先** — Markdown格式存储，便于版本控制和人类阅读\n2. **治理驱动变更** — 记忆只能通过正式提案→审批流程修改\n3. **多协议支持** — 同时提供CLI、MCP和REST API接口\n4. **质量门控** — 预存储过滤器确保数据质量\n5. **可审计性** — Merkle证明和哈希链验证数据完整性\n\n---\n\n\n\n## 核心功能一览\n\n### 相关页面\n\n相关主题：[MIND-Mem简介](#page-introduction), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)\n- [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)\n- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)\n- [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)\n- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n- [src/mind_mem/model_provenance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)\n \n\n# 核心功能一览\n\nmind-mem 是一个多智能体记忆管理系统，提供了完整的信息召回、治理、压缩和长期记忆维护能力。本页概述系统的核心功能模块，包括 MCP 工具、CLI 接口、编译事实系统和 v4.0 特性预览。\n\n## 1. 系统架构总览\n\nmind-mem 采用分层架构设计，核心组件包括：\n\n```mermaid\ngraph TD\n subgraph \"接口层\"\n CLI[CLI 命令行工具
mm]\n MCP[MCP 服务器
Model Context Protocol]\n REST[REST API
v3.2.0+]\n end\n \n subgraph \"功能域\"\n RECALL[召回 Recall]\n GOV[治理 Governance]\n CONSOL[记忆整合 Consolidation]\n MEMOPS[记忆操作 Memory Ops]\n end\n \n subgraph \"核心引擎\"\n FTS[FTS5 全文索引]\n BLOCK[Block Parser]\n COMPILED[Compiled Truth]\n COGNITIVE[认知遗忘 Cognitive Forget]\n end\n \n subgraph \"存储层\"\n WORKSPACE[Workspace 目录]\n MIND[MIND 内核配置]\n DB[(SQLite FTS5)]\n end\n \n CLI --> RECALL\n MCP --> RECALL\n MCP --> GOV\n MCP --> CONSOL\n MCP --> MEMOPS\n \n RECALL --> FTS\n GOV --> BLOCK\n CONSOL --> COGNITIVE\n \n FTS --> DB\n BLOCK --> WORKSPACE\n COMPILED --> WORKSPACE\n COGNITIVE --> WORKSPACE\n```\n\n## 2. MCP 工具集\n\nMCP（Model Context Protocol）服务器提供标准化工具接口，支持 Claude Code、Codex CLI、Cursor、Windsurf 等 AI 客户端直接调用记忆功能。工具按功能域分为以下类别：\n\n### 2.1 KERNELS 域 — MIND 内核配置\n\n负责管理和配置召回、排序和管道参数的内核文件访问。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `list_mind_kernels` | 列出所有可用的 .mind 内核配置文件 | [kernels.py:28-48](src/mind_mem/mcp/tools/kernels.py) |\n| `get_mind_kernel` | 获取指定内核配置详情 | [kernels.py:28-48](src/mind_mem/mcp/tools/kernels.py) |\n\n内核配置控制项包括：\n- 召回权重调优（recall tuning）\n- 重排序参数（reranking）\n- RM3 扩展配置\n- 管道级联参数\n\n### 2.2 GOVERNANCE 域 — 治理与生命周期\n\n治理域是\"记忆永不直接修改\"原则的核心实现，所有变更必须经过治理流程。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `propose_update` | 提案新决策或任务，写入 SIGNALS.md 待人工审核 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `approve_apply` | 应用已批准提案（默认干运行模式） | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `rollback_proposal` | 从预应用快照恢复工作区 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `scan` | 完整性扫描（矛盾检测/漂移检测/待处理项） | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `list_contradictions` | 列出检测到的矛盾项 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n| `memory_evolution` | 获取区块的 A-MEM 元数据 | [governance.py:39-70](src/mind_mem/mcp/tools/governance.py) |\n\n**治理工作流：**\n\n```mermaid\ngraph LR\n A[propose_update
提案阶段] --> B{SIGNALS.md}\n B --> C[人工审核]\n C --> D{approve_apply
批准应用}\n D -->|干运行 OK| E[正式应用]\n D -->|发现问题| F[rollback_proposal
回滚]\n E --> G[区块更新]\n F --> H[快照恢复]\n```\n\n### 2.3 CONSOLIDATION 域 — 记忆整合\n\n\"记忆随时间沉淀\"表面，实现认知遗忘和自动整合机制。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `plan_consolidation` | 认知遗忘周期干运行 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n| `propagate_staleness` | 跨引用扩散陈旧度分数 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n| `project_profile` | 会话启动情报摘要 | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n| `dream_cycle` | 自主记忆丰富（实体发现/断裂引用扫描/整合候选/自动修复） | [consolidation.py:26-55](src/mind_mem/mcp/tools/consolidation.py) |\n\n### 2.4 MEMORY_OPS 域 — 记忆操作\n\n工作区生命周期和内省操作，处理索引、删除、导出等管理任务。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `index_stats` | FTS5 索引状态查询 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `reindex` | 重建全文索引 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `delete_memory_item` | 原子化管理员范围区块移除 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `export_memory` | JSONL 格式完整导出 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `get_block` | 单区块查询 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `memory_health` | 健康状态仪表盘 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `compact` | 存储压缩 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n| `stale_blocks` | 陈旧区块标记管理 | [memory_ops.py:28-60](src/mind_mem/mcp/tools/memory_ops.py) |\n\n### 2.5 BENCHMARK 域 — 基准测试\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `governance_health_bench` | 矛盾检测/审计完整性/漂移/可扩展性探测 | [benchmark.py:24-50](src/mind_mem/mcp/tools/benchmark.py) |\n| `category_summary` | 类别蒸馏器查询 | [benchmark.py:52-75](src/mind_mem/mcp/tools/benchmark.py) |\n\n### 2.6 ARCH_MIND 域 — 架构知识管理\n\n包装 `arch-mind` 二进制工具，提供架构基线、历史记录、规则检查和会话管理。\n\n| 工具名称 | 功能描述 | 资料来源 |\n|---------|---------|----------|\n| `arch_baseline` | 初始化架构基线 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_delta` | 计算当前扫描与基线的差异 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_history` | 列出架构历史事件 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_check_rules` | 应用规则文件检查 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_session_start` | 开启会话证据节点 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_session_end` | 关闭会话并写入增量证据 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n| `arch_metric_explain` | 单指标详细分解 | [arch_mind.py:26-50](src/mind_mem/mcp/tools/arch_mind.py) |\n\n## 3. CLI 命令行工具\n\n`mm` 命令提供 MCP 之外的轻量级接口，适用于非 MCP 智能体。\n\n```bash\nmm recall \"\" # 搜索记忆\nmm context \"\" # 生成预算限制的片段\nmm inject --agent \"\" # 为特定智能体渲染片段\nmm vault scan # 列出解析的 vault 块\nmm vault write --type --body \nmm status # 工作区摘要\nmm trace --live # 实时流式 MCP 调用日志\nmm trace --last 20 --tool xxx # 最近 N 次工具调用\n```\n\n资料来源：[mm_cli.py:1-50](src/mind_mem/mm_cli.py)\n\n## 4. 编译事实系统\n\n编译事实（Compiled Truth）是按实体聚合证据并重新编译权威理解的关键机制。\n\n### 4.1 核心概念\n\n```mermaid\ngraph TD\n subgraph \"来源\"\n SOURCE1[memory/决策A.md]\n SOURCE2[memory/任务B.md]\n SOURCE3[memory/事件C.md]\n end\n \n subgraph \"候选提取\"\n SENTENCE[句子提取
频率≥3]\n CANDIDATE[事实候选]\n end\n \n subgraph \"编译事实页\"\n ENTITY[实体标识]\n EVIDENCE[证据条目列表]\n CANONICAL[权威摘要]\n VERSION[版本号]\n LAST_COMPILED[最后编译时间]\n end\n \n SOURCE1 --> SENTENCE\n SOURCE2 --> SENTENCE\n SOURCE3 --> SENTENCE\n SENTENCE --> CANDIDATE\n CANDIDATE --> EVIDENCE\n EVIDENCE --> CANONICAL\n CANONICAL --> ENTITY\n```\n\n### 4.2 编译事实数据结构\n\n| 字段 | 类型 | 说明 |\n|-----|------|------|\n| `entity_id` | str | 实体唯一标识 |\n| `evidence_entries` | list | 证据条目列表 |\n| `compiled_summary` | str | 权威摘要文本 |\n| `version` | int | 编译版本号 |\n| `last_compiled` | datetime | 最后编译时间 |\n| `superseded_entries` | list | 已废弃条目 |\n\n### 4.3 关键函数\n\n| 函数 | 功能 | 资料来源 |\n|-----|------|----------|\n| `extract_compiled_truth_candidates` | 从 memory/ 目录提取候选事实 | [compiled_truth.py:30-80](src/mind_mem/compiled_truth.py) |\n| `supersede_evidence_entry` | 标记证据条目为已废弃 | [compiled_truth.py:150-175](src/mind_mem/compiled_truth.py) |\n| `recompile_truth` | 从非废弃证据重新生成摘要 | [compiled_truth.py:180-200](src/mind_mem/compiled_truth.py) |\n\n## 5. MCP 资源声明\n\n通过 `@mcp.resource` 暴露只读视图，提供工作区信息的统一访问：\n\n| 资源 URI | 内容描述 |\n|---------|----------|\n| `mind-mem://decisions` | 活动决策（DECISIONS.md） |\n| `mind-mem://tasks` | 所有任务（TASKS.md） |\n| `mind-mem://entities/{type}` | 项目/人员/工具/事件实体 |\n| `mind-mem://signals` | 自动捕获信号 |\n| `mind-mem://contradictions` | 检测到的矛盾 |\n| `mind-mem://health` | 工作区健康摘要 |\n| `mind-mem://recall/{query}` | BM25 召回搜索 |\n| `mind-mem://ledger` | 共享多智能体事实账本 |\n\n资料来源：[resources.py:1-50](src/mind_mem/mcp/resources.py)\n\n## 6. 模型溯源系统\n\n`model_provenance.py` 定义了发布商注册表和来源发现机制：\n\n| 发布商 | Slugs | 描述 |\n|-------|-------|------|\n| Mistral | `mistralai` | Mistral / Mixtral / Codestral 家族 |\n| Google Gemma | `google` | Gemma / Gemma-2 / PaLM 家族 |\n| IBM Granite | `ibm-granite`, `ibm` | Granite-3 / Granite-Code 家族 |\n| OpenAI | `openai` | Whisper / CLIP 及开源模型 |\n| Anthropic | `anthropic` | Anthropic 发布产物 |\n| DeepSeek | `deepseek-ai` | DeepSeek-V2 / V3 / R1 家族 |\n| Microsoft Phi | `microsoft` | Phi-2 / Phi-3 / Phi-4 家族 |\n| TII Falcon | `tiiuae` | Falcon-7B / 40B / 180B 家族 |\n\n资料来源：[model_provenance.py:1-80](src/mind_mem/model_provenance.py)\n\n## 7. v4.0 功能预览\n\nv4.0 采用显式功能开关设计，默认关闭以保持 v3.x 行为兼容。\n\n```mermaid\ngraph TD\n subgraph \"v4.0 功能门\"\n CONFIG[mind-mem.json
v4 feature flag]\n end\n \n subgraph \"A. 认知/模型层\"\n TIER[tier-aware block schema]\n COG_KRN[Cognitive Mind Kernel API]\n SURPRISE[surprise-weighted retrieval]\n end\n \n subgraph \"B. 知识图谱\"\n KINDS[entity/concept kinds]\n LONG_CTX[long-context recall]\n FUSION[LLM-driven fusion]\n STREAM[streaming recall]\n CHAT[conversational chat]\n PROMPT_SCHEMA[prompt schema]\n end\n \n subgraph \"C. 治理/UX\"\n IDLE[idle-only ingest]\n LINT[AI lint + auto-fix]\n CONTRAD[contradiction state machine]\n SELF_HEAL[self-healing index]\n end\n \n CONFIG --> TIER\n CONFIG --> KINDS\n CONFIG --> IDLE\n```\n\n资料来源：[v4/__init__.py:1-40](src/mind_mem/v4/__init__.py)\n\n## 8. 智能体集成\n\nmind-mem 支持多种 AI 编码客户端集成，通过 `hook_installer.py` 管理：\n\n| 智能体 | 配置格式 | 说明 |\n|-------|---------|------|\n| Claude | JSON | Anthropic Claude 家族 |\n| Claude Code | JSON block | 支持 MCP 配置 |\n| Codex CLI | JSON block | OpenAI Codex |\n| Cursor | JSON block | Cursor IDE |\n| Windsurf | mcp-json-windsurf | Codeium Windsurf |\n| aider | YAML block | aider CLI (paul-gauthier) |\n| OpenClaw | JSON hooks | 开源 AI 助手 |\n| NanoClaw | JSON hooks | 紧凑型 Claw 变体 |\n| NemoClaw | JSON hooks | 记忆聚焦型 Claw |\n\nMCP 服务器路径解析优先级：\n1. `MIND_MEM_MCP_SERVER` 环境变量\n2. `/../mcp_server.py`（源码检出布局）\n3. `/mcp_server.py`（打包安装布局）\n\n资料来源：[hook_installer.py:1-50](src/mind_mem/hook_installer.py)\n\n## 9. 观察压缩\n\n`observation_compress.py` 实现记忆压缩专家系统，支持多种查询类型：\n\n| 类型 | 用途 |\n|-----|------|\n| `direct` | 直接事实查询 |\n| `comparative` | 对比分析 |\n| `denial` | 否定证据识别 |\n| `temporal` | 时序/因果关系 |\n| `multi-hop` | 多跳推理连接 |\n\n资料来源：[observation_compress.py:1-60](src/mind_mem/observation_compress.py)\n\n## 10. 总结\n\nmind-mem 的核心功能可归纳为以下维度：\n\n| 维度 | 核心能力 |\n|-----|---------|\n| **召回** | BM25/混合检索、FTS5 全文索引、长上下文模式 |\n| **治理** | 提案-审批-回滚流程、矛盾检测、快照恢复 |\n| **整合** | 认知遗忘周期、陈旧度扩散、自主丰富 |\n| **操作** | 索引管理、原子删除、JSONL 导出、健康监控 |\n| **事实** | 编译事实页、证据聚合、版本化管理 |\n| **可观测性** | 结构化日志、MCP 调用追踪、trace 工具 |\n\n所有核心功能均通过 MCP 工具接口或 CLI 提供，确保与主流 AI 编码客户端的广泛兼容性。\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[MIND-Mem简介](#page-introduction), [数据流与处理管道](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-gag/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)\n- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [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)\n- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)\n- [src/mind_mem/protection.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/protection.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n \n\n# 系统架构\n\nmind-mem 是一个面向多智能体协作的持久化记忆系统，旨在为 AI 编码助手提供持久化上下文记忆能力。该系统通过 Model Context Protocol (MCP) 向各类 AI 客户端暴露统一的记忆接口，支持记忆检索、上下文注入、治理决策追踪和完整性审计等核心功能。\n\n## 1. 整体架构概览\n\nmind-mem 采用分层架构设计，核心由 MCP 服务层、记忆操作层、数据持久化层和治理审计层组成。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n CLAUDE[\"Claude Code\"]\n COPILOT[\"GitHub Copilot\"]\n CODY[\"Sourcegraph Cody\"]\n QODO[\"Qodo Gen\"]\n end\n \n subgraph 接口层\n MCP[\"MCP Server
(mcp_server.py)\"]\n CLI[\"CLI 工具
(mm)\"]\n WEB[\"Web 控制台
(Next.js)\"]\n end\n \n subgraph 服务层\n RECALL[\"Recall API\"]\n GOVERNANCE[\"Governance Tools\"]\n AUDIT[\"Audit Tools\"]\n CONSOLIDATION[\"Consolidation Tools\"]\n KERNELS[\"Mind Kernel Tools\"]\n end\n \n subgraph 数据层\n FTS[\"FTS5 全文索引\"]\n HASH[\"Hash Chain v2\"]\n EVIDENCE[\"Evidence Chain\"]\n TRUTH[\"Compiled Truth\"]\n end\n \n subgraph 持久化层\n MARKDOWN[\"Markdown 记忆文件\"]\n SQLITE[\"SQLite 数据库\"]\n CORPUS[\"语料库目录\"]\n end\n \n CLIENTS[AI 客户端] --> MCP\n CLIENTS --> CLI\n MCP --> RECALL\n MCP --> GOVERNANCE\n MCP --> AUDIT\n CLI --> RECALL\n RECALL --> FTS\n FTS --> MARKDOWN\n GOVERNANCE --> HASH\n GOVERNANCE --> EVIDENCE\n AUDIT --> TRUTH\n```\n\n## 2. MCP 服务架构\n\nMCP (Model Context Protocol) 是 mind-mem 的核心对外接口协议。系统将 MCP 服务分解为多个工具域，每个域对应特定的功能模块。\n\n### 2.1 工具域划分\n\n| 工具域 | 文件路径 | 核心工具 |\n|--------|----------|----------|\n| governance | `mcp/tools/governance.py` | propose_update, approve_apply, rollback_proposal, scan |\n| audit | `mcp/tools/audit.py` | verify_merkle, verify_chain, list_evidence, mind_mem_verify |\n| kernels | `mcp/tools/kernels.py` | list_mind_kernels, get_mind_kernel, compiled_truth_* |\n| memory_ops | `mcp/tools/memory_ops.py` | index_stats, reindex, delete_memory_item, export_memory |\n| consolidation | `mcp/tools/consolidation.py` | plan_consolidation, propagate_staleness, dream_cycle |\n| benchmark | `mcp/tools/benchmark.py` | governance_health_bench, category_summary |\n| arch_mind | `mcp/tools/arch_mind.py` | arch_baseline, arch_delta, arch_session_* |\n\n### 2.2 MCP 资源声明\n\nMCP 服务还暴露一组只读资源，提供对工作区记忆的查询视图：\n\n```mermaid\ngraph LR\n R1[\"mind-mem://decisions
决策记录\"]\n R2[\"mind-mem://tasks
任务列表\"]\n R3[\"mind-mem://entities/{type}
实体查询\"]\n R4[\"mind-mem://signals
信号数据\"]\n R5[\"mind-mem://contradictions
矛盾检测\"]\n R6[\"mind-mem://health
健康状态\"]\n R7[\"mind-mem://recall/{query}
BM25 检索\"]\n R8[\"mind-mem://ledger
多智能体账本\"]\n```\n\n资料来源：[src/mind_mem/mcp/resources.py:1-30]()\n\n### 2.3 MCP 服务启动流程\n\n```python\n# 资料来源：src/mind_mem/hook_installer.py\ndef mcp_server_spec(workspace: str) -> dict[str, Any]:\n \"\"\"生成 MCP 服务调用规范\"\"\"\n return {\n \"command\": _sys.executable or \"python3\",\n \"args\": [_mcp_server_path()],\n \"env\": {\"MIND_MEM_WORKSPACE\": workspace},\n }\n```\n\nMCP 服务器路径按以下优先级解析：\n\n1. `MIND_MEM_MCP_SERVER` 环境变量（显式覆盖）\n2. `/../mcp_server.py`（源码 checkout 布局）\n3. `/mcp_server.py`（打包安装布局）\n\n资料来源：[src/mind_mem/hook_installer.py]()\n\n## 3. CLI 工具架构\n\n`mm` 是面向非 MCP 智能体的统一 CLI 工具，提供命令行记忆操作能力。\n\n### 3.1 CLI 子命令\n\n| 子命令 | 功能描述 |\n|--------|----------|\n| `mm recall \"\"` | BM25 记忆检索 |\n| `mm context \"\"` | 生成符 合 token 预算的上下文片段 |\n| `mm inject --agent \"\"` | 为指定智能体渲染记忆片段 |\n| `mm vault scan ` | 列出解析的 vault 块（JSON 格式）|\n| `mm vault write ` | 写入 vault 记忆块 |\n| `mm status` | 工作区状态摘要 |\n\n资料来源：[src/mind_mem/mm_cli.py:1-25]()\n\n### 3.2 工作区解析\n\n```python\ndef _workspace() -> str:\n ws = os.environ.get(\"MIND_MEM_WORKSPACE\", \"\").strip()\n if not ws:\n ws = os.getcwd()\n return os.path.realpath(ws)\n```\n\n工作区路径通过 `MIND_MEM_WORKSPACE` 环境变量或当前工作目录确定。\n\n## 4. 记忆检索系统\n\n### 4.1 Recall API\n\nRecall 是核心检索引擎，支持 BM25 全文搜索和上下文感知记忆提取。\n\n```mermaid\ngraph TD\n Q[\"查询输入\"] --> PARSE[\"查询解析\"]\n PARSE --> FTS[\"FTS5 索引查询\"]\n FTS --> RERANK[\"重排序\"]\n RERANK --> PACK[\"预算打包
(pack_to_budget)\"]\n PACK --> RESULT[\"记忆片段\"]\n \n subgraph 记忆来源\n MEMORY[\"memory/ 目录\"]\n TASKS[\"TASKS.md\"]\n DECISIONS[\"DECISIONS.md\"]\n end\n \n FTS --> MEMORY\n FTS --> TASKS\n FTS --> DECISIONS\n```\n\n### 4.2 记忆类型映射\n\n记忆文件使用特定前缀标识类型：\n\n| 前缀 | 类型 | 说明 |\n|------|------|------|\n| `[[` | Obsidian 风格链接 | 跨块引用 |\n| `TASK` | 任务块 | 任务追踪 |\n| `DECISION` | 决策块 | 架构决策记录 |\n| `SIGNAL` | 信号块 | 待审批提案 |\n\n## 5. 治理与决策系统\n\n### 5.1 治理原则\n\nmind-mem 遵循\"记忆仅通过治理修改\"的不变性原则。所有记忆变更必须经过提议、审批、生效的完整治理流程。\n\n```mermaid\nstateDiagram-v2\n [*] --> SIGNAL: propose_update\n SIGNAL --> REVIEW: 提交提案\n REVIEW --> APPROVED: approve_apply\n REVIEW --> REJECTED: 拒绝/超时\n APPROVED --> ACTIVE: 写入记忆\n ACTIVE --> SUPERSEDED: rollback_proposal\n SUPERSEDED --> [*]\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-30]()\n\n### 5.2 治理工具集\n\n| 工具 | 功能 |\n|------|------|\n| `propose_update` | 提议新决策或任务，写入 SIGNALS.md |\n| `approve_apply` | 应用已审批提案（默认 dry-run）|\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理）|\n| `list_contradictions` | 矛盾列表查询 |\n\n## 6. 编译真相系统 (Compiled Truth)\n\n### 6.1 系统设计\n\n编译真相系统通过聚合证据来维护实体的规范理解，支持基于句子级出现频率的事实提取。\n\n```python\n# 资料来源：src/mind_mem/compiled_truth.py\ndef extract_common_facts(workspace: str, min_mentions: int = 3) -> list[dict]:\n \"\"\"从 memory/ 目录提取高频事实\"\"\"\n # 1. 遍历所有 .md 文件\n # 2. 句子级分词\n # 3. 统计归一化后的句子出现次数\n # 4. 返回出现 >= min_mentions 次的事实\n```\n\n### 6.2 真相页结构\n\n每个真相页维护以下数据结构：\n\n| 字段 | 说明 |\n|------|------|\n| `entity_id` | 实体唯一标识 |\n| `evidence_entries` | 证据条目列表 |\n| `compiled_summary` | 编译后的摘要 |\n| `version` | 版本号 |\n| `last_compiled` | 最后编译时间 |\n\n### 6.3 证据管理\n\n```mermaid\ngraph LR\n E1[\"新证据\"] --> VALIDATE[\"验证\"]\n VALIDATE --> ADD[\"添加证据\"]\n ADD --> COMPILE[\"重新编译\"]\n COMPILE --> SUMMARY[\"生成摘要\"]\n \n E2[\"旧证据\"] --> SUPERSEDE[\"标记 superseded\"]\n SUPERSEDE --> COMPILE\n```\n\n## 7. 完整性审计系统\n\n### 7.1 审计层设计\n\n审计系统通过哈希链和默克尔树保证记忆的不可篡改性。\n\n| 组件 | 用途 |\n|------|------|\n| Hash Chain v2 | SHA3-512 追加式账本 |\n| Evidence Chain | 结构化治理证据 |\n| Merkle Tree | 块级包含证明 |\n| Integrity Manifest | 发布完整性清单 |\n\n### 7.2 验证工具\n\n| 工具 | 功能 |\n|------|------|\n| `verify_merkle` | 验证块的默克尔包含证明 |\n| `verify_chain` | 验证哈希链和证据链完整性 |\n| `list_evidence` | 枚举治理证据对象 |\n| `mind_mem_verify` | 独立验证 CLI |\n\n### 7.3 验证退出码\n\n| 退出码 | 含义 |\n|--------|------|\n| 0 | 所有检查通过 |\n| 1 | 通用失败（路径缺失）|\n| 2 | 哈希链完整性违规 |\n| 3 | 规范哈希绑定漂移 |\n| 4 | 证据链完整性违规 |\n| 5 | 默克尔根不匹配 |\n| 6 | 链头/快照锚点不匹配 |\n\n资料来源：[src/mind_mem/verify_cli.py:1-45]()\n\n## 8. 智能体集成系统\n\n### 8.1 支持的智能体\n\n| 智能体 | 配置格式 | 配置路径 | 说明 |\n|--------|----------|----------|------|\n| claude | JSON | `~/.claude/settings.json` | Anthropic Claude Code |\n| copilot | Text Block | `.github/copilot-instructions.md` | GitHub Copilot |\n| cody | JSON | `.cody/config.json` | Sourcegraph Cody |\n| qodo | Text Block | `.codium/ai-rules.md` | Qodo Gen |\n\n资料来源：[src/mind_mem/hook_installer.py]()\n\n### 8.2 集成机制\n\n```mermaid\ngraph TD\n INSTALL[\"hook_installer\"] --> DETECT[\"检测智能体\"]\n DETECT --> SPEC[\"生成 AgentSpec\"]\n SPEC --> WRITE[\"写入配置文件\"]\n WRITE --> PREPEND[\"注入记忆锚点\"]\n \n PREPEND --> QUERY[\"mm inject --agent \"]\n QUERY --> CONTEXT[\"返回记忆上下文\"]\n```\n\n### 8.3 智能体规范定义\n\n```python\n@dataclass(frozen=True)\nclass AgentSpec:\n name: str # 智能体键名\n description: str # 人类可读描述\n config_fmt: str # 配置格式 (json-claude/path-toml/text-block)\n path_tmpl: str # 配置文件路径模板\n content_tmpl: str # 注入内容模板\n always_offer: bool # 是否自动推荐\n detect_paths: tuple # 检测路径\n detect_binaries: tuple # 检测二进制\n```\n\n## 9. 记忆操作工具\n\n### 9.1 索引操作\n\n| 工具 | 功能 |\n|------|------|\n| `index_stats` | 查询 FTS5 索引状态 |\n| `reindex` | 重建全文索引 |\n\n### 9.2 生命周期管理\n\n| 工具 | 功能 |\n|------|------|\n| `delete_memory_item` | 原子性记忆块删除（带追加式恢复日志）|\n| `get_block` | 块内容查询 |\n| `memory_health` | 健康状态仪表盘 |\n| `compact` | 存储压缩 |\n| `stale_blocks` | 陈旧块标记管理 |\n\n### 9.3 导出功能\n\n```python\ndef export_memory(\n max_items: int = 10000,\n include_metadata: bool = True,\n max_size_mb: int = 50\n) -> str:\n \"\"\"导出所有记忆块为 JSONL 格式\"\"\"\n```\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-40]()\n\n## 10. 记忆整合系统\n\n### 10.1 认知遗忘周期\n\n```mermaid\ngraph TD\n START[\"开始整合\"] --> CONFIG[\"ConsolidationConfig\"]\n CONFIG --> SCORE[\"BlockCognition 评分\"]\n SCORE --> THRESHOLD{\"重要度阈值?\"}\n THRESHOLD -->|高| KEEP[\"保留\"]\n THRESHOLD -->|低| STALE[\"标记陈旧\"]\n STALE --> AGE{\"超过归档天数?\"}\n AGE -->|是| ARCHIVE[\"归档\"]\n AGE -->|否| GRACE[\"宽限期\"]\n KEEP --> COMPLETE[\"完成\"]\n ARCHIVE --> COMPLETE\n GRACE --> COMPLETE\n```\n\n### 10.2 整合工具\n\n| 工具 | 功能 |\n|------|------|\n| `plan_consolidation` | 认知遗忘周期预演 |\n| `propagate_staleness` | 陈旧度跨引用扩散 |\n| `project_profile` | 会话启动情报摘要 |\n| `dream_cycle` | 自主记忆丰富化 |\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-30]()\n\n## 11. v4.0 架构演进\n\nv4.0 作为架构演进版本，默认关闭，通过 feature flag 启用。\n\n### 11.1 功能组映射\n\n| 组别 | 功能 | 模块 |\n|------|------|------|\n| A | 认知层/模型层 | tier_memory, cognitive_kernel, surprise_retrieval |\n| B | 知识图谱 | block_kinds, long_context_recall, fusion, streaming_recall, chat, prompt_schema |\n| C | 知识图谱治理 | idle_ingest, lint, contradiction_states, self_heal |\n| D | 基准测试 | arch_baseline, arch_delta |\n| E | 高级记忆 | block_cognition, consolidation |\n| F | 多租户 | tenant_audit, tenant_kms |\n\n资料来源：[src/mind_mem/v4/__init__.py:1-50]()\n\n### 11.2 特征门控\n\n```python\nclass FeatureDisabledError(Exception):\n \"\"\"v4 功能未启用时抛出\"\"\"\n pass\n```\n\n所有 v4.0 功能均需在 `mind-mem.json` 配置文件的 `v4` 键下显式启用。\n\n## 12. 完整性保护机制\n\n### 12.1 关键模块保护\n\n系统维护一份关键模块清单，用于完整性验证：\n\n| 关键模块 | 说明 |\n|----------|------|\n| recall.py | 检索核心 |\n| recall_vector.py | 向量检索 |\n| apply_engine.py | 治理应用引擎 |\n| audit_chain.py | 审计链 |\n| encryption.py | 加密模块 |\n| graph_recall.py | 图检索 |\n| consensus_vote.py | 共识投票 |\n| tenant_audit.py | 租户审计 |\n\n资料来源：[src/mind_mem/protection.py:30-50]()\n\n### 12.2 完整性报告\n\n```python\n@dataclass(frozen=True)\nclass IntegrityReport:\n ok: bool\n module: str\n expected_hash: str\n actual_hash: str\n```\n\n## 13. Web 控制台架构\n\nmind-mem 提供基于 Next.js 的 Web 控制台，提供可视化记忆查询界面。\n\n```mermaid\ngraph LR\n API[\"REST API
/v1/recall
/v1/health\"] --> PAGE[\"app/page.tsx\"]\n PAGE --> GRAPH[\"GraphView
(d3-force)\"]\n PAGE --> TIMELINE[\"TimelineView\"]\n PAGE --> FACTS[\"FactList\"]\n \n GRAPH --> NODES[\"节点: 按状态着色\"]\n GRAPH --> EDGES[\"边: 按谓词着色\"]\n```\n\n组件说明：\n\n| 组件 | 功能 |\n|------|------|\n| GraphView.tsx | 力导向图可视化 |\n| TimelineView.tsx | 时间线视图 |\n| FactList.tsx | 提取的事实列表 |\n| lib/api.ts | 类型化 API 客户端 |\n\n资料来源：[web/README.md]()\n\n## 14. 依赖关系总览\n\n```mermaid\ngraph BT\n subgraph 核心依赖\n BLOCK[\"block_parser\"]\n FTS[\"sqlite_index
(FTS5)\"]\n COGNITIVE[\"cognitive_forget\"]\n end\n \n subgraph MCP 工具\n GOVERNANCE[\"governance.py\"]\n AUDIT[\"audit.py\"]\n MEMORY_OPS[\"memory_ops.py\"]\n CONSOLIDATION[\"consolidation.py\"]\n end\n \n subgraph 基础设施\n OBSERVE[\"observability\"]\n CONFIG[\"config\"]\n WORKSPACE[\"workspace\"]\n end\n \n MCP[\"mcp_server.py\"] --> GOVERNANCE\n MCP --> AUDIT\n MCP --> MEMORY_OPS\n MCP --> CONSOLIDATION\n \n GOVERNANCE --> BLOCK\n GOVERNANCE --> FTS\n AUDIT --> BLOCK\n MEMORY_OPS --> FTS\n CONSOLIDATION --> COGNITIVE\n \n BLOCK --> FTS\n COGNITIVE --> FTS\n```\n\n## 15. 总结\n\nmind-mem 的系统架构围绕以下核心设计原则构建：\n\n1. **协议分离**：通过 MCP 协议将核心功能暴露给 AI 客户端，CLI 作为补充\n2. **治理优先**：所有记忆修改必须经过治理流程，保证可追溯性\n3. **完整性保证**：多层审计机制（哈希链、默克尔树、证据链）确保记忆不可篡改\n4. **智能体无关**：通过可扩展的 hook 系统支持多种 AI 编码助手\n5. **演进能力**：v4.0 架构通过 feature flag 逐步引入新功能，不影响现有系统\n\n---\n\n\n\n## 数据流与处理管道\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [存储后端](#page-storage), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/capture.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/capture.py)\n- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/ingestion_pipeline.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/ingestion_pipeline.py)\n- [src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n \n\n# 数据流与处理管道\n\n## 概述\n\n数据流与处理管道是 mind-mem 系统的核心组成部分，负责管理从数据捕获、存储、处理到检索的完整生命周期。该管道遵循\"内存永不直接修改，只能通过治理机制变更\"的核心不变量，确保所有数据变更都经过审批和追踪流程。\n\n## 整体架构\n\n```mermaid\ngraph TD\n subgraph 数据捕获层\n CAPT[数据捕获]\n SIG[信号生成]\n end\n\n subgraph 存储抽象层\n BS[BlockStore 抽象]\n MB[MarkdownBlockStore]\n PG[PostgresBlockStore]\n ES[EncryptedBlockStore]\n end\n\n subgraph 处理引擎层\n APPLY[ApplyEngine]\n SNAP[快照管理]\n DIFF[差异计算]\n end\n\n subgraph 治理层\n PROP[提案机制]\n APPROVE[审批应用]\n ROLLBACK[回滚机制]\n end\n\n subgraph 检索层\n RECALL[Recall 检索]\n BM25[BM25 检索]\n VECTOR[向量检索]\n HYBRID[混合检索]\n end\n\n CAPT --> BS\n SIG --> BS\n BS --> APPLY\n APPLY --> SNAP\n APPLY --> DIFF\n PROP --> APPROVE\n APPROVE --> ROLLBACK\n RECALL --> BM25\n RECALL --> VECTOR\n RECALL --> HYBRID\n```\n\n## 核心组件\n\n### BlockStore 抽象层\n\nBlockStore 是数据持久化的核心抽象，支持多种后端实现：\n\n| 组件 | 类名 | 用途 | 配置键 |\n|------|------|------|--------|\n| 默认后端 | `MarkdownBlockStore` | Markdown 文件存储 | `block_store.backend: markdown` |\n| Postgres 后端 | `PostgresBlockStore` | 关系型数据库存储 | `block_store.backend: postgres` |\n| 加密包装器 | `EncryptedBlockStore` | 加密数据存储 | `mind-mem.json` passphrase 设置 |\n\n资料来源：[src/mind_mem/apply_engine.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n### ApplyEngine 处理引擎\n\nApplyEngine 负责数据变更的实际执行，提供快照、回滚和差异对比功能：\n\n```python\ndef _store_for(ws) -> BlockStore:\n \"\"\"根据配置获取对应的 BlockStore 实现\"\"\"\n \ndef create_snapshot(ws, ts, files_touched=None) -> str:\n \"\"\"创建应用前快照，返回快照目录路径\"\"\"\n\ndef restore_snapshot(ws, snap_dir) -> None:\n \"\"\"从快照目录恢复工作空间\"\"\"\n\ndef snapshot_diff(ws, snap_dir) -> list[str]:\n \"\"\"返回当前工作空间与快照的差异文件列表\"\"\"\n```\n\n资料来源：[src/mind_mem/apply_engine.py:30-55](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## 数据流阶段\n\n### 阶段一：数据捕获\n\n数据捕获层负责收集外部信号和用户输入，生成标准化的 Block 结构：\n\n```mermaid\ngraph LR\n A[外部输入] --> B[Capture 模块]\n B --> C[Block 结构化]\n C --> D[信号写入]\n D --> E[SIGNALS.md]\n```\n\n关键流程：\n1. 接收外部数据源（CLI、API、MCP 工具）\n2. 解析为标准 Block 格式\n3. 写入 SIGNALS.md 待审批队列\n\n### 阶段二：存储抽象\n\n存储层根据配置选择合适的持久化后端：\n\n```mermaid\ngraph TD\n A[写入请求] --> B{配置检查}\n B -->|passphrase 设置| C[EncryptedBlockStore]\n B -->|postgres 配置| D[PostgresBlockStore]\n B -->|默认| E[MarkdownBlockStore]\n C --> F[加密后写入]\n D --> G[SQL 写入]\n E --> H[Markdown 文件写入]\n```\n\n资料来源：[src/mind_mem/block_store.py:1-80](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n### 阶段三：检索与召回\n\nRecall 模块提供多种检索策略：\n\n| 检索模式 | 参数 | 说明 |\n|----------|------|------|\n| BM25 | `strategy: bm25` | 基于词频的稀疏检索 |\n| 向量检索 | `strategy: vector` | 密集向量相似度检索 |\n| 混合模式 | `strategy: hybrid` | BM25 + 向量加权融合 |\n| 自动模式 | `strategy: auto` | 根据查询特征自动选择 |\n\n资料来源：[src/mind_mem/recall.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n\n## 治理与变更流程\n\n### 提案-审批模式\n\n所有数据变更必须通过治理机制：\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant P as 提案模块\n participant A as ApplyEngine\n participant S as 快照\n participant R as 检索系统\n\n U->>P: propose_update(block_type, statement)\n P->>P: 生成 SIGNAL\n P->>S: create_snapshot(ws, timestamp)\n Note over S: 创建预应用快照\n U->>A: approve_apply(signal_id)\n A->>S: snapshot_diff()\n A->>R: 更新索引\n Note over A: 应用变更\n```\n\n### 回滚机制\n\n当变更需要撤销时，系统通过快照恢复：\n\n```python\n# 回滚流程\nsnap_dir = create_snapshot(ws, ts) # 变更前创建快照\n# ... 执行变更 ...\nrestore_snapshot(ws, snap_dir) # 需要回滚时恢复\n```\n\n资料来源：[src/mind_mem/apply_engine.py:40-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## 编译真相机制\n\nCompiled Truth 模块负责证据聚合和事实编译：\n\n```mermaid\ngraph TD\n A[原始证据] --> B[EvidenceEntry 解析]\n B --> C[证据池累积]\n C --> D[检测矛盾]\n D -->|无矛盾| E[recompile_truth]\n D -->|存在矛盾| F[矛盾标记]\n E --> G[CompiledTruthPage]\n```\n\n关键函数：\n- `add_evidence()`: 向真相页添加新证据\n- `recompile_truth()`: 重新编译真相摘要\n- `detect_contradictions()`: 检测证据矛盾\n\n资料来源：[src/mind_mem/compiled_truth.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## MCP 工具集成\n\nMCP 工具层提供外部系统交互接口：\n\n| 工具类别 | 工具名称 | 功能 |\n|----------|----------|------|\n| 内核管理 | `list_mind_kernels` | 列出可用内核配置 |\n| 内核管理 | `get_mind_kernel` | 获取指定内核详情 |\n| 真相管理 | `compiled_truth_add_evidence` | 添加证据到真相页 |\n| 真相管理 | `compiled_truth_contradictions` | 检测真相矛盾 |\n| 治理工具 | `propose_update` | 提交变更提案 |\n| 治理工具 | `approve_apply` | 审批并应用变更 |\n| 治理工具 | `rollback_proposal` | 回滚提案 |\n\n资料来源：[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)\n\n## 配置参数\n\n### BlockStore 配置\n\n在 `mind-mem.json` 中的配置结构：\n\n```json\n{\n \"block_store\": {\n \"backend\": \"markdown|postgres|encrypted\",\n \"passphrase\": \"<加密密钥>\",\n \"connection\": \"\"\n }\n}\n```\n\n### 检索配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `strategy` | string | `auto` | 检索策略选择 |\n| `limit` | int | 20 | 结果数量限制 |\n| `active_only` | bool | false | 仅返回活跃块 |\n\n## 错误处理与容错\n\n系统采用分层错误处理策略：\n\n1. **BlockStore 层**：异常时回退到 MarkdownBlockStore 默认实现\n2. **ApplyEngine 层**：快照操作失败时记录日志但不阻断主流程\n3. **Recall 层**：单一检索失败时尝试降级到其他策略\n\n```python\ntry:\n return get_block_store(ws)\nexcept Exception:\n return MarkdownBlockStore(ws) # 降级保底\n```\n\n资料来源：[src/mind_mem/apply_engine.py:40-45](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## 性能考量\n\n- **快照开销**：create_snapshot 在变更频繁场景下可能产生 IO 压力\n- **检索延迟**：混合检索模式需要并行执行 BM25 和向量检索\n- **存储选择**：Postgres 后端适合高并发写入场景，Markdown 适合简单部署\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[数据流与处理管道](#page-data-flow), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n- [src/mind_mem/storage/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/storage/__init__.py)\n- [src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n \n\n# 存储后端\n\nmind-mem 采用插件化的存储后端架构，支持多种持久化方案以适应不同的部署场景。所有存储操作通过统一的 BlockStore 接口抽象，确保上层逻辑与具体存储技术解耦。\n\n## 架构概述\n\n存储后端系统采用工厂模式（Factory Pattern）进行后端实例化。`get_block_store()` 工厂函数根据工作区配置动态选择合适的存储实现。\n\n```mermaid\ngraph TD\n A[应用层代码] --> B[get_block_store 工厂函数]\n B --> C{mind-mem.json 配置}\n C -->|backend: markdown| D[MarkdownBlockStore]\n C -->|backend: encrypted| E[EncryptedBlockStore 包装器]\n C -->|backend: postgres| F[PostgresBlockStore]\n E --> D\n F --> G[(PostgreSQL 数据库)]\n D --> H[/workspace/memory/\\*.md]\n```\n\n资料来源：[src/mind_mem/storage/__init__.py:53-70]()\n\n## 支持的后端类型\n\n| 后端类型 | 配置值 | 说明 | 依赖 |\n|---------|--------|------|------|\n| Markdown | `markdown` | 默认后端，将块存储为 Markdown 文件 | 无 |\n| 加密存储 | `encrypted` | 在 Markdown 后端基础上添加加密层 | `MIND_MEM_ENCRYPTION_PASSPHRASE` 环境变量 |\n| PostgreSQL | `postgres` | 企业级关系数据库存储 | `psycopg[binary]`、`dsn` 配置 |\n\n资料来源：[src/mind_mem/storage/__init__.py:55-68]()\n\n## 工厂函数 API\n\n### get_block_store(workspace, config=None)\n\n`storage/__init__.py` 中定义的工厂函数，负责根据配置实例化正确的后端。\n\n**函数签名：**\n\n```python\ndef get_block_store(workspace: str, config: dict[str, Any] | None = None) -> BlockStore:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|-----|------|------|------|\n| `workspace` | str | 是 | mind-mem 工作区根目录路径 |\n| `config` | dict \\| None | 否 | 完整配置字典，为空时自动从 `mind-mem.json` 加载 |\n\n**返回值：**\n\n返回 `BlockStore` 实例（`MarkdownBlockStore`、`EncryptedBlockStore` 或 `PostgresBlockStore`）。\n\n**异常处理：**\n\n| 异常类型 | 触发条件 |\n|---------|----------|\n| `ValueError` | `backend` 值无法识别 |\n| `ValueError` | 使用 `encrypted` 后端但未设置环境变量 |\n| `ValueError` | 使用 `postgres` 后端但配置中缺少 `dsn` |\n| `ImportError` | 使用 `postgres` 后端但未安装 `psycopg` |\n\n资料来源：[src/mind_mem/storage/__init__.py:30-50]()\n\n### 配置读取逻辑\n\n工厂函数首先尝试从工作区目录加载 `mind-mem.json` 配置文件：\n\n```python\ndef _load_workspace_config(workspace: str) -> dict[str, Any]:\n config_path = os.path.join(workspace, \"mind-mem.json\")\n if os.path.isfile(config_path):\n with open(config_path, encoding=\"utf-8\") as f:\n return json.load(f)\n return {}\n```\n\n如果配置文件不存在或解析失败，返回空字典，工厂函数将使用默认值 `markdown`。\n\n资料来源：[src/mind_mem/storage/__init__.py:16-28]()\n\n## 核心接口：BlockStore\n\n`BlockStore` 是所有存储后端的基类，定义了统一的存储操作接口。关键方法包括快照管理，这是实现\"内存永不直接修改\"治理不变量的基础。\n\n### 快照操作\n\n快照机制是 apply_engine 实现回滚功能的核心。当需要修改工作区内容时，系统首先创建快照，然后对快照进行操作，验证通过后才正式应用。\n\n| 方法 | 功能 |\n|-----|------|\n| `snapshot(snap_dir, files_touched)` | 创建预应用快照 |\n| `restore(snap_dir)` | 从快照目录恢复工作区 |\n| `diff(snap_dir)` | 比较当前工作区与快照的差异 |\n\n```mermaid\nsequenceDiagram\n participant AE as ApplyEngine\n participant BS as BlockStore\n participant WS as Workspace\n participant SNAP as Snapshot Dir\n\n AE->>BS: create_snapshot(ws, ts)\n BS->>WS: 读取当前文件\n WS-->>BS: 文件内容\n BS->>SNAP: 写入快照目录\n Note over BS: Markdown: 复制文件树
Postgres: SQL 转储\n BS-->>AE: snap_dir 路径\n```\n\n资料来源：[src/mind_mem/apply_engine.py:26-38]()\n\n## Markdown 后端\n\nMarkdownBlockStore 是默认存储后端，将每个块存储为独立的 Markdown 文件。\n\n### 存储结构\n\n```\nworkspace/\n├── memory/\n│ ├── decisions/\n│ │ └── D-20260213-001.md\n│ ├── tasks/\n│ │ └── T-20260213-001.md\n│ └── signals/\n│ └── S-20260213-001.md\n└── intelligence/\n └── applied/\n └── 20260213-120000/ # 快照目录\n```\n\n### 块格式规范\n\n每个 Markdown 块遵循固定格式，包含标识头和键值对字段：\n\n```markdown\n[ID]\nStatement: 决策内容描述\nDate: 2026-02-13\nStatus: active\nConfidence: high\nTags: architecture, backend\n\n[ID]\n```\n\n`CANONICAL_FIELD_ORDER` 定义了字段的标准顺序，确保块序列化的一致性：\n\n```python\n_CANONICAL_FIELD_ORDER: tuple[str, ...] = (\n \"Statement\", \"Date\", \"Status\", \"Priority\", \"Risk\",\n \"Type\", \"Subject\", \"Object\", \"Tags\", \"Rationale\",\n \"Evidence\", \"Source\", \"Confidence\", \"ContentHash\",\n \"Excerpt\", \"Action\",\n)\n```\n\n资料来源：[src/mind_mem/block_store.py:75-90]()\n\n## PostgreSQL 后端\n\nPostgresBlockStore 为企业级部署提供关系数据库存储能力。适用于需要事务支持、并发访问和高可用性的生产环境。\n\n### 配置示例\n\n```json\n{\n \"block_store\": {\n \"backend\": \"postgres\",\n \"dsn\": \"postgresql://user:password@localhost:5432/mindmem\"\n }\n}\n```\n\n### 与 Markdown 后端的差异\n\n| 特性 | Markdown | PostgreSQL |\n|-----|----------|------------|\n| 快照方式 | 文件复制 | SQL 转储 |\n| 并发支持 | 文件锁 | 数据库事务 |\n| 查询能力 | 全文搜索 | SQL 查询 |\n| 部署复杂度 | 简单 | 需要数据库服务 |\n\n## 加密存储包装器\n\nEncryptedBlockStore 是一个包装器后端，它在底层 Markdown 后端基础上添加加密功能。当设置了 `MIND_MEM_ENCRYPTION_PASSPHRASE` 环境变量时，存储模块会自动返回加密包装后的实例。\n\n资料来源：[src/mind_mem/storage/__init__.py:65-67]()\n\n## 在 Apply Engine 中的应用\n\napply_engine 模块通过 `_store_for(ws)` 函数获取当前配置的 BlockStore 实例，所有存储操作都通过该实例进行路由：\n\n```python\ndef _store_for(ws):\n try:\n from .storage import get_block_store\n return get_block_store(ws)\n except Exception:\n return MarkdownBlockStore(ws) # 容错降级\n```\n\n这种设计确保了 apply_engine 的韧性：在首次运行或配置错误的工作区，系统会优雅降级到默认的 Markdown 后端。\n\n资料来源：[src/mind_mem/apply_engine.py:20-26]()\n\n## 删除日志\n\n当块被删除时，后端会将删除收据写入 `memory/deleted_blocks.jsonl` 文件：\n\n```json\n{\"block_id\": \"D-20260213-001\", \"deleted_at\": \"2026-02-13T12:00:00+00:00\", \"content\": \"...\"}\n```\n\n这一机制与 MCP 工具 `delete_memory_item` 保持一致，两条删除路径最终汇聚到同一恢复日志。\n\n资料来源：[src/mind_mem/block_store.py:45-60]()\n\n## 配置建议\n\n| 场景 | 推荐后端 | 原因 |\n|-----|---------|------|\n| 本地开发 / 个人使用 | Markdown | 简单、无依赖、易于调试 |\n| 小团队协作 | Markdown + Git | 利用版本控制进行协作 |\n| 企业级生产环境 | PostgreSQL | 事务支持、并发控制、备份恢复 |\n| 安全敏感数据 | Encrypted | 静态数据加密保护 |\n\n---\n\n\n\n## 检索管道\n\n### 相关页面\n\n相关主题：[存储后端](#page-storage), [治理与矛盾检测](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)\n- [src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/query_expansion.py)\n- [src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)\n- [src/mind_mem/rerank_ensemble.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/rerank_ensemble.py)\n- [mind/bm25.mind](https://github.com/star-ga/mind-mem/blob/main/mind/bm25.mind)\n- [mind/rrf.mind](https://github.com/star-ga/mind-mem/blob/main/mind/rrf.mind)\n \n\n# 检索管道\n\n## 概述\n\n检索管道（Retrieval Pipeline）是 mind-mem 系统中的核心组件，负责从工作空间内存中定位和召回与用户查询相关的记忆块。该管道采用多阶段架构，结合了稀疏检索（BM25）、密集检索（向量检索）和重排序（Re-ranking）等多种技术，以实现高质量的检索结果。\n\n检索管道的主要职责包括：\n- 解析用户查询并执行多路召回\n- 对多条召回路径的结果进行融合排序\n- 应用质量过滤和后处理逻辑\n- 返回符合置信度和活跃状态要求的结果集\n\n## 架构概览\n\n检索管道采用三层架构设计，各层职责分明：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[查询扩展层]\n B --> C[多路召回层]\n C --> D[结果融合层]\n D --> E[重排序层]\n E --> F[最终结果]\n \n C --> C1[BM25 稀疏检索]\n C --> C2[向量检索]\n C --> C3[RM3 扩展检索]\n \n D --> D1[RRF 融合]\n D --> D2[加权融合]\n```\n\n## 查询扩展层\n\n### 查询扩展机制\n\n查询扩展（Query Expansion）是检索管道的入口阶段，负责增强原始查询的语义表达能力。通过分析查询意图，系统可以引入相关术语和同义词，从而扩大检索范围。\n\n查询扩展支持多种策略：\n- **RM3 扩展**：基于伪相关反馈的扩展方法，从初始检索结果中提取高权重词项\n- **同义词扩展**：利用预定义的同义词库进行术语扩展\n- **概念扩展**：识别查询中的实体概念并引入相关概念\n\n### 配置参数\n\n查询扩展的行为可以通过 `.mind` 内核配置文件进行调优，主要参数包括：\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `rm3_expansion_terms` | int | 10 | RM3 扩展的词项数量 |\n| `rm3_collection_weight` | float | 0.9 | 文档权重系数 |\n| `expansion_enabled` | bool | true | 是否启用扩展 |\n\n## 多路召回层\n\n多路召回是检索管道的核心阶段，通过并行执行多种检索算法来最大化召回率。\n\n### BM25 稀疏检索\n\nBM25（Best Matching 25）是一种经典的稀疏检索算法，基于词项频率和文档频率的统计模型计算相关性评分。\n\nBM25 的核心公式：\n\n```\nScore(D, Q) = Σ IDF(qi) × (f(qi, D) × (k1 + 1)) / (f(qi, D) + k1 × (1 - b + b × |D|/avgdl))\n```\n\n其中：\n- `f(qi, D)`：词项 qi 在文档 D 中的频率\n- `|D|`：文档长度\n- `avgdl`：平均文档长度\n- `k1`, `b`：可调参数（通常 k1=1.2, b=0.75）\n\nBM25 内核配置文件（`mind/bm25.mind`）允许调整以下参数：\n\n| 参数 | 说明 | 典型值 |\n|------|------|--------|\n| `k1` | 词频饱和参数 | 1.2 |\n| `b` | 文档长度归一化参数 | 0.75 |\n| `avgdl` | 平均文档长度基准 | - |\n\n### 向量检索\n\n向量检索（Vector Recall）使用密集嵌入表示进行语义级别的相似度匹配。系统将记忆块和查询都编码为高维向量，然后通过最近邻搜索找到相关结果。\n\n向量检索的流程：\n\n```mermaid\ngraph LR\n A[记忆块文本] --> B[Embedding 模型]\n B --> C[向量索引]\n C --> D[查询向量]\n D --> E[向量相似度计算]\n E --> F[Top-K 结果]\n```\n\n向量检索的主要配置参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `model_name` | str | 嵌入模型名称 |\n| `dimension` | int | 向量维度 |\n| `similarity_metric` | str | 相似度度量（cosine/dot/euclidean） |\n| `top_k` | int | 返回的最近邻数量 |\n\n### RM3 扩展检索\n\nRM3 是一种伪相关反馈方法，通过以下步骤扩展查询：\n\n1. 执行初始检索获取 Top-N 结果\n2. 从结果中提取高权重词项和词组\n3. 将扩展词项加入原始查询\n4. 执行二次检索\n\nRM3 扩展检索的实现位于 `query_expansion.py`，其核心逻辑包括：\n\n- 词项权重计算：基于文档内频率和逆文档频率\n- 词组提取：识别连续的高频词序列\n- 权重融合：将扩展词项与原始查询词项按权重合并\n\n## 结果融合层\n\n多路召回产生多个候选结果集，融合层负责将这些结果合并为一个统一的排序列表。\n\n### 倒数排序融合（RRF）\n\n倒数排序融合（Reciprocal Rank Fusion）是一种简单而有效的多路召回结果融合算法。RRF 不依赖各路召回的绝对分数，而是利用相对排名信息进行融合。\n\nRRF 公式：\n\n```\nRRF_score(d) = Σ 1 / (k + rank(d, Ri))\n```\n\n其中：\n- `d`：目标文档\n- `Ri`：第 i 路召回的排名列表\n- `k`：常量平滑因子（通常 k=60）\n- `rank(d, Ri)`：文档 d 在第 i 路召回中的排名\n\nRRF 内核配置文件（`mind/rrf.mind`）定义融合参数：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `k` | 60 | RRF 平滑因子 |\n| `enabled` | true | 是否启用 RRF |\n\n### 加权融合\n\n除了 RRF，系统还支持基于分数的加权融合方法：\n\n```\nfusion_score(d) = Σ wi × norm(scorei(d))\n```\n\n其中 `wi` 是各路召回的可配置权重，`norm()` 是归一化函数。\n\n## 重排序层\n\n重排序（Re-ranking）阶段对融合后的候选结果进行精细化排序，以提高最终结果的相关性。\n\n### 重排序策略\n\n重排序器（`rerank_ensemble.py`）支持多种重排序策略：\n\n1. **Cross-Encoder 重排序**：使用更强大的模型对 Top-K 候选进行精确评分\n2. **Learning-to-Rank**：基于特征的训练模型进行排序\n3. **级联重排序**：多轮渐进式重排序\n\n### 排序特征\n\n重排序阶段考虑的特征包括：\n\n| 特征类别 | 具体特征 |\n|----------|----------|\n| 相关性特征 | BM25 分数、向量相似度、语义匹配度 |\n| 质量特征 | 块完整性、置信度评分、来源权重 |\n| 时效性特征 | 创建时间、最后更新时间、活跃状态 |\n| 关联性特征 | 引用次数、依赖关系、实体匹配 |\n\n## 混合检索流程\n\n完整的混合检索流程如下：\n\n```mermaid\nsequenceDiagram\n participant 用户\n participant 管道\n participant BM25\n participant 向量引擎\n participant 融合器\n participant 重排序器\n participant 结果\n \n 用户->>管道: 提交查询\n 管道->>BM25: 发起 BM25 检索\n 管道->>向量引擎: 发起向量检索\n 管道->>BM25: 获取 Top-K 结果\n 管道->>向量引擎: 获取 Top-K 结果\n BM25-->>管道: BM25 结果集\n 向量引擎-->>管道: 向量结果集\n 管道->>融合器: 合并多路结果\n 融合器-->>管道: 融合排序列表\n 管道->>重排序器: 精细化重排序\n 重排序器-->>管道: 最终排序结果\n 管道-->>用户: 返回 Top-N 结果\n```\n\n## 集成接口\n\n### Python API\n\n检索管道通过 `recall` 模块提供核心检索接口：\n\n```python\nfrom mind_mem.recall import recall\n\nresults = recall(\n workspace,\n query,\n limit=10,\n active_only=True,\n format=\"blocks\"\n)\n```\n\n### MCP 工具接口\n\n在 MCP 服务器中，检索管道通过以下工具暴露：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `recall` | 基础检索接口 |\n| `recall_with_persona` | 带角色投影的检索 |\n| `list_mind_kernels` | 列出可用的检索内核配置 |\n| `get_mind_kernel` | 获取特定内核配置详情 |\n\n### CLI 接口\n\n命令行工具 `mm` 提供检索访问：\n\n```bash\nmm recall \"查询内容\" --limit 10 --active-only\nmm context \"查询内容\" --budget 4096\n```\n\n## 配置管理\n\n### 内核配置文件\n\n检索管道的各项参数通过 `.mind` 内核配置文件进行管理：\n\n```\nmind/\n├── bm25.mind # BM25 检索参数\n├── rrf.mind # RRF 融合参数\n└── rerank.mind # 重排序参数\n```\n\n### 运行时配置\n\n检索管道支持运行时配置覆盖：\n\n```python\nrecall(\n workspace,\n query,\n backend=\"auto\", # auto/bm25/hybrid\n format=\"json\", # json/blocks/bundle\n)\n```\n\n## 性能优化\n\n### 索引优化\n\n- **FTS5 索引**：使用 SQLite FTS5 实现高效的全文搜索\n- **向量索引**：采用近似最近邻（ANN）算法加速向量检索\n- **缓存策略**：对高频查询结果进行缓存\n\n### 查询优化\n\n- **早停机制**：当累计分数达到阈值时提前终止\n- **分层检索**：先用轻量级方法过滤，再用重排序精细化\n- **并行执行**：多路召回并行执行以降低延迟\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 检索结果为空 | 索引未建立 | 执行 `reindex` 工具 |\n| 结果不相关 | 查询扩展过度 | 调整 `expansion_enabled` |\n| 延迟过高 | 向量索引未优化 | 检查 ANN 参数配置 |\n| 排名异常 | 内核参数冲突 | 检查 `.mind` 配置文件 |\n\n## 扩展阅读\n\n- [内核配置系统](./内核配置系统.md)\n- [记忆块解析](./记忆块解析.md)\n- [证据捆绑](./证据捆绑.md)\n\n---\n\n\n\n## MCP服务器\n\n### 相关页面\n\n相关主题：[MCP工具集](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/mcp/server.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py)\n- [src/mind_mem/mcp_entry.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_entry.py)\n- [mcp_server.py](https://github.com/star-ga/mind-mem/blob/main/mcp_server.py)\n- [docs/mcp-integration.md](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-integration.md)\n \n\n# MCP服务器\n\n## 概述\n\nMCP服务器（Model Context Protocol Server）是mind-mem项目提供的AI记忆管理服务接口，通过MCP协议为AI智能体（Agent）提供记忆存储、检索和上下文管理能力。该服务器使AI应用能够持久化存储对话上下文和记忆数据，并在后续对话中动态加载相关记忆，实现跨会话的上下文连续性。\n\n## 核心架构\n\n### 架构组件\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| MCP Server | MCP协议服务端实现，处理客户端请求 | `src/mind_mem/mcp/server.py` |\n| MCP Entry | 服务入口点，负责初始化和启动 | `src/mind_mem/mcp_entry.py` |\n| 记忆存储引擎 | 管理记忆数据的持久化存储 | 内部模块 |\n| 检索引擎 | 支持语义检索和关键词匹配 | 内部模块 |\n\n### 数据流架构\n\n```mermaid\ngraph TD\n A[AI Agent] -->|MCP Protocol| B[MCP Server]\n B --> C[记忆存储引擎]\n C --> D[向量数据库]\n C --> E[键值存储]\n B --> F[检索引擎]\n F --> D\n F --> E\n G[外部应用] -->|REST/gRPC| B\n```\n\n## 服务启动\n\n### 启动方式\n\nMCP服务器支持两种启动方式：\n\n1. **直接启动脚本**：`mcp_server.py` 提供了独立运行的入口点\n2. **模块导入启动**：通过 `src/mind_mem/mcp_entry.py` 导入并初始化\n\n### 启动配置\n\n服务器启动时需要配置以下参数：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| host | 服务监听地址 | 0.0.0.0 |\n| port | 服务监听端口 | 8080 |\n| storage_path | 记忆存储路径 | ./memory_data |\n| vector_dim | 向量维度 | 768 |\n\n## MCP协议接口\n\n### 核心工具\n\nMCP服务器通过MCP协议暴露以下核心工具：\n\n| 工具名称 | 功能 | 输入参数 |\n|----------|------|----------|\n| store_memory | 存储记忆 | user_id, content, metadata |\n| retrieve_memories | 检索记忆 | query, user_id, limit |\n| update_memory | 更新记忆 | memory_id, content |\n| delete_memory | 删除记忆 | memory_id |\n| list_memories | 列出记忆 | user_id, filters |\n\n### 资源管理\n\n服务器提供以下MCP资源：\n\n```mermaid\ngraph LR\n A[Resources] --> B[memory://user/{user_id}]\n A --> C[memory://conversation/{conv_id}]\n A --> D[memory://summary/{user_id}]\n```\n\n## 集成方式\n\n### 客户端集成\n\n项目文档 `docs/mcp-integration.md` 描述了与AI智能体的集成方式：\n\n```mermaid\nsequenceDiagram\n participant Agent as AI Agent\n participant MCP as MCP Client\n participant Server as MCP Server\n \n Agent->>MCP: 连接服务器\n MCP->>Server: 握手协商\n Server-->>MCP: 连接确认\n MCP-->>Agent: 就绪状态\n \n Agent->>MCP: 发送记忆存储请求\n MCP->>Server: store_memory()\n Server-->>MCP: 存储成功\n MCP-->>Agent: 确认响应\n \n Agent->>MCP: 发送检索请求\n MCP->>Server: retrieve_memories()\n Server-->>MCP: 相关记忆\n MCP-->>Agent: 返回上下文\n```\n\n### 集成配置示例\n\n```json\n{\n \"mcp_servers\": {\n \"mind-mem\": {\n \"command\": \"python\",\n \"args\": [\"mcp_server.py\", \"--port\", \"8080\"],\n \"env\": {\n \"MEMORY_STORAGE_PATH\": \"./data/memory\"\n }\n }\n }\n}\n```\n\n## 记忆管理机制\n\n### 存储策略\n\n| 策略类型 | 说明 | 适用场景 |\n|----------|------|----------|\n| 即时存储 | 实时保存每次交互 | 重要对话记录 |\n| 批量存储 | 定时批量写入 | 低优先级日志 |\n| 压缩存储 | 自动摘要后存储 | 长对话历史 |\n\n### 检索机制\n\n服务器支持多种检索模式：\n\n1. **语义检索**：基于向量相似度匹配相关记忆\n2. **关键词检索**：精确匹配关键词\n3. **时间范围检索**：按时间筛选记忆\n4. **混合检索**：结合语义和关键词的混合搜索\n\n## 安全特性\n\n| 安全措施 | 说明 |\n|----------|------|\n| 用户隔离 | 不同用户记忆严格隔离 |\n| 访问控制 | 基于用户ID的访问验证 |\n| 数据加密 | 敏感数据加密存储 |\n| 审计日志 | 记录所有操作日志 |\n\n## 使用示例\n\n### 存储记忆\n\n```python\nfrom mind_mem import MCPClient\n\nclient = MCPClient(\"http://localhost:8080\")\nclient.store_memory(\n user_id=\"user123\",\n content=\"用户偏好使用中文交流\",\n metadata={\"source\": \"conversation\", \"timestamp\": \"2024-01-01\"}\n)\n```\n\n### 检索记忆\n\n```python\nmemories = client.retrieve_memories(\n query=\"用户偏好\",\n user_id=\"user123\",\n limit=5\n)\nfor memory in memories:\n print(memory.content)\n```\n\n## 配置选项\n\n### 环境变量配置\n\n| 变量名 | 说明 | 示例值 |\n|--------|------|--------|\n| MEMORY_STORAGE_PATH | 存储路径 | /data/memory |\n| MCP_PORT | 服务端口 | 8080 |\n| MCP_HOST | 服务地址 | localhost |\n| VECTOR_DB_TYPE | 向量数据库类型 | qdrant/chroma |\n| MAX_MEMORY_SIZE | 最大记忆大小 | 10000 |\n\n### 运行时配置\n\n```yaml\nserver:\n host: 0.0.0.0\n port: 8080\n workers: 4\n \nstorage:\n backend: sqlite\n path: ./data/memory.db\n \nvector:\n model: text-embedding-ada-002\n dimension: 1536\n```\n\n## 相关文档\n\n- [MCP集成指南](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-integration.md)\n- [主入口模块](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_entry.py)\n- [服务器实现](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/server.py)\n\n---\n\n\n\n## MCP工具集\n\n### 相关页面\n\n相关主题：[MCP服务器](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/consolidation.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/consolidation.py)\n- [src/mind_mem/mcp/tools/kernels.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n- [src/mind_mem/mcp/tools/core.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/core.py)\n- [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)\n- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)\n \n\n# MCP工具集\n\n## 概述\n\nMCP工具集（Model Context Protocol Tools）是mind-mem项目为非MCP智能体提供的统一命令行接口（CLI）以及MCP服务端工具集。该工具集涵盖了记忆管理的完整生命周期，包括记忆召回、上下文打包、记忆操作、治理、归档和基准测试等核心功能。\n\nMCP工具集的设计遵循以下核心原则：\n\n- **记忆不可直接修改原则**：记忆只能通过治理流程进行修改\n- **自愈式遗忘**：记忆通过认知遗忘机制自动衰减和归档\n- **知识核调优**：通过`.mind`内核文件调整召回和排序策略\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-30]()\n\n## 架构总览\n\nMCP工具集采用模块化架构，按功能域划分为多个工具子模块：\n\n```mermaid\ngraph TD\n subgraph MCP服务端\n A[mcp_server.py] --> B[tools/]\n B --> C[memory_ops]\n B --> D[governance]\n B --> E[consolidation]\n B --> F[kernels]\n B --> G[core]\n B --> H[arch_mind]\n B --> I[benchmark]\n B --> J[recall]\n B --> K[graph]\n end\n \n subgraph 基础设施层\n L[infra/observability]\n M[infra/workspace]\n N[infra/config]\n end\n \n C --> L\n D --> L\n E --> L\n G --> M\n H --> M\n I --> M\n```\n\n## 工具域分类\n\n### 记忆操作工具域（memory_ops）\n\n记忆操作工具域提供了记忆的索引重建、生命周期管理和健康检查功能。\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-50]()\n\n#### 核心工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `index_stats` | 获取FTS5全文索引状态 |\n| `reindex` | 重建全文索引 |\n| `delete_memory_item` | 原子性记忆块删除 |\n| `export_memory` | 导出记忆为JSONL格式 |\n| `get_block` | 获取单个记忆块 |\n| `memory_health` | 记忆健康状态仪表板 |\n| `compact` | 记忆压缩 |\n| `stale_blocks` | 陈旧记忆块管理 |\n\n#### 块前缀映射表\n\n工具内部维护了`_BLOCK_PREFIX_MAP`，用于快速定位不同类型记忆块的文件路径：\n\n| 前缀 | 文件路径 |\n|-----|---------|\n| `DEC` | `decisions/DECISIONS.md` |\n| `TSK` | `tasks/TASKS.md` |\n| `SIG` | `signals/SIGNALS.md` |\n| `ENT` | `entities/*.md` |\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:100-150]()\n\n### 治理工具域（governance）\n\n治理工具域是mind-mem的核心模块，遵循\"记忆只能通过治理流程修改\"的不变式。\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-40]()\n\n#### 治理工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `propose_update` | 将新决策/任务暂存为SIGNAL |\n| `approve_apply` | 应用暂存的提案（默认干跑） |\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理） |\n| `list_contradictions` | 矛盾列表枚举 |\n| `memory_evolution` | 获取记忆块的A-MEM元数据 |\n\n#### 治理工作流\n\n```mermaid\ngraph LR\n A[propose_update] --> B{SIGNALS.md}\n B --> C[人工审核]\n C --> D{approve_apply}\n D -->|干跑模式| E[预览变更]\n D -->|执行模式| F[应用变更]\n F --> G[快照记录]\n G --> H[rollback可用]\n```\n\n### 记忆整合工具域（consolidation）\n\n记忆整合工具域实现了\"记忆随时间沉淀\"的能力，通过认知遗忘循环维护记忆健康度。\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-35]()\n\n#### 整合工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `plan_consolidation` | 认知遗忘周期干跑 |\n| `propagate_staleness` | 跨引用扩散陈旧度评分 |\n| `project_profile` | 会话启动智能摘要 |\n| `dream_cycle` | 自主记忆富化（实体发现、损坏引用扫描、整合候选） |\n\n#### 整合配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|-----|-------|------|\n| `importance_threshold` | float | 0.25 | 重要性阈值 |\n| `stale_days` | int | 14 | 陈旧天数 |\n| `archive_after_days` | int | 60 | 归档天数 |\n| `grace_days` | int | 30 | 宽限期 |\n\n### 知识核工具域（kernels）\n\n知识核工具域提供了对`.mind`内核配置文件的只读访问，用于调整召回、排序和RM3扩展策略。\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:1-40]()\n\n#### 内核工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `list_mind_kernels` | 列出可用内核配置文件 |\n| `get_mind_kernel` | 获取指定内核配置详情 |\n| `compiled_truth_load` | 加载实体真值页面 |\n| `compiled_truth_add_evidence` | 添加证据到真值页面 |\n| `compiled_truth_contradictions` | 检测真值页面的矛盾 |\n\n### 上下文核心工具域（core）\n\n上下文核心工具域封装了CoreRegistry单例，管理`.mmcore`便携式块的打包和知识图归档。\n\n资料来源：[src/mind_mem/mcp/tools/core.py:1-45]()\n\n#### 核心工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `build_core` | 从活跃工作区构建.mmcore包 |\n| `load_core` | 加载.mmcore包到内存 |\n| `unload_core` | 卸载已加载的核心 |\n| `list_cores` | 列出已注册的核心 |\n\n#### mmcore包结构\n\n```mermaid\ngraph TD\n A[.mmcore归档] --> B[manifest.json]\n A --> C[blocks/]\n A --> D[edges/]\n A --> E[retrieval_policies.json]\n A --> F[ontology.json]\n \n C --> C1[block_001.json]\n C --> C2[block_002.json]\n D --> D1[edge_001.json]\n D --> D2[edge_002.json]\n```\n\n### Arch-Mind工具域（arch_mind）\n\nArch-Mind工具域将`arch-mind`二进制程序封装为7个MCP工具，提供架构基线管理和会话级指标追踪。\n\n资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-50]()\n\n#### Arch工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `arch_baseline` | 初始化架构基线 |\n| `arch_delta` | 计算当前扫描与基线的差异 |\n| `arch_history` | 列出架构事件历史 |\n| `arch_check_rules` | 应用规则到新扫描 |\n| `arch_session_start` | 打开会话证据节点 |\n| `arch_session_end` | 关闭会话并写入增量证据 |\n| `arch_metric_explain` | 逐指标解释 |\n\n### 基准测试工具域（benchmark）\n\n基准测试工具域提供了治理健康度和类别摘要的评估工具。\n\n资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-40]()\n\n#### 基准工具集\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `governance_health_bench` | 治理健康基准测试（矛盾检测、审计完整性、漂移检测、可扩展性探测） |\n| `category_summary` | 类别摘要蒸馏查找 |\n\n## MCP工具元数据\n\n所有MCP工具均通过以下装饰器实现统一观测：\n\n### 装饰器链\n\n```python\n@mcp_tool_observe # 观测性装饰器\n@_traced(\"tool_name\") # 追踪装饰器\ndef tool_function(args):\n ...\n```\n\n### 返回格式\n\n所有工具返回JSON格式字符串，包含标准模式版本头：\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"tool_name\": \"result_data\"\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:40-80]()\n\n## 工作区感知\n\nMCP工具集通过统一的`_workspace()`函数解析工作区路径：\n\n```mermaid\ngraph LR\n A[MIND_MEM_WORKSPACE环境变量] -->|优先级1| B[显式覆盖]\n A -->|未设置| C[当前工作目录]\n C --> D[realpath解析]\n B --> D\n D --> E[工作区根目录]\n```\n\n工作区检查通过`_check_workspace()`验证：\n\n1. 工作区目录存在\n2. 必需的子目录结构完整\n3. 必要的配置文件可读\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:20-50]()\n\n## CLI命令映射\n\nMCP工具集同时提供命令行接口（CLI），位于`mm_cli.py`：\n\n| CLI命令 | 对应工具域 |\n|--------|----------|\n| `mm recall` | 记忆召回 |\n| `mm context` | 上下文打包 |\n| `mm inject` | 智能体上下文注入 |\n| `mm vault` | 知识库扫描/写入 |\n| `mm status` | 工作区摘要 |\n| `mm explain` | 指标解释 |\n| `mm trace` | MCP调用日志追踪 |\n\n资料来源：[src/mind_mem/mm_cli.py:1-80]()\n\n## 错误处理\n\nMCP工具集采用统一的错误处理模式：\n\n### 错误类型\n\n| 错误类型 | 说明 | 处理方式 |\n|---------|-----|---------|\n| `WorkspaceError` | 工作区路径无效 | 返回错误JSON |\n| `BlockCorruptedError` | 记忆块损坏 | 隔离并记录 |\n| `CoreLoadError` | mmcore包解析失败 | 验证并报告 |\n| `SQLiteBusyError` | 数据库锁定 | 重试或等待 |\n\n### 错误响应格式\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"error\": \"error_description\"\n}\n```\n\n## 配置集成\n\nMCP工具集通过基础设施层获取配置：\n\n```python\nfrom ..infra.config import _get_limits, _load_extra_categories\nfrom ..infra.workspace import _workspace, _check_workspace\n```\n\n可配置项包括：\n\n- 最大类别结果数\n- 额外类别定义\n- 全文索引限制\n- 导出大小上限\n\n## 扩展机制\n\n### 自定义工具域\n\n新增工具域需要：\n\n1. 在`mcp/tools/`目录下创建新模块\n2. 实现工具函数并添加装饰器\n3. 在`mcp_server.py`中注册\n4. 更新本文档\n\n### 观测性扩展\n\n工具函数通过`mcp_tool_observe`装饰器自动集成到观测系统：\n\n- 调用计数（metrics.inc）\n- 日志记录（_log.info）\n- 追踪（traced decorator）\n\n## 相关文档\n\n- [MCP工具示例](https://github.com/star-ga/mind-mem/blob/main/docs/mcp-tool-examples.md)\n- [MCP服务端架构](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp_server.py)\n\n---\n\n\n\n## 治理与矛盾检测\n\n### 相关页面\n\n相关主题：[质量保障与验证](#page-quality), [检索管道](#page-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)\n- [src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)\n- [src/mind_mem/governance_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/governance_gate.py)\n- [src/mind_mem/audit_chain.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n- [src/mind_mem/mcp/tools/audit.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/audit.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/mcp/tools/benchmark.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/benchmark.py)\n \n\n# 治理与矛盾检测\n\n## 概述\n\n治理与矛盾检测是 mind-mem 系统的核心安全机制，确保记忆体的变更遵循\"记忆永不直接修改，只能通过治理流程变更\"的不变式。该模块涵盖了从提议、审批、应用到回滚的完整生命周期，同时提供矛盾检测、漂移检测和审计链验证等多层次防护。\n\n核心设计原则：\n- **治理驱动变更**：所有决策和任务的修改必须通过提议-审批流程\n- **证据链完整**：每条证据都有时间戳、来源和可信度标记\n- **矛盾优先检测**：在编译真理页面时自动检测冲突证据\n- **可审计可回滚**：所有操作记录在案，支持快照回滚\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-20]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n subgraph 治理层\n A[提议 Propose] --> B[审批 Apply]\n B --> C[回滚 Rollback]\n C --> D[扫描 Scan]\n D --> E[矛盾列表]\n end\n \n subgraph 证据层\n F[CompiledTruthPage] --> G[detect_contradictions]\n G --> H[EvidenceEntry]\n H --> I[superseded 标记]\n end\n \n subgraph 审计层\n J[verify_merkle] --> K[Merkle Tree]\n L[verify_chain] --> M[SHA3-512 Hash Chain]\n N[verify_evidence] --> O[Evidence Chain]\n end\n \n B --> J\n B --> L\n F --> G\n```\n\n## 核心组件\n\n### 1. 治理门 (Governance Gate)\n\n治理门是记忆修改的守门人，确保所有变更必须通过标准流程。\n\n```python\n# 伪代码展示治理门工作流程\ndef governance_check(block):\n if is_proposal(block) and is_approved(block):\n return APPLY\n elif is_contradiction_detected(block):\n return REJECT_CONFLICT\n else:\n return QUEUE_FOR_REVIEW\n```\n\n**治理门配置参数**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `require_approval` | bool | true | 是否要求审批 |\n| `contradiction_threshold` | float | 0.7 | 矛盾检测阈值 |\n| `drift_tolerance` | int | 3 | 漂移容忍度 |\n\n资料来源：[src/mind_mem/governance_gate.py]()\n\n### 2. 矛盾检测器 (Contradiction Detector)\n\n矛盾检测器分析编译真理页面的证据条目，识别相互冲突的陈述。\n\n```mermaid\ngraph LR\n A[Evidence Entry 1] --> D{矛盾检测}\n B[Evidence Entry 2] --> D\n C[Evidence Entry 3] --> D\n D --> E[冲突报告]\n E --> F[标记为 superseded]\n```\n\n**核心检测逻辑**：\n\n```python\ndef detect_contradictions(page: CompiledTruthPage) -> list[Contradiction]:\n \"\"\"检测证据条目间的矛盾\"\"\"\n contradictions = []\n for i, entry_i in enumerate(page.evidence_entries):\n for j, entry_j in enumerate(page.evidence_entries[i+1:], i+1):\n if _is_contradictory(entry_i, entry_j):\n contradictions.append(Contradiction(\n entry_a=i,\n entry_b=j,\n severity=_calculate_severity(entry_i, entry_j)\n ))\n return contradictions\n```\n\n**检测维度**：\n\n| 维度 | 说明 | 优先级 |\n|------|------|--------|\n| 时间矛盾 | 同一事件的时间陈述不一致 | 高 |\n| 属性矛盾 | 实体属性值冲突 | 高 |\n| 因果矛盾 | 因果关系陈述相反 | 中 |\n| 语义矛盾 | 否定/肯定陈述冲突 | 中 |\n| 数值矛盾 | 数值范围或精度不匹配 | 低 |\n\n资料来源：[src/mind_mem/contradiction_detector.py]()\n\n### 3. 漂移检测器 (Drift Detector)\n\n漂移检测器监控决策或任务的实际执行与原始声明之间的偏离。\n\n```mermaid\ngraph TD\n A[原始声明] --> B[版本化快照]\n C[当前状态] --> D{漂移计算}\n B --> D\n D --> E{超出容忍度?}\n E -->|是| F[触发告警]\n E -->|否| G[继续监控]\n```\n\n**漂移检测触发条件**：\n\n- 决策状态与预期不符\n- 任务优先级发生非预期变更\n- 截止日期与原计划偏差超过阈值\n- 关联实体发生未记录变更\n\n资料来源：[src/mind_mem/drift_detector.py]()\n\n### 4. 审计链 (Audit Chain)\n\n审计链提供加密可验证的完整性证明，确保记忆体的历史不可篡改。\n\n```mermaid\ngraph LR\n A[Block 1] -->|SHA3-512| B[Block 2]\n B -->|SHA3-512| C[Block 3]\n C -->|SHA3-512| D[Block N]\n D --> E[Merkle Root]\n \n F[Merkle Proof] --> G[验证包含性]\n```\n\n**审计工具清单**：\n\n| 工具 | 功能 | 输入 | 输出 |\n|------|------|------|------|\n| `verify_merkle` | Merkle包含证明 | block_id, content_hash | 证明 + ok标志 |\n| `verify_chain` | 哈希链验证 | workspace路径 | 完整性报告 |\n| `list_evidence` | 证据枚举 | block_id, action过滤 | 证据列表 |\n| `mind_mem_verify` | CLI审计入口 | snapshot路径 | 验证结果 |\n\n资料来源：[src/mind_mem/mcp/tools/audit.py:1-50]()\n\n## MCP 治理工具\n\n### propose_update - 提议更新\n\n创建新的决策或任务提议，写入 SIGNALS.md 待人工审核。\n\n**函数签名**：\n\n```python\ndef propose_update(\n block_type: str,\n statement: str,\n rationale: str = \"\",\n tags: str = \"\",\n confidence: str = \"medium\"\n) -> str\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `block_type` | str | 是 | 块类型 (DECISION/TASK) |\n| `statement` | str | 是 | 核心陈述 |\n| `rationale` | str | 否 | 变更理由 |\n| `tags` | str | 否 | 逗号分隔标签 |\n| `confidence` | str | 否 | 可信度 (low/medium/high) |\n\n**返回值示例**：\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"signal_id\": \"SIG-20260115-001\",\n \"message\": \"Proposal queued for review\"\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:50-80]()\n\n### approve_apply - 审批应用\n\n应用已通过的提议，支持干运行模式。\n\n**核心流程**：\n\n```mermaid\ngraph TD\n A[加载提议] --> B[干运行验证]\n B --> C{验证通过?}\n C -->|否| D[返回错误]\n C -->|是| E[创建快照]\n E --> F[应用变更]\n F --> G[更新索引]\n G --> H[清理信号]\n```\n\n**关键特性**：\n- 默认干运行 (`dry_run=True`)\n- 自动快照回滚点\n- 原子性事务保证\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:100-150]()\n\n### rollback_proposal - 回滚提案\n\n从预应用快照恢复工作区状态。\n\n```mermaid\ngraph LR\n A[当前状态] --> B[快照恢复]\n B --> C[索引回退]\n C --> D[信号重建]\n```\n\n**约束条件**：\n- 只能回滚处于待应用状态的提案\n- 快照必须在有效期内（默认7天）\n- 回滚本身会产生新的治理记录\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:150-200]()\n\n### scan - 完整性扫描\n\n执行综合健康检查，覆盖矛盾检测、漂移检测和待处理项。\n\n```python\ndef scan(workspace: str) -> dict:\n return {\n \"contradictions\": detect_all_contradictions(workspace),\n \"drift\": detect_drift(workspace),\n \"pending\": list_pending_signals(workspace),\n \"health_score\": calculate_health_score(workspace)\n }\n```\n\n**扫描子项**：\n\n| 子项 | 说明 | 阈值 |\n|------|------|------|\n| 矛盾数量 | 检测到的冲突证据对 | > 0 需关注 |\n| 漂移事件 | 偏离原声明的变更 | > 3 需关注 |\n| 待审批 | 队列中的提案数 | 无限制 |\n| 审计完整性 | 哈希链连续性 | 必须完整 |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:200-250]()\n\n### list_contradictions - 矛盾列表\n\n返回枚举的矛盾详情，支持富文本输出。\n\n**输出格式**：\n\n```json\n{\n \"contradictions\": [\n {\n \"entity_id\": \"PRJ-alpha\",\n \"severity\": \"high\",\n \"entries\": [\n {\n \"index\": 0,\n \"timestamp\": \"2026-01-10T09:00:00Z\",\n \"observation\": \"项目截止日期为 Q1\",\n \"confidence\": \"HIGH\",\n \"source\": \"decisions.md\"\n },\n {\n \"index\": 3,\n \"timestamp\": \"2026-01-12T14:30:00Z\",\n \"observation\": \"项目截止日期为 Q2\",\n \"confidence\": \"MEDIUM\",\n \"source\": \"tasks.md\"\n }\n ]\n }\n ]\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:250-300]()\n\n### governance_health_bench - 健康基准测试\n\n运行治理健康基准测试套件，验证矛盾检测、审计完整性、漂移检测和可扩展性。\n\n**测试子项**：\n\n| 测试 | 覆盖范围 | 预期结果 |\n|------|----------|----------|\n| 矛盾检测探针 | 人工构造的矛盾场景 | 100%检出 |\n| 审计完整性探针 | 哈希链断裂注入 | 正确检测 |\n| 漂移探针 | 状态偏离注入 | 正确识别 |\n| 可扩展性探针 | 大规模数据压力 | 性能可接受 |\n\n**返回值结构**：\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"tests_run\": 12,\n \"passed\": 11,\n \"failed\": 1,\n \"results\": [...]\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/benchmark.py:20-60]()\n\n## 编译真理页面 (Compiled Truth Page)\n\n编译真理页面是矛盾检测的核心载体，聚合实体的所有证据并自动编译权威理解。\n\n### 数据结构\n\n```python\n@dataclass\nclass CompiledTruthPage:\n entity_id: str # 实体标识符\n entity_type: str # 实体类型 (PER/PRJ/TOOL/INC)\n compiled_section: str # 编译后的权威理解\n evidence_entries: list[EvidenceEntry] # 证据条目列表\n last_compiled: str # ISO时间戳\n version: int # 版本号\n```\n\n### 证据条目\n\n```python\n@dataclass\nclass EvidenceEntry:\n timestamp: str # ISO 8601 时间戳\n source: str # 来源文件\n observation: str # 观察内容\n confidence: str # HIGH/MEDIUM/LOW\n superseded: bool # 是否已被取代\n```\n\n### 矛盾检测集成\n\n编译真理页面在重新编译时自动调用矛盾检测：\n\n```python\ndef recompile_truth(page: CompiledTruthPage) -> CompiledTruthPage:\n \"\"\"从非取代证据重新生成编译部分\"\"\"\n # 过滤非取代证据\n active_entries = [e for e in page.evidence_entries if not e.superseded]\n \n # 检测矛盾\n contradictions = detect_contradictions(page)\n \n # 生成报告\n for conflict in contradictions:\n _log.warning(\n \"contradiction_detected\",\n entity_id=page.entity_id,\n entry_a=conflict.entry_a,\n entry_b=conflict.entry_b\n )\n \n # 按时间戳排序，生成摘要\n ...\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:100-150]()\n\n### 证据取代机制\n\n当检测到矛盾时，可通过治理流程标记旧证据为 superseded：\n\n```python\ndef supersede_evidence(\n page: CompiledTruthPage,\n entry_index: int,\n reason: str\n) -> CompiledTruthPage:\n \"\"\"将证据标记为已取代\"\"\"\n new_entry = dataclasses.replace(\n page.evidence_entries[entry_index],\n superseded=True\n )\n new_entries = list(page.evidence_entries)\n new_entries[entry_index] = new_entry\n return dataclasses.replace(page, evidence_entries=new_entries)\n```\n\n**取代规则**：\n- 被取代证据仍保留在历史中，但计算时忽略\n- 取代操作本身产生新的治理记录\n- 新版本触发重新编译\n\n资料来源：[src/mind_mem/compiled_truth.py:150-200]()\n\n## 工作流示例\n\n### 决策变更完整流程\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP as MCP Server\n participant Store as Block Store\n participant Audit as Audit Chain\n participant Truth as Compiled Truth\n\n Agent->>MCP: propose_update(DECISION, \"变更X\")\n MCP->>Store: 写入SIGNALS.md\n Note over MCP: 状态: PENDING\n\n Agent->>MCP: approve_apply(SIG-xxx, dry_run=true)\n MCP->>Truth: 检查矛盾\n Truth-->>MCP: 无冲突\n\n Agent->>MCP: approve_apply(SIG-xxx, dry_run=false)\n MCP->>Store: 创建快照\n MCP->>Store: 应用变更\n MCP->>Audit: 更新哈希链\n Note over MCP: 状态: APPLIED\n\n Agent->>MCP: scan()\n MCP-->>Agent: 健康报告\n```\n\n### 矛盾处理流程\n\n```mermaid\ngraph TD\n A[检测到矛盾] --> B{自动解决可能?}\n B -->|否| C[人工审核]\n C --> D[审查证据]\n D --> E[选择保留哪条]\n E --> F[取代旧证据]\n B -->|是| G[自动取代低可信度]\n G --> F\n F --> H[重新编译]\n H --> I[生成新版本]\n I --> J[更新审计链]\n```\n\n## 配置选项\n\n### 矛盾检测配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `contradiction_min_confidence_gap` | 0.3 | 最低可信度差距 |\n| `auto_supersede_low_confidence` | true | 自动取代低可信度 |\n| `contradiction_alert_threshold` | 2 | 告警阈值 |\n\n### 审计配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `hash_algorithm` | SHA3-512 | 哈希算法 |\n| `merkle_update_on_write` | true | 写入时更新Merkle树 |\n| `audit_retention_days` | 365 | 审计保留天数 |\n\n### 漂移检测配置\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `drift_check_interval_hours` | 24 | 检查间隔 |\n| `drift_tolerance_priority` | 2 | 优先级容差 |\n| `drift_tolerance_date_days` | 7 | 日期容差 |\n\n## 相关命令\n\n### mm CLI 治理命令\n\n```bash\n# 提议新决策\nmm governance propose --type DECISION --statement \"采用新技术栈\"\n\n# 应用审批\nmm governance approve SIG-20260115-001\n\n# 回滚操作\nmm governance rollback SIG-20260115-001\n\n# 运行健康扫描\nmm governance scan\n\n# 列出矛盾\nmm governance contradictions --entity PRJ-alpha\n\n# 验证审计链\nmm verify --type chain\n```\n\n### MCP 工具调用\n\n```json\n{\n \"tool\": \"propose_update\",\n \"arguments\": {\n \"block_type\": \"DECISION\",\n \"statement\": \"迁移至微服务架构\",\n \"rationale\": \"提升可扩展性\",\n \"tags\": \"architecture, refactor\",\n \"confidence\": \"high\"\n }\n}\n```\n\n## 最佳实践\n\n### 1. 矛盾预防\n- 在添加新证据前先查询现有编译真理页面\n- 使用高可信度来源标注证据\n- 避免重复提交相似陈述\n\n### 2. 治理流程\n- 干运行优先，正式应用前验证\n- 保持提议的原子性描述\n- 定期运行健康扫描\n\n### 3. 审计合规\n- 验证哈希链完整性作为CI/CD环节\n- 保留足够的快照以支持回滚\n- 监控审计链验证失败事件\n\n## 总结\n\n治理与矛盾检测模块为 mind-mem 提供了企业级的记忆管理安全保障。通过\"提议-审批-应用-回滚\"的完整生命周期管理，确保了所有变更的可追溯性和可控性。矛盾检测与编译真理页面的深度集成，使得知识库的权威性得到持续维护，而审计链则为整个系统提供了密码学级别的完整性保证。\n\n---\n\n\n\n## 质量保障与验证\n\n### 相关页面\n\n相关主题：[治理与矛盾检测](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n- [src/mind_mem/block_parser.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)\n- [src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n- [src/mind_mem/model_provenance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)\n- [src/mind_mem/mcp/tools/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n \n\n# 质量保障与验证\n\nmind-mem 采用多层次的质量保障体系，确保记忆块的可靠性、一致性和安全性。系统从内容存储前的预处理、解析时的验证、到运行时的矛盾检测，形成了完整的质量闭环。\n\n## 质量门禁（Quality Gate）\n\n质量门禁是记忆块写入前的第一道防线，位于 `src/mind_mem/quality_gate.py`。它是一个确定性、基于内容的预存储过滤器，对候选块进行检查并返回结构化裁决。\n\n### 核心规则\n\n质量门禁包含八条规则，全部为确定性规则，不依赖外部服务：\n\n| 规则标识 | 规则名称 | 检查条件 | 处理方式 |\n|---------|---------|---------|---------|\n| `empty` | 空块检测 | 块内容为纯空白字符 | 标记并可拒绝 |\n| `too_short` | 过短检测 | 非空白字符少于 32 个 | 标记并可拒绝 |\n| `oversize` | 超大检测 | UTF-8 编码超过 64 KiB | 标记并可拒绝 |\n| `malformed_utf8` | UTF-8 损坏检测 | 包含孤立代理或无法通过 UTF-8 往返 | 标记并可拒绝 |\n| `stopwords_only` | 停用词检测 | 所有 token 均为停用词，无语义内容 | 标记并可拒绝 |\n| `near_duplicate` | 近似重复检测 | 与 24 小时内块编辑距离相似度 ≥ 0.97 | 标记并可拒绝 |\n| `injection_marker` | 注入标记检测 | 匹配已知提示注入模式 | 标记并可拒绝 |\n| `ok` | 通过 | 无规则触发 | 接受 |\n\n### 裁决模式\n\n质量门禁支持两种裁决模式：\n\n- **顾问模式（默认）**：每条规则都会被记录，但裁决仍返回 `accept`\n- **严格模式（strict）**：任何规则触发都导致 `reject`\n\n严格模式可通过以下方式启用：\n1. 调用时传入 `strict=True` 关键字参数\n2. 工作区 `QualityGateConfig(mode=\"strict\")`\n3. 工作区配置 `mind-mem.json` 中的 `quality_gate_mode = \"strict\"`\n\n### 工作流程\n\n```mermaid\ngraph TD\n A[接收候选块] --> B[执行 8 条规则检查]\n B --> C{触发任何规则?}\n C -->|否| D[裁决: accept]\n C -->|是| E{strict 模式?}\n E -->|否| F[记录日志]\n F --> D\n E -->|是| G[裁决: reject]\n D --> H[写入存储]\n G --> I[返回错误信息]\n```\n\n### 返回数据结构\n\n```python\n@dataclass\nclass Verdict:\n decision: Literal[\"accept\", \"reject\"]\n fired_rules: list[str] # 触发的规则列表\n score: float # 质量分数 0.0-1.0\n reason: Optional[str] # 拒绝原因描述\n```\n\n资料来源：[src/mind_mem/quality_gate.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n\n## 块解析质量控制\n\n`src/mind_mem/block_parser.py` 负责从文本中解析记忆块，解析过程内置了多项质量验证机制。\n\n### UTF-8 BOM 处理\n\n解析器首先检查并处理 UTF-8 BOM（Byte Order Mark）：\n\n```python\nif text.startswith(''):\n text = text[1:]\n```\n\n这确保第一个块头不会被 BOM 字符遮挡，保证解析的一致性。\n\n### 否定块识别\n\n系统内置否定块检测正则表达式，用于识别语义反转的声明：\n\n```python\n_NEGATION_RE = re.compile(\n r\"\\b(not|never|don't|won't|shouldn't|cannot|can't|...\"\n r\"|no\\s+\\w+|none)\\b\",\n re.IGNORECASE,\n)\n```\n\n这对于矛盾检测和语义理解具有重要意义。\n\n### ConstraintSignature 解析\n\nv2.0 版本支持结构化的 ConstraintSignature 解析，识别以下嵌套字段：\n\n| 字段名 | 用途 |\n|-------|------|\n| `scope` | 约束作用范围 |\n| `axis` | 约束维度 |\n| `lifecycle` | 生命周期阶段 |\n\n解析器维护内部状态机，正确处理嵌套结构和操作符列表。\n\n资料来源：[src/mind_mem/block_parser.py:1-80](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_parser.py)\n\n## 编译真相与矛盾检测\n\n编译真相（Compiled Truth）是 mind-mem 的核心概念之一，位于 `src/mind_mem/compiled_truth.py`。它通过聚合证据来维护实体的规范理解。\n\n### 证据条目结构\n\n```python\n@dataclass\nclass EvidenceEntry:\n timestamp: str # ISO 时间戳\n source: str # 来源标识\n observation: str # 观察内容\n confidence: str # 置信度: high/medium/low\n superseded: bool # 是否已被替代\n```\n\n### 编译真相页面结构\n\n| 字段 | 说明 |\n|-----|------|\n| `entity_id` | 实体唯一标识符 |\n| `entity_type` | 实体类型 |\n| `compiled_section` | 当前规范理解（摘要） |\n| `evidence_entries` | 证据条目列表 |\n| `last_compiled` | 最后编译时间 |\n| `version` | 版本号 |\n\n### 矛盾检测\n\n系统提供 `detect_contradictions()` 函数用于检测编译真相页面中的矛盾：\n\n```python\ndef detect_contradictions(page: CompiledTruthPage) -> list[ContradictionPair]:\n \"\"\"检测页面中的矛盾证据对\"\"\"\n```\n\n矛盾检测通过以下步骤工作：\n1. 遍历所有未废弃的证据条目\n2. 比较语义相反的陈述\n3. 识别否定关系（如 \"应该使用 X\" vs \"不应该使用 X\"）\n4. 返回矛盾对列表\n\n### 证据替代机制\n\n当新证据与旧证据矛盾时，系统支持标记旧证据为已废弃：\n\n```python\ndef supersede_evidence(\n page: CompiledTruthPage,\n entry_index: int,\n reason: str\n) -> CompiledTruthPage:\n```\n\n替代后的旧证据保留在历史中，但不影响规范理解的生成。\n\n资料来源：[src/mind_mem/compiled_truth.py:1-150](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## 治理工具与矛盾扫描\n\nMCP 工具提供程序化的质量保障能力，位于 `src/mind_mem/mcp/tools/governance.py`。\n\n### 可用工具\n\n| 工具名称 | 功能 |\n|---------|------|\n| `propose_update` | 提议新决策或任务，写入 SIGNALS.md 待人工审核 |\n| `approve_apply` | 应用已提议的更新（默认干跑模式） |\n| `rollback_proposal` | 从预应用快照恢复工作区 |\n| `scan` | 完整性扫描（矛盾/漂移/待处理） |\n| `list_contradictions` | 矛盾列表的富文本展示 |\n| `memory_evolution` | 获取块的 A-MEM 元数据 |\n\n### 扫描操作\n\n`scan` 工具执行三类检查：\n\n1. **矛盾检测**：识别同一实体的相互冲突的证据\n2. **漂移检测**：检测规范理解与实际证据的不一致\n3. **待处理检测**：列出未处理的信号和提案\n\n### SQLite 锁处理\n\n扫描操作使用 SQLite 数据库，工具内置锁冲突处理：\n\n```python\ndef _is_db_locked(exc: Exception) -> bool:\n return \"database is locked\" in str(exc)\n\ndef _sqlite_busy_error(result: str, exc: Exception) -> str:\n return json.dumps({\"error\": f\"DB locked: {exc}\", \"retry\": True})\n```\n\n资料来源：[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)\n\n## 模型溯源验证\n\n`src/mind_mem/model_provenance.py` 提供模型出处检查能力，确保引用的模型信息准确。\n\n### 支持的发布商\n\n| 发布商 | Slug 标识 | 模型家族 |\n|-------|----------|---------|\n| Meta Llama | `meta-llama` | Llama 2/3/4 |\n| Mistral | `mistralai` | Mistral/Mixtral/Codestral |\n| Google Gemma | `google` | Gemma/Gemma-2/PaLM |\n| IBM Granite | `ibm-granite`, `ibm` | Granite-3/Granite-Code |\n| DeepSeek | `deepseek-ai` | DeepSeek-V2/V3/R1 |\n| Microsoft Phi | `microsoft` | Phi-2/Phi-3/Phi-4 |\n| TII Falcon | `tiiuae` | Falcon-7B/40B/180B |\n\n### ProvenanceFinding 结果\n\n```python\n@dataclass\nclass ProvenanceFinding:\n passed: bool # 检查是否通过\n publisher: Optional[str] # 识别的发布商\n model_family: Optional[str] # 模型家族\n confidence: float # 置信度 0.0-1.0\n```\n\n资料来源：[src/mind_mem/model_provenance.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/model_provenance.py)\n\n## 删除恢复与审计\n\n系统维护删除操作的全量审计日志，支持误删恢复。\n\n### 删除收据格式\n\n删除块时，系统将删除收据写入 `memory/deleted_blocks.jsonl`：\n\n```json\n{\n \"block_id\": \"D-20260213-001\",\n \"deleted_at\": \"2026-03-15T10:30:00+00:00\",\n \"content\": \"原始块内容...\"\n}\n```\n\n### 块定位逻辑\n\n删除收据记录使用与 `mcp.tools.memory_ops.delete_memory_item` 相同的边界规则：\n- 块从 `[]` 行开始\n- 块结束于下一个 `[]` 头行、孤立的 `---` 分隔符或 EOF\n\n这确保两个删除路径收敛到同一恢复日志格式。\n\n资料来源：[src/mind_mem/block_store.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n## 配置与指标\n\n### 质量门禁配置优先级\n\n```\n1. 函数调用 strict=True 参数（最高优先级）\n2. QualityGateConfig(mode=\"strict\") 对象\n3. mind-mem.json 中的 quality_gate_mode 设置\n4. 默认值（advisory 模式）\n```\n\n### 质量指标\n\n系统通过 `metrics.inc()` 追踪质量事件：\n\n| 指标名称 | 触发场景 |\n|---------|---------|\n| `truth_pages_loaded` | 编译真相页面加载 |\n| `evidence_entries_superseded` | 证据被替代 |\n| `mcp_compiled_truth_add_evidence` | 添加新证据 |\n| `contradictions_detected` | 检测到矛盾 |\n\n### 日志记录\n\n质量事件通过结构化日志记录：\n\n```python\n_log.info(\n \"evidence_superseded\",\n entity_id=page.entity_id,\n index=entry_index,\n reason=reason,\n)\n```\n\n日志输出到 `MIND_MEM_LOG_FILE` 或标准输出。\n\n## 最佳实践\n\n### 启用严格模式\n\n对于生产环境，建议在工作区配置中启用严格模式：\n\n```json\n{\n \"quality_gate_mode\": \"strict\"\n}\n```\n\n### 定期扫描\n\n使用 MCP 工具 `scan` 定期检查工作区一致性：\n\n```bash\nmm mcp call scan --scan-type full\n```\n\n### 矛盾审查\n\n当检测到矛盾时，通过 `list_contradictions` 工具获取详细信息：\n\n```bash\nmm mcp call list_contradictions\n```\n\n### 删除恢复\n\n误删块后，可通过 `deleted_blocks.jsonl` 恢复内容：\n\n```bash\n# 查看最近删除\ntail -n 10 memory/deleted_blocks.jsonl\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：star-ga/mind-mem\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)。\n\n## 1. 安装坑 · 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_366d8c18c1aa45ffb07174af516285d4 | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing\n\n## 8. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-251)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e9c9207806f46a6a90a83828e99c173 | https://github.com/star-ga/mind-mem/issues/529 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ea39fdeb939e484a9be8751555483fc5 | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d71f093408f04636bc91f85df44c811d | https://github.com/star-ga/mind-mem/issues/508 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7bf148881d754982a8b6bbb0959436d0 | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_afb67087422e43678c941140da7019de | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0917cf4b43b34ffe8d43e599d353665c | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad9e7a85457041afbc88c886568b2657 | https://github.com/star-ga/mind-mem/issues/511 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_32106da2cae04c0185f7a6331cd1ef8a | https://github.com/star-ga/mind-mem/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport.py:687-694)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7bba956cb937439b85b35fb2c150b7e2 | https://github.com/star-ga/mind-mem/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：star-ga/mind-mem\n\n摘要：发现 21 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)。\n\n## 1. 安装坑 · 来源证据：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm doctor --rebuild-cache` errors=263 (no such table: blocks)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_366d8c18c1aa45ffb07174af516285d4 | https://github.com/star-ga/mind-mem/issues/524 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：PG-backed: `mm recall` returns [] despite direct PG FTS finding matches\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ba0bc6a7eec24a3a963611eac1e66e9f | https://github.com/star-ga/mind-mem/issues/525 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Perf regression: build_index on a fresh 80KB workspace takes ~55s\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af7792e47f904c0ea9362c21e6944c19 | https://github.com/star-ga/mind-mem/issues/530 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1160652179 | https://github.com/star-ga/mind-mem | host_targets=mcp_host, claude, claude_code, cursor\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1160652179 | https://github.com/star-ga/mind-mem | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 来源证据：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：test_rollback_removes_new_files fails on macOS + Windows runners (passes on Linux)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e1922336b59a45f889940eab33dba770 | https://github.com/star-ga/mind-mem/issues/515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | last_activity_observed missing\n\n## 8. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1160652179 | https://github.com/star-ga/mind-mem | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ACL `_get_request_scope` fail-open on token-introspection exception (acl.py:139-142)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0a6d1439d14f4eb79c2e37a14ed436b0 | https://github.com/star-ga/mind-mem/issues/526 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 安全/权限坑 · 来源证据：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FederationClient: no scheme allowlist, no redirect cap, no response-size cap, no TLS pinning (federation_client.py:240-251)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1e9c9207806f46a6a90a83828e99c173 | https://github.com/star-ga/mind-mem/issues/529 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 安全/权限坑 · 来源证据：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：THREE_WAY_MERGE doesn't bump vclock — resolved conflicts recur on every detect_conflict pass (federation.py:359-360)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ea39fdeb939e484a9be8751555483fc5 | https://github.com/star-ga/mind-mem/issues/527 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CRITICAL] N-01 / T-002: Default-on ACL gate (admin tools open with MIND_MEM_ADMIN_TOKEN unset)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d71f093408f04636bc91f85df44c811d | https://github.com/star-ga/mind-mem/issues/508 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[HIGH] T-006: Bound vault_scan / vault_sync filesystem walks (arbitrary host markdown exfil)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7bf148881d754982a8b6bbb0959436d0 | https://github.com/star-ga/mind-mem/issues/509 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-02: REST rollback_proposal silently drops 'reason' field\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_afb67087422e43678c941140da7019de | https://github.com/star-ga/mind-mem/issues/510 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-03: Rate limiter collapses all stdio clients into 'default' bucket\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0917cf4b43b34ffe8d43e599d353665c | https://github.com/star-ga/mind-mem/issues/513 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] N-04: staged_change rollback dispatcher silently drops 'reason'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ad9e7a85457041afbc88c886568b2657 | https://github.com/star-ga/mind-mem/issues/511 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MEDIUM] T-003: propose_update input bounds bypass (rationale/tags written verbatim to SIGNALS.md)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_32106da2cae04c0185f7a6331cd1ef8a | https://github.com/star-ga/mind-mem/issues/512 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport…\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：`_handle_fed_resolve` accepts caller-supplied merged_payload without validating it against the conflict (http_transport.py:687-694)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7bba956cb937439b85b35fb2c150b7e2 | https://github.com/star-ga/mind-mem/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | issue_or_pr_quality=unknown\n\n## 21. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1160652179 | https://github.com/star-ga/mind-mem | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mind-mem - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mind-mem 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想检查一个 AI 工具或 Agent 工作流在权限、提示注入和数据泄露上的风险。\n我常用的宿主 AI：MCP Client / claude / Claude Code / Cursor\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：MIND-Mem简介。围绕“MIND-Mem简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-features：核心功能一览。围绕“核心功能一览”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-data-flow：数据流与处理管道。围绕“数据流与处理管道”模拟一次用户任务，不展示安装或运行结果。\n5. page-storage：存储后端。围绕“存储后端”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“MIND-Mem简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-features\n输入：用户提供的“核心功能一览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-data-flow\n输入：用户提供的“数据流与处理管道”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-storage\n输入：用户提供的“存储后端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“MIND-Mem简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-features：Step 2 必须围绕“核心功能一览”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-data-flow：Step 4 必须围绕“数据流与处理管道”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-storage：Step 5 必须围绕“存储后端”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/star-ga/mind-mem\n- https://github.com/star-ga/mind-mem#readme\n- .agents/skills/mind-mem-development/SKILL.md\n- skills/apply-proposal/SKILL.md\n- skills/integrity-scan/SKILL.md\n- skills/memory-recall/SKILL.md\n- README.md\n- SPEC.md\n- mind/recall.mind\n- mind/governance.mind\n- mind/mic_map_quickstart.py\n- docs/architecture.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mind-mem 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：star-ga/mind-mem\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install mind-mem\n```\n\n来源：https://github.com/star-ga/mind-mem#readme\n\n## 来源\n\n- repo: https://github.com/star-ga/mind-mem\n- docs: https://github.com/star-ga/mind-mem#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_70536ae0c26943dab978c2fbdfba0cd9"
}