{
"canonical_name": "doobidoo/mcp-memory-service",
"compilation_id": "pack_7a85e6122cfc4d55ab8a35e8b1525999",
"created_at": "2026-05-12T06:20:12.651907+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 mcp-memory-service` 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 mcp-memory-service",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_26d52871bd7d4478a9b7b8f36607fcd7"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_8b991682189b8f49c8da7cda008f1722",
"canonical_name": "doobidoo/mcp-memory-service",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/doobidoo/mcp-memory-service",
"slug": "mcp-memory-service",
"source_packet_id": "phit_9e861d5e27ae4d72bf3ec51d69ea594b",
"source_validation_id": "dval_7899c8707642490e861a62147ece645b"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 mcp_host的用户",
"github_forks": 279,
"github_stars": 1835,
"one_liner_en": "Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.",
"one_liner_zh": "Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "matched_keywords:knowledge, graph, source"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "mcp-memory-service",
"title_zh": "mcp-memory-service 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Multi-agent Collaboration",
"label_zh": "多 Agent 协作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-multi-agent-collaboration",
"type": "core_capability"
},
{
"label_en": "Multi-role Workflow",
"label_zh": "多角色协作流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-multi-role-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_9e861d5e27ae4d72bf3ec51d69ea594b",
"page_model": {
"artifacts": {
"artifact_slug": "mcp-memory-service",
"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 mcp-memory-service",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/doobidoo/mcp-memory-service#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"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 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_fdb895dcb5694a15937c208c89c79c98 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.1 — Milvus consolidation fix",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c344fbad309a43aa81482c5e4b429a53 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.51.1 — Milvus consolidation fix",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.3 — Versioned memory update flag + transitive graph inference",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_e282c4b45ed04c8eb58759d1b32722bc | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.54.0 — AND/OR tag filtering for memory_search",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.55.1 — Entity Link Storage Fix",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | 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:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：feat: cascading search fallback when semantic results are sparse",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.50.0 — Plugin Hook Scaffolding",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_af91db1e780a4ee5b0c16b8ea3238bf2 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.50.0 — Plugin Hook Scaffolding",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d648b9854ac1432b8a86297ab220ba34 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 63,
"forks": 279,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 1835,
"open_issues": 8,
"pushed_at": null
},
"source_url": "https://github.com/doobidoo/mcp-memory-service",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.",
"title": "mcp-memory-service 能力包",
"trial_prompt": "# mcp-memory-service - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-memory-service 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. storage-backends：存储后端。围绕“存储后端”模拟一次用户任务，不展示安装或运行结果。\n5. knowledge-graph：知识图谱。围绕“知识图谱”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. storage-backends\n输入：用户提供的“存储后端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. knowledge-graph\n输入：用户提供的“知识图谱”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / storage-backends：Step 4 必须围绕“存储后端”形成一个小中间产物，并等待用户确认。\n- Step 5 / knowledge-graph：Step 5 必须围绕“知识图谱”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/doobidoo/mcp-memory-service\n- https://github.com/doobidoo/mcp-memory-service#readme\n- .claude/skills/gitnexus/debugging/SKILL.md\n- .claude/skills/gitnexus/exploring/SKILL.md\n- .claude/skills/gitnexus/impact-analysis/SKILL.md\n- .claude/skills/gitnexus/refactoring/SKILL.md\n- README.md\n- src/mcp_memory_service/__init__.py\n- docs/architecture.md\n- docs/setup-guide.md\n- docs/first-time-setup.md\n- install.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-memory-service 的核心服务。\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: chore(milvus): track optional BaseStorage overrides + test coverage gaps（https://github.com/doobidoo/mcp-memory-service/issues/888）；github/github_issue: feat: cascading search fallback when semantic results are sparse（https://github.com/doobidoo/mcp-memory-service/issues/873）；github/github_release: v10.55.1 — Entity Link Storage Fix（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1）；github/github_release: v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0）；github/github_release: v10.54.0 — AND/OR tag filtering for memory_search（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0）；github/github_release: v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0）；github/github_release: v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0）；github/github_release: v10.51.3 — Versioned memory update flag + transitive graph inference（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3）；github/github_release: v10.51.2 — OAuth CORS fixes + Milvus embedding hydration（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2）；github/github_release: v10.51.1 — Milvus consolidation fix（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1）；github/github_release: v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0）；github/github_release: v10.50.0 — Plugin Hook Scaffolding（https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/888"
},
{
"kind": "github_issue",
"source": "github",
"title": "feat: cascading search fallback when semantic results are sparse",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/873"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.55.1 — Entity Link Storage Fix",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.54.0 — AND/OR tag filtering for memory_search",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.51.3 — Versioned memory update flag + transitive graph inference",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.51.2 — OAuth CORS fixes + Milvus embedding hydration",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.51.1 — Milvus consolidation fix",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v10.50.0 — Plugin Hook Scaffolding",
"url": "https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.",
"effort": "安装已验证",
"forks": 278,
"icon": "search",
"name": "mcp-memory-service 能力包",
"risk": "可发布",
"slug": "mcp-memory-service",
"stars": 1830,
"tags": [
"MCP 工具",
"知识库问答",
"多 Agent 协作",
"多角色协作流程",
"评测体系"
],
"thumb": "blue",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/doobidoo/mcp-memory-service 项目说明书\n\n生成时间：2026-05-12 06:04:02 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [快速开始](#quick-start)\n- [系统架构](#architecture)\n- [存储后端](#storage-backends)\n- [知识图谱](#knowledge-graph)\n- [记忆整合系统](#consolidation)\n- [质量评分系统](#quality-scoring)\n- [MCP 协议集成](#mcp-integration)\n- [代理框架集成](#agent-frameworks)\n- [插件系统](#plugins)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [系统架构](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/README.md)\n- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)\n- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)\n- [src/mcp_memory_service/server_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)\n- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n \n\n# 项目介绍\n\n## 概述\n\nMCP Memory Service 是一个基于 MCP（Model Context Protocol）架构的语义记忆存储与检索服务。该项目为 AI 应用提供持久化记忆能力，支持语义搜索、时间范围查询、标签分类等高级功能。 资料来源：[README.md:1-10]()\n\n## 核心功能\n\n### 记忆存储与管理\n\n系统提供完整的记忆生命周期管理，包括存储、检索、删除和更新操作。每条记忆自动生成内容哈希和语义向量嵌入，便于精确匹配和相似性搜索。 资料来源：[src/mcp_memory_service/web/app.py:20-50]()\n\n### 语义搜索能力\n\n基于向量嵌入的语义相似度搜索是本项目的核心特性。用户可以使用自然语言查询，系统自动计算查询向量与存储记忆的余弦相似度，返回最相关的结果。 资料来源：[src/mcp_memory_service/api/__init__.py:10-25]()\n\n### 实时事件流\n\n通过 Server-Sent Events（SSE）技术，系统支持实时记忆事件推送。客户端可以订阅记忆创建、更新、删除等事件，实现与外部系统的实时集成。 资料来源：[src/mcp_memory_service/web/app.py:55-70]()\n\n## 技术架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[Claude Code / MCP Client] --> B[MCP Memory Service]\n B --> C[API Layer]\n C --> D[Memory Service]\n D --> E[Storage Backend]\n E --> F[SQLite-vec]\n E --> G[Cloudflare D1]\n H[Hooks / Commands] --> B\n```\n\n### 存储后端\n\n系统支持多种存储后端配置：\n\n| 后端类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| SQLite-vec | 本地向量数据库，轻量级部署 | 个人用户、小型团队 |\n| Cloudflare D1 + Vectorize | 云端向量存储，全球分发 | 企业级部署、高可用需求 |\n| Hybrid | 混合模式，结合本地和云端优势 | 复杂架构场景 |\n\n资料来源：[src/mcp_memory_service/web/app.py:120-135]()\n\n### 嵌入模型\n\n系统默认使用 **all-MiniLM-L6-v2** 嵌入模型，该模型在性能和精度之间取得良好平衡：\n\n- 向量维度：384\n- 上下文窗口：256 tokens\n- 平均延迟：5-10ms（后续调用）\n\n资料来源：[src/mcp_memory_service/web/app.py:140-145]()\n\n## API 接口\n\n### 记忆管理接口\n\n| 接口 | 方法 | 路径 | 功能 |\n|------|------|------|------|\n| 存储记忆 | POST | `/api/memories` | 存储新记忆，自动生成嵌入向量 |\n| 列出记忆 | GET | `/api/memories` | 分页列出所有记忆 |\n| 获取记忆 | GET | `/api/memories/{hash}` | 通过内容哈希获取特定记忆 |\n| 删除记忆 | DELETE | `/api/memories/{hash}` | 删除记忆及其嵌入向量 |\n\n资料来源：[src/mcp_memory_service/web/app.py:15-45]()\n\n### 搜索接口\n\n| 接口 | 方法 | 路径 | 功能 |\n|------|------|------|------|\n| 语义搜索 | POST | `/api/search` | 基于嵌入向量的语义相似度搜索 |\n| 相似记忆 | GET | `/api/search/similar/{hash}` | 查找与指定记忆相似的其他记忆 |\n\n### 事件接口\n\n| 接口 | 方法 | 路径 | 功能 |\n|------|------|------|------|\n| 事件流 | GET | `/api/events` | 订阅实时记忆事件流 |\n| 统计信息 | GET | `/api/events/stats` | 查看 SSE 连接统计 |\n\n## CLI 命令集成\n\n系统提供一系列 Claude Code CLI 命令，方便在终端环境中操作记忆：\n\n### 可用命令\n\n| 命令 | 功能 |\n|------|------|\n| `/memory-store` | 存储新记忆 |\n| `/memory-recall` | 基于时间表达式的记忆检索 |\n| `/memory-search` | 标签和内容搜索 |\n| `/memory-context` | 捕获当前会话上下文作为记忆 |\n| `/memory-health` | 服务健康检查 |\n\n资料来源：[claude_commands/README.md:15-50]()\n\n### 安装方式\n\n```bash\n# 自动安装（推荐）\npython scripts/installation/install.py\n\n# 强制安装命令\npython scripts/installation/install.py --install-claude-commands\n```\n\n## Claude Hooks 集成\n\n系统提供自动化记忆管理钩子，深度集成到 Claude Code 工作流中：\n\n### 钩子类型\n\n| 钩子名称 | 触发时机 | 功能 |\n|---------|---------|------|\n| `session-start` | 会话开始时 | 自动加载相关项目记忆 |\n| `mid-conversation` | 对话过程中 | 根据关键词触发记忆注入 |\n| `session-end` | 会话结束时 | 存储会话洞察和决策 |\n| `auto-capture` | 代码修改时 | 自动捕获代码变更上下文 |\n\n资料来源：[claude-hooks/README.md:10-30]()\n\n### 配置选项\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"your-api-key\"\n },\n \"verbosity\": {\n \"verbose\": true,\n \"showMemoryDetails\": false,\n \"cleanMode\": false\n }\n}\n```\n\n## 性能指标\n\n### 响应时间\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 首次调用 | ~50ms | 包含存储初始化开销 |\n| 后续调用 | 5-10ms | 连接复用后延迟 |\n| 内存占用 | <10MB | 服务进程内存开销 |\n\n### 成本估算\n\n- **费用**: $0.15/1M tokens\n- **10用户部署年费**: $16.43/年\n\n资料来源：[src/mcp_memory_service/api/__init__.py:5-15]()\n\n## 维护工具\n\n系统提供完整的维护脚本支持：\n\n| 脚本 | 功能 |\n|------|------|\n| `check_memory_types.py` | 检查记忆类型碎片化程度 |\n| `consolidate_memory_types.py` | 将碎片化类型合并为标准24类分类体系 |\n| `cleanup_duplicates.py` | 识别和清理重复记忆 |\n\n资料来源：[scripts/maintenance/README.md:10-40]()\n\n## 插件系统\n\n系统支持插件扩展机制，允许开发者自定义钩子处理逻辑：\n\n```python\n# 插件注册示例\ndef register(ctx):\n ctx.on(\"on_store\", my_store_handler)\n ctx.on(\"on_retrieve\", my_retrieve_handler)\n```\n\n插件通过 `entry_points` 机制自动加载：\n\n```toml\n[project.entry-points.\"mcp_memory_service.plugins\"]\nmy_plugin = \"my_package:register\"\n```\n\n资料来源：[examples/plugin-audit-log/README.md:20-35]()\n\n## 快速开始\n\n### 安装依赖\n\n```bash\npip install mcp-memory-service\n```\n\n### 启动服务\n\n```bash\nmcp-memory-http\n```\n\n### 验证安装\n\n```bash\ncurl https://localhost:8443/api/health\n```\n\n### 基础使用示例\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 存储记忆\nhash_id = store(\"New memory\", tags=[\"note\", \"important\"])\n\n# 语义搜索\nresults = search(\"architecture decisions\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# 健康检查\ninfo = health()\nprint(f\"Backend: {info.backend}, Count: {info.count}\")\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py:20-40]()\n\n## 技术栈\n\n| 组件 | 技术选型 |\n|------|---------|\n| 后端框架 | FastAPI / MCP Server |\n| 向量数据库 | SQLite-vec |\n| 嵌入模型 | all-MiniLM-L6-v2 |\n| 实时通信 | Server-Sent Events |\n| 部署方式 | Docker / Systemd / Litestream |\n\n## 总结\n\nMCP Memory Service 为 AI 应用提供了一个功能完整、高性能、可扩展的记忆存储解决方案。通过 MCP 协议与 Claude Code 的深度集成，以及丰富的 CLI 命令和 Hooks 机制，该服务能够无缝融入现有的 AI 开发工作流程，成为智能应用的\"外部大脑\"。\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py) - Web 应用与 API 端点\n- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py) - API 模块文档与使用示例\n- [src/mcp_memory_service/server_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py) - MCP 服务器实现\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md) - Claude Code 钩子安装指南\n- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md) - Claude 命令文档\n- [examples/plugin-audit-log/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/examples/plugin-audit-log/README.md) - 插件系统说明\n \n\n# 快速开始\n\nMCP Memory Service 是一个语义记忆服务，用于存储、检索和管理基于向量的语义记忆。本文档帮助你在 5 分钟内完成安装、配置并开始使用该服务。\n\n## 系统要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 核心运行环境 |\n| Node.js | 任意版本 | 用于钩子执行 |\n| jq | 最新版本 | Claude Code 状态栏显示所需 |\n| pip | 最新版本 | Python 包管理 |\n\n资料来源：[claude-hooks/README.md:44-49]()\n\n## 安装方式\n\n### 方式一：完整安装（推荐）\n\n完整安装包含 HTTP 服务器、Claude Code 钩子和命令：\n\n```bash\ncd mcp-memory-service\npython scripts/installation/install.py\n```\n\n安装脚本会依次安装：\n\n1. HTTP 服务器及其依赖\n2. Claude Code 钩子（自动记忆加载和存储）\n3. Claude Code 命令（手动记忆操作）\n4. 交互式 API 文档\n\n资料来源：[scripts/installation/install.py]() - 主安装脚本\n\n### 方式二：分步安装\n\n#### 步骤 1：安装 HTTP 服务器\n\n```bash\npip install mcp-memory-service\nmcp-memory-http # 启动服务器\n```\n\n服务器默认在 `https://localhost:8443` 运行。\n\n#### 步骤 2：安装 Claude Code 钩子\n\n```bash\ncd claude-hooks\npython install_hooks.py # 安装所有功能\n```\n\n或安装特定功能：\n\n```bash\npython install_hooks.py --basic # 基础记忆钩子\npython install_hooks.py --natural-triggers # 自然记忆触发器\n```\n\n资料来源：[claude-hooks/README.md:38-51]()\n\n#### 步骤 3：安装 Claude 命令\n\n```bash\ncd claude_commands\nclaude /install-commands\n```\n\n或使用安装脚本：\n\n```bash\npython scripts/installation/install.py --install-claude-commands\n```\n\n资料来源：[claude_commands/README.md:32-45]()\n\n## 配置\n\n### Claude Desktop 配置\n\n在 Claude Desktop 配置文件中添加 MCP 服务器：\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-memory-service\"],\n \"env\": {\n \"MCP_MEMORY_DB_PATH\": \"~/.local/share/mcp-memory/sqlite_vec.db\"\n }\n }\n }\n}\n```\n\n资料来源：[examples/claude_desktop_config_template.json]() - Claude Desktop 配置模板\n\n### 钩子配置\n\n编辑 `~/.claude/hooks/config.json` 配置记忆服务连接：\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"your-api-key\"\n },\n \"verbosity\": {\n \"verbose\": true,\n \"showMemoryDetails\": false,\n \"cleanMode\": false\n }\n}\n```\n\n资料来源：[claude-hooks/README.md:66-75]()\n\n## 服务启动\n\n### 启动 HTTP 服务器\n\n```bash\n# 使用默认配置\nmcp-memory-http\n\n# 或使用自定义配置\nmcp-memory-http --host 0.0.0.0 --port 8080\n```\n\n### 验证安装\n\n```bash\n# 检查服务健康状态\ncurl -k https://localhost:8443/api/health\n\n# 验证钩子安装\nclaude --debug hooks\n```\n\n资料来源：[claude-hooks/README.md:53-56]()\n\n## API 快速使用\n\n### Python API\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 搜索记忆（20 tokens）\nresults = search(\"架构决策\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# 存储记忆（15 tokens）\nhash_id = store(\"新记忆\", tags=[\"笔记\", \"重要\"])\nprint(f\"已存储: {hash_id}\")\n\n# 健康检查（5 tokens）\ninfo = health()\nprint(f\"后端: {info.backend}, 数量: {info.count}\")\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py:1-20]()\n\n### REST API 端点\n\n| 方法 | 端点 | 说明 |\n|------|------|------|\n| POST | `/api/memories` | 存储新记忆（自动生成嵌入向量） |\n| GET | `/api/memories` | 列出所有记忆（支持分页） |\n| GET | `/api/memories/{hash}` | 按内容哈希检索特定记忆 |\n| DELETE | `/api/memories/{hash}` | 删除记忆及其嵌入向量 |\n| POST | `/api/search` | 语义相似性搜索 |\n| GET | `/api/search/similar/{hash}` | 查找相似记忆 |\n| GET | `/api/events` | 订阅实时记忆事件流 |\n\n资料来源：[src/mcp_memory_service/web/app.py:1-50]()\n\n## Claude 命令速查\n\n| 命令 | 用途 | 示例 |\n|------|------|------|\n| `/memory-recall` | 自然语言时间检索 | `/memory-recall \"上周的数据库讨论\"` |\n| `/memory-search` | 标签和内容搜索 | `/memory-search --tags \"架构,数据库\"` |\n| `/memory-context` | 上下文记忆保存 | `/memory-context --summary \"架构规划\"` |\n| `/memory-health` | 服务健康检查 | `/memory-health --detailed` |\n\n资料来源：[claude_commands/README.md:1-30]()\n\n## 插件系统\n\n### 安装插件\n\n创建包含入口点的 Python 包：\n\n```toml\n[project.entry-points.\"mcp_memory_service.plugins\"]\nmy_plugin = \"my_package:register\"\n```\n\n### 实现插件\n\n```python\ndef register(ctx):\n ctx.on(\"on_store\", my_store_handler)\n ctx.on(\"on_retrieve\", my_retrieve_handler)\n```\n\n### 可用钩子\n\n| 钩子 | 用途 |\n|------|------|\n| `on_store` | 记录哈希、类型、标签、内容长度 |\n| `on_delete` | 记录删除的哈希 |\n| `on_retrieve` | 记录查询和结果数量 |\n| `on_consolidate` | 记录合并统计 |\n\n资料来源：[examples/plugin-audit-log/README.md:1-40]()\n\n## 性能指标\n\n| 指标 | 数值 |\n|------|------|\n| 首次调用 | ~50ms（含存储初始化） |\n| 后续调用 | ~5-10ms（连接复用） |\n| 内存开销 | <10MB |\n| 每百万 token 成本 | $0.15（10 用户部署约 $16.43/年） |\n\n资料来源：[src/mcp_memory_service/api/__init__.py:10-16]()\n\n## 故障排除\n\n| 问题 | 解决方案 |\n|------|----------|\n| 钩子未检测到 | 运行 `ls ~/.claude/settings.json`，如缺失则重新安装 |\n| JSON 解析错误 | 更新到最新版本（含 Python 字典转换） |\n| 连接失败 | 检查 `curl -k https://your-endpoint:8443/api/health` |\n| 目录错误 | 将 `~/.claude-code/hooks/*` 移动到 `~/.claude/hooks/` |\n\n资料来源：[claude-hooks/README.md:58-68]()\n\n## 后续步骤\n\n- 查看 [维护脚本](../maintenance/README.md) 了解数据库优化\n- 配置 Litestream 实现自动备份\n- 探索插件系统扩展功能\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[存储后端](#storage-backends), [知识图谱](#knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)\n- [src/mcp_memory_service/server/__main__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/__main__.py)\n- [src/mcp_memory_service/services/memory_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py)\n- [src/mcp_memory_service/services/graph_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py)\n- [docs/architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture.md)\n- [docs/architecture/graph-database-design.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture/graph-database-design.md)\n \n\n# 系统架构\n\n## 概述\n\nMCP Memory Service 是一个基于 Model Context Protocol (MCP) 的语义记忆服务系统，旨在为 AI 助手和开发者提供持久化、可搜索的上下文记忆能力。该系统通过向量嵌入技术实现语义相似度搜索，支持跨机器同步，并提供多种访问接口包括 MCP 协议、REST API、CLI 命令和 Web 界面。\n\n系统的核心设计理念是创建一个**轻量级但功能强大**的记忆服务，使得 AI 能够在多轮对话和跨会话场景中保持上下文连续性。通过自动嵌入生成、智能标签管理和关系图谱构建，系统能够高效地组织和检索记忆内容。\n\n---\n\n## 整体架构\n\n### 分层架构设计\n\nMCP Memory Service 采用分层架构，将系统划分为清晰的功能层级：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| **接口层** | MCP Server、Web API、CLI、Web UI | 提供多种访问方式 |\n| **服务层** | Memory Service、Graph Service | 核心业务逻辑 |\n| **存储层** | SQLite-Vec、文件系统 | 数据持久化 |\n| **同步层** | Litestream 配置 | 跨机器数据同步 |\n\n### 核心组件交互\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n Claude[Claude Code]\n HTTP[HTTP 客户端]\n CLI[CLI 命令]\n MCP[MCP 客户端]\n end\n \n subgraph \"接口层\"\n MCP_Server[MCP Server
mcp_server.py]\n Web_API[Web API
app.py]\n CLI_Main[CLI Main
main.py]\n end\n \n subgraph \"服务层\"\n Memory_Service[Memory Service
memory_service.py]\n Graph_Service[Graph Service
graph_service.py]\n Embedding[Embedding Service]\n Search[Search Service]\n end\n \n subgraph \"存储层\"\n SQLite_Vec[(SQLite-Vec
向量数据库)]\n File_System[(文件系统
配置与备份)]\n end\n \n subgraph \"同步层\"\n Litestream[Litestream
跨机器同步]\n end\n \n Claude --> MCP_Server\n MCP --> MCP_Server\n HTTP --> Web_API\n CLI --> CLI_Main\n \n MCP_Server --> Memory_Service\n Web_API --> Memory_Service\n CLI_Main --> Memory_Service\n \n Memory_Service --> SQLite_Vec\n Graph_Service --> SQLite_Vec\n Memory_Service --> Embedding\n \n Litestream --> SQLite_Vec\n```\n\n---\n\n## MCP 协议层\n\n### MCP Server 实现\n\nMCP Server 是系统的核心接口之一，遵循 Model Context Protocol 规范实现。服务器通过 MCP 工具暴露记忆管理功能，使 Claude Code 等 MCP 兼容客户端能够直接调用记忆服务。\n\n**核心功能模块**：\n\n- **工具注册**：动态注册 MCP 工具到客户端\n- **请求路由**：将 MCP 请求分发到对应的服务层方法\n- **响应格式化**：将服务层结果转换为 MCP 协议格式\n- **错误处理**：统一异常捕获和错误响应\n\n### MCP 工具列表\n\n| 工具名称 | 功能描述 | 参数 |\n|---------|---------|------|\n| `memory-store` | 存储新记忆，自动生成嵌入向量 | content, tags, memory_type, metadata |\n| `memory-recall` | 基于语义相似度检索记忆 | query, limit, tags, time_range |\n| `memory-search` | 标签和内容关键词搜索 | query, tags, memory_type |\n| `memory-list` | 列出所有记忆，支持分页 | limit, offset, tags |\n| `memory-delete` | 删除指定记忆 | content_hash |\n| `memory-update` | 更新记忆内容和标签 | content_hash, content, tags |\n\n---\n\n## 服务层架构\n\n### Memory Service\n\nMemory Service 是系统的核心业务逻辑层，负责处理所有与记忆相关的操作。该服务封装了存储、检索、更新和删除的完整流程，并与嵌入服务紧密协作实现语义搜索功能。\n\n**主要职责**：\n\n1. **记忆存储**：接收原始内容，调用嵌入服务生成向量，存储到 SQLite-Vec\n2. **语义搜索**：将查询文本转换为向量，执行相似度搜索\n3. **标签管理**：维护和索引记忆标签，支持多标签过滤\n4. **类型分类**：支持 24 种标准化的记忆类型分类体系\n5. **元数据管理**：处理机器标识、时间戳、自定义元数据\n\n**存储流程**：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[内容验证]\n B --> C[生成 SHA256 Hash]\n C --> D{检查重复}\n D -->|已存在| E[返回现有记录]\n D -->|新内容| F[Embedding 生成]\n F --> G[向量存储]\n G --> H[元数据存储]\n H --> I[(SQLite-Vec)]\n I --> J[发送 SSE 事件]\n```\n\n### Graph Service\n\nGraph Service 负责构建和维护记忆之间的关系图谱。该服务基于 SQLite-Vec 的图扩展实现，支持复杂的关系查询和推理。\n\n**核心能力**：\n\n- **关系建模**：定义记忆间的多种关系类型\n- **关系推理**：自动推断和补全关系\n- **图遍历**：支持深度优先和广度优先遍历\n- **关系查询**：基于关系路径的复杂查询\n\n### Embedding Service\n\n嵌入服务负责将文本内容转换为高维向量表示，支持多种嵌入模型：\n\n| 配置项 | 默认值 | 说明 |\n|-------|-------|------|\n| `EMBEDDING_MODEL` | `nomic-embed-text` | 嵌入模型名称 |\n| `EMBEDDING_DIMENSIONS` | `768` | 向量维度 |\n| `EMBEDDING_API_URL` | - | 自定义嵌入 API 端点 |\n\n---\n\n## 存储层设计\n\n### SQLite-Vec 数据库架构\n\n系统使用 SQLite-Vec 作为主要存储引擎，结合了传统关系型数据库的可靠性和向量搜索的能力。\n\n**数据库结构**：\n\n| 表名 | 用途 | 关键字段 |\n|------|------|---------|\n| `memories` | 记忆主表 | id, content, content_hash, memory_type, created_at, updated_at |\n| `tags` | 标签表 | id, tag_name, memory_id |\n| `embeddings` | 向量表 | id, memory_id, vector, model |\n| `graph_edges` | 关系边表 | id, from_id, to_id, relationship_type, properties |\n| `metadata` | 元数据表 | id, memory_id, key, value |\n\n**性能特性**：\n\n- **向量索引**：支持 HNSW 和 IVF 索引类型\n- **事务支持**：完整的 ACID 事务保证\n- **并发访问**：支持多进程并发读写\n- **备份恢复**：内置备份机制，支持时间点恢复\n\n### 数据目录结构\n\n```\n~/.local/share/mcp-memory/\n├── sqlite_vec.db # 主数据库\n├── sqlite_vec.db.backup-* # 自动备份\n└── logs/ # 日志目录\n```\n\n---\n\n## API 层架构\n\n### Web API 设计\n\nWeb API 基于 FastAPI 框架构建，提供完整的 RESTful 接口和交互式文档。\n\n**API 端点概览**：\n\n| 类别 | 端点 | 方法 | 功能 |\n|------|------|------|------|\n| 记忆管理 | `/api/memories` | POST | 存储新记忆 |\n| | `/api/memories` | GET | 列出所有记忆 |\n| | `/api/memories/{hash}` | GET | 获取指定记忆 |\n| | `/api/memories/{hash}` | DELETE | 删除记忆 |\n| 搜索操作 | `/api/search` | POST | 语义搜索 |\n| | `/api/search/similar/{hash}` | GET | 查找相似记忆 |\n| 实时事件 | `/api/events` | GET | SSE 事件流 |\n| | `/api/events/stats` | GET | 连接统计 |\n| 系统状态 | `/api/health` | GET | 健康检查 |\n\n### 响应大小限制\n\n系统内置响应限制器防止上下文窗口溢出：\n\n```python\n# 环境变量配置\nMCP_MAX_RESPONSE_CHARS=0 # 0 = 无限制\n```\n\n限制器功能包括：\n- 按记忆边界截断\n- 返回截断元数据（总数、已显示数、字符数）\n- 支持格式化截断响应\n\n---\n\n## 同步层设计\n\n### Litestream 跨机器同步\n\n系统支持通过 Litestream 实现数据库的持续复制和跨机器同步，确保多设备间的数据一致性。\n\n**同步架构**：\n\n```mermaid\ngraph LR\n A[主设备] -->|写入| B[(本地 SQLite)]\n A -->|Litestream| C[(S3 存储桶)]\n D[从设备] -->|Litestream| C\n D -->|读取| E[(本地 SQLite)]\n```\n\n**配置文件路径**：`src/mcp_memory_service/sync/litestream_config.py`\n\n**支持平台**：\n\n| 平台 | 安装方式 |\n|------|---------|\n| macOS | `brew install benbjohnson/litestream/litestream` |\n| Linux | `curl -LsS ... \\| tar -xzf -` |\n| Windows | 手动下载二进制文件 |\n\n### 导入导出机制\n\n系统提供完整的 JSON 导入导出功能，支持批量数据迁移和跨实例同步：\n\n```json\n{\n \"export_metadata\": {\n \"source_machine\": \"machine-name\",\n \"export_timestamp\": \"2025-08-12T10:30:00Z\",\n \"total_memories\": 450,\n \"database_path\": \"/path/to/sqlite_vec.db\",\n \"platform\": \"Windows\"\n },\n \"memories\": [...]\n}\n```\n\n**性能指标**：\n- 导出速度：约 1000 条记忆/秒\n- 导入速度：约 500 条记忆/秒（含去重）\n- 平均大小：约 1KB/条记忆\n\n---\n\n## 客户端集成\n\n### Claude Code 钩子集成\n\n系统提供 Claude Code 集成钩子，实现自动记忆加载和会话上下文管理：\n\n**钩子组件**：\n\n| 钩子 | 版本 | 触发时机 |\n|------|------|---------|\n| `session-start.js` | v2.2 | 会话启动时 |\n| `session-end.js` | - | 会话结束时 |\n| `memory-retrieval.js` | - | 记忆检索请求 |\n| `permission-request.js` | v1.0 | 权限请求时（全局生效） |\n\n### CLI 命令\n\n| 命令 | 功能 | 示例 |\n|------|------|------|\n| `memory server` | 启动 MCP 服务器 | `memory server --debug` |\n| `memory recall` | 语义检索记忆 | `memory recall \"架构决策\"` |\n| `memory search` | 搜索记忆 | `memory search --tags \"note\"` |\n| `memory store` | 存储记忆 | `memory store \"新内容\" --tags \"note\"` |\n| `memory health` | 健康检查 | `memory health --detailed` |\n| `memory logs` | 查看日志 | `memory logs --lines 50` |\n\n---\n\n## 安全与配置\n\n### 认证机制\n\n系统支持可选的 API Key 认证：\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"your-api-key\"\n }\n}\n```\n\n### 环境变量配置\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `MCP_SERVER_HOST` | `0.0.0.0` | 服务监听地址 |\n| `MCP_SERVER_PORT` | `8443` | 服务监听端口 |\n| `MCP_API_KEY` | - | API 认证密钥 |\n| `MCP_DATA_DIR` | `~/.local/share/mcp-memory/` | 数据目录 |\n| `EMBEDDING_MODEL` | `nomic-embed-text` | 嵌入模型 |\n| `EMBEDDING_DIMENSIONS` | `768` | 向量维度 |\n| `MCP_MAX_RESPONSE_CHARS` | `0` | 最大响应字符数 |\n\n---\n\n## 维护工具\n\n### 维护脚本概览\n\n| 脚本 | 用途 | 关键功能 |\n|------|------|---------|\n| `consolidate_memory_types.py` | 类型归并 | 将碎片化类型合并为 24 种标准类型 |\n| `cleanup_memories.py` | 记忆清理 | 清理孤立记忆和过期数据 |\n| `find_duplicates.py` | 去重检测 | 查找并移除重复记忆 |\n| `repair_memories.py` | 数据修复 | 修复损坏的记忆条目 |\n| `repair_sqlite_vec_embeddings.py` | 向量修复 | 修复嵌入不一致问题 |\n| `migrate_embeddings.py` | 模型迁移 | 迁移到不同的嵌入模型 |\n\n### 类型归并功能\n\n支持将多个相似类型归并为标准类型：\n\n```json\n{\n \"mappings\": {\n \"bug-fix\": \"fix\",\n \"technical-solution\": \"solution\",\n \"old-type-name\": \"new-type-name\"\n }\n}\n```\n\n**标准 24 种类型分类**：\n- 内容类型：`note`、`reference`、`document`、`guide`\n- 活动类型：`session`、`implementation`、`analysis`\n\n---\n\n## 总结\n\nMCP Memory Service 采用模块化分层架构，核心优势包括：\n\n1. **多协议支持**：同时提供 MCP、REST API、CLI 三种访问方式\n2. **语义搜索**：基于向量嵌入的语义相似度检索\n3. **关系图谱**：支持复杂关系建模和推理\n4. **跨设备同步**：通过 Litestream 实现多设备数据一致性\n5. **可维护性**：完善的维护工具和自动备份机制\n6. **上下文感知**：与 Claude Code 深度集成，自动加载相关记忆\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [记忆整合系统](#consolidation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/storage/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/__init__.py)\n- [src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)\n- [src/mcp_memory_service/storage/sqlite_vec.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/sqlite_vec.py)\n- [src/mcp_memory_service/storage/cloudflare.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/cloudflare.py)\n- [src/mcp_memory_service/storage/hybrid.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/hybrid.py)\n- [src/mcp_memory_service/storage/milvus.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus.py)\n- [src/mcp_memory_service/storage/milvus_graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus_graph.py)\n- [docs/guides/STORAGE_BACKENDS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/STORAGE_BACKENDS.md)\n- [docs/milvus-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/milvus-backend.md)\n- [docs/cloudflare-setup.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/cloudflare-setup.md)\n \n\n# 存储后端\n\n## 概述\n\n存储后端是 MCP Memory Service 的核心组件，负责管理记忆数据的持久化存储和向量嵌入检索功能。该服务支持多种存储后端实现，允许用户根据性能需求、部署环境和成本考虑选择最适合的解决方案。\n\nMCP Memory Service 采用模块化存储架构，通过统一的抽象接口支持不同后端实现的无缝切换，同时保证数据模型和操作语义的一致性。资料来源：[src/mcp_memory_service/storage/__init__.py]()\n\n## 架构设计\n\n### 存储后端层次结构\n\n```mermaid\ngraph TD\n A[MCP Memory Service] --> B[存储抽象层]\n B --> C[工厂模式选择器]\n C --> D[SQLite Vec 后端]\n C --> E[Cloudflare 后端]\n C --> F[Milvus 后端]\n C --> G[Hybrid 混合后端]\n C --> H[Milvus Graph 后端]\n```\n\n### 核心存储接口\n\n所有存储后端必须实现统一的抽象接口，确保功能一致性和可替换性：\n\n| 接口方法 | 功能描述 | 返回类型 |\n|---------|---------|---------|\n| `store()` | 存储记忆及其向量嵌入 | str (content_hash) |\n| `retrieve()` | 根据内容哈希检索记忆 | Memory |\n| `search()` | 向量相似性搜索 | List[Memory] |\n| `delete()` | 删除指定记忆 | bool |\n| `list()` | 分页列出所有记忆 | List[Memory] |\n| `health()` | 检查存储健康状态 | HealthInfo |\n\n资料来源：[src/mcp_memory_service/storage/factory.py]()\n\n## 支持的存储后端\n\n### SQLite Vec 后端\n\nSQLite Vec 是默认且推荐的本地存储后端，适用于单机部署场景。\n\n**核心特性**：\n\n- 完全本地化部署，数据隐私保护\n- 使用 SQLite 存储结构化数据\n- 使用 sqlite-vec 扩展处理向量嵌入\n- 支持 ACID 事务保证数据一致性\n- 首次调用约 50ms（含存储初始化）\n- 后续调用约 5-10ms（连接复用）\n- 内存开销小于 10MB\n- 成本估算：每 10 用户部署约 $16.43/年（按 $0.15/1M tokens）\n\n**配置参数**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `db_path` | str | ~/.local/share/mcp-memory/ | 数据库文件路径 |\n| `embedding_model` | str | BAAI/bge-m3 | 嵌入模型名称 |\n| `embedding_dim` | int | 1024 | 嵌入向量维度 |\n\n资料来源：[src/mcp_memory_service/storage/sqlite_vec.py]()\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n### Cloudflare 后端\n\nCloudflare 后端使用 Cloudflare Workers Vectorize 实现云端向量存储，适合无服务器部署场景。\n\n**核心特性**：\n\n- 完全托管的云端向量数据库\n- 无需管理服务器基础设施\n- 全球分布式低延迟访问\n- 按使用量付费的成本模型\n- 支持 HTTP/HTTPS 自动检测连接\n\n**配置要求**：\n\n| 参数 | 必需 | 说明 |\n|-----|-----|-----|\n| `CLOUDFLARE_ACCOUNT_ID` | 是 | Cloudflare 账户 ID |\n| `CLOUDFLARE_API_TOKEN` | 是 | API 访问令牌 |\n| `vectorize_index_name` | 是 | Vectorize 索引名称 |\n| `embedding_model` | 否 | 嵌入模型（默认 BAAI/bge-m3）|\n\n**适用场景**：\n\n- Serverless 架构部署\n- 需要全球化访问的项目\n- 不想维护本地基础设施的用户\n\n资料来源：[src/mcp_memory_service/storage/cloudflare.py]()\n资料来源：[docs/cloudflare-setup.md]()\n\n### Milvus 后端\n\nMilvus 是高性能的分布式向量数据库，适合大规模数据场景。\n\n**核心特性**：\n\n- 支持十亿级向量规模\n- 分布式水平扩展能力\n- 多种索引类型支持（IVF、HNSW 等）\n- 高并发查询处理\n- 支持混合标量过滤\n\n**配置参数**：\n\n| 参数 | 必需 | 说明 |\n|-----|-----|-----|\n| `MILVUS_HOST` | 是 | Milvus 服务器地址 |\n| `MILVUS_PORT` | 是 | Milvus 端口（默认 19530） |\n| `MILVUS_USER` | 否 | 用户名 |\n| `MILVUS_PASSWORD` | 否 | 密码 |\n| `COLLECTION_NAME` | 否 | 集合名称（默认 memories）|\n| `INDEX_TYPE` | 否 | 索引类型（默认 HNSW）|\n\n资料来源：[src/mcp_memory_service/storage/milvus.py]()\n资料来源：[docs/milvus-backend.md]()\n\n### Milvus Graph 后端\n\nMilvus Graph 是 Milvus 后端的增强版本，集成了图数据库能力，提供关系型记忆检索。\n\n**扩展功能**：\n\n- 记忆间关系图的存储和查询\n- 支持复杂的多跳关系推理\n- 关系类型推断引擎\n- 路径查询支持\n\n资料来源：[src/mcp_memory_service/storage/milvus_graph.py]()\n\n### Hybrid 混合后端\n\nHybrid 后端支持同时使用多个存储后端，实现数据冗余和负载分发。\n\n**架构特点**：\n\n```mermaid\ngraph LR\n A[写入请求] --> B[主存储]\n A --> C[备份存储]\n B --> D[向量数据]\n C --> D\n E[读取请求] --> F[负载均衡]\n F --> B\n F --> C\n```\n\n**优势**：\n\n- 数据冗余备份，提高可靠性\n- 读写分离提升性能\n- 支持渐进式迁移\n- 故障自动切换\n\n资料来源：[src/mcp_memory_service/storage/hybrid.py]()\n\n## 工厂模式与后端选择\n\n### 存储工厂\n\n存储工厂根据配置自动实例化相应的存储后端：\n\n```python\n# 后端选择逻辑伪代码\ndef create_storage(backend_type: str, config: dict) -> BaseStorage:\n backends = {\n \"sqlite_vec\": SQLiteVecStorage,\n \"cloudflare\": CloudflareStorage,\n \"milvus\": MilvusStorage,\n \"milvus_graph\": MilvusGraphStorage,\n \"hybrid\": HybridStorage,\n }\n return backends.get(backend_type)(config)\n```\n\n资料来源：[src/mcp_memory_service/storage/factory.py]()\n\n### 环境变量配置\n\n后端选择通过环境变量控制：\n\n| 环境变量 | 可选值 | 说明 |\n|---------|-------|-----|\n| `MCP_MEMORY_BACKEND` | sqlite_vec, cloudflare, milvus, hybrid | 指定存储后端类型 |\n| `STORAGE_URL` | 数据库连接 URL | 各后端特定配置 |\n\n### 后端选择决策树\n\n```mermaid\ngraph TD\n A[选择存储后端] --> B{部署环境?}\n B -->|本地/单机| C[SQLite Vec]\n B -->|Serverless| D[Cloudflare]\n B -->|大规模/分布式| E[Milvus]\n B -->|需要图关系| F[Milvus Graph]\n B -->|高可用需求| G[Hybrid]\n C --> H[默认推荐]\n D --> I[低成本起步]\n E --> J[高性能扩展]\n F --> K[关系推理]\n G --> L[容错备份]\n```\n\n## 数据模型\n\n### 记忆数据结构\n\n所有存储后端使用统一的数据模型：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `content` | str | 记忆内容 |\n| `content_hash` | str | SHA256 内容哈希 |\n| `tags` | List[str] | 标签列表 |\n| `memory_type` | str | 记忆类型 |\n| `created_at` | float | 创建时间戳 |\n| `updated_at` | float | 更新时间戳 |\n| `metadata` | dict | 额外元数据 |\n| `embedding` | List[float] | 向量嵌入（后端存储）|\n\n### 记忆类型分类\n\n系统支持标准化的 24 类记忆类型：\n\n**内容类型**：`note`、`reference`、`document`、`guide`\n\n**活动类型**：`session`、`implementation`、`analysis`\n\n**其他分类**：`fix`、`solution`、`decision` 等\n\n资料来源：[scripts/maintenance/README.md]()\n\n## 向量嵌入\n\n### 嵌入模型\n\n默认使用 BAAI/bge-m3 模型：\n\n| 模型 | 维度 | 说明 |\n|-----|------|-----|\n| BAAI/bge-m3 | 1024 | 默认模型，多语言支持 |\n| 其他兼容模型 | 可配置 | 支持自定义模型 |\n\n### 嵌入维度迁移\n\n系统提供嵌入模型迁移脚本：\n\n```bash\npython maintenance/migrate_embeddings.py --url --model --dry-run\n```\n\n功能特性：\n\n- 支持维度变更\n- 干运行模式预览\n- 批量更新处理\n- 回滚支持\n\n资料来源：[scripts/README.md]()\n\n## 数据库迁移\n\n### Litestream 实时复制\n\n支持使用 Litestream 进行数据库实时复制和灾难恢复：\n\n**支持的平台**：\n\n| 平台 | 安装方式 |\n|-----|---------|\n| macOS | `brew install benbjohnson/litestream/litestream` |\n| Linux | `curl -LsS ... \\| tar -xzf -` |\n| Windows | 手动下载安装 |\n\n**配置示例**（macOS plist）：\n\n```xml\n\n ProgramArguments\n \n /usr/local/bin/litestream\n replicate\n -config\n {config_path}\n \n RunAtLoad\n \n KeepAlive\n \n\n```\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py]()\n\n## 维护工具\n\n### 记忆类型规范化\n\n`consolidate_memory_types.py` 脚本用于合并碎片化的记忆类型：\n\n```bash\n# 预览更改（只读）\npython scripts/maintenance/consolidate_memory_types.py --dry-run\n\n# 执行合并\npython scripts/maintenance/consolidate_memory_types.py\n\n# 使用自定义配置\npython scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json\n```\n\n**性能指标**：\n\n- 1,000 条记忆更新约 5 秒\n- 自动创建带时间戳的备份\n- 事务安全（原子操作，失败回滚）\n\n**安全特性**：\n\n- 自动备份机制\n- 干运行模式预览\n- 数据库锁检测\n- 磁盘空间验证\n- 备份完整性检查\n\n资料来源：[scripts/maintenance/README.md]()\n\n### 修复和维护脚本\n\n| 脚本 | 功能 |\n|-----|------|\n| `repair_memories.py` | 修复损坏的记忆条目 |\n| `repair_sqlite_vec_embeddings.py` | 修复嵌入不一致问题 |\n| `repair_zero_embeddings.py` | 修复零值/空值嵌入 |\n| `cleanup_corrupted_encoding.py` | 修复损坏的 Emoji 编码 |\n| `find_duplicates.py` | 查找并删除重复记忆 |\n\n资料来源：[scripts/README.md]()\n\n## 性能比较\n\n| 后端 | 首次调用 | 后续调用 | 内存开销 | 扩展性 |\n|-----|---------|---------|---------|-------|\n| SQLite Vec | ~50ms | ~5-10ms | <10MB | 单机 |\n| Cloudflare | 可变 | 可变 | 无 | 全球分布 |\n| Milvus | ~20ms | ~5ms | 可配置 | 分布式 |\n| Hybrid | 组合 | 组合 | 组合 | 高可用 |\n\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n## 配置示例\n\n### SQLite Vec 配置\n\n```json\n{\n \"backend\": \"sqlite_vec\",\n \"db_path\": \"~/.local/share/mcp-memory/\",\n \"embedding_model\": \"BAAI/bge-m3\",\n \"embedding_dim\": 1024\n}\n```\n\n### Cloudflare 配置\n\n```json\n{\n \"backend\": \"cloudflare\",\n \"CLOUDFLARE_ACCOUNT_ID\": \"your-account-id\",\n \"CLOUDFLARE_API_TOKEN\": \"your-api-token\",\n \"vectorize_index_name\": \"memories-index\",\n \"embedding_model\": \"BAAI/bge-m3\"\n}\n```\n\n### Milvus 配置\n\n```json\n{\n \"backend\": \"milvus\",\n \"MILVUS_HOST\": \"localhost\",\n \"MILVUS_PORT\": 19530,\n \"MILVUS_USER\": \"username\",\n \"MILVUS_PASSWORD\": \"password\",\n \"COLLECTION_NAME\": \"memories\",\n \"INDEX_TYPE\": \"HNSW\"\n}\n```\n\n## 扩展阅读\n\n- [存储后端完整指南](docs/guides/STORAGE_BACKENDS.md)\n- [Milvus 后端配置](docs/milvus-backend.md)\n- [Cloudflare 设置指南](docs/cloudflare-setup.md)\n- [数据库维护脚本](scripts/README.md)\n\n---\n\n\n\n## 知识图谱\n\n### 相关页面\n\n相关主题：[记忆整合系统](#consolidation), [系统架构](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/storage/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)\n- [src/mcp_memory_service/models/association.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/association.py)\n- [src/mcp_memory_service/reasoning/entities.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)\n- [src/mcp_memory_service/reasoning/inference.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/inference.py)\n- [src/mcp_memory_service/consolidation/relationship_inference.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/relationship_inference.py)\n- [src/mcp_memory_service/consolidation/associations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/associations.py)\n- [src/mcp_memory_service/server/handlers/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n- [docs/wiki-Graph-Database-Architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/wiki-Graph-Database-Architecture.md)\n- [docs/migrations/010-asymmetric-relationships.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/migrations/010-asymmetric-relationships.md)\n \n\n# 知识图谱\n\n## 概述\n\nMCP Memory Service 的知识图谱模块是系统的核心组件之一，负责管理和维护记忆之间的语义关系。与传统的关系型存储不同，知识图谱通过节点（记忆）和边（关联）的方式组织数据，使得复杂的关联查询和推理成为可能。\n\n知识图谱系统的主要目标包括：\n\n- **语义关联**：自动发现并建立记忆之间的语义关联\n- **关系推理**：基于现有关系推断新的潜在关联\n- **图查询**：支持基于图结构的复杂查询操作\n- **上下文增强**：为 AI 推理提供丰富的上下文关系网络\n\n## 架构设计\n\n### 核心组件\n\n知识图谱系统由以下几个核心模块组成：\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 图存储层 | `src/mcp_memory_service/storage/graph.py` | 管理图数据的持久化和索引 |\n| 关联模型 | `src/mcp_memory_service/models/association.py` | 定义记忆间关联的数据结构 |\n| 实体识别 | `src/mcp_memory_service/reasoning/entities.py` | 从记忆内容中提取实体 |\n| 推理引擎 | `src/mcp_memory_service/reasoning/inference.py` | 执行关系推理和推断 |\n| 关联推断 | `src/mcp_memory_service/consolidation/relationship_inference.py` | 批量推断和优化关联 |\n| API 处理器 | `src/mcp_memory_service/server/handlers/graph.py` | 提供图查询的 HTTP 接口 |\n\n### 架构层次\n\n```mermaid\ngraph TB\n subgraph \"表现层\"\n A[Graph API Handlers]\n end\n \n subgraph \"服务层\"\n B[Relationship Inference Engine]\n C[Entity Recognition Module]\n D[Inference Processor]\n end\n \n subgraph \"存储层\"\n E[Graph Storage]\n F[Association Models]\n end\n \n A --> B\n A --> C\n B --> D\n C --> D\n D --> E\n F --> E\n \n G[(Vector Embeddings)] --> B\n G --> C\n```\n\n## 关联模型\n\n### 数据结构\n\n关联模型 (`Association`) 是知识图谱的边，连接两个记忆节点：\n\n```python\nclass Association:\n source_hash: str # 源记忆哈希\n target_hash: str # 目标记忆哈希\n relation_type: str # 关系类型\n confidence: float # 置信度 0.0-1.0\n metadata: Dict # 额外元数据\n```\n\n### 非对称关系\n\n系统支持非对称关系的建模，这是知识图谱的核心特性之一。资料来源：[docs/migrations/010-asymmetric-relationships.md]()\n\n```mermaid\ngraph LR\n A[记忆 A] -->|\"基于\"| B[记忆 B]\n B -->|\"衍生自\"| A\n```\n\n非对称关系意味着：\n- 关系方向有实际意义\n- A→B 与 B→A 表示不同的语义\n- 支持更精确的因果和依赖建模\n\n### 关系类型\n\n| 关系类型 | 描述 | 典型场景 |\n|----------|------|----------|\n| `related` | 语义相关 | 一般关联 |\n| `derived_from` | 衍生关系 | 实现源自设计 |\n| `contradicts` | 矛盾关系 | 冲突的决策 |\n| `references` | 引用关系 | 引用外部资源 |\n| `similar` | 相似关系 | 内容相似度高 |\n\n## 实体识别\n\n实体识别模块 (`entities.py`) 负责从记忆内容中提取有意义的实体：\n\n### 提取流程\n\n```mermaid\ngraph TD\n A[记忆内容] --> B[文本预处理]\n B --> C[命名实体识别]\n C --> D[实体消歧]\n D --> E[实体标准化]\n E --> F[实体图谱]\n```\n\n### 实体类型\n\n识别并支持的实体类型包括：\n\n| 实体类型 | 示例 | 用途 |\n|----------|------|------|\n| `person` | 人名 | 人员关联 |\n| `organization` | 公司/组织 | 组织归属 |\n| `technology` | 技术名称 | 技术栈关联 |\n| `concept` | 抽象概念 | 知识分类 |\n| `document` | 文档引用 | 文档关系 |\n\n资料来源：[src/mcp_memory_service/reasoning/entities.py]()\n\n## 推理引擎\n\n推理引擎是知识图谱的智能核心，基于现有关联推断新的潜在关系。\n\n### 推理方法\n\n| 方法 | 描述 | 输入 | 输出 |\n|------|------|------|------|\n| 传递推理 | A→B, B→C ⇒ A→C | 两条边 | 推断的第三条边 |\n| 相似传播 | A≈B ⇒ A的属性≈B的属性 | 相似实体 | 属性映射 |\n| 反事实推理 | A导致B ⇒ ¬B ⇒ ¬A | 因果关系 | 反向推断 |\n\n### 置信度计算\n\n```mermaid\ngraph LR\n A[关系证据] --> B{证据强度}\n B -->|强| C[高置信度 0.8-1.0]\n B -->|中| D[中置信度 0.5-0.8]\n B -->|弱| E[低置信度 0.2-0.5]\n```\n\n置信度计算考虑因素：\n\n1. **共现频率**：两个记忆在同一上下文中出现的次数\n2. **语义相似度**：基于向量的余弦相似度\n3. **关系传递路径**：推理路径的长度\n4. **来源可靠性**：记忆来源的可信度评分\n\n资料来源：[src/mcp_memory_service/reasoning/inference.py]()\n\n## 图存储\n\n### 存储架构\n\n图存储模块 (`graph.py`) 负责将图数据持久化：\n\n```mermaid\ngraph TB\n subgraph \"存储层\"\n A[(SQLite Vec)]\n B[(向量索引)]\n C[(关系统引)]\n end\n \n subgraph \"索引\"\n D[哈希索引]\n E[关系类型索引]\n F[时间索引]\n end\n \n A --> D\n A --> E\n A --> F\n B --> D\n C --> E\n```\n\n### 存储优化\n\n- **批量写入**：支持批量关联写入以提高性能\n- **增量更新**：仅更新变化的关联\n- **索引维护**：自动维护关系类型和哈希索引\n\n资料来源：[src/mcp_memory_service/storage/graph.py]()\n\n## API 接口\n\n### 图查询端点\n\n系统通过 REST API 提供图查询能力：\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/graph/related/{hash}` | GET | 获取记忆的关联 |\n| `/api/graph/infer` | POST | 执行推理查询 |\n| `/api/graph/path` | POST | 查找两记忆间的路径 |\n\n### 请求示例\n\n```bash\n# 获取记忆的所有关联\ncurl -X GET \"http://localhost:8443/api/graph/related/abc12345\"\n\n# 执行推理查询\ncurl -X POST \"http://localhost:8443/api/graph/infer\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"source_hash\": \"abc123\", \"depth\": 2}'\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py]()\n\n## 关联推断系统\n\n### 批量推断流程\n\n关联推断模块 (`relationship_inference.py`) 提供批量关联优化功能：\n\n```mermaid\ngraph TD\n A[加载现有关联] --> B[分析关联质量]\n B --> C{质量评估}\n C -->|低| D[标记待优化]\n C -->|高| E[保留]\n D --> F[执行推断]\n F --> G[验证推断结果]\n G --> H[更新关联数据]\n H --> I[生成报告]\n```\n\n### 优化策略\n\n| 策略 | 触发条件 | 优化动作 |\n|------|----------|----------|\n| 合并重复 | 多个相同关系 | 去重合并 |\n| 提升置信度 | 多次验证 | 增加置信度 |\n| 清理孤立 | 无关联记忆 | 移除或标记 |\n| 类型标准化 | 非标准类型 | 映射到标准类型 |\n\n### 执行命令\n\n```bash\n# 预览优化效果（不执行）\npython scripts/maintenance/update_graph_relationship_types.py --dry-run\n\n# 执行优化\npython scripts/maintenance/update_graph_relationship_types.py\n```\n\n资料来源：[src/mcp_memory_service/consolidation/relationship_inference.py]()\n\n## 关联管理\n\n### 关联生命周期\n\n```mermaid\ngraph LR\n A[创建] --> B[验证]\n B --> C[索引]\n C --> D[使用]\n D --> E{评估}\n E -->|需要更新| F[更新]\n E -->|不再有效| G[归档/删除]\n F --> D\n```\n\n### 关联类型管理\n\n关联类型标准化通过 `associations.py` 模块实现：\n\n```json\n{\n \"关系映射\": {\n \"bug-fix\": \"fix\",\n \"technical-solution\": \"solution\",\n \"implementation\": \"implement\"\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/consolidation/associations.py]()\n\n## 与向量存储的集成\n\n知识图谱与向量存储紧密集成，形成混合检索系统：\n\n### 双索引架构\n\n```mermaid\ngraph TB\n subgraph \"输入层\"\n A[记忆内容]\n end\n \n subgraph \"处理\"\n A --> B[生成向量]\n A --> C[提取实体]\n C --> D[识别关系]\n end\n \n subgraph \"存储\"\n B --> E[(向量索引)]\n D --> F[(图索引)]\n end\n \n subgraph \"查询\"\n G[语义查询] --> E\n H[关系查询] --> F\n end\n```\n\n### 协同检索\n\n| 场景 | 向量检索 | 图检索 | 合并策略 |\n|------|----------|--------|----------|\n| 相似内容 | ✓ 主导 | 补充 | 加权合并 |\n| 因果追溯 | ✓ 补充 | 主导 | 图优先 |\n| 推荐发现 | ✓ 主导 | 主导 | 交叉验证 |\n\n## 性能特性\n\n### 性能指标\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 单次关联写入 | ~5ms | 含索引更新 |\n| 关联查询 (一级) | ~10ms | 直接邻居 |\n| 路径查询 (深度2) | ~50ms | 含推理 |\n| 批量推断 (1000条) | ~5秒 | 完整优化 |\n\n### 扩展性\n\n- 支持 **sqlite-vec** 作为本地向量存储后端\n- 支持 **Cloudflare D1 + Vectorize** 作为云端后端\n- 支持 **混合模式** 部署\n\n## 维护工具\n\n### 可用脚本\n\n| 脚本 | 功能 | 位置 |\n|------|------|------|\n| `update_graph_relationship_types.py` | 推断和优化关联类型 | `scripts/maintenance/` |\n| `repair_sqlite_vec_embeddings.py` | 修复嵌入问题 | `scripts/maintenance/` |\n| `repair_zero_embeddings.py` | 修复零嵌入 | `scripts/maintenance/` |\n\n### 维护建议\n\n1. **定期运行推断优化**：每月执行一次关联质量检查\n2. **监控孤立节点**：清理无关联的记忆以保持图质量\n3. **验证索引一致性**：确保向量索引与图索引同步\n\n## 最佳实践\n\n### 记忆组织\n\n1. **使用标准类型**：选择预定义的关系类型而非自定义\n2. **保持原子性**：每条记忆聚焦单一主题，便于关系建立\n3. **添加上下文标签**：使用标签辅助关系推断\n\n### 查询优化\n\n1. **指定深度限制**：避免过深的图遍历\n2. **使用类型过滤**：按关系类型筛选以提高性能\n3. **缓存常用查询**：对于频繁访问的图结构使用缓存\n\n## 总结\n\nMCP Memory Service 的知识图谱模块通过实体识别、关系推理和图存储的协同工作，为系统提供了强大的语义关联能力。它不仅支持传统的向量相似度检索，还能通过图结构发现更深层次的关联关系，为 AI 助手提供更丰富的上下文理解能力。\n\n通过持续优化的关联推断系统和维护工具，系统能够自动保持图谱的质量和相关性，确保长期使用的有效性。\n\n---\n\n\n\n## 记忆整合系统\n\n### 相关页面\n\n相关主题：[知识图谱](#knowledge-graph), [质量评分系统](#quality-scoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/consolidation/consolidator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n- [src/mcp_memory_service/consolidation/scheduler.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/scheduler.py)\n- [src/mcp_memory_service/consolidation/compression.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/compression.py)\n- [src/mcp_memory_service/consolidation/decay.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/decay.py)\n- [src/mcp_memory_service/consolidation/forgetting.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/forgetting.py)\n- [src/mcp_memory_service/consolidation/health.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/health.py)\n- [src/mcp_memory_service/consolidation/insights.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/insights.py)\n- [src/mcp_memory_service/consolidation/clustering.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/clustering.py)\n- [src/mcp_memory_service/server/handlers/consolidation.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/consolidation.py)\n- [docs/guides/memory-consolidation-guide.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/memory-consolidation-guide.md)\n \n\n# 记忆整合系统\n\n## 概述\n\n记忆整合系统（Memory Consolidation System）是 MCP Memory Service 的核心组件之一，负责对存储的语义记忆进行周期性优化、压缩和遗忘处理。该系统通过自动化调度机制，在不影响服务正常运行的情况下，对数据库中的记忆进行智能管理和维护。\n\n记忆整合系统的设计目标包括：\n\n- **记忆压缩**：将相似或冗余的记忆内容进行合并，减少存储空间\n- **记忆衰减**：根据时间因素和访问频率调整记忆的重要性评分\n- **选择性遗忘**：自动移除不再需要的低价值记忆，保持数据库健康\n- **洞察生成**：从记忆数据中提取有价值的分析信息\n- **集群管理**：对记忆进行语义聚类，优化检索效率\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:1-50]()\n\n## 系统架构\n\n记忆整合系统采用模块化设计，各子模块协同工作完成不同的整合任务。\n\n```mermaid\ngraph TD\n subgraph 记忆整合系统\n A[触发器/调度器] --> B[整合器]\n B --> C[压缩模块]\n B --> D[衰减模块]\n B --> E[遗忘模块]\n B --> F[健康检查模块]\n B --> G[洞察生成模块]\n B --> H[聚类模块]\n end\n \n I[SQLite数据库] <--> B\n J[MCP服务器] --> A\n K[HTTP API] --> A\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 整合器 | `consolidation/consolidator.py` | 协调各模块执行，负责整体流程控制 |\n| 调度器 | `consolidation/scheduler.py` | 管理定时任务，支持日/周/月三种时间粒度 |\n| 压缩模块 | `consolidation/compression.py` | 识别相似记忆并进行合并 |\n| 衰减模块 | `consolidation/decay.py` | 实现记忆重要性随时间的衰减计算 |\n| 遗忘模块 | `consolidation/forgetting.py` | 根据策略删除低价值记忆 |\n| 健康检查 | `consolidation/health.py` | 监控数据库状态和整合效果 |\n| 洞察生成 | `consolidation/insights.py` | 提取记忆中的统计和分析信息 |\n| 聚类模块 | `consolidation/clustering.py` | 对记忆进行语义聚类优化 |\n\n资料来源：[src/mcp_memory_service/consolidation/scheduler.py:1-30]()\n\n## 时间视野策略\n\n系统支持三种不同时间粒度的整合策略，适用于不同类型的记忆管理需求。\n\n| 时间视野 | 适用场景 | 典型保留周期 |\n|----------|----------|--------------|\n| 日整合 (daily) | 近期工作记忆、临时笔记 | 最近 7-30 天 |\n| 周整合 (weekly) | 项目进度、会议决策 | 最近 1-6 个月 |\n| 月整合 (monthly) | 长期知识沉淀、架构决策 | 6 个月以上 |\n\n每种时间视野对应不同的压缩率和遗忘阈值，确保短期记忆保留完整性的同时，长期记忆不会被无限积累。\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:50-100]()\n\n## 整合执行流程\n\n```mermaid\ngraph LR\n A[开始整合] --> B{健康检查}\n B -->|通过| C[执行压缩]\n B -->|失败| Z[终止整合]\n C --> D[执行衰减]\n D --> E[执行遗忘]\n E --> F[更新聚类]\n F --> G[生成洞察]\n G --> H[记录统计]\n H --> I[完成整合]\n```\n\n### 各阶段详细说明\n\n#### 1. 健康检查阶段\n\n在执行任何修改操作前，系统首先进行数据库健康状态检查，包括：\n\n- 数据库连接可用性验证\n- 磁盘空间检查（需要至少 2 倍数据库大小的空间）\n- 现有任务冲突检测\n- 数据库锁状态确认\n\n资料来源：[src/mcp_memory_service/consolidation/health.py:1-50]()\n\n#### 2. 压缩阶段\n\n压缩模块负责识别和合并语义相似的记忆内容：\n\n- 计算记忆间的相似度评分\n- 对超过相似度阈值的记忆进行合并\n- 保留最早的创建时间戳\n- 合并标签集和元数据\n\n资料来源：[src/mcp_memory_service/consolidation/compression.py:1-60]()\n\n#### 3. 衰减阶段\n\n衰减模块根据时间因素调整记忆的重要性评分：\n\n- 基础衰减率按时间视野配置\n- 访问频率作为衰减调整因子\n- 重要性评分影响后续遗忘决策\n\n```python\n# 衰减计算公式示例\n衰减因子 = base_decay_rate × (1 - access_frequency_weight)\n新评分 = 原始评分 × 衰减因子\n```\n\n资料来源：[src/mcp_memory_service/consolidation/decay.py:1-45]()\n\n#### 4. 遗忘阶段\n\n遗忘模块根据评分阈值决定应删除的记忆：\n\n- 低于遗忘阈值的记忆被标记为待删除\n- 保护期内的记忆不会被删除\n- 系统记忆和重要标记的记忆受特殊保护\n\n资料来源：[src/mcp_memory_service/consolidation/forgetting.py:1-50]()\n\n#### 5. 聚类更新阶段\n\n聚类模块对现有记忆进行语义分组：\n\n- 基于嵌入向量的相似性计算\n- 更新记忆的聚类标签\n- 优化向量检索效率\n\n资料来源：[src/mcp_memory_service/consolidation/clustering.py:1-40]()\n\n#### 6. 洞察生成阶段\n\n洞察模块从整合过程中提取分析数据：\n\n- 整合统计（处理记忆数、压缩数、遗忘数）\n- 记忆类型分布分析\n- 时间趋势报告\n- 健康状态摘要\n\n资料来源：[src/mcp_memory_service/consolidation/insights.py:1-50]()\n\n## API 接口\n\n系统提供 HTTP API 接口用于触发和管理整合操作。\n\n### 触发整合\n\n```\nPOST /api/consolidate\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| time_horizon | string | 否 | 时间视野：`daily`、`weekly`、`monthly`，默认 `weekly` |\n\n**响应示例：**\n\n```json\n{\n \"status\": \"completed\",\n \"time_horizon\": \"weekly\",\n \"processed\": 2418,\n \"compressed\": 156,\n \"forgotten\": 43,\n \"duration_seconds\": 18.5\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/consolidation.py:1-80]()\n\n### 查询调度器状态\n\n```\nGET /api/consolidate/status\n```\n\n**响应示例：**\n\n```json\n{\n \"running\": true,\n \"next_daily\": \"2025-01-08T03:00:00Z\",\n \"next_weekly\": \"2025-01-12T03:00:00Z\",\n \"next_monthly\": \"2025-02-01T03:00:00Z\",\n \"jobs_executed\": 156,\n \"jobs_failed\": 2\n}\n```\n\n资料来源：[src/mcp_memory_service/api/operations.py:100-150]()\n\n## Python API\n\n除 HTTP API 外，系统还提供 Python API 供直接调用。\n\n### 异步接口\n\n```python\nfrom mcp_memory_service.api import consolidate\n\n# 执行周整合\nresult = await consolidate('weekly')\nprint(f\"压缩: {result.compressed}, 遗忘: {result.forgotten}\")\n```\n\n### 同步接口\n\n```python\nfrom mcp_memory_service.api import consolidate\n\n# 同步调用\nresult = consolidate('monthly')\nprint(f\"状态: {result.status}\")\n```\n\n**性能指标：**\n\n- 典型执行时长：10-30 秒（取决于记忆数量）\n- 线性扩展：约 10ms/记忆\n- 后台执行，非阻塞操作\n\n资料来源：[src/mcp_memory_service/api/__init__.py:1-60]()\n\n## 调度配置\n\n### 调度器初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| enabled | bool | true | 是否启用自动调度 |\n| daily_hour | int | 3 | 日整合执行小时（凌晨） |\n| weekly_day | int | 6 | 周整合执行日期（周六） |\n| monthly_day | int | 1 | 月整合执行日期（每月1日） |\n| timezone | string | \"UTC\" | 执行时区 |\n\n### 自定义调度\n\n调度器使用 APScheduler 作为底层调度引擎，支持：\n\n- Cron 表达式配置\n- 间隔执行模式\n- 一次性任务\n\n资料来源：[src/mcp_memory_service/consolidation/scheduler.py:60-120]()\n\n## 配置示例\n\n### 基本配置\n\n```json\n{\n \"consolidation\": {\n \"enabled\": true,\n \"time_horizon\": \"weekly\",\n \"compression_threshold\": 0.85,\n \"forgetting_threshold\": 0.3,\n \"decay_rate\": 0.95\n }\n}\n```\n\n### 激进配置（更多遗忘）\n\n```json\n{\n \"consolidation\": {\n \"enabled\": true,\n \"time_horizon\": \"monthly\",\n \"compression_threshold\": 0.75,\n \"forgetting_threshold\": 0.5,\n \"decay_rate\": 0.9\n }\n}\n```\n\n### 保守配置（更多保留）\n\n```json\n{\n \"consolidation\": {\n \"enabled\": true,\n \"time_horizon\": \"daily\",\n \"compression_threshold\": 0.95,\n \"forgetting_threshold\": 0.1,\n \"decay_rate\": 0.99\n }\n}\n```\n\n资料来源：[docs/guides/memory-consolidation-guide.md:1-80]()\n\n## 维护脚本\n\n系统提供命令行维护脚本用于手动执行整合操作。\n\n### 使用方法\n\n```bash\n# 预览整合效果（安全，不实际执行）\npython scripts/maintenance/consolidate_memories.py --dry-run\n\n# 执行周整合\npython scripts/maintenance/consolidate_memories.py\n\n# 执行月整合并指定时间视野\npython scripts/maintenance/consolidate_memories.py --time-horizon monthly\n```\n\n### 安全特性\n\n- **自动备份**：执行前自动创建带时间戳的数据库备份\n- **干运行模式**：`--dry-run` 模式仅预览不修改\n- **事务安全**：原子操作，错误时自动回滚\n- **并发检测**：检测数据库锁防止并发访问冲突\n- **磁盘空间检查**：验证是否有足够空间进行操作\n- **备份验证**：操作后验证备份文件完整性\n\n### 恢复流程\n\n如果整合操作出现问题，可从自动备份恢复：\n\n```bash\n# 停止服务\nsystemctl --user stop mcp-memory-http.service\n\n# 断开所有 MCP 客户端连接\n\n# 从备份恢复\ncp ~/.local/share/mcp-memory/sqlite_vec.db.backup-TIMESTAMP \\\n ~/.local/share/mcp-memory/sqlite_vec.db\n\n# 验证恢复\nsqlite3 ~/.local/share/mcp-memory/sqlite_vec.db \\\n \"SELECT COUNT(*), COUNT(DISTINCT memory_type) FROM memories;\"\n```\n\n资料来源：[scripts/maintenance/README.md:1-60]()\n\n## 最佳实践\n\n### 执行时机建议\n\n1. **服务空闲时执行**：建议在凌晨或低峰时段运行\n2. **停止 HTTP 服务**：执行前停止 HTTP 服务器避免并发冲突\n3. **断开 MCP 客户端**：确保没有活跃的 Claude Code 会话\n4. **监控磁盘空间**：确保有足够的存储空间进行备份和操作\n\n### 维护周期\n\n| 检查类型 | 建议频率 | 工具 |\n|----------|----------|------|\n| 干运行检查 | 每月 | `--dry-run` |\n| 执行整合 | 按配置 | 调度器或手动 |\n| 类型归一化 | 按需 | `consolidate_memory_types.py` |\n| 性能优化 | 每季度 | `cleanup_memories.py` |\n\n### 监控指标\n\n建议监控以下整合指标：\n\n- `processed`：处理的记忆总数\n- `compressed`：被压缩的记忆数\n- `forgotten`：被遗忘的记忆数\n- `duration_seconds`：执行耗时\n- `jobs_failed`：失败的任务数\n\n资料来源：[src/mcp_memory_service/consolidation/insights.py:50-100]()\n\n## 相关模块文档\n\n- [压缩模块详解](./consolidation-compression.md)\n- [遗忘算法详解](./consolidation-forgetting.md)\n- [调度器配置](./consolidation-scheduler.md)\n- [API 参考](../api/reference.md)\n\n---\n\n\n\n## 质量评分系统\n\n### 相关页面\n\n相关主题：[记忆整合系统](#consolidation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/quality/scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/scorer.py)\n- [src/mcp_memory_service/quality/onnx_ranker.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/onnx_ranker.py)\n- [src/mcp_memory_service/quality/ai_evaluator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/ai_evaluator.py)\n- [src/mcp_memory_service/quality/async_scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/async_scorer.py)\n- [src/mcp_memory_service/quality/config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/config.py)\n- [src/mcp_memory_service/quality/implicit_signals.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/implicit_signals.py)\n- [src/mcp_memory_service/embeddings/onnx_embeddings.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/embeddings/onnx_embeddings.py)\n- [docs/guides/memory-quality-guide.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/memory-quality-guide.md)\n- [docs/features/association-quality-boost.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/features/association-quality-boost.md)\n \n\n# 质量评分系统\n\n## 概述\n\n质量评分系统是 MCP Memory Service 的核心组件之一，负责对存储的语义记忆进行多维度质量评估。该系统通过静态评分、机器学习排序和隐式信号分析等多种机制，综合判断记忆内容的价值和质量等级，从而优化搜索结果的相关性排序。\n\n在 Claude Code 的会话管理中，增强的记忆过滤功能会自动移除\"implementation...\"等通用摘要内容，确保只保留高价值的洞察信息。系统支持多种配置选项，包括详细程度控制和质量评分权重调整。\n\n质量评分系统的主要目标是提高记忆检索的准确性，确保最相关和最有价值的记忆能够优先呈现给用户。系统采用分层评分架构，结合 ONNX 运行时加速和异步处理能力，在保证性能的同时提供精确的质量评估。\n\n## 系统架构\n\n质量评分系统采用模块化设计，各组件之间通过清晰的接口进行通信。核心架构包含评分引擎、ONNX 排序器、AI 评估器、异步评分器和隐式信号分析器等多个模块。\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[记忆存储] --> B[质量评分系统]\n B --> C[评分引擎 scorer.py]\n B --> D[ONNX 排序器 onnx_ranker.py]\n B --> E[AI 评估器 ai_evaluator.py]\n B --> F[异步评分器 async_scorer.py]\n B --> G[隐式信号 implicit_signals.py]\n C --> H[配置模块 config.py]\n D --> I[ONNX 运行时]\n E --> J[LLM API]\n G --> K[用户行为数据]\n H --> L[评分策略配置]\n F --> M[异步任务队列]\n M --> N[结果缓存]\n N --> O[搜索结果排序]\n```\n\n### 核心模块说明\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 评分引擎 | `quality/scorer.py` | 核心评分逻辑，整合多维度评分因子 |\n| ONNX 排序器 | `quality/onnx_ranker.py` | 使用 ONNX 加速的机器学习排序模型 |\n| AI 评估器 | `quality/ai_evaluator.py` | 基于大语言模型的质量评估 |\n| 异步评分器 | `quality/async_scorer.py` | 后台异步执行批量评分任务 |\n| 配置模块 | `quality/config.py` | 评分策略和参数配置管理 |\n| 隐式信号 | `quality/implicit_signals.py` | 从用户行为中提取质量信号 |\n| ONNX 嵌入 | `embeddings/onnx_embeddings.py` | 语义嵌入向量生成 |\n\n## 评分策略配置\n\n质量评分系统通过 `config.py` 模块提供灵活的配置选项。配置参数控制评分算法的行为、权重分配和性能调优。\n\n### 配置参数表\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `contentQuality` | float | 0.3 | 内容质量评估权重 |\n| `relevanceWeight` | float | 0.4 | 语义相关性权重 |\n| `recencyWeight` | float | 0.2 | 时间衰减因子权重 |\n| `usageWeight` | float | 0.1 | 使用频率权重 |\n| `minQualityThreshold` | float | 0.5 | 最低质量阈值 |\n\n配置示例：\n\n```python\nfrom mcp_memory_service.quality.config import QualityConfig\n\nconfig = QualityConfig(\n contentQuality=0.35,\n relevanceWeight=0.35,\n recencyWeight=0.15,\n usageWeight=0.15,\n minQualityThreshold=0.6\n)\n```\n\n## ONNX 加速排序\n\n系统使用 ONNX Runtime 加速机器学习排序模型的推理过程。相比纯 Python 实现，ONNX 排序器能够显著提升批量评分的吞吐量。\n\n### ONNX 排序器工作流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Scorer as 评分引擎\n participant ONNX as ONNX排序器\n participant Cache as 结果缓存\n \n Client->>Scorer: 提交评分请求\n Scorer->>ONNX: 请求批量排序\n ONNX->>ONNX: 模型推理\n ONNX-->>Scorer: 排序分数\n Scorer->>Cache: 缓存结果\n Scorer-->>Client: 返回评分结果\n```\n\nONNX 嵌入模块负责将文本内容转换为高维向量表示，用于后续的语义相似度计算和质量评估。嵌入向量结合了语义信息和上下文关系，为评分引擎提供丰富的特征输入。\n\n## 异步评分机制\n\n对于批量评分任务，系统采用异步处理架构以避免阻塞主线程。异步评分器支持任务队列管理、并发控制和结果回调。\n\n### 异步评分特性\n\n异步评分器提供以下核心功能：\n\n1. **任务批量处理**：将多个评分请求合并为单一批处理任务，减少模型调用开销\n2. **优先级队列**：支持按优先级排序的评分任务调度\n3. **结果回调**：评分完成后自动触发预设的回调函数\n4. **错误重试**：网络或服务异常时自动重试失败任务\n\n```python\nfrom mcp_memory_service.quality.async_scorer import AsyncScorer\n\nasync_scorer = AsyncScorer(max_concurrent=4)\n\n# 提交异步评分任务\ntask_id = await async_scorer.submit_batch(\n memory_ids=[\"hash1\", \"hash2\", \"hash3\"],\n callback=on_score_complete\n)\n```\n\n## 隐式信号分析\n\n隐式信号分析器从用户行为数据中提取质量相关的反馈信号，无需显式评分即可评估记忆的价值。\n\n### 信号类型表\n\n| 信号类型 | 数据来源 | 权重 | 说明 |\n|----------|----------|------|------|\n| 检索频率 | 搜索日志 | 0.25 | 记忆被检索的次数 |\n| 引用次数 | 对话记录 | 0.30 | 记忆中内容被引用的次数 |\n| 停留时长 | 会话数据 | 0.20 | 用户查看记忆的平均时长 |\n| 修改频率 | 版本历史 | 0.15 | 记忆被修改的频率 |\n| 关联强度 | 链接关系 | 0.10 | 与其他高价值记忆的关联数 |\n\n隐式信号分析器持续监控用户与记忆的交互模式，通过机器学习算法识别高价值内容。系统会根据累积的信号数据动态调整评分模型的参数。\n\n## AI 评估器\n\nAI 评估器利用大语言模型的能力对记忆内容进行深度质量分析。该模块能够理解语义上下文，评估内容的完整性、清晰度和实用价值。\n\n### 评估维度\n\n| 维度 | 描述 | 分数范围 |\n|------|------|----------|\n| 内容完整性 | 记忆是否包含足够的上下文信息 | 0-1 |\n| 语义清晰度 | 表述是否清晰、无歧义 | 0-1 |\n| 实用价值 | 对未来参考的潜在价值 | 0-1 |\n| 时效性 | 内容是否需要更新 | 0-1 |\n| 唯一性 | 与现有记忆的重复程度 | 0-1 |\n\nAI 评估器支持流式输出模式，能够在评估过程中逐步返回中间结果，便于实时显示评估进度。\n\n## 关联质量提升\n\n质量评分系统与关联记忆机制紧密集成。通过分析记忆之间的语义关联，系统能够识别和提升高价值内容的显示优先级。\n\n关联质量提升特性包括：\n\n- **语义聚类**：将相关内容自动分组\n- **关联强度评分**：计算记忆间的关联紧密度\n- **质量传播**：高评分记忆的关联项获得适度加分\n- **去重推荐**：避免重复或高度相似的内容重复出现\n\n该机制确保搜索结果不仅在语义上相关，而且在质量和独特性上也能满足用户需求。系统在处理关联查询时会综合考虑直接匹配度和关联记忆的质量表现。\n\n## 集成指南\n\n### 基础集成\n\n在应用中使用质量评分系统：\n\n```python\nfrom mcp_memory_service.quality.scorer import QualityScorer\nfrom mcp_memory_service.quality.config import QualityConfig\n\n# 初始化配置和评分器\nconfig = QualityConfig()\nscorer = QualityScorer(config)\n\n# 对单条记忆评分\nmemory_id = \"abc12345\"\nscore = await scorer.score_memory(memory_id)\nprint(f\"记忆质量分数: {score.overall:.2f}\")\n```\n\n### 批量评分集成\n\n```python\nfrom mcp_memory_service.quality.async_scorer import AsyncScorer\n\nasync_scorer = AsyncScorer(max_concurrent=10)\n\n# 定义回调函数\ndef on_complete(task_id, results):\n print(f\"任务 {task_id} 完成，共评分 {len(results)} 条记忆\")\n\n# 提交批量任务\nresults = await async_scorer.submit_batch(\n memory_ids=[...], # 记忆 ID 列表\n callback=on_complete\n)\n```\n\n## 配置示例\n\n### 详细模式配置\n\n```python\nconfig = QualityConfig(\n contentQuality=0.4,\n relevanceWeight=0.3,\n recencyWeight=0.15,\n usageWeight=0.15,\n minQualityThreshold=0.5,\n enable_ai_evaluator=True,\n enable_implicit_signals=True,\n async_batch_size=50\n)\n```\n\n### 简洁模式配置\n\n```python\nconfig = QualityConfig(\n contentQuality=0.2,\n relevanceWeight=0.5,\n recencyWeight=0.2,\n usageWeight=0.1,\n minQualityThreshold=0.6,\n enable_ai_evaluator=False,\n enable_implicit_signals=True,\n async_batch_size=20\n)\n```\n\n## 性能指标\n\n根据实际部署测试，系统在标准配置下的性能表现如下：\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 单条评分延迟 | <50ms | 同步评分响应时间 |\n| 批量评分吞吐 | ~100条/秒 | 异步模式下的处理速度 |\n| ONNX 推理延迟 | <10ms | 单次模型推理时间 |\n| 内存占用 | <100MB | 运行时内存峰值 |\n\n性能数据来源于项目的基准测试套件，实际表现会因硬件配置和数据规模而有所不同。\n\n## 相关文档\n\n- [记忆质量指南](docs/guides/memory-quality-guide.md) - 详细的使用指南和最佳实践\n- [关联质量提升](docs/features/association-quality-boost.md) - 关联机制的技术说明\n- [API 参考](../api/reference.md) - 评分系统的 API 接口文档\n\n---\n\n\n\n## MCP 协议集成\n\n### 相关页面\n\n相关主题：[代理框架集成](#agent-frameworks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)\n- [src/mcp_memory_service/server/handlers/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/__init__.py)\n- [src/mcp_memory_service/server/handlers/memory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n- [src/mcp_memory_service/server/handlers/utility.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/utility.py)\n- [src/mcp_memory_service/discovery/mdns_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/discovery/mdns_service.py)\n- [docs/remote-mcp-setup.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/remote-mcp-setup.md)\n- [docs/guides/mcp-enhancements.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/mcp-enhancements.md)\n \n\n# MCP 协议集成\n\nMCP Memory Service 是一个基于 Model Context Protocol (MCP) 的语义记忆服务，为 Claude Code 等 MCP 客户端提供记忆存储、检索和语义搜索能力。本页面详细介绍 MCP 协议集成的架构设计、核心组件、API 接口以及配置方法。\n\n## MCP 协议概述\n\nModel Context Protocol (MCP) 是一种标准化协议，用于在 AI 助手与外部数据源、工具之间建立通信桥梁。MCP Memory Service 通过该协议暴露记忆管理功能，使 AI 助手能够：\n\n- 持久化存储对话上下文和重要信息\n- 基于语义相似性检索记忆\n- 通过标签和类型组织记忆\n- 实时获取记忆更新事件\n\n资料来源：[src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端层\"\n Claude[Claude Code]\n OpenCode[OpenCode]\n Custom[自定义 MCP 客户端]\n end\n \n subgraph \"MCP Memory Service 核心\"\n MCPServer[MCP Server]\n Handlers[Handler 路由层]\n MemoryService[Memory Service]\n EmbeddingEngine[Embedding 引擎]\n end\n \n subgraph \"存储层\"\n SQLiteVec[(SQLite Vec
向量存储)]\n GraphDB[(图数据库
关系存储)]\n end\n \n subgraph \"发现服务\"\n MDNS[mDNS Service
服务发现]\n end\n \n Claude --> MCPServer\n OpenCode --> MCPServer\n Custom --> MCPServer\n \n MCPServer --> Handlers\n Handlers --> MemoryService\n MemoryService --> EmbeddingEngine\n MemoryService --> SQLiteVec\n MemoryService --> GraphDB\n MCPServer --> MDNS\n```\n\n### 核心组件职责\n\n| 组件 | 文件路径 | 主要职责 |\n|------|----------|----------|\n| MCP Server | `mcp_server.py` | 协议握手、请求路由、响应格式化 |\n| Memory Handler | `handlers/memory.py` | 处理记忆 CRUD 操作 |\n| Utility Handler | `handlers/utility.py` | 处理健康检查、统计等辅助功能 |\n| Memory Service | `services/memory_service.py` | 业务逻辑编排、数据验证 |\n| mDNS Service | `discovery/mdns_service.py` | 局域网服务自动发现 |\n\n资料来源：[src/mcp_memory_service/server/handlers/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/__init__.py)\n\n## Handler 路由层设计\n\n### 路由分发流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP Server\n participant Router as Handler Router\n participant Handler as 具体 Handler\n \n Client->>Server: MCP JSON-RPC 请求\n Server->>Router: 解析 method 名称\n Router->>Handler: 路由到对应 Handler\n Handler->>Handler: 执行业务逻辑\n Handler->>Router: 返回处理结果\n Router->>Server: 封装响应\n Server->>Client: 返回 JSON-RPC 响应\n```\n\n### Handler 模块结构\n\n```python\n# handlers/__init__.py 导出结构\nfrom .memory import MemoryHandler # 记忆操作处理器\nfrom .utility import UtilityHandler # 工具类处理器\n```\n\n每个 Handler 负责特定的 MCP 工具调用，遵循统一的接口规范：\n\n| 方法 | 说明 |\n|------|------|\n| `initialize()` | 初始化处理器，验证配置 |\n| `handle_request()` | 处理传入的 MCP 请求 |\n| `get_schema()` | 返回工具的 JSON Schema 定义 |\n\n资料来源：[src/mcp_memory_service/server/handlers/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/__init__.py)\n\n## Memory Handler 详解\n\nMemory Handler 是 MCP 协议集成的核心，负责处理所有与记忆相关的操作。\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### 支持的工具调用\n\n| 工具名称 | 方法 | 功能描述 |\n|----------|------|----------|\n| `store_memory` | 存储记忆 | 创建新记忆，自动生成嵌入向量 |\n| `retrieve_memory` | 检索记忆 | 通过哈希值获取单条记忆 |\n| `search_memories` | 语义搜索 | 基于向量相似度搜索相关记忆 |\n| `list_memories` | 列表查询 | 分页获取记忆列表 |\n| `delete_memory` | 删除记忆 | 移除指定记忆及其关联数据 |\n| `update_memory` | 更新记忆 | 修改记忆内容和元数据 |\n\n### 请求参数模型\n\n```mermaid\ngraph LR\n A[store_memory] --> B{content}\n A --> C{tags?}\n A --> D{memory_type?}\n A --> E{metadata?}\n \n F[search_memories] --> G{query}\n F --> H{limit?}\n F --> I{similarity_threshold?}\n F --> J{tags_filter?}\n```\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `content` | string | 是 | 记忆内容文本 |\n| `tags` | string[] | 否 | 标签数组 |\n| `memory_type` | string | 否 | 记忆类型（note/reference/session 等） |\n| `metadata` | object | 否 | 自定义元数据 |\n| `query` | string | 是（搜索时） | 搜索查询文本 |\n| `limit` | integer | 否 | 返回结果数量限制 |\n| `similarity_threshold` | float | 否 | 相似度阈值（0-1） |\n\n### 响应格式\n\n```json\n{\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Memory content here...\"\n }\n ],\n \"isError\": false\n}\n```\n\n错误响应示例：\n\n```json\n{\n \"content\": [\n {\n \"type\": \"text\", \n \"text\": \"Error: Memory not found\"\n }\n ],\n \"isError\": true\n}\n```\n\n## Utility Handler 详解\n\nUtility Handler 提供系统级的辅助功能接口。\n\n资料来源：[src/mcp_memory_service/server/handlers/utility.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/utility.py)\n\n### 健康检查接口\n\n| 工具名称 | 功能 | 返回信息 |\n|----------|------|----------|\n| `health` | 服务健康状态 | 后端类型、记忆总数、运行时间 |\n| `list_tools` | 列出可用工具 | 所有注册的 MCP 工具清单 |\n| `get_capabilities` | 获取能力列表 | 服务器支持的协议特性 |\n\n### 健康检查响应示例\n\n```json\n{\n \"status\": \"healthy\",\n \"backend\": \"sqlite_vec\",\n \"memory_count\": 1247,\n \"version\": \"9.3.0\",\n \"uptime_seconds\": 3600\n}\n```\n\n## 服务发现机制\n\nMCP Memory Service 支持通过 mDNS (Multicast DNS) 进行局域网服务自动发现，使客户端能够无需手动配置即可找到服务。\n\n资料来源：[src/mcp_memory_service/discovery/mdns_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/discovery/mdns_service.py)\n\n### 服务公告流程\n\n```mermaid\ngraph LR\n A[服务启动] --> B[注册 mDNS]\n B --> C[公告 _mcp-memory._tcp]\n C --> D[客户端发现服务]\n D --> E[获取 host:port]\n E --> F[建立 MCP 连接]\n```\n\n### 服务配置参数\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|----------|--------|------|\n| 服务名称 | `MDNS_SERVICE_NAME` | `mcp-memory` | mDNS 服务标识 |\n| 服务类型 | - | `_mcp-memory._tcp` | mDNS 服务协议类型 |\n| 公告端口 | `PORT` | `8443` | MCP 服务监听端口 |\n| API Key | `MCP_API_KEY` | 无 | 认证密钥 |\n\n## MCP 工具调用示例\n\n### Python SDK 使用方式\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 健康检查（约 5 tokens）\n>>> info = health()\n>>> print(f\"Backend: {info.backend}, Count: {info.count}\")\nBackend: sqlite_vec, Count: 1247\n\n# 存储记忆（约 15 tokens）\n>>> hash = store(\"New memory content\", tags=[\"note\", \"important\"])\n>>> print(f\"Stored: {hash}\")\nStored: abc12345\n\n# 语义搜索（约 20 tokens）\n>>> results = search(\"architecture decisions\", limit=5)\n>>> for m in results.memories:\n... print(f\"{m.hash}: {m.preview[:50]}...\")\nabc12345: Implemented OAuth 2.1 authentication for...\ndef67890: Refactored storage backend to support...\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)\n\n### Claude Code 命令行调用\n\n| 命令 | 功能 | 示例 |\n|------|------|------|\n| `/memory-recall` | 基于时间检索 | `/memory-recall \"last week discussions\"` |\n| `/memory-search` | 标签/内容搜索 | `/memory-search --tags \"architecture\"` |\n| `/memory-context` | 上下文捕获 | `/memory-context --summary \"planning\"` |\n| `/memory-health` | 健康检查 | `/memory-health --detailed` |\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n## 远程 MCP 配置\n\n对于需要远程连接 MCP Memory Service 的场景，需要进行专门的配置。\n\n资料来源：[docs/remote-mcp-setup.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/remote-mcp-setup.md)\n\n### 远程配置架构\n\n```mermaid\ngraph LR\n subgraph \"远程服务器\"\n Server[MCP Memory Service]\n DB[(SQLite Vec)]\n Server --> DB\n end\n \n subgraph \"本地客户端\"\n Claude[Claude Code]\n Config[MCP Config]\n end\n \n Config -->|HTTPS + API Key| Server\n```\n\n### 配置步骤\n\n1. **服务端配置**：确保服务监听在可访问的网络接口\n2. **API Key 设置**：配置 `MCP_API_KEY` 环境变量\n3. **客户端配置**：在 `~/.claude/settings.json` 中添加远程服务器信息\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"],\n \"url\": \"https://your-server:8443/mcp\"\n }\n }\n}\n```\n\n## MCP 增强功能\n\nMCP Memory Service 在标准 MCP 协议基础上实现了多项增强功能。\n\n资料来源：[docs/guides/mcp-enhancements.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/mcp-enhancements.md)\n\n### 功能增强列表\n\n| 增强功能 | 说明 | 启用方式 |\n|----------|------|----------|\n| 实时事件推送 | 支持 Server-Sent Events 实时推送记忆更新 | `/api/events` 端点 |\n| 图关系推理 | 自动推断记忆间的语义关系 | `RelationshipInferenceEngine` |\n| 类型本体优化 | 标准化记忆类型分类体系 | `improve_memory_ontology.py` |\n| 响应大小限制 | 防止上下文窗口溢出 | `MCP_MAX_RESPONSE_CHARS` 环境变量 |\n\n### 响应大小限制配置\n\n```python\n# src/mcp_memory_service/server/utils/response_limiter.py\nimport os\n\n# 默认值：0 = 无限制（向后兼容）\nDEFAULT_MAX_CHARS = int(os.environ.get(\"MCP_MAX_RESPONSE_CHARS\", 0))\n```\n\n配置方式：\n\n```bash\n# 限制单次响应最大 100,000 字符\nexport MCP_MAX_RESPONSE_CHARS=100000\n```\n\n## 性能特性\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Token 成本 | $0.15/1M tokens | 每 10 用户部署约 $16.43/年 |\n| 首次调用延迟 | ~50ms | 包含存储初始化 |\n| 后续调用延迟 | ~5-10ms | 连接复用 |\n| 内存占用 | <10MB | 服务进程开销 |\n| 搜索吞吐量 | ~1000 memories/second | 语义搜索 |\n\n资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)\n\n## 与 Claude Code 的集成\n\nClaude Code 通过 MCP 协议与 Memory Service 深度集成，支持自动化的记忆感知功能。\n\n```mermaid\ngraph TB\n subgraph \"Claude Code 生命周期\"\n Start[Session Start]\n Compact[Compacting]\n End[Session End]\n end\n \n Start --> |自动加载| LoadMem[Load Relevant Memories]\n Compact --> |可选注入| InjectMem[Inject Context]\n End --> |自动保存| SaveMem[Save Session Insights]\n \n LoadMem --> MCPServer[MCP Server]\n MCPServer --> MemService[Memory Service]\n```\n\n### 钩子脚本列表\n\n| 脚本 | 功能 | 版本 |\n|------|------|------|\n| `session-start.js` | 会话启动时加载记忆 | v2.2 |\n| `session-end.js` | 会话结束时保存洞察 | v2.0 |\n| `memory-retrieval.js` | 按需检索记忆 | v1.5 |\n| `permission-request.js` | 权限自动化处理 | v1.0 |\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n## 错误处理与调试\n\n### 常见错误码\n\n| 错误码 | 含义 | 处理建议 |\n|--------|------|----------|\n| `E_NOT_FOUND` | 记忆不存在 | 检查 content_hash 是否正确 |\n| `E_DUPLICATE` | 记忆已存在 | 使用现有记忆或修改内容 |\n| `E_INVALID_TAGS` | 标签格式错误 | 确保标签为字符串数组 |\n| `E_CONNECTION_FAILED` | 连接失败 | 检查服务是否运行、网络是否通 |\n\n### 调试模式启用\n\n```bash\n# CLI 启用调试\nmemory server --debug\n\n# Claude Code 调试钩子\nclaude --debug hooks\n```\n\n## 总结\n\nMCP Memory Service 通过标准化的 MCP 协议，为 AI 助手提供了强大的语义记忆能力。其核心优势包括：\n\n- **标准化接口**：遵循 MCP 协议规范，支持多种 MCP 客户端\n- **语义搜索**：基于向量嵌入的相似度检索\n- **实时事件**：通过 SSE 推送实现即时记忆同步\n- **自动发现**：mDNS 支持简化服务配置\n- **高效性能**：毫秒级响应速度，低资源占用\n\n通过 MCP 协议集成，MCP Memory Service 能够无缝融入 Claude Code 等 AI 开发工具的工作流，为开发者提供持久化的上下文记忆能力。\n\n---\n\n\n\n## 代理框架集成\n\n### 相关页面\n\n相关主题：[MCP 协议集成](#mcp-integration), [快速开始](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/api/client.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/client.py)\n- [src/mcp_memory_service/api/operations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n- [claude-hooks/core/session-end-harvest.js](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/core/session-end-harvest.js)\n- [claude-hooks/core/auto-capture-hook.js](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/core/auto-capture-hook.js)\n- [docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)\n- [docs/agents/langgraph.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/langgraph.md)\n- [docs/agents/crewai.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/crewai.md)\n- [docs/agents/autogen.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/autogen.md)\n \n\n# 代理框架集成\n\n## 概述\n\nMCP Memory Service 通过提供标准化的 API 接口和专门设计的客户端模块，实现与主流 AI 代理框架的无缝集成。这些集成使得代理（Agent）能够利用持久化记忆服务，实现跨会话的上下文感知和长期知识积累。代理框架集成是 MCP Memory Service 的核心能力之一，它将记忆服务从简单的存储层提升为智能代理的外部记忆系统。 资料来源：[docs/guides/AGENTS.md]()\n\n## 集成架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"代理框架层\"\n LG[LangGraph]\n CR[CrewAI]\n AG[AutoGen]\n CUSTOM[自定义代理]\n end\n \n subgraph \"MCP Memory Service API\"\n API[REST API]\n SSE[Server-Sent Events]\n TOOLS[MCP Tools]\n end\n \n subgraph \"客户端层\"\n CLIENT[Python Client]\n HOOKS[Claude Hooks]\n end\n \n subgraph \"存储后端\"\n SQLiteVec[(SQLite-Vec)]\n Cloudflare[(Cloudflare D1)]\n end\n \n LG --> CLIENT\n CR --> CLIENT\n AG --> CLIENT\n CUSTOM --> API\n HOOKS --> API\n CLIENT --> API\n API --> SSE\n API --> TOOLS\n API --> SQLiteVec\n API --> Cloudflare\n```\n\n### 核心组件关系\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| Python Client | 提供高级 API 封装 | `src/mcp_memory_service/api/client.py` |\n| Operations | 定义具体操作方法 | `src/mcp_memory_service/api/operations.py` |\n| Claude Hooks | 会话生命周期记忆管理 | `claude-hooks/core/` |\n| REST API | HTTP 接口暴露 | FastAPI 自动生成 |\n\n## Python 客户端集成\n\n### 客户端初始化\n\nMCP Memory Service 提供了专门的 Python 客户端，用于代理框架集成。客户端支持连接配置和认证管理。\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 搜索记忆 (20 tokens)\nresults = search(\"architecture decisions\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# 存储记忆 (15 tokens)\nhash = store(\"New memory\", tags=[\"note\", \"important\"])\nprint(f\"Stored: {hash}\")\n\n# 健康检查 (5 tokens)\ninfo = health()\nprint(f\"Backend: {info.backend}, Count: {info.count}\")\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n### 核心操作接口\n\n| 方法 | 功能 | 典型延迟 |\n|------|------|----------|\n| `search()` | 语义相似性搜索 | 5-10ms |\n| `store()` | 存储新记忆 | 50ms (首次) / 5-10ms (后续) |\n| `health()` | 服务健康检查 | <1ms |\n| `list_memories()` | 分页列举记忆 | 5-10ms |\n| `get_memory()` | 通过哈希获取单条记忆 | <5ms |\n\n### 性能指标\n\n根据基准测试数据，在 10 用户部署场景下的成本和性能表现如下：\n\n- **成本**: $0.15/1M tokens，每年约 $16.43\n- **首次调用延迟**: 约 50ms（包含存储初始化）\n- **后续调用延迟**: 5-10ms（连接复用）\n- **内存开销**: <10MB\n\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n## Claude Hooks 集成\n\n### 钩子类型概述\n\nClaude Hooks 提供了一种轻量级的代理记忆集成方式，支持会话生命周期的自动记忆管理。\n\n```mermaid\ngraph LR\n A[会话开始] --> B[Session-Start Hook]\n B --> C[加载相关记忆]\n C --> D[代理执行任务]\n D --> E[会话结束]\n E --> F[Session-End Hook]\n F --> G[存储会话洞察]\n \n H[自动捕获] --> I[Auto-Capture Hook]\n I --> D\n```\n\n### 会话结束收割机制\n\n`session-end-harvest.js` 负责在会话结束时自动提取和存储关键信息：\n\n| 功能 | 描述 |\n|------|------|\n| 决策提取 | 识别并保存会话中的关键决策 |\n| 洞察收集 | 收集有价值的见解和发现 |\n| 上下文保存 | 保留重要的技术上下文 |\n\n资料来源：[claude-hooks/core/session-end-harvest.js]()\n\n### 自动捕获钩子\n\n`auto-capture-hook.js` 提供了实时记忆捕获能力，无需用户显式操作即可记录重要信息：\n\n```javascript\n// 自动捕获配置示例\n{\n \"captureTriggers\": [\"#remember\", \"#important\"],\n \"excludePatterns\": [\"password\", \"api-key\"],\n \"maxContentLength\": 10000\n}\n```\n\n资料来源：[claude-hooks/core/auto-capture-hook.js]()\n\n### 配置选项\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `verbose` | `true` | 显示基本信息 |\n| `showMemoryDetails` | `false` | 显示记忆评分详情 |\n| `cleanMode` | `false` | 最小化输出 |\n| `injectAfterCompacting` | `false` | 紧凑化后注入记忆 |\n| `contentQuality` | - | 内容质量评分权重 |\n\n资料来源：[claude-hooks/README.md]()\n\n## LangGraph 集成\n\n### 集成方式\n\nMCP Memory Service 可以作为 LangGraph 代理的外部记忆存储，实现状态感知的长期记忆管理。\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom mcp_memory_service.api import search, store\n\n# 创建带记忆的代理\ndef memory_node(state):\n query = state.get(\"query\", \"\")\n results = search(query, limit=3)\n return {\"memories\": results.memories}\n\nagent = create_react_agent(\n model=llm,\n tools=[memory_node],\n state_modifier=\"你有一个外部记忆系统可以使用。\"\n)\n```\n\n### 状态流设计\n\n```mermaid\ngraph TB\n START[用户输入] --> MEMORY_QUERY[查询记忆]\n MEMORY_QUERY --> MEMORY_RESULTS[返回相关记忆]\n MEMORY_RESULTS --> CONTEXT_BUILD[构建上下文]\n CONTEXT_BUILD --> LLM_REASON[LLM 推理]\n LLM_REASON --> DECISION{需要新记忆?}\n DECISION -->|是| STORE[存储记忆]\n DECISION -->|否| RESPONSE[返回响应]\n STORE --> RESPONSE\n```\n\n资料来源：[docs/agents/langgraph.md]()\n\n## CrewAI 集成\n\n### 代理角色配置\n\nCrewAI 中的代理可以配置使用 MCP Memory Service 作为共享知识库：\n\n```python\nfrom crewai import Agent\nfrom mcp_memory_service.api import search\n\nresearcher = Agent(\n role=\"研究员\",\n goal=\"基于现有知识库进行深入研究\",\n backstory=\"你是一个研究专家，可以访问公司的知识库。\",\n tools=[search]\n)\n```\n\n### 记忆感知工作流\n\n| 组件 | 功能 |\n|------|------|\n| 共享记忆库 | 所有代理可访问的持久化记忆 |\n| 上下文注入 | 自动将相关记忆注入代理上下文 |\n| 学习反馈 | 任务完成后自动更新记忆库 |\n\n资料来源：[docs/agents/crewai.md]()\n\n## AutoGen 集成\n\n### 会话管理器集成\n\nAutoGen 的群组会话管理器可以与 MCP Memory Service 深度集成：\n\n```python\nimport autogen\nfrom mcp_memory_service.api import store, search\n\n# 创建记忆感知的群组管理员\nclass MemoryGroupChat(autogen.GroupChat):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.memory_service = True\n \n def select_speaker(self):\n # 基于相关记忆选择下一个发言者\n context = search(self.messages_summary)\n return super().select_speaker()\n```\n\n### 多代理记忆同步\n\n```mermaid\ngraph TB\n subgraph \"AutoGen 群组\"\n AGENT1[代理 A]\n AGENT2[代理 B]\n AGENT3[代理 C]\n end\n \n subgraph \"记忆服务\"\n MEMSTORE[(记忆存储)]\n end\n \n AGENT1 -->|写入洞察| MEMSTORE\n AGENT2 -->|写入发现| MEMSTORE\n AGENT3 -->|写入结论| MEMSTORE\n AGENT1 -->|读取| MEMSTORE\n AGENT2 -->|读取| MEMSTORE\n AGENT3 -->|读取| MEMSTORE\n```\n\n资料来源：[docs/agents/autogen.md]()\n\n## 配置管理\n\n### 环境变量配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `MCP_MAX_RESPONSE_CHARS` | `0` (无限制) | 最大响应字符数 |\n| `MCP_MEMORY_ENDPOINT` | 本地服务 | API 端点地址 |\n| `MCP_MEMORY_API_KEY` | 无 | API 认证密钥 |\n\n### 客户端配置示例\n\n```python\nfrom mcp_memory_service.api.client import MemoryServiceClient\n\nclient = MemoryServiceClient(\n endpoint=\"https://your-server:8443\",\n api_key=\"your-api-key\",\n timeout=30,\n max_retries=3\n)\n```\n\n资料来源：[src/mcp_memory_service/api/client.py]()\n\n## 错误处理与容错\n\n### 重试策略\n\nPython 客户端内置自动重试机制：\n\n| 错误类型 | 重试次数 | 退避策略 |\n|----------|----------|----------|\n| 网络超时 | 3 次 | 指数退避 |\n| 500 错误 | 2 次 | 线性退避 |\n| 认证失败 | 0 次 | 立即失败 |\n\n### 降级处理\n\n当记忆服务不可用时，代理框架可以配置降级策略：\n\n1. **静默降级**: 继续执行任务，记录警告\n2. **缓存降级**: 使用本地缓存的记忆\n3. **失败降级**: 返回错误，要求用户干预\n\n资料来源：[src/mcp_memory_service/api/operations.py]()\n\n## 最佳实践\n\n### 记忆质量控制\n\n| 原则 | 说明 |\n|------|------|\n| 相关性过滤 | 仅存储与目标相关的信息 |\n| 去重处理 | 避免存储重复内容 |\n| 时效性管理 | 定期清理过时记忆 |\n| 隐私保护 | 过滤敏感信息后再存储 |\n\n### 性能优化建议\n\n1. **批量操作**: 使用批量 API 减少网络往返\n2. **连接复用**: 保持长连接以降低延迟\n3. **异步处理**: 非关键路径使用异步调用\n4. **缓存策略**: 实现本地缓存减少重复查询\n\n### 安全注意事项\n\n- API 密钥应存储在环境变量或密钥管理服务中\n- 敏感记忆内容应在存储前进行脱敏处理\n- 定期轮换 API 访问凭证\n\n## 版本兼容性\n\n| 功能 | 最低版本要求 |\n|------|--------------|\n| Python 客户端 | v5.0.0+ |\n| Claude Hooks | v8.5.7+ |\n| LangGraph 集成 | v6.0.0+ |\n| CrewAI 集成 | v0.4.0+ |\n| AutoGen 集成 | v0.2.0+ |\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接超时 | 服务未启动 | 检查 `curl http://localhost:8000/api/health` |\n| 认证失败 | API 密钥错误 | 验证环境变量配置 |\n| 记忆未找到 | 哈希值错误 | 使用 `list_memories()` 检查 |\n| 响应延迟高 | 网络问题或负载高 | 检查服务端资源使用情况 |\n\n### 诊断命令\n\n```bash\n# 检查服务健康状态\ncurl http://localhost:8000/api/health\n\n# 检查 SSE 连接统计\ncurl http://localhost:8000/api/events/stats\n\n# 验证 Python 客户端连接\npython -c \"from mcp_memory_service.api import health; print(health())\"\n\n---\n\n\n\n## 插件系统\n\n### 相关页面\n\n相关主题：[MCP 协议集成](#mcp-integration), [记忆整合系统](#consolidation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/plugins/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/plugins/__init__.py)\n- [src/mcp_memory_service/plugins/registry.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/plugins/registry.py)\n- [src/mcp_memory_service/plugins/context.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/plugins/context.py)\n- [examples/plugin-audit-log/mcp_memory_plugin_audit_log/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/examples/plugin-audit-log/mcp_memory_plugin_audit_log/__init__.py)\n- [docs/plugins/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/plugins/README.md)\n \n\n# 插件系统\n\n## 概述\n\nMCP Memory Service 的插件系统是一个事件驱动的扩展框架，允许开发者通过订阅特定的钩子（Hook）来拦截和响应内存操作的生命周期事件。该系统采用基于 entry_points 的自动发现机制，插件无需修改核心代码即可扩展服务功能。\n\n## 架构设计\n\n### 核心组件\n\n插件系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 插件注册表 | `plugins/registry.py` | 管理所有已加载的插件，提供插件的注册、发现和生命周期管理 |\n| 插件上下文 | `plugins/context.py` | 提供插件与核心系统交互的 API，包括事件订阅和上下文信息访问 |\n| 插件入口 | `plugins/__init__.py` | 定义插件接口规范和公共导出 |\n\n### 事件驱动模型\n\n插件系统基于发布-订阅模式实现，核心服务在特定操作发生时触发相应的事件钩子：\n\n```mermaid\ngraph TD\n A[核心服务] -->|触发事件| B[事件总线]\n B --> C[插件A - on_store处理器]\n B --> D[插件B - on_store处理器]\n B --> E[插件C - on_retrieve处理器]\n \n C -->|处理| F[执行自定义逻辑]\n D -->|处理| G[记录审计日志]\n E -->|处理| H[缓存管理]\n```\n\n## 可用钩子\n\n系统提供四个主要的事件钩子，覆盖内存数据的完整生命周期：\n\n| 钩子名称 | 触发时机 | 典型用途 | 资料来源 |\n|----------|----------|----------|----------|\n| `on_store` | 新建记忆时 | 审计日志、自定义索引、统计收集 | [examples/plugin-audit-log/README.md]() |\n| `on_delete` | 删除记忆时 | 清理关联资源、更新统计数据 | [examples/plugin-audit-log/README.md]() |\n| `on_retrieve` | 查询记忆时 | 缓存记录、查询日志、性能监控 | [examples/plugin-audit-log/README.md]() |\n| `on_consolidate` | 记忆类型合并时 | 记录合并操作、验证数据一致性 | [examples/plugin-audit-log/README.md]() |\n\n## 开发指南\n\n### 创建插件\n\n#### 步骤一：创建插件包结构\n\n```\nmy-memory-plugin/\n├── my_memory_plugin/\n│ └── __init__.py\n├── pyproject.toml\n└── README.md\n```\n\n#### 步骤二：配置 entry_points\n\n在 `pyproject.toml` 中声明插件入口点：\n\n```toml\n[project]\nname = \"my-memory-plugin\"\nversion = \"0.1.0\"\n\n[project.entry-points.\"mcp_memory_service.plugins\"]\nmy_plugin = \"my_memory_plugin:register\"\n```\n\n#### 步骤三：实现插件逻辑\n\n```python\n# my_memory_plugin/__init__.py\n\ndef register(ctx):\n \"\"\"\n 注册插件处理器\n \n 参数:\n ctx: PluginContext 实例，提供事件订阅和系统交互能力\n \"\"\"\n ctx.on(\"on_store\", handle_store)\n ctx.on(\"on_delete\", handle_delete)\n ctx.on(\"on_retrieve\", handle_retrieve)\n ctx.on(\"on_consolidate\", handle_consolidate)\n\ndef handle_store(event):\n \"\"\"处理记忆存储事件\"\"\"\n print(f\"新记忆已存储: {event.hash}\")\n print(f\"类型: {event.memory_type}, 标签: {event.tags}\")\n\ndef handle_delete(event):\n \"\"\"处理记忆删除事件\"\"\"\n print(f\"记忆已删除: {event.hash}\")\n\ndef handle_retrieve(event):\n \"\"\"处理记忆检索事件\"\"\"\n print(f\"查询: {event.query}, 返回结果: {event.count} 条\")\n return event # 返回事件对象，确保后续处理器正常执行\n\ndef handle_consolidate(event):\n \"\"\"处理记忆类型合并事件\"\"\"\n print(f\"合并操作: {event.old_type} -> {event.new_type}\")\n print(f\"影响记忆数: {event.affected_count}\")\n```\n\n### 安装和使用\n\n1. 以开发模式安装插件：\n\n```bash\ncd my-memory-plugin\npip install -e .\n```\n\n2. 重启 MCP Memory Service：\n\n```bash\nsystemctl --user restart mcp-memory-http.service\n```\n\n3. 验证插件加载状态：\n\n```bash\ncurl -k https://localhost:8443/api/health\n```\n\n## 插件示例：审计日志\n\n`examples/plugin-audit-log` 提供了一个完整的参考实现：\n\n```python\n# 事件处理函数示例\n\ndef on_store_handler(event):\n \"\"\"记录存储操作\"\"\"\n log_entry = {\n \"action\": \"store\",\n \"hash\": event.hash,\n \"memory_type\": event.memory_type,\n \"tags\": event.tags,\n \"content_length\": len(event.content)\n }\n audit_logger.info(log_entry)\n\ndef on_delete_handler(event):\n \"\"\"记录删除操作\"\"\"\n log_entry = {\n \"action\": \"delete\",\n \"hash\": event.hash\n }\n audit_logger.info(log_entry)\n\ndef on_retrieve_handler(event):\n \"\"\"记录检索操作\"\"\"\n log_entry = {\n \"action\": \"retrieve\",\n \"query\": event.query,\n \"result_count\": len(event.results)\n }\n audit_logger.info(log_entry)\n return event # 返回事件确保后续处理链不被中断\n```\n\n## 插件上下文 API\n\n`PluginContext` 对象提供以下核心能力：\n\n| 方法 | 说明 | 返回值 |\n|------|------|--------|\n| `on(event, handler)` | 订阅指定事件 | 无 |\n| `off(event, handler)` | 取消事件订阅 | 无 |\n| `emit(event, data)` | 触发事件（由系统内部调用） | 无 |\n\n## 最佳实践\n\n### 事件处理器返回值\n\n处理检索相关事件时，**必须返回原始事件对象**以确保事件链正常传递：\n\n```python\ndef on_retrieve_handler(event):\n # 执行自定义逻辑\n process_results(event.results)\n # 必须返回事件对象\n return event\n```\n\n### 错误处理\n\n插件应实现健壮的错误处理机制，避免因单点故障影响系统稳定性：\n\n```python\ndef handle_store(event):\n try:\n # 插件逻辑\n do_something(event)\n except Exception as e:\n logger.error(f\"插件处理失败: {e}\")\n # 不抛出异常，保持系统正常运行\n```\n\n### 异步处理\n\n对于耗时操作，建议使用异步机制：\n\n```python\nimport asyncio\n\nasync def handle_store_async(event):\n await long_running_task(event)\n\ndef handle_store(event):\n asyncio.create_task(handle_store_async(event))\n```\n\n## 部署注意事项\n\n| 项目 | 说明 |\n|------|------|\n| 安装位置 | 插件包需安装到与 MCP Memory Service 相同的环境 |\n| 入口点名称 | 必须是 `mcp_memory_service.plugins` 组下的有效条目 |\n| 服务重启 | 每次安装或更新插件后需重启服务 |\n| 依赖隔离 | 建议使用虚拟环境管理插件依赖 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：doobidoo/mcp-memory-service\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps。\n\n## 1. 安装坑 · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fdb895dcb5694a15937c208c89c79c98 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：v10.51.1 — Milvus consolidation fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.1 — Milvus consolidation fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c344fbad309a43aa81482c5e4b429a53 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.3 — Versioned memory update flag + transitive graph inference\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e282c4b45ed04c8eb58759d1b32722bc | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n\n## 8. 能力坑 · 能力判断依赖假设\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:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：feat: cascading search fallback when semantic results are sparse\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v10.50.0 — Plugin Hook Scaffolding\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.50.0 — Plugin Hook Scaffolding\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af91db1e780a4ee5b0c16b8ea3238bf2 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d648b9854ac1432b8a86297ab220ba34 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · 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:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown\n\n\n",
"markdown_key": "mcp-memory-service",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:908539519",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/doobidoo/mcp-memory-service"
},
{
"evidence_id": "art_09b6ae48ac6f419583040a752c4a064c",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/doobidoo/mcp-memory-service#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mcp-memory-service 说明书",
"toc": [
"https://github.com/doobidoo/mcp-memory-service 项目说明书",
"目录",
"项目介绍",
"概述",
"核心功能",
"技术架构",
"API 接口",
"CLI 命令集成",
"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": "90fd7b531b48b62c409e2a0cae1fe78479f5dbe7",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/integrations.md",
"docs/architecture.md",
"docs/HOOK_IMPROVEMENTS.md",
"docs/enhancement-roadmap-issue-14.md",
"docs/sqlite-vec-backend.md",
"docs/CLAUDE_CODE_QUICK_REFERENCE.md",
"docs/setup-guide.md",
"docs/pr-graphql-integration.md",
"docs/oauth-storage-backends.md",
"docs/remote-configuration-wiki-section.md",
"docs/memory-ontology.md",
"docs/BENCHMARKS.md",
"docs/LM_STUDIO_COMPATIBILITY.md",
"docs/wiki-Graph-Database-Architecture.md",
"docs/docker-optimized-build.md",
"docs/remote-mcp-setup.md",
"docs/first-time-setup.md",
"docs/milvus-backend.md",
"docs/MIGRATION.md",
"docs/quick-setup-cloudflare-dual-environment.md",
"docs/amp-cli-bridge.md",
"docs/ide-compatability.md",
"docs/README.md",
"docs/IMAGE_RETENTION_POLICY.md",
"docs/LIGHTWEIGHT_ONNX_SETUP.md",
"docs/glama-deployment.md",
"docs/ROADMAP.md",
"docs/cloudflare-setup.md",
"docs/testing-cloudflare-backend.md",
"docs/http-server-management.md",
"docs/document-ingestion.md",
"docs/oauth-setup.md",
"docs/migrations/010-asymmetric-relationships.md",
"docs/testing/regression-tests.md",
"docs/testing/integrity-monitoring-test-report.md",
"docs/api/tag-standardization.md",
"docs/api/code-execution-interface.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# mcp-bridge-tests - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 mcp-bridge-tests 编译的 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_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md`, `.claude/skills/gitnexus/refactoring/SKILL.md` Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md`, `.claude/skills/gitnexus/refactoring/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json`, `claude-hooks/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `pip install mcp-memory-service` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `claude mcp add memory -- memory server` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `git clone https://github.com/doobidoo/mcp-memory-service.git` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install -e . # Editable install` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `pip install -e .` 证据：`CLAUDE.md` Claim：`clm_0009` supported 0.86, `clm_0010` supported 0.86, `clm_0011` supported 0.86, `clm_0012` supported 0.86 等\n- `pip install -e \".[full]\" # All features` 证据：`CLAUDE.md` Claim：`clm_0011` supported 0.86\n- `pip install -e \".[sqlite]\" # SQLite with ONNX only` 证据：`CLAUDE.md` Claim：`clm_0012` supported 0.86\n- `pip install -e \".[ml]\" # Full ML capabilities` 证据：`CLAUDE.md` Claim：`clm_0013` supported 0.86\n- `curl http://127.0.0.1:8000/api/health` 证据：`CLAUDE.md` Claim：`clm_0014` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md`, `.claude/skills/gitnexus/refactoring/SKILL.md` Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md`, `.claude/skills/gitnexus/refactoring/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json`, `claude-hooks/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`, `.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md` 等\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`, `claude-hooks/.claude-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`, `.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md` 等\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `CLAUDE.md`, `README.md`, `claude-hooks/.claude-plugin/plugin.json`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`.claude/directives/storage-backends.md`, `CLAUDE.md`, `archive/docs-root-cleanup-2025-08-23/CLOUDFLARE_IMPLEMENTATION.md`, `archive/docs-root-cleanup-2025-08-23/README-ORIGINAL-BACKUP.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0015` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json`, `claude-hooks/.claude-plugin/plugin.json` Claim：`clm_0016` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0017` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/skills/gitnexus/debugging/SKILL.md`, `.claude/skills/gitnexus/exploring/SKILL.md`, `.claude/skills/gitnexus/impact-analysis/SKILL.md`, `.claude/skills/gitnexus/refactoring/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json`, `claude-hooks/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：1112\n- 重要文件覆盖：40/1112\n- 证据索引条目：80\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 mcp-bridge-tests 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 mcp-bridge-tests 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 mcp-bridge-tests 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **gitnexus-debugging**（skill）：Trace bugs through call chains using knowledge graph 激活提示：当用户任务与“gitnexus-debugging”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/gitnexus/debugging/SKILL.md`\n- **gitnexus-exploring**（skill）：Navigate unfamiliar code using GitNexus knowledge graph 激活提示：当用户任务与“gitnexus-exploring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/gitnexus/exploring/SKILL.md`\n- **gitnexus-impact-analysis**（skill）：Analyze blast radius before making code changes 激活提示：当用户任务与“gitnexus-impact-analysis”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/gitnexus/impact-analysis/SKILL.md`\n- **gitnexus-refactoring**（skill）：Plan safe refactors using blast radius and dependency mapping 激活提示：当用户任务与“gitnexus-refactoring”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/gitnexus/refactoring/SKILL.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **MCP Memory Service Documentation**（documentation）：Welcome to the comprehensive documentation for MCP Memory Service - a Model Context Protocol server that provides semantic memory and persistent storage capabilities for Claude Desktop and other MCP clients. 证据：`docs/README.md`\n- **Agent Integration Guides**（documentation）：mcp-memory-service provides persistent shared memory for multi-agent systems via a framework-agnostic REST API . No MCP client library required — any HTTP client works. 证据：`docs/agents/README.md`\n- **Obsolete Workflows Archive**（documentation）：This directory contains historical documentation of workflows that have been superseded by better, automated solutions. 证据：`docs/archive/obsolete-workflows/README.md`\n- **MCP Memory Service Screenshots**（documentation）：This directory contains screenshots and visual assets for the MCP Memory Service documentation. 证据：`docs/assets/images/README.md`\n- **MCP Memory Service - Agent Guidelines**（documentation）：MCP Memory Service - Agent Guidelines 证据：`docs/guides/AGENTS.md`\n- **Gemini Context: MCP Memory Service**（documentation）：This project is a sophisticated and feature-rich MCP Memory Component Protocol server designed to provide a persistent, semantic memory layer for AI assistants, particularly \"Claude Desktop\". It's built with Python and leverages a variety of technologies to deliver a robust and performant memory service. 证据：`docs/integrations/gemini.md`\n- **GitNexus MCP**（documentation）：This project is indexed by GitNexus as mcp-memory-service 6259 symbols, 18031 relationships, 300 execution flows . 证据：`AGENTS.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with this MCP Memory Service repository. 证据：`CLAUDE.md`\n- **mcp-memory-service**（documentation）：Persistent Shared Memory for AI Agent Pipelines 证据：`README.md`\n- **Claude Code Memory Awareness Hooks**（documentation）：Automatic memory awareness and intelligent context injection for Claude Code using the MCP Memory Service. 证据：`claude-hooks/README.md`\n- **Claude Code Commands for MCP Memory Service**（documentation）：Claude Code Commands for MCP Memory Service 证据：`claude_commands/README.md`\n- **MCP Memory Service Examples**（documentation）：This directory contains example configurations, scripts, and setup utilities for deploying MCP Memory Service in various scenarios. 证据：`examples/README.md`\n- **OpenCode Memory Awareness Plugin**（documentation）：Automatic memory retrieval and context injection for OpenCode using the mcp-memory-service HTTP API. 证据：`opencode/README.md`\n- **MCP Memory Service Scripts**（documentation）：This directory contains organized utility scripts for maintaining, managing, and operating the MCP Memory Service. Scripts are categorized by function for easy navigation and maintenance. 证据：`scripts/README.md`\n- **MCP-MEMORY-SERVICE Tests**（documentation）：This directory contains tests for the MCP-MEMORY-SERVICE project. 证据：`tests/README.md`\n- **Development Tools and Utilities**（documentation）：This directory contains development tools, build utilities, and deployment configurations for MCP Memory Service. 证据：`tools/README.md`\n- **MCP Memory Service - Technical Showcase Video**（documentation）：MCP Memory Service - Technical Showcase Video 证据：`video/README.md`\n- **Claude Code Commands**（documentation）：Custom slash commands for mcp-memory-service development. 证据：`.claude/commands/README.md`\n- **Claude Code Directives**（documentation）：This directory contains modular directive files that supplement CLAUDE.md with specific behavioral rules and conventions. 证据：`.claude/directives/README.md`\n- **Agent Integrations - Detailed Usage**（documentation）：Agent Integrations - Detailed Usage 证据：`.claude/directives/agents.md`\n- **Tool Optimization - Execution Guide**（documentation）：Tool Optimization - Execution Guide 证据：`archive/docs-root-cleanup-2026-04-02/tasks-tool-optimization/CLAUDE.md`\n- **MCP Memory Service - Tool Optimization Plan**（documentation）：MCP Memory Service - Tool Optimization Plan 证据：`archive/docs-root-cleanup-2026-04-02/tasks-tool-optimization/README.md`\n- **Development Files Archive**（documentation）：This directory contains files used during the development and setup process: 证据：`archive/setup-development/README.md`\n- **Audit Log Plugin — Example**（documentation）：Demonstrates all 4 lifecycle hooks by writing events to a JSON Lines file. 证据：`examples/plugin-audit-log/README.md`\n- **Maintenance Scripts**（documentation）：This directory contains maintenance and diagnostic scripts for the MCP Memory Service database. 证据：`scripts/maintenance/README.md`\n- **Database Synchronization Scripts**（documentation）：This directory contains scripts for synchronizing SQLite-vec databases across multiple machines using JSON export/import and Litestream replication. 证据：`scripts/sync/README.md`\n- **Litestream Sync - Local Network HTTP API Synchronization**（documentation）：Litestream Sync - Local Network HTTP API Synchronization 证据：`scripts/sync/litestream/README.md`\n- **MCP Memory Service Interactive Dashboard**（documentation）：MCP Memory Service Interactive Dashboard 证据：`src/mcp_memory_service/web/static/README.md`\n- **Docker Setup for MCP Memory Service**（documentation）：Docker Setup for MCP Memory Service 证据：`tools/docker/README.md`\n- **PyPI Defensive Name Placeholders**（documentation）：Tracking issue: 809 https://github.com/doobidoo/mcp-memory-service/issues/809 证据：`tools/pypi-placeholders/README.md`\n- **agent-memory-service placeholder**（documentation）：This is a placeholder package . The actual implementation lives at: 证据：`tools/pypi-placeholders/agent-memory-service/README.md`\n- **ai-memory-service placeholder**（documentation）：This is a placeholder package . The actual implementation lives at: 证据：`tools/pypi-placeholders/ai-memory-service/README.md`\n- **memory-for-agents placeholder**（documentation）：This is a placeholder package . The actual implementation lives at: 证据：`tools/pypi-placeholders/memory-for-agents/README.md`\n- **Package**（package_manifest）：{ \"name\": \"mcp-memory-video\", \"version\": \"1.0.0\", \"description\": \"Technical Showcase video for MCP Memory Service\", \"scripts\": { \"extract-data\": \"tsx scripts/extract-project-data.ts\", \"dev\": \"remotion studio\", \"build\": \"remotion render MCPMemoryShowcase out/showcase.mp4\", \"build:short\": \"remotion render MCPMemoryShowcase-Short out/showcase-short.mp4\", \"build:walkthrough\": \"remotion render MCPMemoryWalkthrough out/walkthrough.mp4\", \"build:gif\": \"remotion render MCPMemoryShowcase out/preview.gif --codec=gif --scale=0.5\", \"preview\": \"remotion preview out/showcase.mp4\", \"upgrade\": \"remotion upgrade\" }, \"dependencies\": { \"@react-three/drei\": \"^9.96.0\", \"@react-three/fiber\": \"^8.15.16\", \"@react-t… 证据：`video/package.json`\n- **Contributing to MCP Memory Service**（documentation）：Thank you for your interest in contributing to MCP Memory Service! 🎉 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"mcp-bridge-tests\", \"version\": \"1.0.0\", \"description\": \"Unit tests for HTTP-MCP bridge\", \"main\": \"test http mcp bridge.js\", \"scripts\": { \"test\": \"mocha test http mcp bridge.js --reporter spec\", \"test:watch\": \"mocha test http mcp bridge.js --reporter spec --watch\" }, \"dependencies\": { \"mocha\": \"^10.0.0\", \"sinon\": \"^17.0.0\" }, \"devDependencies\": {}, \"overrides\": { \"minimatch\": \"^10.2.3\", \"serialize-javascript\": \"^7.0.3\" }, \"keywords\": \"mcp\", \"bridge\", \"testing\" , \"author\": \"\", \"license\": \"Apache-2.0\" } 证据：`tests/bridge/package.json`\n- **Package**（package_manifest）：{ \"name\": \"mcp-integration-tests\", \"version\": \"1.0.0\", \"description\": \"Integration tests for HTTP-MCP bridge\", \"main\": \"test bridge integration.js\", \"scripts\": { \"test\": \"mocha test bridge integration.js --reporter spec --timeout 10000\", \"test:watch\": \"mocha test bridge integration.js --reporter spec --timeout 10000 --watch\" }, \"dependencies\": { \"mocha\": \"^10.0.0\", \"sinon\": \"^17.0.0\" }, \"devDependencies\": {}, \"overrides\": { \"minimatch\": \"^10.2.3\", \"serialize-javascript\": \"^7.0.3\" }, \"keywords\": \"mcp\", \"bridge\", \"integration\", \"testing\" , \"author\": \"\", \"license\": \"Apache-2.0\" } 证据：`tests/integration/package.json`\n- **Debugging with GitNexus**（skill_instruction）：When to Use - \"Why is this function failing?\" - \"Trace where this error comes from\" - \"Who calls this method?\" - \"This endpoint returns 500\" - Investigating bugs, errors, or unexpected behavior 证据：`.claude/skills/gitnexus/debugging/SKILL.md`\n- **Exploring Codebases with GitNexus**（skill_instruction）：When to Use - \"How does authentication work?\" - \"What's the project structure?\" - \"Show me the main components\" - \"Where is the database logic?\" - Understanding code you haven't seen before 证据：`.claude/skills/gitnexus/exploring/SKILL.md`\n- **Impact Analysis with GitNexus**（skill_instruction）：When to Use - \"Is it safe to change this function?\" - \"What will break if I modify X?\" - \"Show me the blast radius\" - \"Who uses this code?\" - Before making non-trivial code changes - Before committing — to understand what your changes affect 证据：`.claude/skills/gitnexus/impact-analysis/SKILL.md`\n- **Refactoring with GitNexus**（skill_instruction）：When to Use - \"Rename this function safely\" - \"Extract this into a module\" - \"Split this service\" - \"Move this to a new file\" - Any task involving renaming, extracting, splitting, or restructuring code 证据：`.claude/skills/gitnexus/refactoring/SKILL.md`\n- **Marketplace**（structured_config）：{ \"name\": \"mcp-memory-service\", \"owner\": { \"name\": \"doobidoo\", \"url\": \"https://github.com/doobidoo\" }, \"plugins\": { \"name\": \"mcp-memory-service\", \"source\": \"./claude-hooks\", \"description\": \"Semantic memory for Claude Code sessions\" } } 证据：`.claude-plugin/marketplace.json`\n- **Test Environment Scripts**（documentation）：CRITICAL: These scripts protect production data during manual testing. 证据：`scripts/test/README.md`\n- **Manual Testing Scripts**（documentation）：This directory contains manual test scripts that are NOT run by pytest. 证据：`scripts/testing/README.md`\n- **Plugin**（structured_config）：{ \"name\": \"mcp-memory-service\", \"version\": \"1.0.0\", \"description\": \"Automatic memory capture and injection for Claude Code via MCP Memory Service\", \"author\": { \"name\": \"doobidoo\" }, \"homepage\": \"https://github.com/doobidoo/mcp-memory-service\", \"mcpServers\": \"./.mcp.json\", \"hooks\": \"./.claude-plugin/hooks.json\" } 证据：`claude-hooks/.claude-plugin/plugin.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **MCP Memory Service — Benchmark Results**（documentation）：MCP Memory Service — Benchmark Results 证据：`docs/BENCHMARKS.md`\n- **Claude Code Quick Reference for MCP Memory Service**（documentation）：Claude Code Quick Reference for MCP Memory Service 证据：`docs/CLAUDE_CODE_QUICK_REFERENCE.md`\n- **Claude Code Session Hook Improvements**（documentation）：Claude Code Session Hook Improvements 证据：`docs/HOOK_IMPROVEMENTS.md`\n- **Docker Image Retention Policy**（documentation）：This document describes the automated image retention and cleanup policies for the MCP Memory Service Docker images across Docker Hub and GitHub Container Registry GHCR . 证据：`docs/IMAGE_RETENTION_POLICY.md`\n- **MCP Memory Service - Portable Multi-Machine Setup**（documentation）：MCP Memory Service - Portable Multi-Machine Setup 证据：`docs/LIGHTWEIGHT_ONNX_SETUP.md`\n- **LM Studio Compatibility Guide**（documentation）：When using MCP Memory Service with LM Studio or Claude Desktop, you may encounter errors when operations are cancelled or timeout: 证据：`docs/LM_STUDIO_COMPATIBILITY.md`\n- **Tool Migration Guide**（documentation）：MCP Memory Service v2.0 consolidates 34 tools into 12 unified tools for better usability and MCP best practices compliance. 证据：`docs/MIGRATION.md`\n- **Development Roadmap**（documentation）：The official roadmap has moved to the Wiki for easier maintenance and community collaboration. 证据：`docs/ROADMAP.md`\n- **Amp CLI Bridge Semi-Automated Workflow**（documentation）：Amp CLI Bridge Semi-Automated Workflow 证据：`docs/amp-cli-bridge.md`\n- **MCP Memory Service Architecture**（documentation）：MCP Memory Service is a Model Context Protocol server that provides semantic memory and persistent storage capabilities for AI assistants. It enables long-term memory storage with semantic search, time-based recall, and tag-based organization across conversations. 证据：`docs/architecture.md`\n- **Cloudflare Backend Setup Guide**（documentation）：The MCP Memory Service supports native Cloudflare integration using Vectorize for vector storage, D1 for metadata, and optional R2 for large content. This provides: 证据：`docs/cloudflare-setup.md`\n- **Docker Optimized Build Guide**（documentation）：The MCP Memory Service Docker images have been optimized to use sqlite vec as the default storage backend with lightweight ONNX embeddings , removing heavy ML dependencies PyTorch, sentence-transformers from the default build. This results in: 证据：`docs/docker-optimized-build.md`\n- **Document Ingestion v7.6.0+**（documentation）：Enhanced document parsing with optional semtools integration for superior quality extraction. 证据：`docs/document-ingestion.md`\n- **Memory Awareness Enhancement Roadmap - Issue 14**（documentation）：Memory Awareness Enhancement Roadmap - Issue 14 证据：`docs/enhancement-roadmap-issue-14.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `docs/agents/README.md`, `docs/archive/obsolete-workflows/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `docs/agents/README.md`, `docs/archive/obsolete-workflows/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, src/mcp_memory_service/__init__.py, docs/architecture.md\n- **快速开始**：importance `high`\n - source_paths: docs/setup-guide.md, docs/first-time-setup.md, install.py, examples/claude_desktop_config_template.json\n- **系统架构**：importance `high`\n - source_paths: src/mcp_memory_service/mcp_server.py, src/mcp_memory_service/server/__main__.py, src/mcp_memory_service/services/memory_service.py, src/mcp_memory_service/services/graph_service.py, docs/architecture.md\n- **存储后端**：importance `high`\n - source_paths: src/mcp_memory_service/storage/__init__.py, src/mcp_memory_service/storage/factory.py, src/mcp_memory_service/storage/sqlite_vec.py, src/mcp_memory_service/storage/cloudflare.py, src/mcp_memory_service/storage/hybrid.py\n- **知识图谱**：importance `high`\n - source_paths: src/mcp_memory_service/storage/graph.py, src/mcp_memory_service/models/association.py, src/mcp_memory_service/reasoning/entities.py, src/mcp_memory_service/reasoning/inference.py, src/mcp_memory_service/consolidation/relationship_inference.py\n- **记忆整合系统**：importance `high`\n - source_paths: src/mcp_memory_service/consolidation/consolidator.py, src/mcp_memory_service/consolidation/scheduler.py, src/mcp_memory_service/consolidation/compression.py, src/mcp_memory_service/consolidation/decay.py, src/mcp_memory_service/consolidation/forgetting.py\n- **质量评分系统**：importance `medium`\n - source_paths: src/mcp_memory_service/quality/scorer.py, src/mcp_memory_service/quality/onnx_ranker.py, src/mcp_memory_service/quality/ai_evaluator.py, src/mcp_memory_service/quality/async_scorer.py, src/mcp_memory_service/quality/config.py\n- **MCP 协议集成**：importance `high`\n - source_paths: src/mcp_memory_service/mcp_server.py, src/mcp_memory_service/server/handlers/__init__.py, src/mcp_memory_service/server/handlers/memory.py, src/mcp_memory_service/server/handlers/utility.py, src/mcp_memory_service/discovery/mdns_service.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `90fd7b531b48b62c409e2a0cae1fe78479f5dbe7`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/integrations.md`, `docs/architecture.md`, `docs/HOOK_IMPROVEMENTS.md`, `docs/enhancement-roadmap-issue-14.md`, `docs/sqlite-vec-backend.md`, `docs/CLAUDE_CODE_QUICK_REFERENCE.md`, `docs/setup-guide.md`, `docs/pr-graphql-integration.md`, `docs/oauth-storage-backends.md`, `docs/remote-configuration-wiki-section.md`, `docs/memory-ontology.md`, `docs/BENCHMARKS.md`, `docs/LM_STUDIO_COMPATIBILITY.md`, `docs/wiki-Graph-Database-Architecture.md`, `docs/docker-optimized-build.md`, `docs/remote-mcp-setup.md`, `docs/first-time-setup.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_fdb895dcb5694a15937c208c89c79c98 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：v10.51.1 — Milvus consolidation fix\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.1 — Milvus consolidation fix\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c344fbad309a43aa81482c5e4b429a53 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.3 — Versioned memory update flag + transitive graph inference\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_e282c4b45ed04c8eb58759d1b32722bc | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：doobidoo/mcp-memory-service\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps（medium）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v10.51.1 — Milvus consolidation fix（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：v10.54.0 — AND/OR tag filtering for memory_search（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/doobidoo/mcp-memory-service 项目说明书\n\n生成时间：2026-05-12 06:04:02 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [快速开始](#quick-start)\n- [系统架构](#architecture)\n- [存储后端](#storage-backends)\n- [知识图谱](#knowledge-graph)\n- [记忆整合系统](#consolidation)\n- [质量评分系统](#quality-scoring)\n- [MCP 协议集成](#mcp-integration)\n- [代理框架集成](#agent-frameworks)\n- [插件系统](#plugins)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速开始](#quick-start), [系统架构](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/README.md)\n- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)\n- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)\n- [src/mcp_memory_service/server_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)\n- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n \n\n# 项目介绍\n\n## 概述\n\nMCP Memory Service 是一个基于 MCP（Model Context Protocol）架构的语义记忆存储与检索服务。该项目为 AI 应用提供持久化记忆能力，支持语义搜索、时间范围查询、标签分类等高级功能。 资料来源：[README.md:1-10]()\n\n## 核心功能\n\n### 记忆存储与管理\n\n系统提供完整的记忆生命周期管理，包括存储、检索、删除和更新操作。每条记忆自动生成内容哈希和语义向量嵌入，便于精确匹配和相似性搜索。 资料来源：[src/mcp_memory_service/web/app.py:20-50]()\n\n### 语义搜索能力\n\n基于向量嵌入的语义相似度搜索是本项目的核心特性。用户可以使用自然语言查询，系统自动计算查询向量与存储记忆的余弦相似度，返回最相关的结果。 资料来源：[src/mcp_memory_service/api/__init__.py:10-25]()\n\n### 实时事件流\n\n通过 Server-Sent Events（SSE）技术，系统支持实时记忆事件推送。客户端可以订阅记忆创建、更新、删除等事件，实现与外部系统的实时集成。 资料来源：[src/mcp_memory_service/web/app.py:55-70]()\n\n## 技术架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[Claude Code / MCP Client] --> B[MCP Memory Service]\n B --> C[API Layer]\n C --> D[Memory Service]\n D --> E[Storage Backend]\n E --> F[SQLite-vec]\n E --> G[Cloudflare D1]\n H[Hooks / Commands] --> B\n```\n\n### 存储后端\n\n系统支持多种存储后端配置：\n\n| 后端类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| SQLite-vec | 本地向量数据库，轻量级部署 | 个人用户、小型团队 |\n| Cloudflare D1 + Vectorize | 云端向量存储，全球分发 | 企业级部署、高可用需求 |\n| Hybrid | 混合模式，结合本地和云端优势 | 复杂架构场景 |\n\n资料来源：[src/mcp_memory_service/web/app.py:120-135]()\n\n### 嵌入模型\n\n系统默认使用 **all-MiniLM-L6-v2** 嵌入模型，该模型在性能和精度之间取得良好平衡：\n\n- 向量维度：384\n- 上下文窗口：256 tokens\n- 平均延迟：5-10ms（后续调用）\n\n资料来源：[src/mcp_memory_service/web/app.py:140-145]()\n\n## API 接口\n\n### 记忆管理接口\n\n| 接口 | 方法 | 路径 | 功能 |\n|------|------|------|------|\n| 存储记忆 | POST | `/api/memories` | 存储新记忆，自动生成嵌入向量 |\n| 列出记忆 | GET | `/api/memories` | 分页列出所有记忆 |\n| 获取记忆 | GET | `/api/memories/{hash}` | 通过内容哈希获取特定记忆 |\n| 删除记忆 | DELETE | `/api/memories/{hash}` | 删除记忆及其嵌入向量 |\n\n资料来源：[src/mcp_memory_service/web/app.py:15-45]()\n\n### 搜索接口\n\n| 接口 | 方法 | 路径 | 功能 |\n|------|------|------|------|\n| 语义搜索 | POST | `/api/search` | 基于嵌入向量的语义相似度搜索 |\n| 相似记忆 | GET | `/api/search/similar/{hash}` | 查找与指定记忆相似的其他记忆 |\n\n### 事件接口\n\n| 接口 | 方法 | 路径 | 功能 |\n|------|------|------|------|\n| 事件流 | GET | `/api/events` | 订阅实时记忆事件流 |\n| 统计信息 | GET | `/api/events/stats` | 查看 SSE 连接统计 |\n\n## CLI 命令集成\n\n系统提供一系列 Claude Code CLI 命令，方便在终端环境中操作记忆：\n\n### 可用命令\n\n| 命令 | 功能 |\n|------|------|\n| `/memory-store` | 存储新记忆 |\n| `/memory-recall` | 基于时间表达式的记忆检索 |\n| `/memory-search` | 标签和内容搜索 |\n| `/memory-context` | 捕获当前会话上下文作为记忆 |\n| `/memory-health` | 服务健康检查 |\n\n资料来源：[claude_commands/README.md:15-50]()\n\n### 安装方式\n\n```bash\n# 自动安装（推荐）\npython scripts/installation/install.py\n\n# 强制安装命令\npython scripts/installation/install.py --install-claude-commands\n```\n\n## Claude Hooks 集成\n\n系统提供自动化记忆管理钩子，深度集成到 Claude Code 工作流中：\n\n### 钩子类型\n\n| 钩子名称 | 触发时机 | 功能 |\n|---------|---------|------|\n| `session-start` | 会话开始时 | 自动加载相关项目记忆 |\n| `mid-conversation` | 对话过程中 | 根据关键词触发记忆注入 |\n| `session-end` | 会话结束时 | 存储会话洞察和决策 |\n| `auto-capture` | 代码修改时 | 自动捕获代码变更上下文 |\n\n资料来源：[claude-hooks/README.md:10-30]()\n\n### 配置选项\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"your-api-key\"\n },\n \"verbosity\": {\n \"verbose\": true,\n \"showMemoryDetails\": false,\n \"cleanMode\": false\n }\n}\n```\n\n## 性能指标\n\n### 响应时间\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 首次调用 | ~50ms | 包含存储初始化开销 |\n| 后续调用 | 5-10ms | 连接复用后延迟 |\n| 内存占用 | <10MB | 服务进程内存开销 |\n\n### 成本估算\n\n- **费用**: $0.15/1M tokens\n- **10用户部署年费**: $16.43/年\n\n资料来源：[src/mcp_memory_service/api/__init__.py:5-15]()\n\n## 维护工具\n\n系统提供完整的维护脚本支持：\n\n| 脚本 | 功能 |\n|------|------|\n| `check_memory_types.py` | 检查记忆类型碎片化程度 |\n| `consolidate_memory_types.py` | 将碎片化类型合并为标准24类分类体系 |\n| `cleanup_duplicates.py` | 识别和清理重复记忆 |\n\n资料来源：[scripts/maintenance/README.md:10-40]()\n\n## 插件系统\n\n系统支持插件扩展机制，允许开发者自定义钩子处理逻辑：\n\n```python\n# 插件注册示例\ndef register(ctx):\n ctx.on(\"on_store\", my_store_handler)\n ctx.on(\"on_retrieve\", my_retrieve_handler)\n```\n\n插件通过 `entry_points` 机制自动加载：\n\n```toml\n[project.entry-points.\"mcp_memory_service.plugins\"]\nmy_plugin = \"my_package:register\"\n```\n\n资料来源：[examples/plugin-audit-log/README.md:20-35]()\n\n## 快速开始\n\n### 安装依赖\n\n```bash\npip install mcp-memory-service\n```\n\n### 启动服务\n\n```bash\nmcp-memory-http\n```\n\n### 验证安装\n\n```bash\ncurl https://localhost:8443/api/health\n```\n\n### 基础使用示例\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 存储记忆\nhash_id = store(\"New memory\", tags=[\"note\", \"important\"])\n\n# 语义搜索\nresults = search(\"architecture decisions\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# 健康检查\ninfo = health()\nprint(f\"Backend: {info.backend}, Count: {info.count}\")\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py:20-40]()\n\n## 技术栈\n\n| 组件 | 技术选型 |\n|------|---------|\n| 后端框架 | FastAPI / MCP Server |\n| 向量数据库 | SQLite-vec |\n| 嵌入模型 | all-MiniLM-L6-v2 |\n| 实时通信 | Server-Sent Events |\n| 部署方式 | Docker / Systemd / Litestream |\n\n## 总结\n\nMCP Memory Service 为 AI 应用提供了一个功能完整、高性能、可扩展的记忆存储解决方案。通过 MCP 协议与 Claude Code 的深度集成，以及丰富的 CLI 命令和 Hooks 机制，该服务能够无缝融入现有的 AI 开发工作流程，成为智能应用的\"外部大脑\"。\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/web/app.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py) - Web 应用与 API 端点\n- [src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py) - API 模块文档与使用示例\n- [src/mcp_memory_service/server_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py) - MCP 服务器实现\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md) - Claude Code 钩子安装指南\n- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md) - Claude 命令文档\n- [examples/plugin-audit-log/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/examples/plugin-audit-log/README.md) - 插件系统说明\n \n\n# 快速开始\n\nMCP Memory Service 是一个语义记忆服务，用于存储、检索和管理基于向量的语义记忆。本文档帮助你在 5 分钟内完成安装、配置并开始使用该服务。\n\n## 系统要求\n\n| 组件 | 最低版本 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 核心运行环境 |\n| Node.js | 任意版本 | 用于钩子执行 |\n| jq | 最新版本 | Claude Code 状态栏显示所需 |\n| pip | 最新版本 | Python 包管理 |\n\n资料来源：[claude-hooks/README.md:44-49]()\n\n## 安装方式\n\n### 方式一：完整安装（推荐）\n\n完整安装包含 HTTP 服务器、Claude Code 钩子和命令：\n\n```bash\ncd mcp-memory-service\npython scripts/installation/install.py\n```\n\n安装脚本会依次安装：\n\n1. HTTP 服务器及其依赖\n2. Claude Code 钩子（自动记忆加载和存储）\n3. Claude Code 命令（手动记忆操作）\n4. 交互式 API 文档\n\n资料来源：[scripts/installation/install.py]() - 主安装脚本\n\n### 方式二：分步安装\n\n#### 步骤 1：安装 HTTP 服务器\n\n```bash\npip install mcp-memory-service\nmcp-memory-http # 启动服务器\n```\n\n服务器默认在 `https://localhost:8443` 运行。\n\n#### 步骤 2：安装 Claude Code 钩子\n\n```bash\ncd claude-hooks\npython install_hooks.py # 安装所有功能\n```\n\n或安装特定功能：\n\n```bash\npython install_hooks.py --basic # 基础记忆钩子\npython install_hooks.py --natural-triggers # 自然记忆触发器\n```\n\n资料来源：[claude-hooks/README.md:38-51]()\n\n#### 步骤 3：安装 Claude 命令\n\n```bash\ncd claude_commands\nclaude /install-commands\n```\n\n或使用安装脚本：\n\n```bash\npython scripts/installation/install.py --install-claude-commands\n```\n\n资料来源：[claude_commands/README.md:32-45]()\n\n## 配置\n\n### Claude Desktop 配置\n\n在 Claude Desktop 配置文件中添加 MCP 服务器：\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-memory-service\"],\n \"env\": {\n \"MCP_MEMORY_DB_PATH\": \"~/.local/share/mcp-memory/sqlite_vec.db\"\n }\n }\n }\n}\n```\n\n资料来源：[examples/claude_desktop_config_template.json]() - Claude Desktop 配置模板\n\n### 钩子配置\n\n编辑 `~/.claude/hooks/config.json` 配置记忆服务连接：\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"your-api-key\"\n },\n \"verbosity\": {\n \"verbose\": true,\n \"showMemoryDetails\": false,\n \"cleanMode\": false\n }\n}\n```\n\n资料来源：[claude-hooks/README.md:66-75]()\n\n## 服务启动\n\n### 启动 HTTP 服务器\n\n```bash\n# 使用默认配置\nmcp-memory-http\n\n# 或使用自定义配置\nmcp-memory-http --host 0.0.0.0 --port 8080\n```\n\n### 验证安装\n\n```bash\n# 检查服务健康状态\ncurl -k https://localhost:8443/api/health\n\n# 验证钩子安装\nclaude --debug hooks\n```\n\n资料来源：[claude-hooks/README.md:53-56]()\n\n## API 快速使用\n\n### Python API\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 搜索记忆（20 tokens）\nresults = search(\"架构决策\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# 存储记忆（15 tokens）\nhash_id = store(\"新记忆\", tags=[\"笔记\", \"重要\"])\nprint(f\"已存储: {hash_id}\")\n\n# 健康检查（5 tokens）\ninfo = health()\nprint(f\"后端: {info.backend}, 数量: {info.count}\")\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py:1-20]()\n\n### REST API 端点\n\n| 方法 | 端点 | 说明 |\n|------|------|------|\n| POST | `/api/memories` | 存储新记忆（自动生成嵌入向量） |\n| GET | `/api/memories` | 列出所有记忆（支持分页） |\n| GET | `/api/memories/{hash}` | 按内容哈希检索特定记忆 |\n| DELETE | `/api/memories/{hash}` | 删除记忆及其嵌入向量 |\n| POST | `/api/search` | 语义相似性搜索 |\n| GET | `/api/search/similar/{hash}` | 查找相似记忆 |\n| GET | `/api/events` | 订阅实时记忆事件流 |\n\n资料来源：[src/mcp_memory_service/web/app.py:1-50]()\n\n## Claude 命令速查\n\n| 命令 | 用途 | 示例 |\n|------|------|------|\n| `/memory-recall` | 自然语言时间检索 | `/memory-recall \"上周的数据库讨论\"` |\n| `/memory-search` | 标签和内容搜索 | `/memory-search --tags \"架构,数据库\"` |\n| `/memory-context` | 上下文记忆保存 | `/memory-context --summary \"架构规划\"` |\n| `/memory-health` | 服务健康检查 | `/memory-health --detailed` |\n\n资料来源：[claude_commands/README.md:1-30]()\n\n## 插件系统\n\n### 安装插件\n\n创建包含入口点的 Python 包：\n\n```toml\n[project.entry-points.\"mcp_memory_service.plugins\"]\nmy_plugin = \"my_package:register\"\n```\n\n### 实现插件\n\n```python\ndef register(ctx):\n ctx.on(\"on_store\", my_store_handler)\n ctx.on(\"on_retrieve\", my_retrieve_handler)\n```\n\n### 可用钩子\n\n| 钩子 | 用途 |\n|------|------|\n| `on_store` | 记录哈希、类型、标签、内容长度 |\n| `on_delete` | 记录删除的哈希 |\n| `on_retrieve` | 记录查询和结果数量 |\n| `on_consolidate` | 记录合并统计 |\n\n资料来源：[examples/plugin-audit-log/README.md:1-40]()\n\n## 性能指标\n\n| 指标 | 数值 |\n|------|------|\n| 首次调用 | ~50ms（含存储初始化） |\n| 后续调用 | ~5-10ms（连接复用） |\n| 内存开销 | <10MB |\n| 每百万 token 成本 | $0.15（10 用户部署约 $16.43/年） |\n\n资料来源：[src/mcp_memory_service/api/__init__.py:10-16]()\n\n## 故障排除\n\n| 问题 | 解决方案 |\n|------|----------|\n| 钩子未检测到 | 运行 `ls ~/.claude/settings.json`，如缺失则重新安装 |\n| JSON 解析错误 | 更新到最新版本（含 Python 字典转换） |\n| 连接失败 | 检查 `curl -k https://your-endpoint:8443/api/health` |\n| 目录错误 | 将 `~/.claude-code/hooks/*` 移动到 `~/.claude/hooks/` |\n\n资料来源：[claude-hooks/README.md:58-68]()\n\n## 后续步骤\n\n- 查看 [维护脚本](../maintenance/README.md) 了解数据库优化\n- 配置 Litestream 实现自动备份\n- 探索插件系统扩展功能\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[存储后端](#storage-backends), [知识图谱](#knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)\n- [src/mcp_memory_service/server/__main__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/__main__.py)\n- [src/mcp_memory_service/services/memory_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py)\n- [src/mcp_memory_service/services/graph_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py)\n- [docs/architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture.md)\n- [docs/architecture/graph-database-design.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture/graph-database-design.md)\n \n\n# 系统架构\n\n## 概述\n\nMCP Memory Service 是一个基于 Model Context Protocol (MCP) 的语义记忆服务系统，旨在为 AI 助手和开发者提供持久化、可搜索的上下文记忆能力。该系统通过向量嵌入技术实现语义相似度搜索，支持跨机器同步，并提供多种访问接口包括 MCP 协议、REST API、CLI 命令和 Web 界面。\n\n系统的核心设计理念是创建一个**轻量级但功能强大**的记忆服务，使得 AI 能够在多轮对话和跨会话场景中保持上下文连续性。通过自动嵌入生成、智能标签管理和关系图谱构建，系统能够高效地组织和检索记忆内容。\n\n---\n\n## 整体架构\n\n### 分层架构设计\n\nMCP Memory Service 采用分层架构，将系统划分为清晰的功能层级：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| **接口层** | MCP Server、Web API、CLI、Web UI | 提供多种访问方式 |\n| **服务层** | Memory Service、Graph Service | 核心业务逻辑 |\n| **存储层** | SQLite-Vec、文件系统 | 数据持久化 |\n| **同步层** | Litestream 配置 | 跨机器数据同步 |\n\n### 核心组件交互\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n Claude[Claude Code]\n HTTP[HTTP 客户端]\n CLI[CLI 命令]\n MCP[MCP 客户端]\n end\n \n subgraph \"接口层\"\n MCP_Server[MCP Server
mcp_server.py]\n Web_API[Web API
app.py]\n CLI_Main[CLI Main
main.py]\n end\n \n subgraph \"服务层\"\n Memory_Service[Memory Service
memory_service.py]\n Graph_Service[Graph Service
graph_service.py]\n Embedding[Embedding Service]\n Search[Search Service]\n end\n \n subgraph \"存储层\"\n SQLite_Vec[(SQLite-Vec
向量数据库)]\n File_System[(文件系统
配置与备份)]\n end\n \n subgraph \"同步层\"\n Litestream[Litestream
跨机器同步]\n end\n \n Claude --> MCP_Server\n MCP --> MCP_Server\n HTTP --> Web_API\n CLI --> CLI_Main\n \n MCP_Server --> Memory_Service\n Web_API --> Memory_Service\n CLI_Main --> Memory_Service\n \n Memory_Service --> SQLite_Vec\n Graph_Service --> SQLite_Vec\n Memory_Service --> Embedding\n \n Litestream --> SQLite_Vec\n```\n\n---\n\n## MCP 协议层\n\n### MCP Server 实现\n\nMCP Server 是系统的核心接口之一，遵循 Model Context Protocol 规范实现。服务器通过 MCP 工具暴露记忆管理功能，使 Claude Code 等 MCP 兼容客户端能够直接调用记忆服务。\n\n**核心功能模块**：\n\n- **工具注册**：动态注册 MCP 工具到客户端\n- **请求路由**：将 MCP 请求分发到对应的服务层方法\n- **响应格式化**：将服务层结果转换为 MCP 协议格式\n- **错误处理**：统一异常捕获和错误响应\n\n### MCP 工具列表\n\n| 工具名称 | 功能描述 | 参数 |\n|---------|---------|------|\n| `memory-store` | 存储新记忆，自动生成嵌入向量 | content, tags, memory_type, metadata |\n| `memory-recall` | 基于语义相似度检索记忆 | query, limit, tags, time_range |\n| `memory-search` | 标签和内容关键词搜索 | query, tags, memory_type |\n| `memory-list` | 列出所有记忆，支持分页 | limit, offset, tags |\n| `memory-delete` | 删除指定记忆 | content_hash |\n| `memory-update` | 更新记忆内容和标签 | content_hash, content, tags |\n\n---\n\n## 服务层架构\n\n### Memory Service\n\nMemory Service 是系统的核心业务逻辑层，负责处理所有与记忆相关的操作。该服务封装了存储、检索、更新和删除的完整流程，并与嵌入服务紧密协作实现语义搜索功能。\n\n**主要职责**：\n\n1. **记忆存储**：接收原始内容，调用嵌入服务生成向量，存储到 SQLite-Vec\n2. **语义搜索**：将查询文本转换为向量，执行相似度搜索\n3. **标签管理**：维护和索引记忆标签，支持多标签过滤\n4. **类型分类**：支持 24 种标准化的记忆类型分类体系\n5. **元数据管理**：处理机器标识、时间戳、自定义元数据\n\n**存储流程**：\n\n```mermaid\ngraph LR\n A[用户输入] --> B[内容验证]\n B --> C[生成 SHA256 Hash]\n C --> D{检查重复}\n D -->|已存在| E[返回现有记录]\n D -->|新内容| F[Embedding 生成]\n F --> G[向量存储]\n G --> H[元数据存储]\n H --> I[(SQLite-Vec)]\n I --> J[发送 SSE 事件]\n```\n\n### Graph Service\n\nGraph Service 负责构建和维护记忆之间的关系图谱。该服务基于 SQLite-Vec 的图扩展实现，支持复杂的关系查询和推理。\n\n**核心能力**：\n\n- **关系建模**：定义记忆间的多种关系类型\n- **关系推理**：自动推断和补全关系\n- **图遍历**：支持深度优先和广度优先遍历\n- **关系查询**：基于关系路径的复杂查询\n\n### Embedding Service\n\n嵌入服务负责将文本内容转换为高维向量表示，支持多种嵌入模型：\n\n| 配置项 | 默认值 | 说明 |\n|-------|-------|------|\n| `EMBEDDING_MODEL` | `nomic-embed-text` | 嵌入模型名称 |\n| `EMBEDDING_DIMENSIONS` | `768` | 向量维度 |\n| `EMBEDDING_API_URL` | - | 自定义嵌入 API 端点 |\n\n---\n\n## 存储层设计\n\n### SQLite-Vec 数据库架构\n\n系统使用 SQLite-Vec 作为主要存储引擎，结合了传统关系型数据库的可靠性和向量搜索的能力。\n\n**数据库结构**：\n\n| 表名 | 用途 | 关键字段 |\n|------|------|---------|\n| `memories` | 记忆主表 | id, content, content_hash, memory_type, created_at, updated_at |\n| `tags` | 标签表 | id, tag_name, memory_id |\n| `embeddings` | 向量表 | id, memory_id, vector, model |\n| `graph_edges` | 关系边表 | id, from_id, to_id, relationship_type, properties |\n| `metadata` | 元数据表 | id, memory_id, key, value |\n\n**性能特性**：\n\n- **向量索引**：支持 HNSW 和 IVF 索引类型\n- **事务支持**：完整的 ACID 事务保证\n- **并发访问**：支持多进程并发读写\n- **备份恢复**：内置备份机制，支持时间点恢复\n\n### 数据目录结构\n\n```\n~/.local/share/mcp-memory/\n├── sqlite_vec.db # 主数据库\n├── sqlite_vec.db.backup-* # 自动备份\n└── logs/ # 日志目录\n```\n\n---\n\n## API 层架构\n\n### Web API 设计\n\nWeb API 基于 FastAPI 框架构建，提供完整的 RESTful 接口和交互式文档。\n\n**API 端点概览**：\n\n| 类别 | 端点 | 方法 | 功能 |\n|------|------|------|------|\n| 记忆管理 | `/api/memories` | POST | 存储新记忆 |\n| | `/api/memories` | GET | 列出所有记忆 |\n| | `/api/memories/{hash}` | GET | 获取指定记忆 |\n| | `/api/memories/{hash}` | DELETE | 删除记忆 |\n| 搜索操作 | `/api/search` | POST | 语义搜索 |\n| | `/api/search/similar/{hash}` | GET | 查找相似记忆 |\n| 实时事件 | `/api/events` | GET | SSE 事件流 |\n| | `/api/events/stats` | GET | 连接统计 |\n| 系统状态 | `/api/health` | GET | 健康检查 |\n\n### 响应大小限制\n\n系统内置响应限制器防止上下文窗口溢出：\n\n```python\n# 环境变量配置\nMCP_MAX_RESPONSE_CHARS=0 # 0 = 无限制\n```\n\n限制器功能包括：\n- 按记忆边界截断\n- 返回截断元数据（总数、已显示数、字符数）\n- 支持格式化截断响应\n\n---\n\n## 同步层设计\n\n### Litestream 跨机器同步\n\n系统支持通过 Litestream 实现数据库的持续复制和跨机器同步，确保多设备间的数据一致性。\n\n**同步架构**：\n\n```mermaid\ngraph LR\n A[主设备] -->|写入| B[(本地 SQLite)]\n A -->|Litestream| C[(S3 存储桶)]\n D[从设备] -->|Litestream| C\n D -->|读取| E[(本地 SQLite)]\n```\n\n**配置文件路径**：`src/mcp_memory_service/sync/litestream_config.py`\n\n**支持平台**：\n\n| 平台 | 安装方式 |\n|------|---------|\n| macOS | `brew install benbjohnson/litestream/litestream` |\n| Linux | `curl -LsS ... \\| tar -xzf -` |\n| Windows | 手动下载二进制文件 |\n\n### 导入导出机制\n\n系统提供完整的 JSON 导入导出功能，支持批量数据迁移和跨实例同步：\n\n```json\n{\n \"export_metadata\": {\n \"source_machine\": \"machine-name\",\n \"export_timestamp\": \"2025-08-12T10:30:00Z\",\n \"total_memories\": 450,\n \"database_path\": \"/path/to/sqlite_vec.db\",\n \"platform\": \"Windows\"\n },\n \"memories\": [...]\n}\n```\n\n**性能指标**：\n- 导出速度：约 1000 条记忆/秒\n- 导入速度：约 500 条记忆/秒（含去重）\n- 平均大小：约 1KB/条记忆\n\n---\n\n## 客户端集成\n\n### Claude Code 钩子集成\n\n系统提供 Claude Code 集成钩子，实现自动记忆加载和会话上下文管理：\n\n**钩子组件**：\n\n| 钩子 | 版本 | 触发时机 |\n|------|------|---------|\n| `session-start.js` | v2.2 | 会话启动时 |\n| `session-end.js` | - | 会话结束时 |\n| `memory-retrieval.js` | - | 记忆检索请求 |\n| `permission-request.js` | v1.0 | 权限请求时（全局生效） |\n\n### CLI 命令\n\n| 命令 | 功能 | 示例 |\n|------|------|------|\n| `memory server` | 启动 MCP 服务器 | `memory server --debug` |\n| `memory recall` | 语义检索记忆 | `memory recall \"架构决策\"` |\n| `memory search` | 搜索记忆 | `memory search --tags \"note\"` |\n| `memory store` | 存储记忆 | `memory store \"新内容\" --tags \"note\"` |\n| `memory health` | 健康检查 | `memory health --detailed` |\n| `memory logs` | 查看日志 | `memory logs --lines 50` |\n\n---\n\n## 安全与配置\n\n### 认证机制\n\n系统支持可选的 API Key 认证：\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"your-api-key\"\n }\n}\n```\n\n### 环境变量配置\n\n| 变量名 | 默认值 | 说明 |\n|-------|-------|------|\n| `MCP_SERVER_HOST` | `0.0.0.0` | 服务监听地址 |\n| `MCP_SERVER_PORT` | `8443` | 服务监听端口 |\n| `MCP_API_KEY` | - | API 认证密钥 |\n| `MCP_DATA_DIR` | `~/.local/share/mcp-memory/` | 数据目录 |\n| `EMBEDDING_MODEL` | `nomic-embed-text` | 嵌入模型 |\n| `EMBEDDING_DIMENSIONS` | `768` | 向量维度 |\n| `MCP_MAX_RESPONSE_CHARS` | `0` | 最大响应字符数 |\n\n---\n\n## 维护工具\n\n### 维护脚本概览\n\n| 脚本 | 用途 | 关键功能 |\n|------|------|---------|\n| `consolidate_memory_types.py` | 类型归并 | 将碎片化类型合并为 24 种标准类型 |\n| `cleanup_memories.py` | 记忆清理 | 清理孤立记忆和过期数据 |\n| `find_duplicates.py` | 去重检测 | 查找并移除重复记忆 |\n| `repair_memories.py` | 数据修复 | 修复损坏的记忆条目 |\n| `repair_sqlite_vec_embeddings.py` | 向量修复 | 修复嵌入不一致问题 |\n| `migrate_embeddings.py` | 模型迁移 | 迁移到不同的嵌入模型 |\n\n### 类型归并功能\n\n支持将多个相似类型归并为标准类型：\n\n```json\n{\n \"mappings\": {\n \"bug-fix\": \"fix\",\n \"technical-solution\": \"solution\",\n \"old-type-name\": \"new-type-name\"\n }\n}\n```\n\n**标准 24 种类型分类**：\n- 内容类型：`note`、`reference`、`document`、`guide`\n- 活动类型：`session`、`implementation`、`analysis`\n\n---\n\n## 总结\n\nMCP Memory Service 采用模块化分层架构，核心优势包括：\n\n1. **多协议支持**：同时提供 MCP、REST API、CLI 三种访问方式\n2. **语义搜索**：基于向量嵌入的语义相似度检索\n3. **关系图谱**：支持复杂关系建模和推理\n4. **跨设备同步**：通过 Litestream 实现多设备数据一致性\n5. **可维护性**：完善的维护工具和自动备份机制\n6. **上下文感知**：与 Claude Code 深度集成，自动加载相关记忆\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[系统架构](#architecture), [记忆整合系统](#consolidation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/storage/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/__init__.py)\n- [src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)\n- [src/mcp_memory_service/storage/sqlite_vec.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/sqlite_vec.py)\n- [src/mcp_memory_service/storage/cloudflare.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/cloudflare.py)\n- [src/mcp_memory_service/storage/hybrid.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/hybrid.py)\n- [src/mcp_memory_service/storage/milvus.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus.py)\n- [src/mcp_memory_service/storage/milvus_graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus_graph.py)\n- [docs/guides/STORAGE_BACKENDS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/STORAGE_BACKENDS.md)\n- [docs/milvus-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/milvus-backend.md)\n- [docs/cloudflare-setup.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/cloudflare-setup.md)\n \n\n# 存储后端\n\n## 概述\n\n存储后端是 MCP Memory Service 的核心组件，负责管理记忆数据的持久化存储和向量嵌入检索功能。该服务支持多种存储后端实现，允许用户根据性能需求、部署环境和成本考虑选择最适合的解决方案。\n\nMCP Memory Service 采用模块化存储架构，通过统一的抽象接口支持不同后端实现的无缝切换，同时保证数据模型和操作语义的一致性。资料来源：[src/mcp_memory_service/storage/__init__.py]()\n\n## 架构设计\n\n### 存储后端层次结构\n\n```mermaid\ngraph TD\n A[MCP Memory Service] --> B[存储抽象层]\n B --> C[工厂模式选择器]\n C --> D[SQLite Vec 后端]\n C --> E[Cloudflare 后端]\n C --> F[Milvus 后端]\n C --> G[Hybrid 混合后端]\n C --> H[Milvus Graph 后端]\n```\n\n### 核心存储接口\n\n所有存储后端必须实现统一的抽象接口，确保功能一致性和可替换性：\n\n| 接口方法 | 功能描述 | 返回类型 |\n|---------|---------|---------|\n| `store()` | 存储记忆及其向量嵌入 | str (content_hash) |\n| `retrieve()` | 根据内容哈希检索记忆 | Memory |\n| `search()` | 向量相似性搜索 | List[Memory] |\n| `delete()` | 删除指定记忆 | bool |\n| `list()` | 分页列出所有记忆 | List[Memory] |\n| `health()` | 检查存储健康状态 | HealthInfo |\n\n资料来源：[src/mcp_memory_service/storage/factory.py]()\n\n## 支持的存储后端\n\n### SQLite Vec 后端\n\nSQLite Vec 是默认且推荐的本地存储后端，适用于单机部署场景。\n\n**核心特性**：\n\n- 完全本地化部署，数据隐私保护\n- 使用 SQLite 存储结构化数据\n- 使用 sqlite-vec 扩展处理向量嵌入\n- 支持 ACID 事务保证数据一致性\n- 首次调用约 50ms（含存储初始化）\n- 后续调用约 5-10ms（连接复用）\n- 内存开销小于 10MB\n- 成本估算：每 10 用户部署约 $16.43/年（按 $0.15/1M tokens）\n\n**配置参数**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|-----|\n| `db_path` | str | ~/.local/share/mcp-memory/ | 数据库文件路径 |\n| `embedding_model` | str | BAAI/bge-m3 | 嵌入模型名称 |\n| `embedding_dim` | int | 1024 | 嵌入向量维度 |\n\n资料来源：[src/mcp_memory_service/storage/sqlite_vec.py]()\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n### Cloudflare 后端\n\nCloudflare 后端使用 Cloudflare Workers Vectorize 实现云端向量存储，适合无服务器部署场景。\n\n**核心特性**：\n\n- 完全托管的云端向量数据库\n- 无需管理服务器基础设施\n- 全球分布式低延迟访问\n- 按使用量付费的成本模型\n- 支持 HTTP/HTTPS 自动检测连接\n\n**配置要求**：\n\n| 参数 | 必需 | 说明 |\n|-----|-----|-----|\n| `CLOUDFLARE_ACCOUNT_ID` | 是 | Cloudflare 账户 ID |\n| `CLOUDFLARE_API_TOKEN` | 是 | API 访问令牌 |\n| `vectorize_index_name` | 是 | Vectorize 索引名称 |\n| `embedding_model` | 否 | 嵌入模型（默认 BAAI/bge-m3）|\n\n**适用场景**：\n\n- Serverless 架构部署\n- 需要全球化访问的项目\n- 不想维护本地基础设施的用户\n\n资料来源：[src/mcp_memory_service/storage/cloudflare.py]()\n资料来源：[docs/cloudflare-setup.md]()\n\n### Milvus 后端\n\nMilvus 是高性能的分布式向量数据库，适合大规模数据场景。\n\n**核心特性**：\n\n- 支持十亿级向量规模\n- 分布式水平扩展能力\n- 多种索引类型支持（IVF、HNSW 等）\n- 高并发查询处理\n- 支持混合标量过滤\n\n**配置参数**：\n\n| 参数 | 必需 | 说明 |\n|-----|-----|-----|\n| `MILVUS_HOST` | 是 | Milvus 服务器地址 |\n| `MILVUS_PORT` | 是 | Milvus 端口（默认 19530） |\n| `MILVUS_USER` | 否 | 用户名 |\n| `MILVUS_PASSWORD` | 否 | 密码 |\n| `COLLECTION_NAME` | 否 | 集合名称（默认 memories）|\n| `INDEX_TYPE` | 否 | 索引类型（默认 HNSW）|\n\n资料来源：[src/mcp_memory_service/storage/milvus.py]()\n资料来源：[docs/milvus-backend.md]()\n\n### Milvus Graph 后端\n\nMilvus Graph 是 Milvus 后端的增强版本，集成了图数据库能力，提供关系型记忆检索。\n\n**扩展功能**：\n\n- 记忆间关系图的存储和查询\n- 支持复杂的多跳关系推理\n- 关系类型推断引擎\n- 路径查询支持\n\n资料来源：[src/mcp_memory_service/storage/milvus_graph.py]()\n\n### Hybrid 混合后端\n\nHybrid 后端支持同时使用多个存储后端，实现数据冗余和负载分发。\n\n**架构特点**：\n\n```mermaid\ngraph LR\n A[写入请求] --> B[主存储]\n A --> C[备份存储]\n B --> D[向量数据]\n C --> D\n E[读取请求] --> F[负载均衡]\n F --> B\n F --> C\n```\n\n**优势**：\n\n- 数据冗余备份，提高可靠性\n- 读写分离提升性能\n- 支持渐进式迁移\n- 故障自动切换\n\n资料来源：[src/mcp_memory_service/storage/hybrid.py]()\n\n## 工厂模式与后端选择\n\n### 存储工厂\n\n存储工厂根据配置自动实例化相应的存储后端：\n\n```python\n# 后端选择逻辑伪代码\ndef create_storage(backend_type: str, config: dict) -> BaseStorage:\n backends = {\n \"sqlite_vec\": SQLiteVecStorage,\n \"cloudflare\": CloudflareStorage,\n \"milvus\": MilvusStorage,\n \"milvus_graph\": MilvusGraphStorage,\n \"hybrid\": HybridStorage,\n }\n return backends.get(backend_type)(config)\n```\n\n资料来源：[src/mcp_memory_service/storage/factory.py]()\n\n### 环境变量配置\n\n后端选择通过环境变量控制：\n\n| 环境变量 | 可选值 | 说明 |\n|---------|-------|-----|\n| `MCP_MEMORY_BACKEND` | sqlite_vec, cloudflare, milvus, hybrid | 指定存储后端类型 |\n| `STORAGE_URL` | 数据库连接 URL | 各后端特定配置 |\n\n### 后端选择决策树\n\n```mermaid\ngraph TD\n A[选择存储后端] --> B{部署环境?}\n B -->|本地/单机| C[SQLite Vec]\n B -->|Serverless| D[Cloudflare]\n B -->|大规模/分布式| E[Milvus]\n B -->|需要图关系| F[Milvus Graph]\n B -->|高可用需求| G[Hybrid]\n C --> H[默认推荐]\n D --> I[低成本起步]\n E --> J[高性能扩展]\n F --> K[关系推理]\n G --> L[容错备份]\n```\n\n## 数据模型\n\n### 记忆数据结构\n\n所有存储后端使用统一的数据模型：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `content` | str | 记忆内容 |\n| `content_hash` | str | SHA256 内容哈希 |\n| `tags` | List[str] | 标签列表 |\n| `memory_type` | str | 记忆类型 |\n| `created_at` | float | 创建时间戳 |\n| `updated_at` | float | 更新时间戳 |\n| `metadata` | dict | 额外元数据 |\n| `embedding` | List[float] | 向量嵌入（后端存储）|\n\n### 记忆类型分类\n\n系统支持标准化的 24 类记忆类型：\n\n**内容类型**：`note`、`reference`、`document`、`guide`\n\n**活动类型**：`session`、`implementation`、`analysis`\n\n**其他分类**：`fix`、`solution`、`decision` 等\n\n资料来源：[scripts/maintenance/README.md]()\n\n## 向量嵌入\n\n### 嵌入模型\n\n默认使用 BAAI/bge-m3 模型：\n\n| 模型 | 维度 | 说明 |\n|-----|------|-----|\n| BAAI/bge-m3 | 1024 | 默认模型，多语言支持 |\n| 其他兼容模型 | 可配置 | 支持自定义模型 |\n\n### 嵌入维度迁移\n\n系统提供嵌入模型迁移脚本：\n\n```bash\npython maintenance/migrate_embeddings.py --url --model --dry-run\n```\n\n功能特性：\n\n- 支持维度变更\n- 干运行模式预览\n- 批量更新处理\n- 回滚支持\n\n资料来源：[scripts/README.md]()\n\n## 数据库迁移\n\n### Litestream 实时复制\n\n支持使用 Litestream 进行数据库实时复制和灾难恢复：\n\n**支持的平台**：\n\n| 平台 | 安装方式 |\n|-----|---------|\n| macOS | `brew install benbjohnson/litestream/litestream` |\n| Linux | `curl -LsS ... \\| tar -xzf -` |\n| Windows | 手动下载安装 |\n\n**配置示例**（macOS plist）：\n\n```xml\n\n ProgramArguments\n \n /usr/local/bin/litestream\n replicate\n -config\n {config_path}\n \n RunAtLoad\n \n KeepAlive\n \n\n```\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py]()\n\n## 维护工具\n\n### 记忆类型规范化\n\n`consolidate_memory_types.py` 脚本用于合并碎片化的记忆类型：\n\n```bash\n# 预览更改（只读）\npython scripts/maintenance/consolidate_memory_types.py --dry-run\n\n# 执行合并\npython scripts/maintenance/consolidate_memory_types.py\n\n# 使用自定义配置\npython scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json\n```\n\n**性能指标**：\n\n- 1,000 条记忆更新约 5 秒\n- 自动创建带时间戳的备份\n- 事务安全（原子操作，失败回滚）\n\n**安全特性**：\n\n- 自动备份机制\n- 干运行模式预览\n- 数据库锁检测\n- 磁盘空间验证\n- 备份完整性检查\n\n资料来源：[scripts/maintenance/README.md]()\n\n### 修复和维护脚本\n\n| 脚本 | 功能 |\n|-----|------|\n| `repair_memories.py` | 修复损坏的记忆条目 |\n| `repair_sqlite_vec_embeddings.py` | 修复嵌入不一致问题 |\n| `repair_zero_embeddings.py` | 修复零值/空值嵌入 |\n| `cleanup_corrupted_encoding.py` | 修复损坏的 Emoji 编码 |\n| `find_duplicates.py` | 查找并删除重复记忆 |\n\n资料来源：[scripts/README.md]()\n\n## 性能比较\n\n| 后端 | 首次调用 | 后续调用 | 内存开销 | 扩展性 |\n|-----|---------|---------|---------|-------|\n| SQLite Vec | ~50ms | ~5-10ms | <10MB | 单机 |\n| Cloudflare | 可变 | 可变 | 无 | 全球分布 |\n| Milvus | ~20ms | ~5ms | 可配置 | 分布式 |\n| Hybrid | 组合 | 组合 | 组合 | 高可用 |\n\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n## 配置示例\n\n### SQLite Vec 配置\n\n```json\n{\n \"backend\": \"sqlite_vec\",\n \"db_path\": \"~/.local/share/mcp-memory/\",\n \"embedding_model\": \"BAAI/bge-m3\",\n \"embedding_dim\": 1024\n}\n```\n\n### Cloudflare 配置\n\n```json\n{\n \"backend\": \"cloudflare\",\n \"CLOUDFLARE_ACCOUNT_ID\": \"your-account-id\",\n \"CLOUDFLARE_API_TOKEN\": \"your-api-token\",\n \"vectorize_index_name\": \"memories-index\",\n \"embedding_model\": \"BAAI/bge-m3\"\n}\n```\n\n### Milvus 配置\n\n```json\n{\n \"backend\": \"milvus\",\n \"MILVUS_HOST\": \"localhost\",\n \"MILVUS_PORT\": 19530,\n \"MILVUS_USER\": \"username\",\n \"MILVUS_PASSWORD\": \"password\",\n \"COLLECTION_NAME\": \"memories\",\n \"INDEX_TYPE\": \"HNSW\"\n}\n```\n\n## 扩展阅读\n\n- [存储后端完整指南](docs/guides/STORAGE_BACKENDS.md)\n- [Milvus 后端配置](docs/milvus-backend.md)\n- [Cloudflare 设置指南](docs/cloudflare-setup.md)\n- [数据库维护脚本](scripts/README.md)\n\n---\n\n\n\n## 知识图谱\n\n### 相关页面\n\n相关主题：[记忆整合系统](#consolidation), [系统架构](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/storage/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)\n- [src/mcp_memory_service/models/association.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/association.py)\n- [src/mcp_memory_service/reasoning/entities.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)\n- [src/mcp_memory_service/reasoning/inference.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/inference.py)\n- [src/mcp_memory_service/consolidation/relationship_inference.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/relationship_inference.py)\n- [src/mcp_memory_service/consolidation/associations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/associations.py)\n- [src/mcp_memory_service/server/handlers/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n- [docs/wiki-Graph-Database-Architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/wiki-Graph-Database-Architecture.md)\n- [docs/migrations/010-asymmetric-relationships.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/migrations/010-asymmetric-relationships.md)\n \n\n# 知识图谱\n\n## 概述\n\nMCP Memory Service 的知识图谱模块是系统的核心组件之一，负责管理和维护记忆之间的语义关系。与传统的关系型存储不同，知识图谱通过节点（记忆）和边（关联）的方式组织数据，使得复杂的关联查询和推理成为可能。\n\n知识图谱系统的主要目标包括：\n\n- **语义关联**：自动发现并建立记忆之间的语义关联\n- **关系推理**：基于现有关系推断新的潜在关联\n- **图查询**：支持基于图结构的复杂查询操作\n- **上下文增强**：为 AI 推理提供丰富的上下文关系网络\n\n## 架构设计\n\n### 核心组件\n\n知识图谱系统由以下几个核心模块组成：\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 图存储层 | `src/mcp_memory_service/storage/graph.py` | 管理图数据的持久化和索引 |\n| 关联模型 | `src/mcp_memory_service/models/association.py` | 定义记忆间关联的数据结构 |\n| 实体识别 | `src/mcp_memory_service/reasoning/entities.py` | 从记忆内容中提取实体 |\n| 推理引擎 | `src/mcp_memory_service/reasoning/inference.py` | 执行关系推理和推断 |\n| 关联推断 | `src/mcp_memory_service/consolidation/relationship_inference.py` | 批量推断和优化关联 |\n| API 处理器 | `src/mcp_memory_service/server/handlers/graph.py` | 提供图查询的 HTTP 接口 |\n\n### 架构层次\n\n```mermaid\ngraph TB\n subgraph \"表现层\"\n A[Graph API Handlers]\n end\n \n subgraph \"服务层\"\n B[Relationship Inference Engine]\n C[Entity Recognition Module]\n D[Inference Processor]\n end\n \n subgraph \"存储层\"\n E[Graph Storage]\n F[Association Models]\n end\n \n A --> B\n A --> C\n B --> D\n C --> D\n D --> E\n F --> E\n \n G[(Vector Embeddings)] --> B\n G --> C\n```\n\n## 关联模型\n\n### 数据结构\n\n关联模型 (`Association`) 是知识图谱的边，连接两个记忆节点：\n\n```python\nclass Association:\n source_hash: str # 源记忆哈希\n target_hash: str # 目标记忆哈希\n relation_type: str # 关系类型\n confidence: float # 置信度 0.0-1.0\n metadata: Dict # 额外元数据\n```\n\n### 非对称关系\n\n系统支持非对称关系的建模，这是知识图谱的核心特性之一。资料来源：[docs/migrations/010-asymmetric-relationships.md]()\n\n```mermaid\ngraph LR\n A[记忆 A] -->|\"基于\"| B[记忆 B]\n B -->|\"衍生自\"| A\n```\n\n非对称关系意味着：\n- 关系方向有实际意义\n- A→B 与 B→A 表示不同的语义\n- 支持更精确的因果和依赖建模\n\n### 关系类型\n\n| 关系类型 | 描述 | 典型场景 |\n|----------|------|----------|\n| `related` | 语义相关 | 一般关联 |\n| `derived_from` | 衍生关系 | 实现源自设计 |\n| `contradicts` | 矛盾关系 | 冲突的决策 |\n| `references` | 引用关系 | 引用外部资源 |\n| `similar` | 相似关系 | 内容相似度高 |\n\n## 实体识别\n\n实体识别模块 (`entities.py`) 负责从记忆内容中提取有意义的实体：\n\n### 提取流程\n\n```mermaid\ngraph TD\n A[记忆内容] --> B[文本预处理]\n B --> C[命名实体识别]\n C --> D[实体消歧]\n D --> E[实体标准化]\n E --> F[实体图谱]\n```\n\n### 实体类型\n\n识别并支持的实体类型包括：\n\n| 实体类型 | 示例 | 用途 |\n|----------|------|------|\n| `person` | 人名 | 人员关联 |\n| `organization` | 公司/组织 | 组织归属 |\n| `technology` | 技术名称 | 技术栈关联 |\n| `concept` | 抽象概念 | 知识分类 |\n| `document` | 文档引用 | 文档关系 |\n\n资料来源：[src/mcp_memory_service/reasoning/entities.py]()\n\n## 推理引擎\n\n推理引擎是知识图谱的智能核心，基于现有关联推断新的潜在关系。\n\n### 推理方法\n\n| 方法 | 描述 | 输入 | 输出 |\n|------|------|------|------|\n| 传递推理 | A→B, B→C ⇒ A→C | 两条边 | 推断的第三条边 |\n| 相似传播 | A≈B ⇒ A的属性≈B的属性 | 相似实体 | 属性映射 |\n| 反事实推理 | A导致B ⇒ ¬B ⇒ ¬A | 因果关系 | 反向推断 |\n\n### 置信度计算\n\n```mermaid\ngraph LR\n A[关系证据] --> B{证据强度}\n B -->|强| C[高置信度 0.8-1.0]\n B -->|中| D[中置信度 0.5-0.8]\n B -->|弱| E[低置信度 0.2-0.5]\n```\n\n置信度计算考虑因素：\n\n1. **共现频率**：两个记忆在同一上下文中出现的次数\n2. **语义相似度**：基于向量的余弦相似度\n3. **关系传递路径**：推理路径的长度\n4. **来源可靠性**：记忆来源的可信度评分\n\n资料来源：[src/mcp_memory_service/reasoning/inference.py]()\n\n## 图存储\n\n### 存储架构\n\n图存储模块 (`graph.py`) 负责将图数据持久化：\n\n```mermaid\ngraph TB\n subgraph \"存储层\"\n A[(SQLite Vec)]\n B[(向量索引)]\n C[(关系统引)]\n end\n \n subgraph \"索引\"\n D[哈希索引]\n E[关系类型索引]\n F[时间索引]\n end\n \n A --> D\n A --> E\n A --> F\n B --> D\n C --> E\n```\n\n### 存储优化\n\n- **批量写入**：支持批量关联写入以提高性能\n- **增量更新**：仅更新变化的关联\n- **索引维护**：自动维护关系类型和哈希索引\n\n资料来源：[src/mcp_memory_service/storage/graph.py]()\n\n## API 接口\n\n### 图查询端点\n\n系统通过 REST API 提供图查询能力：\n\n| 端点 | 方法 | 描述 |\n|------|------|------|\n| `/api/graph/related/{hash}` | GET | 获取记忆的关联 |\n| `/api/graph/infer` | POST | 执行推理查询 |\n| `/api/graph/path` | POST | 查找两记忆间的路径 |\n\n### 请求示例\n\n```bash\n# 获取记忆的所有关联\ncurl -X GET \"http://localhost:8443/api/graph/related/abc12345\"\n\n# 执行推理查询\ncurl -X POST \"http://localhost:8443/api/graph/infer\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"source_hash\": \"abc123\", \"depth\": 2}'\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py]()\n\n## 关联推断系统\n\n### 批量推断流程\n\n关联推断模块 (`relationship_inference.py`) 提供批量关联优化功能：\n\n```mermaid\ngraph TD\n A[加载现有关联] --> B[分析关联质量]\n B --> C{质量评估}\n C -->|低| D[标记待优化]\n C -->|高| E[保留]\n D --> F[执行推断]\n F --> G[验证推断结果]\n G --> H[更新关联数据]\n H --> I[生成报告]\n```\n\n### 优化策略\n\n| 策略 | 触发条件 | 优化动作 |\n|------|----------|----------|\n| 合并重复 | 多个相同关系 | 去重合并 |\n| 提升置信度 | 多次验证 | 增加置信度 |\n| 清理孤立 | 无关联记忆 | 移除或标记 |\n| 类型标准化 | 非标准类型 | 映射到标准类型 |\n\n### 执行命令\n\n```bash\n# 预览优化效果（不执行）\npython scripts/maintenance/update_graph_relationship_types.py --dry-run\n\n# 执行优化\npython scripts/maintenance/update_graph_relationship_types.py\n```\n\n资料来源：[src/mcp_memory_service/consolidation/relationship_inference.py]()\n\n## 关联管理\n\n### 关联生命周期\n\n```mermaid\ngraph LR\n A[创建] --> B[验证]\n B --> C[索引]\n C --> D[使用]\n D --> E{评估}\n E -->|需要更新| F[更新]\n E -->|不再有效| G[归档/删除]\n F --> D\n```\n\n### 关联类型管理\n\n关联类型标准化通过 `associations.py` 模块实现：\n\n```json\n{\n \"关系映射\": {\n \"bug-fix\": \"fix\",\n \"technical-solution\": \"solution\",\n \"implementation\": \"implement\"\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/consolidation/associations.py]()\n\n## 与向量存储的集成\n\n知识图谱与向量存储紧密集成，形成混合检索系统：\n\n### 双索引架构\n\n```mermaid\ngraph TB\n subgraph \"输入层\"\n A[记忆内容]\n end\n \n subgraph \"处理\"\n A --> B[生成向量]\n A --> C[提取实体]\n C --> D[识别关系]\n end\n \n subgraph \"存储\"\n B --> E[(向量索引)]\n D --> F[(图索引)]\n end\n \n subgraph \"查询\"\n G[语义查询] --> E\n H[关系查询] --> F\n end\n```\n\n### 协同检索\n\n| 场景 | 向量检索 | 图检索 | 合并策略 |\n|------|----------|--------|----------|\n| 相似内容 | ✓ 主导 | 补充 | 加权合并 |\n| 因果追溯 | ✓ 补充 | 主导 | 图优先 |\n| 推荐发现 | ✓ 主导 | 主导 | 交叉验证 |\n\n## 性能特性\n\n### 性能指标\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 单次关联写入 | ~5ms | 含索引更新 |\n| 关联查询 (一级) | ~10ms | 直接邻居 |\n| 路径查询 (深度2) | ~50ms | 含推理 |\n| 批量推断 (1000条) | ~5秒 | 完整优化 |\n\n### 扩展性\n\n- 支持 **sqlite-vec** 作为本地向量存储后端\n- 支持 **Cloudflare D1 + Vectorize** 作为云端后端\n- 支持 **混合模式** 部署\n\n## 维护工具\n\n### 可用脚本\n\n| 脚本 | 功能 | 位置 |\n|------|------|------|\n| `update_graph_relationship_types.py` | 推断和优化关联类型 | `scripts/maintenance/` |\n| `repair_sqlite_vec_embeddings.py` | 修复嵌入问题 | `scripts/maintenance/` |\n| `repair_zero_embeddings.py` | 修复零嵌入 | `scripts/maintenance/` |\n\n### 维护建议\n\n1. **定期运行推断优化**：每月执行一次关联质量检查\n2. **监控孤立节点**：清理无关联的记忆以保持图质量\n3. **验证索引一致性**：确保向量索引与图索引同步\n\n## 最佳实践\n\n### 记忆组织\n\n1. **使用标准类型**：选择预定义的关系类型而非自定义\n2. **保持原子性**：每条记忆聚焦单一主题，便于关系建立\n3. **添加上下文标签**：使用标签辅助关系推断\n\n### 查询优化\n\n1. **指定深度限制**：避免过深的图遍历\n2. **使用类型过滤**：按关系类型筛选以提高性能\n3. **缓存常用查询**：对于频繁访问的图结构使用缓存\n\n## 总结\n\nMCP Memory Service 的知识图谱模块通过实体识别、关系推理和图存储的协同工作，为系统提供了强大的语义关联能力。它不仅支持传统的向量相似度检索，还能通过图结构发现更深层次的关联关系，为 AI 助手提供更丰富的上下文理解能力。\n\n通过持续优化的关联推断系统和维护工具，系统能够自动保持图谱的质量和相关性，确保长期使用的有效性。\n\n---\n\n\n\n## 记忆整合系统\n\n### 相关页面\n\n相关主题：[知识图谱](#knowledge-graph), [质量评分系统](#quality-scoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/consolidation/consolidator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n- [src/mcp_memory_service/consolidation/scheduler.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/scheduler.py)\n- [src/mcp_memory_service/consolidation/compression.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/compression.py)\n- [src/mcp_memory_service/consolidation/decay.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/decay.py)\n- [src/mcp_memory_service/consolidation/forgetting.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/forgetting.py)\n- [src/mcp_memory_service/consolidation/health.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/health.py)\n- [src/mcp_memory_service/consolidation/insights.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/insights.py)\n- [src/mcp_memory_service/consolidation/clustering.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/clustering.py)\n- [src/mcp_memory_service/server/handlers/consolidation.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/consolidation.py)\n- [docs/guides/memory-consolidation-guide.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/memory-consolidation-guide.md)\n \n\n# 记忆整合系统\n\n## 概述\n\n记忆整合系统（Memory Consolidation System）是 MCP Memory Service 的核心组件之一，负责对存储的语义记忆进行周期性优化、压缩和遗忘处理。该系统通过自动化调度机制，在不影响服务正常运行的情况下，对数据库中的记忆进行智能管理和维护。\n\n记忆整合系统的设计目标包括：\n\n- **记忆压缩**：将相似或冗余的记忆内容进行合并，减少存储空间\n- **记忆衰减**：根据时间因素和访问频率调整记忆的重要性评分\n- **选择性遗忘**：自动移除不再需要的低价值记忆，保持数据库健康\n- **洞察生成**：从记忆数据中提取有价值的分析信息\n- **集群管理**：对记忆进行语义聚类，优化检索效率\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:1-50]()\n\n## 系统架构\n\n记忆整合系统采用模块化设计，各子模块协同工作完成不同的整合任务。\n\n```mermaid\ngraph TD\n subgraph 记忆整合系统\n A[触发器/调度器] --> B[整合器]\n B --> C[压缩模块]\n B --> D[衰减模块]\n B --> E[遗忘模块]\n B --> F[健康检查模块]\n B --> G[洞察生成模块]\n B --> H[聚类模块]\n end\n \n I[SQLite数据库] <--> B\n J[MCP服务器] --> A\n K[HTTP API] --> A\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 整合器 | `consolidation/consolidator.py` | 协调各模块执行，负责整体流程控制 |\n| 调度器 | `consolidation/scheduler.py` | 管理定时任务，支持日/周/月三种时间粒度 |\n| 压缩模块 | `consolidation/compression.py` | 识别相似记忆并进行合并 |\n| 衰减模块 | `consolidation/decay.py` | 实现记忆重要性随时间的衰减计算 |\n| 遗忘模块 | `consolidation/forgetting.py` | 根据策略删除低价值记忆 |\n| 健康检查 | `consolidation/health.py` | 监控数据库状态和整合效果 |\n| 洞察生成 | `consolidation/insights.py` | 提取记忆中的统计和分析信息 |\n| 聚类模块 | `consolidation/clustering.py` | 对记忆进行语义聚类优化 |\n\n资料来源：[src/mcp_memory_service/consolidation/scheduler.py:1-30]()\n\n## 时间视野策略\n\n系统支持三种不同时间粒度的整合策略，适用于不同类型的记忆管理需求。\n\n| 时间视野 | 适用场景 | 典型保留周期 |\n|----------|----------|--------------|\n| 日整合 (daily) | 近期工作记忆、临时笔记 | 最近 7-30 天 |\n| 周整合 (weekly) | 项目进度、会议决策 | 最近 1-6 个月 |\n| 月整合 (monthly) | 长期知识沉淀、架构决策 | 6 个月以上 |\n\n每种时间视野对应不同的压缩率和遗忘阈值，确保短期记忆保留完整性的同时，长期记忆不会被无限积累。\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:50-100]()\n\n## 整合执行流程\n\n```mermaid\ngraph LR\n A[开始整合] --> B{健康检查}\n B -->|通过| C[执行压缩]\n B -->|失败| Z[终止整合]\n C --> D[执行衰减]\n D --> E[执行遗忘]\n E --> F[更新聚类]\n F --> G[生成洞察]\n G --> H[记录统计]\n H --> I[完成整合]\n```\n\n### 各阶段详细说明\n\n#### 1. 健康检查阶段\n\n在执行任何修改操作前，系统首先进行数据库健康状态检查，包括：\n\n- 数据库连接可用性验证\n- 磁盘空间检查（需要至少 2 倍数据库大小的空间）\n- 现有任务冲突检测\n- 数据库锁状态确认\n\n资料来源：[src/mcp_memory_service/consolidation/health.py:1-50]()\n\n#### 2. 压缩阶段\n\n压缩模块负责识别和合并语义相似的记忆内容：\n\n- 计算记忆间的相似度评分\n- 对超过相似度阈值的记忆进行合并\n- 保留最早的创建时间戳\n- 合并标签集和元数据\n\n资料来源：[src/mcp_memory_service/consolidation/compression.py:1-60]()\n\n#### 3. 衰减阶段\n\n衰减模块根据时间因素调整记忆的重要性评分：\n\n- 基础衰减率按时间视野配置\n- 访问频率作为衰减调整因子\n- 重要性评分影响后续遗忘决策\n\n```python\n# 衰减计算公式示例\n衰减因子 = base_decay_rate × (1 - access_frequency_weight)\n新评分 = 原始评分 × 衰减因子\n```\n\n资料来源：[src/mcp_memory_service/consolidation/decay.py:1-45]()\n\n#### 4. 遗忘阶段\n\n遗忘模块根据评分阈值决定应删除的记忆：\n\n- 低于遗忘阈值的记忆被标记为待删除\n- 保护期内的记忆不会被删除\n- 系统记忆和重要标记的记忆受特殊保护\n\n资料来源：[src/mcp_memory_service/consolidation/forgetting.py:1-50]()\n\n#### 5. 聚类更新阶段\n\n聚类模块对现有记忆进行语义分组：\n\n- 基于嵌入向量的相似性计算\n- 更新记忆的聚类标签\n- 优化向量检索效率\n\n资料来源：[src/mcp_memory_service/consolidation/clustering.py:1-40]()\n\n#### 6. 洞察生成阶段\n\n洞察模块从整合过程中提取分析数据：\n\n- 整合统计（处理记忆数、压缩数、遗忘数）\n- 记忆类型分布分析\n- 时间趋势报告\n- 健康状态摘要\n\n资料来源：[src/mcp_memory_service/consolidation/insights.py:1-50]()\n\n## API 接口\n\n系统提供 HTTP API 接口用于触发和管理整合操作。\n\n### 触发整合\n\n```\nPOST /api/consolidate\n```\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| time_horizon | string | 否 | 时间视野：`daily`、`weekly`、`monthly`，默认 `weekly` |\n\n**响应示例：**\n\n```json\n{\n \"status\": \"completed\",\n \"time_horizon\": \"weekly\",\n \"processed\": 2418,\n \"compressed\": 156,\n \"forgotten\": 43,\n \"duration_seconds\": 18.5\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/consolidation.py:1-80]()\n\n### 查询调度器状态\n\n```\nGET /api/consolidate/status\n```\n\n**响应示例：**\n\n```json\n{\n \"running\": true,\n \"next_daily\": \"2025-01-08T03:00:00Z\",\n \"next_weekly\": \"2025-01-12T03:00:00Z\",\n \"next_monthly\": \"2025-02-01T03:00:00Z\",\n \"jobs_executed\": 156,\n \"jobs_failed\": 2\n}\n```\n\n资料来源：[src/mcp_memory_service/api/operations.py:100-150]()\n\n## Python API\n\n除 HTTP API 外，系统还提供 Python API 供直接调用。\n\n### 异步接口\n\n```python\nfrom mcp_memory_service.api import consolidate\n\n# 执行周整合\nresult = await consolidate('weekly')\nprint(f\"压缩: {result.compressed}, 遗忘: {result.forgotten}\")\n```\n\n### 同步接口\n\n```python\nfrom mcp_memory_service.api import consolidate\n\n# 同步调用\nresult = consolidate('monthly')\nprint(f\"状态: {result.status}\")\n```\n\n**性能指标：**\n\n- 典型执行时长：10-30 秒（取决于记忆数量）\n- 线性扩展：约 10ms/记忆\n- 后台执行，非阻塞操作\n\n资料来源：[src/mcp_memory_service/api/__init__.py:1-60]()\n\n## 调度配置\n\n### 调度器初始化参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| enabled | bool | true | 是否启用自动调度 |\n| daily_hour | int | 3 | 日整合执行小时（凌晨） |\n| weekly_day | int | 6 | 周整合执行日期（周六） |\n| monthly_day | int | 1 | 月整合执行日期（每月1日） |\n| timezone | string | \"UTC\" | 执行时区 |\n\n### 自定义调度\n\n调度器使用 APScheduler 作为底层调度引擎，支持：\n\n- Cron 表达式配置\n- 间隔执行模式\n- 一次性任务\n\n资料来源：[src/mcp_memory_service/consolidation/scheduler.py:60-120]()\n\n## 配置示例\n\n### 基本配置\n\n```json\n{\n \"consolidation\": {\n \"enabled\": true,\n \"time_horizon\": \"weekly\",\n \"compression_threshold\": 0.85,\n \"forgetting_threshold\": 0.3,\n \"decay_rate\": 0.95\n }\n}\n```\n\n### 激进配置（更多遗忘）\n\n```json\n{\n \"consolidation\": {\n \"enabled\": true,\n \"time_horizon\": \"monthly\",\n \"compression_threshold\": 0.75,\n \"forgetting_threshold\": 0.5,\n \"decay_rate\": 0.9\n }\n}\n```\n\n### 保守配置（更多保留）\n\n```json\n{\n \"consolidation\": {\n \"enabled\": true,\n \"time_horizon\": \"daily\",\n \"compression_threshold\": 0.95,\n \"forgetting_threshold\": 0.1,\n \"decay_rate\": 0.99\n }\n}\n```\n\n资料来源：[docs/guides/memory-consolidation-guide.md:1-80]()\n\n## 维护脚本\n\n系统提供命令行维护脚本用于手动执行整合操作。\n\n### 使用方法\n\n```bash\n# 预览整合效果（安全，不实际执行）\npython scripts/maintenance/consolidate_memories.py --dry-run\n\n# 执行周整合\npython scripts/maintenance/consolidate_memories.py\n\n# 执行月整合并指定时间视野\npython scripts/maintenance/consolidate_memories.py --time-horizon monthly\n```\n\n### 安全特性\n\n- **自动备份**：执行前自动创建带时间戳的数据库备份\n- **干运行模式**：`--dry-run` 模式仅预览不修改\n- **事务安全**：原子操作，错误时自动回滚\n- **并发检测**：检测数据库锁防止并发访问冲突\n- **磁盘空间检查**：验证是否有足够空间进行操作\n- **备份验证**：操作后验证备份文件完整性\n\n### 恢复流程\n\n如果整合操作出现问题，可从自动备份恢复：\n\n```bash\n# 停止服务\nsystemctl --user stop mcp-memory-http.service\n\n# 断开所有 MCP 客户端连接\n\n# 从备份恢复\ncp ~/.local/share/mcp-memory/sqlite_vec.db.backup-TIMESTAMP \\\n ~/.local/share/mcp-memory/sqlite_vec.db\n\n# 验证恢复\nsqlite3 ~/.local/share/mcp-memory/sqlite_vec.db \\\n \"SELECT COUNT(*), COUNT(DISTINCT memory_type) FROM memories;\"\n```\n\n资料来源：[scripts/maintenance/README.md:1-60]()\n\n## 最佳实践\n\n### 执行时机建议\n\n1. **服务空闲时执行**：建议在凌晨或低峰时段运行\n2. **停止 HTTP 服务**：执行前停止 HTTP 服务器避免并发冲突\n3. **断开 MCP 客户端**：确保没有活跃的 Claude Code 会话\n4. **监控磁盘空间**：确保有足够的存储空间进行备份和操作\n\n### 维护周期\n\n| 检查类型 | 建议频率 | 工具 |\n|----------|----------|------|\n| 干运行检查 | 每月 | `--dry-run` |\n| 执行整合 | 按配置 | 调度器或手动 |\n| 类型归一化 | 按需 | `consolidate_memory_types.py` |\n| 性能优化 | 每季度 | `cleanup_memories.py` |\n\n### 监控指标\n\n建议监控以下整合指标：\n\n- `processed`：处理的记忆总数\n- `compressed`：被压缩的记忆数\n- `forgotten`：被遗忘的记忆数\n- `duration_seconds`：执行耗时\n- `jobs_failed`：失败的任务数\n\n资料来源：[src/mcp_memory_service/consolidation/insights.py:50-100]()\n\n## 相关模块文档\n\n- [压缩模块详解](./consolidation-compression.md)\n- [遗忘算法详解](./consolidation-forgetting.md)\n- [调度器配置](./consolidation-scheduler.md)\n- [API 参考](../api/reference.md)\n\n---\n\n\n\n## 质量评分系统\n\n### 相关页面\n\n相关主题：[记忆整合系统](#consolidation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/quality/scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/scorer.py)\n- [src/mcp_memory_service/quality/onnx_ranker.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/onnx_ranker.py)\n- [src/mcp_memory_service/quality/ai_evaluator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/ai_evaluator.py)\n- [src/mcp_memory_service/quality/async_scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/async_scorer.py)\n- [src/mcp_memory_service/quality/config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/config.py)\n- [src/mcp_memory_service/quality/implicit_signals.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/implicit_signals.py)\n- [src/mcp_memory_service/embeddings/onnx_embeddings.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/embeddings/onnx_embeddings.py)\n- [docs/guides/memory-quality-guide.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/memory-quality-guide.md)\n- [docs/features/association-quality-boost.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/features/association-quality-boost.md)\n \n\n# 质量评分系统\n\n## 概述\n\n质量评分系统是 MCP Memory Service 的核心组件之一，负责对存储的语义记忆进行多维度质量评估。该系统通过静态评分、机器学习排序和隐式信号分析等多种机制，综合判断记忆内容的价值和质量等级，从而优化搜索结果的相关性排序。\n\n在 Claude Code 的会话管理中，增强的记忆过滤功能会自动移除\"implementation...\"等通用摘要内容，确保只保留高价值的洞察信息。系统支持多种配置选项，包括详细程度控制和质量评分权重调整。\n\n质量评分系统的主要目标是提高记忆检索的准确性，确保最相关和最有价值的记忆能够优先呈现给用户。系统采用分层评分架构，结合 ONNX 运行时加速和异步处理能力，在保证性能的同时提供精确的质量评估。\n\n## 系统架构\n\n质量评分系统采用模块化设计，各组件之间通过清晰的接口进行通信。核心架构包含评分引擎、ONNX 排序器、AI 评估器、异步评分器和隐式信号分析器等多个模块。\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[记忆存储] --> B[质量评分系统]\n B --> C[评分引擎 scorer.py]\n B --> D[ONNX 排序器 onnx_ranker.py]\n B --> E[AI 评估器 ai_evaluator.py]\n B --> F[异步评分器 async_scorer.py]\n B --> G[隐式信号 implicit_signals.py]\n C --> H[配置模块 config.py]\n D --> I[ONNX 运行时]\n E --> J[LLM API]\n G --> K[用户行为数据]\n H --> L[评分策略配置]\n F --> M[异步任务队列]\n M --> N[结果缓存]\n N --> O[搜索结果排序]\n```\n\n### 核心模块说明\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 评分引擎 | `quality/scorer.py` | 核心评分逻辑，整合多维度评分因子 |\n| ONNX 排序器 | `quality/onnx_ranker.py` | 使用 ONNX 加速的机器学习排序模型 |\n| AI 评估器 | `quality/ai_evaluator.py` | 基于大语言模型的质量评估 |\n| 异步评分器 | `quality/async_scorer.py` | 后台异步执行批量评分任务 |\n| 配置模块 | `quality/config.py` | 评分策略和参数配置管理 |\n| 隐式信号 | `quality/implicit_signals.py` | 从用户行为中提取质量信号 |\n| ONNX 嵌入 | `embeddings/onnx_embeddings.py` | 语义嵌入向量生成 |\n\n## 评分策略配置\n\n质量评分系统通过 `config.py` 模块提供灵活的配置选项。配置参数控制评分算法的行为、权重分配和性能调优。\n\n### 配置参数表\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `contentQuality` | float | 0.3 | 内容质量评估权重 |\n| `relevanceWeight` | float | 0.4 | 语义相关性权重 |\n| `recencyWeight` | float | 0.2 | 时间衰减因子权重 |\n| `usageWeight` | float | 0.1 | 使用频率权重 |\n| `minQualityThreshold` | float | 0.5 | 最低质量阈值 |\n\n配置示例：\n\n```python\nfrom mcp_memory_service.quality.config import QualityConfig\n\nconfig = QualityConfig(\n contentQuality=0.35,\n relevanceWeight=0.35,\n recencyWeight=0.15,\n usageWeight=0.15,\n minQualityThreshold=0.6\n)\n```\n\n## ONNX 加速排序\n\n系统使用 ONNX Runtime 加速机器学习排序模型的推理过程。相比纯 Python 实现，ONNX 排序器能够显著提升批量评分的吞吐量。\n\n### ONNX 排序器工作流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Scorer as 评分引擎\n participant ONNX as ONNX排序器\n participant Cache as 结果缓存\n \n Client->>Scorer: 提交评分请求\n Scorer->>ONNX: 请求批量排序\n ONNX->>ONNX: 模型推理\n ONNX-->>Scorer: 排序分数\n Scorer->>Cache: 缓存结果\n Scorer-->>Client: 返回评分结果\n```\n\nONNX 嵌入模块负责将文本内容转换为高维向量表示，用于后续的语义相似度计算和质量评估。嵌入向量结合了语义信息和上下文关系，为评分引擎提供丰富的特征输入。\n\n## 异步评分机制\n\n对于批量评分任务，系统采用异步处理架构以避免阻塞主线程。异步评分器支持任务队列管理、并发控制和结果回调。\n\n### 异步评分特性\n\n异步评分器提供以下核心功能：\n\n1. **任务批量处理**：将多个评分请求合并为单一批处理任务，减少模型调用开销\n2. **优先级队列**：支持按优先级排序的评分任务调度\n3. **结果回调**：评分完成后自动触发预设的回调函数\n4. **错误重试**：网络或服务异常时自动重试失败任务\n\n```python\nfrom mcp_memory_service.quality.async_scorer import AsyncScorer\n\nasync_scorer = AsyncScorer(max_concurrent=4)\n\n# 提交异步评分任务\ntask_id = await async_scorer.submit_batch(\n memory_ids=[\"hash1\", \"hash2\", \"hash3\"],\n callback=on_score_complete\n)\n```\n\n## 隐式信号分析\n\n隐式信号分析器从用户行为数据中提取质量相关的反馈信号，无需显式评分即可评估记忆的价值。\n\n### 信号类型表\n\n| 信号类型 | 数据来源 | 权重 | 说明 |\n|----------|----------|------|------|\n| 检索频率 | 搜索日志 | 0.25 | 记忆被检索的次数 |\n| 引用次数 | 对话记录 | 0.30 | 记忆中内容被引用的次数 |\n| 停留时长 | 会话数据 | 0.20 | 用户查看记忆的平均时长 |\n| 修改频率 | 版本历史 | 0.15 | 记忆被修改的频率 |\n| 关联强度 | 链接关系 | 0.10 | 与其他高价值记忆的关联数 |\n\n隐式信号分析器持续监控用户与记忆的交互模式，通过机器学习算法识别高价值内容。系统会根据累积的信号数据动态调整评分模型的参数。\n\n## AI 评估器\n\nAI 评估器利用大语言模型的能力对记忆内容进行深度质量分析。该模块能够理解语义上下文，评估内容的完整性、清晰度和实用价值。\n\n### 评估维度\n\n| 维度 | 描述 | 分数范围 |\n|------|------|----------|\n| 内容完整性 | 记忆是否包含足够的上下文信息 | 0-1 |\n| 语义清晰度 | 表述是否清晰、无歧义 | 0-1 |\n| 实用价值 | 对未来参考的潜在价值 | 0-1 |\n| 时效性 | 内容是否需要更新 | 0-1 |\n| 唯一性 | 与现有记忆的重复程度 | 0-1 |\n\nAI 评估器支持流式输出模式，能够在评估过程中逐步返回中间结果，便于实时显示评估进度。\n\n## 关联质量提升\n\n质量评分系统与关联记忆机制紧密集成。通过分析记忆之间的语义关联，系统能够识别和提升高价值内容的显示优先级。\n\n关联质量提升特性包括：\n\n- **语义聚类**：将相关内容自动分组\n- **关联强度评分**：计算记忆间的关联紧密度\n- **质量传播**：高评分记忆的关联项获得适度加分\n- **去重推荐**：避免重复或高度相似的内容重复出现\n\n该机制确保搜索结果不仅在语义上相关，而且在质量和独特性上也能满足用户需求。系统在处理关联查询时会综合考虑直接匹配度和关联记忆的质量表现。\n\n## 集成指南\n\n### 基础集成\n\n在应用中使用质量评分系统：\n\n```python\nfrom mcp_memory_service.quality.scorer import QualityScorer\nfrom mcp_memory_service.quality.config import QualityConfig\n\n# 初始化配置和评分器\nconfig = QualityConfig()\nscorer = QualityScorer(config)\n\n# 对单条记忆评分\nmemory_id = \"abc12345\"\nscore = await scorer.score_memory(memory_id)\nprint(f\"记忆质量分数: {score.overall:.2f}\")\n```\n\n### 批量评分集成\n\n```python\nfrom mcp_memory_service.quality.async_scorer import AsyncScorer\n\nasync_scorer = AsyncScorer(max_concurrent=10)\n\n# 定义回调函数\ndef on_complete(task_id, results):\n print(f\"任务 {task_id} 完成，共评分 {len(results)} 条记忆\")\n\n# 提交批量任务\nresults = await async_scorer.submit_batch(\n memory_ids=[...], # 记忆 ID 列表\n callback=on_complete\n)\n```\n\n## 配置示例\n\n### 详细模式配置\n\n```python\nconfig = QualityConfig(\n contentQuality=0.4,\n relevanceWeight=0.3,\n recencyWeight=0.15,\n usageWeight=0.15,\n minQualityThreshold=0.5,\n enable_ai_evaluator=True,\n enable_implicit_signals=True,\n async_batch_size=50\n)\n```\n\n### 简洁模式配置\n\n```python\nconfig = QualityConfig(\n contentQuality=0.2,\n relevanceWeight=0.5,\n recencyWeight=0.2,\n usageWeight=0.1,\n minQualityThreshold=0.6,\n enable_ai_evaluator=False,\n enable_implicit_signals=True,\n async_batch_size=20\n)\n```\n\n## 性能指标\n\n根据实际部署测试，系统在标准配置下的性能表现如下：\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| 单条评分延迟 | <50ms | 同步评分响应时间 |\n| 批量评分吞吐 | ~100条/秒 | 异步模式下的处理速度 |\n| ONNX 推理延迟 | <10ms | 单次模型推理时间 |\n| 内存占用 | <100MB | 运行时内存峰值 |\n\n性能数据来源于项目的基准测试套件，实际表现会因硬件配置和数据规模而有所不同。\n\n## 相关文档\n\n- [记忆质量指南](docs/guides/memory-quality-guide.md) - 详细的使用指南和最佳实践\n- [关联质量提升](docs/features/association-quality-boost.md) - 关联机制的技术说明\n- [API 参考](../api/reference.md) - 评分系统的 API 接口文档\n\n---\n\n\n\n## MCP 协议集成\n\n### 相关页面\n\n相关主题：[代理框架集成](#agent-frameworks)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)\n- [src/mcp_memory_service/server/handlers/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/__init__.py)\n- [src/mcp_memory_service/server/handlers/memory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n- [src/mcp_memory_service/server/handlers/utility.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/utility.py)\n- [src/mcp_memory_service/discovery/mdns_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/discovery/mdns_service.py)\n- [docs/remote-mcp-setup.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/remote-mcp-setup.md)\n- [docs/guides/mcp-enhancements.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/mcp-enhancements.md)\n \n\n# MCP 协议集成\n\nMCP Memory Service 是一个基于 Model Context Protocol (MCP) 的语义记忆服务，为 Claude Code 等 MCP 客户端提供记忆存储、检索和语义搜索能力。本页面详细介绍 MCP 协议集成的架构设计、核心组件、API 接口以及配置方法。\n\n## MCP 协议概述\n\nModel Context Protocol (MCP) 是一种标准化协议，用于在 AI 助手与外部数据源、工具之间建立通信桥梁。MCP Memory Service 通过该协议暴露记忆管理功能，使 AI 助手能够：\n\n- 持久化存储对话上下文和重要信息\n- 基于语义相似性检索记忆\n- 通过标签和类型组织记忆\n- 实时获取记忆更新事件\n\n资料来源：[src/mcp_memory_service/mcp_server.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)\n\n## 架构设计\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端层\"\n Claude[Claude Code]\n OpenCode[OpenCode]\n Custom[自定义 MCP 客户端]\n end\n \n subgraph \"MCP Memory Service 核心\"\n MCPServer[MCP Server]\n Handlers[Handler 路由层]\n MemoryService[Memory Service]\n EmbeddingEngine[Embedding 引擎]\n end\n \n subgraph \"存储层\"\n SQLiteVec[(SQLite Vec
向量存储)]\n GraphDB[(图数据库
关系存储)]\n end\n \n subgraph \"发现服务\"\n MDNS[mDNS Service
服务发现]\n end\n \n Claude --> MCPServer\n OpenCode --> MCPServer\n Custom --> MCPServer\n \n MCPServer --> Handlers\n Handlers --> MemoryService\n MemoryService --> EmbeddingEngine\n MemoryService --> SQLiteVec\n MemoryService --> GraphDB\n MCPServer --> MDNS\n```\n\n### 核心组件职责\n\n| 组件 | 文件路径 | 主要职责 |\n|------|----------|----------|\n| MCP Server | `mcp_server.py` | 协议握手、请求路由、响应格式化 |\n| Memory Handler | `handlers/memory.py` | 处理记忆 CRUD 操作 |\n| Utility Handler | `handlers/utility.py` | 处理健康检查、统计等辅助功能 |\n| Memory Service | `services/memory_service.py` | 业务逻辑编排、数据验证 |\n| mDNS Service | `discovery/mdns_service.py` | 局域网服务自动发现 |\n\n资料来源：[src/mcp_memory_service/server/handlers/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/__init__.py)\n\n## Handler 路由层设计\n\n### 路由分发流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP Server\n participant Router as Handler Router\n participant Handler as 具体 Handler\n \n Client->>Server: MCP JSON-RPC 请求\n Server->>Router: 解析 method 名称\n Router->>Handler: 路由到对应 Handler\n Handler->>Handler: 执行业务逻辑\n Handler->>Router: 返回处理结果\n Router->>Server: 封装响应\n Server->>Client: 返回 JSON-RPC 响应\n```\n\n### Handler 模块结构\n\n```python\n# handlers/__init__.py 导出结构\nfrom .memory import MemoryHandler # 记忆操作处理器\nfrom .utility import UtilityHandler # 工具类处理器\n```\n\n每个 Handler 负责特定的 MCP 工具调用，遵循统一的接口规范：\n\n| 方法 | 说明 |\n|------|------|\n| `initialize()` | 初始化处理器，验证配置 |\n| `handle_request()` | 处理传入的 MCP 请求 |\n| `get_schema()` | 返回工具的 JSON Schema 定义 |\n\n资料来源：[src/mcp_memory_service/server/handlers/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/__init__.py)\n\n## Memory Handler 详解\n\nMemory Handler 是 MCP 协议集成的核心，负责处理所有与记忆相关的操作。\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### 支持的工具调用\n\n| 工具名称 | 方法 | 功能描述 |\n|----------|------|----------|\n| `store_memory` | 存储记忆 | 创建新记忆，自动生成嵌入向量 |\n| `retrieve_memory` | 检索记忆 | 通过哈希值获取单条记忆 |\n| `search_memories` | 语义搜索 | 基于向量相似度搜索相关记忆 |\n| `list_memories` | 列表查询 | 分页获取记忆列表 |\n| `delete_memory` | 删除记忆 | 移除指定记忆及其关联数据 |\n| `update_memory` | 更新记忆 | 修改记忆内容和元数据 |\n\n### 请求参数模型\n\n```mermaid\ngraph LR\n A[store_memory] --> B{content}\n A --> C{tags?}\n A --> D{memory_type?}\n A --> E{metadata?}\n \n F[search_memories] --> G{query}\n F --> H{limit?}\n F --> I{similarity_threshold?}\n F --> J{tags_filter?}\n```\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `content` | string | 是 | 记忆内容文本 |\n| `tags` | string[] | 否 | 标签数组 |\n| `memory_type` | string | 否 | 记忆类型（note/reference/session 等） |\n| `metadata` | object | 否 | 自定义元数据 |\n| `query` | string | 是（搜索时） | 搜索查询文本 |\n| `limit` | integer | 否 | 返回结果数量限制 |\n| `similarity_threshold` | float | 否 | 相似度阈值（0-1） |\n\n### 响应格式\n\n```json\n{\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Memory content here...\"\n }\n ],\n \"isError\": false\n}\n```\n\n错误响应示例：\n\n```json\n{\n \"content\": [\n {\n \"type\": \"text\", \n \"text\": \"Error: Memory not found\"\n }\n ],\n \"isError\": true\n}\n```\n\n## Utility Handler 详解\n\nUtility Handler 提供系统级的辅助功能接口。\n\n资料来源：[src/mcp_memory_service/server/handlers/utility.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/utility.py)\n\n### 健康检查接口\n\n| 工具名称 | 功能 | 返回信息 |\n|----------|------|----------|\n| `health` | 服务健康状态 | 后端类型、记忆总数、运行时间 |\n| `list_tools` | 列出可用工具 | 所有注册的 MCP 工具清单 |\n| `get_capabilities` | 获取能力列表 | 服务器支持的协议特性 |\n\n### 健康检查响应示例\n\n```json\n{\n \"status\": \"healthy\",\n \"backend\": \"sqlite_vec\",\n \"memory_count\": 1247,\n \"version\": \"9.3.0\",\n \"uptime_seconds\": 3600\n}\n```\n\n## 服务发现机制\n\nMCP Memory Service 支持通过 mDNS (Multicast DNS) 进行局域网服务自动发现，使客户端能够无需手动配置即可找到服务。\n\n资料来源：[src/mcp_memory_service/discovery/mdns_service.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/discovery/mdns_service.py)\n\n### 服务公告流程\n\n```mermaid\ngraph LR\n A[服务启动] --> B[注册 mDNS]\n B --> C[公告 _mcp-memory._tcp]\n C --> D[客户端发现服务]\n D --> E[获取 host:port]\n E --> F[建立 MCP 连接]\n```\n\n### 服务配置参数\n\n| 参数 | 环境变量 | 默认值 | 说明 |\n|------|----------|--------|------|\n| 服务名称 | `MDNS_SERVICE_NAME` | `mcp-memory` | mDNS 服务标识 |\n| 服务类型 | - | `_mcp-memory._tcp` | mDNS 服务协议类型 |\n| 公告端口 | `PORT` | `8443` | MCP 服务监听端口 |\n| API Key | `MCP_API_KEY` | 无 | 认证密钥 |\n\n## MCP 工具调用示例\n\n### Python SDK 使用方式\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 健康检查（约 5 tokens）\n>>> info = health()\n>>> print(f\"Backend: {info.backend}, Count: {info.count}\")\nBackend: sqlite_vec, Count: 1247\n\n# 存储记忆（约 15 tokens）\n>>> hash = store(\"New memory content\", tags=[\"note\", \"important\"])\n>>> print(f\"Stored: {hash}\")\nStored: abc12345\n\n# 语义搜索（约 20 tokens）\n>>> results = search(\"architecture decisions\", limit=5)\n>>> for m in results.memories:\n... print(f\"{m.hash}: {m.preview[:50]}...\")\nabc12345: Implemented OAuth 2.1 authentication for...\ndef67890: Refactored storage backend to support...\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)\n\n### Claude Code 命令行调用\n\n| 命令 | 功能 | 示例 |\n|------|------|------|\n| `/memory-recall` | 基于时间检索 | `/memory-recall \"last week discussions\"` |\n| `/memory-search` | 标签/内容搜索 | `/memory-search --tags \"architecture\"` |\n| `/memory-context` | 上下文捕获 | `/memory-context --summary \"planning\"` |\n| `/memory-health` | 健康检查 | `/memory-health --detailed` |\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n## 远程 MCP 配置\n\n对于需要远程连接 MCP Memory Service 的场景，需要进行专门的配置。\n\n资料来源：[docs/remote-mcp-setup.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/remote-mcp-setup.md)\n\n### 远程配置架构\n\n```mermaid\ngraph LR\n subgraph \"远程服务器\"\n Server[MCP Memory Service]\n DB[(SQLite Vec)]\n Server --> DB\n end\n \n subgraph \"本地客户端\"\n Claude[Claude Code]\n Config[MCP Config]\n end\n \n Config -->|HTTPS + API Key| Server\n```\n\n### 配置步骤\n\n1. **服务端配置**：确保服务监听在可访问的网络接口\n2. **API Key 设置**：配置 `MCP_API_KEY` 环境变量\n3. **客户端配置**：在 `~/.claude/settings.json` 中添加远程服务器信息\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-memory\"],\n \"url\": \"https://your-server:8443/mcp\"\n }\n }\n}\n```\n\n## MCP 增强功能\n\nMCP Memory Service 在标准 MCP 协议基础上实现了多项增强功能。\n\n资料来源：[docs/guides/mcp-enhancements.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/mcp-enhancements.md)\n\n### 功能增强列表\n\n| 增强功能 | 说明 | 启用方式 |\n|----------|------|----------|\n| 实时事件推送 | 支持 Server-Sent Events 实时推送记忆更新 | `/api/events` 端点 |\n| 图关系推理 | 自动推断记忆间的语义关系 | `RelationshipInferenceEngine` |\n| 类型本体优化 | 标准化记忆类型分类体系 | `improve_memory_ontology.py` |\n| 响应大小限制 | 防止上下文窗口溢出 | `MCP_MAX_RESPONSE_CHARS` 环境变量 |\n\n### 响应大小限制配置\n\n```python\n# src/mcp_memory_service/server/utils/response_limiter.py\nimport os\n\n# 默认值：0 = 无限制（向后兼容）\nDEFAULT_MAX_CHARS = int(os.environ.get(\"MCP_MAX_RESPONSE_CHARS\", 0))\n```\n\n配置方式：\n\n```bash\n# 限制单次响应最大 100,000 字符\nexport MCP_MAX_RESPONSE_CHARS=100000\n```\n\n## 性能特性\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| Token 成本 | $0.15/1M tokens | 每 10 用户部署约 $16.43/年 |\n| 首次调用延迟 | ~50ms | 包含存储初始化 |\n| 后续调用延迟 | ~5-10ms | 连接复用 |\n| 内存占用 | <10MB | 服务进程开销 |\n| 搜索吞吐量 | ~1000 memories/second | 语义搜索 |\n\n资料来源：[src/mcp_memory_service/api/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)\n\n## 与 Claude Code 的集成\n\nClaude Code 通过 MCP 协议与 Memory Service 深度集成，支持自动化的记忆感知功能。\n\n```mermaid\ngraph TB\n subgraph \"Claude Code 生命周期\"\n Start[Session Start]\n Compact[Compacting]\n End[Session End]\n end\n \n Start --> |自动加载| LoadMem[Load Relevant Memories]\n Compact --> |可选注入| InjectMem[Inject Context]\n End --> |自动保存| SaveMem[Save Session Insights]\n \n LoadMem --> MCPServer[MCP Server]\n MCPServer --> MemService[Memory Service]\n```\n\n### 钩子脚本列表\n\n| 脚本 | 功能 | 版本 |\n|------|------|------|\n| `session-start.js` | 会话启动时加载记忆 | v2.2 |\n| `session-end.js` | 会话结束时保存洞察 | v2.0 |\n| `memory-retrieval.js` | 按需检索记忆 | v1.5 |\n| `permission-request.js` | 权限自动化处理 | v1.0 |\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n## 错误处理与调试\n\n### 常见错误码\n\n| 错误码 | 含义 | 处理建议 |\n|--------|------|----------|\n| `E_NOT_FOUND` | 记忆不存在 | 检查 content_hash 是否正确 |\n| `E_DUPLICATE` | 记忆已存在 | 使用现有记忆或修改内容 |\n| `E_INVALID_TAGS` | 标签格式错误 | 确保标签为字符串数组 |\n| `E_CONNECTION_FAILED` | 连接失败 | 检查服务是否运行、网络是否通 |\n\n### 调试模式启用\n\n```bash\n# CLI 启用调试\nmemory server --debug\n\n# Claude Code 调试钩子\nclaude --debug hooks\n```\n\n## 总结\n\nMCP Memory Service 通过标准化的 MCP 协议，为 AI 助手提供了强大的语义记忆能力。其核心优势包括：\n\n- **标准化接口**：遵循 MCP 协议规范，支持多种 MCP 客户端\n- **语义搜索**：基于向量嵌入的相似度检索\n- **实时事件**：通过 SSE 推送实现即时记忆同步\n- **自动发现**：mDNS 支持简化服务配置\n- **高效性能**：毫秒级响应速度，低资源占用\n\n通过 MCP 协议集成，MCP Memory Service 能够无缝融入 Claude Code 等 AI 开发工具的工作流，为开发者提供持久化的上下文记忆能力。\n\n---\n\n\n\n## 代理框架集成\n\n### 相关页面\n\n相关主题：[MCP 协议集成](#mcp-integration), [快速开始](#quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/api/client.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/client.py)\n- [src/mcp_memory_service/api/operations.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n- [claude-hooks/core/session-end-harvest.js](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/core/session-end-harvest.js)\n- [claude-hooks/core/auto-capture-hook.js](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/core/auto-capture-hook.js)\n- [docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)\n- [docs/agents/langgraph.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/langgraph.md)\n- [docs/agents/crewai.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/crewai.md)\n- [docs/agents/autogen.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/autogen.md)\n \n\n# 代理框架集成\n\n## 概述\n\nMCP Memory Service 通过提供标准化的 API 接口和专门设计的客户端模块，实现与主流 AI 代理框架的无缝集成。这些集成使得代理（Agent）能够利用持久化记忆服务，实现跨会话的上下文感知和长期知识积累。代理框架集成是 MCP Memory Service 的核心能力之一，它将记忆服务从简单的存储层提升为智能代理的外部记忆系统。 资料来源：[docs/guides/AGENTS.md]()\n\n## 集成架构\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"代理框架层\"\n LG[LangGraph]\n CR[CrewAI]\n AG[AutoGen]\n CUSTOM[自定义代理]\n end\n \n subgraph \"MCP Memory Service API\"\n API[REST API]\n SSE[Server-Sent Events]\n TOOLS[MCP Tools]\n end\n \n subgraph \"客户端层\"\n CLIENT[Python Client]\n HOOKS[Claude Hooks]\n end\n \n subgraph \"存储后端\"\n SQLiteVec[(SQLite-Vec)]\n Cloudflare[(Cloudflare D1)]\n end\n \n LG --> CLIENT\n CR --> CLIENT\n AG --> CLIENT\n CUSTOM --> API\n HOOKS --> API\n CLIENT --> API\n API --> SSE\n API --> TOOLS\n API --> SQLiteVec\n API --> Cloudflare\n```\n\n### 核心组件关系\n\n| 组件 | 职责 | 文件位置 |\n|------|------|----------|\n| Python Client | 提供高级 API 封装 | `src/mcp_memory_service/api/client.py` |\n| Operations | 定义具体操作方法 | `src/mcp_memory_service/api/operations.py` |\n| Claude Hooks | 会话生命周期记忆管理 | `claude-hooks/core/` |\n| REST API | HTTP 接口暴露 | FastAPI 自动生成 |\n\n## Python 客户端集成\n\n### 客户端初始化\n\nMCP Memory Service 提供了专门的 Python 客户端，用于代理框架集成。客户端支持连接配置和认证管理。\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# 搜索记忆 (20 tokens)\nresults = search(\"architecture decisions\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# 存储记忆 (15 tokens)\nhash = store(\"New memory\", tags=[\"note\", \"important\"])\nprint(f\"Stored: {hash}\")\n\n# 健康检查 (5 tokens)\ninfo = health()\nprint(f\"Backend: {info.backend}, Count: {info.count}\")\n```\n\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n### 核心操作接口\n\n| 方法 | 功能 | 典型延迟 |\n|------|------|----------|\n| `search()` | 语义相似性搜索 | 5-10ms |\n| `store()` | 存储新记忆 | 50ms (首次) / 5-10ms (后续) |\n| `health()` | 服务健康检查 | <1ms |\n| `list_memories()` | 分页列举记忆 | 5-10ms |\n| `get_memory()` | 通过哈希获取单条记忆 | <5ms |\n\n### 性能指标\n\n根据基准测试数据，在 10 用户部署场景下的成本和性能表现如下：\n\n- **成本**: $0.15/1M tokens，每年约 $16.43\n- **首次调用延迟**: 约 50ms（包含存储初始化）\n- **后续调用延迟**: 5-10ms（连接复用）\n- **内存开销**: <10MB\n\n资料来源：[src/mcp_memory_service/api/__init__.py]()\n\n## Claude Hooks 集成\n\n### 钩子类型概述\n\nClaude Hooks 提供了一种轻量级的代理记忆集成方式，支持会话生命周期的自动记忆管理。\n\n```mermaid\ngraph LR\n A[会话开始] --> B[Session-Start Hook]\n B --> C[加载相关记忆]\n C --> D[代理执行任务]\n D --> E[会话结束]\n E --> F[Session-End Hook]\n F --> G[存储会话洞察]\n \n H[自动捕获] --> I[Auto-Capture Hook]\n I --> D\n```\n\n### 会话结束收割机制\n\n`session-end-harvest.js` 负责在会话结束时自动提取和存储关键信息：\n\n| 功能 | 描述 |\n|------|------|\n| 决策提取 | 识别并保存会话中的关键决策 |\n| 洞察收集 | 收集有价值的见解和发现 |\n| 上下文保存 | 保留重要的技术上下文 |\n\n资料来源：[claude-hooks/core/session-end-harvest.js]()\n\n### 自动捕获钩子\n\n`auto-capture-hook.js` 提供了实时记忆捕获能力，无需用户显式操作即可记录重要信息：\n\n```javascript\n// 自动捕获配置示例\n{\n \"captureTriggers\": [\"#remember\", \"#important\"],\n \"excludePatterns\": [\"password\", \"api-key\"],\n \"maxContentLength\": 10000\n}\n```\n\n资料来源：[claude-hooks/core/auto-capture-hook.js]()\n\n### 配置选项\n\n| 选项 | 默认值 | 说明 |\n|------|--------|------|\n| `verbose` | `true` | 显示基本信息 |\n| `showMemoryDetails` | `false` | 显示记忆评分详情 |\n| `cleanMode` | `false` | 最小化输出 |\n| `injectAfterCompacting` | `false` | 紧凑化后注入记忆 |\n| `contentQuality` | - | 内容质量评分权重 |\n\n资料来源：[claude-hooks/README.md]()\n\n## LangGraph 集成\n\n### 集成方式\n\nMCP Memory Service 可以作为 LangGraph 代理的外部记忆存储，实现状态感知的长期记忆管理。\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom mcp_memory_service.api import search, store\n\n# 创建带记忆的代理\ndef memory_node(state):\n query = state.get(\"query\", \"\")\n results = search(query, limit=3)\n return {\"memories\": results.memories}\n\nagent = create_react_agent(\n model=llm,\n tools=[memory_node],\n state_modifier=\"你有一个外部记忆系统可以使用。\"\n)\n```\n\n### 状态流设计\n\n```mermaid\ngraph TB\n START[用户输入] --> MEMORY_QUERY[查询记忆]\n MEMORY_QUERY --> MEMORY_RESULTS[返回相关记忆]\n MEMORY_RESULTS --> CONTEXT_BUILD[构建上下文]\n CONTEXT_BUILD --> LLM_REASON[LLM 推理]\n LLM_REASON --> DECISION{需要新记忆?}\n DECISION -->|是| STORE[存储记忆]\n DECISION -->|否| RESPONSE[返回响应]\n STORE --> RESPONSE\n```\n\n资料来源：[docs/agents/langgraph.md]()\n\n## CrewAI 集成\n\n### 代理角色配置\n\nCrewAI 中的代理可以配置使用 MCP Memory Service 作为共享知识库：\n\n```python\nfrom crewai import Agent\nfrom mcp_memory_service.api import search\n\nresearcher = Agent(\n role=\"研究员\",\n goal=\"基于现有知识库进行深入研究\",\n backstory=\"你是一个研究专家，可以访问公司的知识库。\",\n tools=[search]\n)\n```\n\n### 记忆感知工作流\n\n| 组件 | 功能 |\n|------|------|\n| 共享记忆库 | 所有代理可访问的持久化记忆 |\n| 上下文注入 | 自动将相关记忆注入代理上下文 |\n| 学习反馈 | 任务完成后自动更新记忆库 |\n\n资料来源：[docs/agents/crewai.md]()\n\n## AutoGen 集成\n\n### 会话管理器集成\n\nAutoGen 的群组会话管理器可以与 MCP Memory Service 深度集成：\n\n```python\nimport autogen\nfrom mcp_memory_service.api import store, search\n\n# 创建记忆感知的群组管理员\nclass MemoryGroupChat(autogen.GroupChat):\n def __init__(self, *args, **kwargs):\n super().__init__(*args, **kwargs)\n self.memory_service = True\n \n def select_speaker(self):\n # 基于相关记忆选择下一个发言者\n context = search(self.messages_summary)\n return super().select_speaker()\n```\n\n### 多代理记忆同步\n\n```mermaid\ngraph TB\n subgraph \"AutoGen 群组\"\n AGENT1[代理 A]\n AGENT2[代理 B]\n AGENT3[代理 C]\n end\n \n subgraph \"记忆服务\"\n MEMSTORE[(记忆存储)]\n end\n \n AGENT1 -->|写入洞察| MEMSTORE\n AGENT2 -->|写入发现| MEMSTORE\n AGENT3 -->|写入结论| MEMSTORE\n AGENT1 -->|读取| MEMSTORE\n AGENT2 -->|读取| MEMSTORE\n AGENT3 -->|读取| MEMSTORE\n```\n\n资料来源：[docs/agents/autogen.md]()\n\n## 配置管理\n\n### 环境变量配置\n\n| 变量 | 默认值 | 说明 |\n|------|--------|------|\n| `MCP_MAX_RESPONSE_CHARS` | `0` (无限制) | 最大响应字符数 |\n| `MCP_MEMORY_ENDPOINT` | 本地服务 | API 端点地址 |\n| `MCP_MEMORY_API_KEY` | 无 | API 认证密钥 |\n\n### 客户端配置示例\n\n```python\nfrom mcp_memory_service.api.client import MemoryServiceClient\n\nclient = MemoryServiceClient(\n endpoint=\"https://your-server:8443\",\n api_key=\"your-api-key\",\n timeout=30,\n max_retries=3\n)\n```\n\n资料来源：[src/mcp_memory_service/api/client.py]()\n\n## 错误处理与容错\n\n### 重试策略\n\nPython 客户端内置自动重试机制：\n\n| 错误类型 | 重试次数 | 退避策略 |\n|----------|----------|----------|\n| 网络超时 | 3 次 | 指数退避 |\n| 500 错误 | 2 次 | 线性退避 |\n| 认证失败 | 0 次 | 立即失败 |\n\n### 降级处理\n\n当记忆服务不可用时，代理框架可以配置降级策略：\n\n1. **静默降级**: 继续执行任务，记录警告\n2. **缓存降级**: 使用本地缓存的记忆\n3. **失败降级**: 返回错误，要求用户干预\n\n资料来源：[src/mcp_memory_service/api/operations.py]()\n\n## 最佳实践\n\n### 记忆质量控制\n\n| 原则 | 说明 |\n|------|------|\n| 相关性过滤 | 仅存储与目标相关的信息 |\n| 去重处理 | 避免存储重复内容 |\n| 时效性管理 | 定期清理过时记忆 |\n| 隐私保护 | 过滤敏感信息后再存储 |\n\n### 性能优化建议\n\n1. **批量操作**: 使用批量 API 减少网络往返\n2. **连接复用**: 保持长连接以降低延迟\n3. **异步处理**: 非关键路径使用异步调用\n4. **缓存策略**: 实现本地缓存减少重复查询\n\n### 安全注意事项\n\n- API 密钥应存储在环境变量或密钥管理服务中\n- 敏感记忆内容应在存储前进行脱敏处理\n- 定期轮换 API 访问凭证\n\n## 版本兼容性\n\n| 功能 | 最低版本要求 |\n|------|--------------|\n| Python 客户端 | v5.0.0+ |\n| Claude Hooks | v8.5.7+ |\n| LangGraph 集成 | v6.0.0+ |\n| CrewAI 集成 | v0.4.0+ |\n| AutoGen 集成 | v0.2.0+ |\n\n## 故障排查\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接超时 | 服务未启动 | 检查 `curl http://localhost:8000/api/health` |\n| 认证失败 | API 密钥错误 | 验证环境变量配置 |\n| 记忆未找到 | 哈希值错误 | 使用 `list_memories()` 检查 |\n| 响应延迟高 | 网络问题或负载高 | 检查服务端资源使用情况 |\n\n### 诊断命令\n\n```bash\n# 检查服务健康状态\ncurl http://localhost:8000/api/health\n\n# 检查 SSE 连接统计\ncurl http://localhost:8000/api/events/stats\n\n# 验证 Python 客户端连接\npython -c \"from mcp_memory_service.api import health; print(health())\"\n\n---\n\n\n\n## 插件系统\n\n### 相关页面\n\n相关主题：[MCP 协议集成](#mcp-integration), [记忆整合系统](#consolidation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/plugins/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/plugins/__init__.py)\n- [src/mcp_memory_service/plugins/registry.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/plugins/registry.py)\n- [src/mcp_memory_service/plugins/context.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/plugins/context.py)\n- [examples/plugin-audit-log/mcp_memory_plugin_audit_log/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/examples/plugin-audit-log/mcp_memory_plugin_audit_log/__init__.py)\n- [docs/plugins/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/plugins/README.md)\n \n\n# 插件系统\n\n## 概述\n\nMCP Memory Service 的插件系统是一个事件驱动的扩展框架，允许开发者通过订阅特定的钩子（Hook）来拦截和响应内存操作的生命周期事件。该系统采用基于 entry_points 的自动发现机制，插件无需修改核心代码即可扩展服务功能。\n\n## 架构设计\n\n### 核心组件\n\n插件系统由以下核心组件构成：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 插件注册表 | `plugins/registry.py` | 管理所有已加载的插件，提供插件的注册、发现和生命周期管理 |\n| 插件上下文 | `plugins/context.py` | 提供插件与核心系统交互的 API，包括事件订阅和上下文信息访问 |\n| 插件入口 | `plugins/__init__.py` | 定义插件接口规范和公共导出 |\n\n### 事件驱动模型\n\n插件系统基于发布-订阅模式实现，核心服务在特定操作发生时触发相应的事件钩子：\n\n```mermaid\ngraph TD\n A[核心服务] -->|触发事件| B[事件总线]\n B --> C[插件A - on_store处理器]\n B --> D[插件B - on_store处理器]\n B --> E[插件C - on_retrieve处理器]\n \n C -->|处理| F[执行自定义逻辑]\n D -->|处理| G[记录审计日志]\n E -->|处理| H[缓存管理]\n```\n\n## 可用钩子\n\n系统提供四个主要的事件钩子，覆盖内存数据的完整生命周期：\n\n| 钩子名称 | 触发时机 | 典型用途 | 资料来源 |\n|----------|----------|----------|----------|\n| `on_store` | 新建记忆时 | 审计日志、自定义索引、统计收集 | [examples/plugin-audit-log/README.md]() |\n| `on_delete` | 删除记忆时 | 清理关联资源、更新统计数据 | [examples/plugin-audit-log/README.md]() |\n| `on_retrieve` | 查询记忆时 | 缓存记录、查询日志、性能监控 | [examples/plugin-audit-log/README.md]() |\n| `on_consolidate` | 记忆类型合并时 | 记录合并操作、验证数据一致性 | [examples/plugin-audit-log/README.md]() |\n\n## 开发指南\n\n### 创建插件\n\n#### 步骤一：创建插件包结构\n\n```\nmy-memory-plugin/\n├── my_memory_plugin/\n│ └── __init__.py\n├── pyproject.toml\n└── README.md\n```\n\n#### 步骤二：配置 entry_points\n\n在 `pyproject.toml` 中声明插件入口点：\n\n```toml\n[project]\nname = \"my-memory-plugin\"\nversion = \"0.1.0\"\n\n[project.entry-points.\"mcp_memory_service.plugins\"]\nmy_plugin = \"my_memory_plugin:register\"\n```\n\n#### 步骤三：实现插件逻辑\n\n```python\n# my_memory_plugin/__init__.py\n\ndef register(ctx):\n \"\"\"\n 注册插件处理器\n \n 参数:\n ctx: PluginContext 实例，提供事件订阅和系统交互能力\n \"\"\"\n ctx.on(\"on_store\", handle_store)\n ctx.on(\"on_delete\", handle_delete)\n ctx.on(\"on_retrieve\", handle_retrieve)\n ctx.on(\"on_consolidate\", handle_consolidate)\n\ndef handle_store(event):\n \"\"\"处理记忆存储事件\"\"\"\n print(f\"新记忆已存储: {event.hash}\")\n print(f\"类型: {event.memory_type}, 标签: {event.tags}\")\n\ndef handle_delete(event):\n \"\"\"处理记忆删除事件\"\"\"\n print(f\"记忆已删除: {event.hash}\")\n\ndef handle_retrieve(event):\n \"\"\"处理记忆检索事件\"\"\"\n print(f\"查询: {event.query}, 返回结果: {event.count} 条\")\n return event # 返回事件对象，确保后续处理器正常执行\n\ndef handle_consolidate(event):\n \"\"\"处理记忆类型合并事件\"\"\"\n print(f\"合并操作: {event.old_type} -> {event.new_type}\")\n print(f\"影响记忆数: {event.affected_count}\")\n```\n\n### 安装和使用\n\n1. 以开发模式安装插件：\n\n```bash\ncd my-memory-plugin\npip install -e .\n```\n\n2. 重启 MCP Memory Service：\n\n```bash\nsystemctl --user restart mcp-memory-http.service\n```\n\n3. 验证插件加载状态：\n\n```bash\ncurl -k https://localhost:8443/api/health\n```\n\n## 插件示例：审计日志\n\n`examples/plugin-audit-log` 提供了一个完整的参考实现：\n\n```python\n# 事件处理函数示例\n\ndef on_store_handler(event):\n \"\"\"记录存储操作\"\"\"\n log_entry = {\n \"action\": \"store\",\n \"hash\": event.hash,\n \"memory_type\": event.memory_type,\n \"tags\": event.tags,\n \"content_length\": len(event.content)\n }\n audit_logger.info(log_entry)\n\ndef on_delete_handler(event):\n \"\"\"记录删除操作\"\"\"\n log_entry = {\n \"action\": \"delete\",\n \"hash\": event.hash\n }\n audit_logger.info(log_entry)\n\ndef on_retrieve_handler(event):\n \"\"\"记录检索操作\"\"\"\n log_entry = {\n \"action\": \"retrieve\",\n \"query\": event.query,\n \"result_count\": len(event.results)\n }\n audit_logger.info(log_entry)\n return event # 返回事件确保后续处理链不被中断\n```\n\n## 插件上下文 API\n\n`PluginContext` 对象提供以下核心能力：\n\n| 方法 | 说明 | 返回值 |\n|------|------|--------|\n| `on(event, handler)` | 订阅指定事件 | 无 |\n| `off(event, handler)` | 取消事件订阅 | 无 |\n| `emit(event, data)` | 触发事件（由系统内部调用） | 无 |\n\n## 最佳实践\n\n### 事件处理器返回值\n\n处理检索相关事件时，**必须返回原始事件对象**以确保事件链正常传递：\n\n```python\ndef on_retrieve_handler(event):\n # 执行自定义逻辑\n process_results(event.results)\n # 必须返回事件对象\n return event\n```\n\n### 错误处理\n\n插件应实现健壮的错误处理机制，避免因单点故障影响系统稳定性：\n\n```python\ndef handle_store(event):\n try:\n # 插件逻辑\n do_something(event)\n except Exception as e:\n logger.error(f\"插件处理失败: {e}\")\n # 不抛出异常，保持系统正常运行\n```\n\n### 异步处理\n\n对于耗时操作，建议使用异步机制：\n\n```python\nimport asyncio\n\nasync def handle_store_async(event):\n await long_running_task(event)\n\ndef handle_store(event):\n asyncio.create_task(handle_store_async(event))\n```\n\n## 部署注意事项\n\n| 项目 | 说明 |\n|------|------|\n| 安装位置 | 插件包需安装到与 MCP Memory Service 相同的环境 |\n| 入口点名称 | 必须是 `mcp_memory_service.plugins` 组下的有效条目 |\n| 服务重启 | 每次安装或更新插件后需重启服务 |\n| 依赖隔离 | 建议使用虚拟环境管理插件依赖 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：doobidoo/mcp-memory-service\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps。\n\n## 1. 安装坑 · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fdb895dcb5694a15937c208c89c79c98 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：v10.51.1 — Milvus consolidation fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.1 — Milvus consolidation fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c344fbad309a43aa81482c5e4b429a53 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.3 — Versioned memory update flag + transitive graph inference\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e282c4b45ed04c8eb58759d1b32722bc | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n\n## 8. 能力坑 · 能力判断依赖假设\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:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：feat: cascading search fallback when semantic results are sparse\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v10.50.0 — Plugin Hook Scaffolding\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.50.0 — Plugin Hook Scaffolding\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af91db1e780a4ee5b0c16b8ea3238bf2 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d648b9854ac1432b8a86297ab220ba34 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · 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:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：doobidoo/mcp-memory-service\n\n摘要：发现 20 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps。\n\n## 1. 安装坑 · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.0 — Plugin hooks live, dynamic /api/types, audit-log example\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fdb895dcb5694a15937c208c89c79c98 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 3. 安装坑 · 来源证据：v10.51.1 — Milvus consolidation fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.1 — Milvus consolidation fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c344fbad309a43aa81482c5e4b429a53 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：v10.51.3 — Versioned memory update flag + transitive graph inference\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.51.3 — Versioned memory update flag + transitive graph inference\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e282c4b45ed04c8eb58759d1b32722bc | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n\n## 8. 能力坑 · 能力判断依赖假设\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:908539519 | https://github.com/doobidoo/mcp-memory-service | README/documentation is current enough for a first validation pass.\n\n## 9. 维护坑 · 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n\n## 11. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 13. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 来源证据：feat: cascading search fallback when semantic results are sparse\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 15. 安全/权限坑 · 来源证据：v10.50.0 — Plugin Hook Scaffolding\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.50.0 — Plugin Hook Scaffolding\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af91db1e780a4ee5b0c16b8ea3238bf2 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.50.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.51.2 — OAuth CORS fixes + Milvus embedding hydration\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d648b9854ac1432b8a86297ab220ba34 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.51.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 17. 安全/权限坑 · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 18. 安全/权限坑 · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 维护坑 · 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:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown\n\n## 20. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-memory-service - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-memory-service 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. storage-backends：存储后端。围绕“存储后端”模拟一次用户任务，不展示安装或运行结果。\n5. knowledge-graph：知识图谱。围绕“知识图谱”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. storage-backends\n输入：用户提供的“存储后端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. knowledge-graph\n输入：用户提供的“知识图谱”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / storage-backends：Step 4 必须围绕“存储后端”形成一个小中间产物，并等待用户确认。\n- Step 5 / knowledge-graph：Step 5 必须围绕“知识图谱”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/doobidoo/mcp-memory-service\n- https://github.com/doobidoo/mcp-memory-service#readme\n- .claude/skills/gitnexus/debugging/SKILL.md\n- .claude/skills/gitnexus/exploring/SKILL.md\n- .claude/skills/gitnexus/impact-analysis/SKILL.md\n- .claude/skills/gitnexus/refactoring/SKILL.md\n- README.md\n- src/mcp_memory_service/__init__.py\n- docs/architecture.md\n- docs/setup-guide.md\n- docs/first-time-setup.md\n- install.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-memory-service 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：doobidoo/mcp-memory-service\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install mcp-memory-service\n```\n\n来源：https://github.com/doobidoo/mcp-memory-service#readme\n\n## 来源\n\n- repo: https://github.com/doobidoo/mcp-memory-service\n- docs: https://github.com/doobidoo/mcp-memory-service#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_7899c8707642490e861a62147ece645b"
}