{
"canonical_name": "star-ga/mind-mem",
"compilation_id": "pack_9608c25f8b284fa58a19ea7b37eec7fb",
"created_at": "2026-05-17T19:30:39.728799+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": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"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 工具",
"知识库问答",
"多 Agent 协作",
"断点恢复流程",
"评测体系"
],
"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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for star-ga/mind-mem.\n\nProject:\n- Name: mind-mem\n- Repository: https://github.com/star-ga/mind-mem\n- Summary: 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.\n- Host target: mcp_host, claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 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.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. page-key-concepts: Key Concepts. Produce one small intermediate artifact and wait for confirmation.\n3. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n4. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n5. page-components: Core Components. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- docs/architecture.md\n- docs/block-format.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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 工具",
"知识库问答",
"多 Agent 协作",
"断点恢复流程",
"评测体系"
],
"thumb": "purple",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/star-ga/mind-mem 项目说明书\n\n生成时间：2026-05-17 19:29:27 UTC\n\n## 目录\n\n- [Overview](#page-overview)\n- [Key Concepts](#page-key-concepts)\n- [Quick Start Guide](#page-quickstart)\n- [System Architecture](#page-architecture)\n- [Core Components](#page-components)\n- [Hybrid Search & Retrieval](#page-hybrid-search)\n- [Knowledge Graph & Entity Management](#page-knowledge-graph)\n- [Governance & Safety](#page-governance)\n- [Block Format & Data Model](#page-data-model)\n- [MCP Server & Tools](#page-mcp-server)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart), [MCP Server & Tools](#page-mcp-server)\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/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/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/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/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [src/mind_mem/protection.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/protection.py)\n \n\n# Overview\n\n**MIND-Mem** is a multi-agent memory and knowledge management system designed to provide persistent, queryable memory for AI coding assistants. It maintains a structured workspace containing decisions, tasks, entities, signals, and contradictions—enabling AI agents to recall relevant context across sessions while enforcing governance rules that prevent unauthorized memory modifications.\n\n## Purpose and Scope\n\nMIND-Mem solves the context window exhaustion problem in long-running AI-assisted development by:\n\n- **Storing structured memories** in markdown files organized by type (DECISIONS.md, TASKS.md, entities, signals)\n- **Providing fast retrieval** via BM25 full-text search and FTS5 SQLite indexes\n- **Enforcing governance** through a propose → approve → apply workflow\n- **Maintaining audit trails** with SHA3-512 hash chains and Merkle proofs\n- **Supporting compiled truth pages** that aggregate evidence for key entities\n\n资料来源：[src/mind_mem/compiled_truth.py:1-30]()\n\n## Architecture Overview\n\nThe system consists of several interconnected layers:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[CLI mm]\n MCP[MCP Server]\n WEB[Web Console]\n end\n \n subgraph \"Core Engine\"\n RECALL[Recall Engine]\n IDX[FTS5 Index]\n GOV[Governance]\n AUDIT[Audit Chain]\n end\n \n subgraph \"Storage Layer\"\n MARKDOWN[Markdown Files]\n SQLITE[SQLite DB]\n KERNEL[.mind Kernel Configs]\n end\n \n CLI --> MCP\n WEB --> RECALL\n RECALL --> IDX\n RECALL --> MARKDOWN\n GOV --> MARKDOWN\n AUDIT --> IDX\n KERNEL --> RECALL\n```\n\n资料来源：[src/mind_mem/mm_cli.py:1-25]()\n\n## Workspace Structure\n\nEach workspace managed by MIND-Mem follows a canonical directory layout:\n\n| Directory | Purpose |\n|-----------|---------|\n| `memory/` | Individual memory blocks as markdown files |\n| `entities/` | Entity definitions and compiled truth pages |\n| `compiled/` | Compiled truth pages (`entities/compiled/`) |\n| `.mind/` | MIND kernel configuration files |\n| `signals/` | Staged governance proposals |\n| `snapshots/` | Pre-apply rollback snapshots |\n\n资料来源：[src/mind_mem/compiled_truth.py:80-100]()\n\n## MCP Server Surface\n\nThe MCP (Model Context Protocol) server exposes a comprehensive tool surface organized into domains:\n\n### Core Tool Domains\n\n| Domain | Tools | Purpose |\n|--------|-------|---------|\n| **Governance** | `propose_update`, `approve_apply`, `rollback_proposal`, `scan`, `list_contradictions`, `memory_evolution` | Memory modification workflow |\n| **Memory Ops** | `index_stats`, `reindex`, `delete_memory_item`, `export_memory`, `get_block`, `memory_health`, `compact`, `stale_blocks` | Workspace lifecycle |\n| **Kernels** | `list_mind_kernels`, `get_mind_kernel`, `compiled_truth_load`, `compiled_truth_add_evidence`, `compiled_truth_contradictions` | Kernel configuration access |\n| **Audit** | `verify_merkle`, `verify_chain`, `list_evidence`, `mind_mem_verify` | Integrity verification |\n| **Benchmark** | `governance_health_bench`, `category_summary` | Health diagnostics |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-30]()\n\n### MCP Resources\n\nThe server also exposes read-only resources via the MCP resource protocol:\n\n| Resource URI | Content |\n|--------------|---------|\n| `mind-mem://decisions` | Active decisions from DECISIONS.md |\n| `mind-mem://tasks` | All tasks from TASKS.md |\n| `mind-mem://entities/{type}` | Projects, people, tools, incidents |\n| `mind-mem://signals` | Auto-captured signals |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search results |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\n资料来源：[src/mind_mem/mcp/resources.py:1-40]()\n\n## CLI Interface\n\nThe `mm` command provides a unified interface for non-MCP agents:\n\n```bash\nmm recall \"\" # Search memory with BM25\nmm context \"\" # Generate token-budgeted snippet\nmm inject --agent \"\" # Render snippet for specific agent\nmm vault scan # List parsed vault blocks (JSON)\nmm vault write --type --body \nmm status # Workspace summary\n```\n\n资料来源：[src/mind_mem/mm_cli.py:30-55]()\n\n## Governance Model\n\nMIND-Mem enforces an invariant: **memory is never modified except by governance**. The governance workflow:\n\n```mermaid\ngraph LR\n A[Propose] --> B{Human Review}\n B -->|Approved| C[Apply/Dry-Run]\n B -->|Rejected| D[Discard]\n C -->|Dry-Run| E[Review Changes]\n E -->|Confirm| F[Commit]\n F --> G[Snapshot Stored]\n C -->|Direct| F\n G --> H[Rollback Available]\n```\n\nKey governance tools:\n- `propose_update` — Stage a new decision/task as a SIGNAL\n- `approve_apply` — Apply a staged proposal (dry-run by default)\n- `rollback_proposal` — Restore workspace from pre-apply snapshot\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:35-60]()\n\n## Compiled Truth System\n\nCompiled truth pages aggregate evidence for key entities, enabling efficient retrieval of canonical understanding:\n\n```mermaid\ngraph TD\n A[Memory Files] --> B[Sentence Extraction]\n B --> C[Fact Candidates]\n C --> D{min_mentions?}\n D -->|≥3| E[Promote to Truth]\n E --> F[Compiled Section]\n G[New Evidence] --> H[Add Entry]\n H --> I[Recompile]\n I --> F\n```\n\nThe system supports:\n- **Evidence entries** with timestamps, sources, and confidence levels\n- **Superseding** outdated evidence\n- **Version tracking** with recompilation\n\n资料来源：[src/mind_mem/compiled_truth.py:150-200]()\n\n## Integrity and Audit\n\nMIND-Mem provides cryptographic integrity guarantees:\n\n### Protection Module\n\nThe protection system validates critical module integrity:\n\n- **Critical modules** include recall, vector search, apply engine, audit chain, encryption, graph recall, rerank ensemble, consensus vote, tenant audit, and governance\n- **Integrity manifest** (`_integrity_manifest.json`) stores SHA-256 hashes\n- **Strict mode** available via `MIND_MEM_INTEGRITY` environment variable\n\n资料来源：[src/mind_mem/protection.py:35-60]()\n\n### Audit Chain\n\n| Verification Type | Description |\n|-------------------|-------------|\n| **Merkle Proofs** | Prove block inclusion against live Merkle tree |\n| **Hash Chain** | SHA3-512 chain verification for governance records |\n| **Evidence Chain** | Walk and verify evidence relationships |\n| **Manifest Signing** | Ed25519 signatures on model audit checkpoints |\n\n资料来源：[src/mind_mem/mcp/tools/audit.py:1-30]()\n\n## Agent Integration\n\nMIND-Mem supports integration with various AI coding assistants through a declarative registry:\n\n| Agent | Config Format | Status |\n|-------|---------------|--------|\n| Claude | JSON/CLaude Desktop | Configurable |\n| Cursor | Custom config | Hook-based |\n| Windsurf | Custom config | Hook-based |\n| Codex CLI | MCP native | Supported |\n\nThe hook installer resolves the MCP server path through:\n1. `MIND_MEM_MCP_SERVER` environment variable (explicit override)\n2. `/../mcp_server.py` (src-layout checkout)\n3. `/mcp_server.py` (packaged install)\n\n资料来源：[src/mind_mem/hook_installer.py:20-45]()\n\n## v4.0 Surface\n\nThe v4.0 implementation is gated by feature flags in `mind-mem.json` under the `v4` key:\n\n| Group | Features |\n|-------|----------|\n| **A. Cognition** | Tier-aware blocks, Cognitive Mind Kernel API, surprise-weighted retrieval |\n| **B. Knowledge Graph** | Block kinds, long-context recall, LLM fusion, streaming, conversational chat |\n| **C. Governance UX** | Idle ingest, AI lint, contradiction states, self-healing index |\n\nWithout the feature flag, v3.x behavior is preserved unchanged.\n\n资料来源：[src/mind_mem/v4/__init__.py:1-40]()\n\n## Web Console\n\nA Next.js web interface provides visual exploration:\n\n```mermaid\ngraph LR\n A[API /v1/recall] --> B[Bundle Response]\n B --> C[GraphView]\n B --> D[TimelineView]\n B --> E[FactList]\n C --> F[d3-force graph]\n D --> G[Chronological events]\n E --> H[Extracted claims]\n```\n\nComponents:\n- `app/page.tsx` — Single-page console\n- `components/GraphView.tsx` — Force-directed block graph\n- `components/TimelineView.tsx` — Dated events timeline\n- `components/FactList.tsx` — Extracted facts with confidence\n\n资料来源：[web/README.md:1-30]()\n\n## Configuration\n\n### Workspace Resolution\n\nThe workspace is resolved in order:\n1. `MIND_MEM_WORKSPACE` environment variable\n2. Current working directory (`cwd`)\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### MCP Server Invocation\n\nThe canonical MCP server invocation record:\n\n```python\n{\n \"command\": \"python3\",\n \"args\": [\"mcp_server.py\"],\n \"env\": {\"MIND_MEM_WORKSPACE\": workspace}\n}\n```\n\n资料来源：[src/mind_mem/hook_installer.py:50-70]()\n\n## Quick Start\n\n```bash\n# Install\npip install -e .\n\n# Initialize workspace\nmm status\n\n# Search memory\nmm recall \"authentication\"\n\n# Context for agent\nmm context \"database schema\"\n\n# Web interface\ncd web && pnpm install && pnpm dev\n```\n\n资料来源：[examples/README.md:1-20]()\n\n## Summary\n\nMIND-Mem provides a robust multi-agent memory system with:\n\n- **Structured storage** for decisions, tasks, entities, and signals\n- **Fast retrieval** via BM25 and FTS5 indexes\n- **Governance-first** memory modification workflow\n- **Cryptographic integrity** through Merkle proofs and hash chains\n- **Extensive tooling** via CLI, MCP server, and web console\n- **Agent integration** support for Claude, Cursor, Codex, and more\n\n---\n\n\n\n## Key Concepts\n\n### 相关页面\n\n相关主题：[Overview](#page-overview), [Block Format & Data Model](#page-data-model), [Governance & Safety](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/block-format.md](https://github.com/star-ga/mind-mem/blob/main/docs/block-format.md)\n- [docs/mic-map.md](https://github.com/star-ga/mind-mem/blob/main/docs/mic-map.md)\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/namespaces.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/namespaces.py)\n- [src/mind_mem/mcp/infra/acl.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/infra/acl.py)\n \n\n# Key Concepts\n\nMind-Mem is a persistent memory system designed for multi-agent workflows. It stores structured knowledge as markdown \"blocks\" that can be recalled, reasoned about, and governed by a set of declarative rules. Understanding the core data model and access control mechanisms is essential for effective use.\n\n---\n\n## Block Format\n\n### Overview\n\nBlocks are the fundamental storage unit in Mind-Mem. Each block represents a discrete unit of knowledge—a decision, task, signal, fact, or entity record—stored as structured Markdown with a consistent header format.\n\n```mermaid\ngraph LR\n A[Block Header
[ID]] --> B[Field: Value]\n B --> C[Field: Value]\n C --> D[Blank Line]\n D --> E[Optional Body
Content]\n E --> F[Block Separator
---]\n```\n\n资料来源：[src/mind_mem/block_store.py:1-50]()\n\n### Block Header Structure\n\nEvery block begins with a unique identifier in the format `[block-id]`:\n\n```\n[Dcision-2024-001]\n\nStatement: PostgreSQL shall be the primary relational store\nDate: 2024-01-15\nStatus: Active\nType: Decision\nRationale: Proven reliability and extensive tooling ecosystem\nConfidence: high\nTags: infrastructure, database, postgresql\n```\n\n资料来源：[docs/block-format.md:1-30]()\n\n### Canonical Field Order\n\nBlocks emit fields in a fixed order to ensure deterministic round-trips:\n\n| Order | Field | Description |\n|-------|-------|-------------|\n| 1 | `Statement` | Core claim or action |\n| 2 | `Date` | ISO-8601 timestamp |\n| 3 | `Status` | Active, Superseded, Deprecated |\n| 4 | `Priority` | High, Medium, Low |\n| 5 | `Risk` | Risk assessment level |\n| 6 | `Type` | Decision, Task, Signal, Fact, Entity |\n| 7 | `Subject` | Primary entity of interest |\n| 8 | `Object` | Secondary entity or target |\n| 9 | `Tags` | Comma-separated labels |\n| 10 | `Rationale` | Explanation or justification |\n| 11 | `Evidence` | Supporting data or references |\n| 12 | `Source` | Origin of the information |\n| 13 | `Confidence` | low, medium, high |\n| 14 | `ContentHash` | SHA-256 content fingerprint |\n| 15 | `Excerpt` | Brief summary |\n| 16 | `Action` | Next step or task |\n\n资料来源：[src/mind_mem/block_store.py:180-200]()\n\n### Block Types and Prefixes\n\nMind-Mem uses a prefix-based mapping system to organize blocks into subdirectories:\n\n| Block Type | Prefix | Storage Path |\n|------------|--------|--------------|\n| Decision | `D` | `decisions/` |\n| Task | `T` | `tasks/` |\n| Signal | `S` | `signals/` |\n| Fact | `F` | `facts/` |\n| Entity | `E` | `entities/` |\n| Note | `N` | `notes/` |\n| Project | `P` | `projects/` |\n\n资料来源：[src/mind_mem/block_store.py:160-175]()\n\n### Forbidden Write Fields\n\nThe following synthetic fields are emitted during parsing but are never persisted back to storage:\n\n- `_id` — synthetic parse-time block identifier\n- `_source_file` — tool-side hint for source tracking\n- `_line_number` — original file location\n- `_raw` — unprocessed block content\n\n资料来源：[src/mind_mem/block_store.py:201-205]()\n\n---\n\n## Namespaces\n\n### Overview\n\nNamespaces provide logical isolation between different workspaces, tenants, or organizational units within Mind-Mem. They ensure that blocks and their associated metadata remain segregated while sharing common infrastructure.\n\n```mermaid\ngraph TD\n subgraph Workspace1\n NS1[namespace: default]\n B1[Block Store]\n NS1 --> B1\n end\n \n subgraph Workspace2\n NS2[namespace: project-a]\n B2[Block Store]\n NS2 --> B2\n end\n \n subgraph Shared\n ACL[Access Control List]\n Meta[Metadata Index]\n end\n \n NS1 --> ACL\n NS2 --> ACL\n```\n\n资料来源：[src/mind_mem/namespaces.py:1-40]()\n\n### Namespace Resolution\n\nNamespaces are resolved in the following priority order:\n\n1. Explicit `namespace` parameter in API calls\n2. `MIND_MEM_NAMESPACE` environment variable\n3. Workspace-specific configuration in `mind-mem.json`\n4. Default namespace (`default`)\n\n```python\ndef resolve_namespace(workspace: str, explicit: Optional[str] = None) -> str:\n if explicit:\n return explicit\n env_namespace = os.environ.get(\"MIND_MEM_NAMESPACE\")\n if env_namespace:\n return env_namespace\n config = load_workspace_config(workspace)\n return config.get(\"namespace\", \"default\")\n```\n\n资料来源：[src/mind_mem/namespaces.py:45-60]()\n\n### Namespace-Qualified Identifiers\n\nBlock IDs can be namespace-qualified using the format `:`:\n\n```\nproject-a:Dcision-2024-001\ndefault:Task-2024-015\nteam-infra:Fact-2024-003\n```\n\n资料来源：[src/mind_mem/namespaces.py:70-85]()\n\n---\n\n## Access Control Lists (ACL)\n\n### Overview\n\nMind-Mem implements a declarative ACL system that governs read and write access to blocks based on requester identity, namespace, and operation type.\n\n```mermaid\ngraph LR\n A[Request] --> B[ACL Engine]\n B --> C{Namespace Match?}\n C -->|Yes| D{Operation Allowed?}\n C -->|No| E[Deny: Unknown Namespace]\n D -->|Yes| F[Allow]\n D -->|No| G[Deny: Permission Denied]\n```\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:1-50]()\n\n### ACL Entry Structure\n\nEach ACL entry defines a permission rule:\n\n```json\n{\n \"subject\": \"agent:cody\",\n \"namespace\": \"project-a\",\n \"permissions\": [\"read\", \"write\"],\n \"conditions\": {\n \"block_types\": [\"decision\", \"task\", \"signal\"],\n \"max_age_days\": 30\n }\n}\n```\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:55-70]()\n\n### Permission Types\n\n| Permission | Description | Applicable Operations |\n|------------|-------------|----------------------|\n| `read` | View block content | `get_block`, `recall`, `search` |\n| `write` | Create or modify blocks | `create_block`, `update_block` |\n| `delete` | Remove blocks | `delete_block`, `archive_block` |\n| `govern` | Approve/reject proposals | `approve_apply`, `rollback` |\n| `admin` | Full namespace control | `scan`, `audit`, `reconcile` |\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:75-90]()\n\n### Built-in Roles\n\nMind-Mem ships with predefined roles for common use cases:\n\n| Role | Permissions | Use Case |\n|------|-------------|----------|\n| `viewer` | read | Read-only dashboards, reports |\n| `contributor` | read, write | Standard agents adding knowledge |\n| `governor` | read, write, govern | Governance workflow participants |\n| `admin` | read, write, delete, govern, admin | Full workspace management |\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:95-110]()\n\n### ACL Evaluation Logic\n\n```python\ndef evaluate_acl(request: RequestContext) -> AccessDecision:\n # 1. Check for wildcard (allow all)\n if _has_wildcard_entry(request.namespace, request.subject):\n return AccessDecision(allowed=True, reason=\"wildcard_match\")\n \n # 2. Check explicit deny entries\n for entry in _deny_entries(request.namespace, request.subject):\n if _matches_conditions(request, entry.conditions):\n return AccessDecision(allowed=False, reason=\"explicit_deny\")\n \n # 3. Check explicit allow entries\n for entry in _allow_entries(request.namespace, request.subject):\n if request.operation in entry.permissions:\n if _matches_conditions(request, entry.conditions):\n return AccessDecision(allowed=True, reason=\"explicit_allow\")\n \n # 4. Default: deny\n return AccessDecision(allowed=False, reason=\"default_deny\")\n```\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:120-150]()\n\n---\n\n## Block Storage Architecture\n\n### Directory Structure\n\nMind-Mem organizes blocks hierarchically under the workspace root:\n\n```\nworkspace/\n├── CLAUDE.md\n├── mind-mem.json\n├── decisions/\n│ └── D-*.md\n├── tasks/\n│ └── T-*.md\n├── signals/\n│ └── S-*.md\n├── facts/\n│ └── F-*.md\n├── entities/\n│ ├── projects/\n│ ├── people/\n│ └── tools/\n├── memory/\n│ └── *.md\n├── .ledger/\n│ └── ledger.db\n└── .signals/\n └── signals.db\n```\n\n资料来源：[src/mind_mem/block_store.py:50-100]()\n\n### Block Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Draft: create_block\n Draft --> Active: approve_apply\n Active --> Superseded: newer version\n Active --> Deprecated: manual\n Active --> Archived: delete_block\n Draft --> Rejected: governance_reject\n Superseded --> Archived: cleanup\n Deprecated --> [*]\n Archived --> Recoverable: restore_block\n```\n\n资料来源：[src/mind_mem/block_store.py:100-130]()\n\n### Quality Gates\n\nBefore storage, blocks pass through a deterministic quality gate:\n\n| Rule | Condition | Default Action |\n|------|-----------|----------------|\n| `empty` | Whitespace-only content | Log warning |\n| `too_short` | Fewer than 32 non-whitespace chars | Log warning |\n| `oversize` | Exceeds 64 KiB | Reject (strict) |\n| `malformed_utf8` | Contains lone surrogates | Reject (strict) |\n| `stopwords_only` | All tokens are stopwords | Log warning |\n| `near_duplicate` | Levenshtein similarity ≥ 0.97 | Log warning |\n| `injection_marker` | Matches prompt-injection patterns | Reject (strict) |\n| `ok` | No rule fired | Accept |\n\n资料来源：[src/mind_mem/quality_gate.py:1-50]()\n\n---\n\n## Recall and Retrieval\n\n### BM25 Search\n\nMind-Mem uses BM25 (Best Matching 25) for keyword-based retrieval:\n\n```python\ndef recall(workspace: str, query: str, limit: int = 10, active_only: bool = True):\n # 1. Parse all blocks in workspace\n blocks = parse_workspace_blocks(workspace, active_only=active_only)\n \n # 2. Build inverted index\n index = build_bm25_index(blocks)\n \n # 3. Score and rank results\n scores = index.score(query)\n \n # 4. Return top-k results with metadata\n return sorted(scores, key=lambda x: x.score, reverse=True)[:limit]\n```\n\n资料来源：[src/mind_mem/recall.py:1-40]()\n\n### Compiled Truth Pages\n\nFact blocks can be aggregated into compiled truth pages that consolidate evidence across multiple sources:\n\n```mermaid\ngraph LR\n A[Evidence A] --> B[Compiled Truth Page]\n C[Evidence B] --> B\n D[Evidence C] --> B\n B --> E[Current Understanding]\n B --> F[Evidence Trail]\n F --> G[Timestamped Entries]\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:1-60]()\n\n---\n\n## Governance Model\n\n### Proposal Workflow\n\nAll changes to the knowledge base flow through a governed proposal system:\n\n```mermaid\ngraph LR\n A[propose_update] --> B[Staged in SIGNALS.md]\n B --> C[Human Review]\n C -->|Approve| D[approve_apply]\n C -->|Reject| E[Rollback]\n D --> F[Active Block]\n E --> G[Discarded]\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-50]()\n\n### Governance Rules\n\n| Rule | Description |\n|------|-------------|\n| Immutability | Active blocks cannot be directly modified |\n| Audit Trail | Every state change is logged with timestamp and actor |\n| Separation | Agents propose; humans approve |\n| Rollback | Failed applications can be restored from snapshots |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:50-80]()\n\n---\n\n## Configuration\n\n### Workspace Configuration (`mind-mem.json`)\n\n```json\n{\n \"namespace\": \"default\",\n \"quality_gate_mode\": \"advisory\",\n \"recall_limit\": 20,\n \"mcp_schema_version\": \"3.2.0\",\n \"acl\": {\n \"default_policy\": \"allow\",\n \"entries\": []\n }\n}\n```\n\n资料来源：[src/mind_mem/infra/constants.py:1-30]()\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MIND_MEM_WORKSPACE` | Workspace root directory | Current working directory |\n| `MIND_MEM_NAMESPACE` | Override namespace | From config |\n| `MIND_MEM_LOG_FILE` | Structured log output path | stderr |\n| `MIND_MEM_MCP_SERVER` | Path to MCP server binary | Auto-detected |\n\n资料来源：[src/mind_mem/infra/workspace.py:1-40]()\n\n---\n\n## Related Documentation\n\n- [Block Format Specification](docs/block-format.md)\n- [MIC Map Reference](docs/mic-map.md)\n- [MCP Tools Documentation](src/mind_mem/mcp/tools/)\n- [API Reference](src/mind_mem/api/)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Overview](#page-overview), [MCP Server & Tools](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/README.md](https://github.com/star-ga/mind-mem/blob/main/examples/README.md)\n- [examples/basic_usage.py](https://github.com/star-ga/mind-mem/blob/main/examples/basic_usage.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/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n \n\n# Quick Start Guide\n\n## Overview\n\nThe Quick Start Guide provides a comprehensive introduction to **mind-mem**, a persistent memory system designed for AI coding assistants. Mind-mem enables multi-agent teams to store, recall, and govern structured memory blocks across development sessions.\n\n**Purpose and Scope**\n\nMind-mem serves as a unified memory layer that:\n- Parses and indexes markdown-based memory blocks (DECISIONS, TASKS, SIGNALS, etc.)\n- Provides BM25 and vector-based recall capabilities\n- Supports MCP (Model Context Protocol) integration for AI assistants\n- Implements governance workflows for memory evolution\n- Offers a CLI (`mm`) for direct workspace interaction\n\nThis guide walks through installation, workspace initialization, basic operations, and first steps for integrating mind-mem into your development workflow.\n\n资料来源：[examples/README.md:1-15]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[\"mm CLI\"]\n MCP[\"MCP Server\"]\n WEB[\"Web Console\"]\n end\n \n subgraph \"Core Modules\"\n RECALL[\"recall.py
BM25 + Vector Recall\"]\n COGNITIVE[\"cognitive_forget.py
Token Budget Packing\"]\n PARSER[\"block_parser.py
Markdown Parsing\"]\n end\n \n subgraph \"Storage Layer\"\n FTS[\"FTS Index
SQLite FTS5\"]\n META[\"Block Metadata\"]\n end\n \n CLI --> RECALL\n MCP --> RECALL\n WEB --> RECALL\n RECALL --> PARSER\n RECALL --> FTS\n PARSER --> META\n```\n\nThe system follows a layered architecture where the CLI and MCP server expose recall and governance APIs, while the core modules handle parsing, indexing, and retrieval.\n\n资料来源：[src/mind_mem/mm_cli.py:1-25]()\n\n## Prerequisites\n\nBefore getting started with mind-mem, ensure your environment meets these requirements:\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required for core package |\n| SQLite | 3.35+ | Built-in FTS5 support needed |\n| pip | 21.0+ | For package installation |\n| Node.js | 18+ | Optional, for web console only |\n| pnpm/npm | 8+/16+ | Optional, for web console |\n\nFor full feature support including encryption and governance:\n- OpenSSL 1.1.1+ (for encryption features)\n- watchgod or watchdog (optional, for file watching)\n\n资料来源：[examples/README.md:1-20]()\n\n## Installation\n\n### Standard Installation\n\nInstall mind-mem from the repository in development/editable mode:\n\n```bash\npip install -e .\n```\n\nThis installs the package with all dependencies and makes the `mm` CLI available system-wide.\n\n资料来源：[examples/README.md:12-15]()\n\n### Package Structure\n\nAfter installation, the following components become available:\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| `mm` CLI | Command line | Unified interface for all operations |\n| Python API | `mind_mem.*` | Programmatic access to recall, governance |\n| MCP Server | `mcp_server.py` | Model Context Protocol integration |\n| Hook Installer | `hook_installer.py` | Agent configuration for AI clients |\n\n### Workspace Environment\n\nMind-mem resolves the workspace directory using this precedence:\n\n```mermaid\ngraph LR\n A[\"MIND_MEM_WORKSPACE
Environment Variable\"] --> B{Set?}\n B -->|Yes| C[\"Use env value\"]\n B -->|No| D[\"Current Working
Directory\"]\n C --> E[\"Realpath Resolution\"]\n D --> E\n```\n\nSet the workspace explicitly:\n```bash\nexport MIND_MEM_WORKSPACE=/path/to/your/project\n```\n\n资料来源：[src/mind_mem/mm_cli.py:35-50]()\n\n## Basic Usage\n\n### Running the First Example\n\nThe `basic_usage.py` example demonstrates core functionality:\n\n```bash\npython3 examples/basic_usage.py\n```\n\n资料来源：[examples/README.md:5-8]()\n\n### Python API Walkthrough\n\nThe following demonstrates the fundamental workflow using the Python API:\n\n```python\nfrom mind_mem import recall, initialize_workspace\n\n# Initialize workspace memory directory\nworkspace = \"/path/to/project\"\ninitialize_workspace(workspace)\n\n# Search memory using BM25 recall\nresults = recall(\n workspace,\n \"authentication design decision\",\n limit=10,\n active_only=True\n)\n```\n\n### CLI Commands\n\nThe `mm` CLI provides five primary subcommands:\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `mm recall` | Search memory | `mm recall \"query\"` |\n| `mm context` | Generate token-budgeted snippet | `mm context \"query\"` |\n| `mm inject` | Render snippet for specific agent | `mm inject --agent claude \"query\"` |\n| `mm vault` | List/manage vault blocks | `mm vault scan ` |\n| `mm status` | Workspace summary | `mm status` |\n\n#### Recall Command\n\n```bash\n# Basic search\nmm recall \"authentication flow\"\n\n# With limit and active-only filter\nmm recall \"decision\" --limit 5 --active-only\n```\n\n#### Context Command\n\nGenerates a token-budgeted snippet suitable for including in LLM context windows:\n\n```bash\nmm context \"redis configuration\" --max-tokens 2000\n```\n\n资料来源：[src/mind_mem/mm_cli.py:53-80]()\n\n## Agent Integration\n\nMind-mem supports multiple AI coding assistants through the hook installer system.\n\n### Supported Agents\n\n| Agent | Config Format | Detection Method |\n|-------|---------------|------------------|\n| Claude Code | JSON | Binary path |\n| Cursor | JSON | Binary path |\n| Windsurf | JSON | Binary path |\n| Aider | YAML | Binary path |\n| Copilot | Text block | Always offered |\n| Cody | JSON | Binary + config path |\n| Qodo | Text block | Config path |\n\n资料来源：[src/mind_mem/hook_installer.py:80-150]()\n\n### Installing Agent Hooks\n\nThe hook installer generates configuration files and provides MCP server specifications:\n\n```python\nfrom mind_mem.hook_installer import (\n mcp_server_spec,\n get_agent_spec,\n install_hooks\n)\n\n# Get MCP server invocation for your client\nspec = mcp_server_spec(workspace=\"/path/to/project\")\n# Returns: {command, args, env}\n\n# Install hooks for a specific agent\ninstall_hooks(\"claude\", workspace=\"/path/to/project\")\n```\n\n### MCP Server Path Resolution\n\nThe MCP server is located using this precedence:\n\n```mermaid\ngraph TD\n A[\"MIND_MEM_MCP_SERVER
env var\"] --> B{File exists?}\n B -->|Yes| C[\"Use override path\"]\n B -->|No| D[\"src-layout checkout
../mcp_server.py\"]\n D --> E{File exists?}\n E -->|No| F[\"Packaged install
../mcp_server.py\"]\n F --> G{File exists?}\n G -->|No| H[\"Package root
mcp_server.py\"]\n H --> I[\"Fallback: mcp_server.py\"]\n```\n\n资料来源：[src/mind_mem/hook_installer.py:15-40]()\n\n## Web Console (Optional)\n\nFor visual exploration of memory, the web console provides a force-directed graph view:\n\n```bash\ncd web\npnpm install\npnpm dev\n```\n\nAccess at `http://localhost:3000`.\n\n### Web Console Features\n\nThe console displays:\n- **Graph View**: Force-directed visualization of block relationships\n- **Timeline View**: Chronological event ordering\n- **Facts Panel**: Extracted claims with confidence scores\n\nAll views derive from a single `recall(format=\"bundle\")` call.\n\n资料来源：[web/README.md:1-35]()\n\n### Configuration\n\nSet the API URL if mind-mem isn't on localhost:8080:\n\n```bash\nNEXT_PUBLIC_MIND_MEM_API_URL=http://mind-mem.internal:8080 pnpm dev\n```\n\n资料来源：[web/README.md:14-18]()\n\n## MCP Resources\n\nThe MCP server exposes read-only resources for AI assistants:\n\n| Resource URI | Content |\n|--------------|---------|\n| `mind-mem://decisions` | Active decisions (DECISIONS.md) |\n| `mind-mem://tasks` | All tasks (TASKS.md) |\n| `mind-mem://entities/{type}` | Projects, people, tools, incidents |\n| `mind-mem://signals` | Auto-captured signals |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\nResources are registered after server construction to avoid circular imports.\n\n资料来源：[src/mind_mem/mcp/resources.py:20-45]()\n\n## Next Steps\n\nAfter completing this quick start guide:\n\n1. **Explore Memory Blocks**: Create DECISIONS.md, TASKS.md, and SIGNALS.md files in your workspace\n2. **Configure Your Agent**: Use the hook installer to integrate with your preferred AI assistant\n3. **Try Advanced Recall**: Experiment with `mm context` for token-budgeted retrieval\n4. **Set Up Governance**: Configure the governance workflow for memory evolution\n5. **Run the Web Console**: Visualize your memory graph\n\n### File Structure Convention\n\nMind-mem expects this structure within your workspace:\n\n```\nworkspace/\n├── memory/ # User-authored memory blocks\n│ ├── DECISIONS.md\n│ ├── TASKS.md\n│ └── SIGNALS.md\n├── .mind/ # Kernel configuration files\n└── mind-mem.json # Feature flags and limits\n```\n\n资料来源：[examples/basic_usage.py:1-30]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `mm: command not found` | Reinstall package with `pip install -e .` |\n| Empty recall results | Check workspace path and memory/ directory |\n| MCP connection fails | Verify MIND_MEM_MCP_SERVER path |\n| Import errors | Ensure all dependencies installed with `-e .` |\n\n### Debug Mode\n\nEnable verbose logging by setting:\n```bash\nexport MIND_MEM_LOG_LEVEL=DEBUG\n```\n\n## Summary\n\nThis guide covered:\n- Installation via pip editable mode\n- Workspace initialization and environment variables\n- Basic CLI commands (recall, context, inject, vault, status)\n- Agent hook installation for AI assistant integration\n- Optional web console setup\n- MCP resources for programmatic access\n\nFor deeper integration, explore the governance tools, audit capabilities, and v4 cognitive features in the advanced documentation.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Overview](#page-overview), [Core Components](#page-components), [Hybrid Search & Retrieval](#page-hybrid-search)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.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/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.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/arch_mind.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.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/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n \n\n# System Architecture\n\n## Overview\n\nmind-mem is a persistent memory system designed for AI coding agents. It provides structured memory management through markdown-based block files, BM25 full-text search, graph-based relationship tracking, and an MCP (Model Context Protocol) server interface for seamless integration with AI coding clients.\n\nThe system follows a \"memory is never modified except by governance\" invariant, ensuring that all changes to the knowledge base go through a formal propose → approve → apply workflow. This architecture enables multi-agent collaboration while maintaining audit trails and preventing uncontrolled drift.\n\n资料来源：[src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLI[mm CLI]\n MCP[MCP Clients
Claude Code, Codex, Cursor, Windsurf]\n WebApp[Web Console]\n end\n\n subgraph \"Interface Layer\"\n MM_CLI[mm_cli.py
Non-MCP Interface]\n MCPServer[MCP Server
FastMCP]\n RestAPI[REST API v1]\n end\n\n subgraph \"Core Engine\"\n Recall[recall.py
BM25 + Vector Recall]\n Graph[knowledge_graph.py
Entity Relationships]\n BlockParser[block_parser.py
Markdown Processing]\n ApplyEngine[apply_engine.py
Change Application]\n end\n\n subgraph \"Governance Layer\"\n Governance[governance.py
Proposals & Approvals]\n CompiledTruth[compiled_truth.py
Truth Aggregation]\n AuditChain[audit_chain.py
Integrity Verification]\n end\n\n subgraph \"Data Layer\"\n Workspace[(Workspace
memory/ intelligence/ signals/)]\n FTS5[(FTS5 Index)]\n SQLite[(SQLite DB)]\n end\n\n CLI --> MM_CLI\n MCP --> MCPServer\n WebApp --> RestAPI\n\n MM_CLI --> Recall\n MCPServer --> Recall\n MCPServer --> Governance\n MCPServer --> ApplyEngine\n RestAPI --> Recall\n\n Recall --> BlockParser\n Recall --> Graph\n ApplyEngine --> BlockParser\n Governance --> CompiledTruth\n\n BlockParser --> Workspace\n Graph --> SQLite\n Recall --> FTS5\n```\n\n## Directory Structure\n\n```\nmind-mem/\n├── src/mind_mem/\n│ ├── mcp/\n│ │ ├── server.py # Main MCP server entry point\n│ │ ├── resources.py # MCP resource declarations\n│ │ └── tools/\n│ │ ├── governance.py # Propose, approve, rollback tools\n│ │ ├── kernels.py # Mind kernel configuration tools\n│ │ ├── memory_ops.py # Index, health, export tools\n│ │ └── arch_mind.py # Architecture baseline/delta tools\n│ ├── recall.py # BM25 recall implementation\n│ ├── knowledge_graph.py # Entity extraction & relationships\n│ ├── compiled_truth.py # Compiled truth page management\n│ ├── apply_engine.py # Workspace modification engine\n│ ├── block_parser.py # Markdown block parsing\n│ ├── mm_cli.py # CLI interface for non-MCP agents\n│ ├── hook_installer.py # Per-agent hook configuration\n│ ├── model_provenance.py # Model audit & provenance\n│ └── v4/ # v4.0 future capabilities\n├── web/ # Next.js web console\n└── docs/\n```\n\n## Core Components\n\n### Workspace Organization\n\nThe workspace is the root directory containing all memory files and metadata. It is resolved from the `MIND_MEM_WORKSPACE` environment variable or defaults to the current working directory.\n\n资料来源：[src/mind_mem/mm_cli.py:28-32](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n```mermaid\ngraph TD\n W[(Workspace Root)]\n W --> |memory/| M[memory/
DECISIONS.md
TASKS.md
entities/]\n W --> |intelligence/| I[intelligence/
applied/ snapshots/]\n W --> |signals/| S[signals/
SIGNALS.md]\n W --> |.mind/| MK[.mind/
kernel configs/]\n W --> |mind-mem.json| CFG[mind-mem.json
Configuration]\n```\n\n| Directory | Purpose |\n|-----------|---------|\n| `memory/` | Primary knowledge base (decisions, tasks, entities) |\n| `intelligence/` | Applied changes and snapshots for rollback |\n| `signals/` | Staged proposals awaiting governance |\n| `.mind/` | Mind kernel configuration files |\n| `mind-mem.json` | Workspace configuration |\n\n### Block Parser\n\nThe block parser extracts structured information from markdown files, supporting various block types with frontmatter metadata.\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:24-26](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n\n| Block Type | Prefix | Description |\n|------------|--------|-------------|\n| DECISION | `# decision` | Architectural decisions with rationale |\n| TASK | `# task` | Actionable items with status tracking |\n| PROJECT | `# project` | Entity type for project definitions |\n| PERSON | `# person` | Entity type for people |\n| TOOL | `# tool` | Entity type for tool configurations |\n| INCIDENT | `# incident` | Entity type for incidents |\n| SIGNAL | `# signal` | Staged proposals |\n| CLAIM | `# claim` | Factual assertions with confidence |\n\n### Recall System\n\nThe recall system provides BM25-based full-text search across the workspace memory. It ranks results by relevance and supports filtering by block type and temporal constraints.\n\n资料来源：[src/mind_mem/mm_cli.py:36-43](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n```mermaid\ngraph LR\n Q[Query] --> Recall\n Recall --> |BM25| FTS[FTS5 Index]\n Recall --> |parse| BP[block_parser.py]\n BP --> |active blocks| Filter\n FTS --> Filter\n Filter --> R[Ranked Results
JSON bundle format]\n```\n\n## MCP Server Architecture\n\nThe MCP server exposes tools and resources through the Model Context Protocol, enabling AI coding clients to interact with the memory system.\n\n资料来源：[src/mind_mem/mcp/resources.py:1-29](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n\n### MCP Resources\n\nResources provide read-only access to workspace data:\n\n| Resource URI | Description |\n|--------------|-------------|\n| `mind-mem://decisions` | Active decisions from DECISIONS.md |\n| `mind-mem://tasks` | All tasks from TASKS.md |\n| `mind-mem://entities/{type}` | Projects, people, tools, incidents |\n| `mind-mem://signals` | Auto-captured signals |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\n### MCP Tool Categories\n\n#### Governance Tools\n\nGovernance tools manage the propose → approve → apply lifecycle:\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-28](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n\n| Tool | Purpose |\n|------|---------|\n| `propose_update` | Stage a new decision or task as a SIGNAL |\n| `approve_apply` | Apply a staged proposal (dry-run by default) |\n| `rollback_proposal` | Restore workspace from pre-apply snapshot |\n| `scan` | Integrity scan (contradictions, drift, pending) |\n| `list_contradictions` | Enriched contradiction listing |\n| `memory_evolution` | A-MEM metadata for a block |\n\n#### Memory Operations Tools\n\nMemory operations provide lifecycle management:\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-30](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)\n\n| Tool | Purpose |\n|------|---------|\n| `index_stats` | FTS5 index state inspection |\n| `reindex` | Rebuild the full-text search index |\n| `delete_memory_item` | Atomic block removal with recovery log |\n| `export_memory` | JSONL dump with configurable metadata |\n| `get_block` | Block lookup by ID |\n| `memory_health` | Health dashboard |\n| `compact` | Workspace compaction |\n| `stale_blocks` | Staleness-flag management |\n\n#### Kernel Tools\n\nKernel tools provide access to mind kernel configuration:\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:1-27](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n\n| Tool | Purpose |\n|------|---------|\n| `list_mind_kernels` | List available .mind kernel files |\n| `get_mind_kernel` | Read a specific kernel configuration |\n| `compiled_truth_load` | Load truth page for an entity |\n| `compiled_truth_add_evidence` | Add evidence to a truth page |\n| `compiled_truth_contradictions` | Check for contradictions |\n\n#### Architecture Mind Tools\n\nArch-mind tools integrate architecture baseline management:\n\n资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)\n\n| Tool | Purpose |\n|------|---------|\n| `arch_baseline` | Initialize arch-mind store with baseline |\n| `arch_delta` | Compute (current scan) - (baseline scores) |\n| `arch_history` | List events in arch-mind store |\n| `arch_check_rules` | Apply rules.mind to a fresh scan |\n| `arch_session_start` | Open session evidence node |\n| `arch_session_end` | Close session, write delta evidence |\n| `arch_metric_explain` | Per-metric breakdown for a fixture |\n\n## Governance Workflow\n\nThe governance system ensures all memory modifications follow a controlled process:\n\n```mermaid\ngraph LR\n A[Agent proposes
propose_update] --> B{Signal created
in signals/}\n B --> C{Human review}\n C -->|approve| D[dry-run]\n C -->|reject| E[Signal discarded]\n D -->|confirm| F[apply_engine.py]\n D -->|cancel| E\n F --> G[Snapshot created
for rollback]\n G --> H[Changes applied
to workspace]\n H --> I[Compiled truth
recompiled]\n```\n\n### Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity into canonical understanding pages:\n\n资料来源：[src/mind_mem/compiled_truth.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n```\n# entity_id — Compiled Truth\n\n## Current Understanding\n- Bullet point summary from evidence\n\n## Evidence Trail\n### timestamp [CONF] (source: ...)\nObservation text\n```\n\n| Field | Description |\n|-------|-------------|\n| `entity_id` | Unique entity identifier |\n| `entity_type` | Type (project, person, tool, incident) |\n| `compiled_section` | Bullet-point summary of current understanding |\n| `evidence_entries` | List of observations with confidence and timestamp |\n| `version` | Incremented on each recompilation |\n\n## Apply Engine\n\nThe apply engine handles workspace modifications through the configured BlockStore:\n\n资料来源：[src/mind_mem/apply_engine.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n```mermaid\ngraph TD\n AE[apply_engine.py] --> BS{BlockStore
mind-mem.json}\n BS -->|markdown| MS[MarkdownBlockStore]\n BS -->|postgres| PS[PostgresBlockStore]\n BS -->|encrypted| ES[EncryptedWrapper]\n MS --> WD[(Workspace
Files)]\n PS --> PG[(PostgreSQL)]\n ES --> PS\n \n AE --> |create_snapshot| Snap\n AE --> |restore_snapshot| Rest\n AE --> |snapshot_diff| Diff\n```\n\n| Backend | Configuration | Use Case |\n|---------|---------------|----------|\n| MarkdownBlockStore | Default | Standard file-based storage |\n| PostgresBlockStore | `block_store.backend: postgres` | Scalable multi-tenant |\n| EncryptedWrapper | `passphrase` set | Sensitive data protection |\n\n## CLI Interface\n\nThe `mm` CLI provides a unified interface for non-MCP agents:\n\n资料来源：[src/mind_mem/mm_cli.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n```bash\nmm recall \"\" # Search memory\nmm context \"\" # Generate token-budgeted snippet\nmm inject --agent \"\" # Render snippet for specific agent\nmm vault scan # List parsed vault blocks (JSON)\nmm vault write --type --body \nmm status # Workspace summary\n```\n\n## Web Console\n\nThe web console provides a visual interface for memory exploration:\n\n资料来源：[web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n\n```mermaid\ngraph TB\n Web[Next.js Console] --> API[lib/api.ts]\n API --> Recall[/v1/recall]\n API --> Health[/v1/health]\n \n Recall --> |bundle| GV[GraphView
d3-force]\n Recall --> |bundle| TV[TimelineView
Chronological]\n Recall --> |bundle| FL[FactList
Extracted claims]\n```\n\n| Component | Purpose |\n|-----------|---------|\n| `GraphView.tsx` | Force-directed graph of blocks and cross-references |\n| `TimelineView.tsx` | Chronological view of dated events |\n| `FactList.tsx` | Extracted claims with confidence levels |\n\n## Agent Integration\n\nThe hook installer enables per-agent memory integration:\n\n资料来源：[src/mind_mem/hook_installer.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n\n| Agent | Config Path | Format |\n|-------|-------------|--------|\n| Claude Code | `~/.claude/projects/*/.claude.md` | Markdown block |\n| Copilot | `.github/copilot-instructions.md` | Markdown block |\n| Cody | `.cody/config.json` | JSON generic |\n| Cursor | `.cursor/rules/*.mdc` | Markdown with frontmatter |\n| Windsurf | `.codeium/windsurf/mcp_config.json` | JSON windsurf |\n| Aider | `.aider.conf.yml` | YAML block |\n\n## v4.0 Future Architecture\n\nThe v4.0 package provides side-by-side scaffolding, gated by feature flags:\n\n资料来源：[src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n\n| Group | Features |\n|-------|----------|\n| A. Cognition | Tier-aware blocks, Cognitive Mind Kernel, surprise-weighted retrieval |\n| B. Knowledge Graph | Entity/concept extraction, long-context recall, LLM fusion, streaming |\n| C. Governance UX | Idle background ingest, AI lint with auto-fix, contradiction state machine |\n\n## Key Design Principles\n\n| Principle | Implementation |\n|-----------|-----------------|\n| Memory immutability | All changes go through governance workflow |\n| Auditability | Every modification has a snapshot and proposal trail |\n| Multi-agent safety | File locking and governance prevents conflicts |\n| Separation of concerns | Distinct layers for interface, core, governance, and data |\n| Extensibility | Plugin architecture via BlockStore and MCP tools |\n\n---\n\n\n\n## Core Components\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Hybrid Search & Retrieval](#page-hybrid-search), [Governance & Safety](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/conflict_resolver.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/conflict_resolver.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/tiered_memory.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/tiered_memory.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 \n\n# Core Components\n\nMIND-Mem's architecture centers on a set of interconnected components that manage workspace memory through a structured lifecycle: recall, storage, application, conflict resolution, drift detection, and tiered memory management. These components work together to provide a robust, multi-agent compatible memory system that maintains data integrity and supports autonomous memory consolidation.\n\n## Memory Recall System\n\nThe recall system is the primary retrieval engine in MIND-Mem, providing BM25-based full-text search over the workspace memory blocks. It supports flexible querying with result limiting and active-only filtering.\n\n### Recall Architecture\n\n```mermaid\ngraph TD\n A[Query Input] --> B[recall function]\n B --> C[BM25 FTS5 Index]\n C --> D[Ranked Results]\n D --> E[Optional: pack_to_budget]\n E --> F[Token-Budgeted Snippet]\n```\n\n### Recall Function\n\nThe `recall()` function serves as the main entry point for memory retrieval:\n\n```python\ndef recall(workspace, query, limit=10, active_only=True)\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `workspace` | `str` | required | Root workspace directory path |\n| `query` | `str` | required | Search query string |\n| `limit` | `int` | `10` | Maximum number of results to return |\n| `active_only` | `bool` | `True` | Filter to only active (non-superseded) blocks |\n\n资料来源：[src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n\n### Context Generation\n\nThe `pack_to_budget()` function from `cognitive_forget` module works with recall results to generate token-budgeted snippets for efficient context injection:\n\n```python\nfrom mind_mem.cognitive_forget import pack_to_budget\nresults = recall(workspace, query)\ncontext = pack_to_budget(results, token_budget)\n```\n\n资料来源：[src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n\n## Block Storage Layer\n\nThe block storage layer provides an abstraction over different storage backends, enabling MIND-Mem to work with Markdown files on disk or optional PostgreSQL deployments.\n\n### Storage Backend Selection\n\n```mermaid\ngraph TD\n A[get_block_store workspace] --> B{Try Import storage module}\n B -->|Success| C[Return configured backend]\n B -->|Exception| D[Fallback to MarkdownBlockStore]\n C --> E[Markdown / Postgres / Encrypted]\n```\n\n### BlockStore Implementations\n\n| Backend | Description | Configuration Key |\n|---------|-------------|-------------------|\n| `MarkdownBlockStore` | Default, file-based storage | N/A (default) |\n| `PostgresBlockStore` | Optional SQL backend | `block_store.backend: \"postgres\"` |\n| `EncryptedBlockStore` | Passphrase-protected wrapper | `block_store.backend: \"encrypted\"` |\n\n资料来源：[src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n### Block Deletion and Recovery\n\nThe storage layer maintains an append-only deletion log for recovery:\n\n```python\ndef _log_block_deletion(workspace, block_id, content):\n \"\"\"Append deletion receipt to memory/deleted_blocks.jsonl.\"\"\"\n log_path = os.path.join(workspace, \"memory\", \"deleted_blocks.jsonl\")\n entry = {\n \"block_id\": block_id,\n \"deleted_at\": datetime.now(timezone.utc).isoformat(),\n \"content\": content,\n }\n```\n\nBlock locations are determined by scanning text content for block ID headers `[block_id]`, with boundaries at next headers or `---` separators.\n\n资料来源：[src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n## Apply Engine\n\nThe apply engine handles workspace modifications through a staged proposal and apply workflow, supporting snapshots, rollback, and diff operations.\n\n### Application Workflow\n\n```mermaid\ngraph LR\n A[propose_update] --> B[Signal Written]\n B --> C[approve_apply]\n C --> D{Snapshot Created}\n D -->|Success| E[Changes Applied]\n D -->|Failure| F[Rollback Available]\n```\n\n### Snapshot Operations\n\n| Operation | Function | Description |\n|-----------|----------|-------------|\n| Create | `create_snapshot(ws, ts, files_touched)` | Creates pre-apply snapshot for rollback |\n| Restore | `restore_snapshot(ws, snap_dir)` | Restores workspace from snapshot |\n| Diff | `snapshot_diff(ws, snap_dir)` | Returns list of files that differ |\n\nThe apply engine routes through the configured BlockStore, allowing Postgres-backed deployments to snapshot via SQL instead of on-disk copies.\n\n资料来源：[src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n### Block Store Routing\n\n```python\ndef _store_for(ws):\n \"\"\"Route to the configured BlockStore implementation.\"\"\"\n try:\n from .storage import get_block_store\n return get_block_store(ws)\n except Exception:\n return MarkdownBlockStore(ws) # Fallback resilience\n```\n\nThis fallback mechanism keeps the apply engine resilient on first-run or misconfigured workspaces.\n\n资料来源：[src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## Conflict Resolution\n\nThe conflict resolver manages situations where multiple agents or processes attempt to modify the same memory blocks, ensuring data consistency and preventing silent overwrites.\n\n### Resolution Strategy\n\nThe conflict resolver implements a last-write-wins (LWW) strategy with evidence preservation, allowing the system to track and potentially rollback conflicting changes.\n\n### Key Operations\n\n| Method | Purpose |\n|--------|---------|\n| `detect_conflicts()` | Identify overlapping block modifications |\n| `resolve_conflict()` | Apply resolution strategy and merge evidence |\n| `get_conflict_history()` | Retrieve conflict metadata for audit |\n\n资料来源：[src/mind_mem/conflict_resolver.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/conflict_resolver.py)\n\n## Drift Detection\n\nThe drift detector monitors memory state changes over time, identifying when factual understanding diverges from previously recorded information.\n\n### Drift Detection Pipeline\n\n```mermaid\ngraph TD\n A[Memory Blocks] --> B[Baseline Snapshot]\n B --> C[Current State]\n C --> D[Comparison Engine]\n D --> E{Drift Detected?}\n E -->|Yes| F[Flag for Review]\n E -->|No| G[Continue Monitoring]\n```\n\n### Detection Criteria\n\n| Drift Type | Detection Method | Severity |\n|------------|------------------|----------|\n| Semantic Drift | Factual claim contradiction | High |\n| Temporal Drift | Outdated timestamps | Medium |\n| Structural Drift | Schema/format changes | Low |\n\n资料来源：[src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)\n\n## Tiered Memory\n\nThe tiered memory system organizes memory blocks across multiple storage tiers based on access patterns, importance, and staleness, enabling efficient resource utilization.\n\n### Memory Tier Structure\n\n```mermaid\ngraph BT\n A[Hot Tier] --> B[Warm Tier]\n B --> C[Cold Tier]\n A --> D[Active Memory]\n B --> E[Archived Memory]\n C --> F[Long-term Storage]\n```\n\n### Tier Classification\n\n| Tier | Criteria | Eviction Policy |\n|------|----------|------------------|\n| Hot | Recently accessed, high importance | LRU with importance boost |\n| Warm | Moderate access frequency | Threshold-based archiving |\n| Cold | Stale, low importance | Compression or deletion after grace period |\n\nThe consolidation system uses `ConsolidationConfig` to control the forgetting cycle:\n\n```python\ncfg = ConsolidationConfig(\n importance_threshold=0.25,\n stale_days=14,\n archive_after_days=60,\n grace_days=30,\n)\n```\n\n资料来源：[src/mind_mem/tiered_memory.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/tiered_memory.py)\n\n## MCP Core Tools\n\nThe MCP (Model Context Protocol) layer exposes core functionality as tools for agent integration. The core tools module provides the primary interface for memory operations.\n\n### Available Core Tools\n\n| Tool | Function | Description |\n|------|----------|-------------|\n| `list_mind_kernels` | List kernel configs | Enumerate `.mind` kernel configuration files |\n| `get_mind_kernel` | Get kernel config | Retrieve specific kernel configuration |\n| `compiled_truth_load` | Load truth page | Load compiled truth for an entity |\n| `compiled_truth_add_evidence` | Add evidence | Append evidence to a truth page |\n| `compiled_truth_contradictions` | List contradictions | Show detected entity contradictions |\n\n### Kernel Configuration Loading\n\n```python\nfrom mind_mem.mind_ffi import get_mind_dir, load_all_kernel_configs, load_kernel_config\n\nmind_dir = get_mind_dir(workspace)\nall_cfgs = load_all_kernel_configs(mind_dir)\n```\n\nThe `.mind` kernel files tune recall, reranking, RM3 expansion, and related pipeline knobs.\n\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\n## Quality Gate\n\nThe quality gate provides a deterministic pre-storage filter for candidate blocks, ensuring memory integrity through content validation.\n\n### Quality Rules\n\n| Rule | Condition | Default Action |\n|------|-----------|----------------|\n| `empty` | Whitespace-only content | Log warning |\n| `too_short` | Fewer than 32 non-whitespace chars | Log warning |\n| `oversize` | Exceeds 64 KiB | Log warning |\n| `malformed_utf8` | Contains lone surrogates | Log warning |\n| `stopwords_only` | No semantic content | Log warning |\n| `near_duplicate` | Similarity ≥ 0.97 to recent block | Log warning |\n| `injection_marker` | Matches prompt-injection pattern | Log warning |\n| `ok` | No rule fired | Accept |\n\nQuality gate modes:\n\n| Mode | Behavior |\n|------|----------|\n| `advisory` (default) | Log warnings, always accept |\n| `strict` | Reject blocks that trigger any rule |\n\nConfiguration sources (in priority order): `strict=True` keyword argument → `QualityGateConfig(mode=\"strict\")` → `mind-mem.json` setting `quality_gate_mode = \"strict\"`.\n\n资料来源：[src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n\n## Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity and recompiles canonical understanding from source memory blocks.\n\n### Truth Page Format\n\n```markdown\n---\nentity_id: \nentity_type: \nlast_compiled: \nversion: \n---\n\n# — Compiled Truth\n\n## Current Understanding\n\n\n## Evidence Trail\n### [CONF] (source: )\n\n\n### [SUPERSEDED] (source: )\n\n```\n\n### Evidence Aggregation\n\nThe system reads markdown files from `{workspace}/memory/`, counts sentence-level occurrences, and promotes sentences appearing at least `min_mentions` times as candidates for compiled truth pages.\n\n资料来源：[src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## Component Interactions\n\nThe following diagram illustrates how core components interact during a typical memory operation:\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP_Tools\n participant Apply_Engine\n participant Quality_Gate\n participant Block_Store\n participant Recall\n participant Drift_Detector\n\n Agent->>MCP_Tools: propose_update()\n MCP_Tools->>Quality_Gate: validate(block)\n Quality_Gate-->>Apply_Engine: verdict\n Apply_Engine->>Apply_Engine: create_snapshot()\n Apply_Engine->>Block_Store: write(block)\n Block_Store-->>Apply_Engine: success\n Agent->>Recall: recall(query)\n Recall-->>Agent: results\n Recall->>Drift_Detector: check_drift(results)\n Drift_Detector-->>Agent: drift_alerts\n```\n\n## CLI Integration\n\nThe `mm` CLI provides command-line access to core components for non-MCP agents:\n\n| Command | Component | Description |\n|---------|-----------|-------------|\n| `mm recall \"\"` | Recall | Search memory |\n| `mm context \"\"` | Recall + cognitive_forget | Generate token-budgeted snippet |\n| `mm inject --agent \"\"` | Recall | Render snippet for specific agent |\n| `mm status` | All | Workspace summary |\n\n资料来源：[src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n---\n\n\n\n## Hybrid Search & Retrieval\n\n### 相关页面\n\n相关主题：[Knowledge Graph & Entity Management](#page-knowledge-graph), [Core Components](#page-components), [Block Format & Data Model](#page-data-model)\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/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)\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/graph_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_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/cross_encoder_reranker.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/cross_encoder_reranker.py)\n- [src/mind_mem/intent_router.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/intent_router.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/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n- [docs/scoring.md](https://github.com/star-ga/mind-mem/blob/main/docs/scoring.md)\n \n\n# Hybrid Search & Retrieval\n\n## Overview\n\nThe Hybrid Search & Retrieval system in mind-mem provides multi-modal memory retrieval capabilities that combine keyword-based search (BM25), dense vector search, graph-based traversal, and intelligent reranking to deliver contextually relevant results for AI agents and CLI operations.\n\nThe system operates under the principle that no single retrieval method is optimal for all query types. By combining multiple retrieval strategies with Reciprocal Rank Fusion (RRF), mind-mem achieves robust and accurate recall across diverse query patterns.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Intent Router]\n B --> C{Query Type}\n C -->|Keyword| D[BM25 / FTS5]\n C -->|Semantic| E[Vector Recall]\n C -->|Graph| F[Graph Recall]\n D --> G[Query Expansion]\n E --> G\n F --> G\n G --> H[Hybrid Recall]\n H --> I[Cross-Encoder Reranker]\n I --> J[Final Results]\n \n K[Graph DB] --> F\n L[FTS5 Index] --> D\n M[Vector Store] --> E\n```\n\n## Core Components\n\n### Intent Router\n\nThe Intent Router (`intent_router.py`) classifies incoming queries to determine the optimal retrieval strategy.\n\n**Responsibilities:**\n- Analyze query semantics to determine intent\n- Route queries to appropriate retrieval backends\n- Support mixed-mode retrieval when query intent is ambiguous\n\n**Routing Decisions:**\n\n| Query Pattern | Routing | Rationale |\n|---------------|---------|-----------|\n| Exact terms / keywords | BM25 primary | Precision-focused |\n| Conceptual / semantic | Vector primary | Semantic similarity |\n| Entity relationships | Graph primary | Traversal-based |\n| Complex / multi-aspect | Hybrid RRF | Combined scoring |\n\n资料来源：[src/mind_mem/intent_router.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/intent_router.py)\n\n### BM25 Keyword Search\n\nBM25 (Best Matching 25) provides traditional keyword-based retrieval through SQLite FTS5. This approach excels at exact term matching and is the default retrieval method for the CLI `recall` command.\n\n**Key Features:**\n- Term frequency/inverse document frequency scoring\n- Configurable BM25 parameters via `.mind` kernel files\n- Integration with the `recall` function for workspace queries\n\n**Usage in CLI:**\n```python\ndef _cmd_recall(args: argparse.Namespace) -> int:\n from mind_mem.recall import recall\n results = recall(_workspace(), args.query, limit=args.limit, active_only=args.active_only)\n print(json.dumps(results, indent=2, default=str))\n return 0\n```\n\n资料来源：[src/mind_mem/mm_cli.py:42-47](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py#L42-L47)\n\n### Vector Recall\n\nDense vector retrieval (`recall_vector.py`) provides semantic similarity search using embeddings. This method identifies conceptually related content even when exact terms differ.\n\n**Capabilities:**\n- Dense embedding-based similarity scoring\n- Configurable embedding model selection\n- Fallback to BM25 when vector search unavailable\n\n**Integration Points:**\n- Called by hybrid recall orchestrator\n- Results fed into cross-encoder reranking pipeline\n- Supports workspace-specific vector stores\n\n资料来源：[src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)\n\n### Graph Recall\n\nGraph-based recall (`graph_recall.py`) traverses the co-retrieval graph to discover related memory blocks based on entity relationships and cross-reference patterns.\n\n**Algorithm Overview:**\n```mermaid\ngraph LR\n A[Query Block] --> B[Find Connected Nodes]\n B --> C[Weighted Edge Traversal]\n C --> D[Collect Related Blocks]\n D --> E[Score by Path Length]\n \n F[Co-Retrieval DB] --> B\n```\n\n**Features:**\n- Kahn's algorithm for topological ordering\n- Cycle breaking on lowest-weight edges\n- Chronological backbone combined with co-retrieval edges\n\nThe graph recall is particularly valuable for \"walkthrough\" scenarios where temporal dependencies matter:\n\n> For teach me / explain queries, agents and humans both want a learning order — foundations first, then derived context, then current state.\n\n资料来源：[src/mind_mem/graph_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_recall.py)\n\n### Query Expansion\n\nQuery expansion (`query_expansion.py`) enhances the original query with related terms, synonyms, and context to improve recall coverage.\n\n**Expansion Strategies:**\n- Synonym injection based on domain knowledge\n- Entity-aware term expansion\n- Contextual query reformulation\n\n资料来源：[src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/query_expansion.py)\n\n## Hybrid Recall Orchestration\n\n### RRF (Reciprocal Rank Fusion)\n\nThe hybrid recall module (`hybrid_recall.py`) combines results from multiple retrieval methods using Reciprocal Rank Fusion. RRF provides a simple yet effective way to merge ranked lists without requiring score normalization.\n\n**RRF Formula:**\n```\nscore(d) = Σ 1 / (k + rank_i(d))\n```\nWhere `k` is typically 60, and `rank_i(d)` is the rank of document `d` in retrieval list `i`.\n\n**Benefits:**\n- No need for score calibration between methods\n- Robust to individual method failures\n- Emphasizes documents ranked well across multiple sources\n\n资料来源：[src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)\n\n### Integration with MCP Resources\n\nThe MCP (Model Context Protocol) layer exposes recall functionality as resources:\n\n```python\n\"\"\"mind-mem://recall/{query} — BM25 recall search\"\"\"\n```\n\nThis enables MCP-aware AI clients to request memory context directly through the standardized resource interface.\n\n资料来源：[src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n\n## Reranking Pipeline\n\n### Cross-Encoder Reranker\n\nThe cross-encoder reranker (`cross_encoder_reranker.py`) applies a trained model to re-score retrieved candidates against the original query, significantly improving ranking quality.\n\n**Pipeline Position:**\n```mermaid\ngraph LR\n A[Hybrid Recall] --> B[Cross-Encoder Rerank]\n B --> C[Final Ranking]\n```\n\n**Processing Flow:**\n1. Receive top-N candidates from hybrid recall (e.g., top 100)\n2. Score each candidate against the query using cross-encoder\n3. Re-rank by cross-encoder scores\n4. Return top-K final results (typically K < N)\n\n**Cross-Encoder Advantages:**\n- Captures query-document interaction features\n- Better handles complex semantic relationships\n- Can incorporate attention mechanisms for relevance\n\n资料来源：[src/mind_mem/cross_encoder_reranker.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/cross_encoder_reranker.py)\n\n## Scoring System\n\n### Score Composition\n\nThe final relevance score combines multiple signals:\n\n| Component | Weight | Source |\n|-----------|--------|--------|\n| BM25 Score | Variable | FTS5 index |\n| Vector Similarity | Variable | Embedding model |\n| Graph Proximity | Variable | Co-retrieval graph |\n| RRF Score | Fixed formula | Rank fusion |\n| Cross-Encoder | High | Trained model |\n\n### Scoring Configuration\n\nMind-mem uses `.mind` kernel files to configure retrieval parameters. The `bm25.mind` file controls BM25-specific settings while `rrf.mind` manages fusion parameters.\n\n资料来源：[docs/scoring.md](https://github.com/star-ga/mind-mem/blob/main/docs/scoring.md)\n\n## MCP Tools Integration\n\n### Memory Operations Tools\n\nThe MCP layer provides programmatic access to recall functionality:\n\n| Tool | Purpose |\n|------|---------|\n| `index_stats` | FTS5 index state inspection |\n| `reindex` | Rebuild search indices |\n| `get_block` | Direct block retrieval |\n| `memory_health` | Retrieval health dashboard |\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\n## CLI Usage\n\n### Recall Command\n\n```bash\nmm recall \"query\" # search memory\nmm recall \"query\" --limit 10 # limit results\nmm recall \"query\" --active-only # exclude archived blocks\n```\n\n### Context Command\n\nThe `context` command generates token-budgeted snippets using cognitive forgetting logic to pack relevant content within token constraints.\n\n```bash\nmm context \"query\" # generate budgeted context\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\n## Configuration\n\n### Kernel Files\n\nRetrieval behavior is tuned through `.mind` kernel configuration files:\n\n| File | Purpose |\n|------|---------|\n| `bm25.mind` | BM25 parameters (k1, b) |\n| `rrf.mind` | RRF k-value and weights |\n| `recall.mind` | General recall settings |\n\nThe kernel loader supports hot-reloading for runtime tuning:\n\n```python\nfrom mind_mem.mind_ffi import load_kernel_config, get_mind_dir\n\nmind_dir = get_mind_dir(workspace)\ncfg = load_kernel_config(mind_dir, \"rrf\")\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\n## Performance Considerations\n\n### Index Maintenance\n\n- FTS5 indices support incremental updates\n- Periodic reindexing recommended for optimal performance\n- Vector indices may require periodic re-embedding for freshness\n\n### Latency Optimization\n\n- Hybrid recall executes multiple retrieval paths in parallel\n- Cross-encoder reranking applied only to top-N candidates\n- Caching of frequent query patterns recommended\n\n## Related Documentation\n\n- [Scoring System](docs/scoring.md) — Detailed scoring algorithms\n- [Walkthrough Module](src/mind_mem/walkthrough.py) — Dependency-ordered retrieval for teaching\n- [Quality Gate](src/mind_mem/quality_gate.py) — Block quality filtering before storage\n\n---\n\n\n\n## Knowledge Graph & Entity Management\n\n### 相关页面\n\n相关主题：[Hybrid Search & Retrieval](#page-hybrid-search), [Governance & Safety](#page-governance), [Block Format & Data Model](#page-data-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/knowledge_graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/knowledge_graph.py)\n- [src/mind_mem/entity_ingest.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/entity_ingest.py)\n- [src/mind_mem/causal_graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/causal_graph.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/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)\n- [src/mind_mem/mcp/tools/graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/graph.py)\n \n\n# Knowledge Graph & Entity Management\n\n## Overview\n\nThe Knowledge Graph & Entity Management system in mind-mem provides a structured mechanism for capturing, organizing, and querying relationships between entities in the workspace. It extends the basic block storage model with typed edges, entity ontologies, compiled truth pages, and contradiction detection capabilities.\n\nThis system serves multiple purposes:\n\n- **Relationship Tracking**: Records typed relationships (subject-predicate-object triples) between blocks and entities\n- **Entity Classification**: Defines and validates entity types through an ontology registry\n- **Truth Compilation**: Aggregates evidence from multiple sources into canonical entity understanding\n- **Contradiction Detection**: Identifies conflicting claims across evidence entries\n- **Causal Analysis**: Tracks dependency relationships between blocks for impact analysis\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:1-17]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Data Layer\"\n KG[Knowledge Graph
retrieval_graph.db]\n CG[Causal Graph
causal_graph.db]\n TP[Truth Pages
truth/ directory]\n ONT[Ontology
Registry]\n end\n\n subgraph \"Ingestion Layer\"\n EI[Entity Ingest]\n BD[Block Store]\n CD[Contradiction
Detector]\n end\n\n subgraph \"MCP Tools\"\n GQ[graph_query]\n GTA[graph_add_edge]\n TGG[traverse_graph]\n CTL[compiled_truth_load]\n CTA[compiled_truth_add_evidence]\n CTC[compiled_truth_contradictions]\n end\n\n EI --> ONT\n BD --> KG\n BD --> CG\n KG --> GQ\n CG --> TGG\n TP --> CTL\n TP --> CTA\n CD --> CTC\n\n style KG fill:#e1f5fe\n style CG fill:#e8f5e8\n style TP fill:#fff3e0\n style ONT fill:#fce4ec\n```\n\n## Knowledge Graph\n\n### Core Data Model\n\nThe knowledge graph stores typed edges between entities using SQLite. Each edge contains:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `subject` | str | Source entity identifier |\n| `predicate` | str | Relationship type |\n| `object` | str | Target entity identifier |\n| `confidence` | float | Edge confidence (0.0-1.0) |\n| `source_block_id` | str | Block that created this edge |\n| `created_at` | str | ISO timestamp of creation |\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:20-45]()\n\n### Predicate Types\n\nThe system supports predefined predicate types through the `Predicate` enum:\n\n```python\nclass Predicate(str, Enum):\n \"\"\"Predefined relationship types for the knowledge graph.\"\"\"\n DEPENDS_ON = \"depends_on\"\n RELATED_TO = \"related_to\"\n PART_OF = \"part_of\"\n IMPLEMENTS = \"implements\"\n CONTRADICTS = \"contradicts\"\n REFERENCES = \"references\"\n CAUSED_BY = \"caused_by\"\n```\n\n资料来源：[src/mind_mem/knowledge_graph.py]() (inferred from usage patterns)\n\n### MCP Tools for Knowledge Graph\n\n#### `graph_add_edge`\n\nRecords a typed relationship in the knowledge graph.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `subject` | str | Yes | - | Source entity identifier |\n| `predicate` | str | Yes | - | Relationship type |\n| `object` | str | Yes | - | Target entity identifier |\n| `source_block_id` | str | Yes | - | Source block ID |\n| `confidence` | float | No | 1.0 | Edge confidence (0.0-1.0) |\n\n**Returns:**\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"subject\": \"PROJECT-A\",\n \"predicate\": \"depends_on\",\n \"object\": \"PROJECT-B\",\n \"confidence\": 0.95,\n \"edge_id\": 42\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:30-80]()\n\n#### `graph_query`\n\nPerforms N-hop traversal queries on the knowledge graph.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `subject` | str | No | - | Starting node |\n| `predicate` | str | No | - | Filter by predicate type |\n| `object` | str | No | - | Target node |\n| `hops` | int | No | 1 | Number of hops to traverse |\n| `direction` | str | No | \"out\" | \"out\", \"in\", or \"both\" |\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:80-150]()\n\n#### `graph_stats`\n\nReturns aggregate statistics about the knowledge graph.\n\n**Returns:**\n```json\n{\n \"total_edges\": 156,\n \"predicates\": {\n \"depends_on\": 45,\n \"related_to\": 67,\n \"references\": 44\n },\n \"unique_subjects\": 89,\n \"unique_objects\": 102\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:150-200]()\n\n## Entity Management\n\n### Ontology Registry\n\nThe ontology system defines entity types with their required and optional properties:\n\n```mermaid\nclassDiagram\n class EntityType {\n +str name\n +str parent\n +tuple required\n +tuple optional\n +dict property_types\n +validate(data) bool\n }\n\n class Ontology {\n +str name\n +str version\n +dict~str, EntityType~ entity_types\n +get_type(name) EntityType\n +register(entity_type) None\n }\n\n class OntologyRegistry {\n +list ontologies\n +get_default() Ontology\n +register(ontology) None\n }\n\n OntologyRegistry \"1\" --> \"*\" Ontology\n Ontology \"1\" --> \"*\" EntityType\n EntityType --> EntityType : inherits from\n```\n\n资料来源：[src/mind_mem/ontology.py]()\n\n### Built-in Entity Types\n\n| Entity Type | Parent | Required Fields | Optional Fields |\n|-------------|--------|-----------------|-----------------|\n| `ENTITY` | - | (name,) | (description, tags) |\n| `PROJECT` | ENTITY | (name, status) | (owner, priority, deadline) |\n| `PERSON` | ENTITY | (name,) | (role, email, team) |\n| `TOOL` | ENTITY | (name,) | (version, language, category) |\n| `INCIDENT` | ENTITY | (title,) | (severity, status, assignee) |\n| `TASK` | ENTITY | (title,) | (assignee, priority, due) |\n\n资料来源：[src/mind_mem/ontology.py]()\n\n### Entity Ingestion\n\nEntities are ingested through the `entity_ingest` module which:\n\n1. Parses incoming entity data\n2. Validates against the active ontology\n3. Updates or creates entity records\n4. Links entities to their source blocks\n\n资料来源：[src/mind_mem/entity_ingest.py]()\n\n## Compiled Truth Pages\n\nCompiled Truth Pages aggregate evidence from multiple sources into canonical understanding for each entity. This follows a \"memory is never modified except by governance\" principle.\n\n### Data Model\n\n```mermaid\nclassDiagram\n class CompiledTruthPage {\n +str entity_id\n +str entity_type\n +str compiled_section\n +list evidence_entries\n +str last_compiled\n +int version\n }\n\n class EvidenceEntry {\n +str timestamp\n +str source\n +str observation\n +str confidence\n +bool superseded\n }\n\n CompiledTruthPage \"1\" --> \"*\" EvidenceEntry\n```\n\n资料来源：[src/mind_mem/compiled_truth.py]()\n\n### Evidence Entry Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `timestamp` | str | ISO 8601 timestamp of evidence |\n| `source` | str | Source block ID or filename |\n| `observation` | str | The factual claim |\n| `confidence` | str | \"high\", \"medium\", or \"low\" |\n| `superseded` | bool | Whether this entry is outdated |\n\n资料来源：[src/mind_mem/compiled_truth.py:1-50]()\n\n### Truth Page Format\n\nTruth pages are stored as Markdown with YAML frontmatter:\n\n```yaml\n---\nentity_id: PROJECT-ALPHA\nentity_type: PROJECT\nlast_compiled: 2024-01-15T10:30:00Z\nversion: 3\n---\n# PROJECT-ALPHA — Compiled Truth\n\n## Current Understanding\n- Multi-agent orchestration platform\n- Version 2.1.0 deployed to production\n\n## Evidence Trail\n\n### 2024-01-15T10:30:00Z [HIGH] (source: BLOCK-20240115-001)\nCurrent stable release supporting concurrent task execution.\n\n### 2024-01-10T08:00:00Z [MEDIUM] (source: BLOCK-20240110-015) ~~SUPERSEDED~~\nOriginal architecture diagram showing single-threaded design.\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:60-100]()\n\n### Compiled Truth MCP Tools\n\n#### `compiled_truth_load`\n\nLoads a compiled truth page for an entity.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `entity_id` | str | Yes | The entity identifier |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:100-150]()\n\n#### `compiled_truth_add_evidence`\n\nAdds new evidence to an entity's truth page and triggers recompilation.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `entity_id` | str | Yes | - | Entity identifier |\n| `entity_type` | str | Yes | - | Entity type |\n| `observation` | str | Yes | - | The factual claim |\n| `source` | str | Yes | - | Source block ID |\n| `confidence` | str | No | \"medium\" | Confidence level |\n\n**Returns:**\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"entity_id\": \"PROJECT-ALPHA\",\n \"version\": 4,\n \"evidence_count\": 15,\n \"path\": \"/workspace/truth/PROJECT-ALPHA.md\",\n \"message\": \"Evidence added and page recompiled (v4).\"\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:150-220]()\n\n#### `compiled_truth_contradictions`\n\nDetects contradictions within a compiled truth page.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `entity_id` | str | Yes | Entity identifier |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:220-280]()\n\n### Recompilation Process\n\nThe `recompile_truth` function regenerates the compiled section from non-superseded evidence:\n\n1. Filters out superseded evidence entries\n2. Orders remaining entries by timestamp (newest first)\n3. Generates bullet-point summary\n4. Increments version number\n5. Updates `last_compiled` timestamp\n\n资料来源：[src/mind_mem/compiled_truth.py:200-250]()\n\n## Causal Graph\n\nThe causal graph tracks dependency relationships between blocks for impact analysis:\n\n```mermaid\ngraph LR\n A[Decision Made] --> B[Task Created]\n B --> C[Implementation Started]\n A --> D[Risk Assessment]\n C --> E[Code Reviewed]\n D --> F[Mitigation Applied]\n E --> G[Deployed]\n F --> G\n```\n\n### Traversal for Impact Analysis\n\nThe `traverse_graph` function supports:\n\n- **Forward propagation**: \"What blocks depend on this?\"\n- **Backward propagation**: \"What blocks does this depend on?\"\n- **Reachability queries**: \"Are these blocks connected?\"\n- **Critical path identification**: Longest dependency chains\n\n资料来源：[src/mind_mem/causal_graph.py]()\n\n## Contradiction Detection\n\n### Detection Strategy\n\nThe contradiction detector analyzes evidence entries to identify conflicting claims:\n\n1. **Temporal conflict**: Claims that cannot both be true given their timestamps\n2. **Semantic conflict**: Claims with opposing sentiment or meaning\n3. **Logical conflict**: Claims that logically exclude each other based on domain rules\n\n### Detection Function\n\n```python\ndef detect_contradictions(page: CompiledTruthPage) -> list[Contradiction]:\n \"\"\"Detect contradictions in a compiled truth page.\n \n Returns a list of detected contradictions with severity and\n affected evidence indices.\n \"\"\"\n```\n\n资料来源：[src/mind_mem/contradiction_detector.py]()\n\n### Contradiction Resolution\n\nWhen contradictions are detected, the system supports:\n\n1. **Supersession**: Mark older evidence as `superseded=True`\n2. **Escalation**: Flag for human review through the governance workflow\n3. **Version branching**: Create alternative truth pages for competing hypotheses\n\n资料来源：[src/mind_mem/compiled_truth.py:180-200]()\n\n## MCP Tool Summary\n\n| Tool | Domain | Purpose |\n|------|--------|---------|\n| `graph_add_edge` | Knowledge Graph | Add typed relationship |\n| `graph_query` | Knowledge Graph | N-hop traversal queries |\n| `graph_stats` | Knowledge Graph | Graph statistics |\n| `traverse_graph` | Causal Graph | Dependency impact analysis |\n| `compiled_truth_load` | Truth Pages | Load entity truth page |\n| `compiled_truth_add_evidence` | Truth Pages | Add evidence and recompile |\n| `compiled_truth_contradictions` | Truth Pages | Detect conflicts |\n| `list_contradictions` | Governance | List all contradictions |\n| `memory_evolution` | Governance | A-MEM block metadata |\n\n资料来源：[src/mind_mem/mcp/tools/graph.py](), [src/mind_mem/mcp/tools/kernels.py](), [src/mind_mem/mcp/tools/governance.py]()\n\n## Configuration\n\n### Workspace Configuration\n\nIn `mind-mem.json`:\n\n```json\n{\n \"knowledge_graph\": {\n \"enabled\": true,\n \"db_path\": \"intelligence/state/retrieval_graph.db\"\n },\n \"causal_graph\": {\n \"enabled\": true,\n \"db_path\": \"intelligence/state/causal_graph.db\"\n },\n \"truth_pages\": {\n \"enabled\": true,\n \"directory\": \"truth/\"\n },\n \"contradiction_detection\": {\n \"enabled\": true,\n \"severity_threshold\": \"medium\"\n }\n}\n```\n\n### Schema Version\n\nAll MCP tools return responses with `_schema_version` for API compatibility:\n\n```python\nMCP_SCHEMA_VERSION = \"3.2.0\"\n```\n\n资料来源：[src/mind_mem/infra/constants.py]()\n\n---\n\n\n\n## Governance & Safety\n\n### 相关页面\n\n相关主题：[Core Components](#page-components), [Key Concepts](#page-key-concepts), [Block Format & Data Model](#page-data-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/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/audit_chain.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py)\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/abstention_classifier.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/abstention_classifier.py)\n- [mind/governance.mind](https://github.com/star-ga/mind-mem/blob/main/mind/governance.mind)\n- [docs/governance.md](https://github.com/star-ga/mind-mem/blob/main/docs/governance.md)\n- [docs/protection.md](https://github.com/star-ga/mind-mem/blob/main/docs/protection.md)\n \n\n# Governance & Safety\n\nThe mind-mem system implements a multi-layered governance and safety architecture designed to ensure memory integrity, prevent contradictions, detect drift, and enforce quality standards before any block enters the system. The core invariant is: **\"memory is never modified except by governance\"** — meaning every change to the memory state requires explicit approval through a controlled workflow.\n\n## Architecture Overview\n\nThe governance and safety subsystem spans several interconnected components:\n\n```mermaid\ngraph TD\n subgraph \"Ingestion Layer\"\n QG[Quality Gate]\n AC[Abstention Classifier]\n GG[Governance Gate]\n end\n \n subgraph \"Integrity Layer\"\n CT[Compiled Truth]\n CD[Contradiction Detector]\n DD[Drift Detector]\n end\n \n subgraph \"Audit Layer\"\n AU[Audit Chain]\n MH[Merkle Hash]\n end\n \n subgraph \"MCP Tools\"\n PRO[propose_update]\n APP[approve_apply]\n ROLL[rollback_proposal]\n SCAN[scan]\n LIST_CON[List Contradictions]\n end\n \n QG -->|block review| GG\n AC -->|abstain if uncertain| QG\n GG -->|staged proposal| PRO\n PRO -->|pending| APP\n APP -->|apply| CT\n CT -->|evidence| CD\n CT -->|evidence| DD\n AU -->|genesis block| MH\n MH -->|verify| AU\n \n SCAN -->|run all checks| CD\n SCAN -->|run all checks| DD\n LIST_CON -->|contradiction list| CD\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-15]()\n\n## Core Governance Invariants\n\n### The Memory Modification Rule\n\nThe fundamental governance rule is explicit:\n\n> **\"Memory is never modified except by governance\"**\n\nThis means:\n1. No agent can directly write or modify memory blocks\n2. All modifications must go through the governance workflow\n3. The governance workflow includes staged proposals, human review, and audit trails\n4. Rollback capabilities exist to restore from pre-apply snapshots\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:17-20]()\n\n### Governance Workflow States\n\n```mermaid\nstateDiagram-v2\n [*] --> Proposed: propose_update\n Proposed --> Approved: approve_apply\n Proposed --> Rejected: reject\n Approved --> Applied: execute\n Applied --> [*]\n Proposed --> RolledBack: rollback_proposal\n Rejected --> [*]\n RolledBack --> [*]\n```\n\n## Quality Gate\n\nThe quality gate is a pre-storage filter that inspects candidate blocks before they enter the system. It implements 8 deterministic, content-based rules.\n\n资料来源：[src/mind_mem/quality_gate.py:1-20]()\n\n### Quality Rules\n\n| Rule ID | Rule Name | Description | Default Action |\n|---------|-----------|-------------|----------------|\n| 1 | `empty` | Block is whitespace-only | Log only |\n| 2 | `too_short` | Fewer than 32 non-whitespace characters | Log only |\n| 3 | `oversize` | Exceeds 64 KiB of UTF-8 bytes | Log only |\n| 4 | `malformed_utf8` | Contains lone surrogates or cannot round-trip | Log only |\n| 5 | `stopwords_only` | Every token is a stopword (no semantic content) | Log only |\n| 6 | `near_duplicate` | Levenshtein similarity ≥ 0.97 to a recent block (within 24h) | Log only |\n| 7 | `injection_marker` | Matches a known prompt-injection pattern | Log only |\n| 8 | `ok` | No rule fired (happy path) | Accept |\n\n### Quality Gate Modes\n\nThe quality gate operates in two modes:\n\n| Mode | Behavior | Trigger |\n|------|----------|---------|\n| **Advisory** (default) | All rules logged but verdict still `accept` | Default configuration |\n| **Strict** | Any rule that fires causes `reject` | `strict=True` kwarg OR `QualityGateConfig(mode=\"strict\")` OR `mind-mem.json` setting |\n\n资料来源：[src/mind_mem/quality_gate.py:20-45]()\n\n## Abstention Classifier\n\nThe abstention classifier provides an uncertainty-aware filtering layer that can abstain from processing when confidence is insufficient.\n\n资料来源：[src/mind_mem/abstention_classifier.py:1-10]()\n\n## Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity and recompiles canonical understanding. Each truth page contains:\n\n### Data Model\n\n```python\n@dataclass\nclass CompiledTruthPage:\n entity_id: str # Entity identifier\n entity_type: str # Type classification\n compiled_section: str # Regenerated summary\n evidence_entries: list # All evidence items\n last_compiled: str # ISO timestamp\n version: int # Increments on recompile\n```\n\n### Evidence Entry Structure\n\n```python\n@dataclass\nclass EvidenceEntry:\n timestamp: str # ISO timestamp\n source: str # Source identifier\n observation: str # The factual observation\n confidence: str # Confidence level\n superseded: bool # Whether this entry is superseded\n```\n\n### Compiled Truth Workflow\n\n```mermaid\ngraph LR\n subgraph \"Evidence Collection\"\n OBS[New Observation] --> ADD[compiled_truth_add_evidence]\n end\n \n subgraph \"Recompilation\"\n ADD --> REQ[recompile_truth]\n REQ --> GEN[Generate bullet summary]\n REQ --> INC[Increment version]\n REQ --> UPDATE[Update last_compiled]\n end\n \n subgraph \"Output\"\n GEN --> PAGE[Compiled Truth Page]\n INC --> PAGE\n UPDATE --> PAGE\n end\n```\n\n### Key Functions\n\n| Function | Purpose |\n|----------|---------|\n| `load_truth_page(workspace, entity_id)` | Load compiled truth from `{workspace}/entities/compiled/{entity_id}.md` |\n| `save_truth_page(workspace, page)` | Persist truth page to disk |\n| `recompile_truth(page)` | Regenerate compiled section from non-superseded evidence |\n| `supersede_evidence(page, entry_index, reason)` | Mark an evidence entry as superseded |\n| `detect_contradictions(page)` | Scan for conflicting evidence entries |\n\n资料来源：[src/mind_mem/compiled_truth.py:1-150]()\n\n## Contradiction Detection\n\nThe contradiction detector identifies conflicts within compiled truth pages and across the memory system.\n\n### Detection Capabilities\n\n- **Intra-page contradictions**: Conflicting evidence within a single entity's truth page\n- **Cross-page contradictions**: Conflicts between different entities\n- **Temporal conflicts**: Evidence that contradicts based on timing\n- **Confidence-weighted detection**: Higher confidence evidence takes precedence\n\n### Contradiction Result Structure\n\n```python\n@dataclass\nclass ContradictionFinding:\n entity_id: str # Affected entity\n type: str # e.g., \"temporal\", \"factual\", \"confidence\"\n evidence_a: EvidenceEntry # First conflicting entry\n evidence_b: EvidenceEntry # Second conflicting entry\n resolution_hint: str # Suggested resolution\n```\n\n资料来源：[src/mind_mem/contradiction_detector.py:1-30]()\n\n## Drift Detection\n\nDrift detection monitors for changes in memory that deviate from established patterns or governance-approved state.\n\n### Drift Categories\n\n| Category | Description |\n|----------|-------------|\n| **Content Drift** | Gradual semantic shifts in memory content |\n| **Structural Drift** | Changes in block format or organization |\n| **Behavioral Drift** | Patterns in how memory is modified |\n| **Governance Drift** | Deviation from governance-approved workflows |\n\n资料来源：[src/mind_mem/drift_detector.py:1-25]()\n\n## Audit Chain\n\nThe audit chain maintains a cryptographic record of all governance actions using SHA3-512 hashing.\n\n### Audit Chain Components\n\n```mermaid\ngraph TD\n subgraph \"Genesis Block\"\n GB[Genesis Hash]\n end\n \n subgraph \"Audit Records\"\n A1[Action 1 Record]\n A2[Action 2 Record]\n A3[Action 3 Record]\n end\n \n subgraph \"Hash Chain\"\n GB --> H1[Hash 1]\n H1 --> H2[Hash 2]\n H2 --> H3[Hash 3]\n end\n \n A1 --> H1\n A2 --> H2\n A3 --> H3\n```\n\n### Verification Capabilities\n\n| Tool | Purpose |\n|------|---------|\n| `verify_merkle(block_id, content_hash)` | Prove a block's Merkle inclusion against the live tree |\n| `verify_chain()` | Walk both SHA3-512 governance hash chain and evidence chain |\n| `list_evidence(block_id, action)` | Enumerate governance evidence objects with filters |\n\n资料来源：[src/mind_mem/audit_chain.py:1-50]()\n\n## Governance MCP Tools\n\nThe governance functionality is exposed through MCP (Model Context Protocol) tools for agent integration.\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-25]()\n\n### Tool Reference\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| `propose_update` | Stage a new decision/task as a SIGNAL | `block_type`, `statement`, `rationale`, `tags`, `confidence` |\n| `approve_apply` | Apply a staged proposal (dry-run by default) | `signal_id`, `dry_run` |\n| `rollback_proposal` | Restore workspace from pre-apply snapshot | `signal_id` |\n| `scan` | Integrity scan (contradictions/drift/pending) | — |\n| `list_contradictions` | Enriched contradiction listing | `entity_id` (optional) |\n| `memory_evolution` | A-MEM metadata for a block | `block_id` |\n\n### `propose_update` Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `block_type` | `str` | required | Decision or task |\n| `statement` | `str` | required | The proposed content |\n| `rationale` | `str` | \"\" | Justification |\n| `tags` | `str` | \"\" | Comma-separated tags |\n| `confidence` | `str` | \"medium\" | low/medium/high |\n\n### `approve_apply` Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `signal_id` | `str` | required | Signal identifier to apply |\n| `dry_run` | `bool` | `true` | Preview without applying |\n\n### `rollback_proposal` Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `signal_id` | `str` | required | Signal to rollback |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:30-100]()\n\n## Governance Health Benchmark\n\nThe governance health benchmark (`governance_health_bench`) exercises the full governance system:\n\n```mermaid\ngraph TD\n GB[governance_health_bench] --> CD[Contradiction Detection]\n GB --> AC[Audit Completeness]\n GB --> DD[Drift Detection]\n GB --> SC[Scalability Probes]\n \n CD --> CR{Results}\n AC --> CR\n DD --> CR\n SC --> CR\n \n CR --> JSON[JSON Report]\n```\n\n### Benchmark Sub-Suites\n\n| Sub-Suite | Description |\n|-----------|-------------|\n| Contradiction Detection | Tests contradiction detector against known conflict patterns |\n| Audit Completeness | Verifies all governance actions have audit records |\n| Drift Detection | Exercises drift detection with synthetic drift scenarios |\n| Scalability Probes | Performance testing under load |\n\n资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-40]()\n\n## Configuration\n\n### Workspace Configuration\n\nThe governance system respects workspace-level configuration in `mind-mem.json`:\n\n```json\n{\n \"quality_gate_mode\": \"advisory\",\n \"contradiction_detection\": {\n \"enabled\": true,\n \"min_confidence_threshold\": \"medium\"\n },\n \"drift_detection\": {\n \"enabled\": true,\n \"drift_threshold\": 0.15\n }\n}\n```\n\n### Kernel Configuration\n\nMIND kernel files in `.mind` format control governance behavior:\n\n| Kernel File | Purpose |\n|-------------|---------|\n| `governance.mind` | Governance rules and workflow configuration |\n| `contradictions.mind` | Contradiction detection parameters |\n| `protection.mind` | Safety thresholds and limits |\n\n资料来源：[mind/governance.mind:1-30]()\n\n## MCP Resources\n\nGovernance state is also exposed as read-only MCP resources:\n\n| Resource URI | Description |\n|--------------|-------------|\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\n资料来源：[src/mind_mem/mcp/resources.py:1-40]()\n\n## Error Handling\n\n### Structured Error Envelope\n\nAll governance tools return a consistent error format:\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"error\": \"Human-readable error message\"\n}\n```\n\n### Common Error Scenarios\n\n| Scenario | Error Message Pattern |\n|----------|----------------------|\n| Entity not found | \"No compiled truth page found for '{entity_id}'\" |\n| Failed evidence add | \"Failed to add evidence: {exception}\" |\n| Rollback unavailable | \"No snapshot found for signal '{signal_id}'\" |\n| Workspace locked | SQLite busy error (retry-able) |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:60-80]()\n\n## Metrics and Observability\n\nGovernance operations emit metrics for monitoring:\n\n| Metric Name | Description |\n|-------------|-------------|\n| `mcp_kernel_list` | Kernel list operations |\n| `mcp_compiled_truth_add_evidence` | Evidence additions |\n| `evidence_entries_superseded` | Superseded evidence count |\n| `truth_pages_loaded` | Truth page load operations |\n| `contradictions_detected` | New contradictions found |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:35-40]()\n\n## See Also\n\n- [Memory System](./memory-system.md) — Core memory storage and retrieval\n- [MCP Tools](./mcp-tools.md) — MCP tool reference\n- [CLI Reference](./cli-reference.md) — `mm` command-line interface\n- [Protection](./protection.md) — Safety mechanisms and thresholds\n\n---\n\n\n\n## Block Format & Data Model\n\n### 相关页面\n\n相关主题：[Key Concepts](#page-key-concepts), [Hybrid Search & Retrieval](#page-hybrid-search)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.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/schema_version.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/schema_version.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 \n\n# Block Format & Data Model\n\n## Overview\n\nThe mind-mem system uses a **Markdown-based block format** as its primary data model for storing and retrieving structured knowledge. Each block is a self-contained unit of information stored as Markdown text with a specific header format and field structure. This design enables human readability, git-friendly versioning, and flexible querying through the recall system.\n\n资料来源：[src/mind_mem/block_store.py:1-50]()\n\n## Block Structure\n\n### Anatomy of a Block\n\nA mind-mem block consists of three main parts:\n\n```markdown\n[UNIQUE_BLOCK_ID]\nField1: value\nField2: value\nListField:\n- item1\n- item2\nTags: tag1, tag2\n\n---\n```\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| Block ID | Unique identifier in square brackets | `[DECISION-2024-001]` |\n| Fields | Key-value pairs with colon separators | `Status: active` |\n| Separator | `---` marks block end | `---` |\n\n资料来源：[src/mind_mem/block_store.py:45-75]()\n\n### Canonical Field Order\n\nBlocks emit fields in a fixed order to ensure deterministic round-trips. Unknown fields are appended alphabetically after the canonical head.\n\n```python\n_CANONICAL_FIELD_ORDER: tuple[str, ...] = (\n \"Statement\",\n \"Date\",\n \"Status\",\n \"Priority\",\n \"Risk\",\n \"Type\",\n \"Subject\",\n \"Object\",\n \"Tags\",\n \"Rationale\",\n \"Evidence\",\n \"Source\",\n \"Confidence\",\n \"ContentHash\",\n \"Excerpt\",\n \"Action\",\n)\n```\n\n资料来源：[src/mind_mem/block_store.py:28-46]()\n\n### Forbidden Write Fields\n\nThese internal fields are parsed for display but never written back to storage:\n\n```python\n_FORBIDDEN_WRITE_FIELDS: frozenset[str] = frozenset({\n \"_id\", \n \"_source_file\", \n \"_line_number\", \n \"_raw\"\n})\n```\n\n资料来源：[src/mind_mem/block_store.py:48]()\n\n## Block Storage Architecture\n\n### Directory Organization\n\nBlocks are stored across multiple directories based on their type prefix:\n\n```mermaid\ngraph TD\n A[\"Block ID: `[DECISION-xxx]`\"] --> B[\"_BLOCK_PREFIX_MAP\"]\n B --> C[\"`decisions/` directory\"]\n \n A2[\"Block ID: `[TASK-xxx]`\"] --> B\n B --> C2[\"`tasks/` directory\"]\n \n A3[\"Block ID: `[PROJECT-xxx]`\"] --> B\n B --> C3[\"`projects/` directory\"]\n \n A4[\"Block ID: `[INCIDENT-xxx]`\"] --> B\n B --> C4[\"`incidents/` directory\"]\n```\n\n### Block Prefix Mapping\n\nThe system maps block ID prefixes to their canonical storage locations:\n\n| Prefix | Storage Directory | Description |\n|--------|-------------------|-------------|\n| `DECISION` | `decisions/` | Decision records |\n| `TASK` | `tasks/` | Task items |\n| `PROJECT` | `projects/` | Project definitions |\n| `INCIDENT` | `incidents/` | Incident reports |\n| `PERSON` | `people/` | Person entities |\n| `TOOL` | `tools/` | Tool definitions |\n| `SIGNAL` | `signals/` | Auto-captured signals |\n\n资料来源：[src/mind_mem/block_store.py:15-26]()\n\n## Block Rendering\n\n### Serialization Process\n\nThe `_render_block()` function converts a parsed block dictionary back to its Markdown form:\n\n```mermaid\ngraph LR\n A[\"block dict\"] --> B[\"Extract _id\"]\n B --> C[\"Lookup target file\"]\n C --> D[\"Render fields in canonical order\"]\n D --> E[\"Handle list fields as bullets\"]\n E --> F[\"Neutralize \\\\n[ to prevent block collision\"]\n F --> G[\"Output markdown string\"]\n```\n\nKey rendering rules:\n- Lists are rendered as `- item` bullets on lines following the field\n- Multi-line values are emitted verbatim\n- Newline-plus-left-bracket sequences are neutralized to prevent accidental block headers\n\n资料来源：[src/mind_mem/block_store.py:50-85]()\n\n### Write Surface\n\nThe `BlockStore.write_block()` method handles persistence:\n\n```python\ndef write_block(self, block: dict[str, Any]) -> str:\n block_id = block.get(\"_id\")\n target = _resolve_block_file(self._workspace, block_id)\n rendered = _render_block(block)\n \n with FileLock(target):\n # Replace existing or append\n existing_text = fh.read()\n loc = _locate_block_in_text(existing_text, block_id)\n # Insert or append\n```\n\n资料来源：[src/mind_mem/block_store.py:120-160]()\n\n## Compiled Truth Pages\n\n### Purpose\n\nCompiled Truth Pages aggregate evidence for a specific entity into a canonical understanding. They maintain an **evidence trail** showing how knowledge evolved over time.\n\n```mermaid\ngraph TD\n A[\"Evidence Entries
from memory/\"] --> B[\"Compile Process\"]\n B --> C[\"CompiledTruthPage\"]\n C --> D[\"Current Understanding\"]\n C --> E[\"Evidence Trail\"]\n```\n\n### Data Model\n\n```python\nclass CompiledTruthPage:\n entity_id: str\n entity_type: str\n compiled_section: str # Canonical understanding\n evidence_entries: list[EvidenceEntry]\n last_compiled: datetime\n version: str\n\nclass EvidenceEntry:\n timestamp: str\n source: str\n observation: str\n confidence: str # HIGH, MEDIUM, LOW\n superseded: bool # Marked if later evidence contradicts\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:20-50]()\n\n### Markdown Format\n\nCompiled Truth Pages use structured Markdown with YAML frontmatter:\n\n```markdown\n---\nentity_id: postgresql-migration\nentity_type: project\nlast_compiled: 2024-01-15T10:30:00Z\nversion: v3\n---\n\n# postgresql-migration — Compiled Truth\n\n## Current Understanding\nThe migration to PostgreSQL 16 is complete and stable.\n\n## Evidence Trail\n\n### 2024-01-10 [HIGH] (source: decisions.md)\nInitial decision to migrate from MySQL to PostgreSQL.\n\n### 2024-01-12 [MEDIUM] (source: signals.md) ~~SUPERSEDED~~\nInterim report showing migration issues. ~~SUPERSEDED~~\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:55-95]()\n\n### File Operations\n\n| Function | Purpose | Location |\n|----------|---------|----------|\n| `format_truth_page()` | Serialize page to Markdown | `entities/compiled/{entity_id}.md` |\n| `parse_truth_page()` | Parse Markdown back to page object | Read from `entities/compiled/` |\n| `load_truth_page()` | Load from disk, return `None` if missing | `entities/compiled/{entity_id}.md` |\n| `save_truth_page()` | Persist page to disk | `entities/compiled/{entity_id}.md` |\n\n资料来源：[src/mind_mem/compiled_truth.py:95-150]()\n\n## Block Lifecycle\n\n```mermaid\ngraph TD\n A[\"Block Created\"] --> B[\"Quality Gate Check\"]\n B --> C{Pass?}\n C -->|No| D[\"Log verdict
Reject if strict mode\"]\n C -->|Yes| E[\"Parse & Validate\"]\n E --> F[\"Write to canonical file\"]\n F --> G[\"Index for recall\"]\n G --> H[\"Block Active\"]\n H --> I{\"Update proposal?\"}\n I -->|Yes| J[\"Stage as SIGNAL\"]\n I -->|No| K[\"Query via recall API\"]\n```\n\n### Quality Gate Rules\n\nBefore storage, blocks pass through eight deterministic checks:\n\n| Rule | Condition | Default Behavior |\n|------|-----------|-------------------|\n| `empty` | Whitespace-only content | Accept with log |\n| `too_short` | < 32 non-whitespace chars | Accept with log |\n| `oversize` | > 64 KiB UTF-8 bytes | Reject |\n| `malformed_utf8` | Lone surrogates present | Reject |\n| `stopwords_only` | All tokens are stopwords | Accept with log |\n| `near_duplicate` | ≥ 0.97 similarity to recent block | Accept with log |\n| `injection_marker` | Matches known injection patterns | Reject |\n\n资料来源：[src/mind_mem/quality_gate.py:1-30]()\n\n## Deletion & Recovery\n\n### Block Deletion\n\nWhen a block is deleted, its content is preserved in a recovery journal:\n\n```python\ndef _delete_block(self, block_id: str, workspace: str) -> None:\n log_path = os.path.join(workspace, \"memory\", \"deleted_blocks.jsonl\")\n entry = {\n \"block_id\": block_id,\n \"deleted_at\": datetime.now(timezone.utc).isoformat(),\n \"content\": content,\n }\n with open(log_path, \"a\") as f:\n f.write(json.dumps(entry) + \"\\n\")\n```\n\n### Locating Blocks in Text\n\nThe `_locate_block_in_text()` function finds block boundaries:\n\n1. Block starts at line exactly equal to `[]`\n2. Block ends at:\n - Next `[]` header line\n - Isolated `---` separator (preceded by blank line)\n - End of file\n\n资料来源：[src/mind_mem/block_store.py:100-120]()\n\n## Summary\n\nThe mind-mem block format provides:\n\n| Feature | Implementation |\n|---------|----------------|\n| **Storage** | Markdown files organized by type prefix |\n| **Serialization** | Canonical field ordering for deterministic output |\n| **Compiled Truth** | Aggregated evidence with version tracking |\n| **Recovery** | JSONL deletion log for block restoration |\n| **Quality** | Eight-rule pre-storage gate |\n| **Concurrency** | File-level locking via `FileLock` |\n\nThis design enables human-readable storage, git-friendly versioning, and a flexible recall system that can parse and index blocks across the workspace.\n\n---\n\n\n\n## MCP Server & Tools\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/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/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/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/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 \n\n# MCP Server & Tools\n\nThe MCP Server & Tools layer is the primary interface through which AI agents interact with the mind-mem workspace. Built on the FastMCP framework, this component exposes the entire memory system's capabilities—including recall, governance, consolidation, and knowledge management—as a standardized Model Context Protocol (MCP) surface that any MCP-compatible AI client (Claude Code, Cursor, Windsurf, Codex CLI, etc.) can consume.\n\n## Architecture Overview\n\nThe MCP layer is organized as a modular plugin architecture under `src/mind_mem/mcp/`:\n\n```\nmcp/\n├── server.py # FastMCP server entry point\n├── resources.py # @mcp.resource declarations\n├── infra/\n│ ├── rate_limit.py # Rate limiting infrastructure\n│ └── http_auth.py # HTTP authentication\n└── tools/\n ├── recall.py # Memory recall & search\n ├── governance.py # Decision/task governance\n ├── memory_ops.py # Index & lifecycle management\n ├── kernels.py # MIND kernel configuration\n ├── consolidation.py # Memory consolidation\n ├── core.py # Context-core bundle management\n ├── benchmark.py # Governance health benchmarks\n ├── audit.py # Compliance & drift detection\n └── arch_mind.py # Architecture metrics wrapper\n```\n\n### Server Initialization Pattern\n\nThe server uses a deferred registration pattern to avoid circular imports. Tools and resources are defined as module-level functions, then wired onto the FastMCP instance via a `register(mcp)` function call after the server instance is constructed.\n\n```python\n# Resources use module-level definition\ndef get_decisions() -> str:\n \"\"\"Active decisions from DECISIONS.md\"\"\"\n ...\n\n# Registration happens after server construction\ndef register(mcp: FastMCP) -> None:\n mcp.resource(\"mind-mem://decisions\")(get_decisions)\n```\n\nThis pattern ensures that test files referencing `server.get_decisions` continue to work without triggering import-time circular dependencies. 资料来源：[src/mind_mem/mcp/resources.py:1-47]()\n\n## MCP Resources\n\nMCP Resources provide read-only views over the workspace filesystem. They expose the structured content of workspace documents as consumable data without requiring file I/O on the client side.\n\n### Available Resources\n\n| Resource URI | Source Document | Description |\n|-------------|-----------------|-------------|\n| `mind-mem://decisions` | `DECISIONS.md` | Active decisions (ADRs) |\n| `mind-mem://tasks` | `TASKS.md` | All tracked tasks |\n| `mind-mem://entities/{type}` | `memory/entities/*.md` | Projects, people, tools, incidents |\n| `mind-mem://signals` | `memory/signals/` | Auto-captured signals |\n| `mind-mem://contradictions` | `memory/contradictions/` | Detected contradictions |\n| `mind-mem://health` | Computed | Workspace health summary |\n| `mind-mem://recall/{query}` | Computed | BM25 recall search results |\n| `mind-mem://ledger` | `memory/ledger/` | Shared multi-agent fact ledger |\n\nThe resource module consolidates all eight resource types into a single file because each body is small (5–15 lines), they share the same imports, and they form a cohesive read-only surface. 资料来源：[src/mind_mem/mcp/resources.py:1-47]()\n\n## MCP Tools\n\nMCP Tools expose the full operational surface of the mind-mem system. They are organized by domain into eight functional areas.\n\n### Tool Registration Pattern\n\nAll tools are decorated with `@mcp_tool_observe` for observability, which wraps the function to emit metrics and structured logging. Tools also support tracing via the `@_traced` decorator for detailed request tracking.\n\n```python\n@mcp_tool_observe\n@_traced(\"tool_name\")\ndef tool_name(param: str) -> str:\n \"\"\"Tool description.\"\"\"\n ws = _workspace()\n # implementation\n return json.dumps(result, indent=2)\n```\n\n### Tool Domains\n\n## Recall Tools\n\nRecall tools provide the primary memory retrieval surface. They support multiple retrieval backends and output formats.\n\n| Tool | Purpose |\n|------|---------|\n| `recall` | Full-text search with configurable backend (BM25, auto, hybrid) |\n| `context` | Token-budgeted snippet generation |\n| `explain` | Query intent explanation |\n| `trace` | MCP call log tail viewer |\n\nThe recall implementation supports three retrieval backends:\n- **auto** (default): System selects based on query characteristics\n- **bm25**: Classic bag-of-words relevance ranking\n- **hybrid**: Combines BM25 with semantic similarity\n\nOutput formats include `text` (human-readable) and `json` (structured). 资料来源：[src/mind_mem/mm_cli.py:1-100]()\n\n## Governance Tools\n\nGovernance tools implement the \"memory is never modified except by governance\" invariant. They provide a staged update workflow where changes are proposed, reviewed, and then applied atomically.\n\n| Tool | Purpose |\n|------|---------|\n| `propose_update` | Stage a new decision or task as a SIGNAL |\n| `approve_apply` | Apply a staged proposal (dry-run by default) |\n| `rollback_proposal` | Restore workspace from pre-apply snapshot |\n| `scan` | Integrity scan for contradictions, drift, and pending items |\n| `list_contradictions` | Enriched contradiction listing |\n| `memory_evolution` | A-MEM metadata for a block |\n\n### Governance Workflow\n\n```mermaid\ngraph TD\n A[propose_update] --> B{Review}\n B -->|Approve| C[approve_apply]\n B -->|Reject| D[rollback_proposal]\n C --> E[Snapshot Created]\n E --> F[Changes Applied]\n F --> G[Audit Log Updated]\n D --> H[Workspace Restored]\n```\n\nThe governance system maintains append-only audit logs and supports atomic rollback through workspace snapshots. 资料来源：[src/mind_mem/mcp/tools/governance.py:1-60]()\n\n## Memory Operations Tools\n\nMemory operations tools manage the workspace lifecycle and provide introspection capabilities.\n\n| Tool | Purpose |\n|------|---------|\n| `index_stats` | FTS5 index state inspection |\n| `reindex` | Full index rebuild |\n| `delete_memory_item` | Atomic block removal with recovery log |\n| `export_memory` | JSONL dump with configurable metadata and size cap |\n| `get_block` | Block lookup by ID |\n| `memory_health` | Health dashboard |\n| `compact` | Workspace compaction |\n| `stale_blocks` | Staleness-flag management |\n\nDeletion operations are atomic and maintain an append-only recovery log for disaster recovery. The export tool supports size capping to prevent unbounded output when dumping large workspaces. 资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-80]()\n\n## MIND Kernel Tools\n\nMIND Kernel tools provide read-write access to `.mind` configuration files that tune recall, reranking, RM3 expansion, and related pipeline knobs.\n\n| Tool | Purpose |\n|------|---------|\n| `list_mind_kernels` | List available kernel configurations |\n| `get_mind_kernel` | Retrieve specific kernel configuration |\n| `compiled_truth_load` | Load entity truth page |\n| `compiled_truth_add_evidence` | Add evidence to truth page |\n| `compiled_truth_contradictions` | Detect contradictions in truth page |\n\nThese tools interact with the FFI layer (`mind_ffi`) to load and persist kernel configurations stored in the workspace's `.mind/` directory. 资料来源：[src/mind_mem/mcp/tools/kernels.py:1-70]()\n\n## Consolidation Tools\n\nConsolidation tools implement the \"memory settles over time\" principle through cognitive forgetting and autonomous enrichment.\n\n| Tool | Purpose |\n|------|---------|\n| `plan_consolidation` | Dry-run of the cognitive forgetting cycle |\n| `propagate_staleness` | Diffusion of staleness scores over cross-references |\n| `project_profile` | Structured session-start intelligence summary |\n| `dream_cycle` | Autonomous memory enrichment |\n\nThe consolidation cycle analyzes block importance scores, identifies candidates for archival, and optionally auto-repairs broken citations. Configuration parameters include:\n- `importance_threshold` (default: 0.25)\n- `stale_days` (default: 14)\n- `archive_after_days` (default: 60)\n- `grace_days` (default: 30)\n\n```mermaid\ngraph LR\n A[Memory Blocks] --> B[Importance Scoring]\n B --> C{Threshold Check}\n C -->|Low Importance| D[Staleness Propagation]\n C -->|High Importance| E[Retain]\n D --> F[Archive Candidates]\n F --> G[Broken Citation Scan]\n G --> H[Auto-Repair]\n```\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-60]()\n\n## Benchmark Tools\n\nBenchmark tools provide governance health validation and category analysis.\n\n| Tool | Purpose |\n|------|---------|\n| `governance_health_bench` | Run contradiction detection, audit completeness, drift, and scalability probes |\n| `category_summary` | Category distiller lookup with configurable limits |\n\nThe governance health benchmark exercises the full suite of validation checks and returns aggregated pass/fail counts per sub-suite. 资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-60]()\n\n## Core Tools\n\nCore tools manage the `.mmcore` bundle lifecycle for portable block and knowledge-graph archives.\n\n| Tool | Purpose |\n|------|---------|\n| `build_core` | Snapshot blocks and knowledge graph into portable `.mmcore` archive |\n| `load_core` | Load a `.mmcore` bundle into workspace |\n| `unload_core` | Unload and remove core bundle |\n| `list_cores` | List installed cores |\n\nBundles support namespace prefixing for block isolation when loading cores from different sources. 资料来源：[src/mind_mem/mcp/tools/core.py:1-60]()\n\n## Architecture Metrics Tools (arch-mind)\n\nArch-mind tools wrap the `arch-mind` binary to expose architecture quality metrics as MCP tools.\n\n| Tool | Purpose |\n|------|---------|\n| `arch_baseline` | Initialize arch-mind store with baseline |\n| `arch_delta` | Compute (current scan) - (baseline scores) |\n| `arch_history` | List events in arch-mind store |\n| `arch_check_rules` | Apply rules.mind to fresh scan |\n| `arch_session_start` | Open session evidence node |\n| `arch_session_end` | Close session, write delta evidence |\n| `arch_metric_explain` | Per-metric breakdown for a fixture |\n\nThe binary is located via the `ARCH_MIND_BIN` environment variable, falling back to `PATH` lookup. These tools delegate all metric arithmetic to the binary, which enforces the canonical AST schema and Q16.16 determinism contract. 资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-60]()\n\n## CLI Interface (mm)\n\nThe `mm` CLI provides unified access to mind-mem for non-MCP agents. It mirrors the MCP tool surface with command-line equivalents.\n\n### Available Commands\n\n| Command | MCP Equivalent | Description |\n|---------|---------------|-------------|\n| `mm recall \"\"` | recall tool | Search memory |\n| `mm context \"\"` | context tool | Generate token-budgeted snippet |\n| `mm inject --agent \"\"` | inject tool | Render snippet for specific agent |\n| `mm vault scan ` | vault tools | List parsed vault blocks (JSON) |\n| `mm vault write --type --body ` | vault tools | Write vault block |\n| `mm status` | memory_health tool | Workspace summary |\n| `mm explain` | explain tool | Query intent explanation |\n| `mm trace` | trace tool | MCP call log tail |\n\nThe workspace is resolved via `MIND_MEM_WORKSPACE` environment variable, defaulting to `cwd` if unset. 资料来源：[src/mind_mem/mm_cli.py:1-100]()\n\n## Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity and maintains a canonical understanding that recompiles when new evidence is added.\n\n### Data Model\n\n```python\n@dataclass\nclass CompiledTruthPage:\n entity_id: str\n entity_type: str\n compiled_section: str # Canonical understanding\n evidence_entries: list[EvidenceEntry]\n last_compiled: str # ISO timestamp\n version: int\n\n@dataclass\nclass EvidenceEntry:\n timestamp: str\n source: str\n observation: str\n confidence: str # \"high\", \"medium\", \"low\"\n superseded: bool\n```\n\n### Compiled Truth Format\n\nTruth pages are stored as markdown with frontmatter:\n\n```markdown\n---\nentity_id: project-alpha\nentity_type: project\nlast_compiled: 2026-01-15T10:30:00Z\nversion: 3\n---\n\n# project-alpha — Compiled Truth\n\n## Current Understanding\n[Compiled canonical understanding]\n\n## Evidence Trail\n\n### 2026-01-15T10:30:00Z [HIGH] (source: standup-notes.md)\n[Observation text]\n```\n\nEvidence entries are ordered newest-first, with superseded entries marked for visibility. 资料来源：[src/mind_mem/compiled_truth.py:1-100]()\n\n## Observability & Metrics\n\nAll MCP tools are wrapped with `@mcp_tool_observe` for automatic metrics emission. The observability layer tracks:\n\n- Tool invocation counts per tool name\n- Error rates and exception types\n- Latency percentiles\n- Workspace-scoped activity\n\nTools can optionally use the `@_traced` decorator for detailed request tracing that captures the full call chain. 资料来源：[src/mind_mem/mcp/tools/governance.py:1-50]()\n\n## Agent Integration\n\nThe `hook_installer` module provides declarative integration for various AI coding clients:\n\n| Agent | Config Format | Detection |\n|-------|--------------|-----------|\n| claude | JSON config block | `claude` binary |\n| cursor | JSON config block | `cursor` binary |\n| windsurf | MCP JSON | `windsurf` binary |\n| aider | YAML block | `aider` binary |\n| openclaw | JSON hooks | `~/.openclaw/` path |\n| copilot | Text block | Always offered |\n| cody | JSON generic | `cody` binary |\n| qodo | Text block | `~/.codium/` path |\n\nEach agent type has a canonical config file path, content template with the `MIND_MEM_MARKER`, and detection strategy (binary presence, config path, or explicit flag). 资料来源：[src/mind_mem/hook_installer.py:1-200]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `MIND_MEM_WORKSPACE` | Workspace root directory | `cwd` |\n| `MIND_MEM_MCP_SERVER` | Override MCP server path | Auto-detect |\n| `ARCH_MIND_BIN` | arch-mind binary path | `arch-mind` on PATH |\n| `MIND_MEM_LOG_FILE` | Structured JSON log path | stderr |\n\n### Workspace Structure\n\n```\nworkspace/\n├── DECISIONS.md # Active decisions\n├── TASKS.md # Task tracking\n├── memory/\n│ ├── entities/ # Entity truth pages\n│ ├── signals/ # Auto-captured signals\n│ ├── contradictions/ # Detected contradictions\n│ ├── ledger/ # Multi-agent fact ledger\n│ └── cores/ # .mmcore bundles\n└── .mind/ # Kernel configurations\n```\n\n## Summary\n\nThe MCP Server & Tools layer transforms mind-mem from a library into a first-class AI teammate interface. By exposing all capabilities through the Model Context Protocol:\n\n1. **Recall** becomes a first-class tool with configurable backends and output formats\n2. **Governance** enforces change management through propose-apply-rollback workflows\n3. **Consolidation** runs autonomously based on configurable importance thresholds\n4. **Observability** tracks all tool usage for audit and improvement\n\nThe modular tool organization allows clients to consume only the capabilities they need while maintaining a coherent system that enforces invariants like \"memory is never modified except by governance.\"\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 项目说明书",
"目录",
"Overview",
"Purpose and Scope",
"Architecture Overview",
"Workspace Structure",
"MCP Server Surface",
"CLI Interface",
"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": "24bb14e29ed43330b60b80d3d5fdfaf039dbd1b3",
"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- 文件总数：828\n- 重要文件覆盖：40/828\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 MIND Language Profile: default full tensor stdlib + Q16.16 + heap — see Phase 10.6 证据：`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- **Overview**：importance `high`\n - source_paths: README.md, SPEC.md, docs/architecture.md\n- **Key Concepts**：importance `high`\n - source_paths: docs/block-format.md, docs/mic-map.md, src/mind_mem/block_store.py, src/mind_mem/namespaces.py, src/mind_mem/mcp/infra/acl.py\n- **Quick Start Guide**：importance `high`\n - source_paths: install.sh, demo-setup.sh, docs/getting-started.md, docs/quickstart.md, examples/basic_usage.py\n- **System Architecture**：importance `high`\n - source_paths: docs/architecture.md, src/mind_mem/mcp/server.py, src/mind_mem/recall.py, src/mind_mem/memory_mesh.py, src/mind_mem/knowledge_graph.py\n- **Core Components**：importance `high`\n - source_paths: src/mind_mem/recall.py, src/mind_mem/block_store.py, src/mind_mem/apply_engine.py, src/mind_mem/conflict_resolver.py, src/mind_mem/drift_detector.py\n- **Hybrid Search & Retrieval**：importance `high`\n - source_paths: src/mind_mem/bm25.mind, src/mind_mem/recall_vector.py, src/mind_mem/rrf.mind, src/mind_mem/query_expansion.py, src/mind_mem/intent_router.py\n- **Knowledge Graph & Entity Management**：importance `medium`\n - source_paths: src/mind_mem/knowledge_graph.py, src/mind_mem/entity_ingest.py, src/mind_mem/causal_graph.py, src/mind_mem/compiled_truth.py, src/mind_mem/contradiction_detector.py\n- **Governance & Safety**：importance `high`\n - source_paths: src/mind_mem/governance_gate.py, src/mind_mem/contradiction_detector.py, src/mind_mem/drift_detector.py, src/mind_mem/audit_chain.py, src/mind_mem/quality_gate.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `24bb14e29ed43330b60b80d3d5fdfaf039dbd1b3`\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-17 19:29:27 UTC\n\n## 目录\n\n- [Overview](#page-overview)\n- [Key Concepts](#page-key-concepts)\n- [Quick Start Guide](#page-quickstart)\n- [System Architecture](#page-architecture)\n- [Core Components](#page-components)\n- [Hybrid Search & Retrieval](#page-hybrid-search)\n- [Knowledge Graph & Entity Management](#page-knowledge-graph)\n- [Governance & Safety](#page-governance)\n- [Block Format & Data Model](#page-data-model)\n- [MCP Server & Tools](#page-mcp-server)\n\n\n\n## Overview\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Quick Start Guide](#page-quickstart), [MCP Server & Tools](#page-mcp-server)\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/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/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/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/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [src/mind_mem/protection.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/protection.py)\n \n\n# Overview\n\n**MIND-Mem** is a multi-agent memory and knowledge management system designed to provide persistent, queryable memory for AI coding assistants. It maintains a structured workspace containing decisions, tasks, entities, signals, and contradictions—enabling AI agents to recall relevant context across sessions while enforcing governance rules that prevent unauthorized memory modifications.\n\n## Purpose and Scope\n\nMIND-Mem solves the context window exhaustion problem in long-running AI-assisted development by:\n\n- **Storing structured memories** in markdown files organized by type (DECISIONS.md, TASKS.md, entities, signals)\n- **Providing fast retrieval** via BM25 full-text search and FTS5 SQLite indexes\n- **Enforcing governance** through a propose → approve → apply workflow\n- **Maintaining audit trails** with SHA3-512 hash chains and Merkle proofs\n- **Supporting compiled truth pages** that aggregate evidence for key entities\n\n资料来源：[src/mind_mem/compiled_truth.py:1-30]()\n\n## Architecture Overview\n\nThe system consists of several interconnected layers:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[CLI mm]\n MCP[MCP Server]\n WEB[Web Console]\n end\n \n subgraph \"Core Engine\"\n RECALL[Recall Engine]\n IDX[FTS5 Index]\n GOV[Governance]\n AUDIT[Audit Chain]\n end\n \n subgraph \"Storage Layer\"\n MARKDOWN[Markdown Files]\n SQLITE[SQLite DB]\n KERNEL[.mind Kernel Configs]\n end\n \n CLI --> MCP\n WEB --> RECALL\n RECALL --> IDX\n RECALL --> MARKDOWN\n GOV --> MARKDOWN\n AUDIT --> IDX\n KERNEL --> RECALL\n```\n\n资料来源：[src/mind_mem/mm_cli.py:1-25]()\n\n## Workspace Structure\n\nEach workspace managed by MIND-Mem follows a canonical directory layout:\n\n| Directory | Purpose |\n|-----------|---------|\n| `memory/` | Individual memory blocks as markdown files |\n| `entities/` | Entity definitions and compiled truth pages |\n| `compiled/` | Compiled truth pages (`entities/compiled/`) |\n| `.mind/` | MIND kernel configuration files |\n| `signals/` | Staged governance proposals |\n| `snapshots/` | Pre-apply rollback snapshots |\n\n资料来源：[src/mind_mem/compiled_truth.py:80-100]()\n\n## MCP Server Surface\n\nThe MCP (Model Context Protocol) server exposes a comprehensive tool surface organized into domains:\n\n### Core Tool Domains\n\n| Domain | Tools | Purpose |\n|--------|-------|---------|\n| **Governance** | `propose_update`, `approve_apply`, `rollback_proposal`, `scan`, `list_contradictions`, `memory_evolution` | Memory modification workflow |\n| **Memory Ops** | `index_stats`, `reindex`, `delete_memory_item`, `export_memory`, `get_block`, `memory_health`, `compact`, `stale_blocks` | Workspace lifecycle |\n| **Kernels** | `list_mind_kernels`, `get_mind_kernel`, `compiled_truth_load`, `compiled_truth_add_evidence`, `compiled_truth_contradictions` | Kernel configuration access |\n| **Audit** | `verify_merkle`, `verify_chain`, `list_evidence`, `mind_mem_verify` | Integrity verification |\n| **Benchmark** | `governance_health_bench`, `category_summary` | Health diagnostics |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-30]()\n\n### MCP Resources\n\nThe server also exposes read-only resources via the MCP resource protocol:\n\n| Resource URI | Content |\n|--------------|---------|\n| `mind-mem://decisions` | Active decisions from DECISIONS.md |\n| `mind-mem://tasks` | All tasks from TASKS.md |\n| `mind-mem://entities/{type}` | Projects, people, tools, incidents |\n| `mind-mem://signals` | Auto-captured signals |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search results |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\n资料来源：[src/mind_mem/mcp/resources.py:1-40]()\n\n## CLI Interface\n\nThe `mm` command provides a unified interface for non-MCP agents:\n\n```bash\nmm recall \"\" # Search memory with BM25\nmm context \"\" # Generate token-budgeted snippet\nmm inject --agent \"\" # Render snippet for specific agent\nmm vault scan # List parsed vault blocks (JSON)\nmm vault write --type --body \nmm status # Workspace summary\n```\n\n资料来源：[src/mind_mem/mm_cli.py:30-55]()\n\n## Governance Model\n\nMIND-Mem enforces an invariant: **memory is never modified except by governance**. The governance workflow:\n\n```mermaid\ngraph LR\n A[Propose] --> B{Human Review}\n B -->|Approved| C[Apply/Dry-Run]\n B -->|Rejected| D[Discard]\n C -->|Dry-Run| E[Review Changes]\n E -->|Confirm| F[Commit]\n F --> G[Snapshot Stored]\n C -->|Direct| F\n G --> H[Rollback Available]\n```\n\nKey governance tools:\n- `propose_update` — Stage a new decision/task as a SIGNAL\n- `approve_apply` — Apply a staged proposal (dry-run by default)\n- `rollback_proposal` — Restore workspace from pre-apply snapshot\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:35-60]()\n\n## Compiled Truth System\n\nCompiled truth pages aggregate evidence for key entities, enabling efficient retrieval of canonical understanding:\n\n```mermaid\ngraph TD\n A[Memory Files] --> B[Sentence Extraction]\n B --> C[Fact Candidates]\n C --> D{min_mentions?}\n D -->|≥3| E[Promote to Truth]\n E --> F[Compiled Section]\n G[New Evidence] --> H[Add Entry]\n H --> I[Recompile]\n I --> F\n```\n\nThe system supports:\n- **Evidence entries** with timestamps, sources, and confidence levels\n- **Superseding** outdated evidence\n- **Version tracking** with recompilation\n\n资料来源：[src/mind_mem/compiled_truth.py:150-200]()\n\n## Integrity and Audit\n\nMIND-Mem provides cryptographic integrity guarantees:\n\n### Protection Module\n\nThe protection system validates critical module integrity:\n\n- **Critical modules** include recall, vector search, apply engine, audit chain, encryption, graph recall, rerank ensemble, consensus vote, tenant audit, and governance\n- **Integrity manifest** (`_integrity_manifest.json`) stores SHA-256 hashes\n- **Strict mode** available via `MIND_MEM_INTEGRITY` environment variable\n\n资料来源：[src/mind_mem/protection.py:35-60]()\n\n### Audit Chain\n\n| Verification Type | Description |\n|-------------------|-------------|\n| **Merkle Proofs** | Prove block inclusion against live Merkle tree |\n| **Hash Chain** | SHA3-512 chain verification for governance records |\n| **Evidence Chain** | Walk and verify evidence relationships |\n| **Manifest Signing** | Ed25519 signatures on model audit checkpoints |\n\n资料来源：[src/mind_mem/mcp/tools/audit.py:1-30]()\n\n## Agent Integration\n\nMIND-Mem supports integration with various AI coding assistants through a declarative registry:\n\n| Agent | Config Format | Status |\n|-------|---------------|--------|\n| Claude | JSON/CLaude Desktop | Configurable |\n| Cursor | Custom config | Hook-based |\n| Windsurf | Custom config | Hook-based |\n| Codex CLI | MCP native | Supported |\n\nThe hook installer resolves the MCP server path through:\n1. `MIND_MEM_MCP_SERVER` environment variable (explicit override)\n2. `/../mcp_server.py` (src-layout checkout)\n3. `/mcp_server.py` (packaged install)\n\n资料来源：[src/mind_mem/hook_installer.py:20-45]()\n\n## v4.0 Surface\n\nThe v4.0 implementation is gated by feature flags in `mind-mem.json` under the `v4` key:\n\n| Group | Features |\n|-------|----------|\n| **A. Cognition** | Tier-aware blocks, Cognitive Mind Kernel API, surprise-weighted retrieval |\n| **B. Knowledge Graph** | Block kinds, long-context recall, LLM fusion, streaming, conversational chat |\n| **C. Governance UX** | Idle ingest, AI lint, contradiction states, self-healing index |\n\nWithout the feature flag, v3.x behavior is preserved unchanged.\n\n资料来源：[src/mind_mem/v4/__init__.py:1-40]()\n\n## Web Console\n\nA Next.js web interface provides visual exploration:\n\n```mermaid\ngraph LR\n A[API /v1/recall] --> B[Bundle Response]\n B --> C[GraphView]\n B --> D[TimelineView]\n B --> E[FactList]\n C --> F[d3-force graph]\n D --> G[Chronological events]\n E --> H[Extracted claims]\n```\n\nComponents:\n- `app/page.tsx` — Single-page console\n- `components/GraphView.tsx` — Force-directed block graph\n- `components/TimelineView.tsx` — Dated events timeline\n- `components/FactList.tsx` — Extracted facts with confidence\n\n资料来源：[web/README.md:1-30]()\n\n## Configuration\n\n### Workspace Resolution\n\nThe workspace is resolved in order:\n1. `MIND_MEM_WORKSPACE` environment variable\n2. Current working directory (`cwd`)\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### MCP Server Invocation\n\nThe canonical MCP server invocation record:\n\n```python\n{\n \"command\": \"python3\",\n \"args\": [\"mcp_server.py\"],\n \"env\": {\"MIND_MEM_WORKSPACE\": workspace}\n}\n```\n\n资料来源：[src/mind_mem/hook_installer.py:50-70]()\n\n## Quick Start\n\n```bash\n# Install\npip install -e .\n\n# Initialize workspace\nmm status\n\n# Search memory\nmm recall \"authentication\"\n\n# Context for agent\nmm context \"database schema\"\n\n# Web interface\ncd web && pnpm install && pnpm dev\n```\n\n资料来源：[examples/README.md:1-20]()\n\n## Summary\n\nMIND-Mem provides a robust multi-agent memory system with:\n\n- **Structured storage** for decisions, tasks, entities, and signals\n- **Fast retrieval** via BM25 and FTS5 indexes\n- **Governance-first** memory modification workflow\n- **Cryptographic integrity** through Merkle proofs and hash chains\n- **Extensive tooling** via CLI, MCP server, and web console\n- **Agent integration** support for Claude, Cursor, Codex, and more\n\n---\n\n\n\n## Key Concepts\n\n### 相关页面\n\n相关主题：[Overview](#page-overview), [Block Format & Data Model](#page-data-model), [Governance & Safety](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/block-format.md](https://github.com/star-ga/mind-mem/blob/main/docs/block-format.md)\n- [docs/mic-map.md](https://github.com/star-ga/mind-mem/blob/main/docs/mic-map.md)\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/namespaces.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/namespaces.py)\n- [src/mind_mem/mcp/infra/acl.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/infra/acl.py)\n \n\n# Key Concepts\n\nMind-Mem is a persistent memory system designed for multi-agent workflows. It stores structured knowledge as markdown \"blocks\" that can be recalled, reasoned about, and governed by a set of declarative rules. Understanding the core data model and access control mechanisms is essential for effective use.\n\n---\n\n## Block Format\n\n### Overview\n\nBlocks are the fundamental storage unit in Mind-Mem. Each block represents a discrete unit of knowledge—a decision, task, signal, fact, or entity record—stored as structured Markdown with a consistent header format.\n\n```mermaid\ngraph LR\n A[Block Header
[ID]] --> B[Field: Value]\n B --> C[Field: Value]\n C --> D[Blank Line]\n D --> E[Optional Body
Content]\n E --> F[Block Separator
---]\n```\n\n资料来源：[src/mind_mem/block_store.py:1-50]()\n\n### Block Header Structure\n\nEvery block begins with a unique identifier in the format `[block-id]`:\n\n```\n[Dcision-2024-001]\n\nStatement: PostgreSQL shall be the primary relational store\nDate: 2024-01-15\nStatus: Active\nType: Decision\nRationale: Proven reliability and extensive tooling ecosystem\nConfidence: high\nTags: infrastructure, database, postgresql\n```\n\n资料来源：[docs/block-format.md:1-30]()\n\n### Canonical Field Order\n\nBlocks emit fields in a fixed order to ensure deterministic round-trips:\n\n| Order | Field | Description |\n|-------|-------|-------------|\n| 1 | `Statement` | Core claim or action |\n| 2 | `Date` | ISO-8601 timestamp |\n| 3 | `Status` | Active, Superseded, Deprecated |\n| 4 | `Priority` | High, Medium, Low |\n| 5 | `Risk` | Risk assessment level |\n| 6 | `Type` | Decision, Task, Signal, Fact, Entity |\n| 7 | `Subject` | Primary entity of interest |\n| 8 | `Object` | Secondary entity or target |\n| 9 | `Tags` | Comma-separated labels |\n| 10 | `Rationale` | Explanation or justification |\n| 11 | `Evidence` | Supporting data or references |\n| 12 | `Source` | Origin of the information |\n| 13 | `Confidence` | low, medium, high |\n| 14 | `ContentHash` | SHA-256 content fingerprint |\n| 15 | `Excerpt` | Brief summary |\n| 16 | `Action` | Next step or task |\n\n资料来源：[src/mind_mem/block_store.py:180-200]()\n\n### Block Types and Prefixes\n\nMind-Mem uses a prefix-based mapping system to organize blocks into subdirectories:\n\n| Block Type | Prefix | Storage Path |\n|------------|--------|--------------|\n| Decision | `D` | `decisions/` |\n| Task | `T` | `tasks/` |\n| Signal | `S` | `signals/` |\n| Fact | `F` | `facts/` |\n| Entity | `E` | `entities/` |\n| Note | `N` | `notes/` |\n| Project | `P` | `projects/` |\n\n资料来源：[src/mind_mem/block_store.py:160-175]()\n\n### Forbidden Write Fields\n\nThe following synthetic fields are emitted during parsing but are never persisted back to storage:\n\n- `_id` — synthetic parse-time block identifier\n- `_source_file` — tool-side hint for source tracking\n- `_line_number` — original file location\n- `_raw` — unprocessed block content\n\n资料来源：[src/mind_mem/block_store.py:201-205]()\n\n---\n\n## Namespaces\n\n### Overview\n\nNamespaces provide logical isolation between different workspaces, tenants, or organizational units within Mind-Mem. They ensure that blocks and their associated metadata remain segregated while sharing common infrastructure.\n\n```mermaid\ngraph TD\n subgraph Workspace1\n NS1[namespace: default]\n B1[Block Store]\n NS1 --> B1\n end\n \n subgraph Workspace2\n NS2[namespace: project-a]\n B2[Block Store]\n NS2 --> B2\n end\n \n subgraph Shared\n ACL[Access Control List]\n Meta[Metadata Index]\n end\n \n NS1 --> ACL\n NS2 --> ACL\n```\n\n资料来源：[src/mind_mem/namespaces.py:1-40]()\n\n### Namespace Resolution\n\nNamespaces are resolved in the following priority order:\n\n1. Explicit `namespace` parameter in API calls\n2. `MIND_MEM_NAMESPACE` environment variable\n3. Workspace-specific configuration in `mind-mem.json`\n4. Default namespace (`default`)\n\n```python\ndef resolve_namespace(workspace: str, explicit: Optional[str] = None) -> str:\n if explicit:\n return explicit\n env_namespace = os.environ.get(\"MIND_MEM_NAMESPACE\")\n if env_namespace:\n return env_namespace\n config = load_workspace_config(workspace)\n return config.get(\"namespace\", \"default\")\n```\n\n资料来源：[src/mind_mem/namespaces.py:45-60]()\n\n### Namespace-Qualified Identifiers\n\nBlock IDs can be namespace-qualified using the format `:`:\n\n```\nproject-a:Dcision-2024-001\ndefault:Task-2024-015\nteam-infra:Fact-2024-003\n```\n\n资料来源：[src/mind_mem/namespaces.py:70-85]()\n\n---\n\n## Access Control Lists (ACL)\n\n### Overview\n\nMind-Mem implements a declarative ACL system that governs read and write access to blocks based on requester identity, namespace, and operation type.\n\n```mermaid\ngraph LR\n A[Request] --> B[ACL Engine]\n B --> C{Namespace Match?}\n C -->|Yes| D{Operation Allowed?}\n C -->|No| E[Deny: Unknown Namespace]\n D -->|Yes| F[Allow]\n D -->|No| G[Deny: Permission Denied]\n```\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:1-50]()\n\n### ACL Entry Structure\n\nEach ACL entry defines a permission rule:\n\n```json\n{\n \"subject\": \"agent:cody\",\n \"namespace\": \"project-a\",\n \"permissions\": [\"read\", \"write\"],\n \"conditions\": {\n \"block_types\": [\"decision\", \"task\", \"signal\"],\n \"max_age_days\": 30\n }\n}\n```\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:55-70]()\n\n### Permission Types\n\n| Permission | Description | Applicable Operations |\n|------------|-------------|----------------------|\n| `read` | View block content | `get_block`, `recall`, `search` |\n| `write` | Create or modify blocks | `create_block`, `update_block` |\n| `delete` | Remove blocks | `delete_block`, `archive_block` |\n| `govern` | Approve/reject proposals | `approve_apply`, `rollback` |\n| `admin` | Full namespace control | `scan`, `audit`, `reconcile` |\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:75-90]()\n\n### Built-in Roles\n\nMind-Mem ships with predefined roles for common use cases:\n\n| Role | Permissions | Use Case |\n|------|-------------|----------|\n| `viewer` | read | Read-only dashboards, reports |\n| `contributor` | read, write | Standard agents adding knowledge |\n| `governor` | read, write, govern | Governance workflow participants |\n| `admin` | read, write, delete, govern, admin | Full workspace management |\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:95-110]()\n\n### ACL Evaluation Logic\n\n```python\ndef evaluate_acl(request: RequestContext) -> AccessDecision:\n # 1. Check for wildcard (allow all)\n if _has_wildcard_entry(request.namespace, request.subject):\n return AccessDecision(allowed=True, reason=\"wildcard_match\")\n \n # 2. Check explicit deny entries\n for entry in _deny_entries(request.namespace, request.subject):\n if _matches_conditions(request, entry.conditions):\n return AccessDecision(allowed=False, reason=\"explicit_deny\")\n \n # 3. Check explicit allow entries\n for entry in _allow_entries(request.namespace, request.subject):\n if request.operation in entry.permissions:\n if _matches_conditions(request, entry.conditions):\n return AccessDecision(allowed=True, reason=\"explicit_allow\")\n \n # 4. Default: deny\n return AccessDecision(allowed=False, reason=\"default_deny\")\n```\n\n资料来源：[src/mind_mem/mcp/infra/acl.py:120-150]()\n\n---\n\n## Block Storage Architecture\n\n### Directory Structure\n\nMind-Mem organizes blocks hierarchically under the workspace root:\n\n```\nworkspace/\n├── CLAUDE.md\n├── mind-mem.json\n├── decisions/\n│ └── D-*.md\n├── tasks/\n│ └── T-*.md\n├── signals/\n│ └── S-*.md\n├── facts/\n│ └── F-*.md\n├── entities/\n│ ├── projects/\n│ ├── people/\n│ └── tools/\n├── memory/\n│ └── *.md\n├── .ledger/\n│ └── ledger.db\n└── .signals/\n └── signals.db\n```\n\n资料来源：[src/mind_mem/block_store.py:50-100]()\n\n### Block Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Draft: create_block\n Draft --> Active: approve_apply\n Active --> Superseded: newer version\n Active --> Deprecated: manual\n Active --> Archived: delete_block\n Draft --> Rejected: governance_reject\n Superseded --> Archived: cleanup\n Deprecated --> [*]\n Archived --> Recoverable: restore_block\n```\n\n资料来源：[src/mind_mem/block_store.py:100-130]()\n\n### Quality Gates\n\nBefore storage, blocks pass through a deterministic quality gate:\n\n| Rule | Condition | Default Action |\n|------|-----------|----------------|\n| `empty` | Whitespace-only content | Log warning |\n| `too_short` | Fewer than 32 non-whitespace chars | Log warning |\n| `oversize` | Exceeds 64 KiB | Reject (strict) |\n| `malformed_utf8` | Contains lone surrogates | Reject (strict) |\n| `stopwords_only` | All tokens are stopwords | Log warning |\n| `near_duplicate` | Levenshtein similarity ≥ 0.97 | Log warning |\n| `injection_marker` | Matches prompt-injection patterns | Reject (strict) |\n| `ok` | No rule fired | Accept |\n\n资料来源：[src/mind_mem/quality_gate.py:1-50]()\n\n---\n\n## Recall and Retrieval\n\n### BM25 Search\n\nMind-Mem uses BM25 (Best Matching 25) for keyword-based retrieval:\n\n```python\ndef recall(workspace: str, query: str, limit: int = 10, active_only: bool = True):\n # 1. Parse all blocks in workspace\n blocks = parse_workspace_blocks(workspace, active_only=active_only)\n \n # 2. Build inverted index\n index = build_bm25_index(blocks)\n \n # 3. Score and rank results\n scores = index.score(query)\n \n # 4. Return top-k results with metadata\n return sorted(scores, key=lambda x: x.score, reverse=True)[:limit]\n```\n\n资料来源：[src/mind_mem/recall.py:1-40]()\n\n### Compiled Truth Pages\n\nFact blocks can be aggregated into compiled truth pages that consolidate evidence across multiple sources:\n\n```mermaid\ngraph LR\n A[Evidence A] --> B[Compiled Truth Page]\n C[Evidence B] --> B\n D[Evidence C] --> B\n B --> E[Current Understanding]\n B --> F[Evidence Trail]\n F --> G[Timestamped Entries]\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:1-60]()\n\n---\n\n## Governance Model\n\n### Proposal Workflow\n\nAll changes to the knowledge base flow through a governed proposal system:\n\n```mermaid\ngraph LR\n A[propose_update] --> B[Staged in SIGNALS.md]\n B --> C[Human Review]\n C -->|Approve| D[approve_apply]\n C -->|Reject| E[Rollback]\n D --> F[Active Block]\n E --> G[Discarded]\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-50]()\n\n### Governance Rules\n\n| Rule | Description |\n|------|-------------|\n| Immutability | Active blocks cannot be directly modified |\n| Audit Trail | Every state change is logged with timestamp and actor |\n| Separation | Agents propose; humans approve |\n| Rollback | Failed applications can be restored from snapshots |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:50-80]()\n\n---\n\n## Configuration\n\n### Workspace Configuration (`mind-mem.json`)\n\n```json\n{\n \"namespace\": \"default\",\n \"quality_gate_mode\": \"advisory\",\n \"recall_limit\": 20,\n \"mcp_schema_version\": \"3.2.0\",\n \"acl\": {\n \"default_policy\": \"allow\",\n \"entries\": []\n }\n}\n```\n\n资料来源：[src/mind_mem/infra/constants.py:1-30]()\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MIND_MEM_WORKSPACE` | Workspace root directory | Current working directory |\n| `MIND_MEM_NAMESPACE` | Override namespace | From config |\n| `MIND_MEM_LOG_FILE` | Structured log output path | stderr |\n| `MIND_MEM_MCP_SERVER` | Path to MCP server binary | Auto-detected |\n\n资料来源：[src/mind_mem/infra/workspace.py:1-40]()\n\n---\n\n## Related Documentation\n\n- [Block Format Specification](docs/block-format.md)\n- [MIC Map Reference](docs/mic-map.md)\n- [MCP Tools Documentation](src/mind_mem/mcp/tools/)\n- [API Reference](src/mind_mem/api/)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Overview](#page-overview), [MCP Server & Tools](#page-mcp-server)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/README.md](https://github.com/star-ga/mind-mem/blob/main/examples/README.md)\n- [examples/basic_usage.py](https://github.com/star-ga/mind-mem/blob/main/examples/basic_usage.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/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n- [src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n \n\n# Quick Start Guide\n\n## Overview\n\nThe Quick Start Guide provides a comprehensive introduction to **mind-mem**, a persistent memory system designed for AI coding assistants. Mind-mem enables multi-agent teams to store, recall, and govern structured memory blocks across development sessions.\n\n**Purpose and Scope**\n\nMind-mem serves as a unified memory layer that:\n- Parses and indexes markdown-based memory blocks (DECISIONS, TASKS, SIGNALS, etc.)\n- Provides BM25 and vector-based recall capabilities\n- Supports MCP (Model Context Protocol) integration for AI assistants\n- Implements governance workflows for memory evolution\n- Offers a CLI (`mm`) for direct workspace interaction\n\nThis guide walks through installation, workspace initialization, basic operations, and first steps for integrating mind-mem into your development workflow.\n\n资料来源：[examples/README.md:1-15]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n CLI[\"mm CLI\"]\n MCP[\"MCP Server\"]\n WEB[\"Web Console\"]\n end\n \n subgraph \"Core Modules\"\n RECALL[\"recall.py
BM25 + Vector Recall\"]\n COGNITIVE[\"cognitive_forget.py
Token Budget Packing\"]\n PARSER[\"block_parser.py
Markdown Parsing\"]\n end\n \n subgraph \"Storage Layer\"\n FTS[\"FTS Index
SQLite FTS5\"]\n META[\"Block Metadata\"]\n end\n \n CLI --> RECALL\n MCP --> RECALL\n WEB --> RECALL\n RECALL --> PARSER\n RECALL --> FTS\n PARSER --> META\n```\n\nThe system follows a layered architecture where the CLI and MCP server expose recall and governance APIs, while the core modules handle parsing, indexing, and retrieval.\n\n资料来源：[src/mind_mem/mm_cli.py:1-25]()\n\n## Prerequisites\n\nBefore getting started with mind-mem, ensure your environment meets these requirements:\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required for core package |\n| SQLite | 3.35+ | Built-in FTS5 support needed |\n| pip | 21.0+ | For package installation |\n| Node.js | 18+ | Optional, for web console only |\n| pnpm/npm | 8+/16+ | Optional, for web console |\n\nFor full feature support including encryption and governance:\n- OpenSSL 1.1.1+ (for encryption features)\n- watchgod or watchdog (optional, for file watching)\n\n资料来源：[examples/README.md:1-20]()\n\n## Installation\n\n### Standard Installation\n\nInstall mind-mem from the repository in development/editable mode:\n\n```bash\npip install -e .\n```\n\nThis installs the package with all dependencies and makes the `mm` CLI available system-wide.\n\n资料来源：[examples/README.md:12-15]()\n\n### Package Structure\n\nAfter installation, the following components become available:\n\n| Component | Path | Purpose |\n|-----------|------|---------|\n| `mm` CLI | Command line | Unified interface for all operations |\n| Python API | `mind_mem.*` | Programmatic access to recall, governance |\n| MCP Server | `mcp_server.py` | Model Context Protocol integration |\n| Hook Installer | `hook_installer.py` | Agent configuration for AI clients |\n\n### Workspace Environment\n\nMind-mem resolves the workspace directory using this precedence:\n\n```mermaid\ngraph LR\n A[\"MIND_MEM_WORKSPACE
Environment Variable\"] --> B{Set?}\n B -->|Yes| C[\"Use env value\"]\n B -->|No| D[\"Current Working
Directory\"]\n C --> E[\"Realpath Resolution\"]\n D --> E\n```\n\nSet the workspace explicitly:\n```bash\nexport MIND_MEM_WORKSPACE=/path/to/your/project\n```\n\n资料来源：[src/mind_mem/mm_cli.py:35-50]()\n\n## Basic Usage\n\n### Running the First Example\n\nThe `basic_usage.py` example demonstrates core functionality:\n\n```bash\npython3 examples/basic_usage.py\n```\n\n资料来源：[examples/README.md:5-8]()\n\n### Python API Walkthrough\n\nThe following demonstrates the fundamental workflow using the Python API:\n\n```python\nfrom mind_mem import recall, initialize_workspace\n\n# Initialize workspace memory directory\nworkspace = \"/path/to/project\"\ninitialize_workspace(workspace)\n\n# Search memory using BM25 recall\nresults = recall(\n workspace,\n \"authentication design decision\",\n limit=10,\n active_only=True\n)\n```\n\n### CLI Commands\n\nThe `mm` CLI provides five primary subcommands:\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `mm recall` | Search memory | `mm recall \"query\"` |\n| `mm context` | Generate token-budgeted snippet | `mm context \"query\"` |\n| `mm inject` | Render snippet for specific agent | `mm inject --agent claude \"query\"` |\n| `mm vault` | List/manage vault blocks | `mm vault scan ` |\n| `mm status` | Workspace summary | `mm status` |\n\n#### Recall Command\n\n```bash\n# Basic search\nmm recall \"authentication flow\"\n\n# With limit and active-only filter\nmm recall \"decision\" --limit 5 --active-only\n```\n\n#### Context Command\n\nGenerates a token-budgeted snippet suitable for including in LLM context windows:\n\n```bash\nmm context \"redis configuration\" --max-tokens 2000\n```\n\n资料来源：[src/mind_mem/mm_cli.py:53-80]()\n\n## Agent Integration\n\nMind-mem supports multiple AI coding assistants through the hook installer system.\n\n### Supported Agents\n\n| Agent | Config Format | Detection Method |\n|-------|---------------|------------------|\n| Claude Code | JSON | Binary path |\n| Cursor | JSON | Binary path |\n| Windsurf | JSON | Binary path |\n| Aider | YAML | Binary path |\n| Copilot | Text block | Always offered |\n| Cody | JSON | Binary + config path |\n| Qodo | Text block | Config path |\n\n资料来源：[src/mind_mem/hook_installer.py:80-150]()\n\n### Installing Agent Hooks\n\nThe hook installer generates configuration files and provides MCP server specifications:\n\n```python\nfrom mind_mem.hook_installer import (\n mcp_server_spec,\n get_agent_spec,\n install_hooks\n)\n\n# Get MCP server invocation for your client\nspec = mcp_server_spec(workspace=\"/path/to/project\")\n# Returns: {command, args, env}\n\n# Install hooks for a specific agent\ninstall_hooks(\"claude\", workspace=\"/path/to/project\")\n```\n\n### MCP Server Path Resolution\n\nThe MCP server is located using this precedence:\n\n```mermaid\ngraph TD\n A[\"MIND_MEM_MCP_SERVER
env var\"] --> B{File exists?}\n B -->|Yes| C[\"Use override path\"]\n B -->|No| D[\"src-layout checkout
../mcp_server.py\"]\n D --> E{File exists?}\n E -->|No| F[\"Packaged install
../mcp_server.py\"]\n F --> G{File exists?}\n G -->|No| H[\"Package root
mcp_server.py\"]\n H --> I[\"Fallback: mcp_server.py\"]\n```\n\n资料来源：[src/mind_mem/hook_installer.py:15-40]()\n\n## Web Console (Optional)\n\nFor visual exploration of memory, the web console provides a force-directed graph view:\n\n```bash\ncd web\npnpm install\npnpm dev\n```\n\nAccess at `http://localhost:3000`.\n\n### Web Console Features\n\nThe console displays:\n- **Graph View**: Force-directed visualization of block relationships\n- **Timeline View**: Chronological event ordering\n- **Facts Panel**: Extracted claims with confidence scores\n\nAll views derive from a single `recall(format=\"bundle\")` call.\n\n资料来源：[web/README.md:1-35]()\n\n### Configuration\n\nSet the API URL if mind-mem isn't on localhost:8080:\n\n```bash\nNEXT_PUBLIC_MIND_MEM_API_URL=http://mind-mem.internal:8080 pnpm dev\n```\n\n资料来源：[web/README.md:14-18]()\n\n## MCP Resources\n\nThe MCP server exposes read-only resources for AI assistants:\n\n| Resource URI | Content |\n|--------------|---------|\n| `mind-mem://decisions` | Active decisions (DECISIONS.md) |\n| `mind-mem://tasks` | All tasks (TASKS.md) |\n| `mind-mem://entities/{type}` | Projects, people, tools, incidents |\n| `mind-mem://signals` | Auto-captured signals |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\nResources are registered after server construction to avoid circular imports.\n\n资料来源：[src/mind_mem/mcp/resources.py:20-45]()\n\n## Next Steps\n\nAfter completing this quick start guide:\n\n1. **Explore Memory Blocks**: Create DECISIONS.md, TASKS.md, and SIGNALS.md files in your workspace\n2. **Configure Your Agent**: Use the hook installer to integrate with your preferred AI assistant\n3. **Try Advanced Recall**: Experiment with `mm context` for token-budgeted retrieval\n4. **Set Up Governance**: Configure the governance workflow for memory evolution\n5. **Run the Web Console**: Visualize your memory graph\n\n### File Structure Convention\n\nMind-mem expects this structure within your workspace:\n\n```\nworkspace/\n├── memory/ # User-authored memory blocks\n│ ├── DECISIONS.md\n│ ├── TASKS.md\n│ └── SIGNALS.md\n├── .mind/ # Kernel configuration files\n└── mind-mem.json # Feature flags and limits\n```\n\n资料来源：[examples/basic_usage.py:1-30]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `mm: command not found` | Reinstall package with `pip install -e .` |\n| Empty recall results | Check workspace path and memory/ directory |\n| MCP connection fails | Verify MIND_MEM_MCP_SERVER path |\n| Import errors | Ensure all dependencies installed with `-e .` |\n\n### Debug Mode\n\nEnable verbose logging by setting:\n```bash\nexport MIND_MEM_LOG_LEVEL=DEBUG\n```\n\n## Summary\n\nThis guide covered:\n- Installation via pip editable mode\n- Workspace initialization and environment variables\n- Basic CLI commands (recall, context, inject, vault, status)\n- Agent hook installation for AI assistant integration\n- Optional web console setup\n- MCP resources for programmatic access\n\nFor deeper integration, explore the governance tools, audit capabilities, and v4 cognitive features in the advanced documentation.\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Overview](#page-overview), [Core Components](#page-components), [Hybrid Search & Retrieval](#page-hybrid-search)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.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/governance.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.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/arch_mind.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.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/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/hook_installer.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n- [web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n \n\n# System Architecture\n\n## Overview\n\nmind-mem is a persistent memory system designed for AI coding agents. It provides structured memory management through markdown-based block files, BM25 full-text search, graph-based relationship tracking, and an MCP (Model Context Protocol) server interface for seamless integration with AI coding clients.\n\nThe system follows a \"memory is never modified except by governance\" invariant, ensuring that all changes to the knowledge base go through a formal propose → approve → apply workflow. This architecture enables multi-agent collaboration while maintaining audit trails and preventing uncontrolled drift.\n\n资料来源：[src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLI[mm CLI]\n MCP[MCP Clients
Claude Code, Codex, Cursor, Windsurf]\n WebApp[Web Console]\n end\n\n subgraph \"Interface Layer\"\n MM_CLI[mm_cli.py
Non-MCP Interface]\n MCPServer[MCP Server
FastMCP]\n RestAPI[REST API v1]\n end\n\n subgraph \"Core Engine\"\n Recall[recall.py
BM25 + Vector Recall]\n Graph[knowledge_graph.py
Entity Relationships]\n BlockParser[block_parser.py
Markdown Processing]\n ApplyEngine[apply_engine.py
Change Application]\n end\n\n subgraph \"Governance Layer\"\n Governance[governance.py
Proposals & Approvals]\n CompiledTruth[compiled_truth.py
Truth Aggregation]\n AuditChain[audit_chain.py
Integrity Verification]\n end\n\n subgraph \"Data Layer\"\n Workspace[(Workspace
memory/ intelligence/ signals/)]\n FTS5[(FTS5 Index)]\n SQLite[(SQLite DB)]\n end\n\n CLI --> MM_CLI\n MCP --> MCPServer\n WebApp --> RestAPI\n\n MM_CLI --> Recall\n MCPServer --> Recall\n MCPServer --> Governance\n MCPServer --> ApplyEngine\n RestAPI --> Recall\n\n Recall --> BlockParser\n Recall --> Graph\n ApplyEngine --> BlockParser\n Governance --> CompiledTruth\n\n BlockParser --> Workspace\n Graph --> SQLite\n Recall --> FTS5\n```\n\n## Directory Structure\n\n```\nmind-mem/\n├── src/mind_mem/\n│ ├── mcp/\n│ │ ├── server.py # Main MCP server entry point\n│ │ ├── resources.py # MCP resource declarations\n│ │ └── tools/\n│ │ ├── governance.py # Propose, approve, rollback tools\n│ │ ├── kernels.py # Mind kernel configuration tools\n│ │ ├── memory_ops.py # Index, health, export tools\n│ │ └── arch_mind.py # Architecture baseline/delta tools\n│ ├── recall.py # BM25 recall implementation\n│ ├── knowledge_graph.py # Entity extraction & relationships\n│ ├── compiled_truth.py # Compiled truth page management\n│ ├── apply_engine.py # Workspace modification engine\n│ ├── block_parser.py # Markdown block parsing\n│ ├── mm_cli.py # CLI interface for non-MCP agents\n│ ├── hook_installer.py # Per-agent hook configuration\n│ ├── model_provenance.py # Model audit & provenance\n│ └── v4/ # v4.0 future capabilities\n├── web/ # Next.js web console\n└── docs/\n```\n\n## Core Components\n\n### Workspace Organization\n\nThe workspace is the root directory containing all memory files and metadata. It is resolved from the `MIND_MEM_WORKSPACE` environment variable or defaults to the current working directory.\n\n资料来源：[src/mind_mem/mm_cli.py:28-32](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n```mermaid\ngraph TD\n W[(Workspace Root)]\n W --> |memory/| M[memory/
DECISIONS.md
TASKS.md
entities/]\n W --> |intelligence/| I[intelligence/
applied/ snapshots/]\n W --> |signals/| S[signals/
SIGNALS.md]\n W --> |.mind/| MK[.mind/
kernel configs/]\n W --> |mind-mem.json| CFG[mind-mem.json
Configuration]\n```\n\n| Directory | Purpose |\n|-----------|---------|\n| `memory/` | Primary knowledge base (decisions, tasks, entities) |\n| `intelligence/` | Applied changes and snapshots for rollback |\n| `signals/` | Staged proposals awaiting governance |\n| `.mind/` | Mind kernel configuration files |\n| `mind-mem.json` | Workspace configuration |\n\n### Block Parser\n\nThe block parser extracts structured information from markdown files, supporting various block types with frontmatter metadata.\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:24-26](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n\n| Block Type | Prefix | Description |\n|------------|--------|-------------|\n| DECISION | `# decision` | Architectural decisions with rationale |\n| TASK | `# task` | Actionable items with status tracking |\n| PROJECT | `# project` | Entity type for project definitions |\n| PERSON | `# person` | Entity type for people |\n| TOOL | `# tool` | Entity type for tool configurations |\n| INCIDENT | `# incident` | Entity type for incidents |\n| SIGNAL | `# signal` | Staged proposals |\n| CLAIM | `# claim` | Factual assertions with confidence |\n\n### Recall System\n\nThe recall system provides BM25-based full-text search across the workspace memory. It ranks results by relevance and supports filtering by block type and temporal constraints.\n\n资料来源：[src/mind_mem/mm_cli.py:36-43](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n```mermaid\ngraph LR\n Q[Query] --> Recall\n Recall --> |BM25| FTS[FTS5 Index]\n Recall --> |parse| BP[block_parser.py]\n BP --> |active blocks| Filter\n FTS --> Filter\n Filter --> R[Ranked Results
JSON bundle format]\n```\n\n## MCP Server Architecture\n\nThe MCP server exposes tools and resources through the Model Context Protocol, enabling AI coding clients to interact with the memory system.\n\n资料来源：[src/mind_mem/mcp/resources.py:1-29](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n\n### MCP Resources\n\nResources provide read-only access to workspace data:\n\n| Resource URI | Description |\n|--------------|-------------|\n| `mind-mem://decisions` | Active decisions from DECISIONS.md |\n| `mind-mem://tasks` | All tasks from TASKS.md |\n| `mind-mem://entities/{type}` | Projects, people, tools, incidents |\n| `mind-mem://signals` | Auto-captured signals |\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://recall/{query}` | BM25 recall search |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\n### MCP Tool Categories\n\n#### Governance Tools\n\nGovernance tools manage the propose → approve → apply lifecycle:\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-28](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/governance.py)\n\n| Tool | Purpose |\n|------|---------|\n| `propose_update` | Stage a new decision or task as a SIGNAL |\n| `approve_apply` | Apply a staged proposal (dry-run by default) |\n| `rollback_proposal` | Restore workspace from pre-apply snapshot |\n| `scan` | Integrity scan (contradictions, drift, pending) |\n| `list_contradictions` | Enriched contradiction listing |\n| `memory_evolution` | A-MEM metadata for a block |\n\n#### Memory Operations Tools\n\nMemory operations provide lifecycle management:\n\n资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-30](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/memory_ops.py)\n\n| Tool | Purpose |\n|------|---------|\n| `index_stats` | FTS5 index state inspection |\n| `reindex` | Rebuild the full-text search index |\n| `delete_memory_item` | Atomic block removal with recovery log |\n| `export_memory` | JSONL dump with configurable metadata |\n| `get_block` | Block lookup by ID |\n| `memory_health` | Health dashboard |\n| `compact` | Workspace compaction |\n| `stale_blocks` | Staleness-flag management |\n\n#### Kernel Tools\n\nKernel tools provide access to mind kernel configuration:\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:1-27](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/kernels.py)\n\n| Tool | Purpose |\n|------|---------|\n| `list_mind_kernels` | List available .mind kernel files |\n| `get_mind_kernel` | Read a specific kernel configuration |\n| `compiled_truth_load` | Load truth page for an entity |\n| `compiled_truth_add_evidence` | Add evidence to a truth page |\n| `compiled_truth_contradictions` | Check for contradictions |\n\n#### Architecture Mind Tools\n\nArch-mind tools integrate architecture baseline management:\n\n资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-40](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/arch_mind.py)\n\n| Tool | Purpose |\n|------|---------|\n| `arch_baseline` | Initialize arch-mind store with baseline |\n| `arch_delta` | Compute (current scan) - (baseline scores) |\n| `arch_history` | List events in arch-mind store |\n| `arch_check_rules` | Apply rules.mind to a fresh scan |\n| `arch_session_start` | Open session evidence node |\n| `arch_session_end` | Close session, write delta evidence |\n| `arch_metric_explain` | Per-metric breakdown for a fixture |\n\n## Governance Workflow\n\nThe governance system ensures all memory modifications follow a controlled process:\n\n```mermaid\ngraph LR\n A[Agent proposes
propose_update] --> B{Signal created
in signals/}\n B --> C{Human review}\n C -->|approve| D[dry-run]\n C -->|reject| E[Signal discarded]\n D -->|confirm| F[apply_engine.py]\n D -->|cancel| E\n F --> G[Snapshot created
for rollback]\n G --> H[Changes applied
to workspace]\n H --> I[Compiled truth
recompiled]\n```\n\n### Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity into canonical understanding pages:\n\n资料来源：[src/mind_mem/compiled_truth.py:1-50](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n```\n# entity_id — Compiled Truth\n\n## Current Understanding\n- Bullet point summary from evidence\n\n## Evidence Trail\n### timestamp [CONF] (source: ...)\nObservation text\n```\n\n| Field | Description |\n|-------|-------------|\n| `entity_id` | Unique entity identifier |\n| `entity_type` | Type (project, person, tool, incident) |\n| `compiled_section` | Bullet-point summary of current understanding |\n| `evidence_entries` | List of observations with confidence and timestamp |\n| `version` | Incremented on each recompilation |\n\n## Apply Engine\n\nThe apply engine handles workspace modifications through the configured BlockStore:\n\n资料来源：[src/mind_mem/apply_engine.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n```mermaid\ngraph TD\n AE[apply_engine.py] --> BS{BlockStore
mind-mem.json}\n BS -->|markdown| MS[MarkdownBlockStore]\n BS -->|postgres| PS[PostgresBlockStore]\n BS -->|encrypted| ES[EncryptedWrapper]\n MS --> WD[(Workspace
Files)]\n PS --> PG[(PostgreSQL)]\n ES --> PS\n \n AE --> |create_snapshot| Snap\n AE --> |restore_snapshot| Rest\n AE --> |snapshot_diff| Diff\n```\n\n| Backend | Configuration | Use Case |\n|---------|---------------|----------|\n| MarkdownBlockStore | Default | Standard file-based storage |\n| PostgresBlockStore | `block_store.backend: postgres` | Scalable multi-tenant |\n| EncryptedWrapper | `passphrase` set | Sensitive data protection |\n\n## CLI Interface\n\nThe `mm` CLI provides a unified interface for non-MCP agents:\n\n资料来源：[src/mind_mem/mm_cli.py:1-60](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n```bash\nmm recall \"\" # Search memory\nmm context \"\" # Generate token-budgeted snippet\nmm inject --agent \"\" # Render snippet for specific agent\nmm vault scan # List parsed vault blocks (JSON)\nmm vault write --type --body \nmm status # Workspace summary\n```\n\n## Web Console\n\nThe web console provides a visual interface for memory exploration:\n\n资料来源：[web/README.md](https://github.com/star-ga/mind-mem/blob/main/web/README.md)\n\n```mermaid\ngraph TB\n Web[Next.js Console] --> API[lib/api.ts]\n API --> Recall[/v1/recall]\n API --> Health[/v1/health]\n \n Recall --> |bundle| GV[GraphView
d3-force]\n Recall --> |bundle| TV[TimelineView
Chronological]\n Recall --> |bundle| FL[FactList
Extracted claims]\n```\n\n| Component | Purpose |\n|-----------|---------|\n| `GraphView.tsx` | Force-directed graph of blocks and cross-references |\n| `TimelineView.tsx` | Chronological view of dated events |\n| `FactList.tsx` | Extracted claims with confidence levels |\n\n## Agent Integration\n\nThe hook installer enables per-agent memory integration:\n\n资料来源：[src/mind_mem/hook_installer.py:1-100](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hook_installer.py)\n\n| Agent | Config Path | Format |\n|-------|-------------|--------|\n| Claude Code | `~/.claude/projects/*/.claude.md` | Markdown block |\n| Copilot | `.github/copilot-instructions.md` | Markdown block |\n| Cody | `.cody/config.json` | JSON generic |\n| Cursor | `.cursor/rules/*.mdc` | Markdown with frontmatter |\n| Windsurf | `.codeium/windsurf/mcp_config.json` | JSON windsurf |\n| Aider | `.aider.conf.yml` | YAML block |\n\n## v4.0 Future Architecture\n\nThe v4.0 package provides side-by-side scaffolding, gated by feature flags:\n\n资料来源：[src/mind_mem/v4/__init__.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/v4/__init__.py)\n\n| Group | Features |\n|-------|----------|\n| A. Cognition | Tier-aware blocks, Cognitive Mind Kernel, surprise-weighted retrieval |\n| B. Knowledge Graph | Entity/concept extraction, long-context recall, LLM fusion, streaming |\n| C. Governance UX | Idle background ingest, AI lint with auto-fix, contradiction state machine |\n\n## Key Design Principles\n\n| Principle | Implementation |\n|-----------|-----------------|\n| Memory immutability | All changes go through governance workflow |\n| Auditability | Every modification has a snapshot and proposal trail |\n| Multi-agent safety | File locking and governance prevents conflicts |\n| Separation of concerns | Distinct layers for interface, core, governance, and data |\n| Extensibility | Plugin architecture via BlockStore and MCP tools |\n\n---\n\n\n\n## Core Components\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Hybrid Search & Retrieval](#page-hybrid-search), [Governance & Safety](#page-governance)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n- [src/mind_mem/conflict_resolver.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/conflict_resolver.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/tiered_memory.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/tiered_memory.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 \n\n# Core Components\n\nMIND-Mem's architecture centers on a set of interconnected components that manage workspace memory through a structured lifecycle: recall, storage, application, conflict resolution, drift detection, and tiered memory management. These components work together to provide a robust, multi-agent compatible memory system that maintains data integrity and supports autonomous memory consolidation.\n\n## Memory Recall System\n\nThe recall system is the primary retrieval engine in MIND-Mem, providing BM25-based full-text search over the workspace memory blocks. It supports flexible querying with result limiting and active-only filtering.\n\n### Recall Architecture\n\n```mermaid\ngraph TD\n A[Query Input] --> B[recall function]\n B --> C[BM25 FTS5 Index]\n C --> D[Ranked Results]\n D --> E[Optional: pack_to_budget]\n E --> F[Token-Budgeted Snippet]\n```\n\n### Recall Function\n\nThe `recall()` function serves as the main entry point for memory retrieval:\n\n```python\ndef recall(workspace, query, limit=10, active_only=True)\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `workspace` | `str` | required | Root workspace directory path |\n| `query` | `str` | required | Search query string |\n| `limit` | `int` | `10` | Maximum number of results to return |\n| `active_only` | `bool` | `True` | Filter to only active (non-superseded) blocks |\n\n资料来源：[src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n\n### Context Generation\n\nThe `pack_to_budget()` function from `cognitive_forget` module works with recall results to generate token-budgeted snippets for efficient context injection:\n\n```python\nfrom mind_mem.cognitive_forget import pack_to_budget\nresults = recall(workspace, query)\ncontext = pack_to_budget(results, token_budget)\n```\n\n资料来源：[src/mind_mem/recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall.py)\n\n## Block Storage Layer\n\nThe block storage layer provides an abstraction over different storage backends, enabling MIND-Mem to work with Markdown files on disk or optional PostgreSQL deployments.\n\n### Storage Backend Selection\n\n```mermaid\ngraph TD\n A[get_block_store workspace] --> B{Try Import storage module}\n B -->|Success| C[Return configured backend]\n B -->|Exception| D[Fallback to MarkdownBlockStore]\n C --> E[Markdown / Postgres / Encrypted]\n```\n\n### BlockStore Implementations\n\n| Backend | Description | Configuration Key |\n|---------|-------------|-------------------|\n| `MarkdownBlockStore` | Default, file-based storage | N/A (default) |\n| `PostgresBlockStore` | Optional SQL backend | `block_store.backend: \"postgres\"` |\n| `EncryptedBlockStore` | Passphrase-protected wrapper | `block_store.backend: \"encrypted\"` |\n\n资料来源：[src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n### Block Deletion and Recovery\n\nThe storage layer maintains an append-only deletion log for recovery:\n\n```python\ndef _log_block_deletion(workspace, block_id, content):\n \"\"\"Append deletion receipt to memory/deleted_blocks.jsonl.\"\"\"\n log_path = os.path.join(workspace, \"memory\", \"deleted_blocks.jsonl\")\n entry = {\n \"block_id\": block_id,\n \"deleted_at\": datetime.now(timezone.utc).isoformat(),\n \"content\": content,\n }\n```\n\nBlock locations are determined by scanning text content for block ID headers `[block_id]`, with boundaries at next headers or `---` separators.\n\n资料来源：[src/mind_mem/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.py)\n\n## Apply Engine\n\nThe apply engine handles workspace modifications through a staged proposal and apply workflow, supporting snapshots, rollback, and diff operations.\n\n### Application Workflow\n\n```mermaid\ngraph LR\n A[propose_update] --> B[Signal Written]\n B --> C[approve_apply]\n C --> D{Snapshot Created}\n D -->|Success| E[Changes Applied]\n D -->|Failure| F[Rollback Available]\n```\n\n### Snapshot Operations\n\n| Operation | Function | Description |\n|-----------|----------|-------------|\n| Create | `create_snapshot(ws, ts, files_touched)` | Creates pre-apply snapshot for rollback |\n| Restore | `restore_snapshot(ws, snap_dir)` | Restores workspace from snapshot |\n| Diff | `snapshot_diff(ws, snap_dir)` | Returns list of files that differ |\n\nThe apply engine routes through the configured BlockStore, allowing Postgres-backed deployments to snapshot via SQL instead of on-disk copies.\n\n资料来源：[src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n### Block Store Routing\n\n```python\ndef _store_for(ws):\n \"\"\"Route to the configured BlockStore implementation.\"\"\"\n try:\n from .storage import get_block_store\n return get_block_store(ws)\n except Exception:\n return MarkdownBlockStore(ws) # Fallback resilience\n```\n\nThis fallback mechanism keeps the apply engine resilient on first-run or misconfigured workspaces.\n\n资料来源：[src/mind_mem/apply_engine.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/apply_engine.py)\n\n## Conflict Resolution\n\nThe conflict resolver manages situations where multiple agents or processes attempt to modify the same memory blocks, ensuring data consistency and preventing silent overwrites.\n\n### Resolution Strategy\n\nThe conflict resolver implements a last-write-wins (LWW) strategy with evidence preservation, allowing the system to track and potentially rollback conflicting changes.\n\n### Key Operations\n\n| Method | Purpose |\n|--------|---------|\n| `detect_conflicts()` | Identify overlapping block modifications |\n| `resolve_conflict()` | Apply resolution strategy and merge evidence |\n| `get_conflict_history()` | Retrieve conflict metadata for audit |\n\n资料来源：[src/mind_mem/conflict_resolver.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/conflict_resolver.py)\n\n## Drift Detection\n\nThe drift detector monitors memory state changes over time, identifying when factual understanding diverges from previously recorded information.\n\n### Drift Detection Pipeline\n\n```mermaid\ngraph TD\n A[Memory Blocks] --> B[Baseline Snapshot]\n B --> C[Current State]\n C --> D[Comparison Engine]\n D --> E{Drift Detected?}\n E -->|Yes| F[Flag for Review]\n E -->|No| G[Continue Monitoring]\n```\n\n### Detection Criteria\n\n| Drift Type | Detection Method | Severity |\n|------------|------------------|----------|\n| Semantic Drift | Factual claim contradiction | High |\n| Temporal Drift | Outdated timestamps | Medium |\n| Structural Drift | Schema/format changes | Low |\n\n资料来源：[src/mind_mem/drift_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/drift_detector.py)\n\n## Tiered Memory\n\nThe tiered memory system organizes memory blocks across multiple storage tiers based on access patterns, importance, and staleness, enabling efficient resource utilization.\n\n### Memory Tier Structure\n\n```mermaid\ngraph BT\n A[Hot Tier] --> B[Warm Tier]\n B --> C[Cold Tier]\n A --> D[Active Memory]\n B --> E[Archived Memory]\n C --> F[Long-term Storage]\n```\n\n### Tier Classification\n\n| Tier | Criteria | Eviction Policy |\n|------|----------|------------------|\n| Hot | Recently accessed, high importance | LRU with importance boost |\n| Warm | Moderate access frequency | Threshold-based archiving |\n| Cold | Stale, low importance | Compression or deletion after grace period |\n\nThe consolidation system uses `ConsolidationConfig` to control the forgetting cycle:\n\n```python\ncfg = ConsolidationConfig(\n importance_threshold=0.25,\n stale_days=14,\n archive_after_days=60,\n grace_days=30,\n)\n```\n\n资料来源：[src/mind_mem/tiered_memory.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/tiered_memory.py)\n\n## MCP Core Tools\n\nThe MCP (Model Context Protocol) layer exposes core functionality as tools for agent integration. The core tools module provides the primary interface for memory operations.\n\n### Available Core Tools\n\n| Tool | Function | Description |\n|------|----------|-------------|\n| `list_mind_kernels` | List kernel configs | Enumerate `.mind` kernel configuration files |\n| `get_mind_kernel` | Get kernel config | Retrieve specific kernel configuration |\n| `compiled_truth_load` | Load truth page | Load compiled truth for an entity |\n| `compiled_truth_add_evidence` | Add evidence | Append evidence to a truth page |\n| `compiled_truth_contradictions` | List contradictions | Show detected entity contradictions |\n\n### Kernel Configuration Loading\n\n```python\nfrom mind_mem.mind_ffi import get_mind_dir, load_all_kernel_configs, load_kernel_config\n\nmind_dir = get_mind_dir(workspace)\nall_cfgs = load_all_kernel_configs(mind_dir)\n```\n\nThe `.mind` kernel files tune recall, reranking, RM3 expansion, and related pipeline knobs.\n\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\n## Quality Gate\n\nThe quality gate provides a deterministic pre-storage filter for candidate blocks, ensuring memory integrity through content validation.\n\n### Quality Rules\n\n| Rule | Condition | Default Action |\n|------|-----------|----------------|\n| `empty` | Whitespace-only content | Log warning |\n| `too_short` | Fewer than 32 non-whitespace chars | Log warning |\n| `oversize` | Exceeds 64 KiB | Log warning |\n| `malformed_utf8` | Contains lone surrogates | Log warning |\n| `stopwords_only` | No semantic content | Log warning |\n| `near_duplicate` | Similarity ≥ 0.97 to recent block | Log warning |\n| `injection_marker` | Matches prompt-injection pattern | Log warning |\n| `ok` | No rule fired | Accept |\n\nQuality gate modes:\n\n| Mode | Behavior |\n|------|----------|\n| `advisory` (default) | Log warnings, always accept |\n| `strict` | Reject blocks that trigger any rule |\n\nConfiguration sources (in priority order): `strict=True` keyword argument → `QualityGateConfig(mode=\"strict\")` → `mind-mem.json` setting `quality_gate_mode = \"strict\"`.\n\n资料来源：[src/mind_mem/quality_gate.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/quality_gate.py)\n\n## Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity and recompiles canonical understanding from source memory blocks.\n\n### Truth Page Format\n\n```markdown\n---\nentity_id: \nentity_type: \nlast_compiled: \nversion: \n---\n\n# — Compiled Truth\n\n## Current Understanding\n\n\n## Evidence Trail\n### [CONF] (source: )\n\n\n### [SUPERSEDED] (source: )\n\n```\n\n### Evidence Aggregation\n\nThe system reads markdown files from `{workspace}/memory/`, counts sentence-level occurrences, and promotes sentences appearing at least `min_mentions` times as candidates for compiled truth pages.\n\n资料来源：[src/mind_mem/compiled_truth.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/compiled_truth.py)\n\n## Component Interactions\n\nThe following diagram illustrates how core components interact during a typical memory operation:\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP_Tools\n participant Apply_Engine\n participant Quality_Gate\n participant Block_Store\n participant Recall\n participant Drift_Detector\n\n Agent->>MCP_Tools: propose_update()\n MCP_Tools->>Quality_Gate: validate(block)\n Quality_Gate-->>Apply_Engine: verdict\n Apply_Engine->>Apply_Engine: create_snapshot()\n Apply_Engine->>Block_Store: write(block)\n Block_Store-->>Apply_Engine: success\n Agent->>Recall: recall(query)\n Recall-->>Agent: results\n Recall->>Drift_Detector: check_drift(results)\n Drift_Detector-->>Agent: drift_alerts\n```\n\n## CLI Integration\n\nThe `mm` CLI provides command-line access to core components for non-MCP agents:\n\n| Command | Component | Description |\n|---------|-----------|-------------|\n| `mm recall \"\"` | Recall | Search memory |\n| `mm context \"\"` | Recall + cognitive_forget | Generate token-budgeted snippet |\n| `mm inject --agent \"\"` | Recall | Render snippet for specific agent |\n| `mm status` | All | Workspace summary |\n\n资料来源：[src/mind_mem/mm_cli.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py)\n\n---\n\n\n\n## Hybrid Search & Retrieval\n\n### 相关页面\n\n相关主题：[Knowledge Graph & Entity Management](#page-knowledge-graph), [Core Components](#page-components), [Block Format & Data Model](#page-data-model)\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/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)\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/graph_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_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/cross_encoder_reranker.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/cross_encoder_reranker.py)\n- [src/mind_mem/intent_router.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/intent_router.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/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n- [docs/scoring.md](https://github.com/star-ga/mind-mem/blob/main/docs/scoring.md)\n \n\n# Hybrid Search & Retrieval\n\n## Overview\n\nThe Hybrid Search & Retrieval system in mind-mem provides multi-modal memory retrieval capabilities that combine keyword-based search (BM25), dense vector search, graph-based traversal, and intelligent reranking to deliver contextually relevant results for AI agents and CLI operations.\n\nThe system operates under the principle that no single retrieval method is optimal for all query types. By combining multiple retrieval strategies with Reciprocal Rank Fusion (RRF), mind-mem achieves robust and accurate recall across diverse query patterns.\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Intent Router]\n B --> C{Query Type}\n C -->|Keyword| D[BM25 / FTS5]\n C -->|Semantic| E[Vector Recall]\n C -->|Graph| F[Graph Recall]\n D --> G[Query Expansion]\n E --> G\n F --> G\n G --> H[Hybrid Recall]\n H --> I[Cross-Encoder Reranker]\n I --> J[Final Results]\n \n K[Graph DB] --> F\n L[FTS5 Index] --> D\n M[Vector Store] --> E\n```\n\n## Core Components\n\n### Intent Router\n\nThe Intent Router (`intent_router.py`) classifies incoming queries to determine the optimal retrieval strategy.\n\n**Responsibilities:**\n- Analyze query semantics to determine intent\n- Route queries to appropriate retrieval backends\n- Support mixed-mode retrieval when query intent is ambiguous\n\n**Routing Decisions:**\n\n| Query Pattern | Routing | Rationale |\n|---------------|---------|-----------|\n| Exact terms / keywords | BM25 primary | Precision-focused |\n| Conceptual / semantic | Vector primary | Semantic similarity |\n| Entity relationships | Graph primary | Traversal-based |\n| Complex / multi-aspect | Hybrid RRF | Combined scoring |\n\n资料来源：[src/mind_mem/intent_router.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/intent_router.py)\n\n### BM25 Keyword Search\n\nBM25 (Best Matching 25) provides traditional keyword-based retrieval through SQLite FTS5. This approach excels at exact term matching and is the default retrieval method for the CLI `recall` command.\n\n**Key Features:**\n- Term frequency/inverse document frequency scoring\n- Configurable BM25 parameters via `.mind` kernel files\n- Integration with the `recall` function for workspace queries\n\n**Usage in CLI:**\n```python\ndef _cmd_recall(args: argparse.Namespace) -> int:\n from mind_mem.recall import recall\n results = recall(_workspace(), args.query, limit=args.limit, active_only=args.active_only)\n print(json.dumps(results, indent=2, default=str))\n return 0\n```\n\n资料来源：[src/mind_mem/mm_cli.py:42-47](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mm_cli.py#L42-L47)\n\n### Vector Recall\n\nDense vector retrieval (`recall_vector.py`) provides semantic similarity search using embeddings. This method identifies conceptually related content even when exact terms differ.\n\n**Capabilities:**\n- Dense embedding-based similarity scoring\n- Configurable embedding model selection\n- Fallback to BM25 when vector search unavailable\n\n**Integration Points:**\n- Called by hybrid recall orchestrator\n- Results fed into cross-encoder reranking pipeline\n- Supports workspace-specific vector stores\n\n资料来源：[src/mind_mem/recall_vector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/recall_vector.py)\n\n### Graph Recall\n\nGraph-based recall (`graph_recall.py`) traverses the co-retrieval graph to discover related memory blocks based on entity relationships and cross-reference patterns.\n\n**Algorithm Overview:**\n```mermaid\ngraph LR\n A[Query Block] --> B[Find Connected Nodes]\n B --> C[Weighted Edge Traversal]\n C --> D[Collect Related Blocks]\n D --> E[Score by Path Length]\n \n F[Co-Retrieval DB] --> B\n```\n\n**Features:**\n- Kahn's algorithm for topological ordering\n- Cycle breaking on lowest-weight edges\n- Chronological backbone combined with co-retrieval edges\n\nThe graph recall is particularly valuable for \"walkthrough\" scenarios where temporal dependencies matter:\n\n> For teach me / explain queries, agents and humans both want a learning order — foundations first, then derived context, then current state.\n\n资料来源：[src/mind_mem/graph_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/graph_recall.py)\n\n### Query Expansion\n\nQuery expansion (`query_expansion.py`) enhances the original query with related terms, synonyms, and context to improve recall coverage.\n\n**Expansion Strategies:**\n- Synonym injection based on domain knowledge\n- Entity-aware term expansion\n- Contextual query reformulation\n\n资料来源：[src/mind_mem/query_expansion.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/query_expansion.py)\n\n## Hybrid Recall Orchestration\n\n### RRF (Reciprocal Rank Fusion)\n\nThe hybrid recall module (`hybrid_recall.py`) combines results from multiple retrieval methods using Reciprocal Rank Fusion. RRF provides a simple yet effective way to merge ranked lists without requiring score normalization.\n\n**RRF Formula:**\n```\nscore(d) = Σ 1 / (k + rank_i(d))\n```\nWhere `k` is typically 60, and `rank_i(d)` is the rank of document `d` in retrieval list `i`.\n\n**Benefits:**\n- No need for score calibration between methods\n- Robust to individual method failures\n- Emphasizes documents ranked well across multiple sources\n\n资料来源：[src/mind_mem/hybrid_recall.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/hybrid_recall.py)\n\n### Integration with MCP Resources\n\nThe MCP (Model Context Protocol) layer exposes recall functionality as resources:\n\n```python\n\"\"\"mind-mem://recall/{query} — BM25 recall search\"\"\"\n```\n\nThis enables MCP-aware AI clients to request memory context directly through the standardized resource interface.\n\n资料来源：[src/mind_mem/mcp/resources.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/resources.py)\n\n## Reranking Pipeline\n\n### Cross-Encoder Reranker\n\nThe cross-encoder reranker (`cross_encoder_reranker.py`) applies a trained model to re-score retrieved candidates against the original query, significantly improving ranking quality.\n\n**Pipeline Position:**\n```mermaid\ngraph LR\n A[Hybrid Recall] --> B[Cross-Encoder Rerank]\n B --> C[Final Ranking]\n```\n\n**Processing Flow:**\n1. Receive top-N candidates from hybrid recall (e.g., top 100)\n2. Score each candidate against the query using cross-encoder\n3. Re-rank by cross-encoder scores\n4. Return top-K final results (typically K < N)\n\n**Cross-Encoder Advantages:**\n- Captures query-document interaction features\n- Better handles complex semantic relationships\n- Can incorporate attention mechanisms for relevance\n\n资料来源：[src/mind_mem/cross_encoder_reranker.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/cross_encoder_reranker.py)\n\n## Scoring System\n\n### Score Composition\n\nThe final relevance score combines multiple signals:\n\n| Component | Weight | Source |\n|-----------|--------|--------|\n| BM25 Score | Variable | FTS5 index |\n| Vector Similarity | Variable | Embedding model |\n| Graph Proximity | Variable | Co-retrieval graph |\n| RRF Score | Fixed formula | Rank fusion |\n| Cross-Encoder | High | Trained model |\n\n### Scoring Configuration\n\nMind-mem uses `.mind` kernel files to configure retrieval parameters. The `bm25.mind` file controls BM25-specific settings while `rrf.mind` manages fusion parameters.\n\n资料来源：[docs/scoring.md](https://github.com/star-ga/mind-mem/blob/main/docs/scoring.md)\n\n## MCP Tools Integration\n\n### Memory Operations Tools\n\nThe MCP layer provides programmatic access to recall functionality:\n\n| Tool | Purpose |\n|------|---------|\n| `index_stats` | FTS5 index state inspection |\n| `reindex` | Rebuild search indices |\n| `get_block` | Direct block retrieval |\n| `memory_health` | Retrieval health dashboard |\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\n## CLI Usage\n\n### Recall Command\n\n```bash\nmm recall \"query\" # search memory\nmm recall \"query\" --limit 10 # limit results\nmm recall \"query\" --active-only # exclude archived blocks\n```\n\n### Context Command\n\nThe `context` command generates token-budgeted snippets using cognitive forgetting logic to pack relevant content within token constraints.\n\n```bash\nmm context \"query\" # generate budgeted context\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\n## Configuration\n\n### Kernel Files\n\nRetrieval behavior is tuned through `.mind` kernel configuration files:\n\n| File | Purpose |\n|------|---------|\n| `bm25.mind` | BM25 parameters (k1, b) |\n| `rrf.mind` | RRF k-value and weights |\n| `recall.mind` | General recall settings |\n\nThe kernel loader supports hot-reloading for runtime tuning:\n\n```python\nfrom mind_mem.mind_ffi import load_kernel_config, get_mind_dir\n\nmind_dir = get_mind_dir(workspace)\ncfg = load_kernel_config(mind_dir, \"rrf\")\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\n## Performance Considerations\n\n### Index Maintenance\n\n- FTS5 indices support incremental updates\n- Periodic reindexing recommended for optimal performance\n- Vector indices may require periodic re-embedding for freshness\n\n### Latency Optimization\n\n- Hybrid recall executes multiple retrieval paths in parallel\n- Cross-encoder reranking applied only to top-N candidates\n- Caching of frequent query patterns recommended\n\n## Related Documentation\n\n- [Scoring System](docs/scoring.md) — Detailed scoring algorithms\n- [Walkthrough Module](src/mind_mem/walkthrough.py) — Dependency-ordered retrieval for teaching\n- [Quality Gate](src/mind_mem/quality_gate.py) — Block quality filtering before storage\n\n---\n\n\n\n## Knowledge Graph & Entity Management\n\n### 相关页面\n\n相关主题：[Hybrid Search & Retrieval](#page-hybrid-search), [Governance & Safety](#page-governance), [Block Format & Data Model](#page-data-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mind_mem/knowledge_graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/knowledge_graph.py)\n- [src/mind_mem/entity_ingest.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/entity_ingest.py)\n- [src/mind_mem/causal_graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/causal_graph.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/contradiction_detector.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/contradiction_detector.py)\n- [src/mind_mem/mcp/tools/graph.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/mcp/tools/graph.py)\n \n\n# Knowledge Graph & Entity Management\n\n## Overview\n\nThe Knowledge Graph & Entity Management system in mind-mem provides a structured mechanism for capturing, organizing, and querying relationships between entities in the workspace. It extends the basic block storage model with typed edges, entity ontologies, compiled truth pages, and contradiction detection capabilities.\n\nThis system serves multiple purposes:\n\n- **Relationship Tracking**: Records typed relationships (subject-predicate-object triples) between blocks and entities\n- **Entity Classification**: Defines and validates entity types through an ontology registry\n- **Truth Compilation**: Aggregates evidence from multiple sources into canonical entity understanding\n- **Contradiction Detection**: Identifies conflicting claims across evidence entries\n- **Causal Analysis**: Tracks dependency relationships between blocks for impact analysis\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:1-17]()\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Data Layer\"\n KG[Knowledge Graph
retrieval_graph.db]\n CG[Causal Graph
causal_graph.db]\n TP[Truth Pages
truth/ directory]\n ONT[Ontology
Registry]\n end\n\n subgraph \"Ingestion Layer\"\n EI[Entity Ingest]\n BD[Block Store]\n CD[Contradiction
Detector]\n end\n\n subgraph \"MCP Tools\"\n GQ[graph_query]\n GTA[graph_add_edge]\n TGG[traverse_graph]\n CTL[compiled_truth_load]\n CTA[compiled_truth_add_evidence]\n CTC[compiled_truth_contradictions]\n end\n\n EI --> ONT\n BD --> KG\n BD --> CG\n KG --> GQ\n CG --> TGG\n TP --> CTL\n TP --> CTA\n CD --> CTC\n\n style KG fill:#e1f5fe\n style CG fill:#e8f5e8\n style TP fill:#fff3e0\n style ONT fill:#fce4ec\n```\n\n## Knowledge Graph\n\n### Core Data Model\n\nThe knowledge graph stores typed edges between entities using SQLite. Each edge contains:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `subject` | str | Source entity identifier |\n| `predicate` | str | Relationship type |\n| `object` | str | Target entity identifier |\n| `confidence` | float | Edge confidence (0.0-1.0) |\n| `source_block_id` | str | Block that created this edge |\n| `created_at` | str | ISO timestamp of creation |\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:20-45]()\n\n### Predicate Types\n\nThe system supports predefined predicate types through the `Predicate` enum:\n\n```python\nclass Predicate(str, Enum):\n \"\"\"Predefined relationship types for the knowledge graph.\"\"\"\n DEPENDS_ON = \"depends_on\"\n RELATED_TO = \"related_to\"\n PART_OF = \"part_of\"\n IMPLEMENTS = \"implements\"\n CONTRADICTS = \"contradicts\"\n REFERENCES = \"references\"\n CAUSED_BY = \"caused_by\"\n```\n\n资料来源：[src/mind_mem/knowledge_graph.py]() (inferred from usage patterns)\n\n### MCP Tools for Knowledge Graph\n\n#### `graph_add_edge`\n\nRecords a typed relationship in the knowledge graph.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `subject` | str | Yes | - | Source entity identifier |\n| `predicate` | str | Yes | - | Relationship type |\n| `object` | str | Yes | - | Target entity identifier |\n| `source_block_id` | str | Yes | - | Source block ID |\n| `confidence` | float | No | 1.0 | Edge confidence (0.0-1.0) |\n\n**Returns:**\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"subject\": \"PROJECT-A\",\n \"predicate\": \"depends_on\",\n \"object\": \"PROJECT-B\",\n \"confidence\": 0.95,\n \"edge_id\": 42\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:30-80]()\n\n#### `graph_query`\n\nPerforms N-hop traversal queries on the knowledge graph.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `subject` | str | No | - | Starting node |\n| `predicate` | str | No | - | Filter by predicate type |\n| `object` | str | No | - | Target node |\n| `hops` | int | No | 1 | Number of hops to traverse |\n| `direction` | str | No | \"out\" | \"out\", \"in\", or \"both\" |\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:80-150]()\n\n#### `graph_stats`\n\nReturns aggregate statistics about the knowledge graph.\n\n**Returns:**\n```json\n{\n \"total_edges\": 156,\n \"predicates\": {\n \"depends_on\": 45,\n \"related_to\": 67,\n \"references\": 44\n },\n \"unique_subjects\": 89,\n \"unique_objects\": 102\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/graph.py:150-200]()\n\n## Entity Management\n\n### Ontology Registry\n\nThe ontology system defines entity types with their required and optional properties:\n\n```mermaid\nclassDiagram\n class EntityType {\n +str name\n +str parent\n +tuple required\n +tuple optional\n +dict property_types\n +validate(data) bool\n }\n\n class Ontology {\n +str name\n +str version\n +dict~str, EntityType~ entity_types\n +get_type(name) EntityType\n +register(entity_type) None\n }\n\n class OntologyRegistry {\n +list ontologies\n +get_default() Ontology\n +register(ontology) None\n }\n\n OntologyRegistry \"1\" --> \"*\" Ontology\n Ontology \"1\" --> \"*\" EntityType\n EntityType --> EntityType : inherits from\n```\n\n资料来源：[src/mind_mem/ontology.py]()\n\n### Built-in Entity Types\n\n| Entity Type | Parent | Required Fields | Optional Fields |\n|-------------|--------|-----------------|-----------------|\n| `ENTITY` | - | (name,) | (description, tags) |\n| `PROJECT` | ENTITY | (name, status) | (owner, priority, deadline) |\n| `PERSON` | ENTITY | (name,) | (role, email, team) |\n| `TOOL` | ENTITY | (name,) | (version, language, category) |\n| `INCIDENT` | ENTITY | (title,) | (severity, status, assignee) |\n| `TASK` | ENTITY | (title,) | (assignee, priority, due) |\n\n资料来源：[src/mind_mem/ontology.py]()\n\n### Entity Ingestion\n\nEntities are ingested through the `entity_ingest` module which:\n\n1. Parses incoming entity data\n2. Validates against the active ontology\n3. Updates or creates entity records\n4. Links entities to their source blocks\n\n资料来源：[src/mind_mem/entity_ingest.py]()\n\n## Compiled Truth Pages\n\nCompiled Truth Pages aggregate evidence from multiple sources into canonical understanding for each entity. This follows a \"memory is never modified except by governance\" principle.\n\n### Data Model\n\n```mermaid\nclassDiagram\n class CompiledTruthPage {\n +str entity_id\n +str entity_type\n +str compiled_section\n +list evidence_entries\n +str last_compiled\n +int version\n }\n\n class EvidenceEntry {\n +str timestamp\n +str source\n +str observation\n +str confidence\n +bool superseded\n }\n\n CompiledTruthPage \"1\" --> \"*\" EvidenceEntry\n```\n\n资料来源：[src/mind_mem/compiled_truth.py]()\n\n### Evidence Entry Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `timestamp` | str | ISO 8601 timestamp of evidence |\n| `source` | str | Source block ID or filename |\n| `observation` | str | The factual claim |\n| `confidence` | str | \"high\", \"medium\", or \"low\" |\n| `superseded` | bool | Whether this entry is outdated |\n\n资料来源：[src/mind_mem/compiled_truth.py:1-50]()\n\n### Truth Page Format\n\nTruth pages are stored as Markdown with YAML frontmatter:\n\n```yaml\n---\nentity_id: PROJECT-ALPHA\nentity_type: PROJECT\nlast_compiled: 2024-01-15T10:30:00Z\nversion: 3\n---\n# PROJECT-ALPHA — Compiled Truth\n\n## Current Understanding\n- Multi-agent orchestration platform\n- Version 2.1.0 deployed to production\n\n## Evidence Trail\n\n### 2024-01-15T10:30:00Z [HIGH] (source: BLOCK-20240115-001)\nCurrent stable release supporting concurrent task execution.\n\n### 2024-01-10T08:00:00Z [MEDIUM] (source: BLOCK-20240110-015) ~~SUPERSEDED~~\nOriginal architecture diagram showing single-threaded design.\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:60-100]()\n\n### Compiled Truth MCP Tools\n\n#### `compiled_truth_load`\n\nLoads a compiled truth page for an entity.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `entity_id` | str | Yes | The entity identifier |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:100-150]()\n\n#### `compiled_truth_add_evidence`\n\nAdds new evidence to an entity's truth page and triggers recompilation.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `entity_id` | str | Yes | - | Entity identifier |\n| `entity_type` | str | Yes | - | Entity type |\n| `observation` | str | Yes | - | The factual claim |\n| `source` | str | Yes | - | Source block ID |\n| `confidence` | str | No | \"medium\" | Confidence level |\n\n**Returns:**\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"entity_id\": \"PROJECT-ALPHA\",\n \"version\": 4,\n \"evidence_count\": 15,\n \"path\": \"/workspace/truth/PROJECT-ALPHA.md\",\n \"message\": \"Evidence added and page recompiled (v4).\"\n}\n```\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:150-220]()\n\n#### `compiled_truth_contradictions`\n\nDetects contradictions within a compiled truth page.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `entity_id` | str | Yes | Entity identifier |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:220-280]()\n\n### Recompilation Process\n\nThe `recompile_truth` function regenerates the compiled section from non-superseded evidence:\n\n1. Filters out superseded evidence entries\n2. Orders remaining entries by timestamp (newest first)\n3. Generates bullet-point summary\n4. Increments version number\n5. Updates `last_compiled` timestamp\n\n资料来源：[src/mind_mem/compiled_truth.py:200-250]()\n\n## Causal Graph\n\nThe causal graph tracks dependency relationships between blocks for impact analysis:\n\n```mermaid\ngraph LR\n A[Decision Made] --> B[Task Created]\n B --> C[Implementation Started]\n A --> D[Risk Assessment]\n C --> E[Code Reviewed]\n D --> F[Mitigation Applied]\n E --> G[Deployed]\n F --> G\n```\n\n### Traversal for Impact Analysis\n\nThe `traverse_graph` function supports:\n\n- **Forward propagation**: \"What blocks depend on this?\"\n- **Backward propagation**: \"What blocks does this depend on?\"\n- **Reachability queries**: \"Are these blocks connected?\"\n- **Critical path identification**: Longest dependency chains\n\n资料来源：[src/mind_mem/causal_graph.py]()\n\n## Contradiction Detection\n\n### Detection Strategy\n\nThe contradiction detector analyzes evidence entries to identify conflicting claims:\n\n1. **Temporal conflict**: Claims that cannot both be true given their timestamps\n2. **Semantic conflict**: Claims with opposing sentiment or meaning\n3. **Logical conflict**: Claims that logically exclude each other based on domain rules\n\n### Detection Function\n\n```python\ndef detect_contradictions(page: CompiledTruthPage) -> list[Contradiction]:\n \"\"\"Detect contradictions in a compiled truth page.\n \n Returns a list of detected contradictions with severity and\n affected evidence indices.\n \"\"\"\n```\n\n资料来源：[src/mind_mem/contradiction_detector.py]()\n\n### Contradiction Resolution\n\nWhen contradictions are detected, the system supports:\n\n1. **Supersession**: Mark older evidence as `superseded=True`\n2. **Escalation**: Flag for human review through the governance workflow\n3. **Version branching**: Create alternative truth pages for competing hypotheses\n\n资料来源：[src/mind_mem/compiled_truth.py:180-200]()\n\n## MCP Tool Summary\n\n| Tool | Domain | Purpose |\n|------|--------|---------|\n| `graph_add_edge` | Knowledge Graph | Add typed relationship |\n| `graph_query` | Knowledge Graph | N-hop traversal queries |\n| `graph_stats` | Knowledge Graph | Graph statistics |\n| `traverse_graph` | Causal Graph | Dependency impact analysis |\n| `compiled_truth_load` | Truth Pages | Load entity truth page |\n| `compiled_truth_add_evidence` | Truth Pages | Add evidence and recompile |\n| `compiled_truth_contradictions` | Truth Pages | Detect conflicts |\n| `list_contradictions` | Governance | List all contradictions |\n| `memory_evolution` | Governance | A-MEM block metadata |\n\n资料来源：[src/mind_mem/mcp/tools/graph.py](), [src/mind_mem/mcp/tools/kernels.py](), [src/mind_mem/mcp/tools/governance.py]()\n\n## Configuration\n\n### Workspace Configuration\n\nIn `mind-mem.json`:\n\n```json\n{\n \"knowledge_graph\": {\n \"enabled\": true,\n \"db_path\": \"intelligence/state/retrieval_graph.db\"\n },\n \"causal_graph\": {\n \"enabled\": true,\n \"db_path\": \"intelligence/state/causal_graph.db\"\n },\n \"truth_pages\": {\n \"enabled\": true,\n \"directory\": \"truth/\"\n },\n \"contradiction_detection\": {\n \"enabled\": true,\n \"severity_threshold\": \"medium\"\n }\n}\n```\n\n### Schema Version\n\nAll MCP tools return responses with `_schema_version` for API compatibility:\n\n```python\nMCP_SCHEMA_VERSION = \"3.2.0\"\n```\n\n资料来源：[src/mind_mem/infra/constants.py]()\n\n---\n\n\n\n## Governance & Safety\n\n### 相关页面\n\n相关主题：[Core Components](#page-components), [Key Concepts](#page-key-concepts), [Block Format & Data Model](#page-data-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/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/audit_chain.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/audit_chain.py)\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/abstention_classifier.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/abstention_classifier.py)\n- [mind/governance.mind](https://github.com/star-ga/mind-mem/blob/main/mind/governance.mind)\n- [docs/governance.md](https://github.com/star-ga/mind-mem/blob/main/docs/governance.md)\n- [docs/protection.md](https://github.com/star-ga/mind-mem/blob/main/docs/protection.md)\n \n\n# Governance & Safety\n\nThe mind-mem system implements a multi-layered governance and safety architecture designed to ensure memory integrity, prevent contradictions, detect drift, and enforce quality standards before any block enters the system. The core invariant is: **\"memory is never modified except by governance\"** — meaning every change to the memory state requires explicit approval through a controlled workflow.\n\n## Architecture Overview\n\nThe governance and safety subsystem spans several interconnected components:\n\n```mermaid\ngraph TD\n subgraph \"Ingestion Layer\"\n QG[Quality Gate]\n AC[Abstention Classifier]\n GG[Governance Gate]\n end\n \n subgraph \"Integrity Layer\"\n CT[Compiled Truth]\n CD[Contradiction Detector]\n DD[Drift Detector]\n end\n \n subgraph \"Audit Layer\"\n AU[Audit Chain]\n MH[Merkle Hash]\n end\n \n subgraph \"MCP Tools\"\n PRO[propose_update]\n APP[approve_apply]\n ROLL[rollback_proposal]\n SCAN[scan]\n LIST_CON[List Contradictions]\n end\n \n QG -->|block review| GG\n AC -->|abstain if uncertain| QG\n GG -->|staged proposal| PRO\n PRO -->|pending| APP\n APP -->|apply| CT\n CT -->|evidence| CD\n CT -->|evidence| DD\n AU -->|genesis block| MH\n MH -->|verify| AU\n \n SCAN -->|run all checks| CD\n SCAN -->|run all checks| DD\n LIST_CON -->|contradiction list| CD\n```\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-15]()\n\n## Core Governance Invariants\n\n### The Memory Modification Rule\n\nThe fundamental governance rule is explicit:\n\n> **\"Memory is never modified except by governance\"**\n\nThis means:\n1. No agent can directly write or modify memory blocks\n2. All modifications must go through the governance workflow\n3. The governance workflow includes staged proposals, human review, and audit trails\n4. Rollback capabilities exist to restore from pre-apply snapshots\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:17-20]()\n\n### Governance Workflow States\n\n```mermaid\nstateDiagram-v2\n [*] --> Proposed: propose_update\n Proposed --> Approved: approve_apply\n Proposed --> Rejected: reject\n Approved --> Applied: execute\n Applied --> [*]\n Proposed --> RolledBack: rollback_proposal\n Rejected --> [*]\n RolledBack --> [*]\n```\n\n## Quality Gate\n\nThe quality gate is a pre-storage filter that inspects candidate blocks before they enter the system. It implements 8 deterministic, content-based rules.\n\n资料来源：[src/mind_mem/quality_gate.py:1-20]()\n\n### Quality Rules\n\n| Rule ID | Rule Name | Description | Default Action |\n|---------|-----------|-------------|----------------|\n| 1 | `empty` | Block is whitespace-only | Log only |\n| 2 | `too_short` | Fewer than 32 non-whitespace characters | Log only |\n| 3 | `oversize` | Exceeds 64 KiB of UTF-8 bytes | Log only |\n| 4 | `malformed_utf8` | Contains lone surrogates or cannot round-trip | Log only |\n| 5 | `stopwords_only` | Every token is a stopword (no semantic content) | Log only |\n| 6 | `near_duplicate` | Levenshtein similarity ≥ 0.97 to a recent block (within 24h) | Log only |\n| 7 | `injection_marker` | Matches a known prompt-injection pattern | Log only |\n| 8 | `ok` | No rule fired (happy path) | Accept |\n\n### Quality Gate Modes\n\nThe quality gate operates in two modes:\n\n| Mode | Behavior | Trigger |\n|------|----------|---------|\n| **Advisory** (default) | All rules logged but verdict still `accept` | Default configuration |\n| **Strict** | Any rule that fires causes `reject` | `strict=True` kwarg OR `QualityGateConfig(mode=\"strict\")` OR `mind-mem.json` setting |\n\n资料来源：[src/mind_mem/quality_gate.py:20-45]()\n\n## Abstention Classifier\n\nThe abstention classifier provides an uncertainty-aware filtering layer that can abstain from processing when confidence is insufficient.\n\n资料来源：[src/mind_mem/abstention_classifier.py:1-10]()\n\n## Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity and recompiles canonical understanding. Each truth page contains:\n\n### Data Model\n\n```python\n@dataclass\nclass CompiledTruthPage:\n entity_id: str # Entity identifier\n entity_type: str # Type classification\n compiled_section: str # Regenerated summary\n evidence_entries: list # All evidence items\n last_compiled: str # ISO timestamp\n version: int # Increments on recompile\n```\n\n### Evidence Entry Structure\n\n```python\n@dataclass\nclass EvidenceEntry:\n timestamp: str # ISO timestamp\n source: str # Source identifier\n observation: str # The factual observation\n confidence: str # Confidence level\n superseded: bool # Whether this entry is superseded\n```\n\n### Compiled Truth Workflow\n\n```mermaid\ngraph LR\n subgraph \"Evidence Collection\"\n OBS[New Observation] --> ADD[compiled_truth_add_evidence]\n end\n \n subgraph \"Recompilation\"\n ADD --> REQ[recompile_truth]\n REQ --> GEN[Generate bullet summary]\n REQ --> INC[Increment version]\n REQ --> UPDATE[Update last_compiled]\n end\n \n subgraph \"Output\"\n GEN --> PAGE[Compiled Truth Page]\n INC --> PAGE\n UPDATE --> PAGE\n end\n```\n\n### Key Functions\n\n| Function | Purpose |\n|----------|---------|\n| `load_truth_page(workspace, entity_id)` | Load compiled truth from `{workspace}/entities/compiled/{entity_id}.md` |\n| `save_truth_page(workspace, page)` | Persist truth page to disk |\n| `recompile_truth(page)` | Regenerate compiled section from non-superseded evidence |\n| `supersede_evidence(page, entry_index, reason)` | Mark an evidence entry as superseded |\n| `detect_contradictions(page)` | Scan for conflicting evidence entries |\n\n资料来源：[src/mind_mem/compiled_truth.py:1-150]()\n\n## Contradiction Detection\n\nThe contradiction detector identifies conflicts within compiled truth pages and across the memory system.\n\n### Detection Capabilities\n\n- **Intra-page contradictions**: Conflicting evidence within a single entity's truth page\n- **Cross-page contradictions**: Conflicts between different entities\n- **Temporal conflicts**: Evidence that contradicts based on timing\n- **Confidence-weighted detection**: Higher confidence evidence takes precedence\n\n### Contradiction Result Structure\n\n```python\n@dataclass\nclass ContradictionFinding:\n entity_id: str # Affected entity\n type: str # e.g., \"temporal\", \"factual\", \"confidence\"\n evidence_a: EvidenceEntry # First conflicting entry\n evidence_b: EvidenceEntry # Second conflicting entry\n resolution_hint: str # Suggested resolution\n```\n\n资料来源：[src/mind_mem/contradiction_detector.py:1-30]()\n\n## Drift Detection\n\nDrift detection monitors for changes in memory that deviate from established patterns or governance-approved state.\n\n### Drift Categories\n\n| Category | Description |\n|----------|-------------|\n| **Content Drift** | Gradual semantic shifts in memory content |\n| **Structural Drift** | Changes in block format or organization |\n| **Behavioral Drift** | Patterns in how memory is modified |\n| **Governance Drift** | Deviation from governance-approved workflows |\n\n资料来源：[src/mind_mem/drift_detector.py:1-25]()\n\n## Audit Chain\n\nThe audit chain maintains a cryptographic record of all governance actions using SHA3-512 hashing.\n\n### Audit Chain Components\n\n```mermaid\ngraph TD\n subgraph \"Genesis Block\"\n GB[Genesis Hash]\n end\n \n subgraph \"Audit Records\"\n A1[Action 1 Record]\n A2[Action 2 Record]\n A3[Action 3 Record]\n end\n \n subgraph \"Hash Chain\"\n GB --> H1[Hash 1]\n H1 --> H2[Hash 2]\n H2 --> H3[Hash 3]\n end\n \n A1 --> H1\n A2 --> H2\n A3 --> H3\n```\n\n### Verification Capabilities\n\n| Tool | Purpose |\n|------|---------|\n| `verify_merkle(block_id, content_hash)` | Prove a block's Merkle inclusion against the live tree |\n| `verify_chain()` | Walk both SHA3-512 governance hash chain and evidence chain |\n| `list_evidence(block_id, action)` | Enumerate governance evidence objects with filters |\n\n资料来源：[src/mind_mem/audit_chain.py:1-50]()\n\n## Governance MCP Tools\n\nThe governance functionality is exposed through MCP (Model Context Protocol) tools for agent integration.\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:1-25]()\n\n### Tool Reference\n\n| Tool | Purpose | Key Parameters |\n|------|---------|----------------|\n| `propose_update` | Stage a new decision/task as a SIGNAL | `block_type`, `statement`, `rationale`, `tags`, `confidence` |\n| `approve_apply` | Apply a staged proposal (dry-run by default) | `signal_id`, `dry_run` |\n| `rollback_proposal` | Restore workspace from pre-apply snapshot | `signal_id` |\n| `scan` | Integrity scan (contradictions/drift/pending) | — |\n| `list_contradictions` | Enriched contradiction listing | `entity_id` (optional) |\n| `memory_evolution` | A-MEM metadata for a block | `block_id` |\n\n### `propose_update` Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `block_type` | `str` | required | Decision or task |\n| `statement` | `str` | required | The proposed content |\n| `rationale` | `str` | \"\" | Justification |\n| `tags` | `str` | \"\" | Comma-separated tags |\n| `confidence` | `str` | \"medium\" | low/medium/high |\n\n### `approve_apply` Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `signal_id` | `str` | required | Signal identifier to apply |\n| `dry_run` | `bool` | `true` | Preview without applying |\n\n### `rollback_proposal` Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `signal_id` | `str` | required | Signal to rollback |\n\n资料来源：[src/mind_mem/mcp/tools/governance.py:30-100]()\n\n## Governance Health Benchmark\n\nThe governance health benchmark (`governance_health_bench`) exercises the full governance system:\n\n```mermaid\ngraph TD\n GB[governance_health_bench] --> CD[Contradiction Detection]\n GB --> AC[Audit Completeness]\n GB --> DD[Drift Detection]\n GB --> SC[Scalability Probes]\n \n CD --> CR{Results}\n AC --> CR\n DD --> CR\n SC --> CR\n \n CR --> JSON[JSON Report]\n```\n\n### Benchmark Sub-Suites\n\n| Sub-Suite | Description |\n|-----------|-------------|\n| Contradiction Detection | Tests contradiction detector against known conflict patterns |\n| Audit Completeness | Verifies all governance actions have audit records |\n| Drift Detection | Exercises drift detection with synthetic drift scenarios |\n| Scalability Probes | Performance testing under load |\n\n资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-40]()\n\n## Configuration\n\n### Workspace Configuration\n\nThe governance system respects workspace-level configuration in `mind-mem.json`:\n\n```json\n{\n \"quality_gate_mode\": \"advisory\",\n \"contradiction_detection\": {\n \"enabled\": true,\n \"min_confidence_threshold\": \"medium\"\n },\n \"drift_detection\": {\n \"enabled\": true,\n \"drift_threshold\": 0.15\n }\n}\n```\n\n### Kernel Configuration\n\nMIND kernel files in `.mind` format control governance behavior:\n\n| Kernel File | Purpose |\n|-------------|---------|\n| `governance.mind` | Governance rules and workflow configuration |\n| `contradictions.mind` | Contradiction detection parameters |\n| `protection.mind` | Safety thresholds and limits |\n\n资料来源：[mind/governance.mind:1-30]()\n\n## MCP Resources\n\nGovernance state is also exposed as read-only MCP resources:\n\n| Resource URI | Description |\n|--------------|-------------|\n| `mind-mem://contradictions` | Detected contradictions |\n| `mind-mem://health` | Workspace health summary |\n| `mind-mem://ledger` | Shared multi-agent fact ledger |\n\n资料来源：[src/mind_mem/mcp/resources.py:1-40]()\n\n## Error Handling\n\n### Structured Error Envelope\n\nAll governance tools return a consistent error format:\n\n```json\n{\n \"_schema_version\": \"3.2.0\",\n \"error\": \"Human-readable error message\"\n}\n```\n\n### Common Error Scenarios\n\n| Scenario | Error Message Pattern |\n|----------|----------------------|\n| Entity not found | \"No compiled truth page found for '{entity_id}'\" |\n| Failed evidence add | \"Failed to add evidence: {exception}\" |\n| Rollback unavailable | \"No snapshot found for signal '{signal_id}'\" |\n| Workspace locked | SQLite busy error (retry-able) |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:60-80]()\n\n## Metrics and Observability\n\nGovernance operations emit metrics for monitoring:\n\n| Metric Name | Description |\n|-------------|-------------|\n| `mcp_kernel_list` | Kernel list operations |\n| `mcp_compiled_truth_add_evidence` | Evidence additions |\n| `evidence_entries_superseded` | Superseded evidence count |\n| `truth_pages_loaded` | Truth page load operations |\n| `contradictions_detected` | New contradictions found |\n\n资料来源：[src/mind_mem/mcp/tools/kernels.py:35-40]()\n\n## See Also\n\n- [Memory System](./memory-system.md) — Core memory storage and retrieval\n- [MCP Tools](./mcp-tools.md) — MCP tool reference\n- [CLI Reference](./cli-reference.md) — `mm` command-line interface\n- [Protection](./protection.md) — Safety mechanisms and thresholds\n\n---\n\n\n\n## Block Format & Data Model\n\n### 相关页面\n\n相关主题：[Key Concepts](#page-key-concepts), [Hybrid Search & Retrieval](#page-hybrid-search)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/block_store.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/block_store.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/schema_version.py](https://github.com/star-ga/mind-mem/blob/main/src/mind_mem/schema_version.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 \n\n# Block Format & Data Model\n\n## Overview\n\nThe mind-mem system uses a **Markdown-based block format** as its primary data model for storing and retrieving structured knowledge. Each block is a self-contained unit of information stored as Markdown text with a specific header format and field structure. This design enables human readability, git-friendly versioning, and flexible querying through the recall system.\n\n资料来源：[src/mind_mem/block_store.py:1-50]()\n\n## Block Structure\n\n### Anatomy of a Block\n\nA mind-mem block consists of three main parts:\n\n```markdown\n[UNIQUE_BLOCK_ID]\nField1: value\nField2: value\nListField:\n- item1\n- item2\nTags: tag1, tag2\n\n---\n```\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| Block ID | Unique identifier in square brackets | `[DECISION-2024-001]` |\n| Fields | Key-value pairs with colon separators | `Status: active` |\n| Separator | `---` marks block end | `---` |\n\n资料来源：[src/mind_mem/block_store.py:45-75]()\n\n### Canonical Field Order\n\nBlocks emit fields in a fixed order to ensure deterministic round-trips. Unknown fields are appended alphabetically after the canonical head.\n\n```python\n_CANONICAL_FIELD_ORDER: tuple[str, ...] = (\n \"Statement\",\n \"Date\",\n \"Status\",\n \"Priority\",\n \"Risk\",\n \"Type\",\n \"Subject\",\n \"Object\",\n \"Tags\",\n \"Rationale\",\n \"Evidence\",\n \"Source\",\n \"Confidence\",\n \"ContentHash\",\n \"Excerpt\",\n \"Action\",\n)\n```\n\n资料来源：[src/mind_mem/block_store.py:28-46]()\n\n### Forbidden Write Fields\n\nThese internal fields are parsed for display but never written back to storage:\n\n```python\n_FORBIDDEN_WRITE_FIELDS: frozenset[str] = frozenset({\n \"_id\", \n \"_source_file\", \n \"_line_number\", \n \"_raw\"\n})\n```\n\n资料来源：[src/mind_mem/block_store.py:48]()\n\n## Block Storage Architecture\n\n### Directory Organization\n\nBlocks are stored across multiple directories based on their type prefix:\n\n```mermaid\ngraph TD\n A[\"Block ID: `[DECISION-xxx]`\"] --> B[\"_BLOCK_PREFIX_MAP\"]\n B --> C[\"`decisions/` directory\"]\n \n A2[\"Block ID: `[TASK-xxx]`\"] --> B\n B --> C2[\"`tasks/` directory\"]\n \n A3[\"Block ID: `[PROJECT-xxx]`\"] --> B\n B --> C3[\"`projects/` directory\"]\n \n A4[\"Block ID: `[INCIDENT-xxx]`\"] --> B\n B --> C4[\"`incidents/` directory\"]\n```\n\n### Block Prefix Mapping\n\nThe system maps block ID prefixes to their canonical storage locations:\n\n| Prefix | Storage Directory | Description |\n|--------|-------------------|-------------|\n| `DECISION` | `decisions/` | Decision records |\n| `TASK` | `tasks/` | Task items |\n| `PROJECT` | `projects/` | Project definitions |\n| `INCIDENT` | `incidents/` | Incident reports |\n| `PERSON` | `people/` | Person entities |\n| `TOOL` | `tools/` | Tool definitions |\n| `SIGNAL` | `signals/` | Auto-captured signals |\n\n资料来源：[src/mind_mem/block_store.py:15-26]()\n\n## Block Rendering\n\n### Serialization Process\n\nThe `_render_block()` function converts a parsed block dictionary back to its Markdown form:\n\n```mermaid\ngraph LR\n A[\"block dict\"] --> B[\"Extract _id\"]\n B --> C[\"Lookup target file\"]\n C --> D[\"Render fields in canonical order\"]\n D --> E[\"Handle list fields as bullets\"]\n E --> F[\"Neutralize \\\\n[ to prevent block collision\"]\n F --> G[\"Output markdown string\"]\n```\n\nKey rendering rules:\n- Lists are rendered as `- item` bullets on lines following the field\n- Multi-line values are emitted verbatim\n- Newline-plus-left-bracket sequences are neutralized to prevent accidental block headers\n\n资料来源：[src/mind_mem/block_store.py:50-85]()\n\n### Write Surface\n\nThe `BlockStore.write_block()` method handles persistence:\n\n```python\ndef write_block(self, block: dict[str, Any]) -> str:\n block_id = block.get(\"_id\")\n target = _resolve_block_file(self._workspace, block_id)\n rendered = _render_block(block)\n \n with FileLock(target):\n # Replace existing or append\n existing_text = fh.read()\n loc = _locate_block_in_text(existing_text, block_id)\n # Insert or append\n```\n\n资料来源：[src/mind_mem/block_store.py:120-160]()\n\n## Compiled Truth Pages\n\n### Purpose\n\nCompiled Truth Pages aggregate evidence for a specific entity into a canonical understanding. They maintain an **evidence trail** showing how knowledge evolved over time.\n\n```mermaid\ngraph TD\n A[\"Evidence Entries
from memory/\"] --> B[\"Compile Process\"]\n B --> C[\"CompiledTruthPage\"]\n C --> D[\"Current Understanding\"]\n C --> E[\"Evidence Trail\"]\n```\n\n### Data Model\n\n```python\nclass CompiledTruthPage:\n entity_id: str\n entity_type: str\n compiled_section: str # Canonical understanding\n evidence_entries: list[EvidenceEntry]\n last_compiled: datetime\n version: str\n\nclass EvidenceEntry:\n timestamp: str\n source: str\n observation: str\n confidence: str # HIGH, MEDIUM, LOW\n superseded: bool # Marked if later evidence contradicts\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:20-50]()\n\n### Markdown Format\n\nCompiled Truth Pages use structured Markdown with YAML frontmatter:\n\n```markdown\n---\nentity_id: postgresql-migration\nentity_type: project\nlast_compiled: 2024-01-15T10:30:00Z\nversion: v3\n---\n\n# postgresql-migration — Compiled Truth\n\n## Current Understanding\nThe migration to PostgreSQL 16 is complete and stable.\n\n## Evidence Trail\n\n### 2024-01-10 [HIGH] (source: decisions.md)\nInitial decision to migrate from MySQL to PostgreSQL.\n\n### 2024-01-12 [MEDIUM] (source: signals.md) ~~SUPERSEDED~~\nInterim report showing migration issues. ~~SUPERSEDED~~\n```\n\n资料来源：[src/mind_mem/compiled_truth.py:55-95]()\n\n### File Operations\n\n| Function | Purpose | Location |\n|----------|---------|----------|\n| `format_truth_page()` | Serialize page to Markdown | `entities/compiled/{entity_id}.md` |\n| `parse_truth_page()` | Parse Markdown back to page object | Read from `entities/compiled/` |\n| `load_truth_page()` | Load from disk, return `None` if missing | `entities/compiled/{entity_id}.md` |\n| `save_truth_page()` | Persist page to disk | `entities/compiled/{entity_id}.md` |\n\n资料来源：[src/mind_mem/compiled_truth.py:95-150]()\n\n## Block Lifecycle\n\n```mermaid\ngraph TD\n A[\"Block Created\"] --> B[\"Quality Gate Check\"]\n B --> C{Pass?}\n C -->|No| D[\"Log verdict
Reject if strict mode\"]\n C -->|Yes| E[\"Parse & Validate\"]\n E --> F[\"Write to canonical file\"]\n F --> G[\"Index for recall\"]\n G --> H[\"Block Active\"]\n H --> I{\"Update proposal?\"}\n I -->|Yes| J[\"Stage as SIGNAL\"]\n I -->|No| K[\"Query via recall API\"]\n```\n\n### Quality Gate Rules\n\nBefore storage, blocks pass through eight deterministic checks:\n\n| Rule | Condition | Default Behavior |\n|------|-----------|-------------------|\n| `empty` | Whitespace-only content | Accept with log |\n| `too_short` | < 32 non-whitespace chars | Accept with log |\n| `oversize` | > 64 KiB UTF-8 bytes | Reject |\n| `malformed_utf8` | Lone surrogates present | Reject |\n| `stopwords_only` | All tokens are stopwords | Accept with log |\n| `near_duplicate` | ≥ 0.97 similarity to recent block | Accept with log |\n| `injection_marker` | Matches known injection patterns | Reject |\n\n资料来源：[src/mind_mem/quality_gate.py:1-30]()\n\n## Deletion & Recovery\n\n### Block Deletion\n\nWhen a block is deleted, its content is preserved in a recovery journal:\n\n```python\ndef _delete_block(self, block_id: str, workspace: str) -> None:\n log_path = os.path.join(workspace, \"memory\", \"deleted_blocks.jsonl\")\n entry = {\n \"block_id\": block_id,\n \"deleted_at\": datetime.now(timezone.utc).isoformat(),\n \"content\": content,\n }\n with open(log_path, \"a\") as f:\n f.write(json.dumps(entry) + \"\\n\")\n```\n\n### Locating Blocks in Text\n\nThe `_locate_block_in_text()` function finds block boundaries:\n\n1. Block starts at line exactly equal to `[]`\n2. Block ends at:\n - Next `[]` header line\n - Isolated `---` separator (preceded by blank line)\n - End of file\n\n资料来源：[src/mind_mem/block_store.py:100-120]()\n\n## Summary\n\nThe mind-mem block format provides:\n\n| Feature | Implementation |\n|---------|----------------|\n| **Storage** | Markdown files organized by type prefix |\n| **Serialization** | Canonical field ordering for deterministic output |\n| **Compiled Truth** | Aggregated evidence with version tracking |\n| **Recovery** | JSONL deletion log for block restoration |\n| **Quality** | Eight-rule pre-storage gate |\n| **Concurrency** | File-level locking via `FileLock` |\n\nThis design enables human-readable storage, git-friendly versioning, and a flexible recall system that can parse and index blocks across the workspace.\n\n---\n\n\n\n## MCP Server & Tools\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/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/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/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/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 \n\n# MCP Server & Tools\n\nThe MCP Server & Tools layer is the primary interface through which AI agents interact with the mind-mem workspace. Built on the FastMCP framework, this component exposes the entire memory system's capabilities—including recall, governance, consolidation, and knowledge management—as a standardized Model Context Protocol (MCP) surface that any MCP-compatible AI client (Claude Code, Cursor, Windsurf, Codex CLI, etc.) can consume.\n\n## Architecture Overview\n\nThe MCP layer is organized as a modular plugin architecture under `src/mind_mem/mcp/`:\n\n```\nmcp/\n├── server.py # FastMCP server entry point\n├── resources.py # @mcp.resource declarations\n├── infra/\n│ ├── rate_limit.py # Rate limiting infrastructure\n│ └── http_auth.py # HTTP authentication\n└── tools/\n ├── recall.py # Memory recall & search\n ├── governance.py # Decision/task governance\n ├── memory_ops.py # Index & lifecycle management\n ├── kernels.py # MIND kernel configuration\n ├── consolidation.py # Memory consolidation\n ├── core.py # Context-core bundle management\n ├── benchmark.py # Governance health benchmarks\n ├── audit.py # Compliance & drift detection\n └── arch_mind.py # Architecture metrics wrapper\n```\n\n### Server Initialization Pattern\n\nThe server uses a deferred registration pattern to avoid circular imports. Tools and resources are defined as module-level functions, then wired onto the FastMCP instance via a `register(mcp)` function call after the server instance is constructed.\n\n```python\n# Resources use module-level definition\ndef get_decisions() -> str:\n \"\"\"Active decisions from DECISIONS.md\"\"\"\n ...\n\n# Registration happens after server construction\ndef register(mcp: FastMCP) -> None:\n mcp.resource(\"mind-mem://decisions\")(get_decisions)\n```\n\nThis pattern ensures that test files referencing `server.get_decisions` continue to work without triggering import-time circular dependencies. 资料来源：[src/mind_mem/mcp/resources.py:1-47]()\n\n## MCP Resources\n\nMCP Resources provide read-only views over the workspace filesystem. They expose the structured content of workspace documents as consumable data without requiring file I/O on the client side.\n\n### Available Resources\n\n| Resource URI | Source Document | Description |\n|-------------|-----------------|-------------|\n| `mind-mem://decisions` | `DECISIONS.md` | Active decisions (ADRs) |\n| `mind-mem://tasks` | `TASKS.md` | All tracked tasks |\n| `mind-mem://entities/{type}` | `memory/entities/*.md` | Projects, people, tools, incidents |\n| `mind-mem://signals` | `memory/signals/` | Auto-captured signals |\n| `mind-mem://contradictions` | `memory/contradictions/` | Detected contradictions |\n| `mind-mem://health` | Computed | Workspace health summary |\n| `mind-mem://recall/{query}` | Computed | BM25 recall search results |\n| `mind-mem://ledger` | `memory/ledger/` | Shared multi-agent fact ledger |\n\nThe resource module consolidates all eight resource types into a single file because each body is small (5–15 lines), they share the same imports, and they form a cohesive read-only surface. 资料来源：[src/mind_mem/mcp/resources.py:1-47]()\n\n## MCP Tools\n\nMCP Tools expose the full operational surface of the mind-mem system. They are organized by domain into eight functional areas.\n\n### Tool Registration Pattern\n\nAll tools are decorated with `@mcp_tool_observe` for observability, which wraps the function to emit metrics and structured logging. Tools also support tracing via the `@_traced` decorator for detailed request tracking.\n\n```python\n@mcp_tool_observe\n@_traced(\"tool_name\")\ndef tool_name(param: str) -> str:\n \"\"\"Tool description.\"\"\"\n ws = _workspace()\n # implementation\n return json.dumps(result, indent=2)\n```\n\n### Tool Domains\n\n## Recall Tools\n\nRecall tools provide the primary memory retrieval surface. They support multiple retrieval backends and output formats.\n\n| Tool | Purpose |\n|------|---------|\n| `recall` | Full-text search with configurable backend (BM25, auto, hybrid) |\n| `context` | Token-budgeted snippet generation |\n| `explain` | Query intent explanation |\n| `trace` | MCP call log tail viewer |\n\nThe recall implementation supports three retrieval backends:\n- **auto** (default): System selects based on query characteristics\n- **bm25**: Classic bag-of-words relevance ranking\n- **hybrid**: Combines BM25 with semantic similarity\n\nOutput formats include `text` (human-readable) and `json` (structured). 资料来源：[src/mind_mem/mm_cli.py:1-100]()\n\n## Governance Tools\n\nGovernance tools implement the \"memory is never modified except by governance\" invariant. They provide a staged update workflow where changes are proposed, reviewed, and then applied atomically.\n\n| Tool | Purpose |\n|------|---------|\n| `propose_update` | Stage a new decision or task as a SIGNAL |\n| `approve_apply` | Apply a staged proposal (dry-run by default) |\n| `rollback_proposal` | Restore workspace from pre-apply snapshot |\n| `scan` | Integrity scan for contradictions, drift, and pending items |\n| `list_contradictions` | Enriched contradiction listing |\n| `memory_evolution` | A-MEM metadata for a block |\n\n### Governance Workflow\n\n```mermaid\ngraph TD\n A[propose_update] --> B{Review}\n B -->|Approve| C[approve_apply]\n B -->|Reject| D[rollback_proposal]\n C --> E[Snapshot Created]\n E --> F[Changes Applied]\n F --> G[Audit Log Updated]\n D --> H[Workspace Restored]\n```\n\nThe governance system maintains append-only audit logs and supports atomic rollback through workspace snapshots. 资料来源：[src/mind_mem/mcp/tools/governance.py:1-60]()\n\n## Memory Operations Tools\n\nMemory operations tools manage the workspace lifecycle and provide introspection capabilities.\n\n| Tool | Purpose |\n|------|---------|\n| `index_stats` | FTS5 index state inspection |\n| `reindex` | Full index rebuild |\n| `delete_memory_item` | Atomic block removal with recovery log |\n| `export_memory` | JSONL dump with configurable metadata and size cap |\n| `get_block` | Block lookup by ID |\n| `memory_health` | Health dashboard |\n| `compact` | Workspace compaction |\n| `stale_blocks` | Staleness-flag management |\n\nDeletion operations are atomic and maintain an append-only recovery log for disaster recovery. The export tool supports size capping to prevent unbounded output when dumping large workspaces. 资料来源：[src/mind_mem/mcp/tools/memory_ops.py:1-80]()\n\n## MIND Kernel Tools\n\nMIND Kernel tools provide read-write access to `.mind` configuration files that tune recall, reranking, RM3 expansion, and related pipeline knobs.\n\n| Tool | Purpose |\n|------|---------|\n| `list_mind_kernels` | List available kernel configurations |\n| `get_mind_kernel` | Retrieve specific kernel configuration |\n| `compiled_truth_load` | Load entity truth page |\n| `compiled_truth_add_evidence` | Add evidence to truth page |\n| `compiled_truth_contradictions` | Detect contradictions in truth page |\n\nThese tools interact with the FFI layer (`mind_ffi`) to load and persist kernel configurations stored in the workspace's `.mind/` directory. 资料来源：[src/mind_mem/mcp/tools/kernels.py:1-70]()\n\n## Consolidation Tools\n\nConsolidation tools implement the \"memory settles over time\" principle through cognitive forgetting and autonomous enrichment.\n\n| Tool | Purpose |\n|------|---------|\n| `plan_consolidation` | Dry-run of the cognitive forgetting cycle |\n| `propagate_staleness` | Diffusion of staleness scores over cross-references |\n| `project_profile` | Structured session-start intelligence summary |\n| `dream_cycle` | Autonomous memory enrichment |\n\nThe consolidation cycle analyzes block importance scores, identifies candidates for archival, and optionally auto-repairs broken citations. Configuration parameters include:\n- `importance_threshold` (default: 0.25)\n- `stale_days` (default: 14)\n- `archive_after_days` (default: 60)\n- `grace_days` (default: 30)\n\n```mermaid\ngraph LR\n A[Memory Blocks] --> B[Importance Scoring]\n B --> C{Threshold Check}\n C -->|Low Importance| D[Staleness Propagation]\n C -->|High Importance| E[Retain]\n D --> F[Archive Candidates]\n F --> G[Broken Citation Scan]\n G --> H[Auto-Repair]\n```\n\n资料来源：[src/mind_mem/mcp/tools/consolidation.py:1-60]()\n\n## Benchmark Tools\n\nBenchmark tools provide governance health validation and category analysis.\n\n| Tool | Purpose |\n|------|---------|\n| `governance_health_bench` | Run contradiction detection, audit completeness, drift, and scalability probes |\n| `category_summary` | Category distiller lookup with configurable limits |\n\nThe governance health benchmark exercises the full suite of validation checks and returns aggregated pass/fail counts per sub-suite. 资料来源：[src/mind_mem/mcp/tools/benchmark.py:1-60]()\n\n## Core Tools\n\nCore tools manage the `.mmcore` bundle lifecycle for portable block and knowledge-graph archives.\n\n| Tool | Purpose |\n|------|---------|\n| `build_core` | Snapshot blocks and knowledge graph into portable `.mmcore` archive |\n| `load_core` | Load a `.mmcore` bundle into workspace |\n| `unload_core` | Unload and remove core bundle |\n| `list_cores` | List installed cores |\n\nBundles support namespace prefixing for block isolation when loading cores from different sources. 资料来源：[src/mind_mem/mcp/tools/core.py:1-60]()\n\n## Architecture Metrics Tools (arch-mind)\n\nArch-mind tools wrap the `arch-mind` binary to expose architecture quality metrics as MCP tools.\n\n| Tool | Purpose |\n|------|---------|\n| `arch_baseline` | Initialize arch-mind store with baseline |\n| `arch_delta` | Compute (current scan) - (baseline scores) |\n| `arch_history` | List events in arch-mind store |\n| `arch_check_rules` | Apply rules.mind to fresh scan |\n| `arch_session_start` | Open session evidence node |\n| `arch_session_end` | Close session, write delta evidence |\n| `arch_metric_explain` | Per-metric breakdown for a fixture |\n\nThe binary is located via the `ARCH_MIND_BIN` environment variable, falling back to `PATH` lookup. These tools delegate all metric arithmetic to the binary, which enforces the canonical AST schema and Q16.16 determinism contract. 资料来源：[src/mind_mem/mcp/tools/arch_mind.py:1-60]()\n\n## CLI Interface (mm)\n\nThe `mm` CLI provides unified access to mind-mem for non-MCP agents. It mirrors the MCP tool surface with command-line equivalents.\n\n### Available Commands\n\n| Command | MCP Equivalent | Description |\n|---------|---------------|-------------|\n| `mm recall \"\"` | recall tool | Search memory |\n| `mm context \"\"` | context tool | Generate token-budgeted snippet |\n| `mm inject --agent \"\"` | inject tool | Render snippet for specific agent |\n| `mm vault scan ` | vault tools | List parsed vault blocks (JSON) |\n| `mm vault write --type --body ` | vault tools | Write vault block |\n| `mm status` | memory_health tool | Workspace summary |\n| `mm explain` | explain tool | Query intent explanation |\n| `mm trace` | trace tool | MCP call log tail |\n\nThe workspace is resolved via `MIND_MEM_WORKSPACE` environment variable, defaulting to `cwd` if unset. 资料来源：[src/mind_mem/mm_cli.py:1-100]()\n\n## Compiled Truth System\n\nThe compiled truth system aggregates evidence per entity and maintains a canonical understanding that recompiles when new evidence is added.\n\n### Data Model\n\n```python\n@dataclass\nclass CompiledTruthPage:\n entity_id: str\n entity_type: str\n compiled_section: str # Canonical understanding\n evidence_entries: list[EvidenceEntry]\n last_compiled: str # ISO timestamp\n version: int\n\n@dataclass\nclass EvidenceEntry:\n timestamp: str\n source: str\n observation: str\n confidence: str # \"high\", \"medium\", \"low\"\n superseded: bool\n```\n\n### Compiled Truth Format\n\nTruth pages are stored as markdown with frontmatter:\n\n```markdown\n---\nentity_id: project-alpha\nentity_type: project\nlast_compiled: 2026-01-15T10:30:00Z\nversion: 3\n---\n\n# project-alpha — Compiled Truth\n\n## Current Understanding\n[Compiled canonical understanding]\n\n## Evidence Trail\n\n### 2026-01-15T10:30:00Z [HIGH] (source: standup-notes.md)\n[Observation text]\n```\n\nEvidence entries are ordered newest-first, with superseded entries marked for visibility. 资料来源：[src/mind_mem/compiled_truth.py:1-100]()\n\n## Observability & Metrics\n\nAll MCP tools are wrapped with `@mcp_tool_observe` for automatic metrics emission. The observability layer tracks:\n\n- Tool invocation counts per tool name\n- Error rates and exception types\n- Latency percentiles\n- Workspace-scoped activity\n\nTools can optionally use the `@_traced` decorator for detailed request tracing that captures the full call chain. 资料来源：[src/mind_mem/mcp/tools/governance.py:1-50]()\n\n## Agent Integration\n\nThe `hook_installer` module provides declarative integration for various AI coding clients:\n\n| Agent | Config Format | Detection |\n|-------|--------------|-----------|\n| claude | JSON config block | `claude` binary |\n| cursor | JSON config block | `cursor` binary |\n| windsurf | MCP JSON | `windsurf` binary |\n| aider | YAML block | `aider` binary |\n| openclaw | JSON hooks | `~/.openclaw/` path |\n| copilot | Text block | Always offered |\n| cody | JSON generic | `cody` binary |\n| qodo | Text block | `~/.codium/` path |\n\nEach agent type has a canonical config file path, content template with the `MIND_MEM_MARKER`, and detection strategy (binary presence, config path, or explicit flag). 资料来源：[src/mind_mem/hook_installer.py:1-200]()\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Purpose | Default |\n|----------|---------|---------|\n| `MIND_MEM_WORKSPACE` | Workspace root directory | `cwd` |\n| `MIND_MEM_MCP_SERVER` | Override MCP server path | Auto-detect |\n| `ARCH_MIND_BIN` | arch-mind binary path | `arch-mind` on PATH |\n| `MIND_MEM_LOG_FILE` | Structured JSON log path | stderr |\n\n### Workspace Structure\n\n```\nworkspace/\n├── DECISIONS.md # Active decisions\n├── TASKS.md # Task tracking\n├── memory/\n│ ├── entities/ # Entity truth pages\n│ ├── signals/ # Auto-captured signals\n│ ├── contradictions/ # Detected contradictions\n│ ├── ledger/ # Multi-agent fact ledger\n│ └── cores/ # .mmcore bundles\n└── .mind/ # Kernel configurations\n```\n\n## Summary\n\nThe MCP Server & Tools layer transforms mind-mem from a library into a first-class AI teammate interface. By exposing all capabilities through the Model Context Protocol:\n\n1. **Recall** becomes a first-class tool with configurable backends and output formats\n2. **Governance** enforces change management through propose-apply-rollback workflows\n3. **Consolidation** runs autonomously based on configurable importance thresholds\n4. **Observability** tracks all tool usage for audit and improvement\n\nThe modular tool organization allows clients to consume only the capabilities they need while maintaining a coherent system that enforces invariants like \"memory is never modified except by governance.\"\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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for star-ga/mind-mem.\n\nProject:\n- Name: mind-mem\n- Repository: https://github.com/star-ga/mind-mem\n- Summary: 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.\n- Host target: mcp_host, claude, claude_code, cursor\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: 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.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-overview: Overview. Produce one small intermediate artifact and wait for confirmation.\n2. page-key-concepts: Key Concepts. Produce one small intermediate artifact and wait for confirmation.\n3. page-quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n4. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n5. page-components: Core Components. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- docs/architecture.md\n- docs/block-format.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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"
}