{
"canonical_name": "Uranid/mnem",
"compilation_id": "pack_bd5a4663549d4bfd930d6a41498ed835",
"created_at": "2026-05-15T04:18:36.367018+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 mnem-cli` 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 mnem-cli",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_cb10b3629f4b452aa893956c18dedac7"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_c4f7a13530a6dfab0fd064304a487ea4",
"canonical_name": "Uranid/mnem",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/Uranid/mnem",
"slug": "mnem",
"source_packet_id": "phit_be76522d04b24a649fb250c1288a447d",
"source_validation_id": "dval_aa4979168e914161b416107790486e05"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 mcp_host的用户",
"github_forks": 28,
"github_stars": 83,
"one_liner_en": "Git for AI Agent Knowledge. A persistent, versioned memory layer for AI systems. Hybrid GraphRAG retrieval. Runs entirely offline.",
"one_liner_zh": "Git for AI Agent Knowledge. A persistent, versioned memory layer for AI systems. Hybrid GraphRAG retrieval. Runs entirely offline.",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:knowledge, rag, graph"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "mnem",
"title_zh": "mnem 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_be76522d04b24a649fb250c1288a447d",
"page_model": {
"artifacts": {
"artifact_slug": "mnem",
"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 mnem-cli",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/Uranid/mnem#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Git for AI Agent Knowledge. A persistent, versioned memory layer for AI systems. Hybrid GraphRAG retrieval. Runs entirely offline."
},
{
"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",
"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 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feature] hermes support",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_c54919b2b8b340438a9e5aa17291b93a | https://github.com/Uranid/mnem/issues/27 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[feature] hermes support",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1221867246 | https://github.com/Uranid/mnem | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[bug] Broken docs links: SPEC.md, ROADMAP.md, and Architecture page",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_5c74e7a10f774af6b0460b5da009d1b4 | https://github.com/Uranid/mnem/issues/23 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[bug] Broken docs links: SPEC.md, ROADMAP.md, and Architecture page",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1221867246 | https://github.com/Uranid/mnem | 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:1221867246 | https://github.com/Uranid/mnem | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1221867246 | https://github.com/Uranid/mnem | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1221867246 | https://github.com/Uranid/mnem | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1221867246 | https://github.com/Uranid/mnem | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[feature] hermes support。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 28,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 83
},
"source_url": "https://github.com/Uranid/mnem",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Git for AI Agent Knowledge. A persistent, versioned memory layer for AI systems. Hybrid GraphRAG retrieval. Runs entirely offline.",
"title": "mnem 能力包",
"trial_prompt": "# mnem - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mnem 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Git for AI Agent Knowledge. A persistent, versioned memory layer for AI systems. Hybrid GraphRAG retrieval. Runs entirely offline. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-knowledge-graph：知识图谱模型。围绕“知识图谱模型”模拟一次用户任务，不展示安装或运行结果。\n5. page-version-control：版本控制机制。围绕“版本控制机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-knowledge-graph\n输入：用户提供的“知识图谱模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-version-control\n输入：用户提供的“版本控制机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-knowledge-graph：Step 4 必须围绕“知识图谱模型”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-version-control：Step 5 必须围绕“版本控制机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/Uranid/mnem\n- https://github.com/Uranid/mnem#readme\n- README.md\n- README.zh-CN.md\n- crates/mnem-core/README.md\n- docs/src/introduction.md\n- docs/src/install.md\n- Dockerfile\n- docker-compose.yml\n- scripts/install.sh\n- scripts/install.ps1\n- crates/mnem-core/src/lib.rs\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mnem 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [feature] hermes support（https://github.com/Uranid/mnem/issues/27）；github/github_issue: [bug] Broken docs links: SPEC.md, ROADMAP.md, and Architecture page（https://github.com/Uranid/mnem/issues/23）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[feature] hermes support",
"url": "https://github.com/Uranid/mnem/issues/27"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] Broken docs links: SPEC.md, ROADMAP.md, and Architecture page",
"url": "https://github.com/Uranid/mnem/issues/23"
}
],
"status": "已收录 2 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "Git for AI Agent Knowledge. A persistent, versioned memory layer for AI systems. Hybrid GraphRAG retrieval. Runs entirely offline.",
"effort": "安装已验证",
"forks": 28,
"icon": "search",
"name": "mnem 能力包",
"risk": "需复核",
"slug": "mnem",
"stars": 83,
"tags": [
"MCP 工具",
"知识库问答",
"流程自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "blue",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/Uranid/mnem 项目说明书\n\n生成时间：2026-05-15 02:27:44 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [安装指南](#page-installation)\n- [系统架构](#page-architecture)\n- [Crates结构详解](#page-crates-structure)\n- [知识图谱模型](#page-knowledge-graph)\n- [版本控制机制](#page-version-control)\n- [内容寻址系统](#page-content-addressing)\n- [存储后端](#page-storage-backend)\n- [数据流与摄取管道](#page-data-flow)\n- [混合检索系统](#page-hybrid-retrieval)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/Uranid/mnem/blob/main/README.md)\n- [README.zh-CN.md](https://github.com/Uranid/mnem/blob/main/README.zh-CN.md)\n- [crates/mnem-core/README.md](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/README.md)\n- [crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n- [crates/mnem-ingest/src/chunk.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/chunk.rs)\n- [crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n- [crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n- [crates/mnem-ingest/src/pipeline.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pipeline.rs)\n- [crates/mnem-cli/src/commands/ingest.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/ingest.rs)\n- [crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n\n \n\n# 项目介绍\n\n## 概述\n\n**Mnem** 是一个用 Rust 编写的本地优先（local-first）知识图谱系统，旨在为 AI Agent 提供可靠、持久的记忆层。它将外部文档（PDF、Markdown、代码等）解析、分块、提取实体和关系，构建成结构化的有向图，支持版本化、冲突检测和密码学签名验证。\n\n资料来源：[crates/mnem-core/README.md](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/README.md)\n\n## 核心定位\n\nMnem 不是向量数据库，也不是传统的关系型知识库。它是一个**本地优先的 DAG（有向无环图）存储**，其设计目标包括：\n\n| 设计目标 | 说明 |\n|---------|------|\n| **本地优先** | 数据完全存储在本地，零云依赖 |\n| **版本化** | 完整的操作日志，支持分支、回滚和合并 |\n| **可验证** | 支持 Ed25519 签名和吊销列表验证 |\n| **AI 友好** | 专为 LLM/Agent 场景设计，支持上下文检索 |\n| **多源解析** | 支持 PDF、Markdown、代码、会话记录等多种格式 |\n\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n\n## 系统架构\n\nMnem 采用分层架构，核心分为以下几个 crate：\n\n```mermaid\ngraph TD\n subgraph \"表现层\"\n CLI[mnem-cli]\n HTTP[mnem-http]\n MCP[mnem-mcp]\n end\n \n subgraph \"核心层 mnem-core\"\n OBJ[objects: Node/Edge/Commit]\n PROLLY[prolly tree]\n STORE[Blockstore trait]\n RETRIEVE[Retriever]\n SIGN[Signer/Verifier]\n end\n \n subgraph \"数据接入层 mnem-ingest\"\n PDF[PDF 解析]\n MD[Markdown 解析]\n CODE[代码解析]\n CONV[会话解析]\n CHUNK[分块策略]\n EXTRACT[实体/关系提取]\n end\n \n CLI --> HTTP\n HTTP --> MCP\n CLI --> mnem-core\n HTTP --> mnem-core\n MCP --> mnem-core\n mnem-core --> mnem-ingest\n```\n\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n\n### 核心对象模型\n\n```\n资料来源：[crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n```\n\n| 对象类型 | 用途 |\n|---------|------|\n| **Node** | 图中的顶点，包含摘要、属性、上下文句子和可选内容 |\n| **Edge** | 图中的边，连接两个 Node，支持关系类型标签 |\n| **Commit** | 快照，包含一次操作后图的完整视图 |\n| **Operation** | 操作记录，包含时间戳、作者、签名等元信息 |\n| **View** | 读取视角，持有 heads 引用 |\n\n## 数据接入流程\n\n当用户向 Mnem 导入文档时，数据会经过以下处理流程：\n\n```mermaid\ngraph LR\n A[原始文档] --> B[格式检测]\n B --> C{解析器选择}\n C -->|Markdown| D[parse_markdown]\n C -->|PDF| E[pdf 文本提取]\n C -->|代码| F[tree-sitter 解析]\n C -->|会话| G[JSON/JSONL 解析]\n D --> H[Section 列表]\n E --> H\n F --> H\n G --> H\n H --> I[分块策略]\n I --> J[Chunk 向量]\n J --> K[实体提取]\n K --> L[关系提取]\n L --> M[Transaction 提交]\n```\n\n资料来源：[crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n\n### 支持的源格式\n\n| 扩展名 | 源类型 | 默认分块策略 |\n|-------|--------|-------------|\n| `.md` / `.markdown` | Markdown | Paragraph |\n| `.txt` | 纯文本 | SentenceRecursive (256 tokens) |\n| `.pdf` | PDF | SentenceRecursive (512 tokens) |\n| `.json` / `.jsonl` | 会话记录 | Session (10 条消息) |\n| `.rs` / `.py` / `.js` / `.ts` 等 | 代码 | Structural |\n\n资料来源：[crates/mnem-ingest/src/pipeline.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pipeline.rs)\n\n### 分块策略详解\n\n```\n资料来源：[crates/mnem-ingest/src/chunk.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/chunk.rs)\n```\n\n| 策略 | 说明 | 适用场景 |\n|------|------|---------|\n| **Paragraph** | 按双换行分割 | Markdown 文档 |\n| **Recursive** | 词窗口滑动，固定 overlap | 通用场景（向后兼容） |\n| **SentenceRecursive** | 基于 Unicode 句子边界（UAX #29）打包 | 纯文本、PDF |\n| **Session** | 按对话轮次分组，边界在角色返回 user 时触发 | 会话记录 |\n| **Structural** | 每 section 一个 chunk | 代码（函数/类级别） |\n\n## 实体与关系提取\n\nMnem 提供了多层次的实体和关系提取能力：\n\n```\n资料来源：[crates/mnem-ingest/src/extract.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/extract.rs)\n```\n\n| 提取器 | 描述 |\n|--------|------|\n| **RuleExtractor** | 基于规则的提取，使用正则和启发式方法 |\n| **KeyBertAdapter** | 使用 KeyBERT 进行统计实体识别（需启用 `keybert` feature） |\n| **LLM Extractor** | 使用 Ollama LLM 进行提取（需启用 `ollama` feature） |\n\n### Sidecar 提取器\n\n支持外部提取服务：\n\n```toml\n# Cargo.toml\nmnem-ingest = { features = [\"sidecar-docling\"] } # 或 [\"sidecar-unstructured\"]\n```\n\n资料来源：[crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n\n## 检索系统\n\nMnem 提供了一套专为 Agent 设计的多阶段检索管道：\n\n```\n资料来源：[crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n```\n\n```mermaid\ngraph TD\n Q[用户查询] --> F[过滤阶段]\n F --> V[向量检索]\n V --> S[稀疏检索]\n S --> R[重排序]\n R --> P[Token 预算打包]\n P --> R[最终结果]\n```\n\n### 检索配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `retrieve.limit` | - | 最大返回结果数 |\n| `retrieve.budget` | - | Token 预算上限 |\n| `retrieve.vector_cap` | - | 向量检索结果数上限 |\n| `retrieve.graph_expand` | - | 图扩展节点数 |\n| `retrieve.graph_depth` | - | 图扩展深度 |\n| `retrieve.rerank_top_k` | - | 重排序候选数 |\n| `retrieve.hyde_max_tokens` | - | HyDE 最大生成 Token 数 |\n\n资料来源：[crates/mnem-cli/src/config.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/config.rs)\n\n## 版本化与分支\n\nMnem 使用 DAG 结构存储版本历史，每次提交产生一个新的 Commit 节点：\n\n```mermaid\ngraph LR\n A[Commit A] --> B[Commit B]\n B --> C[Commit C]\n C --> D[Commit D]\n B --> E[Commit E
分支]\n E --> F[Commit F]\n D --> G[Commit G]\n```\n\n| 概念 | 说明 |\n|------|------|\n| **Head** | 当前分支的最新提交 |\n| **Branch** | 通过 refs 引用的命名指针 |\n| **Merge** | 检测两个分支的冲突并合并 |\n\n资料来源：[crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n\n### 冲突检测\n\n```\n资料来源：[crates/mnem-core/src/repo/conflict.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/conflict.rs)\n```\n\nMnem 支持基于策略的合并冲突检测：\n\n| 策略 | 说明 |\n|------|------|\n| `ConflictPolicy::Default` | 标准的冲突检测 |\n| `ConflictPolicy::Manual` | 手动解决冲突 |\n\n## 密码学安全\n\n```\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n```\n\n| 组件 | 功能 |\n|------|------|\n| **Signer** | 使用 Ed25519 对 Operation 进行签名 |\n| **Verifier** | 验证签名有效性 |\n| **RevocationList** | 支持吊销列表验证 |\n\n## CLI 命令\n\n```\n资料来源：[crates/mnem-cli/src/commands/ingest.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/ingest.rs)\n```\n\n| 命令 | 功能 |\n|------|------|\n| `mnem init` | 初始化新仓库 |\n| `mnem ingest ` | 导入文档 |\n| `mnem get ` | 获取节点详情 |\n| `mnem query ` | 语义检索 |\n| `mnem branch` | 分支管理 |\n| `mnem merge` | 合并分支 |\n| `mnem integrate` | 集成到 AI 工具（Claude Code、Cursor 等） |\n\n### 常用 ingest 选项\n\n```bash\nmnem ingest notes.md # 自动检测格式\nmnem ingest --chunker recursive --max-tokens 1024 book.pdf\nmnem ingest --recursive docs/ # 递归导入目录\nmnem ingest --text \"Hello world\" # 导入纯文本\n```\n\n## HTTP API\n\n```\n资料来源：[crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n```\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/nodes` | GET | 获取节点列表 |\n| `/v1/nodes/{id}` | GET | 获取指定节点 |\n| `/v1/ingest` | POST | 导入文档 |\n| `/v1/branches` | GET | 获取分支列表 |\n| `/v1/branches` | POST | 创建分支 |\n| `/v1/retrieve` | POST | 检索 |\n\n## MCP Server\n\nMnem 提供了 MCP（Model Context Protocol）集成，支持 AI 工具直接访问知识图谱：\n\n```mermaid\ngraph LR\n A[Claude Code / Cursor] <--> B[MCP Server]\n B --> C[mnem-core]\n```\n\n资料来源：[crates/mnem-cli/src/integrate.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/integrate.rs)\n\n支持的集成平台：\n\n| 平台 | 配置文件 |\n|------|---------|\n| Claude Code | `~/.claude/CLAUDE.md` |\n| Cursor | `~/.cursor/rules/mnem.mdc` |\n| Continue | `~/.continue/config.json` |\n| Zed | `~/.config/zed/settings.json` |\n| Gemini CLI | `~/.gemini/GEMINI.md` |\n\n## 技术特性\n\n```\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n```\n\n| 特性 | 说明 |\n|------|------|\n| `#![forbid(unsafe_code)]` | 完全禁用 unsafe 代码 |\n| 规范编码 | 所有对象支持字节级精确的编解码往返 |\n| DAG-CBOR | 使用 DAG-CBOR 作为主要序列化格式 |\n| Prolly Tree | 用于高效存储和查询的 Prolly Tree 实现 |\n| Tree-sitter | 代码解析支持 10+ 主流编程语言 |\n\n## 使用示例\n\n### 初始化仓库\n\n```bash\nmnem init my-knowledge-base\ncd my-knowledge-base\n```\n\n### 导入文档\n\n```bash\n# 导入 Markdown\nmnem ingest README.md\n\n# 导入 PDF\nmnem ingest --chunker sentence_recursive document.pdf\n\n# 递归导入目录\nmnem ingest --recursive ./docs\n\n# 导入代码文件\nmnem ingest src/main.rs\n```\n\n### 检索知识\n\n```bash\nmnem query \"Mnem 的检索算法是如何工作的？\"\n```\n\n### 分支管理\n\n```bash\nmnem branch create feature-x\nmnem branch switch feature-x\n# ... 进行修改 ...\nmnem commit -m \"添加新功能\"\nmnem merge feature-x\n```\n\n## 总结\n\nMnem 是一个功能完整的本地优先知识图谱系统，特别适合需要持久化记忆的 AI Agent 场景。它通过：\n\n1. **多格式解析** - 支持 PDF、Markdown、代码、会话等\n2. **智能分块** - 针对不同内容类型优化分块策略\n3. **实体提取** - 规则、统计和 LLM 三种提取方式\n4. **版本控制** - DAG 结构支持分支和合并\n5. **可验证性** - Ed25519 签名确保数据完整性\n6. **AI 友好** - 专为 Agent 设计的检索和渲染机制\n\n为开发者提供了一个可靠、可信的知识管理基础设施。\n\n资料来源：[README.zh-CN.md](https://github.com/Uranid/mnem/blob/main/README.zh-CN.md)\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/src/install.md](https://github.com/Uranid/mnem/blob/main/docs/src/install.md)\n- [Dockerfile](https://github.com/Uranid/mnem/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/Uranid/mnem/blob/main/docker-compose.yml)\n- [scripts/install.sh](https://github.com/Uranid/mnem/blob/main/scripts/install.sh)\n- [scripts/install.ps1](https://github.com/Uranid/mnem/blob/main/scripts/install.ps1)\n \n\n# 安装指南\n\n本文档详细说明 mnem 项目的各种安装方式、依赖要求以及初始化配置流程。mnem 是一个基于 Rust 构建的知识图谱管理工具，支持 CLI、HTTP 服务和 MCP（Model Context Protocol）三种接入方式。\n\n## 系统要求\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 内存 | 4 GB | 8 GB 或以上 |\n| 磁盘空间 | 500 MB | 2 GB（用于本地数据库和向量索引） |\n| 处理器 | x86-64 | 多核处理器 |\n\n### 软件依赖\n\nmnem 的核心由 Rust 语言编写，运行时依赖以下组件：\n\n- **Rust 工具链**：建议使用最新稳定版（stable）\n- **OpenSSL**：用于 HTTPS 通信和加密操作\n- **pkg-config**：系统库链接管理\n- **protoc**：Protocol Buffers 编译器（部分功能需要）\n\n资料来源：[crates/mnem-cli/src/main.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/main.rs)\n\n## 安装方式\n\nmnem 提供多种安装途径，可根据使用场景选择合适的方式。\n\n### 方式一：从源码编译安装\n\n#### 前置准备\n\n```bash\n# 安装 Rust 工具链（如尚未安装）\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# 安装系统依赖（Ubuntu/Debian）\nsudo apt-get install -y build-essential pkg-config libssl-dev\n\n# 安装系统依赖（macOS）\nbrew install openssl pkg-config\n```\n\n#### 编译步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Uranid/mnem.git\ncd mnem\n\n# 使用 Cargo 构建所有 crate\ncargo build --release\n\n# 安装二进制文件到 ~/.cargo/bin\ncargo install --path crates/mnem-cli\n```\n\n编译完成后，可执行文件 `mnem` 将被安装到 Cargo 的 bin 目录。\n\n### 方式二：使用安装脚本\n\n项目提供了自动化安装脚本，支持 Linux、macOS 和 Windows。\n\n#### Linux / macOS\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Uranid/mnem/main/scripts/install.sh | bash\n```\n\n脚本会自动检测系统平台，下载或编译对应版本的二进制文件。\n\n#### Windows PowerShell\n\n```powershell\nirm https://raw.githubusercontent.com/Uranid/mnem/main/scripts/install.ps1 | iex\n```\n\n脚本支持 PowerShell 5.1 及以上版本，会将 `mnem.exe` 添加到 PATH 环境变量。\n\n### 方式三：Docker 部署\n\nmnem 支持通过 Docker 容器运行，包含完整的 HTTP 服务和 MCP 服务器。\n\n#### Dockerfile 结构\n\n```dockerfile\n# 使用 Rust 官方镜像作为构建阶段\nFROM rust:1.75 as builder\n\n# 安装构建依赖\nRUN apt-get update && apt-get install -y \\\n pkg-config libssl-dev\n\n# 复制源码并编译\nWORKDIR /app\nCOPY . .\nRUN cargo build --release --bin mnem-http\n\n# 运行阶段使用轻量级镜像\nFROM debian:bookworm-slim\nCOPY --from=builder /app/target/release/mnem-http /usr/local/bin/\nEXPOSE 8080\nCMD [\"mnem-http\"]\n```\n\n资料来源：[Dockerfile](https://github.com/Uranid/mnem/blob/main/Dockerfile)\n\n#### docker-compose 编排\n\n```yaml\nversion: '3.8'\n\nservices:\n mnem:\n build: .\n ports:\n - \"8080:8080\"\n volumes:\n - mnem-data:/data\n environment:\n - MNEM_DATA_DIR=/data\n - OLLAMA_BASE_URL=http://ollama:11434\n restart: unless-stopped\n\n ollama:\n image: ollama/ollama:latest\n volumes:\n - ollama-data:/root/.ollama\n restart: unless-stopped\n\nvolumes:\n mnem-data:\n ollama-data:\n```\n\n资料来源：[docker-compose.yml](https://github.com/Uranid/mnem/blob/main/docker-compose.yml)\n\n#### 启动 Docker 服务\n\n```bash\n# 构建并启动容器\ndocker-compose up -d\n\n# 查看日志\ndocker-compose logs -f mnem\n\n# 停止服务\ndocker-compose down\n```\n\n## 初始化配置\n\n首次使用 mnem 前需要进行仓库初始化和基础配置。\n\n### 仓库初始化\n\n```bash\n# 初始化新的 mnem 仓库\nmnem init\n\n# 指定自定义数据目录\nmnem init --path ~/.my-mnem\n```\n\n初始化命令会在指定目录下创建 `.mnem/` 子目录，包含以下结构：\n\n```\n.mnem/\n├── repo.redb # 主数据库（Redb 键值存储）\n├── config.toml # 用户配置文件\n└── blocks/ # DAG-CBOR 数据块存储\n```\n\n资料来源：[crates/mnem-cli/src/commands/init.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/init.rs)\n\n### 配置文件\n\n初始化后生成的 `config.toml` 包含以下配置项：\n\n```toml\n[user]\n# 用户标识（可选）\nname = \"Your Name\"\nemail = \"your@email.com\"\n\n[llm]\n# Ollama 服务配置\nbase_url = \"http://localhost:11434\"\nmodel = \"llama3.2\"\ntimeout_secs = 120\n\n[ner]\n# 命名实体识别提供者\nprovider = \"rule\" # 可选: \"none\", \"rule\"\n\n[ingest]\n# 默认分块策略\nchunker = \"auto\" # 可选: \"paragraph\", \"recursive\", \"session\", \"structural\"\n```\n\n资料来源：[crates/mnem-cli/src/config.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/config.rs)\n\n### 验证安装\n\n```bash\n# 检查 mnem 版本\nmnem --version\n\n# 查看当前仓库状态\nmnem status\n\n# 列出所有可用命令\nmnem --help\n```\n\n成功安装后，`mnem status` 应显示仓库已初始化且无待提交操作。\n\n## 接入方式\n\nmnem 提供三种主要的接入方式，可根据使用场景选择。\n\n### CLI 模式\n\n命令行模式适合日常笔记记录和知识管理：\n\n```bash\n# 添加节点\nmnem add node -s \"Alice 住在柏林\"\n\n# 添加关系\nmnem add edge --from --to --label 朋友\n\n# 检索知识\nmnem retrieve \"Alice 住在哪里\"\n```\n\n### HTTP 服务模式\n\n通过 HTTP API 提供服务，支持远程访问和程序化集成：\n\n```bash\n# 启动 HTTP 服务（默认端口 8080）\nmnem http serve\n\n# 指定端口\nmnem http serve --port 9090\n\n# 后台运行\nmnem http serve --daemon\n```\n\nAPI 端点示例：\n\n| 方法 | 端点 | 说明 |\n|------|------|------|\n| GET | `/v1/status` | 获取服务状态 |\n| POST | `/v1/nodes` | 创建节点 |\n| GET | `/v1/nodes/{id}` | 获取节点详情 |\n| POST | `/v1/ingest` | 批量导入文档 |\n\n资料来源：[crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n\n### MCP 模式\n\nMCP（Model Context Protocol）模式允许 AI 助手直接访问 mnem 知识图谱：\n\n```bash\n# 启动 MCP 服务器\nmnem mcp serve\n\n# 配置 Claude Desktop 使用 mnem MCP\n# 编辑 ~/.claude/settings.json\n```\n\n资料来源：[crates/mnem-mcp/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-mcp/src/lib.rs)\n\n## 依赖可选功能\n\nmnem 的部分功能需要额外的依赖库支持。\n\n### 文档解析依赖\n\n| 功能 | 依赖 | 启用方式 |\n|------|------|----------|\n| PDF 解析 | docling | `cargo build --features sidecar-docling` |\n| 高级解析 | unstructured | `cargo build --features sidecar-unstructured` |\n| KeyBERT 向量提取 | keybert | `cargo build --features keybert` |\n| LLM 实体提取 | ollama | `cargo build --features ollama` |\n\n资料来源：[crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n\n### 向量检索依赖\n\nmnem 的检索功能依赖嵌入模型生成向量表示，可通过以下方式配置：\n\n```toml\n[embedder]\n# 本地 Ollama 嵌入模型\nprovider = \"ollama\"\nmodel = \"nomic-embed-text\"\nbase_url = \"http://localhost:11434\"\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|源码编译| C[安装 Rust 工具链]\n B -->|安装脚本| D[下载安装脚本]\n B -->|Docker| E[安装 Docker]\n \n C --> F[克隆仓库]\n D --> G[执行安装脚本]\n E --> H[配置 docker-compose]\n \n F --> I[cargo build]\n G --> J[验证二进制]\n H --> K[docker-compose up]\n \n I --> L[初始化仓库]\n J --> L\n K --> L\n \n L --> M[配置 config.toml]\n M --> N{选择接入模式}\n \n N -->|CLI| O[使用 mnem 命令]\n N -->|HTTP| P[启动 http serve]\n N -->|MCP| Q[启动 mcp serve]\n \n O --> R[安装完成]\n P --> R\n Q --> R\n```\n\n## 卸载\n\n### 二进制安装卸载\n\n```bash\n# 删除二进制文件\nrm ~/.cargo/bin/mnem\n\n# 删除配置文件（可选）\nrm -rf ~/.config/mnem\n```\n\n### Docker 卸载\n\n```bash\n# 停止并删除容器\ndocker-compose down -v\n\n# 删除镜像\ndocker rmi mnem-mnem-http\n\n# 删除数据卷\ndocker volume rm mnem_mnem-data\n```\n\n## 常见问题\n\n### 编译失败\n\n如果编译时出现 OpenSSL 相关错误，确保已安装开发库：\n\n```bash\n# Ubuntu/Debian\nsudo apt install libssl-dev\n\n# macOS\nbrew install openssl@3\n```\n\n### 权限问题\n\nLinux/macOS 上如遇到权限错误：\n\n```bash\n# 修复 Cargo bin 目录权限\nchmod +x ~/.cargo/bin/mnem\n```\n\n### 数据库损坏\n\n如遇数据库异常，可尝试重建：\n\n```bash\n# 备份现有数据\nmv ~/.mnem ~/.mnem.bak\n\n# 重新初始化\nmnem init\n```\n\n## 下一步\n\n安装完成后，建议按以下顺序开始使用：\n\n1. 阅读[快速开始指南](./quickstart.md)了解基本操作\n2. 查看[命令参考](./commands.md)获取完整命令列表\n3. 参考[配置文档](./config.md)深入定制功能\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[Crates结构详解](#page-crates-structure), [知识图谱模型](#page-knowledge-graph), [存储后端](#page-storage-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n- [crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n- [crates/mnem-ingest/src/pipeline.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pipeline.rs)\n- [crates/mnem-ingest/src/types.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/types.rs)\n- [crates/mnem-core/src/id/link.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/link.rs)\n \n\n# 系统架构\n\nmnem 是一个基于 Rust 构建的本地优先知识图谱系统，采用内容寻址存储（Content-Addressed Storage）架构，通过 DAG-CBOR 规范实现数据的规范化编解码。该系统支持多端接入，包括命令行界面（CLI）、HTTP API 和 MCP（Model Context Protocol）协议，能够对 Markdown、PDF、代码文件、对话记录等多种格式的文档进行解析、分块、实体提取和语义检索。\n\n## 核心设计原则\n\nmnem 的核心架构遵循以下设计原则，这些原则贯穿整个系统的实现：\n\n1. **无 unsafe 代码**：mnem-core crate 明确禁用所有 unsafe 代码，确保内存安全 资料来源：[crates/mnem-core/src/lib.rs]()`。\n2. **字节级精确编解码**：每个对象类型都保证字节级精确的规范化编码往返特性，即 `decode(encode(x)) == x` 且 `encode(decode(b)) == b` 资料来源：[crates/mnem-core/src/lib.rs]()`。\n3. **幽灵类型安全**：`Link` 通过泛型参数在编译时防止引用类型混淆，例如 `fn parents(&self) -> &[Link]` 拒绝接受 `Link` 资料来源：[crates/mnem-core/src/id/link.rs]()`。\n4. **多端统一解析**：单一规范的解析器实现同时服务于 CLI、HTTP 和 MCP 接入面 资料来源：[crates/mnem-ingest/src/lib.rs]()`。\n\n## 系统分层架构\n\nmnem 系统采用分层架构，各层职责明确，从底层数据存储到顶层用户接口逐层构建。\n\n```mermaid\ngraph TD\n subgraph 用户接入层\n CLI[mnem-cli
命令行工具]\n HTTP[mnem-http
HTTP API]\n MCP[mnem-mcp
MCP Server]\n end\n \n subgraph 核心库层\n CORE[mnem-core
核心数据模型]\n INGEST[mnem-ingest
文档解析与提取]\n end\n \n subgraph 存储层\n STORE[Blockstore
块存储接口]\n VIEW[View
视图快照]\n COMMITS[Commit
提交历史]\n end\n \n CLI --> CORE\n CLI --> INGEST\n HTTP --> CORE\n HTTP --> INGEST\n MCP --> CORE\n MCP --> INGEST\n INGEST --> CORE\n CORE --> STORE\n CORE --> COMMITS\n```\n\n### mnem-core 核心库\n\nmnem-core 是系统的基础核心库，提供所有核心数据结构和算法实现。该库包含以下关键模块 资料来源：[crates/mnem-core/src/lib.rs]()`：\n\n| 模块 | 功能描述 |\n|------|----------|\n| `id` | CID（内容标识符）、ChangeId、OperationId 以及泛型链接类型 Link |\n| `codec` | DAG-CBOR 编解码器和 DAG-JSON 调试导出 |\n| `objects` | Node、Edge、Commit、Operation、View、IndexSet 等核心对象类型 |\n| `prolly` | Prolly 树算法（分块器、构建器、查找、光标、diff、合并） |\n| `store` | Blockstore 和 OpHeadsStore trait 及内存实现 |\n| `repo` | ReadonlyRepo、Transaction 外观类 |\n| `index` | 辅助索引（Query、BruteForceVectorIndex） |\n| `retrieve` | Agent 面向的 Retriever，组合过滤、向量和稀疏排序 |\n| `sign` | Ed25519 签名和撤销列表验证 |\n\n### mnem-ingest 文档解析库\n\nmnem-ingest 负责文档的解析、分块和实体提取工作。该库支持多种文档格式的分阶段处理 资料来源：[crates/mnem-ingest/src/lib.rs]()`：\n\n| 模块 | 功能 |\n|------|------|\n| `md` | CommonMark + GFM Markdown 解析 |\n| `pdf` | 纯 Rust 实现的 PDF 文本层提取 |\n| `code` | 基于 tree-sitter 的代码解析 |\n| `conversation` | ChatGPT/Claude/通用对话导出格式处理 |\n| `text` | 纯文本处理 |\n| `chunk` | 分块策略（Paragraph、Recursive、SentenceRecursive、Session、Structural） |\n| `extract` | 实体和关系提取（RuleExtractor、KeyBertAdapter、LLMExtractor） |\n| `sidecar` | 外部工具集成（docling、unstructured） |\n\n### 用户接入层\n\n系统提供三种主要的用户接入方式：\n\n- **mnem-cli**：命令行工具，支持本地文件的批量导入、检索和图谱管理\n- **mnem-http**：基于 Actix-web 构建的 HTTP API 服务端\n- **mnem-mcp**：Model Context Protocol 服务端，供 AI 代理调用\n\n## 数据模型\n\nmnem 采用 DAG（有向无环图）结构存储知识图谱，核心对象之间通过 CID（内容标识符）相互引用。\n\n### 节点（Node）\n\nNode 是图谱中的基本顶点单元，包含以下关键字段 资料来源：[crates/mnem-core/src/objects/node.rs]()`：\n\n```mermaid\nclassDiagram\n class Node {\n +id: NodeId\n +ntype: String\n +parents: Vec~Link~Commit~~\n +context_sentence: Option~String~\n +summary: Option~String~\n +props: BTreeMap~String, Ipld~\n +content: Option~Bytes~\n +extra: BTreeMap~String, Ipld~\n }\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | NodeId | 节点唯一标识符 |\n| `ntype` | String | 节点类型标签（如 \"Doc\"、\"Section\" 等） |\n| `parents` | Vec> | 父提交链接 |\n| `context_sentence` | Option | 上下文句子（Anthropic 2024 contextual retrieval 设计） |\n| `summary` | Option | LLM 可读的摘要文本，默认截断至 8192 字符 |\n| `props` | BTreeMap | 结构化属性键值对 |\n| `content` | Option | 不透明载荷（如文档体、文件内容） |\n\n### 链接类型（Link）\n\nLink 是一个泛型封装的 CID，提供编译时类型安全保证。在传输层 Link 与普通 CID 字节相同，但泛型参数在 Rust 类型层面防止了错误的引用操作 资料来源：[crates/mnem-core/src/id/link.rs]()`。\n\n### 提交（Commit）与操作（Operation）\n\nCommit 记录图谱的快照状态，Operation 记录具体的变更操作，两者共同构成版本控制的基础。\n\n## 文档解析流程\n\n当用户通过 CLI、HTTP 或 MCP 接入系统进行文档导入时，系统内部执行以下处理流程 资料来源：[crates/mnem-ingest/src/pipeline.rs]()`：\n\n```mermaid\nflowchart LR\n A[原始文件] --> B{文件扩展名检测}\n B -->|md/markdown| C[Markdown解析器]\n B -->|pdf| D[PDF解析器]\n B -->|json/jsonl| E[对话解析器]\n B -->|rs/py/js/ts...| F[Tree-sitter代码解析]\n B -->|其他| G[纯文本解析器]\n \n C --> H{分块策略选择}\n D --> H\n E --> H\n F --> H\n G --> H\n \n H -->|Markdown| I[Paragraph分块]\n H -->|PDF/Text| J[SentenceRecursive分块]\n H -->|Conversation| K[Session分块]\n H -->|Code| L[Structural分块]\n \n I --> M[实体提取]\n J --> M\n K --> M\n L --> M\n \n M --> N[Transaction写入]\n N --> O[Commit提交]\n```\n\n### 源类型自动检测\n\n系统根据文件扩展名自动推断源类型（SourceKind） 资料来源：[crates/mnem-ingest/src/types.rs]()`：\n\n| 扩展名 | SourceKind | 分块策略 |\n|--------|------------|----------|\n| `.md` `.markdown` | Markdown | Paragraph |\n| `.pdf` | Pdf | SentenceRecursive (512 tokens, 64 overlap) |\n| `.txt` | Text | SentenceRecursive (256 tokens, 32 overlap) |\n| `.json` `.jsonl` | Conversation | Session (10 messages) |\n| `.rs` | Code(Rust) | Structural |\n| `.py` `.pyi` | Code(Python) | Structural |\n| `.js` `.mjs` `.cjs` | Code(JavaScript) | Structural |\n| `.ts` `.tsx` | Code(TypeScript) | Structural |\n| `.go` | Code(Go) | Structural |\n| `.java` | Code(Java) | Structural |\n| `.c` `.h` | Code(C) | Structural |\n| `.cpp` `.cc` `.cxx` | Code(Cpp) | Structural |\n| 其他 | Text | SentenceRecursive |\n\n### 分块策略详解\n\n系统提供五种分块策略，适用于不同类型的文档内容 资料来源：[crates/mnem-ingest/src/chunk.rs]()`：\n\n- **Paragraph（段落分块）**：适用于 Markdown 文档，按段落边界切分\n- **Recursive（递归分块）**：按最大 token 数递归拆分，可配置重叠\n- **SentenceRecursive（句子递归分块）**：先按句子边界对齐，再按 token 限制拆分，适合 PDF 和纯文本\n- **Session（会话分块）**：保留消息对话结构，按最大消息数切分\n- **Structural（结构分块）**：利用 AST 解析提取函数、类、结构体等代码单元\n\n## 存储架构\n\nmnem 采用内容寻址存储，所有数据通过 CID 唯一标识。存储层提供两个核心 trait 接口：\n\n### Blockstore Trait\n\nBlockstore 是底层内容存储接口，负责键值对形式的数据读写。系统支持多种后端实现，包括内存实现（用于测试）和持久化实现。\n\n### OpHeadsStore Trait\n\nOpHeadsStore 管理操作头的集合，用于追踪当前工作区的最新状态。\n\n### View 与 Commit\n\n- **View**：视图快照，包含 refs（引用表）和 heads（头提交集）\n- **Commit**：提交记录，指向操作链和视图\n\n```mermaid\ngraph LR\n A[Operation] -->|prev| B[Operation]\n B -->|prev| C[Operation]\n \n D[Commit] -->|ops| A\n D -->|view| E[View]\n \n F[View] -->|heads| G[\"Vec\"]\n F -->|refs| H[\"BTreeMap\"]\n```\n\n## 检索流程\n\n检索（Retrieve）模块负责根据用户查询从图谱中召回最相关的节点 资料来源：[crates/mnem-core/src/retrieve/mod.rs]()`：\n\n1. **过滤阶段**：根据查询条件筛选候选节点\n2. **向量排序**：使用嵌入向量计算语义相似度\n3. **稀疏排序**：BM25 等稀疏检索方法辅助排序\n4. **重排序**：可选的重排序模型优化结果顺序\n5. **Token 预算打包**：将结果打包至 LLM 上下文预算内\n\n检索模块实现了 Anthropic 2024 年提出的 Contextual Retrieval 技术，通过在节点上存储 `context_sentence` 字段（上下文句子）来增强检索效果，该字段在嵌入前被添加到 summary 前缀中 资料来源：[crates/mnem-core/src/objects/node.rs]()`。\n\n## 特性门控\n\n部分功能通过 Cargo feature 进行条件编译控制 资料来源：[crates/mnem-ingest/src/lib.rs]()`：\n\n| Feature | 功能 |\n|---------|------|\n| `keybert` | KeyBERT 统计嵌入器适配器 |\n| `ollama` | Ollama LLM 提取器 |\n| `sidecar-docling` | Docling CLI PDF 解析集成 |\n| `sidecar-unstructured` | Unstructured.io 解析集成 |\n\n## 总结\n\nmnem 的系统架构体现了现代本地优先应用的设计理念：通过内容寻址确保数据的不可变性和可验证性，采用分层模块化设计支持多种接入方式，利用 DAG 结构自然地表达知识图谱的复杂关系。核心库的纯 Rust 实现保证了类型安全和跨平台兼容性，而丰富的文档解析和分块策略则满足了多样化的知识管理需求。\n\n---\n\n\n\n## Crates结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [Cargo.toml](https://github.com/Uranid/mnem/blob/main/Cargo.toml)\n- [crates/mnem-core/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/Cargo.toml)\n- [crates/mnem-cli/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/Cargo.toml)\n- [crates/mnem-ingest/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/Cargo.toml)\n- [crates/mnem-http/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/Cargo.toml)\n- [crates/mnem-mcp/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-mcp/Cargo.toml)\n \n\n# Crates结构详解\n\n## 概述\n\nmnem 是一个基于 Rust 构建的语义记忆系统，采用 IPLD (InterPlanetary Linked Data) 数据模型和 DAG-CBOR 编解码实现内容寻址存储。项目采用工作区 (workspace) 结构，包含多个独立的 crate，每个 crate 负责特定的功能领域。\n\n```mermaid\ngraph TD\n subgraph mnem工作区\n CLI[mnem-cli]\n HTTP[mnem-http]\n MCP[mnem-mcp]\n CORE[mnem-core]\n INGEST[mnem-ingest]\n end\n \n CLI --> CORE\n HTTP --> CORE\n MCP --> CORE\n INGEST --> CORE\n \n CLI --> INGEST\n HTTP --> INGEST\n MCP --> INGEST\n```\n\n## 核心 Crate 架构\n\n### 项目依赖关系总览\n\n| Crate 名称 | 依赖关系 | 主要功能 |\n|------------|----------|----------|\n| `mnem-core` | 无内部依赖 | 核心数据模型、存储、检索 |\n| `mnem-ingest` | 依赖 `mnem-core` | 数据解析、分块、实体提取 |\n| `mnem-cli` | 依赖 `mnem-core`, `mnem-ingest` | 命令行工具 |\n| `mnem-http` | 依赖 `mnem-core`, `mnem-ingest` | HTTP API 服务 |\n| `mnem-mcp` | 依赖 `mnem-core` | MCP 协议集成 |\n\n## mnem-core 核心库\n\n### 定位与职责\n\n`mnem-core` 是整个项目的核心基础设施库，提供底层数据模型、存储抽象和检索能力。该库完全禁止使用 `unsafe` 代码 (`#![forbid(unsafe_code)]`)，确保内存安全。\n\n### 核心模块\n\n```rust\n资料来源：[crates/mnem-core/src/lib.rs](crates/mnem-core/src/lib.rs)\n\npub mod id; // 内容标识符\npub mod codec; // DAG-CBOR 编解码\npub mod objects; // 核心对象类型\npub mod prolly; // Prolly tree 算法\npub mod store; // 存储抽象\npub mod repo; // 仓库事务\npub mod index; // 索引实现\npub mod retrieve; // 检索器\npub mod sign; // 签名验证\n```\n\n### 核心对象类型\n\n资料来源：[crates/mnem-core/src/objects/node.rs](crates/mnem-core/src/objects/node.rs)\n\n| 类型 | 说明 |\n|------|------|\n| `Node` | 核心节点类型，包含摘要、属性、内容和上下文句子 |\n| `Edge` | 节点间的边关系 |\n| `Commit` | 提交记录 |\n| `Operation` | 操作记录 |\n| `View` | 视图快照 |\n| `IndexSet` | 索引集合 |\n\n### ID 系统\n\n资料来源：[crates/mnem-core/src/id/link.rs](crates/mnem-core/src/id/link.rs)\n\n```rust\npub struct Link {\n cid: Cid,\n _target: PhantomData T>,\n}\n```\n\n`Link` 是类型化内容引用，基于 CID 但增加了类型安全保证：\n\n- 编译时类型检查防止引用混淆\n- `Link`、`Link` 等泛型参数确保语义正确\n- 序列化格式与裸 CID 完全兼容\n\n### 检索模块\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs](crates/mnem-core/src/retrieve/mod.rs)\n\n检索模块负责将节点渲染为 LLM 可消费的文本格式，采用 YAML-like 格式：\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n```\n\n渲染规则：\n- `ntype` 和 `id` 始终存在\n- `context` 在 `summary` 之前输出（遵循 Anthropic 2024 contextual-retrieval 配方）\n- `summary` 默认截断至 8192 字符，可通过 `MNEM_RENDER_SUMMARY_CAP_CHARS` 环境变量配置\n- 标量属性按字母序输出，复杂属性（Link、Map、List）跳过\n\n## mnem-ingest 数据摄取库\n\n### 定位与职责\n\n`mnem-ingest` 负责将各种格式的源数据（Markdown、PDF、代码、会话等）解析、分块并提取实体关系。\n\n### 模块架构\n\n```mermaid\ngraph LR\n subgraph 解析器\n MD[Markdown]\n PDF[PDF]\n CODE[Code]\n CONV[Conversation]\n TEXT[Text]\n end\n \n subgraph 分块器\n PARA[Paragraph]\n REC[Recursive]\n SENT[SentenceRecursive]\n SESS[Session]\n STRUC[Structural]\n end\n \n subgraph 提取器\n RULE[RuleExtractor]\n KEYBERT[KeyBertAdapter]\n LLM[LLMExtractor]\n end\n \n MD & PDF & CODE & CONV & TEXT --> PARA & REC & SENT & SESS & STRUC\n PARA & REC & SENT & SESS & STRUC --> RULE & KEYBERT & LLM\n```\n\n### 支持的源类型\n\n资料来源：[crates/mnem-ingest/src/types.rs](crates/mnem-ingest/src/types.rs)\n\n| 源类型 | 文件扩展名 | 默认分块策略 |\n|--------|------------|--------------|\n| `Markdown` | `.md`, `.markdown` | Paragraph |\n| `Pdf` | `.pdf` | SentenceRecursive (512 tokens, 64 overlap) |\n| `Text` | 其他无扩展名文件 | SentenceRecursive (256 tokens, 32 overlap) |\n| `Conversation` | `.json`, `.jsonl` | Session (10 messages) |\n| `Code(lang)` | 各类代码文件 | Structural |\n\n### 分块策略详解\n\n资料来源：[crates/mnem-ingest/src/chunk.rs](crates/mnem-ingest/src/chunk.rs)\n\n```rust\npub enum ChunkerKind {\n Paragraph, // 段落级别\n Recursive { max_tokens, overlap },\n SentenceRecursive { max_tokens, overlap },\n Session { max_messages }, // 会话消息分组\n Structural, // 代码结构（函数/类等）\n}\n```\n\n| 策略 | 适用场景 | 关键参数 |\n|------|----------|----------|\n| `Paragraph` | Markdown 文档 | 无 |\n| `Recursive` | 通用文本递归切分 | `max_tokens`, `overlap` |\n| `SentenceRecursive` | 句子边界感知的递归切分 | `max_tokens`, `overlap` |\n| `Session` | 对话/聊天记录 | `max_messages` |\n| `Structural` | 源代码结构解析 | 无 |\n\n### 代码语言支持\n\n资料来源：[crates/mnem-ingest/src/code.rs](crates/mnem-ingest/src/code.rs)\n\n| 语言 | 扩展名 | Tree-sitter 提取项 |\n|------|--------|-------------------|\n| Rust | `.rs` | function_item, struct_item, enum_item, trait_item |\n| Python | `.py`, `.pyi` | function_definition, class_definition |\n| JavaScript | `.js`, `.mjs`, `.cjs` | function_declaration, class_declaration |\n| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | function_declaration, class_declaration |\n| Go | `.go` | function_declaration, type_declaration |\n| Java | `.java` | method_declaration, class_declaration |\n| C | `.c`, `.h` | function_definition, struct_specifier |\n| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | function_definition, class_specifier |\n| Ruby | `.rb`, `.gemspec`, `.rake` | method_definition, class_module |\n| C# | `.cs`, `.csx` | method_declaration, class_declaration |\n\n### 提取器\n\n资料来源：[crates/mnem-ingest/src/lib.rs](crates/mnem-ingest/src/lib.rs)\n\n```rust\npub mod extract; // 规则提取器\n#[cfg(feature = \"keybert\")]\npub mod extract_keybert; // KeyBERT 统计适配器\n#[cfg(feature = \"ollama\")]\npub mod extract_llm; // LLM 驱动提取器\n```\n\n提取器特性矩阵：\n\n| 提取器 | Feature Flag | 依赖 |\n|--------|--------------|------|\n| `RuleExtractor` | 默认启用 | 无 |\n| `KeyBertAdapter` | `keybert` | embedding 模型 |\n| `LLMExtractor` | `ollama` | Ollama 服务 |\n\n### Sidecar 集成\n\n资料来源：[crates/mnem-ingest/src/sidecar.rs](crates/mnem-ingest/src/sidecar.rs)\n\n提供高级 PDF 解析的后备方案：\n\n| Sidecar | Feature Flag | 说明 |\n|---------|--------------|------|\n| `DoclingSidecar` | `sidecar-docling` | 调用 docling CLI |\n| `UnstructuredSidecar` | `sidecar-unstructured` | 调用 unstructured-ingest CLI |\n\nSidecar 仅在纯 Rust 解析（`parse_pdf`）结果质量不足时使用，需手动配置触发。\n\n## mnem-cli 命令行工具\n\n### 定位与职责\n\n`mnem-cli` 是项目的命令行客户端，提供用户交互接口和配置管理。\n\n### 主要命令\n\n#### ingest 命令\n\n资料来源：[crates/mnem-cli/src/commands/ingest.rs](crates/mnem-cli/src/commands/ingest.rs)\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--chunker` | `auto` | 分块策略：auto, session, paragraph, recursive, sentence_recursive, structural |\n| `--max-tokens` | 512 | 目标分块大小（token） |\n| `--overlap` | 32 | 相邻分块重叠 token 数 |\n| `--recursive` | false | 递归遍历目录 |\n| `--text` | - | 直接摄取内联文本 |\n| `--ntype` | `Doc` | 根节点类型标签 |\n\n### 配置系统\n\n资料来源：[crates/mnem-cli/src/config.rs](crates/mnem-cli/src/config.rs)\n\n配置项分层：\n\n```text\n[user]\n name, email, agent_id\n\n[llm]\n provider: openai | ollama\n model\n api_key_env\n base_url\n timeout_secs\n\n[rerank]\n model, api_key_env, base_url\n\n[ner]\n provider: rule | none\n\n[retrieve]\n limit, budget, vector_cap\n graph_expand, graph_decay, graph_depth\n rerank_top_k, hyde_max_tokens\n```\n\n### Agent 集成\n\n资料来源：[crates/mnem-cli/src/integrate.rs](crates/mnem-cli/src/integrate.rs)\n\n支持将 mnem 系统提示集成到多种 AI 开发工具：\n\n| 主机 | 路径 | 存储格式 |\n|------|------|----------|\n| ClaudeCode | `~/.claude/CLAUDE.md` | Markdown |\n| GeminiCli | `~/.gemini/GEMINI.md` | Markdown |\n| Cursor | `~/.cursor/rules/mnem.mdc` | Markdown |\n| Continue | `~/.continue/config.json` | JSON (systemMessage) |\n| Zed | `settings.json` | JSON (assistant.system_prompt) |\n\n## mnem-http HTTP 服务\n\n### 定位与职责\n\n`mnem-http` 提供 RESTful HTTP API，支持外部服务集成。\n\n### 主要端点\n\n资料来源：[crates/mnem-http/src/handlers.rs](crates/mnem-http/src/handlers.rs)\n\n#### 分支管理\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| GET | `/v1/branches` | 列出所有分支 |\n| POST | `/v1/branches` | 创建新分支 |\n\n响应格式示例：\n\n```json\n{\n \"schema\": \"mnem.v1.branches\",\n \"branches\": [\n {\"name\": \"main\", \"head\": \"\", \"is_current\": true}\n ]\n}\n```\n\n### 摄取接口\n\n资料来源：[crates/mnem-http/src/handlers_ingest.rs](crates/mnem-http/src/handlers_ingest.rs)\n\n| 参数 | 说明 |\n|------|------|\n| `chunker` | 分块策略 (auto, paragraph, recursive, session) |\n| `max_tokens` | 目标 token 数 |\n| `overlap` | 重叠 token 数 |\n| `author` | 提交作者（必需） |\n| `message` | 提交消息 |\n| `extractor` | 提取器选择 (none, keybert) |\n| `ner_provider` | NER 提供者 (rule, none) |\n\n## mnem-mcp MCP 协议集成\n\n`mnem-mcp` 提供 Model Context Protocol 协议支持，使 mnem 可作为 AI 代理的记忆后端。详情待补充。\n\n## 版本与特性矩阵\n\n| Crate | 最小 Rust 版本 | 关键依赖 |\n|-------|---------------|----------|\n| mnem-core | 1.75+ | serde, cid, dag-cbor, tokio |\n| mnem-ingest | 1.75+ | tree-sitter-*, pdf-extract |\n| mnem-cli | 1.75+ | clap, anyhow, dirs |\n| mnem-http | 1.75+ | axum, tower, tokio |\n| mnem-mcp | 1.75+ | sse, tokio |\n\n## 总结\n\nmnem 项目采用清晰的模块化架构：\n\n- **mnem-core** 提供不可变的 DAG-CBOR 数据模型和检索基础设施\n- **mnem-ingest** 负责多格式数据的多策略分块与实体提取\n- **mnem-cli/http/mcp** 提供多渠道访问接口\n\n各 crate 通过严谨的类型系统和内容寻址确保数据一致性和可验证性，完全禁用 `unsafe` 代码保证了内存安全。\n\n---\n\n\n\n## 知识图谱模型\n\n### 相关页面\n\n相关主题：[版本控制机制](#page-version-control), [内容寻址系统](#page-content-addressing), [存储后端](#page-storage-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n- [crates/mnem-core/src/objects/edge.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/edge.rs)\n- [crates/mnem-core/src/objects/commit.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/commit.rs)\n- [crates/mnem-core/src/objects/tombstone.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/tombstone.rs)\n- [crates/mnem-core/src/index/adjacency.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/index/adjacency.rs)\n- [crates/mnem-core/src/id/link.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/link.rs)\n- [crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n- [crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n \n\n# 知识图谱模型\n\n## 概述\n\nmnem 的知识图谱模型是一个基于内容寻址（Content-Addressing）的图数据库核心，它采用 IPLD（InterPlanetary Linked Data）规范来组织和管理数据。该模型的核心设计理念是：\n\n- **不可变性优先**：所有对象一旦写入便不可更改，通过新建版本实现更新\n- **类型安全的链接**：使用 `Link` 泛型确保编译期类型检查\n- **DAG 结构**：节点和边构成有向无环图（DAG），支持高效遍历和查询\n- **确定性编码**：所有对象支持 DAG-CBOR 规范下的字节级精确编解码往返\n\n资料来源：[crates/mnem-core/src/lib.rs:1-50]()\n\n## 核心对象类型\n\n### 节点（Node）\n\n节点是知识图谱的基本存储单元，用于表示文档、文本块、实体等各类知识条目。\n\n```mermaid\nclassDiagram\n class Node {\n +NodeId id\n +NodeType ntype\n +Option~String~ name\n +Option~String~ summary\n +BTreeMap~String, Ipld~ props\n +Option~Bytes~ content\n +Option~String~ context_sentence\n +BTreeMap~String, Ipld~ ext\n }\n```\n\n**关键字段说明**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `NodeId` | 节点的唯一标识符（UUID） |\n| `ntype` | `NodeType` | 节点类型（如 `Doc`、`Chunk`、`Entity` 等） |\n| `name` | `Option` | 节点的友好名称 |\n| `summary` | `Option` | 摘要文本，供 LLM 消费使用 |\n| `props` | `BTreeMap` | 属性映射表，值为任意 DAG-CBOR 兼容类型 |\n| `content` | `Option` | 可选的不透明载荷（如文档正文、文件内容） |\n| `context_sentence` | `Option` | 上下文前缀句（Anthropic 2024 Contextual Retrieval 论文应用） |\n\n**属性设计原则**：\n\n- 标量属性（`String`、`Integer`、`Float`、`Bool`）按 BTreeMap 顺序（字母序）输出\n- 非标量属性（`Link`、`Map`、`List`、`Bytes`、`Null`）在渲染时被跳过，避免占用 token 预算\n- `summary` 字段默认截断至 8192 字符，可通过 `MNEM_RENDER_SUMMARY_CAP_CHARS` 环境变量覆盖\n\n资料来源：[crates/mnem-core/src/objects/node.rs:1-150]()\n\n### 边（Edge）\n\n边表示节点之间的有向关系，是知识图谱关联结构的载体。\n\n```mermaid\nclassDiagram\n class Edge {\n +EdgeId id\n +Link~Node~ src\n +Link~Node~ dst\n +String label\n +Option~Ipld~ props\n }\n```\n\n**关键特性**：\n\n| 特性 | 说明 |\n|------|------|\n| 类型安全 | `src` 和 `dst` 均为 `Link` 类型，编译期确保指向节点 |\n| 关系标签 | `label` 字段描述关系类型（如 `knows`、`authored`、`part_of`） |\n| 属性扩展 | `props` 可选地附加关系级别的元数据 |\n\n**图遍历语义**：\n\n- 边是单向的：从 `src` 指向 `dst`\n- 支持按标签过滤遍历\n- 支持按源节点或目标节点建立索引\n\n资料来源：[crates/mnem-core/src/objects/edge.rs:1-80]()\n\n### 提交（Commit）\n\nCommit 记录图谱的原子变更快照，包含一次或多次操作的集合。\n\n```mermaid\nclassDiagram\n class Commit {\n +ChangeId change_id\n +OperationId operation_id\n +Link~Commit~ parent\n +Author author\n +Timestamp timestamp\n +String message\n +Vec~Operation~ operations\n }\n```\n\n**变更原子性**：\n\n- 每个 Commit 包含完整的 `operations` 向量\n- 操作类型包括：`AddNode`、`AddEdge`、`UpdateNode`、`DeleteNode`、`DeleteEdge`\n- 支持批量原子提交，确保要么全部成功，要么全部回滚\n\n**操作类型**：\n\n| 操作类型 | 说明 |\n|----------|------|\n| `AddNode` | 向图中添加新节点 |\n| `AddEdge` | 在两节点间建立关系 |\n| `UpdateNode` | 更新现有节点的属性（通过 Replace 实现） |\n| `DeleteNode` | 删除节点（软删除，生成 Tombstone） |\n| `DeleteEdge` | 删除边关系 |\n\n资料来源：[crates/mnem-core/src/objects/commit.rs:1-120]()\n\n### 墓碑（Tombstone）\n\nTombstone 是已删除节点的占位符，用于在内容寻址结构中维护图的完整性。\n\n```mermaid\nclassDiagram\n class Tombstone {\n +NodeId id\n +Timestamp deleted_at\n +Option~Author~ deleted_by\n }\n```\n\n**设计目的**：\n\n- 在 IPLD 内容寻址系统中，被删除内容的 CID 仍然可能存在于历史记录或其他节点引用中\n- Tombstone 确保遍历时不会因缺失内容而失败\n- 支持后续的垃圾回收机制识别可清理的孤立对象\n\n资料来源：[crates/mnem-core/src/objects/tombstone.rs:1-60]()\n\n## 链接系统（Link）\n\n### Link 泛型类型\n\n`Link` 是 mnem 的类型安全内容引用封装。\n\n```mermaid\nclassDiagram\n class Link~T~ {\n -Cid cid\n -PhantomData _target\n }\n Link ..> Cid : contains\n```\n\n**核心特性**：\n\n| 特性 | 说明 |\n|------|------|\n| phantom type | 泛型参数 `T` 在运行时不占空间，仅用于编译期类型检查 |\n| CID 等价 | 底层存储与裸 `Cid` 完全相同（相同字节、相同 CBOR 标签） |\n| 编译期安全 | `fn parents(&self) -> &[Link]` 会在传入 `Link` 时编译失败 |\n\n**使用示例**：\n\n```rust\n// 正确的用法：编译通过\nlet commit_link: Link = Link::new(cid);\nfn get_parents(link: &Link) -> &[Link] { ... }\n\n// 错误的用法：编译失败\nlet node_link: Link = Link::new(cid);\nget_parents(&node_link); // 编译错误：类型不匹配\n```\n\n资料来源：[crates/mnem-core/src/id/link.rs:1-80]()\n\n## 索引系统\n\n### 邻接表索引（Adjacency Index）\n\n邻接表是图遍历的核心数据结构，支持高效的关系查询。\n\n```mermaid\ngraph TD\n A[Node A] -->|knows| B[Node B]\n A -->|authored| C[Node C]\n B -->|knows| D[Node D]\n B -->|part_of| A\n C -->|part_of| A\n \n E[Adjacency Index] -->|out_edges| F[HashMap>]\n E -->|in_edges| G[HashMap>]\n```\n\n**索引结构**：\n\n| 索引方向 | 用途 |\n|----------|------|\n| 出边索引 (`out_edges`) | 给定节点，快速获取其所有出向关系 |\n| 入边索引 (`in_edges`) | 给定节点，快速获取指向它的所有关系 |\n\n**查询能力**：\n\n- 按源节点查询所有出边\n- 按目标节点查询所有入边\n- 按边标签过滤\n- 支持多跳路径查询（通过组合调用实现）\n\n资料来源：[crates/mnem-core/src/index/adjacency.rs:1-100]()\n\n## 数据流与操作语义\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Transaction\n participant Operation\n participant Commit\n participant Blockstore\n \n Client->>Transaction: begin()\n Client->>Transaction: add_node(node)\n Transaction->>Operation: Create AddNode operation\n Client->>Transaction: add_edge(src, dst, label)\n Transaction->>Operation: Create AddEdge operation\n Client->>Transaction: commit(author, message)\n Transaction->>Operation: Finalize operations\n Transaction->>Commit: Create Commit with operations\n Commit->>Blockstore: Store Commit (CID)\n Transaction->>Blockstore: Store Node/Edge objects\n Blockstore-->>Commit: Store CIDs\n Commit-->>Transaction: Commit CID\n Transaction-->>Client: ReadonlyRepo\n```\n\n### 图遍历流程\n\n```mermaid\ngraph LR\n A[输入: 起始节点] --> B[查询邻接表出边]\n B --> C{边过滤条件}\n C -->|无过滤| D[返回所有相邻节点]\n C -->|按标签| E[返回匹配标签的节点]\n D --> F[可迭代结果集]\n E --> F\n F --> G[继续遍历下一跳]\n```\n\n## 检索与渲染\n\n### LLM 友好的节点渲染\n\n检索系统在将节点返回给 LLM 使用前，会将节点渲染为确定性的文本表示。\n\n**渲染格式**：\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n...\n```\n\n**渲染规则**：\n\n| 字段 | 存在条件 | 位置 |\n|------|----------|------|\n| `ntype` | 始终 | 第1行 |\n| `id` | 始终 | 第2行 |\n| `context` | `context_sentence` 非空时 | `summary` 之前 |\n| `summary` | `summary` 非空时 | 第3或4行 |\n| 属性 | 仅标量属性 | `summary` 之后 |\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs:1-100]()\n\n## 节点类型枚举\n\n| 节点类型 | 说明 | 典型属性 |\n|----------|------|----------|\n| `Doc` | 文档节点 | `mnem:source_kind`、`title`、`mime_type` |\n| `Chunk` | 文本块节点 | `section_path`、`tokens_estimate` |\n| `Entity` | 实体节点 | NER 提取的实体 |\n| `Conversation` | 对话会话节点 | 消息序列 |\n| `Ref` | 引用/指针节点 | 指向其他节点的 Link |\n\n## 约束与不变量\n\n**核心约束**：\n\n1. `#![forbid(unsafe_code)]` - mnem-core 禁止使用 `unsafe` 代码\n2. **字节级精确编解码**：每个对象类型必须满足 `decode(encode(x)) == x` 和 `encode(decode(b)) == b`\n3. **不可变性**：已有对象不可原地修改，只能创建新版本\n4. **类型化链接**：所有节点间引用必须通过 `Link` 类型化\n\n资料来源：[crates/mnem-core/src/lib.rs:30-50]()\n\n## 与外部系统的集成\n\n### 摄入管道集成\n\n```mermaid\ngraph TD\n A[源文件] --> B[解析器 Parser]\n B --> C[分块器 Chunker]\n C --> D[提取器 Extractor]\n D --> E[Transaction]\n E --> F[Node/Edge 对象]\n F --> G[Blockstore]\n G --> H[Commit 提交]\n```\n\n摄入管道将外部文档转换为图谱节点：\n- **Doc 节点**：原始文档元数据\n- **Chunk 节点**：分块后的文本段落\n- **Entity 节点**：NER 提取的命名实体\n- **Edge 边**：节点间关系（如 `Chunk -[part_of]-> Doc`、`Entity -[extracted_from]-> Chunk`）\n\n资料来源：[crates/mnem-ingest/src/pipeline.rs:1-80]()\n\n### 全局知识图谱\n\nmnem 支持跨仓库的全局知识图谱（`~/.mnemglobal`），检索时同时搜索当前仓库和全局图谱。\n\n**跨图谱链接策略**：\n- 不在 Edge 中添加 `dst_repo: PathBuf`（保持文件系统无关性）\n- Phase 1：检索时同时搜索全局图谱\n- Phase 2（未来）：在节点属性中添加 `_global_anchor` 指向全局 CID\n\n资料来源：[crates/mnem-cli/src/global.rs:1-50]()\n\n## 总结\n\nmnem 的知识图谱模型是一个精心设计的图数据库核心，它通过：\n\n- **类型安全的链接系统** 确保编译期正确性\n- **不可变的内容寻址** 提供版本历史和完整性保证\n- **确定性编码** 确保跨平台一致性\n- **上下文感知检索** 支持 LLM 高效消费图谱数据\n\n该模型为知识管理、AI 代理和语义搜索提供了坚实的数据基础。\n\n---\n\n\n\n## 版本控制机制\n\n### 相关页面\n\n相关主题：[知识图谱模型](#page-knowledge-graph), [数据流与摄取管道](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/repo/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/mod.rs)\n- [crates/mnem-core/src/repo/transaction.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/transaction.rs)\n- [crates/mnem-core/src/repo/merge.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/merge.rs)\n- [crates/mnem-core/src/objects/operation.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/operation.rs)\n- [crates/mnem-cli/src/commands/commit.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/commit.rs)\n- [crates/mnem-cli/src/commands/branch.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/branch.rs)\n- [crates/mnem-cli/src/commands/diff.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/diff.rs)\n- [crates/mnem-cli/src/commands/merge.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/merge.rs)\n \n\n# 版本控制机制\n\n## 概述\n\nmnem 的版本控制机制是一个基于内容寻址存储（Content-Addressable Storage, CAS）的分布式版本控制系统，采用 DAG（有向无环图）结构管理文档变更历史。该系统以操作为核心抽象，支持多分支并行开发、冲突检测与合并、以及加密签名验证等企业级功能。\n\nmnem 的版本控制设计遵循以下核心原则：\n\n- **无冲突写入**：通过事务机制实现原子性操作\n- **去中心化架构**：每个仓库独立运行，无中心服务器依赖\n- **可验证完整性**：所有操作支持 Ed25519 数字签名\n- **语义保留**：变更记录包含 author、task_id、agent_id 等元数据\n\n资料来源：[crates/mnem-core/src/lib.rs:10-30]()\n\n## 核心数据结构\n\n### Operation（操作）\n\nOperation 是版本控制的基本单元，对应传统 VCS 中的 \"commit\" 概念。\n\n```rust\npub struct Operation {\n pub parents: Vec, // 父操作列表（支持多父节点）\n pub view: Cid, // 操作后的视图快照\n pub predecessors: Option>>, // 前驱操作\n pub author: String, // 作者标识\n pub agent_id: Option, // AI 代理标识\n pub task_id: Option, // 任务标识\n pub host: Option, // 主机标识\n pub time: u64, // Unix 时间戳（微秒）\n pub description: String, // 操作描述\n pub signature: Option, // 加密签名\n pub extra: BTreeMap, // 扩展字段\n}\n```\n\n**关键特性说明：**\n\n| 字段 | 类型 | 用途 |\n|------|------|------|\n| `parents` | `Vec` | 支持多父节点，实现 merge 操作的完整历史记录 |\n| `view` | `Cid` | 指向操作后仓库状态的指针，保证内容可寻址 |\n| `signature` | `Option` | Ed25519 签名，用于操作真实性和完整性验证 |\n| `time` | `u64` | 微秒级时间戳，支持高精度排序 |\n\n资料来源：[crates/mnem-core/src/objects/operation.rs:30-70]()\n\n### ChangeId（变更标识）\n\nChangeId 是操作的唯一标识符，用于在 refs 和 parents 中引用操作：\n\n```rust\npub struct ChangeId(bytes::Bytes);\n```\n\nChangeId 通过内容哈希生成，确保相同操作的标识全局一致。\n\n### View（视图）\n\nView 记录特定时间点的仓库完整状态，包含：\n\n- 所有 refs（分支、标签）的当前指向\n- 活动节点集合\n- 墓碑集（tombstones）：已删除节点的记录，用于冲突检测\n\n资料来源：[crates/mnem-core/src/objects/mod.rs]()\n\n## 事务机制\n\n### Transaction 事务\n\nTransaction 是 mnem 的核心写操作接口，提供原子性的变更构建与提交能力。\n\n```mermaid\ngraph TD\n A[创建 Transaction] --> B[add_node 添加节点]\n A --> C[add_edge 添加关系]\n B --> D[resolve_chunker 解析分块器]\n C --> E[extract::RuleExtractor 实体提取]\n D --> F[commit 提交事务]\n E --> F\n G[返回 IngestResult] --> H[ReadonlyRepo]\n```\n\n**主要方法：**\n\n| 方法 | 签名 | 功能 |\n|------|------|------|\n| `add_node` | `add_node(ntype, props, content) -> Result` | 添加节点到当前事务 |\n| `add_edge` | `add_edge(src, dst, etype) -> Result<()>` | 添加节点间关系 |\n| `commit` | `commit(author, message) -> Result` | 原子提交事务 |\n| `ingest` | `ingest(tx, bytes, kind) -> Result` | 端到端导入流程 |\n\n资料来源：[crates/mnem-core/src/repo/transaction.rs:60-120]()\n\n### IngestResult 结果\n\n`ingest` 方法返回的 `IngestResult` 包含执行统计信息：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `nodes_added` | `u32` | 新增节点数 |\n| `chunks_created` | `u32` | 创建的文本块数 |\n| `entities_extracted` | `u32` | 提取的实体数 |\n| `elapsed_ms` | `u64` | 执行耗时（毫秒） |\n\n## 分支与引用管理\n\n### Refs 结构\n\nmnem 使用 refs 管理命名引用：\n\n```text\nrefs/heads/ # 分支头指针\nrefs/tags/ # 标签引用\nHEAD # 当前分支指针\n```\n\n### 分支操作\n\nCLI 提供完整的分支管理能力：\n\n| 命令 | 功能 | 关键参数 |\n|------|------|----------|\n| `mnem branch` | 列出所有分支 | `-v` 详细输出 |\n| `mnem branch create ` | 创建新分支 | `--from ` 指定起点 |\n| `mnem branch delete ` | 删除分支 | `--force` 强制删除 |\n\n**分支创建流程：**\n\n1. 解析目标 commit（支持 CID、ref 名称、分支短名、HEAD）\n2. 在 View 中创建 `refs/heads/` 指针\n3. 生成新的 Operation 记录变更\n4. 更新 HEAD 指针（如为当前分支）\n\n资料来源：[crates/mnem-cli/src/commands/branch.rs:1-80]()\n\n### 标签操作\n\n标签是只读的命名引用，常用于版本标记：\n\n```rust\npub enum TagCmd {\n List, // 列出所有标签\n Create { name: String, target: Option }, // 创建标签\n Delete { name: String }, // 删除标签\n}\n```\n\n**约束条件：**\n\n- 标签名长度不超过 255 字符\n- 不允许包含空格、制表符、换行符、`~`、`^`、`:`、`?`、`*`、`[`等特殊字符\n- 创建时必须指定有效的 author\n\n资料来源：[crates/mnem-cli/src/commands/tag.rs:1-60]()\n\n## 差异比较\n\n### Diff 命令\n\n`mnem diff` 命令用于比较两个提交之间的变更：\n\n```bash\nmnem diff [options] [] []\n```\n\n| 参数 | 说明 |\n|------|------|\n| `` | 左侧 commit（基准），默认 HEAD |\n| `` | 右侧 commit（比较目标），默认工作区 |\n\n**输出内容包括：**\n\n- 节点变更（新增/修改/删除）\n- 边的变更（关系增删）\n- 元数据变更（props、content）\n\n## 合并机制\n\n### Merge 策略\n\nmnem 支持三方合并（three-way merge），通过检测冲突实现：\n\n```mermaid\ngraph TD\n A[开始合并] --> B[加载 left commit]\n A --> C[加载 right commit]\n A --> D[计算 LCA]\n B --> E[detect_conflicts]\n C --> E\n D --> E\n E --> F{检测到冲突?}\n F -->|是| G[返回 MergeConflicts]\n F -->|否| H[自动合并成功]\n G --> I[返回冲突列表]\n H --> J[创建 merge commit]\n J --> K[更新 View]\n```\n\n### 冲突检测\n\n```rust\npub fn detect_conflicts_with_policy(\n repo: &ReadonlyRepo,\n left: Cid, // 左侧 commit CID\n right: Cid, // 右侧 commit CID\n lca: Option, // 最近公共祖先\n policy: ConflictPolicy,\n) -> Result\n```\n\n**冲突类型：**\n\n| 类型 | 说明 |\n|------|------|\n| `ContentConflict` | 内容修改冲突 |\n| `StructuralConflict` | 结构变更冲突（节点增删） |\n| `PropertyConflict` | 属性值冲突 |\n\n### ConflictPolicy 策略\n\n冲突策略控制合并行为：\n\n```rust\npub struct ConflictPolicy {\n pub ours_priority: bool, // true: 优先我们的变更\n pub theirs_priority: bool, // true: 优先他们的变更\n pub auto_resolve: Vec, // 可自动解决的冲突类型\n}\n```\n\n资料来源：[crates/mnem-core/src/repo/merge.rs:1-100]()\n\n## 提交流程\n\n### Commit 命令\n\n`mnem commit` 创建新的操作记录：\n\n```bash\nmnem commit [options] [--message ]\n```\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `--author` | 配置值 | 作者信息 |\n| `--message` | 自动生成 | 提交消息 |\n| `--amend` | false | 修改上一个提交（追加操作） |\n| `--no-edit` | false | 跳过编辑器 |\n\n**提交流程：**\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Transaction\n participant Blockstore\n participant Repo\n \n User->>CLI: mnem commit -m \"message\"\n CLI->>Repo: 创建 Transaction\n Repo-->>Transaction: 返回 &mut Transaction\n CLI->>Transaction: 加载待提交变更\n CLI->>Transaction: commit(author, message)\n Transaction->>Blockstore: 编码新 View\n Transaction->>Blockstore: 创建 Operation\n Blockstore-->>Transaction: 返回 View CID\n Transaction->>Blockstore: 更新 HEAD ref\n Transaction-->>Repo: 返回 ReadonlyRepo\n Repo-->>CLI: 返回结果\n CLI-->>User: 显示 commit 信息\n```\n\n**作者字符串格式：**\n\n- 完整格式：`\"name \"`\n- 仅名称：`\"name\"`\n- 仅邮箱：`\"\"`\n- 仅 agent_id：`\"mnem-cli\"` 或配置的 agent_id\n\n资料来源：[crates/mnem-cli/src/commands/commit.rs:1-100]()\n\n### 签名验证\n\n操作签名基于 Ed25519 算法：\n\n```rust\npub signature: Option, // Ed25519 签名\n```\n\n**签名流程：**\n\n1. 序列化 Operation（排除 signature 字段）\n2. 使用私钥生成 Ed25519 签名\n3. 附加到 Operation 的 signature 字段\n\n**验证流程：**\n\n1. 提取 signature 和公钥信息\n2. 使用公钥验证签名有效性\n3. 确保操作内容未被篡改\n\n资料来源：[crates/mnem-core/src/sign.rs]()\n\n## CLI 命令参考\n\n### 命令总览\n\n| 命令 | 模块 | 功能 |\n|------|------|------|\n| `mnem commit` | commit.rs | 创建提交 |\n| `mnem branch` | branch.rs | 分支管理 |\n| `mnem tag` | tag.rs | 标签管理 |\n| `mnem diff` | diff.rs | 差异比较 |\n| `mnem merge` | merge.rs | 分支合并 |\n| `mnem log` | log.rs | 历史查看 |\n\n### 仓库配置\n\n配置文件位于 `~/.config/mnem/config.toml` 或仓库根目录的 `.mnem/config.toml`：\n\n```toml\n[user]\nname = \"Your Name\"\nemail = \"you@example.com\"\n\n[llm]\nprovider = \"ollama\"\nmodel = \"qwen2.5\"\nbase_url = \"http://localhost:11434\"\n\n[ner]\nprovider = \"rule\" # rule | none\n```\n\n## 架构设计要点\n\n### DAG 持久化\n\nmnem 使用 DAG-CBOR 编码存储 Operation 和 View，确保：\n\n- **规范化**：相同内容产生相同编码\n- **可验证**：编码后哈希作为 CID 可验证完整性\n- **高效存储**：内容去重通过 CID 实现\n\n### 无头指针\n\nmnem 不使用传统 Git 的 \"head pointer\" 链表模式，而是将所有历史直接编码在 Operation 的 `parents` 字段中。这简化了分支模型，但要求合并时必须显式指定 LCA。\n\n### 事务隔离\n\nTransaction 提供写隔离：\n\n- 未提交的变更对其他读者不可见\n- 提交是原子的（全部成功或全部回滚）\n- 支持嵌套事务（通过 savepoint 实现）\n\n---\n\n## 延伸阅读\n\n- [存储引擎](./storage-engine.md) - Blockstore 接口与实现\n- [检索系统](./retrieval.md) - 基于版本化索引的语义搜索\n- [导入管道](./ingestion.md) - 从多源文档到版本化节点\n\n---\n\n\n\n## 内容寻址系统\n\n### 相关页面\n\n相关主题：[知识图谱模型](#page-knowledge-graph), [存储后端](#page-storage-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/id/cid.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/cid.rs)\n- [crates/mnem-core/src/id/multihash.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/multihash.rs)\n- [crates/mnem-core/src/id/link.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/link.rs)\n- [crates/mnem-core/src/codec/dagcbor.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/codec/dagcbor.rs)\n- [crates/mnem-core/src/codec/dagjson.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/codec/dagjson.rs)\n- [crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n- [crates/mnem-core/src/objects/commit.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/commit.rs)\n- [crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n \n\n# 内容寻址系统\n\n## 概述\n\nmnem 的内容寻址系统是整个知识图谱存储和检索的基础架构。该系统基于 IPFS 生态的标准规范构建，通过内容的加密哈希值作为内容的唯一标识符，实现了去重、版本追溯和分布式存储等核心能力。\n\n内容寻址的核心思想是：**内容本身的哈希值即为该内容的地址**。相同的内容必然产生相同的哈希值，这意味着任何节点可以对相同内容达成共识，无需依赖中心化的命名服务器。资料来源：[crates/mnem-core/src/id/cid.rs:1-50]()\n\n## 核心架构\n\nmnem 的内容寻址系统由多个层次组成，每一层负责不同的职责：\n\n```mermaid\ngraph TB\n subgraph \"内容寻址层次结构\"\n A[\"内容数据
Bytes\"] --> B[\"Multihash
多哈希\"]\n B --> C[\"CIDv1
内容标识符\"]\n C --> D[\"DAG-CBOR
编码\"]\n C --> E[\"DAG-JSON
编码\"]\n end\n \n subgraph \"上层应用\"\n D --> F[\"Node 节点\"]\n D --> G[\"Edge 边\"]\n D --> H[\"Commit 提交\"]\n F --> I[\"Transaction 事务\"]\n G --> I\n H --> I\n end\n \n subgraph \"类型系统\"\n J[\"Link<T>
类型化链接\"]\n K[\"ChangeId
变更标识符\"]\n L[\"OperationId
操作标识符\"]\n end\n```\n\n### 核心不变性保证\n\nmnem-core crate 在 crate 级别强制执行以下不变性：\n\n- `#![forbid(unsafe_code)]` - 整个核心模块禁止使用 `unsafe` 代码\n- 每个对象类型必须保持字节级精确的规范化编码往返属性：`decode(encode(x)) == x`\n- 每个 `put` 操作必须验证解码后的对象与原始内容一致 资料来源：[crates/mnem-core/src/lib.rs:30-45]()\n\n## CID 内容标识符\n\n### CID 结构\n\nCID（Content Identifier）是 IPLD 生态系统中用于标识有向无环图（DAG）中节点的标准格式。mnem 使用 CIDv1 格式，支持多种哈希算法。\n\n```rust\n// CID 结构示意（简化版）\npub struct Cid {\n version: u64, // CID 版本，通常为 1\n codec: u64, // 编解码器标识（如 dag-cbor = 0x71）\n hash: Multihash, // 内容的哈希值\n}\n```\n\n### CID 的编解码\n\nCID 的序列化采用 IPLD 规范定义的格式，支持二进制（DAG-CBOR）和字符串（base32）两种表示方式：\n\n| 表示方式 | 用途 | 示例 |\n|---------|------|------|\n| 二进制 | 内部存储、图遍历 | 存储在 Blockstore 中 |\n| Base32 字符串 | 人类可读、URL 安全 | `bafybeig...` 格式 |\n\n资料来源：[crates/mnem-core/src/id/cid.rs:1-100]()\n\n## Multihash 多哈希\n\n### 设计理念\n\nMultihash 是一种自描述的哈希格式，它将哈希算法标识和哈希值封装在一起。这种设计允许系统在不破坏已有内容寻址的前提下，演进哈希算法。\n\n```\n┌─────────────┬─────────────┬──────────────────┐\n│ 算法标识 │ 长度 (2B) │ 哈希值 │\n│ (varint) │ │ │\n└─────────────┴─────────────┴──────────────────┘\n```\n\n### 支持的哈希算法\n\nmnem 通过 `multihash` crate 支持多种哈希算法，具体使用哪种算法取决于配置和用例。常见算法包括：\n\n| 算法 | 标识符 | 输出长度 | 适用场景 |\n|------|--------|----------|----------|\n| SHA-256 | 0x12 | 32 字节 | 默认、安全敏感场景 |\n| Blake3 | 0xb201 | 32 字节 | 高性能需求 |\n| Keccak-256 | 0x1b | 32 字节 | 以太坊兼容 |\n\n资料来源：[crates/mnem-core/src/id/multihash.rs:1-80]()\n\n## Link 类型系统\n\n### 幽灵类型化链接\n\nmnem 引入了 `Link` 类型，这是一种phantom-typed（幽灵类型化）的链接类型，用于在编译期确保类型安全：\n\n```rust\npub struct Link {\n cid: Cid,\n _marker: PhantomData,\n}\n```\n\n这种设计实现了以下保证：\n\n- 编译时类型检查：无法将 `Link` 错误赋值给期望 `Link` 的位置\n- 运行时零开销：幽灵类型不占用实际存储空间\n- 语义清晰：`Link` 表示指向节点，`Link` 表示指向提交\n\n资料来源：[crates/mnem-core/src/id/link.rs:1-60]()\n\n### 相关的标识符类型\n\n除 `Link` 外，系统还定义了以下标识符类型：\n\n| 类型 | 用途 | 说明 |\n|------|------|------|\n| `ChangeId` | 变更标识 | 标识一次原子变更操作 |\n| `OperationId` | 操作标识 | 标识具体的操作实例 |\n| `EdgeId` | 边标识 | 标识图中的一条边 |\n\n资料来源：[crates/mnem-core/src/lib.rs:20-30]()\n\n## 编解码器\n\n### DAG-CBOR 编解码器\n\nDAG-CBOR 是 CBOR（Concise Binary Object Representation）的 DAG 扩展，是 IPLD 系统的默认编解码格式。它具有以下特点：\n\n- **紧凑二进制表示**：相比 JSON 节省 30-50% 空间\n- **确定性编码**：相同数据必然产生相同字节序列\n- **丰富的类型支持**：包括字节串、链接、标签等 IPLD 特有类型\n\n```mermaid\ngraph LR\n A[\"Rust Struct\"] --> B[\"Serialize\"]\n B --> C[\"CBOR Bytes\"]\n C --> D[\"Multihash\"]\n D --> E[\"CID\"]\n \n F[\"CID\"] --> G[\"Multihash\"]\n G --> H[\"CBOR Bytes\"]\n H --> I[\"Deserialize\"]\n I --> J[\"Rust Struct\"]\n```\n\n资料来源：[crates/mnem-core/src/codec/dagcbor.rs:1-100]()\n\n### DAG-JSON 编解码器\n\nDAG-JSON 用于人类可读的调试导出和日志记录。虽然不用于实际存储，但它对于开发和调试至关重要：\n\n| 特性 | DAG-JSON | DAG-CBOR |\n|------|----------|----------|\n| 用途 | 调试、导出 | 实际存储 |\n| 可读性 | 人类可读 | 二进制 |\n| 效率 | 低 | 高 |\n| 规范性 | 非严格 | 严格确定性 |\n\n资料来源：[crates/mnem-core/src/codec/dagjson.rs:1-80]()\n\n## 对象模型\n\n### Node 节点\n\nNode 是内容寻址存储的基本单元，每个节点由以下部分组成：\n\n```mermaid\ngraph TB\n A[\"Node\"] --> B[\"id: NodeId\"]\n A --> C[\"ntype: String
节点类型\"]\n A --> D[\"summary: Option<String>
摘要\"]\n A --> E[\"props: BTreeMap
属性映射\"]\n A --> F[\"content: Option<Bytes>
内容负载\"]\n A --> G[\"context_sentence: Option<String>
上下文句子\"]\n```\n\n#### 字段语义\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `NodeId` | 节点的唯一标识符 |\n| `ntype` | `String` | 节点类型标签（如 \"Fact\", \"Person\"） |\n| `summary` | `Option` | LLM 可读的摘要文本 |\n| `props` | `BTreeMap` | 结构化属性，可包含 `Link` |\n| `content` | `Option` | 原始二进制负载 |\n| `context_sentence` | `Option` | 上下文定位前缀 |\n\n**上下文句子（Context Sentence）**是 Anthropic 2024 年上下文检索论文的实现。系统在嵌入前将此句子添加到摘要前，使密集和稀疏检索都能捕获位置和关系上下文。资料来源：[crates/mnem-core/src/objects/node.rs:1-100]()\n\n### Edge 边\n\nEdge 表示节点之间的有向关系：\n\n```rust\npub struct Edge {\n pub src: NodeId,\n pub label: String,\n pub dst: NodeId,\n pub props: BTreeMap,\n}\n```\n\n### Commit 提交\n\nCommit 封装了一组原子性的变更：\n\n```mermaid\ngraph TB\n A[\"Commit\"] --> B[\"change_id: ChangeId\"]\n A --> C[\"parents: Vec<ChangeId>\"]\n A --> D[\"nodes: Vec<Node>\"]\n A --> E[\"edges: Vec<Edge>\"]\n A --> F[\"author: String\"]\n A --> G[\"time: u64\"]\n A --> H[\"message: String\"]\n A --> I[\"signature: Option<Signature>\"]\n```\n\n资料来源：[crates/mnem-core/src/objects/commit.rs:1-100]()\n\n## 内容寻址工作流\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Transaction\n participant Blockstore\n participant Codec\n \n Client->>Transaction: add_node(node)\n Transaction->>Codec: serialize(node)\n Codec-->>Transaction: dag_cbor_bytes\n Transaction->>Blockstore: put(cid, bytes)\n Blockstore-->>Transaction: CID\n Transaction-->>Client: Link\n \n Client->>Transaction: add_edge(src, label, dst)\n Transaction->>Transaction: 创建 Edge\n Transaction->>Transaction: 创建 Commit\n Transaction->>Codec: serialize(commit)\n Blockstore->>Blockstore: 存储所有子节点\n```\n\n### 读取流程\n\n```mermaid\ngraph LR\n A[\"Link<T>\"] --> B[\"CID\"]\n B --> C[\"Blockstore.get\"]\n C --> D[\"DAG-CBOR Bytes\"]\n D --> E[\"Codec.deserialize\"]\n E --> F[\"T 类型对象\"]\n```\n\n## 源类型与分块\n\n内容寻址系统与源类型处理紧密集成。`SourceKind` 定义了支持的源类型：\n\n| 源类型 | 说明 | 默认分块策略 |\n|--------|------|--------------|\n| `Markdown` | Markdown 文档 | Paragraph |\n| `Text` | 纯文本 | SentenceRecursive (256 tokens, 32 overlap) |\n| `Pdf` | PDF 文档 | SentenceRecursive (512 tokens, 64 overlap) |\n| `Conversation` | 对话记录 | Session (10 messages) |\n| `Code(lang)` | 代码文件 | Structural |\n\n`CodeLanguage` 枚举支持以下语言：Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, Ruby, CSharp\n\n资料来源：[crates/mnem-ingest/src/types.rs:1-100]()\n\n## 检索与渲染\n\n### 节点渲染\n\n检索系统需要将节点转换为适合 LLM 消费的文本格式。渲染格式如下：\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n...\n```\n\n渲染规则：\n\n- `ntype` 和 `id` 始终存在\n- `context` 在 `summary` 之前（遵循 Anthropic 上下文检索方案）\n- `summary` 长度上限 8192 字符（可配置 `MNEM_RENDER_SUMMARY_CAP_CHARS`）\n- 标量属性按 BTreeMap 顺序（字母序）输出\n- 非标量属性（Link, Map, List, Bytes, Null）被跳过\n- 不透明 `content` 永不渲染\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs:50-100]()\n\n## 配置与扩展\n\n### 存储后端\n\nmnem 通过 `Blockstore` trait 定义存储接口，支持多种实现：\n\n```rust\npub trait Blockstore {\n async fn get(&self, cid: &Cid) -> Result>>;\n async fn put(&self, cid: &Cid, block: &[u8]) -> Result<()>;\n}\n```\n\n### 可扩展性设计\n\n内容寻址系统的扩展点包括：\n\n- **新的编解码器**：实现 `Codec` trait 可添加新的序列化格式\n- **新的哈希算法**：通过 `multihash` crate 注册新算法\n- **新的对象类型**：定义新结构体并实现序列化 trait\n\n## 总结\n\nmnem 的内容寻址系统建立在一个经过验证的标准之上（IPLD、CID、Multihash），同时通过以下设计决策提供了独特的价值：\n\n1. **类型安全**：通过 `Link` phantom 类型实现编译期检查\n2. **确定性编码**：确保相同内容产生相同 CID，这是内容去重和一致性的基础\n3. **上下文感知**：通过 `context_sentence` 字段增强检索质量\n4. **规范化保证**：crate 级别禁止 `unsafe`，所有编解码经过往返测试\n\n这套系统使得 mnem 能够可靠地管理知识图谱的长期演进，同时保持高效的内容查询和去重能力。\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[数据流与摄取管道](#page-data-flow), [知识图谱模型](#page-knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/store/blockstore.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/store/blockstore.rs)\n- [crates/mnem-core/src/store/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/store/mod.rs)\n- [crates/mnem-core/src/store/op_heads.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/store/op_heads.rs)\n- [crates/mnem-backend-redb/src/blockstore.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-backend-redb/src/blockstore.rs)\n- [crates/mnem-backend-redb/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-backend-redb/src/lib.rs)\n \n\n# 存储后端\n\nmnem 的存储后端是整个系统的核心基础设施，负责持久化和检索内容寻址的数据块（blocks）。它定义了抽象的存储接口，并提供了多种后端实现，使得上层逻辑与具体存储技术解耦。\n\n## 架构概览\n\nmnem 采用模块化的存储架构，将存储接口抽象为 trait（特征），支持可插拔的后端实现。当前系统包含两套核心存储抽象和两种后端实现。\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A[\"mnem-core
(核心库)\"]\n B[\"mnem-cli
(命令行工具)\"]\n C[\"mnem-http
(HTTP服务)\"]\n end\n \n subgraph \"存储抽象层\"\n D[\"Blockstore trait\"]\n E[\"OpHeadsStore trait\"]\n end\n \n subgraph \"后端实现层\"\n F[\"InMemoryBlockstore
(内存实现)\"]\n G[\"RedbBlockstore
(redb持久化)\"]\n H[\"InMemoryOpHeadsStore\"]\n end\n \n A --> D\n A --> E\n B --> A\n C --> A\n D --> F\n D --> G\n E --> H\n```\n\n## Blockstore 特征\n\n`Blockstore` 是 mnem 系统中用于存储和检索内容寻址数据块的核心 trait。它定义了读写操作的抽象接口，使得无论底层使用何种存储技术，上层的编解码和 DAG 操作都能正常工作。\n\n### 核心方法\n\n| 方法 | 签名 | 功能描述 |\n|------|------|----------|\n| `get` | `fn get(&self, cid: &Cid) -> Result>, Error>` | 根据 CID 检索数据块，返回 `None` 表示不存在 |\n| `put` | `fn put(&self, block: &[u8]) -> Result` | 存储数据块，返回其 CID |\n| `has` | `fn has(&self, cid: &Cid) -> Result` | 检查指定 CID 的数据块是否存在 |\n\n资料来源：[crates/mnem-core/src/store/blockstore.rs:1-50]()\n\n### 存储保证\n\n`Blockstore` 的实现必须满足以下契约：\n\n- **幂等性**：`put` 操作对相同内容应产生相同的 CID（使用 DAG-CBOR 规范）\n- **一致性**：读取已写入的数据必须返回完全相同的字节序列\n- **原子性**：单个 `put` 操作应保持原子性\n\n### CID 与内容映射\n\nmnem 使用 CIDv1 作为内容标识符，数据块采用 DAG-CBOR 编码格式。这种设计确保了：\n\n1. 相同内容始终映射到相同的 CID\n2. CID 包含足够的信息来验证内容完整性\n3. 存储系统无需维护独立的索引来追踪内容\n\n## OpHeadsStore 特征\n\n`OpHeadsStore` 专门用于存储和管理操作头（operation heads）。在 mnem 的操作日志模型中，每个仓库（repo）在任意时刻都可能存在多个并发的操作头，这些头指针指向最新提交的操作序列。\n\n### 核心方法\n\n| 方法 | 签名 | 功能描述 |\n|------|------|----------|\n| `get_op_heads` | `fn get_op_heads(&self) -> Result, Error>` | 获取当前所有操作头 |\n| `put_op_heads` | `fn put_op_heads(&self, heads: &[OperationId]) -> Result<(), Error>` | 原子性地更新操作头集合 |\n\n资料来源：[crates/mnem-core/src/store/op_heads.rs:1-40]()\n\n### 操作头语义\n\n操作头集合代表了仓库的当前状态边界：\n\n- **无头状态**：空的 `Vec` 表示仓库从未有过任何操作\n- **单头状态**：单一操作头表示线性历史\n- **多头状态**：多个操作头表示并发分支，需要合并\n\n## 内存后端实现\n\nmnem-core 包提供了一个内存中的参考实现，适用于测试、开发和单进程场景。\n\n### InMemoryBlockstore\n\n基于 `BTreeMap>` 实现的内存块存储：\n\n```mermaid\ngraph LR\n A[\"put(cid, block)\"] --> B[\"BTreeMap insert\"]\n C[\"get(cid)\"] --> D[\"BTreeMap lookup\"]\n E[\"has(cid)\"] --> F[\"BTreeMap contains_key\"]\n```\n\n特点：\n- 无持久化能力，进程退出后数据丢失\n- 查询性能为 O(log n)，其中 n 为存储块数量\n- 适合单元测试和快速原型开发\n\n### InMemoryOpHeadsStore\n\n同样基于内存的 OpHeadsStore 实现，使用 `Vec` 存储操作头。\n\n## Redb 后端实现\n\n`mnem-backend-redb` 提供基于 [redb](https://github.com/cberner/redb) 的持久化存储实现。redb 是一个纯 Rust 编写的嵌入式事务型 KV 数据库，具有以下特性：\n\n### 特性\n\n| 特性 | 描述 |\n|------|------|\n| 纯 Rust | 无外部依赖，符合 mnem 的安全要求 |\n| ACID 事务 | 支持完整的事务语义 |\n| 嵌入式 | 无需独立的数据库服务器 |\n| MVCC | 多版本并发控制，支持只读事务与读写事务并发 |\n\n资料来源：[crates/mnem-backend-redb/src/lib.rs:1-30]()\n\n### 数据库结构\n\n```mermaid\ngraph TD\n subgraph \"redb 数据库\"\n subgraph \"元数据表\"\n M1[\"op_heads: Vec\"]\n end\n subgraph \"数据表\"\n D1[\"cid_1: Vec\"]\n D2[\"cid_2: Vec\"]\n D3[\"cid_n: Vec\"]\n end\n end\n```\n\n### 事务管理\n\nRedbBlockstore 实现使用读写事务来保证数据一致性：\n\n- **写操作**：在读写事务中执行 `put`，事务提交后数据持久化\n- **读操作**：使用只读事务，避免阻塞写操作\n- **批量操作**：多个 `put` 可以在同一事务中执行\n\n### 配置选项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `path` | `&Path` | 必需 | 数据库文件路径 |\n| `max_db_size` | `u64` | 4GB | 数据库文件最大大小 |\n| `read_transactions` | `bool` | true | 是否启用并发只读事务 |\n\n## 后端选择指南\n\n| 场景 | 推荐后端 | 原因 |\n|------|----------|------|\n| 单元测试 | InMemory | 快速、无副作用 |\n| 开发调试 | InMemory | 便于检查状态 |\n| CLI 工具 | Redb | 持久化 + 嵌入式 |\n| HTTP 服务 | Redb | 事务保证 + 并发支持 |\n| 内存受限环境 | InMemory | 零磁盘占用 |\n\n## 与上层模块的关系\n\n```mermaid\ngraph TD\n subgraph \"mnem-core\"\n R[\"Repo / ReadonlyRepo\"]\n T[\"Transaction\"]\n O[\"Operation\"]\n N[\"Node\"]\n end\n \n subgraph \"存储层\"\n BS[\"Blockstore\"]\n OHS[\"OpHeadsStore\"]\n end\n \n R --> BS\n R --> OHS\n T --> BS\n T --> OHS\n O --> BS\n N --> BS\n```\n\n`ReadonlyRepo` 和 `Transaction` 通过组合持有 `Box` 和 `Box`，实现了存储后端的运行时多态。\n\n## 错误处理\n\n存储操作可能返回以下错误类型：\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `Error::BlockNotFound` | `get` 操作的 CID 不存在 |\n| `Error::Encoding` | DAG-CBOR 编码/解码失败 |\n| `Error::Store` | 后端存储错误（如磁盘满、IO 错误） |\n\n所有存储错误都会向上传播，最终由应用层决定如何处理（如重试、回滚或报告）。\n\n## 扩展新的后端\n\n要实现新的存储后端，需要完成以下步骤：\n\n1. **实现 Blockstore trait**：提供 `get`、`put`、`has` 方法\n2. **实现 OpHeadsStore trait**：提供 `get_op_heads`、`put_op_heads` 方法\n3. **实现 Send + Sync**：确保线程安全\n4. **实现 Default**：提供零参数构造能力\n5. **处理错误转换**：将底层错误映射到 `mnem_core::Error`\n\n建议参考 `mnem-backend-redb` 的目录结构：\n\n```\ncrates/mnem-backend-redb/\n├── src/\n│ ├── lib.rs # 模块导出和公共 API\n│ └── blockstore.rs # Blockstore trait 实现\n├── Cargo.toml\n└── README.md\n```\n\n## 安全考虑\n\nmnem-core 整个包禁用了 `unsafe_code`（`#![forbid(unsafe_code)]`），这意味着：\n\n- 存储后端实现也不能使用 `unsafe`\n- 数据完整性依赖 Rust 的内存安全保证\n- 持久化数据的可靠性完全由后端实现负责\n\n---\n\n\n\n## 数据流与摄取管道\n\n### 相关页面\n\n相关主题：[存储后端](#page-storage-backend), [混合检索系统](#page-hybrid-retrieval)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n- [crates/mnem-ingest/src/pipeline.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pipeline.rs)\n- [crates/mnem-ingest/src/chunk.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/chunk.rs)\n- [crates/mnem-ingest/src/pdf.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pdf.rs)\n- [crates/mnem-ingest/src/md.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/md.rs)\n- [crates/mnem-ingest/src/code.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/code.rs)\n- [crates/mnem-core/src/prolly/chunker.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/prolly/chunker.rs)\n- [crates/mnem-cli/src/commands/ingest.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/ingest.rs)\n- [crates/mnem-ingest/src/types.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/types.rs)\n- [crates/mnem-ingest/src/extract.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/extract.rs)\n \n\n# 数据流与摄取管道\n\n## 概述\n\n摄取管道（Ingestion Pipeline）是 mnem 系统的核心入口，负责将外部源文件（Markdown、PDF、代码、对话记录等）解析、分割、提取并写入仓库图数据库。整个管道设计遵循确定性原则：相同输入无论何时处理，都会产生相同的输出内容与 CID 标识符。\n\nmnem 将每份摄入的文档建模为 **Doc + Chunk + Entity** 三层节点结构，并通过 **relation edges** 将实体与原文关联，形成可供检索的语义图谱。资料来源：[crates/mnem-ingest/src/lib.rs:25]()\n\n```mermaid\ngraph TD\n A[外部源文件] --> B[SourceKind 检测]\n B --> C[专用解析器]\n C --> D[Section 列表]\n D --> E[Chunker 分块策略]\n E --> F[Chunk 列表]\n F --> G[Entity Extractor]\n G --> H[实体与关系]\n H --> I[写入 Transaction]\n I --> J[Commit 提交]\n J --> K[图数据库]\n```\n\n## 核心组件\n\n### 模块架构\n\n| 模块 | 职责 | 关键类型 |\n|------|------|----------|\n| `pipeline` | 端到端管道编排 | `Ingester` |\n| `chunk` | 分块策略选择与执行 | `ChunkerKind`, `chunk()`, `auto_chunker()` |\n| `md` | Markdown 解析 | `parse_markdown()` |\n| `pdf` | PDF 文本提取 | `PdfExtractor` |\n| `code` | 代码解析（tree-sitter） | `parse_code()` |\n| `conversation` | 对话记录解析 | `parse_conversation()` |\n| `extract` | 实体与关系提取 | `RuleExtractor`, `Extractor` trait |\n| `text` | 纯文本处理 | `parse_text()` |\n| `types` | 类型定义 | `SourceKind`, `Section`, `Chunk` |\n\n资料来源：[crates/mnem-ingest/src/lib.rs:10-32]()\n\n## 数据类型体系\n\n### SourceKind 源类型枚举\n\n管道根据文件扩展名自动检测源类型，不同类型采用不同的解析与分块策略。\n\n| 扩展名 | SourceKind | 默认分块策略 |\n|--------|------------|--------------|\n| `.md`, `.markdown` | `Markdown` | Paragraph |\n| `.txt` | `Text` | SentenceRecursive (256 tokens, 32 overlap) |\n| `.pdf` | `Pdf` | SentenceRecursive (512 tokens, 64 overlap) |\n| `.json`, `.jsonl` | `Conversation` | Session (max_messages: 10) |\n| `.rs`, `.py`, `.js` 等 | `Code(lang)` | Structural |\n\n资料来源：[crates/mnem-ingest/src/types.rs:58-75]()\n\n### Section 结构\n\n`Section` 是解析后的中间表示，包含标题层级与正文内容：\n\n```rust\npub struct Section {\n pub heading: Option, // 标题文本\n pub level: u8, // 标题层级 (1-6)\n pub body: String, // 正文内容\n}\n```\n\n### Chunk 结构\n\n`Chunk` 是最终存储的基本单元：\n\n```rust\npub struct Chunk {\n pub tokens_estimate: usize, // token 数量估算\n pub text: String, // 块文本\n pub source_span: SourceSpan, // 源文件位置\n}\n```\n\n资料来源：[crates/mnem-ingest/src/chunk.rs:30-45]()\n\n## 分块策略详解\n\n### ChunkerKind 枚举\n\n管道支持五种分块策略，通过 `ChunkerKind` 枚举选择。\n\n| 策略 | 描述 | 适用场景 |\n|------|------|----------|\n| `Paragraph` | 按双换行符分割 | Markdown 文档 |\n| `Recursive` | 滑动窗口 token 分块（向后兼容） | 通用文本 |\n| `SentenceRecursive` | 基于 Unicode UAX #29 句子边界感知的 token 分块 | PDF、纯文本 |\n| `Session` | 按消息数分组对话片段 | 对话记录 |\n| `Structural` | 每个 Section 一个 Chunk | 代码文件 |\n\n资料来源：[crates/mnem-ingest/src/chunk.rs:20-30]()\n\n### 自动策略选择\n\n`auto_chunker()` 函数根据源类型返回最佳分块策略：\n\n```rust\npub fn auto_chunker(kind: SourceKind, heuristics: ChunkerAuto) -> ChunkerKind {\n match kind {\n SourceKind::Markdown => ChunkerKind::Paragraph,\n SourceKind::Text => ChunkerKind::SentenceRecursive { \n max_tokens: 256, overlap: 32 \n },\n SourceKind::Pdf => ChunkerKind::SentenceRecursive { \n max_tokens: 512, overlap: 64 \n },\n SourceKind::Conversation => ChunkerKind::Session { \n max_messages: 10 \n },\n SourceKind::Code(_) => ChunkerKind::Structural,\n }\n}\n```\n\n资料来源：[crates/mnem-ingest/src/chunk.rs:100-115]()\n\n### SentenceRecursive 策略特点\n\n- 基于 Unicode 句子边界（UAX #29），确保块不在句子中间断开\n- overlap 以句子为单位计算\n- 平均块大小更均匀\n- Token 计数采用空格分割估算（`tokens_estimate` 字段）\n\n## 管道执行流程\n\n### Ingester 核心逻辑\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Ingester\n participant Parser\n participant Chunker\n participant Extractor\n participant Transaction\n\n Client->>Ingester: ingest(bytes, SourceKind)\n Ingester->>Parser: parse(bytes, kind)\n Parser-->>Ingester: Vec\n Ingester->>Chunker: chunk(sections, ChunkerKind)\n Chunker-->>Ingester: Vec\n Ingester->>Extractor: extract(sections, chunks)\n Extractor-->>Ingester: (Vec, Vec)\n Ingester->>Transaction: add_node(Doc) + add_node(Chunk) + add_node(Entity)\n Ingester->>Transaction: add_edge(relation edges)\n Ingester-->>Client: IngestResult\n```\n\n### 关键 API\n\n`Ingester::ingest()` 方法：\n\n```rust\npub fn ingest(\n &self,\n tx: &mut Transaction,\n bytes: &[u8],\n kind: SourceKind,\n) -> Result\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `tx` | `&mut Transaction` | 写入事务引用，不自动提交 |\n| `bytes` | `&[u8]` | 原始字节载荷 |\n| `kind` | `SourceKind` | 源类型标识 |\n\n**返回值：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `counts` | `Counts` | 节点数量统计 |\n| `elapsed` | `Duration` | 执行耗时 |\n| `commit_cid` | `Option` | 留空，调用者需手动 `tx.commit()` |\n\n资料来源：[crates/mnem-ingest/src/pipeline.rs:80-110]()\n\n## 专用解析器\n\n### Markdown 解析器\n\n基于 CommonMark + GFM 规范，支持：\n\n- ATX/Setex 标题（提取层级）\n- 列表、代码块、表格\n- 返回 `Vec`，每个顶级或次级块一个 Section\n\n### PDF 解析器\n\n纯 Rust 实现，支持两种模式：\n\n1. **内置提取**：解析 PDF 文本层\n2. **Sidecar 扩展**：调用外部 `docling` 或 `unstructured-ingest` CLI\n\n```rust\n#[cfg(feature = \"sidecar-docling\")]\npub struct DoclingSidecar;\n\n#[cfg(feature = \"sidecar-unstructured\")]\npub struct UnstructuredSidecar;\n```\n\n资料来源：[crates/mnem-ingest/src/sidecar.rs:30-50]()\n\n### 代码解析器\n\n使用 tree-sitter 解析代码文件，按函数/类级别提取 Section：\n\n| 支持语言 | 扩展名 |\n|----------|--------|\n| Rust | `.rs` |\n| Python | `.py`, `.pyi` |\n| JavaScript | `.js`, `.mjs`, `.cjs` |\n| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` |\n| Go | `.go` |\n| Java | `.java` |\n| C/C++ | `.c`, `.h`, `.cpp`, `.cc`, `.cxx`, `.hpp` |\n| Ruby | `.rb`, `.gemspec`, `.rake`, `.erb` |\n| C# | `.cs`, `.csx` |\n\n### 对话解析器\n\n支持 ChatGPT、Claude 等导出的 JSON/JSONL 格式：\n\n```json\n{\n \"messages\": [\n {\"role\": \"user\", \"content\": \"...\"},\n {\"role\": \"assistant\", \"content\": \"...\"}\n ]\n}\n```\n\n## 实体提取系统\n\n### Extractor Trait\n\n```rust\npub trait Extractor: Send + Sync {\n fn prepare(&self, sections: &[Section]) -> Result<(), Error>;\n fn extract_entities(&self, sections: &[Section], text: &str) -> Vec;\n fn extract_relations(&self, text: &str, entities: &[EntitySpan]) -> Vec;\n}\n```\n\n资料来源：[crates/mnem-ingest/src/extract.rs:50-70]()\n\n### RuleExtractor\n\n默认提取器实现：\n\n- **实体检测**：委托给 `NerProvider`（默认：大写短语启发式）\n- **关系检测**：基于动词窗口正则表达式\n\n```rust\nr\"(?i)\\b(?:joined|founded|acquired|owns|hired|married|...)\n```\n\n### 可选扩展\n\n| 扩展 | 特性 | Cargo Feature |\n|------|------|----------------|\n| `KeyBertAdapter` | 统计 NER + embedding | `keybert` |\n| `OllamaExtractor` | LLM 驱动 schema 约束 NER | `ollama` |\n\nOllama 提取器会对幻觉 span 重新验证，失败时降级为空 Vec 而非错误。\n\n## CLI 接口\n\n### 基本用法\n\n```bash\n# 摄入单个文件\nmnem ingest notes.md\n\n# 指定分块策略\nmnem ingest --chunker recursive --max-tokens 1024 book.pdf\n\n# 递归目录\nmnem ingest --recursive docs/\n```\n\n### 命令行参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--chunker` | `auto` | 策略：`auto|paragraph|recursive|session|structural` |\n| `--max-tokens` | 512 | 目标 token 数 |\n| `--overlap` | 32 | 重叠 token 数 |\n| `--recursive` | false | 递归目录 |\n| `--ntype` | `Doc` | 根节点标签 |\n| `--extractor` | `none` | 提取器：`none|keybert` |\n| `--ner` | `rule` | NER 提供者：`rule|none` |\n\n资料来源：[crates/mnem-cli/src/commands/ingest.rs:50-80]()\n\n## HTTP API\n\n### POST /v1/ingest\n\n**请求体：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `file` | multipart | 要摄入的文件 |\n| `chunker` | `Option` | `auto\\|paragraph\\|recursive` |\n| `max_tokens` | `Option` | 目标 token |\n| `overlap` | `Option` | 重叠 token |\n| `author` | `String` | 提交作者（必需） |\n| `message` | `Option` | 提交信息 |\n| `extractor` | `Option` | `none\\|keybert` |\n| `ner_provider` | `Option` | `rule\\|none` |\n\n资料来源：[crates/mnem-http/src/handlers_ingest.rs:20-50]()\n\n## 确定性保证\n\nmnem 摄取管道的设计目标之一是**确定性**：\n\n1. **解析确定性**：相同输入产生相同的 `Vec`\n2. **分块确定性**：`SentenceRecursive` 使用 Unicode 边界，不依赖运行时状态\n3. **编码确定性**：所有对象类型保证字节级精确的编解码往返\n4. **CID 确定性**：相同内容产生相同 CID，支持去重\n\n> `#![forbid(unsafe_code)]` 确保管道中无未定义行为。\n\n资料来源：[crates/mnem-core/src/lib.rs:25-30]()\n\n## Node 输出结构\n\n摄取完成后，仓库中包含以下节点：\n\n| 节点类型 | ntype | 说明 |\n|----------|-------|------|\n| 文档节点 | `Doc`（可配置） | 根节点，记录来源 |\n| 块节点 | `Chunk` | 分块后的内容单元 |\n| 实体节点 | 实体类型 | 提取的命名实体 |\n\n每个节点包含：\n\n```rust\npub struct Node {\n pub summary: Option, // 摘要（供 LLM 使用）\n pub props: BTreeMap, // 属性映射\n pub content: Option, // 原始内容\n pub context_sentence: Option, // 上下文前缀句\n}\n```\n\n`context_sentence` 字段实现 Anthropic 2024 Contextual Retrieval 方案，在嵌入前添加到摘要前缀。\n\n## 错误处理\n\n| 错误类型 | 触发条件 |\n|----------|----------|\n| `Error::ParseFailed` | 解析器拒绝输入 |\n| `Error::UnsupportedSource` | 不支持的源类型 |\n| `Error::Commit` | 事务写入失败 |\n| `Error::Sidecar` | 外部工具缺失或失败 |\n\nSidecar 工具错误会包装为 `Error::Sidecar { tool, detail }`。\n\n---\n\n\n\n## 混合检索系统\n\n### 相关页面\n\n相关主题：[数据流与摄取管道](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n- [crates/mnem-core/src/retrieve/retriever.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/retriever.rs)\n- [crates/mnem-core/src/retrieve/fusion.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/fusion.rs)\n- [crates/mnem-core/src/index/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/index/mod.rs)\n- [crates/mnem-core/src/index/vector.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/index/vector.rs)\n- [crates/mnem-core/src/index/sparse.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/index/sparse.rs)\n- [crates/mnem-ann/src/hnsw.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ann/src/hnsw.rs)\n- [crates/mnem-cli/src/config.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/config.rs)\n- [crates/mnem-ingest/src/chunk.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/chunk.rs)\n \n\n# 混合检索系统\n\n## 概述\n\nmnem 的混合检索系统（Hybrid Retrieval System）是核心检索引擎，负责在给定的 token 预算内高效地从知识库中召回最相关的内容。该系统通过组合向量检索（dense vector）、稀疏检索（sparse retrieval）和图扩展（graph expansion）等多种策略，为 Agent 提供高质量的上下文上下文。\n\nmnem 的检索架构遵循以下设计原则：\n\n- **多策略融合**：同时利用密集向量和稀疏向量的互补优势\n- **Token 预算感知**：严格控制返回内容的 token 消耗\n- **确定性渲染**：为 LLM 生成稳定、可预测的输入格式\n- **无 Unsafe 代码**：整个检索管线保证内存安全\n\n资料来源：[crates/mnem-core/src/lib.rs]()\n\n## 检索流程架构\n\n混合检索系统的完整工作流程如下：\n\n```mermaid\ngraph TD\n A[用户查询 Query] --> B[查询理解层]\n B --> C{检索策略选择}\n C -->|混合模式| D[向量检索分支]\n C -->|混合模式| E[稀疏检索分支]\n C -->|混合模式| F[图扩展分支]\n D --> G[结果融合]\n E --> G\n F --> G\n G --> H[重排序 Rerank]\n H --> I[Token 预算打包]\n I --> J[渲染 Render]\n J --> K[LLM 上下文输出]\n \n L[配置参数] --> B\n L --> D\n L --> E\n L --> F\n L --> H\n```\n\n## 核心组件\n\n### 检索器（Retriever）\n\nRetriever 是检索系统的主入口，负责协调各个检索分支的执行和结果融合。\n\n| 组件 | 职责 |\n|------|------|\n| `Query` | 查询结构体，包含查询文本和检索参数 |\n| `Retriever` | 主检索器，协调向量、稀疏、图扩展三种检索 |\n| `BruteForceVectorIndex` | 向量索引，支持暴力搜索和 ANN 近似搜索 |\n| `QueryEncoder` | 查询编码器，将自然语言查询转换为向量 |\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs]()\n资料来源：[crates/mnem-core/src/retrieve/retriever.rs]()\n\n### 向量检索（Vector Retrieval）\n\n向量检索使用密集向量表示来衡量语义相似性。mnem 采用 HNSW（Hierarchical Navigable Small World）算法实现近似最近邻搜索。\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `vector_cap` | 向量检索返回的最大结果数 | - |\n| `limit` | 总体检索结果限制 | - |\n\n**HNSW 算法特点**：\n\n- 分层结构：构建多层跳表式图结构\n- 贪心搜索：从顶层向下逐层搜索\n- 参数控制：ef_search、ef_construction、m_max 等影响精度和性能\n\n资料来源：[crates/mnem-ann/src/hnsw.rs]()\n资料来源：[crates/mnem-core/src/index/vector.rs]()\n\n### 稀疏检索（Sparse Retrieval）\n\n稀疏检索基于词项精确匹配，适合处理专有名词、代码标识符等精确查询场景。\n\n| 特性 | 说明 |\n|------|------|\n| BM25 算法 | 基于词频和文档频率的概率排名 |\n| 倒排索引 | 高效的词项到文档映射 |\n| 动态权重 | 根据查询词项在文档中的重要性调整 |\n\n稀疏检索与向量检索形成互补：向量检索擅长语义相似性，稀疏检索擅长精确词项匹配。\n\n资料来源：[crates/mnem-core/src/index/sparse.rs]()\n\n### 图扩展（Graph Expansion）\n\n图扩展利用知识图谱的结构信息进行检索扩展。\n\n| 参数 | 说明 |\n|------|------|\n| `graph_expand` | 图扩展的邻居节点数量 |\n| `graph_depth` | 图遍历的最大深度 |\n| `graph_decay` | 距离衰减系数，控制远处节点的影响力 |\n\n图扩展的工作原理：\n\n1. 从初始检索结果中的节点开始\n2. 沿着边扩展到相邻节点\n3. 根据 `graph_decay` 衰减权重\n4. 重复直到达到 `graph_depth`\n\n资料来源：[crates/mnem-cli/src/config.rs]()\n\n## 结果融合策略\n\n当启用混合检索时，需要将多个检索分支的结果进行融合。mnem 采用基于分数的加权融合策略。\n\n### 融合算法\n\n```mermaid\ngraph LR\n A[向量分数
Vector Score] --> D[分数归一化]\n B[稀疏分数
Sparse Score] --> D\n C[图扩展分数
Graph Score] --> D\n D --> E[权重加权]\n E --> F[分数合并]\n F --> G[排序输出]\n \n H[配置权重] --> E\n```\n\n融合分数计算公式：\n\n```\nfinal_score = w_vector × norm_vector + w_sparse × norm_sparse + w_graph × norm_graph\n```\n\n其中归一化方法采用 Min-Max 归一化：\n\n```\nnorm(x) = (x - min) / (max - min)\n```\n\n资料来源：[crates/mnem-core/src/retrieve/fusion.rs]()\n\n### 重排序（Rerank）\n\n融合后的候选结果会通过重排序模型进一步优化顺序。\n\n| 配置项 | 说明 |\n|--------|------|\n| `rerank.top_k` | 重排序后保留的结果数 |\n| `rerank.model` | 重排序模型名称 |\n| `rerank.base_url` | 重排序 API 端点 |\n| `rerank.api_key_env` | API 密钥环境变量 |\n\n支持的 Rerank 提供商：\n\n- **Cohere**：Cohere Rerank API\n- **Voyage**：Voyage AI Rerank API\n- **Jina**：Jina AI Rerank API\n\n资料来源：[crates/mnem-cli/src/config.rs]()\n\n## Token 预算管理\n\n检索系统的一个核心挑战是在严格的 token 预算内最大化信息价值。\n\n### 预算控制参数\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| `budget` | 检索结果的总 token 预算上限 | 动态计算 |\n\n### 预算打包算法\n\n1. **按分数排序**：根据融合分数降序排列候选 chunks\n2. **贪心选择**：依次添加 chunks 直到达到 budget 限制\n3. **上下文优先**：优先保留高相关性、高信息密度的 chunks\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs]()\n\n## 渲染与输出\n\n检索结果最终需要渲染为适合 LLM 消费的格式。mnem 采用 YAML 风格的确定性渲染格式。\n\n### 渲染格式规范\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n...\n```\n\n**渲染规则**：\n\n- `ntype` 和 `id` 始终输出\n- `context`（上下文句子）在 `summary` 之前输出，符合 Anthropic 2024 contextual-retrieval 最佳实践\n- `summary` 长度默认限制在 8192 字符内，可通过 `MNEM_RENDER_SUMMARY_CAP_CHARS` 环境变量覆盖\n- 标量属性（String、Integer、Float、Bool）按 BTreeMap 顺序输出\n- 非标量属性（Link、Map、List、Bytes、Null）跳过，避免上下文膨胀\n- 原始 `content` 字节永不出现在渲染输出中\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs]()\n\n## 配置参考\n\n### 检索配置示例\n\n```toml\n[retrieve]\nlimit = 50 # 最大返回结果数\nbudget = 8192 # token 预算上限\nvector_cap = 100 # 向量检索候选数\ngraph_expand = 5 # 图扩展邻居数\ngraph_decay = 0.5 # 图距离衰减系数\ngraph_depth = 2 # 图遍历深度\nrerank_top_k = 10 # 重排序后保留数\nhyde_max_tokens = 512 # HyDE 生成的最大 token 数\n\n[rerank]\nprovider = \"cohere\" # rerank 提供商\nmodel = \"rerank-english-v2.0\"\nbase_url = \"https://api.cohere.com\"\napi_key_env = \"COHERE_API_KEY\"\n\n[llm]\nprovider = \"openai\" # LLM 提供商（用于 HyDE 等功能）\nmodel = \"gpt-4\"\n```\n\n### 环境变量\n\n| 环境变量 | 说明 |\n|----------|------|\n| `MNEM_RENDER_SUMMARY_CAP_CHARS` | 渲染时 summary 的最大字符数，默认 8192 |\n\n## 与其他模块的交互\n\n### 数据依赖\n\n```mermaid\ngraph TD\n subgraph Ingest Pipeline\n A[Markdown/PDF/Code] --> B[Chunker]\n B --> C[Section/Chunk]\n C --> D[Extractor]\n D --> E[Index Builder]\n end\n \n subgraph Retrieval\n E --> F[Vector Index]\n E --> G[Sparse Index]\n E --> H[Graph Index]\n F --> I[Retriever]\n G --> I\n H --> I\n I --> J[LLM Context]\n end\n \n subgraph Storage\n E --> K[Blockstore]\n I --> K\n end\n```\n\n检索系统依赖 Ingest Pipeline 构建的索引结构：\n\n1. **分块（Chunking）**：文档被分割为可检索的 chunks\n2. **索引构建**：创建向量索引、稀疏索引和图索引\n3. **存储持久化**：索引数据存储在 Blockstore 中\n\n资料来源：[crates/mnem-ingest/src/chunk.rs]()\n资料来源：[crates/mnem-core/src/index/mod.rs]()\n\n### Chunker 与检索的配合\n\n不同类型的源文档采用不同的分块策略：\n\n| 源类型 | Chunker 类型 | 参数 |\n|--------|--------------|------|\n| Markdown | Paragraph | - |\n| Text | SentenceRecursive | max_tokens: 256, overlap: 32 |\n| PDF | SentenceRecursive | max_tokens: 512, overlap: 64 |\n| Conversation | Session | max_messages: 10 |\n| Code | Structural | - |\n\n资料来源：[crates/mnem-ingest/src/chunk.rs]()\n\n## 最佳实践\n\n### 1. 混合检索配置建议\n\n对于通用场景，推荐使用默认配置：\n\n```toml\n[retrieve]\nlimit = 50\nbudget = 8192\nvector_cap = 100\n```\n\n### 2. 精确查询优化\n\n当查询包含大量专有名词或代码标识符时，启用稀疏检索分支：\n\n- 稀疏检索对精确词项匹配更有效\n- 与向量检索组合使用可兼顾语义和精确性\n\n### 3. 图感知查询\n\n对于需要关系推理的查询，增加图扩展参数：\n\n```toml\n[retrieve]\ngraph_expand = 10\ngraph_depth = 3\ngraph_decay = 0.7\n```\n\n### 4. Token 预算规划\n\n- 高频短查询：`budget` 可设置较低（如 4096）\n- 深度分析查询：`budget` 可提高至 16384\n- 结合 `rerank.top_k` 控制重排序计算量\n\n## 总结\n\nmnem 的混合检索系统通过融合向量检索、稀疏检索和图扩展三大策略，结合重排序和 token 预算管理，为 Agent 提供了灵活且高效的检索能力。系统设计遵循确定性原则，确保相同查询始终产生稳定的输出格式，便于 LLM 理解和处理。\n\n检索系统的配置高度可定制，开发者可根据具体应用场景调整各分支的权重和参数，在检索精度、响应速度和 token 效率之间取得最佳平衡。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：Uranid/mnem\n\n摘要：发现 8 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[feature] hermes support。\n\n## 1. 安全/权限坑 · 来源证据：[feature] hermes support\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[feature] hermes support\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c54919b2b8b340438a9e5aa17291b93a | https://github.com/Uranid/mnem/issues/27 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\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:1221867246 | https://github.com/Uranid/mnem | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：[bug] Broken docs links: SPEC.md, ROADMAP.md, and Architecture page\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[bug] Broken docs links: SPEC.md, ROADMAP.md, and Architecture page\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5c74e7a10f774af6b0460b5da009d1b4 | https://github.com/Uranid/mnem/issues/23 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 4. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1221867246 | https://github.com/Uranid/mnem | last_activity_observed missing\n\n## 5. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1221867246 | https://github.com/Uranid/mnem | no_demo; severity=medium\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1221867246 | https://github.com/Uranid/mnem | no_demo; severity=medium\n\n## 7. 维护坑 · 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:1221867246 | https://github.com/Uranid/mnem | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1221867246 | https://github.com/Uranid/mnem | release_recency=unknown\n\n\n",
"markdown_key": "mnem",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1221867246",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Uranid/mnem"
},
{
"evidence_id": "art_019fe669d31c4feeba30b494eebe6096",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/Uranid/mnem#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mnem 说明书",
"toc": [
"https://github.com/Uranid/mnem 项目说明书",
"目录",
"项目介绍",
"概述",
"核心定位",
"系统架构",
"数据接入流程",
"实体与关系提取",
"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": "1dfa0d9e928a5da11c03eb0389b6d5ee7c8e7388",
"repo_inspection_error": null,
"repo_inspection_files": [
"Dockerfile",
"README.md",
"docker-compose.yml",
"docs/system-prompt.md",
"docs/SPEC.md",
"docs/book.toml",
"docs/README.md",
"docs/ROADMAP.md",
"docs/src/SUMMARY.md",
"docs/src/cli.md",
"docs/src/quickstart.md",
"docs/src/configuration.md",
"docs/src/install.md",
"docs/src/introduction.md",
"docs/src/core-concepts.md",
"docs/src/mcp.md",
"docs/features/content-addressing.md",
"docs/features/integrations.md",
"docs/features/single-binary.md",
"docs/features/token-transparency.md",
"docs/features/hybrid-retrieval.md",
"docs/features/versioned-memory.md",
"docs/features/deterministic-ingest.md",
"docs/features/providers.md",
"docs/features/skills-graph.md",
"docs/features/rich-ingest.md",
"docs/features/benchmarks.md",
"docs/features/wasm-edge.md",
"docs/src/migrations/v0.x-to-v0.1.0.md",
"docs/src/guides/ingest.md",
"docs/src/guides/embed-providers.md",
"docs/src/comparisons/graphify.md",
"docs/src/comparisons/mem0.md",
"docs/src/comparisons/letta.md",
"docs/src/comparisons/mempalace.md",
"docs/src/comparisons/supermemory.md",
"docs/src/comparisons/README.md",
"docs/src/comparisons/cognee.md",
"docs/src/benchmarks/methodology.md",
"docs/src/benchmarks/results.md"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"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": "# mnem-cli - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 mnem-cli 编译的 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_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `docs/src/install.md`, `docs/src/quickstart.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install mnem-cli # gives you the` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `pip install mnem-py # Python library — import with` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npm install -g mnem-cli` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx mnem-cli --version` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `pip install mnem-cli` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0007` supported 0.86\n- `git clone https://github.com/Uranid/mnem` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install mnem-py # package name on PyPI; import name is pymnem` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install sentence-transformers # brings ~200 MB of deps (torch, transformers) — one-time download` 证据：`README.md` Claim：`clm_0010` supported 0.86\n- `curl -L https://github.com/Uranid/mnem/releases/latest/download/mnem-linux-x86_64.tar.gz | tar xz` 证据：`docs/src/install.md` Claim：`clm_0011` supported 0.86\n- `curl http://127.0.0.1:9876/v1/retrieve -d '{\"text\": \"what does this do\"}'` 证据：`docs/src/quickstart.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `docs/src/install.md`, `docs/src/quickstart.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `docs/src/install.md`, `docs/src/quickstart.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/src/install.md`, `docs/src/quickstart.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.es.md`, `README.md`, `README.zh-CN.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\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_0013` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `docs/src/install.md`, `docs/src/quickstart.md` Claim：`clm_0014` 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- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `docs/src/install.md`, `docs/src/quickstart.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：579\n- 重要文件覆盖：40/579\n- 证据索引条目：80\n- 角色 / Skill 条目：77\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请基于 mnem-cli 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 mnem-cli 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 mnem-cli 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 77 个角色 / Skill / 项目文档条目。\n\n- **mnem documentation**（project_doc）：- Source : src/ ./src/SUMMARY.md - Build : mdbook build docs/ output to docs/book/ - Online : rendered site link added post-launch 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **Comparisons**（project_doc）：How mnem stacks up against other agent-memory and knowledge-graph systems. Each comparison is honest: where they win, where mnem wins, when to pick which. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/README.md`\n- **Install**（project_doc）：mnem ships a single mnem binary plus optional Python and HTTP daemons. Pick the source that matches your platform. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/install.md`\n- **The Problem**（project_doc）：! License: Apache-2.0 https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge LICENSE ! CI https://img.shields.io/github/actions/workflow/status/Uranid/mnem/ci.yml?style=for-the-badge&label=CI https://github.com/Uranid/mnem/actions/workflows/ci.yml ! crates.io https://img.shields.io/crates/v/mnem-cli?style=for-the-badge https://crates.io/crates/mnem-cli ! PyPI https://img.shields.io/pypi/v/mnem-cli… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Benchmarks**（project_doc）：Reproducible head-to-head numbers for mnem. Every number ships with the harness, the dataset, and the raw artifacts. If you can't reproduce a number, that's a bug. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`benchmarks/README.md`\n- **mnem fuzz harness**（project_doc）：Coverage-guided fuzz targets for mnem's highest-value parsers. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`fuzz/README.md`\n- **mnem brand assets**（project_doc）：Minimal, deliberately simple. Two colors, one geometric mark, one wordmark. Everything else is composition. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`assets/logo/README.md`\n- **mnem-ann**（project_doc）：Approximate-nearest-neighbour HNSW vector index for mnem. Feature-gated alternative to the built-in brute-force index in mnem-core . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-ann/README.md`\n- **mnem-backend-redb**（project_doc）：Production embedded-KV backend for mnem - redb-backed Blockstore and OpHeadsStore . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-backend-redb/README.md`\n- **mnem-bench**（project_doc）：Benchmark harness for mnem. Ships the runner, dataset cache, LongMemEval / LoCoMo / ConvoMem / MemBench / hybrid-v4 scorers, the cpu-local mnem adapter, the bundled ONNX MiniLM-L6-v2 embedder, and the mnem bench interactive TUI. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-bench/README.md`\n- **mnem-cli**（project_doc）：Command-line interface for mnem - Git for AI Agent Knowledge. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-cli/README.md`\n- **mnem-core-testutils**（project_doc）：Shared test fixtures for the mnem workspace. Internal use only; never published to crates.io publish = false in Cargo.toml . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-core-testutils/README.md`\n- **mnem-core**（project_doc）：Content-addressed versioned substrate for AI agent memory - the core of mnem. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-core/README.md`\n- **mnem-embed-providers**（project_doc）：Embedding-provider adapters for mnem OpenAI, Ollama . Sync, TLS-via-rustls, tokio-free. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-embed-providers/README.md`\n- **mnem-extract**（project_doc）：Extraction strategies for mnem ingest pipelines. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-extract/README.md`\n- **mnem-graphrag**（project_doc）：Extractive community summarization: Centroid + MMR . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-graphrag/README.md`\n- **mnem http**（project_doc）：HTTP JSON API for mnem - REST surface over the core repo operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-http/README.md`\n- **mnem-ingest**（project_doc）：Ingest pipeline for mnem : converts external source artifacts Markdown, plain text, and - in later sub-waves - PDFs and chat conversations into content-addressed memory graphs. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-ingest/README.md`\n- **mnem-llm-providers**（project_doc）：Text-generation adapters for mnem OpenAI chat, Ollama chat for HyDE, multi-query, and future LLM-in-the-loop features. Sync, TLS-via-rustls, tokio-free. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-llm-providers/README.md`\n- **mnem mcp**（project_doc）：Model Context Protocol server for mnem - the AI-native, local-first memory substrate for agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-mcp/README.md`\n- **mnem-ner-providers**（project_doc）：NER provider adapters for mnem. Ships RuleNer heuristic, zero-dependency and NullNer . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-ner-providers/README.md`\n- **mnem Python**（project_doc）：Python bindings for mnem https://github.com/Uranid/mnem - Git for AI Agent Knowledge. A persistent, versioned knowledge layer for AI agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-py/README.md`\n- **mnem-rerank-providers**（project_doc）：Cross-encoder reranker adapters for mnem Cohere, Voyage, Jina . Sync, TLS-via-rustls, tokio-free. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-rerank-providers/README.md`\n- **mnem-sparse-providers**（project_doc）：Learned-sparse encoder adapters for mnem SPLADE, BGE-M3-sparse, opensearch-doc-v3-distill . Sync, TLS-via-rustls, tokio-free. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-sparse-providers/README.md`\n- **mnem-transport**（project_doc）：Offline transport for mnem: CAR v1 export/import of content-addressed subtrees, plus the frozen shapes of the remote wire protocol. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`crates/mnem-transport/README.md`\n- **mnem-cli**（project_doc）：Git for AI Agent Knowledge. A persistent, versioned knowledge layer for AI agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`npm-packages/mnem-cli/README.md`\n- **mnem-cli pip**（project_doc）：On first run mnem downloads the correct prebuilt binary for your platform from the GitHub release https://github.com/Uranid/mnem/releases and caches it in ~/.mnem cli/ . Subsequent calls run the cached binary directly. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`py-packages/mnem-cli/README.md`\n- **Contributing to mnem**（project_doc）：Thanks for your interest. mnem is an early-stage project, and the format spec is deliberately locked down - the whole value proposition is that two independent implementations produce byte-identical objects. This guide exists to keep contributions aligned with that bar. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **mnem Roadmap**（project_doc）：Planned work is tracked in GitHub Issues https://github.com/Uranid/mnem/issues and labelled by phase. The rough arc: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ROADMAP.md`\n- **mnem Format Specification**（project_doc）：Version: 0.1 Status: canonical - implementations MUST conform. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/SPEC.md`\n- **mnem system prompt**（project_doc）：This is the recommended system prompt to add to your agent host Claude Desktop, Claude Code, Cursor, Continue, Zed, Gemini CLI, ... so the LLM uses mnem transparently on every turn - without the user ever having to mention mnem. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/system-prompt.md`\n- **Benchmarks**（project_doc）：mnem is measured head-to-head against mem0 and MemPalace on six public datasets. All numbers are reproducible with the shipped harness. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/benchmarks.md`\n- **Content Addressing**（project_doc）：Every object in mnem - nodes, edges, commits, tree chunks - has an address derived from its content. The same bytes always produce the same address CID , on any machine. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/content-addressing.md`\n- **Deterministic Ingest**（project_doc）：mnem ingests documents without an LLM. The same bytes always produce the same nodes, on any machine. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/deterministic-ingest.md`\n- **Hybrid Retrieval**（project_doc）：mnem retrieves across three lanes simultaneously and fuses the results: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/hybrid-retrieval.md`\n- **Integrations**（project_doc）：mnem exposes the same retrieval engine through four interfaces. Pick whichever fits your stack - they all hit the same graph. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/integrations.md`\n- **Provider Configuration**（project_doc）：mnem ships with a bundled ONNX MiniLM-L6-v2 embedder that runs in-process. No Ollama, no API keys, no configuration needed to get started. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/providers.md`\n- **Rich Ingest Pipeline**（project_doc）：mnem produces semantically coherent chunks from any source file - not arbitrary text windows. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/rich-ingest.md`\n- **Single Binary**（project_doc）：The mnem binary is ~40 MB and self-contained. There is no daemon to start, no cloud account to create, no database server to manage. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/single-binary.md`\n- **Skills Graph**（project_doc）：Agent conventions today live in flat files - .cursorrules , AGENTS.md , CLAUDE.md . They're useful, but they have no structure: you can't query them, diff them against a teammate's, branch them for an experiment, or merge two versions together. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/skills-graph.md`\n- **Token Transparency**（project_doc）：Every mnem retrieve response includes three counters that no other agent-memory system exposes: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/token-transparency.md`\n- **Versioned Memory**（project_doc）：mnem treats every write as a commit - the same way git treats every save as a snapshot. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/versioned-memory.md`\n- **WASM and Edge Deployment**（project_doc）：mnem-core - the retrieval and storage engine - has no tokio, no filesystem calls, and no network dependencies. The same code that runs on your laptop compiles unchanged to wasm32 . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/features/wasm-edge.md`\n- **v0.3 to v0.4 migration guide**（project_doc）：Dense embedding vectors are no longer stored inline on Node bytes. They now live in a per-commit Prolly sidecar tree Commit.embeddings , keyed by NodeCid . This makes NodeCid byte-identical across machines regardless of embedder thread counts or floating-point reduction order. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/migrations/0.3-to-0.4.md`\n- **v0.4 to v0.5 migration guide**（project_doc）：Sparse embedding vectors SPLADE, BGE-M3-sparse, etc. are no longer stored inline on Node bytes. They now live in a per-commit Prolly sidecar tree Commit.sparse , keyed by NodeCid . This mirrors the G16 change that moved dense embeddings to Commit.embeddings . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guide/migrations/0.4-to-0.5.md`\n- **Summary**（project_doc）：- Install ./install.md - Quickstart ./quickstart.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/SUMMARY.md`\n- **Methodology**（project_doc）：Every published number ships with the harness, the dataset hash, and the raw artifacts. If you cannot reproduce a number, that is a bug. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/benchmarks/methodology.md`\n- **Reproduce**（project_doc）：End-to-end recipe to regenerate the 0.1.0 benchmark numbers locally. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/benchmarks/reproduce.md`\n- **Results**（project_doc）：mnem vs MemPalace published numbers. Dense retrieval vector + top-k . No LLM rerank. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/benchmarks/results.md`\n- **Run benchmarks locally with mnem bench**（project_doc）：Run benchmarks locally with mnem bench 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/benchmarks/run-locally.md`\n- **CLI reference**（project_doc）：mnem is the single entry point. Subcommands wrap repo operations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/cli.md`\n- **mnem vs Cognee**（project_doc）：Cognee: \"Knowledge Engine for AI Agent Memory in 6 lines of code\" repo description, topoteretes/cognee mnem: a content-addressed, versioned graph substrate that ingests without an LLM. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/cognee.md`\n- **mnem vs graphify**（project_doc）：graphify: \"AI coding assistant skill Claude Code, Codex, OpenCode, ... . Turn any folder of code, docs, papers, images, or videos into a queryable knowledge graph.\" repo description, safishamsi/graphify mnem: a content-addressed graph substrate. graphify builds a graph from a folder; mnem is the graph. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/graphify.md`\n- **mnem vs Letta**（project_doc）：Letta: \"Letta is the platform for building stateful agents: AI with advanced memory that can learn and self-improve over time.\" repo description, letta-ai/letta mnem: a content-addressed graph substrate that stores the memory an agent uses, without assuming the agent. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/letta.md`\n- **mnem vs mem0**（project_doc）：mem0: \"Universal memory layer for AI Agents\" repo description, mem0ai/mem0 mnem: a content-addressed, versioned graph substrate underneath the memory layer. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/mem0.md`\n- **mnem vs MemPalace**（project_doc）：MemPalace: \"The best-benchmarked open-source AI memory system. And it's free.\" repo description, MemPalace/mempalace mnem: a content-addressed, versioned graph substrate that shares MemPalace's no-LLM-on-write philosophy and pushes further on identity and history. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/mempalace.md`\n- **mnem vs Supermemory**（project_doc）：Supermemory: \"Memory engine and app that is extremely fast, scalable. The Memory API for the AI era.\" repo description, supermemoryai/supermemory mnem: an open-source, embedded, content-addressed knowledge-graph substrate. Self-host or nothing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/comparisons/supermemory.md`\n- **Configuration**（project_doc）：mnem reads config from three sources, in priority order: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/configuration.md`\n- **Core concepts**（project_doc）：Three primitives. Everything else is composed from these. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/core-concepts.md`\n- **Embedding providers**（project_doc）：mnem decouples embedder from store. Switch providers without re-ingesting. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/guides/embed-providers.md`\n- **Ingest pipeline**（project_doc）：mnem ingest is the only path content takes into the graph. The pipeline: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/guides/ingest.md`\n- **Introduction**（project_doc）：mnem is a knowledge-graph substrate. It stores nodes as content-addressed objects, retrieves them with vector + sparse + graph signals, and exposes the result over CLI, HTTP, and MCP surfaces. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/introduction.md`\n- **MCP server**（project_doc）：mnem implements the Model Context Protocol https://modelcontextprotocol.io over stdio. Drop it into any MCP client Claude Desktop, Cursor, Zed, custom . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/mcp.md`\n- **Migrating to 0.1.0**（project_doc）：0.1.0 is the first public release. There is no prior public version; this document exists for completeness and to fix the upgrade pathway forward. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/migrations/v0.x-to-v0.1.0.md`\n- **Quickstart**（project_doc）：Five minutes from zero to retrieve. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/src/quickstart.md`\n- **What this PR does**（project_doc）：- Bug fix non-breaking - New feature non-breaking - Breaking change API or wire-format - Documentation only - CI / tooling only - Refactor no behavior change 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Changelog**（project_doc）：Initial public release. Versioned, mergeable, content-addressed knowledge graph for AI agent memory. Local-first, Apache-2.0. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **El problema**（project_doc）：! License: Apache-2.0 https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge LICENSE ! CI https://img.shields.io/github/actions/workflow/status/Uranid/mnem/ci.yml?style=for-the-badge&label=CI https://github.com/Uranid/mnem/actions/workflows/ci.yml ! crates.io https://img.shields.io/crates/v/mnem-cli?style=for-the-badge https://crates.io/crates/mnem-cli ! PyPI https://img.shields.io/pypi/v/mnem-cli… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.es.md`\n- **问题所在**（project_doc）：! License: Apache-2.0 https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge LICENSE ! CI https://img.shields.io/github/actions/workflow/status/Uranid/mnem/ci.yml?style=for-the-badge&label=CI https://github.com/Uranid/mnem/actions/workflows/ci.yml ! crates.io https://img.shields.io/crates/v/mnem-cli?style=for-the-badge https://crates.io/crates/mnem-cli ! PyPI https://img.shields.io/pypi/v/mnem-cli… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.zh-CN.md`\n- **Security policy**（project_doc）：Pre-launch baseline. Only 0.1.x on main receives fixes; older in-development versions are unsupported. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Fuzz crash-regression policy**（project_doc）：When a fuzz run hits a crash locally or in nightly CI , the input must land as a permanent regression seed so the same shape can never re-crash silently. The flow is short and mechanical. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`fuzz/REGRESSIONS.md`\n- **Question**（project_doc）： HTTP\n HTTP --> MCP\n CLI --> mnem-core\n HTTP --> mnem-core\n MCP --> mnem-core\n mnem-core --> mnem-ingest\n```\n\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n\n### 核心对象模型\n\n```\n资料来源：[crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n```\n\n| 对象类型 | 用途 |\n|---------|------|\n| **Node** | 图中的顶点，包含摘要、属性、上下文句子和可选内容 |\n| **Edge** | 图中的边，连接两个 Node，支持关系类型标签 |\n| **Commit** | 快照，包含一次操作后图的完整视图 |\n| **Operation** | 操作记录，包含时间戳、作者、签名等元信息 |\n| **View** | 读取视角，持有 heads 引用 |\n\n## 数据接入流程\n\n当用户向 Mnem 导入文档时，数据会经过以下处理流程：\n\n```mermaid\ngraph LR\n A[原始文档] --> B[格式检测]\n B --> C{解析器选择}\n C -->|Markdown| D[parse_markdown]\n C -->|PDF| E[pdf 文本提取]\n C -->|代码| F[tree-sitter 解析]\n C -->|会话| G[JSON/JSONL 解析]\n D --> H[Section 列表]\n E --> H\n F --> H\n G --> H\n H --> I[分块策略]\n I --> J[Chunk 向量]\n J --> K[实体提取]\n K --> L[关系提取]\n L --> M[Transaction 提交]\n```\n\n资料来源：[crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n\n### 支持的源格式\n\n| 扩展名 | 源类型 | 默认分块策略 |\n|-------|--------|-------------|\n| `.md` / `.markdown` | Markdown | Paragraph |\n| `.txt` | 纯文本 | SentenceRecursive (256 tokens) |\n| `.pdf` | PDF | SentenceRecursive (512 tokens) |\n| `.json` / `.jsonl` | 会话记录 | Session (10 条消息) |\n| `.rs` / `.py` / `.js` / `.ts` 等 | 代码 | Structural |\n\n资料来源：[crates/mnem-ingest/src/pipeline.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pipeline.rs)\n\n### 分块策略详解\n\n```\n资料来源：[crates/mnem-ingest/src/chunk.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/chunk.rs)\n```\n\n| 策略 | 说明 | 适用场景 |\n|------|------|---------|\n| **Paragraph** | 按双换行分割 | Markdown 文档 |\n| **Recursive** | 词窗口滑动，固定 overlap | 通用场景（向后兼容） |\n| **SentenceRecursive** | 基于 Unicode 句子边界（UAX #29）打包 | 纯文本、PDF |\n| **Session** | 按对话轮次分组，边界在角色返回 user 时触发 | 会话记录 |\n| **Structural** | 每 section 一个 chunk | 代码（函数/类级别） |\n\n## 实体与关系提取\n\nMnem 提供了多层次的实体和关系提取能力：\n\n```\n资料来源：[crates/mnem-ingest/src/extract.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/extract.rs)\n```\n\n| 提取器 | 描述 |\n|--------|------|\n| **RuleExtractor** | 基于规则的提取，使用正则和启发式方法 |\n| **KeyBertAdapter** | 使用 KeyBERT 进行统计实体识别（需启用 `keybert` feature） |\n| **LLM Extractor** | 使用 Ollama LLM 进行提取（需启用 `ollama` feature） |\n\n### Sidecar 提取器\n\n支持外部提取服务：\n\n```toml\n# Cargo.toml\nmnem-ingest = { features = [\"sidecar-docling\"] } # 或 [\"sidecar-unstructured\"]\n```\n\n资料来源：[crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n\n## 检索系统\n\nMnem 提供了一套专为 Agent 设计的多阶段检索管道：\n\n```\n资料来源：[crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n```\n\n```mermaid\ngraph TD\n Q[用户查询] --> F[过滤阶段]\n F --> V[向量检索]\n V --> S[稀疏检索]\n S --> R[重排序]\n R --> P[Token 预算打包]\n P --> R[最终结果]\n```\n\n### 检索配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `retrieve.limit` | - | 最大返回结果数 |\n| `retrieve.budget` | - | Token 预算上限 |\n| `retrieve.vector_cap` | - | 向量检索结果数上限 |\n| `retrieve.graph_expand` | - | 图扩展节点数 |\n| `retrieve.graph_depth` | - | 图扩展深度 |\n| `retrieve.rerank_top_k` | - | 重排序候选数 |\n| `retrieve.hyde_max_tokens` | - | HyDE 最大生成 Token 数 |\n\n资料来源：[crates/mnem-cli/src/config.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/config.rs)\n\n## 版本化与分支\n\nMnem 使用 DAG 结构存储版本历史，每次提交产生一个新的 Commit 节点：\n\n```mermaid\ngraph LR\n A[Commit A] --> B[Commit B]\n B --> C[Commit C]\n C --> D[Commit D]\n B --> E[Commit E
分支]\n E --> F[Commit F]\n D --> G[Commit G]\n```\n\n| 概念 | 说明 |\n|------|------|\n| **Head** | 当前分支的最新提交 |\n| **Branch** | 通过 refs 引用的命名指针 |\n| **Merge** | 检测两个分支的冲突并合并 |\n\n资料来源：[crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n\n### 冲突检测\n\n```\n资料来源：[crates/mnem-core/src/repo/conflict.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/conflict.rs)\n```\n\nMnem 支持基于策略的合并冲突检测：\n\n| 策略 | 说明 |\n|------|------|\n| `ConflictPolicy::Default` | 标准的冲突检测 |\n| `ConflictPolicy::Manual` | 手动解决冲突 |\n\n## 密码学安全\n\n```\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n```\n\n| 组件 | 功能 |\n|------|------|\n| **Signer** | 使用 Ed25519 对 Operation 进行签名 |\n| **Verifier** | 验证签名有效性 |\n| **RevocationList** | 支持吊销列表验证 |\n\n## CLI 命令\n\n```\n资料来源：[crates/mnem-cli/src/commands/ingest.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/ingest.rs)\n```\n\n| 命令 | 功能 |\n|------|------|\n| `mnem init` | 初始化新仓库 |\n| `mnem ingest ` | 导入文档 |\n| `mnem get ` | 获取节点详情 |\n| `mnem query ` | 语义检索 |\n| `mnem branch` | 分支管理 |\n| `mnem merge` | 合并分支 |\n| `mnem integrate` | 集成到 AI 工具（Claude Code、Cursor 等） |\n\n### 常用 ingest 选项\n\n```bash\nmnem ingest notes.md # 自动检测格式\nmnem ingest --chunker recursive --max-tokens 1024 book.pdf\nmnem ingest --recursive docs/ # 递归导入目录\nmnem ingest --text \"Hello world\" # 导入纯文本\n```\n\n## HTTP API\n\n```\n资料来源：[crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n```\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/v1/nodes` | GET | 获取节点列表 |\n| `/v1/nodes/{id}` | GET | 获取指定节点 |\n| `/v1/ingest` | POST | 导入文档 |\n| `/v1/branches` | GET | 获取分支列表 |\n| `/v1/branches` | POST | 创建分支 |\n| `/v1/retrieve` | POST | 检索 |\n\n## MCP Server\n\nMnem 提供了 MCP（Model Context Protocol）集成，支持 AI 工具直接访问知识图谱：\n\n```mermaid\ngraph LR\n A[Claude Code / Cursor] <--> B[MCP Server]\n B --> C[mnem-core]\n```\n\n资料来源：[crates/mnem-cli/src/integrate.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/integrate.rs)\n\n支持的集成平台：\n\n| 平台 | 配置文件 |\n|------|---------|\n| Claude Code | `~/.claude/CLAUDE.md` |\n| Cursor | `~/.cursor/rules/mnem.mdc` |\n| Continue | `~/.continue/config.json` |\n| Zed | `~/.config/zed/settings.json` |\n| Gemini CLI | `~/.gemini/GEMINI.md` |\n\n## 技术特性\n\n```\n资料来源：[crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n```\n\n| 特性 | 说明 |\n|------|------|\n| `#![forbid(unsafe_code)]` | 完全禁用 unsafe 代码 |\n| 规范编码 | 所有对象支持字节级精确的编解码往返 |\n| DAG-CBOR | 使用 DAG-CBOR 作为主要序列化格式 |\n| Prolly Tree | 用于高效存储和查询的 Prolly Tree 实现 |\n| Tree-sitter | 代码解析支持 10+ 主流编程语言 |\n\n## 使用示例\n\n### 初始化仓库\n\n```bash\nmnem init my-knowledge-base\ncd my-knowledge-base\n```\n\n### 导入文档\n\n```bash\n# 导入 Markdown\nmnem ingest README.md\n\n# 导入 PDF\nmnem ingest --chunker sentence_recursive document.pdf\n\n# 递归导入目录\nmnem ingest --recursive ./docs\n\n# 导入代码文件\nmnem ingest src/main.rs\n```\n\n### 检索知识\n\n```bash\nmnem query \"Mnem 的检索算法是如何工作的？\"\n```\n\n### 分支管理\n\n```bash\nmnem branch create feature-x\nmnem branch switch feature-x\n# ... 进行修改 ...\nmnem commit -m \"添加新功能\"\nmnem merge feature-x\n```\n\n## 总结\n\nMnem 是一个功能完整的本地优先知识图谱系统，特别适合需要持久化记忆的 AI Agent 场景。它通过：\n\n1. **多格式解析** - 支持 PDF、Markdown、代码、会话等\n2. **智能分块** - 针对不同内容类型优化分块策略\n3. **实体提取** - 规则、统计和 LLM 三种提取方式\n4. **版本控制** - DAG 结构支持分支和合并\n5. **可验证性** - Ed25519 签名确保数据完整性\n6. **AI 友好** - 专为 Agent 设计的检索和渲染机制\n\n为开发者提供了一个可靠、可信的知识管理基础设施。\n\n资料来源：[README.zh-CN.md](https://github.com/Uranid/mnem/blob/main/README.zh-CN.md)\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/src/install.md](https://github.com/Uranid/mnem/blob/main/docs/src/install.md)\n- [Dockerfile](https://github.com/Uranid/mnem/blob/main/Dockerfile)\n- [docker-compose.yml](https://github.com/Uranid/mnem/blob/main/docker-compose.yml)\n- [scripts/install.sh](https://github.com/Uranid/mnem/blob/main/scripts/install.sh)\n- [scripts/install.ps1](https://github.com/Uranid/mnem/blob/main/scripts/install.ps1)\n \n\n# 安装指南\n\n本文档详细说明 mnem 项目的各种安装方式、依赖要求以及初始化配置流程。mnem 是一个基于 Rust 构建的知识图谱管理工具，支持 CLI、HTTP 服务和 MCP（Model Context Protocol）三种接入方式。\n\n## 系统要求\n\n### 硬件要求\n\n| 组件 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 内存 | 4 GB | 8 GB 或以上 |\n| 磁盘空间 | 500 MB | 2 GB（用于本地数据库和向量索引） |\n| 处理器 | x86-64 | 多核处理器 |\n\n### 软件依赖\n\nmnem 的核心由 Rust 语言编写，运行时依赖以下组件：\n\n- **Rust 工具链**：建议使用最新稳定版（stable）\n- **OpenSSL**：用于 HTTPS 通信和加密操作\n- **pkg-config**：系统库链接管理\n- **protoc**：Protocol Buffers 编译器（部分功能需要）\n\n资料来源：[crates/mnem-cli/src/main.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/main.rs)\n\n## 安装方式\n\nmnem 提供多种安装途径，可根据使用场景选择合适的方式。\n\n### 方式一：从源码编译安装\n\n#### 前置准备\n\n```bash\n# 安装 Rust 工具链（如尚未安装）\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# 安装系统依赖（Ubuntu/Debian）\nsudo apt-get install -y build-essential pkg-config libssl-dev\n\n# 安装系统依赖（macOS）\nbrew install openssl pkg-config\n```\n\n#### 编译步骤\n\n```bash\n# 克隆仓库\ngit clone https://github.com/Uranid/mnem.git\ncd mnem\n\n# 使用 Cargo 构建所有 crate\ncargo build --release\n\n# 安装二进制文件到 ~/.cargo/bin\ncargo install --path crates/mnem-cli\n```\n\n编译完成后，可执行文件 `mnem` 将被安装到 Cargo 的 bin 目录。\n\n### 方式二：使用安装脚本\n\n项目提供了自动化安装脚本，支持 Linux、macOS 和 Windows。\n\n#### Linux / macOS\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Uranid/mnem/main/scripts/install.sh | bash\n```\n\n脚本会自动检测系统平台，下载或编译对应版本的二进制文件。\n\n#### Windows PowerShell\n\n```powershell\nirm https://raw.githubusercontent.com/Uranid/mnem/main/scripts/install.ps1 | iex\n```\n\n脚本支持 PowerShell 5.1 及以上版本，会将 `mnem.exe` 添加到 PATH 环境变量。\n\n### 方式三：Docker 部署\n\nmnem 支持通过 Docker 容器运行，包含完整的 HTTP 服务和 MCP 服务器。\n\n#### Dockerfile 结构\n\n```dockerfile\n# 使用 Rust 官方镜像作为构建阶段\nFROM rust:1.75 as builder\n\n# 安装构建依赖\nRUN apt-get update && apt-get install -y \\\n pkg-config libssl-dev\n\n# 复制源码并编译\nWORKDIR /app\nCOPY . .\nRUN cargo build --release --bin mnem-http\n\n# 运行阶段使用轻量级镜像\nFROM debian:bookworm-slim\nCOPY --from=builder /app/target/release/mnem-http /usr/local/bin/\nEXPOSE 8080\nCMD [\"mnem-http\"]\n```\n\n资料来源：[Dockerfile](https://github.com/Uranid/mnem/blob/main/Dockerfile)\n\n#### docker-compose 编排\n\n```yaml\nversion: '3.8'\n\nservices:\n mnem:\n build: .\n ports:\n - \"8080:8080\"\n volumes:\n - mnem-data:/data\n environment:\n - MNEM_DATA_DIR=/data\n - OLLAMA_BASE_URL=http://ollama:11434\n restart: unless-stopped\n\n ollama:\n image: ollama/ollama:latest\n volumes:\n - ollama-data:/root/.ollama\n restart: unless-stopped\n\nvolumes:\n mnem-data:\n ollama-data:\n```\n\n资料来源：[docker-compose.yml](https://github.com/Uranid/mnem/blob/main/docker-compose.yml)\n\n#### 启动 Docker 服务\n\n```bash\n# 构建并启动容器\ndocker-compose up -d\n\n# 查看日志\ndocker-compose logs -f mnem\n\n# 停止服务\ndocker-compose down\n```\n\n## 初始化配置\n\n首次使用 mnem 前需要进行仓库初始化和基础配置。\n\n### 仓库初始化\n\n```bash\n# 初始化新的 mnem 仓库\nmnem init\n\n# 指定自定义数据目录\nmnem init --path ~/.my-mnem\n```\n\n初始化命令会在指定目录下创建 `.mnem/` 子目录，包含以下结构：\n\n```\n.mnem/\n├── repo.redb # 主数据库（Redb 键值存储）\n├── config.toml # 用户配置文件\n└── blocks/ # DAG-CBOR 数据块存储\n```\n\n资料来源：[crates/mnem-cli/src/commands/init.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/init.rs)\n\n### 配置文件\n\n初始化后生成的 `config.toml` 包含以下配置项：\n\n```toml\n[user]\n# 用户标识（可选）\nname = \"Your Name\"\nemail = \"your@email.com\"\n\n[llm]\n# Ollama 服务配置\nbase_url = \"http://localhost:11434\"\nmodel = \"llama3.2\"\ntimeout_secs = 120\n\n[ner]\n# 命名实体识别提供者\nprovider = \"rule\" # 可选: \"none\", \"rule\"\n\n[ingest]\n# 默认分块策略\nchunker = \"auto\" # 可选: \"paragraph\", \"recursive\", \"session\", \"structural\"\n```\n\n资料来源：[crates/mnem-cli/src/config.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/config.rs)\n\n### 验证安装\n\n```bash\n# 检查 mnem 版本\nmnem --version\n\n# 查看当前仓库状态\nmnem status\n\n# 列出所有可用命令\nmnem --help\n```\n\n成功安装后，`mnem status` 应显示仓库已初始化且无待提交操作。\n\n## 接入方式\n\nmnem 提供三种主要的接入方式，可根据使用场景选择。\n\n### CLI 模式\n\n命令行模式适合日常笔记记录和知识管理：\n\n```bash\n# 添加节点\nmnem add node -s \"Alice 住在柏林\"\n\n# 添加关系\nmnem add edge --from --to --label 朋友\n\n# 检索知识\nmnem retrieve \"Alice 住在哪里\"\n```\n\n### HTTP 服务模式\n\n通过 HTTP API 提供服务，支持远程访问和程序化集成：\n\n```bash\n# 启动 HTTP 服务（默认端口 8080）\nmnem http serve\n\n# 指定端口\nmnem http serve --port 9090\n\n# 后台运行\nmnem http serve --daemon\n```\n\nAPI 端点示例：\n\n| 方法 | 端点 | 说明 |\n|------|------|------|\n| GET | `/v1/status` | 获取服务状态 |\n| POST | `/v1/nodes` | 创建节点 |\n| GET | `/v1/nodes/{id}` | 获取节点详情 |\n| POST | `/v1/ingest` | 批量导入文档 |\n\n资料来源：[crates/mnem-http/src/handlers.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/src/handlers.rs)\n\n### MCP 模式\n\nMCP（Model Context Protocol）模式允许 AI 助手直接访问 mnem 知识图谱：\n\n```bash\n# 启动 MCP 服务器\nmnem mcp serve\n\n# 配置 Claude Desktop 使用 mnem MCP\n# 编辑 ~/.claude/settings.json\n```\n\n资料来源：[crates/mnem-mcp/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-mcp/src/lib.rs)\n\n## 依赖可选功能\n\nmnem 的部分功能需要额外的依赖库支持。\n\n### 文档解析依赖\n\n| 功能 | 依赖 | 启用方式 |\n|------|------|----------|\n| PDF 解析 | docling | `cargo build --features sidecar-docling` |\n| 高级解析 | unstructured | `cargo build --features sidecar-unstructured` |\n| KeyBERT 向量提取 | keybert | `cargo build --features keybert` |\n| LLM 实体提取 | ollama | `cargo build --features ollama` |\n\n资料来源：[crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n\n### 向量检索依赖\n\nmnem 的检索功能依赖嵌入模型生成向量表示，可通过以下方式配置：\n\n```toml\n[embedder]\n# 本地 Ollama 嵌入模型\nprovider = \"ollama\"\nmodel = \"nomic-embed-text\"\nbase_url = \"http://localhost:11434\"\n```\n\n## 安装流程图\n\n```mermaid\ngraph TD\n A[开始安装] --> B{选择安装方式}\n B -->|源码编译| C[安装 Rust 工具链]\n B -->|安装脚本| D[下载安装脚本]\n B -->|Docker| E[安装 Docker]\n \n C --> F[克隆仓库]\n D --> G[执行安装脚本]\n E --> H[配置 docker-compose]\n \n F --> I[cargo build]\n G --> J[验证二进制]\n H --> K[docker-compose up]\n \n I --> L[初始化仓库]\n J --> L\n K --> L\n \n L --> M[配置 config.toml]\n M --> N{选择接入模式}\n \n N -->|CLI| O[使用 mnem 命令]\n N -->|HTTP| P[启动 http serve]\n N -->|MCP| Q[启动 mcp serve]\n \n O --> R[安装完成]\n P --> R\n Q --> R\n```\n\n## 卸载\n\n### 二进制安装卸载\n\n```bash\n# 删除二进制文件\nrm ~/.cargo/bin/mnem\n\n# 删除配置文件（可选）\nrm -rf ~/.config/mnem\n```\n\n### Docker 卸载\n\n```bash\n# 停止并删除容器\ndocker-compose down -v\n\n# 删除镜像\ndocker rmi mnem-mnem-http\n\n# 删除数据卷\ndocker volume rm mnem_mnem-data\n```\n\n## 常见问题\n\n### 编译失败\n\n如果编译时出现 OpenSSL 相关错误，确保已安装开发库：\n\n```bash\n# Ubuntu/Debian\nsudo apt install libssl-dev\n\n# macOS\nbrew install openssl@3\n```\n\n### 权限问题\n\nLinux/macOS 上如遇到权限错误：\n\n```bash\n# 修复 Cargo bin 目录权限\nchmod +x ~/.cargo/bin/mnem\n```\n\n### 数据库损坏\n\n如遇数据库异常，可尝试重建：\n\n```bash\n# 备份现有数据\nmv ~/.mnem ~/.mnem.bak\n\n# 重新初始化\nmnem init\n```\n\n## 下一步\n\n安装完成后，建议按以下顺序开始使用：\n\n1. 阅读[快速开始指南](./quickstart.md)了解基本操作\n2. 查看[命令参考](./commands.md)获取完整命令列表\n3. 参考[配置文档](./config.md)深入定制功能\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[Crates结构详解](#page-crates-structure), [知识图谱模型](#page-knowledge-graph), [存储后端](#page-storage-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n- [crates/mnem-ingest/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/lib.rs)\n- [crates/mnem-ingest/src/pipeline.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/pipeline.rs)\n- [crates/mnem-ingest/src/types.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/src/types.rs)\n- [crates/mnem-core/src/id/link.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/link.rs)\n \n\n# 系统架构\n\nmnem 是一个基于 Rust 构建的本地优先知识图谱系统，采用内容寻址存储（Content-Addressed Storage）架构，通过 DAG-CBOR 规范实现数据的规范化编解码。该系统支持多端接入，包括命令行界面（CLI）、HTTP API 和 MCP（Model Context Protocol）协议，能够对 Markdown、PDF、代码文件、对话记录等多种格式的文档进行解析、分块、实体提取和语义检索。\n\n## 核心设计原则\n\nmnem 的核心架构遵循以下设计原则，这些原则贯穿整个系统的实现：\n\n1. **无 unsafe 代码**：mnem-core crate 明确禁用所有 unsafe 代码，确保内存安全 资料来源：[crates/mnem-core/src/lib.rs]()`。\n2. **字节级精确编解码**：每个对象类型都保证字节级精确的规范化编码往返特性，即 `decode(encode(x)) == x` 且 `encode(decode(b)) == b` 资料来源：[crates/mnem-core/src/lib.rs]()`。\n3. **幽灵类型安全**：`Link` 通过泛型参数在编译时防止引用类型混淆，例如 `fn parents(&self) -> &[Link]` 拒绝接受 `Link` 资料来源：[crates/mnem-core/src/id/link.rs]()`。\n4. **多端统一解析**：单一规范的解析器实现同时服务于 CLI、HTTP 和 MCP 接入面 资料来源：[crates/mnem-ingest/src/lib.rs]()`。\n\n## 系统分层架构\n\nmnem 系统采用分层架构，各层职责明确，从底层数据存储到顶层用户接口逐层构建。\n\n```mermaid\ngraph TD\n subgraph 用户接入层\n CLI[mnem-cli
命令行工具]\n HTTP[mnem-http
HTTP API]\n MCP[mnem-mcp
MCP Server]\n end\n \n subgraph 核心库层\n CORE[mnem-core
核心数据模型]\n INGEST[mnem-ingest
文档解析与提取]\n end\n \n subgraph 存储层\n STORE[Blockstore
块存储接口]\n VIEW[View
视图快照]\n COMMITS[Commit
提交历史]\n end\n \n CLI --> CORE\n CLI --> INGEST\n HTTP --> CORE\n HTTP --> INGEST\n MCP --> CORE\n MCP --> INGEST\n INGEST --> CORE\n CORE --> STORE\n CORE --> COMMITS\n```\n\n### mnem-core 核心库\n\nmnem-core 是系统的基础核心库，提供所有核心数据结构和算法实现。该库包含以下关键模块 资料来源：[crates/mnem-core/src/lib.rs]()`：\n\n| 模块 | 功能描述 |\n|------|----------|\n| `id` | CID（内容标识符）、ChangeId、OperationId 以及泛型链接类型 Link |\n| `codec` | DAG-CBOR 编解码器和 DAG-JSON 调试导出 |\n| `objects` | Node、Edge、Commit、Operation、View、IndexSet 等核心对象类型 |\n| `prolly` | Prolly 树算法（分块器、构建器、查找、光标、diff、合并） |\n| `store` | Blockstore 和 OpHeadsStore trait 及内存实现 |\n| `repo` | ReadonlyRepo、Transaction 外观类 |\n| `index` | 辅助索引（Query、BruteForceVectorIndex） |\n| `retrieve` | Agent 面向的 Retriever，组合过滤、向量和稀疏排序 |\n| `sign` | Ed25519 签名和撤销列表验证 |\n\n### mnem-ingest 文档解析库\n\nmnem-ingest 负责文档的解析、分块和实体提取工作。该库支持多种文档格式的分阶段处理 资料来源：[crates/mnem-ingest/src/lib.rs]()`：\n\n| 模块 | 功能 |\n|------|------|\n| `md` | CommonMark + GFM Markdown 解析 |\n| `pdf` | 纯 Rust 实现的 PDF 文本层提取 |\n| `code` | 基于 tree-sitter 的代码解析 |\n| `conversation` | ChatGPT/Claude/通用对话导出格式处理 |\n| `text` | 纯文本处理 |\n| `chunk` | 分块策略（Paragraph、Recursive、SentenceRecursive、Session、Structural） |\n| `extract` | 实体和关系提取（RuleExtractor、KeyBertAdapter、LLMExtractor） |\n| `sidecar` | 外部工具集成（docling、unstructured） |\n\n### 用户接入层\n\n系统提供三种主要的用户接入方式：\n\n- **mnem-cli**：命令行工具，支持本地文件的批量导入、检索和图谱管理\n- **mnem-http**：基于 Actix-web 构建的 HTTP API 服务端\n- **mnem-mcp**：Model Context Protocol 服务端，供 AI 代理调用\n\n## 数据模型\n\nmnem 采用 DAG（有向无环图）结构存储知识图谱，核心对象之间通过 CID（内容标识符）相互引用。\n\n### 节点（Node）\n\nNode 是图谱中的基本顶点单元，包含以下关键字段 资料来源：[crates/mnem-core/src/objects/node.rs]()`：\n\n```mermaid\nclassDiagram\n class Node {\n +id: NodeId\n +ntype: String\n +parents: Vec~Link~Commit~~\n +context_sentence: Option~String~\n +summary: Option~String~\n +props: BTreeMap~String, Ipld~\n +content: Option~Bytes~\n +extra: BTreeMap~String, Ipld~\n }\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | NodeId | 节点唯一标识符 |\n| `ntype` | String | 节点类型标签（如 \"Doc\"、\"Section\" 等） |\n| `parents` | Vec> | 父提交链接 |\n| `context_sentence` | Option | 上下文句子（Anthropic 2024 contextual retrieval 设计） |\n| `summary` | Option | LLM 可读的摘要文本，默认截断至 8192 字符 |\n| `props` | BTreeMap | 结构化属性键值对 |\n| `content` | Option | 不透明载荷（如文档体、文件内容） |\n\n### 链接类型（Link）\n\nLink 是一个泛型封装的 CID，提供编译时类型安全保证。在传输层 Link 与普通 CID 字节相同，但泛型参数在 Rust 类型层面防止了错误的引用操作 资料来源：[crates/mnem-core/src/id/link.rs]()`。\n\n### 提交（Commit）与操作（Operation）\n\nCommit 记录图谱的快照状态，Operation 记录具体的变更操作，两者共同构成版本控制的基础。\n\n## 文档解析流程\n\n当用户通过 CLI、HTTP 或 MCP 接入系统进行文档导入时，系统内部执行以下处理流程 资料来源：[crates/mnem-ingest/src/pipeline.rs]()`：\n\n```mermaid\nflowchart LR\n A[原始文件] --> B{文件扩展名检测}\n B -->|md/markdown| C[Markdown解析器]\n B -->|pdf| D[PDF解析器]\n B -->|json/jsonl| E[对话解析器]\n B -->|rs/py/js/ts...| F[Tree-sitter代码解析]\n B -->|其他| G[纯文本解析器]\n \n C --> H{分块策略选择}\n D --> H\n E --> H\n F --> H\n G --> H\n \n H -->|Markdown| I[Paragraph分块]\n H -->|PDF/Text| J[SentenceRecursive分块]\n H -->|Conversation| K[Session分块]\n H -->|Code| L[Structural分块]\n \n I --> M[实体提取]\n J --> M\n K --> M\n L --> M\n \n M --> N[Transaction写入]\n N --> O[Commit提交]\n```\n\n### 源类型自动检测\n\n系统根据文件扩展名自动推断源类型（SourceKind） 资料来源：[crates/mnem-ingest/src/types.rs]()`：\n\n| 扩展名 | SourceKind | 分块策略 |\n|--------|------------|----------|\n| `.md` `.markdown` | Markdown | Paragraph |\n| `.pdf` | Pdf | SentenceRecursive (512 tokens, 64 overlap) |\n| `.txt` | Text | SentenceRecursive (256 tokens, 32 overlap) |\n| `.json` `.jsonl` | Conversation | Session (10 messages) |\n| `.rs` | Code(Rust) | Structural |\n| `.py` `.pyi` | Code(Python) | Structural |\n| `.js` `.mjs` `.cjs` | Code(JavaScript) | Structural |\n| `.ts` `.tsx` | Code(TypeScript) | Structural |\n| `.go` | Code(Go) | Structural |\n| `.java` | Code(Java) | Structural |\n| `.c` `.h` | Code(C) | Structural |\n| `.cpp` `.cc` `.cxx` | Code(Cpp) | Structural |\n| 其他 | Text | SentenceRecursive |\n\n### 分块策略详解\n\n系统提供五种分块策略，适用于不同类型的文档内容 资料来源：[crates/mnem-ingest/src/chunk.rs]()`：\n\n- **Paragraph（段落分块）**：适用于 Markdown 文档，按段落边界切分\n- **Recursive（递归分块）**：按最大 token 数递归拆分，可配置重叠\n- **SentenceRecursive（句子递归分块）**：先按句子边界对齐，再按 token 限制拆分，适合 PDF 和纯文本\n- **Session（会话分块）**：保留消息对话结构，按最大消息数切分\n- **Structural（结构分块）**：利用 AST 解析提取函数、类、结构体等代码单元\n\n## 存储架构\n\nmnem 采用内容寻址存储，所有数据通过 CID 唯一标识。存储层提供两个核心 trait 接口：\n\n### Blockstore Trait\n\nBlockstore 是底层内容存储接口，负责键值对形式的数据读写。系统支持多种后端实现，包括内存实现（用于测试）和持久化实现。\n\n### OpHeadsStore Trait\n\nOpHeadsStore 管理操作头的集合，用于追踪当前工作区的最新状态。\n\n### View 与 Commit\n\n- **View**：视图快照，包含 refs（引用表）和 heads（头提交集）\n- **Commit**：提交记录，指向操作链和视图\n\n```mermaid\ngraph LR\n A[Operation] -->|prev| B[Operation]\n B -->|prev| C[Operation]\n \n D[Commit] -->|ops| A\n D -->|view| E[View]\n \n F[View] -->|heads| G[\"Vec\"]\n F -->|refs| H[\"BTreeMap\"]\n```\n\n## 检索流程\n\n检索（Retrieve）模块负责根据用户查询从图谱中召回最相关的节点 资料来源：[crates/mnem-core/src/retrieve/mod.rs]()`：\n\n1. **过滤阶段**：根据查询条件筛选候选节点\n2. **向量排序**：使用嵌入向量计算语义相似度\n3. **稀疏排序**：BM25 等稀疏检索方法辅助排序\n4. **重排序**：可选的重排序模型优化结果顺序\n5. **Token 预算打包**：将结果打包至 LLM 上下文预算内\n\n检索模块实现了 Anthropic 2024 年提出的 Contextual Retrieval 技术，通过在节点上存储 `context_sentence` 字段（上下文句子）来增强检索效果，该字段在嵌入前被添加到 summary 前缀中 资料来源：[crates/mnem-core/src/objects/node.rs]()`。\n\n## 特性门控\n\n部分功能通过 Cargo feature 进行条件编译控制 资料来源：[crates/mnem-ingest/src/lib.rs]()`：\n\n| Feature | 功能 |\n|---------|------|\n| `keybert` | KeyBERT 统计嵌入器适配器 |\n| `ollama` | Ollama LLM 提取器 |\n| `sidecar-docling` | Docling CLI PDF 解析集成 |\n| `sidecar-unstructured` | Unstructured.io 解析集成 |\n\n## 总结\n\nmnem 的系统架构体现了现代本地优先应用的设计理念：通过内容寻址确保数据的不可变性和可验证性，采用分层模块化设计支持多种接入方式，利用 DAG 结构自然地表达知识图谱的复杂关系。核心库的纯 Rust 实现保证了类型安全和跨平台兼容性，而丰富的文档解析和分块策略则满足了多样化的知识管理需求。\n\n---\n\n\n\n## Crates结构详解\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [Cargo.toml](https://github.com/Uranid/mnem/blob/main/Cargo.toml)\n- [crates/mnem-core/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/Cargo.toml)\n- [crates/mnem-cli/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/Cargo.toml)\n- [crates/mnem-ingest/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-ingest/Cargo.toml)\n- [crates/mnem-http/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-http/Cargo.toml)\n- [crates/mnem-mcp/Cargo.toml](https://github.com/Uranid/mnem/blob/main/crates/mnem-mcp/Cargo.toml)\n \n\n# Crates结构详解\n\n## 概述\n\nmnem 是一个基于 Rust 构建的语义记忆系统，采用 IPLD (InterPlanetary Linked Data) 数据模型和 DAG-CBOR 编解码实现内容寻址存储。项目采用工作区 (workspace) 结构，包含多个独立的 crate，每个 crate 负责特定的功能领域。\n\n```mermaid\ngraph TD\n subgraph mnem工作区\n CLI[mnem-cli]\n HTTP[mnem-http]\n MCP[mnem-mcp]\n CORE[mnem-core]\n INGEST[mnem-ingest]\n end\n \n CLI --> CORE\n HTTP --> CORE\n MCP --> CORE\n INGEST --> CORE\n \n CLI --> INGEST\n HTTP --> INGEST\n MCP --> INGEST\n```\n\n## 核心 Crate 架构\n\n### 项目依赖关系总览\n\n| Crate 名称 | 依赖关系 | 主要功能 |\n|------------|----------|----------|\n| `mnem-core` | 无内部依赖 | 核心数据模型、存储、检索 |\n| `mnem-ingest` | 依赖 `mnem-core` | 数据解析、分块、实体提取 |\n| `mnem-cli` | 依赖 `mnem-core`, `mnem-ingest` | 命令行工具 |\n| `mnem-http` | 依赖 `mnem-core`, `mnem-ingest` | HTTP API 服务 |\n| `mnem-mcp` | 依赖 `mnem-core` | MCP 协议集成 |\n\n## mnem-core 核心库\n\n### 定位与职责\n\n`mnem-core` 是整个项目的核心基础设施库，提供底层数据模型、存储抽象和检索能力。该库完全禁止使用 `unsafe` 代码 (`#![forbid(unsafe_code)]`)，确保内存安全。\n\n### 核心模块\n\n```rust\n资料来源：[crates/mnem-core/src/lib.rs](crates/mnem-core/src/lib.rs)\n\npub mod id; // 内容标识符\npub mod codec; // DAG-CBOR 编解码\npub mod objects; // 核心对象类型\npub mod prolly; // Prolly tree 算法\npub mod store; // 存储抽象\npub mod repo; // 仓库事务\npub mod index; // 索引实现\npub mod retrieve; // 检索器\npub mod sign; // 签名验证\n```\n\n### 核心对象类型\n\n资料来源：[crates/mnem-core/src/objects/node.rs](crates/mnem-core/src/objects/node.rs)\n\n| 类型 | 说明 |\n|------|------|\n| `Node` | 核心节点类型，包含摘要、属性、内容和上下文句子 |\n| `Edge` | 节点间的边关系 |\n| `Commit` | 提交记录 |\n| `Operation` | 操作记录 |\n| `View` | 视图快照 |\n| `IndexSet` | 索引集合 |\n\n### ID 系统\n\n资料来源：[crates/mnem-core/src/id/link.rs](crates/mnem-core/src/id/link.rs)\n\n```rust\npub struct Link {\n cid: Cid,\n _target: PhantomData T>,\n}\n```\n\n`Link` 是类型化内容引用，基于 CID 但增加了类型安全保证：\n\n- 编译时类型检查防止引用混淆\n- `Link`、`Link` 等泛型参数确保语义正确\n- 序列化格式与裸 CID 完全兼容\n\n### 检索模块\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs](crates/mnem-core/src/retrieve/mod.rs)\n\n检索模块负责将节点渲染为 LLM 可消费的文本格式，采用 YAML-like 格式：\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n```\n\n渲染规则：\n- `ntype` 和 `id` 始终存在\n- `context` 在 `summary` 之前输出（遵循 Anthropic 2024 contextual-retrieval 配方）\n- `summary` 默认截断至 8192 字符，可通过 `MNEM_RENDER_SUMMARY_CAP_CHARS` 环境变量配置\n- 标量属性按字母序输出，复杂属性（Link、Map、List）跳过\n\n## mnem-ingest 数据摄取库\n\n### 定位与职责\n\n`mnem-ingest` 负责将各种格式的源数据（Markdown、PDF、代码、会话等）解析、分块并提取实体关系。\n\n### 模块架构\n\n```mermaid\ngraph LR\n subgraph 解析器\n MD[Markdown]\n PDF[PDF]\n CODE[Code]\n CONV[Conversation]\n TEXT[Text]\n end\n \n subgraph 分块器\n PARA[Paragraph]\n REC[Recursive]\n SENT[SentenceRecursive]\n SESS[Session]\n STRUC[Structural]\n end\n \n subgraph 提取器\n RULE[RuleExtractor]\n KEYBERT[KeyBertAdapter]\n LLM[LLMExtractor]\n end\n \n MD & PDF & CODE & CONV & TEXT --> PARA & REC & SENT & SESS & STRUC\n PARA & REC & SENT & SESS & STRUC --> RULE & KEYBERT & LLM\n```\n\n### 支持的源类型\n\n资料来源：[crates/mnem-ingest/src/types.rs](crates/mnem-ingest/src/types.rs)\n\n| 源类型 | 文件扩展名 | 默认分块策略 |\n|--------|------------|--------------|\n| `Markdown` | `.md`, `.markdown` | Paragraph |\n| `Pdf` | `.pdf` | SentenceRecursive (512 tokens, 64 overlap) |\n| `Text` | 其他无扩展名文件 | SentenceRecursive (256 tokens, 32 overlap) |\n| `Conversation` | `.json`, `.jsonl` | Session (10 messages) |\n| `Code(lang)` | 各类代码文件 | Structural |\n\n### 分块策略详解\n\n资料来源：[crates/mnem-ingest/src/chunk.rs](crates/mnem-ingest/src/chunk.rs)\n\n```rust\npub enum ChunkerKind {\n Paragraph, // 段落级别\n Recursive { max_tokens, overlap },\n SentenceRecursive { max_tokens, overlap },\n Session { max_messages }, // 会话消息分组\n Structural, // 代码结构（函数/类等）\n}\n```\n\n| 策略 | 适用场景 | 关键参数 |\n|------|----------|----------|\n| `Paragraph` | Markdown 文档 | 无 |\n| `Recursive` | 通用文本递归切分 | `max_tokens`, `overlap` |\n| `SentenceRecursive` | 句子边界感知的递归切分 | `max_tokens`, `overlap` |\n| `Session` | 对话/聊天记录 | `max_messages` |\n| `Structural` | 源代码结构解析 | 无 |\n\n### 代码语言支持\n\n资料来源：[crates/mnem-ingest/src/code.rs](crates/mnem-ingest/src/code.rs)\n\n| 语言 | 扩展名 | Tree-sitter 提取项 |\n|------|--------|-------------------|\n| Rust | `.rs` | function_item, struct_item, enum_item, trait_item |\n| Python | `.py`, `.pyi` | function_definition, class_definition |\n| JavaScript | `.js`, `.mjs`, `.cjs` | function_declaration, class_declaration |\n| TypeScript | `.ts`, `.tsx`, `.mts`, `.cts` | function_declaration, class_declaration |\n| Go | `.go` | function_declaration, type_declaration |\n| Java | `.java` | method_declaration, class_declaration |\n| C | `.c`, `.h` | function_definition, struct_specifier |\n| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | function_definition, class_specifier |\n| Ruby | `.rb`, `.gemspec`, `.rake` | method_definition, class_module |\n| C# | `.cs`, `.csx` | method_declaration, class_declaration |\n\n### 提取器\n\n资料来源：[crates/mnem-ingest/src/lib.rs](crates/mnem-ingest/src/lib.rs)\n\n```rust\npub mod extract; // 规则提取器\n#[cfg(feature = \"keybert\")]\npub mod extract_keybert; // KeyBERT 统计适配器\n#[cfg(feature = \"ollama\")]\npub mod extract_llm; // LLM 驱动提取器\n```\n\n提取器特性矩阵：\n\n| 提取器 | Feature Flag | 依赖 |\n|--------|--------------|------|\n| `RuleExtractor` | 默认启用 | 无 |\n| `KeyBertAdapter` | `keybert` | embedding 模型 |\n| `LLMExtractor` | `ollama` | Ollama 服务 |\n\n### Sidecar 集成\n\n资料来源：[crates/mnem-ingest/src/sidecar.rs](crates/mnem-ingest/src/sidecar.rs)\n\n提供高级 PDF 解析的后备方案：\n\n| Sidecar | Feature Flag | 说明 |\n|---------|--------------|------|\n| `DoclingSidecar` | `sidecar-docling` | 调用 docling CLI |\n| `UnstructuredSidecar` | `sidecar-unstructured` | 调用 unstructured-ingest CLI |\n\nSidecar 仅在纯 Rust 解析（`parse_pdf`）结果质量不足时使用，需手动配置触发。\n\n## mnem-cli 命令行工具\n\n### 定位与职责\n\n`mnem-cli` 是项目的命令行客户端，提供用户交互接口和配置管理。\n\n### 主要命令\n\n#### ingest 命令\n\n资料来源：[crates/mnem-cli/src/commands/ingest.rs](crates/mnem-cli/src/commands/ingest.rs)\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--chunker` | `auto` | 分块策略：auto, session, paragraph, recursive, sentence_recursive, structural |\n| `--max-tokens` | 512 | 目标分块大小（token） |\n| `--overlap` | 32 | 相邻分块重叠 token 数 |\n| `--recursive` | false | 递归遍历目录 |\n| `--text` | - | 直接摄取内联文本 |\n| `--ntype` | `Doc` | 根节点类型标签 |\n\n### 配置系统\n\n资料来源：[crates/mnem-cli/src/config.rs](crates/mnem-cli/src/config.rs)\n\n配置项分层：\n\n```text\n[user]\n name, email, agent_id\n\n[llm]\n provider: openai | ollama\n model\n api_key_env\n base_url\n timeout_secs\n\n[rerank]\n model, api_key_env, base_url\n\n[ner]\n provider: rule | none\n\n[retrieve]\n limit, budget, vector_cap\n graph_expand, graph_decay, graph_depth\n rerank_top_k, hyde_max_tokens\n```\n\n### Agent 集成\n\n资料来源：[crates/mnem-cli/src/integrate.rs](crates/mnem-cli/src/integrate.rs)\n\n支持将 mnem 系统提示集成到多种 AI 开发工具：\n\n| 主机 | 路径 | 存储格式 |\n|------|------|----------|\n| ClaudeCode | `~/.claude/CLAUDE.md` | Markdown |\n| GeminiCli | `~/.gemini/GEMINI.md` | Markdown |\n| Cursor | `~/.cursor/rules/mnem.mdc` | Markdown |\n| Continue | `~/.continue/config.json` | JSON (systemMessage) |\n| Zed | `settings.json` | JSON (assistant.system_prompt) |\n\n## mnem-http HTTP 服务\n\n### 定位与职责\n\n`mnem-http` 提供 RESTful HTTP API，支持外部服务集成。\n\n### 主要端点\n\n资料来源：[crates/mnem-http/src/handlers.rs](crates/mnem-http/src/handlers.rs)\n\n#### 分支管理\n\n| 方法 | 路径 | 说明 |\n|------|------|------|\n| GET | `/v1/branches` | 列出所有分支 |\n| POST | `/v1/branches` | 创建新分支 |\n\n响应格式示例：\n\n```json\n{\n \"schema\": \"mnem.v1.branches\",\n \"branches\": [\n {\"name\": \"main\", \"head\": \"\", \"is_current\": true}\n ]\n}\n```\n\n### 摄取接口\n\n资料来源：[crates/mnem-http/src/handlers_ingest.rs](crates/mnem-http/src/handlers_ingest.rs)\n\n| 参数 | 说明 |\n|------|------|\n| `chunker` | 分块策略 (auto, paragraph, recursive, session) |\n| `max_tokens` | 目标 token 数 |\n| `overlap` | 重叠 token 数 |\n| `author` | 提交作者（必需） |\n| `message` | 提交消息 |\n| `extractor` | 提取器选择 (none, keybert) |\n| `ner_provider` | NER 提供者 (rule, none) |\n\n## mnem-mcp MCP 协议集成\n\n`mnem-mcp` 提供 Model Context Protocol 协议支持，使 mnem 可作为 AI 代理的记忆后端。详情待补充。\n\n## 版本与特性矩阵\n\n| Crate | 最小 Rust 版本 | 关键依赖 |\n|-------|---------------|----------|\n| mnem-core | 1.75+ | serde, cid, dag-cbor, tokio |\n| mnem-ingest | 1.75+ | tree-sitter-*, pdf-extract |\n| mnem-cli | 1.75+ | clap, anyhow, dirs |\n| mnem-http | 1.75+ | axum, tower, tokio |\n| mnem-mcp | 1.75+ | sse, tokio |\n\n## 总结\n\nmnem 项目采用清晰的模块化架构：\n\n- **mnem-core** 提供不可变的 DAG-CBOR 数据模型和检索基础设施\n- **mnem-ingest** 负责多格式数据的多策略分块与实体提取\n- **mnem-cli/http/mcp** 提供多渠道访问接口\n\n各 crate 通过严谨的类型系统和内容寻址确保数据一致性和可验证性，完全禁用 `unsafe` 代码保证了内存安全。\n\n---\n\n\n\n## 知识图谱模型\n\n### 相关页面\n\n相关主题：[版本控制机制](#page-version-control), [内容寻址系统](#page-content-addressing), [存储后端](#page-storage-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n- [crates/mnem-core/src/objects/edge.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/edge.rs)\n- [crates/mnem-core/src/objects/commit.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/commit.rs)\n- [crates/mnem-core/src/objects/tombstone.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/tombstone.rs)\n- [crates/mnem-core/src/index/adjacency.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/index/adjacency.rs)\n- [crates/mnem-core/src/id/link.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/link.rs)\n- [crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n- [crates/mnem-core/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/lib.rs)\n \n\n# 知识图谱模型\n\n## 概述\n\nmnem 的知识图谱模型是一个基于内容寻址（Content-Addressing）的图数据库核心，它采用 IPLD（InterPlanetary Linked Data）规范来组织和管理数据。该模型的核心设计理念是：\n\n- **不可变性优先**：所有对象一旦写入便不可更改，通过新建版本实现更新\n- **类型安全的链接**：使用 `Link` 泛型确保编译期类型检查\n- **DAG 结构**：节点和边构成有向无环图（DAG），支持高效遍历和查询\n- **确定性编码**：所有对象支持 DAG-CBOR 规范下的字节级精确编解码往返\n\n资料来源：[crates/mnem-core/src/lib.rs:1-50]()\n\n## 核心对象类型\n\n### 节点（Node）\n\n节点是知识图谱的基本存储单元，用于表示文档、文本块、实体等各类知识条目。\n\n```mermaid\nclassDiagram\n class Node {\n +NodeId id\n +NodeType ntype\n +Option~String~ name\n +Option~String~ summary\n +BTreeMap~String, Ipld~ props\n +Option~Bytes~ content\n +Option~String~ context_sentence\n +BTreeMap~String, Ipld~ ext\n }\n```\n\n**关键字段说明**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `NodeId` | 节点的唯一标识符（UUID） |\n| `ntype` | `NodeType` | 节点类型（如 `Doc`、`Chunk`、`Entity` 等） |\n| `name` | `Option` | 节点的友好名称 |\n| `summary` | `Option` | 摘要文本，供 LLM 消费使用 |\n| `props` | `BTreeMap` | 属性映射表，值为任意 DAG-CBOR 兼容类型 |\n| `content` | `Option` | 可选的不透明载荷（如文档正文、文件内容） |\n| `context_sentence` | `Option` | 上下文前缀句（Anthropic 2024 Contextual Retrieval 论文应用） |\n\n**属性设计原则**：\n\n- 标量属性（`String`、`Integer`、`Float`、`Bool`）按 BTreeMap 顺序（字母序）输出\n- 非标量属性（`Link`、`Map`、`List`、`Bytes`、`Null`）在渲染时被跳过，避免占用 token 预算\n- `summary` 字段默认截断至 8192 字符，可通过 `MNEM_RENDER_SUMMARY_CAP_CHARS` 环境变量覆盖\n\n资料来源：[crates/mnem-core/src/objects/node.rs:1-150]()\n\n### 边（Edge）\n\n边表示节点之间的有向关系，是知识图谱关联结构的载体。\n\n```mermaid\nclassDiagram\n class Edge {\n +EdgeId id\n +Link~Node~ src\n +Link~Node~ dst\n +String label\n +Option~Ipld~ props\n }\n```\n\n**关键特性**：\n\n| 特性 | 说明 |\n|------|------|\n| 类型安全 | `src` 和 `dst` 均为 `Link` 类型，编译期确保指向节点 |\n| 关系标签 | `label` 字段描述关系类型（如 `knows`、`authored`、`part_of`） |\n| 属性扩展 | `props` 可选地附加关系级别的元数据 |\n\n**图遍历语义**：\n\n- 边是单向的：从 `src` 指向 `dst`\n- 支持按标签过滤遍历\n- 支持按源节点或目标节点建立索引\n\n资料来源：[crates/mnem-core/src/objects/edge.rs:1-80]()\n\n### 提交（Commit）\n\nCommit 记录图谱的原子变更快照，包含一次或多次操作的集合。\n\n```mermaid\nclassDiagram\n class Commit {\n +ChangeId change_id\n +OperationId operation_id\n +Link~Commit~ parent\n +Author author\n +Timestamp timestamp\n +String message\n +Vec~Operation~ operations\n }\n```\n\n**变更原子性**：\n\n- 每个 Commit 包含完整的 `operations` 向量\n- 操作类型包括：`AddNode`、`AddEdge`、`UpdateNode`、`DeleteNode`、`DeleteEdge`\n- 支持批量原子提交，确保要么全部成功，要么全部回滚\n\n**操作类型**：\n\n| 操作类型 | 说明 |\n|----------|------|\n| `AddNode` | 向图中添加新节点 |\n| `AddEdge` | 在两节点间建立关系 |\n| `UpdateNode` | 更新现有节点的属性（通过 Replace 实现） |\n| `DeleteNode` | 删除节点（软删除，生成 Tombstone） |\n| `DeleteEdge` | 删除边关系 |\n\n资料来源：[crates/mnem-core/src/objects/commit.rs:1-120]()\n\n### 墓碑（Tombstone）\n\nTombstone 是已删除节点的占位符，用于在内容寻址结构中维护图的完整性。\n\n```mermaid\nclassDiagram\n class Tombstone {\n +NodeId id\n +Timestamp deleted_at\n +Option~Author~ deleted_by\n }\n```\n\n**设计目的**：\n\n- 在 IPLD 内容寻址系统中，被删除内容的 CID 仍然可能存在于历史记录或其他节点引用中\n- Tombstone 确保遍历时不会因缺失内容而失败\n- 支持后续的垃圾回收机制识别可清理的孤立对象\n\n资料来源：[crates/mnem-core/src/objects/tombstone.rs:1-60]()\n\n## 链接系统（Link）\n\n### Link 泛型类型\n\n`Link` 是 mnem 的类型安全内容引用封装。\n\n```mermaid\nclassDiagram\n class Link~T~ {\n -Cid cid\n -PhantomData _target\n }\n Link ..> Cid : contains\n```\n\n**核心特性**：\n\n| 特性 | 说明 |\n|------|------|\n| phantom type | 泛型参数 `T` 在运行时不占空间，仅用于编译期类型检查 |\n| CID 等价 | 底层存储与裸 `Cid` 完全相同（相同字节、相同 CBOR 标签） |\n| 编译期安全 | `fn parents(&self) -> &[Link]` 会在传入 `Link` 时编译失败 |\n\n**使用示例**：\n\n```rust\n// 正确的用法：编译通过\nlet commit_link: Link = Link::new(cid);\nfn get_parents(link: &Link) -> &[Link] { ... }\n\n// 错误的用法：编译失败\nlet node_link: Link = Link::new(cid);\nget_parents(&node_link); // 编译错误：类型不匹配\n```\n\n资料来源：[crates/mnem-core/src/id/link.rs:1-80]()\n\n## 索引系统\n\n### 邻接表索引（Adjacency Index）\n\n邻接表是图遍历的核心数据结构，支持高效的关系查询。\n\n```mermaid\ngraph TD\n A[Node A] -->|knows| B[Node B]\n A -->|authored| C[Node C]\n B -->|knows| D[Node D]\n B -->|part_of| A\n C -->|part_of| A\n \n E[Adjacency Index] -->|out_edges| F[HashMap>]\n E -->|in_edges| G[HashMap>]\n```\n\n**索引结构**：\n\n| 索引方向 | 用途 |\n|----------|------|\n| 出边索引 (`out_edges`) | 给定节点，快速获取其所有出向关系 |\n| 入边索引 (`in_edges`) | 给定节点，快速获取指向它的所有关系 |\n\n**查询能力**：\n\n- 按源节点查询所有出边\n- 按目标节点查询所有入边\n- 按边标签过滤\n- 支持多跳路径查询（通过组合调用实现）\n\n资料来源：[crates/mnem-core/src/index/adjacency.rs:1-100]()\n\n## 数据流与操作语义\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Transaction\n participant Operation\n participant Commit\n participant Blockstore\n \n Client->>Transaction: begin()\n Client->>Transaction: add_node(node)\n Transaction->>Operation: Create AddNode operation\n Client->>Transaction: add_edge(src, dst, label)\n Transaction->>Operation: Create AddEdge operation\n Client->>Transaction: commit(author, message)\n Transaction->>Operation: Finalize operations\n Transaction->>Commit: Create Commit with operations\n Commit->>Blockstore: Store Commit (CID)\n Transaction->>Blockstore: Store Node/Edge objects\n Blockstore-->>Commit: Store CIDs\n Commit-->>Transaction: Commit CID\n Transaction-->>Client: ReadonlyRepo\n```\n\n### 图遍历流程\n\n```mermaid\ngraph LR\n A[输入: 起始节点] --> B[查询邻接表出边]\n B --> C{边过滤条件}\n C -->|无过滤| D[返回所有相邻节点]\n C -->|按标签| E[返回匹配标签的节点]\n D --> F[可迭代结果集]\n E --> F\n F --> G[继续遍历下一跳]\n```\n\n## 检索与渲染\n\n### LLM 友好的节点渲染\n\n检索系统在将节点返回给 LLM 使用前，会将节点渲染为确定性的文本表示。\n\n**渲染格式**：\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n...\n```\n\n**渲染规则**：\n\n| 字段 | 存在条件 | 位置 |\n|------|----------|------|\n| `ntype` | 始终 | 第1行 |\n| `id` | 始终 | 第2行 |\n| `context` | `context_sentence` 非空时 | `summary` 之前 |\n| `summary` | `summary` 非空时 | 第3或4行 |\n| 属性 | 仅标量属性 | `summary` 之后 |\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs:1-100]()\n\n## 节点类型枚举\n\n| 节点类型 | 说明 | 典型属性 |\n|----------|------|----------|\n| `Doc` | 文档节点 | `mnem:source_kind`、`title`、`mime_type` |\n| `Chunk` | 文本块节点 | `section_path`、`tokens_estimate` |\n| `Entity` | 实体节点 | NER 提取的实体 |\n| `Conversation` | 对话会话节点 | 消息序列 |\n| `Ref` | 引用/指针节点 | 指向其他节点的 Link |\n\n## 约束与不变量\n\n**核心约束**：\n\n1. `#![forbid(unsafe_code)]` - mnem-core 禁止使用 `unsafe` 代码\n2. **字节级精确编解码**：每个对象类型必须满足 `decode(encode(x)) == x` 和 `encode(decode(b)) == b`\n3. **不可变性**：已有对象不可原地修改，只能创建新版本\n4. **类型化链接**：所有节点间引用必须通过 `Link` 类型化\n\n资料来源：[crates/mnem-core/src/lib.rs:30-50]()\n\n## 与外部系统的集成\n\n### 摄入管道集成\n\n```mermaid\ngraph TD\n A[源文件] --> B[解析器 Parser]\n B --> C[分块器 Chunker]\n C --> D[提取器 Extractor]\n D --> E[Transaction]\n E --> F[Node/Edge 对象]\n F --> G[Blockstore]\n G --> H[Commit 提交]\n```\n\n摄入管道将外部文档转换为图谱节点：\n- **Doc 节点**：原始文档元数据\n- **Chunk 节点**：分块后的文本段落\n- **Entity 节点**：NER 提取的命名实体\n- **Edge 边**：节点间关系（如 `Chunk -[part_of]-> Doc`、`Entity -[extracted_from]-> Chunk`）\n\n资料来源：[crates/mnem-ingest/src/pipeline.rs:1-80]()\n\n### 全局知识图谱\n\nmnem 支持跨仓库的全局知识图谱（`~/.mnemglobal`），检索时同时搜索当前仓库和全局图谱。\n\n**跨图谱链接策略**：\n- 不在 Edge 中添加 `dst_repo: PathBuf`（保持文件系统无关性）\n- Phase 1：检索时同时搜索全局图谱\n- Phase 2（未来）：在节点属性中添加 `_global_anchor` 指向全局 CID\n\n资料来源：[crates/mnem-cli/src/global.rs:1-50]()\n\n## 总结\n\nmnem 的知识图谱模型是一个精心设计的图数据库核心，它通过：\n\n- **类型安全的链接系统** 确保编译期正确性\n- **不可变的内容寻址** 提供版本历史和完整性保证\n- **确定性编码** 确保跨平台一致性\n- **上下文感知检索** 支持 LLM 高效消费图谱数据\n\n该模型为知识管理、AI 代理和语义搜索提供了坚实的数据基础。\n\n---\n\n\n\n## 版本控制机制\n\n### 相关页面\n\n相关主题：[知识图谱模型](#page-knowledge-graph), [数据流与摄取管道](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/repo/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/mod.rs)\n- [crates/mnem-core/src/repo/transaction.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/transaction.rs)\n- [crates/mnem-core/src/repo/merge.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/repo/merge.rs)\n- [crates/mnem-core/src/objects/operation.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/operation.rs)\n- [crates/mnem-cli/src/commands/commit.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/commit.rs)\n- [crates/mnem-cli/src/commands/branch.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/branch.rs)\n- [crates/mnem-cli/src/commands/diff.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/diff.rs)\n- [crates/mnem-cli/src/commands/merge.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-cli/src/commands/merge.rs)\n \n\n# 版本控制机制\n\n## 概述\n\nmnem 的版本控制机制是一个基于内容寻址存储（Content-Addressable Storage, CAS）的分布式版本控制系统，采用 DAG（有向无环图）结构管理文档变更历史。该系统以操作为核心抽象，支持多分支并行开发、冲突检测与合并、以及加密签名验证等企业级功能。\n\nmnem 的版本控制设计遵循以下核心原则：\n\n- **无冲突写入**：通过事务机制实现原子性操作\n- **去中心化架构**：每个仓库独立运行，无中心服务器依赖\n- **可验证完整性**：所有操作支持 Ed25519 数字签名\n- **语义保留**：变更记录包含 author、task_id、agent_id 等元数据\n\n资料来源：[crates/mnem-core/src/lib.rs:10-30]()\n\n## 核心数据结构\n\n### Operation（操作）\n\nOperation 是版本控制的基本单元，对应传统 VCS 中的 \"commit\" 概念。\n\n```rust\npub struct Operation {\n pub parents: Vec, // 父操作列表（支持多父节点）\n pub view: Cid, // 操作后的视图快照\n pub predecessors: Option>>, // 前驱操作\n pub author: String, // 作者标识\n pub agent_id: Option, // AI 代理标识\n pub task_id: Option, // 任务标识\n pub host: Option, // 主机标识\n pub time: u64, // Unix 时间戳（微秒）\n pub description: String, // 操作描述\n pub signature: Option, // 加密签名\n pub extra: BTreeMap, // 扩展字段\n}\n```\n\n**关键特性说明：**\n\n| 字段 | 类型 | 用途 |\n|------|------|------|\n| `parents` | `Vec` | 支持多父节点，实现 merge 操作的完整历史记录 |\n| `view` | `Cid` | 指向操作后仓库状态的指针，保证内容可寻址 |\n| `signature` | `Option` | Ed25519 签名，用于操作真实性和完整性验证 |\n| `time` | `u64` | 微秒级时间戳，支持高精度排序 |\n\n资料来源：[crates/mnem-core/src/objects/operation.rs:30-70]()\n\n### ChangeId（变更标识）\n\nChangeId 是操作的唯一标识符，用于在 refs 和 parents 中引用操作：\n\n```rust\npub struct ChangeId(bytes::Bytes);\n```\n\nChangeId 通过内容哈希生成，确保相同操作的标识全局一致。\n\n### View（视图）\n\nView 记录特定时间点的仓库完整状态，包含：\n\n- 所有 refs（分支、标签）的当前指向\n- 活动节点集合\n- 墓碑集（tombstones）：已删除节点的记录，用于冲突检测\n\n资料来源：[crates/mnem-core/src/objects/mod.rs]()\n\n## 事务机制\n\n### Transaction 事务\n\nTransaction 是 mnem 的核心写操作接口，提供原子性的变更构建与提交能力。\n\n```mermaid\ngraph TD\n A[创建 Transaction] --> B[add_node 添加节点]\n A --> C[add_edge 添加关系]\n B --> D[resolve_chunker 解析分块器]\n C --> E[extract::RuleExtractor 实体提取]\n D --> F[commit 提交事务]\n E --> F\n G[返回 IngestResult] --> H[ReadonlyRepo]\n```\n\n**主要方法：**\n\n| 方法 | 签名 | 功能 |\n|------|------|------|\n| `add_node` | `add_node(ntype, props, content) -> Result` | 添加节点到当前事务 |\n| `add_edge` | `add_edge(src, dst, etype) -> Result<()>` | 添加节点间关系 |\n| `commit` | `commit(author, message) -> Result` | 原子提交事务 |\n| `ingest` | `ingest(tx, bytes, kind) -> Result` | 端到端导入流程 |\n\n资料来源：[crates/mnem-core/src/repo/transaction.rs:60-120]()\n\n### IngestResult 结果\n\n`ingest` 方法返回的 `IngestResult` 包含执行统计信息：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `nodes_added` | `u32` | 新增节点数 |\n| `chunks_created` | `u32` | 创建的文本块数 |\n| `entities_extracted` | `u32` | 提取的实体数 |\n| `elapsed_ms` | `u64` | 执行耗时（毫秒） |\n\n## 分支与引用管理\n\n### Refs 结构\n\nmnem 使用 refs 管理命名引用：\n\n```text\nrefs/heads/ # 分支头指针\nrefs/tags/ # 标签引用\nHEAD # 当前分支指针\n```\n\n### 分支操作\n\nCLI 提供完整的分支管理能力：\n\n| 命令 | 功能 | 关键参数 |\n|------|------|----------|\n| `mnem branch` | 列出所有分支 | `-v` 详细输出 |\n| `mnem branch create ` | 创建新分支 | `--from ` 指定起点 |\n| `mnem branch delete ` | 删除分支 | `--force` 强制删除 |\n\n**分支创建流程：**\n\n1. 解析目标 commit（支持 CID、ref 名称、分支短名、HEAD）\n2. 在 View 中创建 `refs/heads/` 指针\n3. 生成新的 Operation 记录变更\n4. 更新 HEAD 指针（如为当前分支）\n\n资料来源：[crates/mnem-cli/src/commands/branch.rs:1-80]()\n\n### 标签操作\n\n标签是只读的命名引用，常用于版本标记：\n\n```rust\npub enum TagCmd {\n List, // 列出所有标签\n Create { name: String, target: Option }, // 创建标签\n Delete { name: String }, // 删除标签\n}\n```\n\n**约束条件：**\n\n- 标签名长度不超过 255 字符\n- 不允许包含空格、制表符、换行符、`~`、`^`、`:`、`?`、`*`、`[`等特殊字符\n- 创建时必须指定有效的 author\n\n资料来源：[crates/mnem-cli/src/commands/tag.rs:1-60]()\n\n## 差异比较\n\n### Diff 命令\n\n`mnem diff` 命令用于比较两个提交之间的变更：\n\n```bash\nmnem diff [options] [] []\n```\n\n| 参数 | 说明 |\n|------|------|\n| `` | 左侧 commit（基准），默认 HEAD |\n| `` | 右侧 commit（比较目标），默认工作区 |\n\n**输出内容包括：**\n\n- 节点变更（新增/修改/删除）\n- 边的变更（关系增删）\n- 元数据变更（props、content）\n\n## 合并机制\n\n### Merge 策略\n\nmnem 支持三方合并（three-way merge），通过检测冲突实现：\n\n```mermaid\ngraph TD\n A[开始合并] --> B[加载 left commit]\n A --> C[加载 right commit]\n A --> D[计算 LCA]\n B --> E[detect_conflicts]\n C --> E\n D --> E\n E --> F{检测到冲突?}\n F -->|是| G[返回 MergeConflicts]\n F -->|否| H[自动合并成功]\n G --> I[返回冲突列表]\n H --> J[创建 merge commit]\n J --> K[更新 View]\n```\n\n### 冲突检测\n\n```rust\npub fn detect_conflicts_with_policy(\n repo: &ReadonlyRepo,\n left: Cid, // 左侧 commit CID\n right: Cid, // 右侧 commit CID\n lca: Option, // 最近公共祖先\n policy: ConflictPolicy,\n) -> Result\n```\n\n**冲突类型：**\n\n| 类型 | 说明 |\n|------|------|\n| `ContentConflict` | 内容修改冲突 |\n| `StructuralConflict` | 结构变更冲突（节点增删） |\n| `PropertyConflict` | 属性值冲突 |\n\n### ConflictPolicy 策略\n\n冲突策略控制合并行为：\n\n```rust\npub struct ConflictPolicy {\n pub ours_priority: bool, // true: 优先我们的变更\n pub theirs_priority: bool, // true: 优先他们的变更\n pub auto_resolve: Vec, // 可自动解决的冲突类型\n}\n```\n\n资料来源：[crates/mnem-core/src/repo/merge.rs:1-100]()\n\n## 提交流程\n\n### Commit 命令\n\n`mnem commit` 创建新的操作记录：\n\n```bash\nmnem commit [options] [--message ]\n```\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `--author` | 配置值 | 作者信息 |\n| `--message` | 自动生成 | 提交消息 |\n| `--amend` | false | 修改上一个提交（追加操作） |\n| `--no-edit` | false | 跳过编辑器 |\n\n**提交流程：**\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Transaction\n participant Blockstore\n participant Repo\n \n User->>CLI: mnem commit -m \"message\"\n CLI->>Repo: 创建 Transaction\n Repo-->>Transaction: 返回 &mut Transaction\n CLI->>Transaction: 加载待提交变更\n CLI->>Transaction: commit(author, message)\n Transaction->>Blockstore: 编码新 View\n Transaction->>Blockstore: 创建 Operation\n Blockstore-->>Transaction: 返回 View CID\n Transaction->>Blockstore: 更新 HEAD ref\n Transaction-->>Repo: 返回 ReadonlyRepo\n Repo-->>CLI: 返回结果\n CLI-->>User: 显示 commit 信息\n```\n\n**作者字符串格式：**\n\n- 完整格式：`\"name \"`\n- 仅名称：`\"name\"`\n- 仅邮箱：`\"\"`\n- 仅 agent_id：`\"mnem-cli\"` 或配置的 agent_id\n\n资料来源：[crates/mnem-cli/src/commands/commit.rs:1-100]()\n\n### 签名验证\n\n操作签名基于 Ed25519 算法：\n\n```rust\npub signature: Option, // Ed25519 签名\n```\n\n**签名流程：**\n\n1. 序列化 Operation（排除 signature 字段）\n2. 使用私钥生成 Ed25519 签名\n3. 附加到 Operation 的 signature 字段\n\n**验证流程：**\n\n1. 提取 signature 和公钥信息\n2. 使用公钥验证签名有效性\n3. 确保操作内容未被篡改\n\n资料来源：[crates/mnem-core/src/sign.rs]()\n\n## CLI 命令参考\n\n### 命令总览\n\n| 命令 | 模块 | 功能 |\n|------|------|------|\n| `mnem commit` | commit.rs | 创建提交 |\n| `mnem branch` | branch.rs | 分支管理 |\n| `mnem tag` | tag.rs | 标签管理 |\n| `mnem diff` | diff.rs | 差异比较 |\n| `mnem merge` | merge.rs | 分支合并 |\n| `mnem log` | log.rs | 历史查看 |\n\n### 仓库配置\n\n配置文件位于 `~/.config/mnem/config.toml` 或仓库根目录的 `.mnem/config.toml`：\n\n```toml\n[user]\nname = \"Your Name\"\nemail = \"you@example.com\"\n\n[llm]\nprovider = \"ollama\"\nmodel = \"qwen2.5\"\nbase_url = \"http://localhost:11434\"\n\n[ner]\nprovider = \"rule\" # rule | none\n```\n\n## 架构设计要点\n\n### DAG 持久化\n\nmnem 使用 DAG-CBOR 编码存储 Operation 和 View，确保：\n\n- **规范化**：相同内容产生相同编码\n- **可验证**：编码后哈希作为 CID 可验证完整性\n- **高效存储**：内容去重通过 CID 实现\n\n### 无头指针\n\nmnem 不使用传统 Git 的 \"head pointer\" 链表模式，而是将所有历史直接编码在 Operation 的 `parents` 字段中。这简化了分支模型，但要求合并时必须显式指定 LCA。\n\n### 事务隔离\n\nTransaction 提供写隔离：\n\n- 未提交的变更对其他读者不可见\n- 提交是原子的（全部成功或全部回滚）\n- 支持嵌套事务（通过 savepoint 实现）\n\n---\n\n## 延伸阅读\n\n- [存储引擎](./storage-engine.md) - Blockstore 接口与实现\n- [检索系统](./retrieval.md) - 基于版本化索引的语义搜索\n- [导入管道](./ingestion.md) - 从多源文档到版本化节点\n\n---\n\n\n\n## 内容寻址系统\n\n### 相关页面\n\n相关主题：[知识图谱模型](#page-knowledge-graph), [存储后端](#page-storage-backend)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/id/cid.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/cid.rs)\n- [crates/mnem-core/src/id/multihash.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/multihash.rs)\n- [crates/mnem-core/src/id/link.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/id/link.rs)\n- [crates/mnem-core/src/codec/dagcbor.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/codec/dagcbor.rs)\n- [crates/mnem-core/src/codec/dagjson.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/codec/dagjson.rs)\n- [crates/mnem-core/src/objects/node.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/node.rs)\n- [crates/mnem-core/src/objects/commit.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/objects/commit.rs)\n- [crates/mnem-core/src/retrieve/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/retrieve/mod.rs)\n \n\n# 内容寻址系统\n\n## 概述\n\nmnem 的内容寻址系统是整个知识图谱存储和检索的基础架构。该系统基于 IPFS 生态的标准规范构建，通过内容的加密哈希值作为内容的唯一标识符，实现了去重、版本追溯和分布式存储等核心能力。\n\n内容寻址的核心思想是：**内容本身的哈希值即为该内容的地址**。相同的内容必然产生相同的哈希值，这意味着任何节点可以对相同内容达成共识，无需依赖中心化的命名服务器。资料来源：[crates/mnem-core/src/id/cid.rs:1-50]()\n\n## 核心架构\n\nmnem 的内容寻址系统由多个层次组成，每一层负责不同的职责：\n\n```mermaid\ngraph TB\n subgraph \"内容寻址层次结构\"\n A[\"内容数据
Bytes\"] --> B[\"Multihash
多哈希\"]\n B --> C[\"CIDv1
内容标识符\"]\n C --> D[\"DAG-CBOR
编码\"]\n C --> E[\"DAG-JSON
编码\"]\n end\n \n subgraph \"上层应用\"\n D --> F[\"Node 节点\"]\n D --> G[\"Edge 边\"]\n D --> H[\"Commit 提交\"]\n F --> I[\"Transaction 事务\"]\n G --> I\n H --> I\n end\n \n subgraph \"类型系统\"\n J[\"Link<T>
类型化链接\"]\n K[\"ChangeId
变更标识符\"]\n L[\"OperationId
操作标识符\"]\n end\n```\n\n### 核心不变性保证\n\nmnem-core crate 在 crate 级别强制执行以下不变性：\n\n- `#![forbid(unsafe_code)]` - 整个核心模块禁止使用 `unsafe` 代码\n- 每个对象类型必须保持字节级精确的规范化编码往返属性：`decode(encode(x)) == x`\n- 每个 `put` 操作必须验证解码后的对象与原始内容一致 资料来源：[crates/mnem-core/src/lib.rs:30-45]()\n\n## CID 内容标识符\n\n### CID 结构\n\nCID（Content Identifier）是 IPLD 生态系统中用于标识有向无环图（DAG）中节点的标准格式。mnem 使用 CIDv1 格式，支持多种哈希算法。\n\n```rust\n// CID 结构示意（简化版）\npub struct Cid {\n version: u64, // CID 版本，通常为 1\n codec: u64, // 编解码器标识（如 dag-cbor = 0x71）\n hash: Multihash, // 内容的哈希值\n}\n```\n\n### CID 的编解码\n\nCID 的序列化采用 IPLD 规范定义的格式，支持二进制（DAG-CBOR）和字符串（base32）两种表示方式：\n\n| 表示方式 | 用途 | 示例 |\n|---------|------|------|\n| 二进制 | 内部存储、图遍历 | 存储在 Blockstore 中 |\n| Base32 字符串 | 人类可读、URL 安全 | `bafybeig...` 格式 |\n\n资料来源：[crates/mnem-core/src/id/cid.rs:1-100]()\n\n## Multihash 多哈希\n\n### 设计理念\n\nMultihash 是一种自描述的哈希格式，它将哈希算法标识和哈希值封装在一起。这种设计允许系统在不破坏已有内容寻址的前提下，演进哈希算法。\n\n```\n┌─────────────┬─────────────┬──────────────────┐\n│ 算法标识 │ 长度 (2B) │ 哈希值 │\n│ (varint) │ │ │\n└─────────────┴─────────────┴──────────────────┘\n```\n\n### 支持的哈希算法\n\nmnem 通过 `multihash` crate 支持多种哈希算法，具体使用哪种算法取决于配置和用例。常见算法包括：\n\n| 算法 | 标识符 | 输出长度 | 适用场景 |\n|------|--------|----------|----------|\n| SHA-256 | 0x12 | 32 字节 | 默认、安全敏感场景 |\n| Blake3 | 0xb201 | 32 字节 | 高性能需求 |\n| Keccak-256 | 0x1b | 32 字节 | 以太坊兼容 |\n\n资料来源：[crates/mnem-core/src/id/multihash.rs:1-80]()\n\n## Link 类型系统\n\n### 幽灵类型化链接\n\nmnem 引入了 `Link` 类型，这是一种phantom-typed（幽灵类型化）的链接类型，用于在编译期确保类型安全：\n\n```rust\npub struct Link {\n cid: Cid,\n _marker: PhantomData,\n}\n```\n\n这种设计实现了以下保证：\n\n- 编译时类型检查：无法将 `Link` 错误赋值给期望 `Link` 的位置\n- 运行时零开销：幽灵类型不占用实际存储空间\n- 语义清晰：`Link` 表示指向节点，`Link` 表示指向提交\n\n资料来源：[crates/mnem-core/src/id/link.rs:1-60]()\n\n### 相关的标识符类型\n\n除 `Link` 外，系统还定义了以下标识符类型：\n\n| 类型 | 用途 | 说明 |\n|------|------|------|\n| `ChangeId` | 变更标识 | 标识一次原子变更操作 |\n| `OperationId` | 操作标识 | 标识具体的操作实例 |\n| `EdgeId` | 边标识 | 标识图中的一条边 |\n\n资料来源：[crates/mnem-core/src/lib.rs:20-30]()\n\n## 编解码器\n\n### DAG-CBOR 编解码器\n\nDAG-CBOR 是 CBOR（Concise Binary Object Representation）的 DAG 扩展，是 IPLD 系统的默认编解码格式。它具有以下特点：\n\n- **紧凑二进制表示**：相比 JSON 节省 30-50% 空间\n- **确定性编码**：相同数据必然产生相同字节序列\n- **丰富的类型支持**：包括字节串、链接、标签等 IPLD 特有类型\n\n```mermaid\ngraph LR\n A[\"Rust Struct\"] --> B[\"Serialize\"]\n B --> C[\"CBOR Bytes\"]\n C --> D[\"Multihash\"]\n D --> E[\"CID\"]\n \n F[\"CID\"] --> G[\"Multihash\"]\n G --> H[\"CBOR Bytes\"]\n H --> I[\"Deserialize\"]\n I --> J[\"Rust Struct\"]\n```\n\n资料来源：[crates/mnem-core/src/codec/dagcbor.rs:1-100]()\n\n### DAG-JSON 编解码器\n\nDAG-JSON 用于人类可读的调试导出和日志记录。虽然不用于实际存储，但它对于开发和调试至关重要：\n\n| 特性 | DAG-JSON | DAG-CBOR |\n|------|----------|----------|\n| 用途 | 调试、导出 | 实际存储 |\n| 可读性 | 人类可读 | 二进制 |\n| 效率 | 低 | 高 |\n| 规范性 | 非严格 | 严格确定性 |\n\n资料来源：[crates/mnem-core/src/codec/dagjson.rs:1-80]()\n\n## 对象模型\n\n### Node 节点\n\nNode 是内容寻址存储的基本单元，每个节点由以下部分组成：\n\n```mermaid\ngraph TB\n A[\"Node\"] --> B[\"id: NodeId\"]\n A --> C[\"ntype: String
节点类型\"]\n A --> D[\"summary: Option<String>
摘要\"]\n A --> E[\"props: BTreeMap
属性映射\"]\n A --> F[\"content: Option<Bytes>
内容负载\"]\n A --> G[\"context_sentence: Option<String>
上下文句子\"]\n```\n\n#### 字段语义\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | `NodeId` | 节点的唯一标识符 |\n| `ntype` | `String` | 节点类型标签（如 \"Fact\", \"Person\"） |\n| `summary` | `Option` | LLM 可读的摘要文本 |\n| `props` | `BTreeMap` | 结构化属性，可包含 `Link` |\n| `content` | `Option` | 原始二进制负载 |\n| `context_sentence` | `Option` | 上下文定位前缀 |\n\n**上下文句子（Context Sentence）**是 Anthropic 2024 年上下文检索论文的实现。系统在嵌入前将此句子添加到摘要前，使密集和稀疏检索都能捕获位置和关系上下文。资料来源：[crates/mnem-core/src/objects/node.rs:1-100]()\n\n### Edge 边\n\nEdge 表示节点之间的有向关系：\n\n```rust\npub struct Edge {\n pub src: NodeId,\n pub label: String,\n pub dst: NodeId,\n pub props: BTreeMap,\n}\n```\n\n### Commit 提交\n\nCommit 封装了一组原子性的变更：\n\n```mermaid\ngraph TB\n A[\"Commit\"] --> B[\"change_id: ChangeId\"]\n A --> C[\"parents: Vec<ChangeId>\"]\n A --> D[\"nodes: Vec<Node>\"]\n A --> E[\"edges: Vec<Edge>\"]\n A --> F[\"author: String\"]\n A --> G[\"time: u64\"]\n A --> H[\"message: String\"]\n A --> I[\"signature: Option<Signature>\"]\n```\n\n资料来源：[crates/mnem-core/src/objects/commit.rs:1-100]()\n\n## 内容寻址工作流\n\n### 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Transaction\n participant Blockstore\n participant Codec\n \n Client->>Transaction: add_node(node)\n Transaction->>Codec: serialize(node)\n Codec-->>Transaction: dag_cbor_bytes\n Transaction->>Blockstore: put(cid, bytes)\n Blockstore-->>Transaction: CID\n Transaction-->>Client: Link\n \n Client->>Transaction: add_edge(src, label, dst)\n Transaction->>Transaction: 创建 Edge\n Transaction->>Transaction: 创建 Commit\n Transaction->>Codec: serialize(commit)\n Blockstore->>Blockstore: 存储所有子节点\n```\n\n### 读取流程\n\n```mermaid\ngraph LR\n A[\"Link<T>\"] --> B[\"CID\"]\n B --> C[\"Blockstore.get\"]\n C --> D[\"DAG-CBOR Bytes\"]\n D --> E[\"Codec.deserialize\"]\n E --> F[\"T 类型对象\"]\n```\n\n## 源类型与分块\n\n内容寻址系统与源类型处理紧密集成。`SourceKind` 定义了支持的源类型：\n\n| 源类型 | 说明 | 默认分块策略 |\n|--------|------|--------------|\n| `Markdown` | Markdown 文档 | Paragraph |\n| `Text` | 纯文本 | SentenceRecursive (256 tokens, 32 overlap) |\n| `Pdf` | PDF 文档 | SentenceRecursive (512 tokens, 64 overlap) |\n| `Conversation` | 对话记录 | Session (10 messages) |\n| `Code(lang)` | 代码文件 | Structural |\n\n`CodeLanguage` 枚举支持以下语言：Rust, Python, JavaScript, TypeScript, Go, Java, C, C++, Ruby, CSharp\n\n资料来源：[crates/mnem-ingest/src/types.rs:1-100]()\n\n## 检索与渲染\n\n### 节点渲染\n\n检索系统需要将节点转换为适合 LLM 消费的文本格式。渲染格式如下：\n\n```text\nntype: \nid: \ncontext: \nsummary: \n: \n...\n```\n\n渲染规则：\n\n- `ntype` 和 `id` 始终存在\n- `context` 在 `summary` 之前（遵循 Anthropic 上下文检索方案）\n- `summary` 长度上限 8192 字符（可配置 `MNEM_RENDER_SUMMARY_CAP_CHARS`）\n- 标量属性按 BTreeMap 顺序（字母序）输出\n- 非标量属性（Link, Map, List, Bytes, Null）被跳过\n- 不透明 `content` 永不渲染\n\n资料来源：[crates/mnem-core/src/retrieve/mod.rs:50-100]()\n\n## 配置与扩展\n\n### 存储后端\n\nmnem 通过 `Blockstore` trait 定义存储接口，支持多种实现：\n\n```rust\npub trait Blockstore {\n async fn get(&self, cid: &Cid) -> Result>>;\n async fn put(&self, cid: &Cid, block: &[u8]) -> Result<()>;\n}\n```\n\n### 可扩展性设计\n\n内容寻址系统的扩展点包括：\n\n- **新的编解码器**：实现 `Codec` trait 可添加新的序列化格式\n- **新的哈希算法**：通过 `multihash` crate 注册新算法\n- **新的对象类型**：定义新结构体并实现序列化 trait\n\n## 总结\n\nmnem 的内容寻址系统建立在一个经过验证的标准之上（IPLD、CID、Multihash），同时通过以下设计决策提供了独特的价值：\n\n1. **类型安全**：通过 `Link` phantom 类型实现编译期检查\n2. **确定性编码**：确保相同内容产生相同 CID，这是内容去重和一致性的基础\n3. **上下文感知**：通过 `context_sentence` 字段增强检索质量\n4. **规范化保证**：crate 级别禁止 `unsafe`，所有编解码经过往返测试\n\n这套系统使得 mnem 能够可靠地管理知识图谱的长期演进，同时保持高效的内容查询和去重能力。\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[数据流与摄取管道](#page-data-flow), [知识图谱模型](#page-knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/mnem-core/src/store/blockstore.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/store/blockstore.rs)\n- [crates/mnem-core/src/store/mod.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/store/mod.rs)\n- [crates/mnem-core/src/store/op_heads.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-core/src/store/op_heads.rs)\n- [crates/mnem-backend-redb/src/blockstore.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-backend-redb/src/blockstore.rs)\n- [crates/mnem-backend-redb/src/lib.rs](https://github.com/Uranid/mnem/blob/main/crates/mnem-backend-redb/src/lib.rs)\n \n\n# 存储后端\n\nmnem 的存储后端是整个系统的核心基础设施，负责持久化和检索内容寻址的数据块（blocks）。它定义了抽象的存储接口，并提供了多种后端实现，使得上层逻辑与具体存储技术解耦。\n\n## 架构概览\n\nmnem 采用模块化的存储架构，将存储接口抽象为 trait（特征），支持可插拔的后端实现。当前系统包含两套核心存储抽象和两种后端实现。\n\n```mermaid\ngraph TD\n subgraph \"应用层\"\n A[\"mnem-core
(核心库)\"]\n B[\"mnem-cli
(命令行工具)\"]\n C[\"mnem-http
(HTTP服务)\"]\n end\n \n subgraph \"存储抽象层\"\n D[\"Blockstore trait\"]\n E[\"OpHeadsStore trait\"]\n end\n \n subgraph \"后端实现层\"\n F[\"InMemoryBlockstore
(内存实现)\"]\n G[\"RedbBlockstore
(redb持久化)\"]\n H[\"InMemoryOpHeadsStore\"]\n end\n \n A --> D\n A --> E\n B --> A\n C --> A\n D --> F\n D --> G\n E --> H\n```\n\n## Blockstore 特征\n\n`Blockstore` 是 mnem 系统中用于存储和检索内容寻址数据块的核心 trait。它定义了读写操作的抽象接口，使得无论底层使用何种存储技术，上层的编解码和 DAG 操作都能正常工作。\n\n### 核心方法\n\n| 方法 | 签名 | 功能描述 |\n|------|------|----------|\n| `get` | `fn get(&self, cid: &Cid) -> Result>, Error>` | 根据 CID 检索数据块，返回 `None` 表示不存在 |\n| `put` | `fn put(&self, block: &[u8]) -> Result` | 存储数据块，返回其 CID |\n| `has` | `fn has(&self, cid: &Cid) -> Result` | 检查指定 CID 的数据块是否存在 |\n\n资料来源：[crates/mnem-core/src/store/blockstore.rs:1-50]()\n\n### 存储保证\n\n`Blockstore` 的实现必须满足以下契约：\n\n- **幂等性**：`put` 操作对相同内容应产生相同的 CID（使用 DAG-CBOR 规范）\n- **一致性**：读取已写入的数据必须返回完全相同的字节序列\n- **原子性**：单个 `put` 操作应保持原子性\n\n### CID 与内容映射\n\nmnem 使用 CIDv1 作为内容标识符，数据块采用 DAG-CBOR 编码格式。这种设计确保了：\n\n1. 相同内容始终映射到相同的 CID\n2. CID 包含足够的信息来验证内容完整性\n3. 存储系统无需维护独立的索引来追踪内容\n\n## OpHeadsStore 特征\n\n`OpHeadsStore` 专门用于存储和管理操作头（operation heads）。在 mnem 的操作日志模型中，每个仓库（repo）在任意时刻都可能存在多个并发的操作头，这些头指针指向最新提交的操作序列。\n\n### 核心方法\n\n| 方法 | 签名 | 功能描述 |\n|------|------|----------|\n| `get_op_heads` | `fn get_op_heads(&self) -> Result, Error>` | 获取当前所有操作头 |\n| `put_op_heads` | `fn put_op_heads(&self, heads: &[OperationId]) -> Result<(), Error>` | 原子性地更新操作头集合 |\n\n资料来源：[crates/mnem-core/src/store/op_heads.rs:1-40]()\n\n### 操作头语义\n\n操作头集合代表了仓库的当前状态边界：\n\n- **无头状态**：空的 `Vec` 表示仓库从未有过任何操作\n- **单头状态**：单一操作头表示线性历史\n- **多头状态**：多个操作头表示并发分支，需要合并\n\n## 内存后端实现\n\nmnem-core 包提供了一个内存中的参考实现，适用于测试、开发和单进程场景。\n\n### InMemoryBlockstore\n\n基于 `BTreeMap>` 实现的内存块存储：\n\n```mermaid\ngraph LR\n A[\"put(cid, block)\"] --> B[\"BTreeMap insert\"]\n C[\"get(cid)\"] --> D[\"BTreeMap lookup\"]\n E[\"has(cid)\"] --> F[\"BTreeMap contains_key\"]\n```\n\n特点：\n- 无持久化能力，进程退出后数据丢失\n- 查询性能为 O(log n)，其中 n 为存储块数量\n- 适合单元测试和快速原型开发\n\n### InMemoryOpHeadsStore\n\n同样基于内存的 OpHeadsStore 实现，使用 `Vec` 存储操作头。\n\n## Redb 后端实现\n\n`mnem-backend-redb` 提供基于 [redb](https://github.com/cberner/redb) 的持久化存储实现。redb 是一个纯 Rust 编写的嵌入式事务型 KV 数据库，具有以下特性：\n\n### 特性\n\n| 特性 | 描述 |\n|------|------|\n| 纯 Rust | 无外部依赖，符合 mnem 的安全要求 |\n| ACID 事务 | 支持完整的事务语义 |\n| 嵌入式 | 无需独立的数据库服务器 |\n| MVCC | 多版本并发控制，支持只读事务与读写事务并发 |\n\n资料来源：[crates/mnem-backend-redb/src/lib.rs:1-30]()\n\n### 数据库结构\n\n```mermaid\ngraph TD\n subgraph \"redb 数据库\"\n subgraph \"元数据表\"\n M1[\"op_heads: Vec