{
"canonical_name": "doobidoo/mcp-memory-service",
"compilation_id": "pack_61a19e0e1ecb448c8246e9c81013b3aa",
"created_at": "2026-05-22T04:07:08.490185+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": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_d7e388c4a3494807b33fd12b5888509c"
},
"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": 278,
"github_stars": 1830,
"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 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d0f9028fc870496f9576de28c5355817 | https://github.com/doobidoo/mcp-memory-service/issues/950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "Developers should check this installation risk before relying on the project: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_dd89642370c2dba2d6aacf12756658a6 | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)",
"failure_mode_cluster:github_issue | fmev_07b451a0081c6435e7494e041a6641bc | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos",
"title": "失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)",
"user_impact": "Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)"
},
{
"body": "Developers should check this installation risk before relying on the project: chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_74209176888c160a35483f3156117496 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"failure_mode_cluster:github_issue | fmev_d8321b2cf697c747506701fd9f641fef | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"failure_mode_cluster:github_issue | fmev_89d7bb3a956afe53a7a303ded77ab494 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"failure_mode_cluster:github_issue | fmev_4d3ba37fa05ae6ea3d30aa7e6acbf4a4 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker",
"title": "失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps",
"user_impact": "Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps"
},
{
"body": "Developers should check this installation risk before relying on the project: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_b14a35b730602b08a29e3abbdfa0c377 | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug",
"failure_mode_cluster:github_issue | fmev_a2aed67ef427fc7f9ddeebb038420d7d | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows",
"title": "失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug",
"user_impact": "Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug"
},
{
"body": "Developers should check this installation risk before relying on the project: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_d0ce94252816336aa4ecbd45eeb73603 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.0 | v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python",
"title": "失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix",
"user_impact": "Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix"
},
{
"body": "Developers should check this installation risk before relying on the project: v10.59.1 — OAuth state parameter RFC 6749 compliance fix",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_a0594e0fe855897f4612a17f520e81d4 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.1 | v10.59.1 — OAuth state parameter RFC 6749 compliance fix"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v10.59.1 — OAuth state parameter RFC 6749 compliance fix. Context: Observed when using python",
"title": "失败模式：installation: v10.59.1 — OAuth state parameter RFC 6749 compliance fix",
"user_impact": "Upgrade or migration may change expected behavior: v10.59.1 — OAuth state parameter RFC 6749 compliance fix"
},
{
"body": "Developers should check this installation risk before relying on the project: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_8a1390fb930fb3d5c55aee894e53c0e3 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.2 | v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility. Context: Observed when using python",
"title": "失败模式：installation: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility",
"user_impact": "Upgrade or migration may change expected behavior: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility"
},
{
"body": "Developers should check this installation risk before relying on the project: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix",
"category": "安装坑",
"evidence": [
"failure_mode_cluster:github_release | fmev_cce458b1322f9ccb8db2498d3499650d | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.63.0 | v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix. Context: Observed when using python",
"title": "失败模式：installation: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix",
"user_impact": "Upgrade or migration may change expected behavior: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_all_memories'",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_da505f8e644d4dedbe7b94f2026f2c47 | https://github.com/doobidoo/mcp-memory-service/issues/981 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_…",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"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 社区证据显示该项目存在一个安装相关的待验证问题：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_99e7481daede4079a5bb8c96cba781ba | https://github.com/doobidoo/mcp-memory-service/issues/957 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_2027915616af406998b039c789f84c69 | https://github.com/doobidoo/mcp-memory-service/issues/938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix",
"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": "Developers should check this configuration risk before relying on the project: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)",
"category": "配置坑",
"evidence": [
"failure_mode_cluster:github_issue | fmev_d1e6b62e41c0cf3c6d4867576ec205f2 | https://github.com/doobidoo/mcp-memory-service/issues/941 | Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)"
],
"severity": "medium",
"suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`). Context: Observed when using python, linux",
"title": "失败模式：configuration: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags...",
"user_impact": "Developers may misconfigure credentials, environment, or host setup: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 39 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 63,
"forks": 278,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1830
},
"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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for doobidoo/mcp-memory-service.\n\nProject:\n- Name: mcp-memory-service\n- Repository: https://github.com/doobidoo/mcp-memory-service\n- Summary: Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview and Key Concepts. Produce one small intermediate artifact and wait for confirmation.\n2. quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. storage-backends: Storage Backends. Produce one small intermediate artifact and wait for confirmation.\n5. rest-api: REST API Reference. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- src/mcp_memory_service/mcp_server.py\n- docs/setup-guide.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVec（https://github.com/doobidoo/mcp-memory-service/issues/981）；github/github_issue: [automated] Contributor activity digest（https://github.com/doobidoo/mcp-memory-service/issues/937）；github/github_issue: chore(milvus): track optional BaseStorage overrides + test coverage gaps（https://github.com/doobidoo/mcp-memory-service/issues/888）；github/github_issue: bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mappin（https://github.com/doobidoo/mcp-memory-service/issues/972）；github/github_issue: bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mappin（https://github.com/doobidoo/mcp-memory-service/issues/972）；github/github_issue: [automated] Contributor activity digest（https://github.com/doobidoo/mcp-memory-service/issues/937）；github/github_issue: bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mappin（https://github.com/doobidoo/mcp-memory-service/issues/972）；github/github_issue: chore(milvus): track optional BaseStorage overrides + test coverage gaps（https://github.com/doobidoo/mcp-memory-service/issues/888）；github/github_issue: chore(milvus): track optional BaseStorage overrides + test coverage gaps（https://github.com/doobidoo/mcp-memory-service/issues/888）；github/github_issue: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunne（https://github.com/doobidoo/mcp-memory-service/issues/957）；github/github_issue: [automated] Contributor activity digest（https://github.com/doobidoo/mcp-memory-service/issues/937）；github/github_issue: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after（https://github.com/doobidoo/mcp-memory-service/issues/938）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVec",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/981"
},
{
"kind": "github_issue",
"source": "github",
"title": "[automated] Contributor activity digest",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/937"
},
{
"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": "bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mappin",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/972"
},
{
"kind": "github_issue",
"source": "github",
"title": "bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mappin",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/972"
},
{
"kind": "github_issue",
"source": "github",
"title": "[automated] Contributor activity digest",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/937"
},
{
"kind": "github_issue",
"source": "github",
"title": "bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mappin",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/972"
},
{
"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": "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": "fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunne",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/957"
},
{
"kind": "github_issue",
"source": "github",
"title": "[automated] Contributor activity digest",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/937"
},
{
"kind": "github_issue",
"source": "github",
"title": "fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after",
"url": "https://github.com/doobidoo/mcp-memory-service/issues/938"
}
],
"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-15 14:48:14 UTC\n\n## 目录\n\n- [Overview and Key Concepts](#overview)\n- [Installation and Setup](#installation)\n- [Quick Start Guide](#quickstart)\n- [System Architecture](#architecture)\n- [Storage Backends](#storage-backends)\n- [Knowledge Graph and Entity Extraction](#knowledge-graph)\n- [Memory Consolidation Engine](#consolidation-engine)\n- [Quality Scoring System](#quality-scoring)\n- [REST API Reference](#rest-api)\n- [Agent Framework Integration](#agent-frameworks)\n\n\n\n## Overview and Key Concepts\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Installation and Setup](#installation), [Quick Start Guide](#quickstart)\n\n\nRelevant Source Files
\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/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n- [scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n \n\n# Overview and Key Concepts\n\nThe MCP Memory Service is a semantic memory storage and retrieval system designed for AI-assisted development workflows. It provides persistent memory capabilities for Claude Code and other MCP-compatible clients, enabling intelligent context retention across development sessions.\n\n## What is MCP Memory Service?\n\nMCP Memory Service solves the context loss problem in AI-assisted development by maintaining a persistent, searchable store of development decisions, architectural choices, and project knowledge. When you work on a project, the service captures important decisions and makes them available in future sessions.\n\n资料来源：[README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/README.md)\n\n## Architecture Overview\n\nThe system follows a layered architecture with clear separation between storage, API, and client integration layers.\n\n```mermaid\ngraph TD\n A[Claude Code / MCP Clients] -->|MCP Protocol| B[MCP Server Layer]\n B --> C[REST API Layer]\n C --> D[Service Layer]\n D --> E[Storage Backend]\n \n E -->|SQLite-vec| F[Local Vector Storage]\n E -->|Cloudflare| G[D1 + Vectorize]\n E -->|Hybrid| H[Combined Approach]\n \n I[Web Dashboard] -->|HTTP| C\n J[Claude Hooks] -->|Session Events| B\n```\n\n### Supported Storage Backends\n\n| Backend | Description | Use Case |\n|---------|-------------|----------|\n| SQLite-vec | Local vector storage with SQLite | Single-machine deployments |\n| Cloudflare D1 + Vectorize | Cloud-hosted serverless | Multi-device, global access |\n| Hybrid | Combined local and cloud | Redundancy and performance |\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## Core Components\n\n### 1. MCP Server\n\nThe MCP Server implements the Model Context Protocol, providing tools and prompts for memory operations. It handles tool execution, prompt management, and bidirectional communication with MCP clients.\n\n**Key Tools:**\n- `store_memory` - Store new memories with automatic embedding generation\n- `search_memories` - Semantic similarity search using embeddings\n- `retrieve_memory` - Retrieve specific memory by content hash\n- `delete_memory` - Remove memory and associated embeddings\n- `list_memories` - List all memories with pagination\n\n**Key Prompts:**\n- `knowledge_retrieval` - Structured memory retrieval with relevance ranking\n- `memory_summary` - Generate summaries of stored memories\n- `knowledge_export` - Export memories in various formats\n- `memory_cleanup` - Identify and remove duplicates\n\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\n### 2. REST API Layer\n\nThe REST API provides HTTP endpoints for direct access to memory operations, useful for integrations and the web dashboard.\n\n```mermaid\ngraph LR\n A[Memory Management] -->|POST /api/memories| B[Store]\n A -->|GET /api/memories| C[List]\n A -->|GET /api/memories/{hash}| D[Retrieve]\n A -->|DELETE /api/memories/{hash}| E[Delete]\n \n F[Search Operations] -->|POST /api/search| G[Semantic Search]\n F -->|GET /api/search/similar/{hash}| H[Similar Search]\n \n I[Real-time Events] -->|GET /api/events| J[SSE Stream]\n I -->|GET /api/events/stats| K[Statistics]\n```\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/memories` | POST | Store a new memory with automatic embedding generation |\n| `/api/memories` | GET | List all memories with pagination support |\n| `/api/memories/{hash}` | GET | Retrieve a specific memory by content hash |\n| `/api/memories/{hash}` | DELETE | Delete a memory and its embeddings |\n| `/api/search` | POST | Semantic similarity search using embeddings |\n| `/api/search/similar/{hash}` | GET | Find memories similar to a specific one |\n| `/api/events` | GET | Subscribe to real-time memory events stream |\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)\n\n### 3. Web Dashboard\n\nThe built-in web interface provides:\n- Interactive API documentation (Swagger UI and ReDoc)\n- Real-time statistics display\n- SSE testing interface\n- Health monitoring\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)\n\n## Key Features\n\n### Semantic Search with Embeddings\n\nThe service uses the `all-MiniLM-L6-v2` embedding model to convert memory content into vector representations. This enables semantic similarity search that understands meaning rather than just keyword matching.\n\n**Performance Characteristics:**\n| Metric | Value |\n|--------|-------|\n| First call latency | ~50ms (includes storage initialization) |\n| Subsequent calls | ~5-10ms (connection reused) |\n| Memory overhead | <10MB |\n| Cost at $0.15/1M tokens | $16.43/year per 10-user deployment |\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### Response Size Limiter\n\nTo prevent context window overflow in LLM clients, the service includes a response limiter that truncates large responses at memory boundaries. This ensures that large memory retrieval operations don't crash Claude or other LLM clients.\n\n**Configuration:**\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_MAX_RESPONSE_CHARS` | 0 (unlimited) | Maximum characters in responses |\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n### Claude Code Integration\n\nThe service provides deep integration with Claude Code through hooks and slash commands.\n\n**Available Commands:**\n| Command | Purpose |\n|---------|---------|\n| `/memory-store` | Store important decisions and context |\n| `/memory-recall` | Retrieve memories using natural language |\n| `/memory-search` | Search by tags and content keywords |\n| `/memory-context` | Capture current session context |\n| `/memory-health` | Check service health and statistics |\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n**Automatic Hooks:**\n- **Session Start**: Load relevant project memories when Claude Code starts\n- **Session End**: Store insights and decisions from completed sessions\n- **Memory Retrieval**: On-demand memory access during conversations\n- **Permission Requests**: Automated handling of MCP permission requests\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n## Memory Types Taxonomy\n\nThe service organizes memories into a standardized taxonomy:\n\n| Category | Types |\n|----------|-------|\n| Content Types | note, reference, document, guide |\n| Activity Types | session, implementation, analysis |\n\nThis standardized taxonomy helps with memory organization and retrieval. The maintenance scripts can consolidate fragmented types into this standardized set.\n\n资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n\n## Data Model\n\nEach memory in the system has the following structure:\n\n```json\n{\n \"content\": \"Memory content here\",\n \"content_hash\": \"sha256hash\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": 1673545200.0,\n \"updated_at\": 1673545200.0,\n \"memory_type\": \"note\",\n \"metadata\": {},\n \"export_source\": \"machine-name\"\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| content | string | The actual memory content |\n| content_hash | string | SHA256 hash of content for deduplication |\n| tags | array | User-defined tags for categorization |\n| created_at | float | Unix timestamp of creation |\n| updated_at | float | Unix timestamp of last update |\n| memory_type | string | Standardized type classification |\n| metadata | object | Additional metadata storage |\n| export_source | string | Source machine identifier |\n\n## Synchronization and Backup\n\n### Export/Import\n\nMemories can be exported and imported in JSON format for backup and migration purposes:\n\n- **Export**: ~1000 memories/second\n- **Import**: ~500 memories/second with deduplication\n- **File Size**: ~1KB per memory\n\n### Litestream Integration\n\nFor real-time replication, the service supports Litestream configuration, providing continuous backup to object storage.\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/sync/litestream_config.py)\n\n## Maintenance Tools\n\nThe service includes several maintenance scripts:\n\n| Script | Purpose |\n|--------|---------|\n| `check_memory_types.py` | Analyze type distribution and fragmentation |\n| `consolidate_memory_types.py` | Consolidate fragmented types into standardized taxonomy |\n| `export_memories.py` | Export memories to JSON format |\n| `import_memories.py` | Import memories from JSON with deduplication |\n\n资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n\n## Installation Methods\n\n### Python Package Installation\n```bash\npip install mcp-memory-service\n```\n\n### Claude Code Integration\n```bash\ncd claude-hooks\npython install_hooks.py --natural-triggers\n```\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n## Summary\n\nMCP Memory Service provides a comprehensive solution for maintaining persistent, searchable memory across AI-assisted development sessions. Its layered architecture supports multiple storage backends, while deep Claude Code integration enables seamless workflow integration. The system prioritizes reliability through response limiting, data deduplication, and maintenance tools that keep the memory store organized and efficient.\n\n---\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [install.py](https://github.com/doobidoo/mcp-memory-service/blob/main/install.py)\n- [scripts/installation/install.py](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/installation/install.py)\n- [.env.example](https://github.com/doobidoo/mcp-memory-service/blob/main/.env.example)\n- [pyproject.toml](https://github.com/doobidoo/mcp-memory-service/blob/main/pyproject.toml)\n \n\n# Installation and Setup\n\n## Overview\n\nThe MCP Memory Service provides a comprehensive installation framework supporting multiple deployment scenarios including pip installation, Claude Code integration, OpenCode plugin support, and standalone HTTP server deployment. The setup system is designed to be modular, allowing users to install only the components they need while maintaining cross-platform compatibility across Windows, macOS, and Linux environments.\n\n## System Requirements\n\n### Prerequisites\n\nThe installation system requires several external dependencies that must be present before deployment:\n\n| Dependency | Purpose | Platform-Specific Notes |\n|------------|---------|------------------------|\n| Python 3.10+ | Runtime environment | Required on all platforms |\n| Node.js | Hooks execution | Required for Claude Code hooks |\n| `jq` | Status line features | macOS: `brew install jq`; Linux: `sudo apt install jq`; Windows: `choco install jq` |\n| pip | Package management | Included with Python 3.10+ |\n\nThe dependency checking system (`src/mcp_memory_service/dependency_check.py`) validates all required dependencies during initialization and provides clear guidance if any are missing.\n\n### Environment Requirements\n\nThe service requires specific directory structures and environment variables:\n\n```bash\n# Standard data directory\n~/.local/share/mcp-memory/\n\n# Database file\n~/.local/share/mcp-memory/sqlite_vec.db\n\n# Configuration directory\n~/.claude/hooks/config.json # For Claude Code integration\n```\n\n## Installation Methods\n\n### Method 1: Pip Installation\n\nThe primary installation method uses pip to install the `mcp-memory-service` package:\n\n```bash\npip install mcp-memory-service\n```\n\nThe `pyproject.toml` file defines all package dependencies and metadata for PyPI distribution. This installation provides:\n\n- Core memory service library\n- HTTP server implementation\n- API endpoints\n- CLI tools\n\n资料来源：[pyproject.toml]()\n\n### Method 2: Standalone HTTP Server Installation\n\nFor HTTP server deployment, the installation script provides a guided setup process:\n\n```bash\n# From the repository root\npython scripts/installation/install.py\n\n# With specific options\npython scripts/installation/install.py --install-claude-commands # Install Claude commands\npython scripts/installation/install.py --skip-claude-commands-prompt # Skip command prompt\n```\n\nThe installer performs the following operations:\n\n1. Validates system prerequisites\n2. Installs the `mcp-memory-service` package\n3. Creates required directories\n4. Configures environment variables\n5. Sets up systemd services (on Linux)\n6. Optionally installs Claude Code commands\n\n资料来源：[scripts/installation/install.py]()\n\n### Method 3: Claude Code Hooks Installation\n\nClaude Code hooks provide automatic memory awareness and context injection. The unified installer supports multiple installation modes:\n\n```bash\ncd claude-hooks\n\n# Install Natural Memory Triggers (recommended)\npython install_hooks.py --natural-triggers\n\n# OR install basic memory awareness hooks\npython install_hooks.py --basic\n```\n\nThe hooks system consists of several components:\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| Session Start Hook | `session-start.js` | Loads relevant memories when Claude Code starts |\n| Session End Hook | `session-end.js` | Stores session insights and decisions |\n| Memory Retrieval | `memory-retrieval.js` | On-demand memory retrieval |\n| Permission Request | `permission-request.js` | MCP server permission automation |\n\n资料来源：[claude-hooks/README.md]()\n\n### Method 4: Claude Commands Installation\n\nFor Claude Code CLI integration, custom commands can be installed:\n\n```bash\n# Automatic installation during main setup\npython scripts/installation/install.py --install-claude-commands\n\n# Manual installation\npython scripts/claude_commands_utils.py\n\n# Test prerequisites\npython scripts/claude_commands_utils.py --test\n\n# Uninstall\npython scripts/claude_commands_utils.py --uninstall\n```\n\nCommands are installed to `~/.claude/commands/` and provide:\n\n- `/memory-save` - Save memories with tags\n- `/memory-recall` - Time-based memory retrieval\n- `/memory-search` - Tag and content search\n- `/memory-context` - Session context integration\n- `/memory-health` - Service health check\n\n资料来源：[claude_commands/README.md]()\n\n### Method 5: OpenCode Plugin Installation\n\nThe OpenCode plugin provides memory awareness for the OpenCode editor:\n\n```bash\n# Install plugin file\nmkdir -p ~/.config/opencode/plugins\ncp opencode/memory-plugin.js ~/.config/opencode/plugins/\n\n# Install example configuration\ncp opencode/memory-plugin.config.example.json ~/.config/opencode/memory-plugin.json\n```\n\n资料来源：[opencode/README.md]()\n\n## Environment Configuration\n\n### Environment Variables\n\nThe `.env.example` file provides configuration templates:\n\n```bash\n# MCP Memory Service Configuration\nMCP_API_KEY=your-api-key-here\nMCP_MEMORY_ENDPOINT=https://localhost:8443\nMCP_MEMORY_TIMEOUT_MS=30000\nMCP_MEMORY_LOAD_TIMEOUT_MS=10000\n```\n\n### Configuration Hierarchy\n\nThe OpenCode plugin demonstrates the configuration precedence system:\n\n```mermaid\ngraph TD\n A[Config Options] --> B[Environment Variables]\n A --> C[Default Config File]\n B --> D[OPENCODE_MEMORY_ENDPOINT]\n B --> E[OPENCODE_MEMORY_API_KEY]\n B --> F[OPENCODE_MEMORY_TIMEOUT_MS]\n C --> G[~/.config/opencode/memory-plugin.json]\n```\n\nConfiguration order of precedence (highest to lowest):\n\n1. Explicit plugin options\n2. Environment variables\n3. User config file (`~/.config/opencode/memory-plugin.json`)\n4. Project-local config (`.opencode/memory-plugin.json`)\n\n资料来源：[opencode/README.md]()\n\n## HTTP Server Deployment\n\n### Service Setup on Linux/macOS\n\nThe Litestream configuration system supports streaming SQLite replication for data durability:\n\n```bash\n# Install Litestream\ncurl -LsS https://github.com/benbjohnson/litestream/releases/latest/download/litestream-linux-amd64.tar.gz | tar -xzf -\nsudo mv litestream /usr/local/bin/\n\n# Generate configuration\npython scripts/sync/litestream_config.py\n```\n\n### Systemd Service Configuration\n\nProduction deployment uses systemd for service management:\n\n```bash\n# Start the service\nsystemctl --user start mcp-memory-http.service\n\n# Enable on boot\nsystemctl --user enable mcp-memory-http.service\n\n# Check status\nsystemctl --user status mcp-memory-http.service\n```\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py]()\n\n### Windows Service Setup\n\nFor Windows deployment, a LaunchAgent plist configuration is provided:\n\n```xml\n\n Label\n com.mcp-memory-service\n ProgramArguments\n \n /local/bin/litestream\n replicate\n -config\n {config_path}\n \n RunAtLoad\n \n\n```\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py]()\n\n## Data Synchronization\n\n### Database Export/Import\n\nFor cross-machine synchronization, the sync scripts provide export and import functionality:\n\n```bash\n# Export memories to JSON\npython scripts/sync/export_memories.py --output ./memories_export.json\n\n# Import memories from JSON\npython scripts/sync/import_memories.py --input ./memories_export.json\n```\n\nThe export format preserves all memory metadata:\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 },\n \"memories\": [\n {\n \"content\": \"Memory content\",\n \"content_hash\": \"sha256hash\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": 1673545200.0,\n \"memory_type\": \"note\"\n }\n ]\n}\n```\n\nDeduplication is based on content hash during import.\n\n资料来源：[scripts/sync/README.md]()\n\n## Maintenance Procedures\n\n### Database Type Consolidation\n\nOver time, memory types may become fragmented. The consolidation script standardizes the taxonomy:\n\n```bash\n# Preview changes (safe, read-only)\npython scripts/maintenance/consolidate_memory_types.py --dry-run\n\n# Execute consolidation\npython scripts/maintenance/consolidate_memory_types.py\n\n# With custom mapping\npython scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json\n```\n\nThe standard 24-type taxonomy includes:\n\n| Category | Types |\n|----------|-------|\n| Content Types | `note`, `reference`, `document`, `guide` |\n| Activity Types | `session`, `implementation`, `analysis` |\n\n资料来源：[scripts/maintenance/README.md]()\n\n## Verification\n\nAfter installation, verify the setup with these checks:\n\n```bash\n# Verify Claude hooks installation\nclaude --debug hooks\n\n# Run integration tests\ncd ~/.claude/hooks && node tests/integration-test.js\n\n# Test API health\ncurl -k https://your-endpoint:8443/api/health\n\n# Verify database\nsqlite3 ~/.local/share/mcp-memory/sqlite_vec.db \"SELECT COUNT(*) FROM memories;\"\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Hooks not detected | Check `ls ~/.claude/settings.json`; reinstall if missing |\n| JSON parse errors | Update to latest version |\n| Connection failed | Verify endpoint with `curl -k https://your-endpoint:8443/api/health` |\n| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |\n| Missing `jq` | Install per platform instructions in prerequisites |\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n```bash\n# Claude Code debug mode\nclaude --debug hooks\n\n# Test individual hooks\nnode ~/.claude/hooks/core/session-start.js\n```\n\n## PyPI Placeholder Packages\n\nFor users who may install the wrong package name, placeholder packages redirect to the correct installation:\n\n```bash\n# These packages emit deprecation warnings and redirect to mcp-memory-service\npip install mcp-memory\npip install memory-service\npip install agent-mem\n```\n\n资料来源：[tools/pypi-placeholders/README.md]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Installation Methods\"\n A[Pip Installation] --> E[Core Service]\n B[Claude Hooks] --> F[Memory Awareness]\n C[Claude Commands] --> G[CLI Integration]\n D[OpenCode Plugin] --> H[Editor Integration]\n end\n \n subgraph \"Runtime Components\"\n E --> I[HTTP Server]\n I --> J[API Endpoints]\n J --> K[Memory Storage]\n K --> L[sqlite_vec]\n end\n \n subgraph \"Data Layer\"\n L --> M[Local Storage]\n L --> N[LitekStream Sync]\n end\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Overview and Key Concepts](#overview), [REST API Reference](#rest-api), [Agent Framework Integration](#agent-frameworks)\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)\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- [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- [scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n \n\n# Quick Start Guide\n\n## Overview\n\nThe MCP Memory Service Quick Start Guide provides developers and users with a streamlined path to deploy and begin using the persistent semantic memory system for AI agents. This guide covers installation methods, initial configuration, core functionality verification, and essential commands for day-to-day operations.\n\nThe service serves as a centralized memory backend that stores, retrieves, and manages semantic memories with automatic embedding generation. It supports multiple deployment configurations including local SQLite-vec storage, Cloudflare D1 + Vectorize for cloud deployments, and hybrid configurations for distributed workflows across multiple machines.\n\n## Prerequisites\n\nBefore beginning the installation, ensure your development environment meets the following requirements:\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required for core service |\n| Node.js | 16+ | Required for hooks execution |\n| SQLite | 3.35+ | Bundled with Python |\n| jq | 1.6+ | Required for statusLine feature |\n| Claude Code CLI | Latest | Optional, for Claude command integration |\n\n### Installing jq (Required for StatusLine Feature)\n\n```bash\n# macOS\nbrew install jq\n\n# Linux (Ubuntu/Debian)\nsudo apt install jq\n\n# Windows\nchoco install jq\n```\n\n## Installation Methods\n\n### Automatic Installation (Recommended)\n\nThe recommended approach uses the unified installer which handles all components:\n\n```bash\ncd claude-hooks\npython install_hooks.py\n```\n\nThe installer supports multiple installation modes:\n\n| Mode | Command | Description |\n|------|---------|-------------|\n| Full Installation | `python install_hooks.py` | Installs all features including basic hooks and natural triggers |\n| Basic Only | `python install_hooks.py --basic` | Installs memory hooks only |\n| Natural Triggers | `python install_hooks.py --natural-triggers` | Installs natural memory triggers only |\n\n### MCP Memory Service Installation\n\nFor the core memory service with HTTP server:\n\n```bash\n# Install with commands (will prompt if Claude Code CLI is detected)\npython scripts/installation/install.py\n\n# Force install commands\npython scripts/installation/install.py --install-claude-commands\n\n# Skip command installation prompt\npython scripts/installation/install.py --skip-claude-commands-prompt\n```\n\n## Initial Configuration\n\n### Claude Desktop Configuration\n\nTo integrate MCP Memory Service with Claude Desktop, create or modify the Claude Desktop configuration file. The configuration path varies by operating system:\n\n- **macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nExample configuration structure:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-memory-service\": {\n \"command\": \"python\",\n \"args\": [\n \"-m\",\n \"mcp_memory_service\",\n \"server\"\n ],\n \"env\": {\n \"MCP_MEMORY_DB_PATH\": \"~/.local/share/mcp-memory/sqlite_vec.db\"\n }\n }\n }\n}\n```\n\n### Environment Variables\n\nThe service recognizes several environment variables for configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_MEMORY_DB_PATH` | `~/.local/share/mcp-memory/sqlite_vec.db` | Database storage path |\n| `MCP_MEMORY_BACKEND` | `sqlite_vec` | Storage backend type |\n| `MCP_MEMORY_PORT` | `8443` | HTTP server port |\n| `MCP_MEMORY_API_KEY` | None | Optional API key authentication |\n\n### Backend Configuration Options\n\nThe service supports multiple backend configurations:\n\n| Backend | Use Case | Configuration Value |\n|---------|----------|---------------------|\n| SQLite-vec | Local development, single machine | `sqlite_vec` or `sqlite-vec` |\n| Cloudflare D1 | Cloud deployment | `cloudflare` |\n| Hybrid | Multi-machine sync | `hybrid` |\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)\n\n## Starting the Service\n\n### HTTP Server Mode\n\nStart the HTTP server for REST API access:\n\n```bash\npython -m mcp_memory_service server\n```\n\nThe server provides an interactive dashboard at the root URL (`/`) displaying:\n\n- Total memory count\n- Active embedding model\n- Server health status\n- Response time metrics\n\n### MCP Server Mode\n\nStart as an MCP server for Claude integration:\n\n```bash\npython -m mcp_memory_service mcp\n```\n\n### Service Health Verification\n\nVerify the installation by checking service health:\n\n```bash\ncurl -k https://localhost:8443/api/health\n```\n\nExpected response includes:\n\n- `backend`: Current storage backend (e.g., `sqlite_vec`)\n- `count`: Total number of stored memories\n- `status`: Service health status\n\n## Core API Endpoints\n\nThe service exposes RESTful endpoints for memory operations:\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)\n\n### Memory Management Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/memories` | Store a new memory with automatic embedding |\n| GET | `/api/memories` | List all memories with pagination |\n| GET | `/api/memories/{hash}` | Retrieve specific memory by content hash |\n| DELETE | `/api/memories/{hash}` | Delete a memory and its embeddings |\n\n### Search Operations\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/search` | Semantic similarity search using embeddings |\n| GET | `/api/search/tags/{tag}` | Find memories by specific tag |\n| GET | `/api/search/similar/{hash}` | Find memories similar to a specific one |\n\n### Real-time Events\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/events` | Subscribe to real-time memory event stream (SSE) |\n| GET | `/api/events/stats` | View SSE connection statistics |\n\n### API Documentation\n\nInteractive API documentation is available at:\n\n- **Swagger UI**: `/api/docs`\n- **ReDoc**: `/api/redoc`\n\n## Claude Commands Integration\n\nAfter installation, several slash commands become available within Claude Code:\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n### Available Commands\n\n#### `/memory-store` - Store New Memories\n\nStore a new memory with automatic content hashing and embedding generation.\n\n```bash\nclaude /memory-store \"Implemented OAuth 2.1 authentication for improved security\"\nclaude /memory-store \"Refactored storage backend to support sqlite-vec for performance\"\n```\n\n#### `/memory-recall` - Time-based Memory Retrieval\n\nRetrieve memories using natural language time expressions.\n\n```bash\nclaude /memory-recall \"what did we decide about the database last week?\"\nclaude /memory-recall \"yesterday's architectural discussions\"\n```\n\n#### `/memory-search` - Tag and Content Search\n\nSearch through stored memories using tags, content keywords, and semantic similarity.\n\n```bash\nclaude /memory-search --tags \"architecture,database\"\nclaude /memory-search \"SQLite performance optimization\"\n```\n\n#### `/memory-context` - Session Context Integration\n\nCapture the current conversation and project context as a memory.\n\n```bash\nclaude /memory-context\nclaude /memory-context --summary \"Architecture planning session\"\n```\n\n#### `/memory-health` - Service Health Check\n\nCheck the health and status of the MCP Memory Service.\n\n```bash\nclaude /memory-health\nclaude /memory-health --detailed\n```\n\n## Claude Hooks Configuration\n\nThe hooks system provides automatic memory capture during Claude Code sessions:\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n### Hook Types\n\n| Hook | Trigger | Action |\n|------|---------|--------|\n| `session-start` | Claude Code launch | Load relevant project memories |\n| `session-end` | Claude Code exit | Store insights and decisions |\n| `auto-capture` | Automatic capture trigger | Capture important context |\n| `mid-conversation` | Periodic intervals | Summarize and store progress |\n\n### Configuration File\n\nEdit `~/.claude/hooks/config.json` to customize hook behavior:\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"optional-api-key\"\n },\n \"hooks\": {\n \"verbose\": true,\n \"showMemoryDetails\": false,\n \"cleanMode\": false,\n \"autoCapture\": true,\n \"forceRemember\": \"#remember\",\n \"forceSkip\": \"#skip\",\n \"applyTo\": [\"auto-capture\", \"session-start\", \"mid-conversation\", \"session-end\"]\n }\n}\n```\n\n### Verbosity Levels\n\n| Level | Settings | Output |\n|-------|----------|--------|\n| Normal | `verbose: true`, others `false` | Essential information only |\n| Detailed | `showMemoryDetails: true` | Includes memory scoring details |\n| Clean | `cleanMode: true` | Minimal output, success/error only |\n| Silent | `verbose: false` | Background operation only |\n\n## Multi-Machine Synchronization\n\nFor users working across multiple machines, the service supports database synchronization:\n\n资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n\n### Export/Import Workflow\n\n```mermaid\ngraph TD\n A[Machine A] -->|export| B[JSON File]\n B -->|import| C[Machine B]\n B -->|import| D[Machine C]\n \n E[Central Database] -->|replicate| A\n E -->|replicate| C\n```\n\n### Export Command\n\n```bash\npython scripts/sync/export_memories.py \\\n --source-db ~/.local/share/mcp-memory/sqlite_vec.db \\\n --output ~/memories-export.json \\\n --machine-name \"workstation-1\"\n```\n\n### Import Command\n\n```bash\npython scripts/sync/import_memories.py \\\n --input ~/memories-export.json \\\n --target-db ~/.local/share/mcp-memory/sqlite_vec.db\n```\n\n### Deduplication\n\nMemories are deduplicated based on content hash during import:\n\n- **Same content hash**: Treated as duplicate, skipped\n- **Different content hash**: Imported as unique memory\n- **Original timestamps**: Preserved from source\n- **Source machine tags**: Added automatically for tracking\n\n### Litestream Configuration\n\nFor continuous database replication, configure Litestream:\n\n```yaml\ndbs:\n - path: ~/.local/share/mcp-memory/sqlite_vec.db\n replicas:\n - url: s3://your-bucket/memory-db\n sync-interval: 1s\n```\n\n## Verification\n\n### Verify Hook Installation\n\n```bash\nclaude --debug hooks\n```\n\nExpected output: `Found 1 hook matchers in settings`\n\n### Run Integration Tests\n\n```bash\ncd ~/.claude/hooks\nnode tests/integration-test.js\n```\n\nExpected: All 14 integration tests pass\n\n### Test API Endpoints\n\n```bash\n# Health check\ncurl -s https://localhost:8443/api/health | jq\n\n# Store a test memory\ncurl -X POST https://localhost:8443/api/memories \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Test memory from quick start\", \"tags\": [\"test\"]}'\n\n# Search memories\ncurl -X POST https://localhost:8443/api/search \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"test\", \"limit\": 5}'\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Hooks not detected | Verify `~/.claude/settings.json` exists; reinstall if missing |\n| JSON parse errors | Update to latest version with Python dict conversion |\n| Connection failed | Check `curl -k https://your-endpoint:8443/api/health` |\n| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |\n\n### Debug Mode\n\nEnable verbose debugging:\n\n```bash\n# Claude hooks debug\nclaude --debug hooks\n\n# Individual hook testing\nnode ~/.claude/hooks/core/session-start.js\n```\n\n### Windows-Specific Considerations\n\n- **Directory Structure**: Hooks install to `%USERPROFILE%\\.claude\\hooks\\`\n- **JSON Path Format**: Use backslashes or forward slashes\n- **Python Executable**: Ensure Python is in PATH\n\n## Performance Characteristics\n\nThe service is optimized for low-latency operations:\n\n| Operation | First Call | Subsequent Calls |\n|-----------|------------|-------------------|\n| Search | ~50ms | ~5-10ms |\n| Store | ~50ms | ~5-10ms |\n| Health Check | ~5ms | ~1ms |\n\n| Metric | Value |\n|--------|-------|\n| Memory Overhead | <10MB |\n| Cost per 10-user deployment | ~$16.43/year |\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## Next Steps\n\nAfter completing this quick start guide, consider exploring:\n\n- **API Reference**: Full endpoint documentation at `/api/docs`\n- **Maintenance Scripts**: Database cleanup and type consolidation tools in `scripts/maintenance/`\n- **Advanced Configuration**: Backend switching and hybrid deployment options\n- **Claude Hooks Customization**: Fine-tune auto-capture behavior and verbosity levels\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Storage Backends](#storage-backends), [Knowledge Graph and Entity Extraction](#knowledge-graph), [Memory Consolidation Engine](#consolidation-engine)\n\n\nRelated Source Files
\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_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.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- [src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)\n- [docs/architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture.md)\n \n\n# System Architecture\n\n## Overview\n\nThe MCP Memory Service is a semantic memory service built on the Model Context Protocol (MCP). It provides storage, retrieval, and search capabilities for AI-assisted workflows by maintaining a persistent vector-based memory store with automatic embedding generation.\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:1-20](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\nThe architecture follows a layered design pattern with clear separation between the MCP protocol layer, business logic services, and storage abstraction layer.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n Claude[Claude Code]\n CLI[CLI Client]\n HTTP[HTTP Client]\n MCP[MCP Client]\n end\n\n subgraph \"Interface Layer\"\n FastAPI[FastAPI Server]\n MCP_Server[MCP Server]\n CLI_Interface[CLI Interface]\n end\n\n subgraph \"Service Layer\"\n Memory_Service[Memory Service]\n Graph_Service[Graph Service]\n Response_Limiter[Response Limiter]\n end\n\n subgraph \"Storage Layer\"\n Factory[Storage Factory]\n SQLiteVec[sqlite_vec]\n Litestream[Litestream Sync]\n end\n\n Client_Layer --> Interface_Layer\n Claude --> MCP_Server\n CLI --> CLI_Interface\n HTTP --> FastAPI\n\n Interface_Layer --> Service_Layer\n Memory_Service --> Factory\n Graph_Service --> Factory\n Factory --> SQLiteVec\n SQLiteVec --> Litestream\n```\n\n## Core Components\n\n### MCP Server\n\nThe MCP Server (`mcp_server.py`) implements the Model Context Protocol, allowing AI assistants like Claude Code to interact with the memory service directly through standardized MCP tools.\n\n**Key responsibilities:**\n- Expose MCP tools for memory operations\n- Handle tool invocation requests from MCP clients\n- Coordinate with the Memory Service for all operations\n\n**资料来源：[src/mcp_memory_service/mcp_server.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)**\n\n### Server Implementation\n\nThe `server_impl.py` serves as the primary server implementation, providing the HTTP/REST interface alongside MCP support.\n\n**资料来源：[src/mcp_memory_service/server_impl.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)**\n\n### Memory Service\n\nThe Memory Service (`memory_service.py`) is the core business logic layer that handles:\n\n| Operation | Description |\n|-----------|-------------|\n| `store()` | Store new memories with automatic embedding generation |\n| `search()` | Semantic similarity search using vector embeddings |\n| `recall()` | Time-based memory retrieval with natural language expressions |\n| `delete()` | Remove memories and their associated embeddings |\n| `list_memories()` | Paginated listing of all memories |\n\n**资料来源：[src/mcp_memory_service/services/memory_service.py:1-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py)**\n\n### Graph Service\n\nThe Graph Service (`graph_service.py`) manages relationship tracking between memories, enabling complex queries about memory connections and dependencies.\n\n**资料来源：[src/mcp_memory_service/services/graph_service.py:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py)**\n\n## Storage Architecture\n\n### Storage Factory Pattern\n\nThe storage layer uses a factory pattern (`storage/factory.py`) to abstract the underlying database implementation:\n\n```mermaid\ngraph LR\n Factory[Storage Factory] -->|Creates| SQLiteVec_Storage[SQLite Vec Storage]\n Factory -->|Creates| InMemory_Storage[In-Memory Storage]\n \n SQLiteVec_Storage -->|Uses| SQLite[(SQLite with vec extension)]\n InMemory_Storage -->|Uses| RAM[(In-Memory)]\n```\n\n**资料来源：[src/mcp_memory_service/storage/factory.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)**\n\n### SQLite Vec Backend\n\nThe default storage backend uses `sqlite_vec`, which provides:\n\n- **Vector storage**: Native support for embedding storage and similarity search\n- **SQLite reliability**: ACID transactions, proven durability\n- **Low overhead**: <10MB memory footprint\n- **Performance**: ~5-10ms subsequent calls after first call initialization\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:15-18](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\n### Litestream Synchronization\n\nFor production deployments, Litestream provides continuous database replication:\n\n**资料来源：[src/mcp_memory_service/sync/litestream_config.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/sync/litestream_config.py)**\n\n| Platform | Installation Command |\n|----------|---------------------|\n| macOS | `brew install benbjohnson/litestream/litestream` |\n| Linux | `curl -LsS https://... \\| tar -xzf -` |\n| Windows | Manual download from GitHub releases |\n\n## API Architecture\n\n### REST API Endpoints\n\n**资料来源：[src/mcp_memory_service/web/app.py:30-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)**\n\n#### Memory Management\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/memories` | Store a new memory with automatic embedding generation |\n| GET | `/api/memories` | List all memories with pagination support |\n| GET | `/api/memories/{hash}` | Retrieve a specific memory by content hash |\n| DELETE | `/api/memories/{hash}` | Delete a memory and its embeddings |\n\n#### Search Operations\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/search` | Semantic similarity search using embeddings |\n| GET | `/api/search/similar/{hash}` | Find memories similar to a specific one |\n\n#### Real-time Events\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/events` | Subscribe to real-time memory events stream (SSE) |\n| GET | `/api/events/stats` | View SSE connection statistics |\n\n### Python API\n\nThe Python API provides programmatic access with low token overhead:\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# Search memories (~20 tokens)\nresults = search(\"architecture decisions\", limit=5)\n\n# Store memory (~15 tokens)\nhash = store(\"New memory\", tags=[\"note\", \"important\"])\n\n# Health check (~5 tokens)\ninfo = health()\n```\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:20-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\n## Response Management\n\n### Response Limiter\n\nThe `response_limiter.py` module prevents context window overflow by truncating responses at memory boundaries.\n\n**资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)**\n\n```mermaid\ngraph TD\n Request[Large Memory Request] --> Check{Under limit?}\n Check -->|Yes| Return_Full[Return all memories]\n Check -->|No| Truncate[Truncate at boundary]\n Truncate --> Add_Header[Add truncation header]\n Add_Header --> Return_Partial[Return partial results]\n```\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_MAX_RESPONSE_CHARS` | `0` (unlimited) | Maximum characters in responses |\n\n## CLI Architecture\n\n**资料来源：[src/mcp_memory_service/cli/main.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/cli/main.py)**\n\nThe CLI provides command-line access to all memory operations:\n\n```bash\nmemory server # Start HTTP server\nmemory health # Check service health\nmemory logs --lines 30 # Show recent log entries\n```\n\nCompatibility entry points:\n- `memory-server` (deprecated, redirects to `memory server`)\n\n## Integration Points\n\n### Claude Code Hooks\n\nThe system integrates with Claude Code through hooks that provide:\n\n- Automatic memory loading on session start\n- Context injection of relevant memories\n- Session insight storage on session end\n\n**资料来源：[claude-hooks/README.md:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)**\n\n### Claude Commands\n\nCustom slash commands for memory operations:\n\n| Command | Purpose |\n|---------|---------|\n| `/memory-save` | Save current conversation as memory |\n| `/memory-recall` | Time-based memory retrieval |\n| `/memory-search` | Tag and content search |\n| `/memory-context` | Session context integration |\n| `/memory-health` | Service health check |\n\n**资料来源：[claude_commands/README.md:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)**\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API\n participant MemoryService\n participant Storage\n participant Litestream\n\n Client->>API: Store memory request\n API->>MemoryService: Save operation\n MemoryService->>MemoryService: Generate embedding\n MemoryService->>Storage: Store content + vector\n Storage->>Litestream: Replicate to S3/GCS\n Storage-->>MemoryService: Confirmation\n MemoryService-->>API: Success response\n API-->>Client: Memory hash returned\n\n Client->>API: Search request\n API->>MemoryService: Query\n MemoryService->>MemoryService: Generate query embedding\n MemoryService->>Storage: Vector similarity search\n Storage-->>MemoryService: Top K results\n MemoryService-->>API: Ranked results\n API-->>Client: Search results\n```\n\n## Maintenance Operations\n\n### Memory Type Consolidation\n\nThe system supports consolidating fragmented memory types into a standardized taxonomy:\n\n**资料来源：[scripts/maintenance/README.md:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)**\n\n**Standard 24-Type Taxonomy:**\n- Content Types: `note`, `reference`, `document`, `guide`\n- Activity Types: `session`, `implementation`, `analysis`\n\n### Sync Export/Import\n\n**资料来源：[scripts/sync/README.md:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)**\n\n| Operation | Performance |\n|-----------|-------------|\n| Export | ~1000 memories/second |\n| Import | ~500 memories/second with deduplication |\n| File Size | ~1KB per memory |\n\n## Performance Characteristics\n\n| Metric | Value |\n|--------|-------|\n| First call latency | ~50ms (includes storage initialization) |\n| Subsequent calls | ~5-10ms (connection reused) |\n| Memory overhead | <10MB |\n| Annual cost | ~$16.43/year per 10-user deployment (at $0.15/1M tokens) |\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:12-15](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\n## Architecture Summary\n\nThe MCP Memory Service architecture is designed around three principles:\n\n1. **Separation of Concerns**: Clear boundaries between protocol handling, business logic, and storage\n2. **Multiple Interfaces**: Support for MCP, REST, Python API, and CLI access patterns\n3. **Production Ready**: Built-in replication, response limiting, and maintenance tools\n\n---\n\n\n\n## Storage Backends\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/milvus.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus.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- [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/sqlite-vec-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/sqlite-vec-backend.md)\n \n\n# Storage Backends\n\nThe mcp-memory-service project implements a **pluggable storage backend architecture** that enables users to choose between different vector database technologies for storing and searching semantic memories. This abstraction layer decouples the core memory service logic from specific database implementations, providing flexibility in deployment scenarios.\n\n## Architecture Overview\n\nThe storage system follows a factory pattern with a unified interface. All storage implementations inherit from a common base class that defines the contract for memory operations: store, retrieve, search, and delete.\n\n```mermaid\ngraph TD\n A[Memory Service] --> B[Storage Factory]\n B --> C[sqlite_vec Storage]\n B --> D[Cloudflare Storage]\n B --> E[Milvus Storage]\n B --> F[Hybrid Storage]\n \n C --> G[(Local SQLite DB)]\n D --> H[(Cloudflare D1 + Vectorize)]\n E --> I[(Milvus Collection)]\n F --> J[(Cloudflare + SQLite)]\n```\n\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\n## Supported Storage Backends\n\n| Backend | Description | Best For |\n|---------|-------------|----------|\n| `sqlite_vec` | Local SQLite database with vec0 extension | Single-user, offline-first, privacy-focused |\n| `cloudflare` | Cloudflare D1 database + Vectorize API | Cloud-native, multi-device sync |\n| `milvus` | Milvus vector database | Enterprise-scale, high-performance |\n| `hybrid` | Cloudflare + SQLite combination | Multi-device with local backup |\n\n资料来源：[docs/guides/STORAGE_BACKENDS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/STORAGE_BACKENDS.md)\n\n## Core Interface\n\nAll storage backends implement a common interface defined through the base storage class. The interface includes:\n\n### Storage Methods\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `store(memory)` | Store a new memory with embedding | Memory object with content, tags, metadata |\n| `retrieve(hash)` | Retrieve memory by content hash | content_hash: str |\n| `search(query, limit)` | Semantic search using embeddings | query: str, limit: int |\n| `search_by_tag(tags, match_all)` | Tag-based filtering | tags: list, match_all: bool |\n| `list_memories(page, page_size)` | Paginated memory listing | page: int, page_size: int |\n| `delete(hash)` | Remove memory and embeddings | content_hash: str |\n\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\n## SQLite Vec Backend\n\nThe `sqlite_vec` backend is the default and most widely-used storage option. It leverages the `sqlite-vec` extension to enable vector similarity search directly within SQLite.\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `SQLITE_VEC_DB_PATH` | `~/.local/share/mcp-memory/sqlite_vec.db` | Path to SQLite database file |\n| `EMBEDDING_MODEL_NAME` | `sentence-transformers/all-MiniLM-L6-v2` | Embedding model for vectorization |\n\n### Database Schema\n\nThe SQLite backend stores memories in a relational table with the following structure:\n\n```sql\nCREATE TABLE memories (\n content TEXT NOT NULL,\n content_hash TEXT PRIMARY KEY,\n tags TEXT,\n memory_type TEXT,\n metadata TEXT,\n created_at REAL,\n updated_at REAL,\n created_at_iso TEXT,\n updated_at_iso TEXT\n);\n\nCREATE VIRTUAL TABLE memories_embeddings USING vec0(\n content_hash TEXT PRIMARY KEY,\n embedding FLOAT[384]\n);\n```\n\n资料来源：[docs/sqlite-vec-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/sqlite-vec-backend.md)\n\n### Performance Characteristics\n\n| Metric | Value |\n|--------|-------|\n| Search latency | 5-10ms |\n| Store latency | 10-20ms (includes embedding) |\n| Memory overhead | <10MB |\n| Capacity | Limited by disk space |\n\n## Cloudflare Backend\n\nThe Cloudflare backend provides cloud-native storage using Cloudflare's D1 (SQLite-compatible) database and Vectorize (vector search) API.\n\n### Configuration\n\n| Environment Variable | Required | Description |\n|---------------------|----------|-------------|\n| `CLOUDFLARE_API_TOKEN` | Yes | Cloudflare API authentication token |\n| `CLOUDFLARE_ACCOUNT_ID` | Yes | Cloudflare account identifier |\n| `CLOUDFLARE_VECTORIZE_INDEX` | Yes | Vectorize index name |\n| `CLOUDFLARE_D1_DATABASE_ID` | Yes | D1 database identifier |\n| `CLOUDFLARE_R2_BUCKET` | No | R2 bucket for large content storage |\n| `CLOUDFLARE_EMBEDDING_MODEL` | No | Embedding model override |\n| `CLOUDFLARE_LARGE_CONTENT_THRESHOLD` | No | Size threshold for R2 storage |\n| `CLOUDFLARE_MAX_RETRIES` | No | Retry attempts for API calls |\n| `CLOUDFLARE_BASE_DELAY` | No | Initial retry delay in seconds |\n\n### Initialization\n\n```python\nstorage = CloudflareStorage(\n api_token=CLOUDFLARE_API_TOKEN,\n account_id=CLOUDFLARE_ACCOUNT_ID,\n vectorize_index=CLOUDFLARE_VECTORIZE_INDEX,\n d1_database_id=CLOUDFLARE_D1_DATABASE_ID,\n r2_bucket=CLOUDFLARE_R2_BUCKET,\n embedding_model=CLOUDFLARE_EMBEDDING_MODEL,\n large_content_threshold=CLOUDFLARE_LARGE_CONTENT_THRESHOLD,\n max_retries=CLOUDFLARE_MAX_RETRIES,\n base_delay=CLOUDFLARE_BASE_DELAY\n)\n```\n\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\n## Milvus Backend\n\nThe Milvus backend targets enterprise deployments requiring high-performance, distributed vector search capabilities.\n\n### Configuration\n\n| Environment Variable | Required | Description |\n|---------------------|----------|-------------|\n| `MILVUS_URI` | Yes | Milvus server URI |\n| `MILVUS_TOKEN` | No | Authentication token |\n| `MILVUS_COLLECTION_NAME` | No | Collection name (default: `memories`) |\n| `EMBEDDING_MODEL_NAME` | No | Embedding model |\n\n### Initialization\n\n```python\nstorage = MilvusMemoryStorage(\n uri=MILVUS_URI,\n token=MILVUS_TOKEN,\n collection_name=MILVUS_COLLECTION_NAME,\n embedding_model=EMBEDDING_MODEL_NAME,\n)\n```\n\n资料来源：[docs/milvus-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/milvus-backend.md)\n\n## Hybrid Backend\n\nThe hybrid backend combines Cloudflare storage with local SQLite-vec backup, enabling multi-device synchronization while maintaining offline capability.\n\n### Architecture\n\n```mermaid\ngraph LR\n A[Local SQLite DB] <--> B[Hybrid Storage]\n B <--> C[Cloudflare D1]\n B <--> D[Cloudflare Vectorize]\n \n E[Write Operations] --> B\n F[Read Operations] --> B\n```\n\n### Configuration\n\nThe hybrid backend requires both Cloudflare and SQLite configuration:\n\n```python\ncloudflare_config = {\n 'api_token': CLOUDFLARE_API_TOKEN,\n 'account_id': CLOUDFLARE_ACCOUNT_ID,\n 'vectorize_index': CLOUDFLARE_VECTORIZE_INDEX,\n 'd1_database_id': CLOUDFLARE_D1_DATABASE_ID,\n}\n\nstorage = HybridMemoryStorage(\n cloudflare_config=cloudflare_config,\n local_db_path=LOCAL_DB_PATH,\n)\n```\n\n## Storage Factory\n\nThe `get_storage()` function in the factory module handles backend instantiation based on configuration:\n\n```python\nasync def get_storage(backend: Optional[str] = None) -> BaseStorage:\n \"\"\"Get storage instance based on configured or specified backend.\"\"\"\n backend = backend or os.getenv(\"MCP_MEMORY_STORAGE_BACKEND\", \"sqlite_vec\")\n \n if backend == \"cloudflare\":\n return CloudflareStorage(...)\n elif backend == \"milvus\":\n return MilvusMemoryStorage(...)\n elif backend == \"hybrid\":\n return HybridMemoryStorage(...)\n else:\n return SQLiteVecStorage(...)\n```\n\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\n## HTTP Client Backend\n\nFor distributed deployments, the project supports HTTP-based storage access through an `HttpStorage` client. This enables communication with remote MCP Memory Service instances.\n\n### HTTP API Endpoints\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| POST | `/api/memories` | Store a new memory |\n| GET | `/api/memories` | List memories with pagination |\n| GET | `/api/memories/{hash}` | Retrieve specific memory |\n| DELETE | `/api/memories/{hash}` | Delete memory |\n| POST | `/api/search` | Semantic search |\n| GET | `/api/search/similar/{hash}` | Find similar memories |\n| GET | `/api/events` | SSE event stream |\n\n### Time Filter Format\n\nWhen searching by time ranges, the HTTP client converts Unix timestamps to ISO date format:\n\n```python\ndef _build_time_filter(time_start: Optional[float], time_end: Optional[float]) -> Optional[str]:\n if time_start and time_end:\n return f\"between {_to_date(time_start)} and {_to_date(time_end)}\"\n elif time_start:\n return _to_date(time_start)\n return _to_date(time_end)\n```\n\n资料来源：[src/mcp_memory_service/storage/http_client.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/http_client.py)\n\n## Backend Selection\n\n### Decision Matrix\n\n| Use Case | Recommended Backend |\n|----------|---------------------|\n| Single machine, privacy-sensitive | `sqlite_vec` |\n| Multi-device with cloud sync | `cloudflare` |\n| Enterprise with high volume | `milvus` |\n| Local backup + cloud sync | `hybrid` |\n\n### Selecting Backend via CLI\n\nWhen using the CLI for operations:\n\n```bash\n# Use SQLite backend (default)\nmemory ingest-document doc.pdf\n\n# Use Cloudflare backend\nmemory ingest-document doc.pdf --storage-backend cloudflare\n\n# Use hybrid backend\nmemory ingest-document doc.pdf --storage-backend hybrid\n```\n\n## Maintenance Operations\n\n### Embedding Migration\n\nTo migrate to a different embedding model (handles dimension changes):\n\n```bash\npython scripts/maintenance/migrate_embeddings.py --url http://localhost:8000 --model new-model --dry-run\n```\n\n### Database Repair Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `repair_memories.py` | Repair corrupted memory entries |\n| `repair_sqlite_vec_embeddings.py` | Fix embedding inconsistencies |\n| `repair_zero_embeddings.py` | Fix zero/null embeddings |\n| `cleanup_corrupted_encoding.py` | Fix corrupted emoji encoding |\n\n### Backup Strategy\n\nFor `sqlite_vec` backend, Litestream provides continuous replication:\n\n```bash\n# Configure in litestream.yml\ndbs:\n - path: ~/.local/share/mcp-memory/sqlite_vec.db\n replicas:\n - url: s3://your-bucket/mcp-memory/\n```\n\n资料来源：[scripts/sync/litestream/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/litestream/README.md)\n\n## Response Limiting\n\nAll storage backends support response size limiting through the `ResponseLimiter` utility to prevent oversized responses:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_chars` | 10000 | Maximum characters in response |\n| `max_results` | 50 | Maximum memories to return |\n\nThe limiter calculates estimated memory sizes including overhead and truncates at memory boundaries to ensure consistent response sizes.\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n---\n\n\n\n## Knowledge Graph and Entity Extraction\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Memory Consolidation Engine](#consolidation-engine), [Quality Scoring System](#quality-scoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/storage/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.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- [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- [src/mcp_memory_service/consolidation/consolidator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n \n\n# Knowledge Graph and Entity Extraction\n\n## Overview\n\nThe MCP Memory Service includes a sophisticated Knowledge Graph system that enables semantic relationships between memories, automatic entity extraction, and intelligent relationship inference. This feature transforms isolated memory entries into an interconnected knowledge network that supports advanced queries like graph traversal, entity-based retrieval, and similarity analysis.\n\nThe knowledge graph layer sits above the core memory storage, providing:\n\n- **Entity Extraction**: Automatic identification of people, organizations, locations, and concepts from memory content\n- **Relationship Mapping**: Discovery and storage of connections between memories based on semantic similarity and content analysis\n- **Graph Traversal**: Navigation of memory relationships using configurable depth and radius parameters\n- **Association Memory**: Automatic creation of memory entries that document discovered relationships between existing memories\n- **Relationship Inference**: AI-powered inference of relationship types (causes, fixes, contradicts, supports, follows)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Memory Layer\"\n M1[Memory 1]\n M2[Memory 2]\n M3[Memory 3]\n end\n\n subgraph \"Entity Extraction\"\n EE[EntityExtractor]\n NER[NER Processing]\n PAT[Pattern Matching]\n end\n\n subgraph \"Graph Storage\"\n GS[GraphStorage]\n RI[RelationshipInference]\n AM[AssociationMemory]\n end\n\n subgraph \"Query Interfaces\"\n GT[Graph Tools]\n ST[Search Tools]\n end\n\n M1 --> EE\n M2 --> EE\n M3 --> EE\n\n EE --> NER\n EE --> PAT\n\n NER --> GS\n PAT --> GS\n\n GS --> RI\n RI --> AM\n AM --> GS\n\n GT --> GS\n ST --> GS\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `EntityExtractor` | `src/mcp_memory_service/reasoning/entities.py` | Extracts entities from memory content |\n| `RelationshipInferenceEngine` | `src/mcp_memory_service/reasoning/inference.py` | Infers relationship types between memories |\n| `GraphStorage` | `src/mcp_memory_service/storage/graph.py` | SQLite-based graph storage backend |\n| `MilvusGraphStorage` | `src/mcp_memory_service/storage/milvus_graph.py` | Milvus vector database backend |\n| `MemoryConsolidator` | `src/mcp_memory_service/consolidation/consolidator.py` | Creates and manages association memories |\n| `Association` | `src/mcp_memory_service/models/association.py` | Data model for memory associations |\n\n资料来源：[src/mcp_memory_service/reasoning/entities.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)\n\n## Entity Extraction\n\n### Overview\n\nEntity extraction automatically identifies and categorizes entities within memory content. The system supports multiple entity types and uses both pattern-based and NER (Named Entity Recognition) approaches.\n\n资料来源：[src/mcp_memory_service/reasoning/entities.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)\n\n### Supported Entity Types\n\nThe system recognizes the following entity categories:\n\n| Entity Type | Description | Examples |\n|-------------|-------------|----------|\n| `person` | Human individuals | \"John\", \"Alice Chen\" |\n| `organization` | Companies, teams, agencies | \"Acme Corp\", \"Engineering Team\" |\n| `location` | Physical places | \"San Francisco\", \"Building A\" |\n| `concept` | Abstract ideas and concepts | \"machine learning\", \"agile methodology\" |\n| `technology` | Tools, frameworks, languages | \"Python\", \"React\", \"Docker\" |\n| `date` | Temporal references | \"December 2024\", \"Q1\" |\n| `project` | Named projects or initiatives | \"Project Alpha\", \"Apollo Initiative\" |\n\n### Extraction Process\n\n```mermaid\ngraph LR\n A[Memory Content] --> B[Pattern Matching]\n A --> C[NER Processing]\n B --> D[Entity Deduplication]\n C --> D\n D --> E[Entity Metadata]\n E --> F[Store Entity Links]\n```\n\nThe extraction process follows these steps:\n\n1. **Pattern Matching**: Initial scan for known patterns (email, URL, date formats, capitalization patterns)\n2. **NER Processing**: Language model-based entity recognition for contextual entity types\n3. **Entity Deduplication**: Normalization and merging of duplicate entities\n4. **Metadata Generation**: Creation of entity metadata including confidence scores\n5. **Storage**: Persisting entity links to the graph storage\n\n### MCP Tool Interface\n\nEntities can be extracted and stored via the MCP `memory_graph` tool:\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:50-75](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n```json\n{\n \"action\": \"extract_entities\",\n \"hash\": \"abc123def456\"\n}\n```\n\n**Response Example:**\n```json\n{\n \"hash\": \"abc123def456\",\n \"entities_extracted\": 5,\n \"entities\": [\n {\"name\": \"Python\", \"type\": \"technology\", \"confidence\": 0.95},\n {\"name\": \"FastAPI\", \"type\": \"technology\", \"confidence\": 0.92}\n ]\n}\n```\n\n## Knowledge Graph Storage\n\n### Storage Backends\n\nThe knowledge graph supports multiple storage backends:\n\n| Backend | File | Use Case |\n|---------|------|----------|\n| SQLite Graph | `src/mcp_memory_service/storage/graph.py` | Default, single-node deployments |\n| Milvus Graph | `src/mcp_memory_service/storage/milvus_graph.py` | Large-scale, distributed deployments |\n\n资料来源：[src/mcp_memory_service/storage/graph.py:1-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)\n\n### Graph Data Model\n\nThe graph storage maintains the following data structures:\n\n#### Entities Table\nStores extracted entities linked to memories:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `entity_id` | TEXT | Unique entity identifier |\n| `name` | TEXT | Entity name |\n| `entity_type` | TEXT | Entity category |\n| `memory_hash` | TEXT | Associated memory hash |\n| `confidence` | REAL | Extraction confidence score |\n\n#### Relationships Table\nStores relationships between memories:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `relationship_id` | TEXT | Unique relationship identifier |\n| `source_hash` | TEXT | Source memory hash |\n| `target_hash` | TEXT | Target memory hash |\n| `relationship_type` | TEXT | Type (similar, causes, fixes, etc.) |\n| `similarity_score` | REAL | Calculated similarity (0.0-1.0) |\n| `metadata` | JSON | Additional relationship metadata |\n\n资料来源：[src/mcp_memory_service/models/association.py:1-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/association.py)\n\n### Graph Operations\n\n#### Store Entity Link\n\n```python\nasync def store_entity_link(\n memory_hash: str,\n entity_name: str,\n entity_type: str\n) -> bool:\n```\n\nLinks an extracted entity to a memory for future retrieval and graph queries.\n\n资料来源：[src/mcp_memory_service/storage/graph.py:150-180](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)\n\n#### Get Memory Subgraph\n\nRetrieves a local subgraph centered on a specific memory:\n\n```python\nasync def get_memory_subgraph(\n memory_hash: str,\n radius: int = 2\n) -> Dict[str, Any]:\n```\n\nParameters:\n- `memory_hash`: Center memory for subgraph traversal\n- `radius`: Maximum traversal depth (default: 2)\n\n#### Graph Traversal\n\n```python\nasync def traverse_graph(\n hash1: str,\n hash2: str,\n max_depth: int = 5\n) -> List[Dict[str, Any]]:\n```\n\nFinds paths between two memories up to a specified depth.\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:20-45](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n## Relationship Inference\n\n### RelationshipInferenceEngine\n\nThe relationship inference engine analyzes memory content pairs to determine semantic relationships:\n\n资料来源：[src/mcp_memory_service/reasoning/inference.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/inference.py)\n\n### Supported Relationship Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `causes` | Source leads to target | \"Changed config\" → \"System crashed\" |\n| `fixes` | Source resolves target | \"Applied patch\" → \"Bug #123\" |\n| `contradicts` | Sources conflict | \"Use X\" vs \"Don't use X\" |\n| `supports` | Source validates target | \"Test results\" → \"Implementation works\" |\n| `follows` | Temporal sequence | \"Phase 1 complete\" → \"Phase 2 started\" |\n| `related` | General connection | Topic similarity without specific type |\n\n### Inference Process\n\n```mermaid\ngraph TD\n M1[Memory 1] --> C1[Content Analysis]\n M2[Memory 2] --> C2[Content Analysis]\n C1 --> SIM[Similarity Check]\n C2 --> SIM\n SIM --> RT{Relationship Type?}\n RT -->|High Similarity| SA[Same Aspect]\n RT -->|Causal Keywords| CA[Causal Link]\n RT -->|Action Keywords| AC[Action Link]\n RT -->|Negation| CN[Contradiction]\n SA --> ST[Store Relationship]\n CA --> ST\n AC --> ST\n CN --> ST\n```\n\n## Association Memory\n\n### Overview\n\nAssociation memories are automatically generated entries that document discovered relationships between existing memories. They provide a memory-level representation of graph connections, enabling search and retrieval of relationship information.\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:150-200](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n\n### Association Data Model\n\n```python\nclass Association:\n source_memory_hashes: List[str]\n similarity_score: float\n connection_type: str\n discovery_method: str\n discovery_date: datetime\n metadata: Dict[str, Any]\n```\n\n### Association Memory Structure\n\nWhen an association is stored as a memory:\n\n```python\nassociation_memory = Memory(\n content=f\"Connected {source_hashes[0][:8]} and {source_hashes[1][:8]} by {connection_type}\",\n content_hash=f\"assoc_{source_hashes[0][:8]}_{source_hashes[1][:8]}\",\n tags=[\"association\", \"discovered\", connection_type],\n memory_type=\"observation\",\n metadata={\n \"source_memory_hashes\": source_hashes,\n \"similarity_score\": similarity,\n \"connection_type\": connection_type,\n \"discovery_method\": association.discovery_method,\n \"discovery_date\": association.discovery_date.isoformat(),\n }\n)\n```\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:170-195](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n\n### Storage Process\n\n```mermaid\ngraph LR\n A[Memory Pair] --> B[Similarity Analysis]\n B --> C{Score >= Threshold?}\n C -->|Yes| D[Type Classification]\n C -->|No| E[Skip]\n D --> F[Create Association]\n F --> G[Store Association Memory]\n G --> H[Update Graph]\n```\n\nThe consolidator stores association memories with `skip_semantic_dedup=True` to prevent deduplication conflicts with templated content.\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:195-210](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n\n## MCP Tools Reference\n\n### memory_graph\n\nMain tool for graph operations:\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `action` | string | Yes | Operation: `traverse`, `subgraph`, `extract_entities` |\n| `hash` | string | Conditional | Memory hash for subgraph/entities actions |\n| `hash1` | string | Conditional | Source hash for traversal |\n| `hash2` | string | Conditional | Target hash for traversal |\n| `radius` | integer | No | Subgraph radius (default: 2) |\n| `max_depth` | integer | No | Traversal max depth (default: 5) |\n\n#### Action Examples\n\n**Extract Entities:**\n```json\n{\n \"action\": \"extract_entities\",\n \"hash\": \"memory_hash_here\"\n}\n```\n\n**Get Subgraph:**\n```json\n{\n \"action\": \"subgraph\",\n \"hash\": \"memory_hash_here\",\n \"radius\": 3\n}\n```\n\n**Traverse Graph:**\n```json\n{\n \"action\": \"traverse\",\n \"hash1\": \"memory_hash_1\",\n \"hash2\": \"memory_hash_2\",\n \"max_depth\": 5\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n## Maintenance Scripts\n\n### update_graph_relationship_types.py\n\nLocated in `scripts/maintenance/`, this script infers relationship types for existing graph associations:\n\n```bash\n# Dry run (preview changes)\npython scripts/maintenance/update_graph_relationship_types.py --dry-run\n\n# Execute inference\npython scripts/maintenance/update_graph_relationship_types.py\n```\n\n**Features:**\n- Uses `RelationshipInferenceEngine` for type inference\n- Supports dry-run mode for safety\n- Automatic backup before execution\n- Updates relationship metadata in graph storage\n\n资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n\n## Configuration\n\n### Graph Storage Configuration\n\nThe graph storage is automatically initialized when the storage service starts. No explicit configuration is required for SQLite-based storage.\n\nFor Milvus-based storage, configure the following environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MILVUS_HOST` | Milvus server host | localhost |\n| `MILVUS_PORT` | Milvus server port | 19530 |\n| `MILVUS_COLLECTION` | Collection name | memory_graph |\n\n### Entity Extraction Configuration\n\nEntity extraction settings can be configured in the service configuration:\n\n| Setting | Type | Description |\n|---------|------|-------------|\n| `entity_types` | List[str] | Enabled entity types |\n| `min_confidence` | float | Minimum confidence threshold (0.0-1.0) |\n| `enable_ner` | bool | Enable NER processing |\n| `pattern_weight` | float | Weight for pattern matching |\n\n## Error Handling\n\nThe graph operations return standardized error responses:\n\n```json\n{\n \"error\": \"Error message describing the issue\"\n}\n```\n\nCommon error scenarios:\n- Memory not found for entity extraction\n- Graph storage not initialized\n- Invalid hash format\n- Maximum depth exceeded during traversal\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:55-65](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n## Best Practices\n\n1. **Entity Naming**: Use consistent entity naming conventions for better graph queries\n2. **Memory Organization**: Group related content in the same memory to strengthen association discovery\n3. **Regular Maintenance**: Run `update_graph_relationship_types.py` periodically to classify new associations\n4. **Tag Usage**: Tag memories with semantic tags to improve entity and relationship extraction\n5. **Graph Traversal**: Use appropriate radius/depth limits to prevent performance issues with highly connected memories\n\n## See Also\n\n- [Memory Storage](storage-overview.md) - Core memory storage architecture\n- [Consolidation System](consolidation.md) - Association memory generation\n- [Reasoning Engine](reasoning.md) - Entity extraction and inference details\n- [Maintenance Scripts](../scripts/maintenance/README.md) - Graph maintenance utilities\n\n---\n\n\n\n## Memory Consolidation Engine\n\n### 相关页面\n\n相关主题：[Knowledge Graph and Entity Extraction](#knowledge-graph), [Quality Scoring System](#quality-scoring), [System Architecture](#architecture)\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/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/insights.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/insights.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# Memory Consolidation Engine\n\nThe Memory Consolidation Engine is a core subsystem of the MCP Memory Service that manages the lifecycle of stored memories through intelligent compression, decay analysis, and selective forgetting mechanisms. It ensures the memory store remains efficient, relevant, and optimized for long-term semantic retrieval.\n\n## Overview\n\nAs memories accumulate over time, the consolidation engine performs background operations to:\n\n- **Compress redundant memories** into consolidated summaries\n- **Apply decay algorithms** to age out less relevant information\n- **Forget obsolete entries** based on configurable time horizons\n- **Generate insights** from consolidated memory patterns\n\n```mermaid\ngraph TD\n A[New Memory] --> B[Memory Store]\n B --> C{Consolidation Scheduler}\n C --> D[Decay Analysis]\n C --> E[Compression]\n C --> F[Forgetting Check]\n D --> G[Relevance Score Update]\n E --> H[Consolidated Memory]\n F --> I[Memory Deletion]\n G --> H\n H --> J[Insights Generation]\n J --> K[Updated Memory Store]\n```\n\n## Architecture\n\nThe consolidation engine comprises five primary modules located in `src/mcp_memory_service/consolidation/`:\n\n| Module | Purpose | Key Functions |\n|--------|---------|---------------|\n| `consolidator.py` | Core consolidation orchestration | Main consolidation loop, memory merging |\n| `scheduler.py` | Automated scheduling of consolidation tasks | Daily, weekly, monthly job scheduling |\n| `decay.py` | Relevance decay calculations | Age-based score reduction algorithms |\n| `forgetting.py` | Selective memory removal | Time-horizon based forgetting policies |\n| `insights.py` | Post-consolidation analysis | Pattern detection, summary generation |\n\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\n## Consolidation Time Horizons\n\nThe engine operates on three configurable time horizons that determine consolidation aggressiveness:\n\n### Weekly Consolidation\n- Processes recent memories (typically 7 days)\n- Light compression to maintain detail\n- Preserves high-relevance memories unchanged\n\n### Monthly Consolidation\n- Reviews memories from past 30 days\n- Moderate compression and decay application\n- Identifies patterns across recent sessions\n\n### Quarterly Consolidation\n- Full store analysis\n- Aggressive forgetting of stale entries\n- Major compression of redundant information\n\n资料来源：[src/mcp_memory_service/api/operations.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n\n## API Integration\n\n### REST API Endpoint\n\n```\nPOST /api/consolidate\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `time_horizon` | string | Yes | One of: `daily`, `weekly`, `monthly` |\n\n**Example Request:**\n```bash\ncurl -X POST https://localhost:8443/api/consolidate \\\n -H \"Content-Type: application/json\" \\\n -d '{\"time_horizon\": \"weekly\"}'\n```\n\n**Example Response:**\n```json\n{\n \"status\": \"completed\",\n \"time_horizon\": \"weekly\",\n \"memories_processed\": 2418,\n \"compressed\": 156,\n \"forgotten\": 43\n}\n```\n\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\n### Python API\n\n```python\nfrom mcp_memory_service.api import consolidate\n\n# Async consolidation\nresult = await consolidate('weekly')\nprint(f\"Compressed: {result.compressed}, Forgotten: {result.forgotten}\")\n```\n\n**Return Value Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `status` | string | Completion status |\n| `time_horizon` | string | Horizon used |\n| `memories_processed` | int | Total memories reviewed |\n| `compressed` | int | Number of memories consolidated |\n| `forgotten` | int | Number of memories deleted |\n\n## Scheduler Configuration\n\nThe consolidation scheduler runs automated tasks based on configured schedules:\n\n```mermaid\ngraph LR\n A[Scheduler Init] --> B{Job Queue}\n B --> C[Daily Job
T+00:00]\n B --> D[Weekly Job
Sunday T+02:00]\n B --> E[Monthly Job
1st T+03:00]\n```\n\n**Scheduler Status Model:**\n\n```python\nCompactSchedulerStatus:\n running: bool\n next_daily: datetime | None\n next_weekly: datetime | None\n next_monthly: datetime | None\n jobs_executed: int\n jobs_failed: int\n```\n\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\n## Decay Algorithm\n\nThe decay module applies relevance scoring based on memory age and access patterns:\n\n```python\ndef calculate_decay_score(memory_age_days: int, access_frequency: float) -> float:\n \"\"\"\n Returns relevance score between 0.0 and 1.0\n Lower scores indicate memories approaching forgetting threshold\n \"\"\"\n```\n\n**Decay Factors:**\n\n| Factor | Description | Weight |\n|--------|-------------|--------|\n| Time Since Creation | Older memories decay faster | 0.4 |\n| Access Frequency | Frequently accessed memories decay slower | 0.3 |\n| Tag Relevance | Tagged memories maintain higher scores | 0.2 |\n| Memory Type | System vs user memory decay rates differ | 0.1 |\n\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\n## Forgetting Mechanism\n\nThe forgetting module determines which memories should be permanently removed:\n\n```python\ndef should_forget(memory: Memory, horizon: str) -> bool:\n \"\"\"\n Evaluates if a memory meets forgetting criteria\n Returns True if memory should be deleted\n \"\"\"\n```\n\n**Forgetting Criteria by Horizon:**\n\n| Horizon | Age Threshold | Min Decay Score | Additional Checks |\n|---------|--------------|-----------------|-------------------|\n| `daily` | 90 days | 0.1 | None |\n| `weekly` | 180 days | 0.2 | Duplicate detection |\n| `monthly` | 365 days | 0.3 | Pattern analysis |\n\n**Safety Features:**\n- Automatic backup before deletion\n- Transaction-based deletion (atomic rollback on failure)\n- Database lock detection to prevent concurrent access issues\n- Disk space verification before execution\n\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\n## Performance Characteristics\n\n| Metric | Value |\n|--------|-------|\n| Typical Duration | 10-30 seconds (varies with memory count) |\n| Scaling | ~10ms per memory processed |\n| Memory Overhead | <10MB during operation |\n| Background Operation | Non-blocking in HTTP server context |\n\n**Performance Tips:**\n- Schedule consolidation during low-usage periods\n- Large stores (>10,000 memories) may take longer\n- Disable automatic scheduling for resource-constrained environments\n\n## Insights Generation\n\nAfter consolidation, the insights module analyzes patterns:\n\n```python\ndef generate_insights(consolidated_memories: List[Memory]) -> List[Insight]:\n \"\"\"\n Produces actionable insights from consolidated memory patterns\n \"\"\"\n```\n\n**Insight Types:**\n\n| Type | Description |\n|------|-------------|\n| `pattern` | Recurring themes detected |\n| `summary` | Condensed representation of grouped memories |\n| `recommendation` | Suggestions based on memory patterns |\n| `conflict` | Detected contradictions between memories |\n\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\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_CONSOLIDATION_ENABLED` | `true` | Enable/disable automatic consolidation |\n| `MCP_CONSOLIDATION_SCHEDULE` | `daily` | Default schedule |\n| `MCP_MAX_RESPONSE_CHARS` | `0` | Response truncation (0 = unlimited) |\n\n### Scheduler Settings\n\nConfigure in `~/.claude/hooks/config.json`:\n\n```json\n{\n \"consolidation\": {\n \"schedule\": {\n \"daily\": \"0 0 * * *\",\n \"weekly\": \"0 2 * * 0\",\n \"monthly\": \"0 3 1 * *\"\n },\n \"enabled\": true,\n \"horizons\": [\"daily\", \"weekly\"]\n }\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Consolidation fails silently | Database locked | Stop MCP clients before running |\n| High memory usage during consolidation | Large store size | Increase `MCP_MAX_RESPONSE_CHARS` |\n| Scheduler not running | Service not started | Check `systemctl --user status mcp-memory.service` |\n\n### Verification\n\n```bash\n# Check scheduler status\ncurl https://localhost:8443/api/consolidate/status\n\n# Manual consolidation (dry-run)\ncurl -X POST https://localhost:8443/api/consolidate \\\n -d '{\"time_horizon\": \"weekly\", \"dry_run\": true}'\n```\n\n## Further Reference\n\n- [Memory Consolidation Guide](docs/guides/memory-consolidation-guide.md) - Detailed usage documentation\n- [API Reference](src/mcp_memory_service/api/operations.py) - Full API specification\n- [CLI Commands](claude_commands/README.md) - Command-line consolidation tools\n\n---\n\n\n\n## Quality Scoring System\n\n### 相关页面\n\n相关主题：[Memory Consolidation Engine](#consolidation-engine), [System Architecture](#architecture), [Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/quality/\\_\\_init\\_\\_.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/__init__.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/scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/scorer.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/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/quality/config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/config.py)\n- [src/mcp_memory_service/server/handlers/quality.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)\n \n\n# Quality Scoring System\n\nThe Quality Scoring System is a multi-layered evaluation framework within the MCP Memory Service that assesses, ranks, and maintains memory content quality. It provides both automatic quality assessment through machine learning models and explicit user feedback mechanisms to ensure that memories retain high-value information over time.\n\n## Overview\n\nThe system addresses a fundamental challenge in semantic memory systems: not all stored memories have equal importance or relevance. Over time, memory stores can become cluttered with transient information, low-value summaries, and outdated content that degrades the overall utility of the memory service.\n\nThe Quality Scoring System solves this by implementing:\n\n- **Automatic Quality Assessment**: Uses ONNX-based ML models to evaluate content quality without manual intervention\n- **Implicit Signal Detection**: Analyzes behavioral patterns to infer memory importance\n- **Manual Rating Support**: Allows users to explicitly rate memory quality\n- **Quality-Aware Search**: Boosts high-quality memories in search results\n- **Maintenance Operations**: Provides tools for quality-based memory management\n\n## Architecture\n\nThe Quality Scoring System follows a modular architecture with four primary components that work together to provide comprehensive quality evaluation.\n\n```mermaid\ngraph TD\n A[Memory Content] --> B[QualityScorer]\n B --> C[ONNXRankerModel]\n B --> D[QualityEvaluator]\n B --> E[ImplicitSignalsEvaluator]\n \n C --> F[CompactSearchResult]\n D --> F\n E --> F\n \n G[User Rating] --> H[handle_rate_memory]\n H --> B\n \n I[Search Query] --> J[quality_boost Parameter]\n J --> F\n \n K[Maintenance Operations] --> L[handle_maintain]\n L --> B\n```\n\n## Core Components\n\n### QualityConfig\n\nThe `QualityConfig` class provides centralized configuration for the quality scoring system. It defines thresholds, weights, and behavioral parameters that control how quality is evaluated.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `min_quality` | float | 0.0 | Minimum quality threshold for inclusion |\n| `max_quality` | float | 1.0 | Maximum possible quality score |\n| `boost_weight` | float | varies | Weight given to quality in search ranking |\n| `implicit_weight` | float | varies | Weight for implicit signal evaluation |\n\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\n### QualityScorer\n\nThe `QualityScorer` is the main orchestrator class that coordinates quality evaluation across all sub-components. It aggregates scores from different evaluation methods and produces a unified quality score.\n\n```python\nclass QualityScorer:\n def __init__(self, config: QualityConfig):\n self.config = config\n self.ranker = ONNXRankerModel()\n self.evaluator = QualityEvaluator()\n self.implicit_evaluator = ImplicitSignalsEvaluator()\n```\n\n**Key Responsibilities:**\n- Aggregates scores from ONNX ranker, AI evaluator, and implicit signals\n- Provides a unified `get_score()` interface\n- Handles caching and optimization for repeated evaluations\n- Manages configuration propagation to sub-components\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\n### ONNXRankerModel\n\nThe `ONNXRankerModel` provides fast, offline-capable quality ranking using ONNX Runtime. This model evaluates content based on learned patterns of what constitutes high-quality memory content.\n\n**Advantages of ONNX-based ranking:**\n- Runs entirely offline without external API dependencies\n- Fast inference suitable for real-time evaluation\n- Portable across different platforms and hardware\n- No per-token costs unlike cloud-based alternatives\n\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\n### QualityEvaluator\n\nThe `QualityEvaluator` provides AI-based quality assessment, likely utilizing more sophisticated language model analysis for nuanced content quality determination.\n\n**Evaluation Criteria:**\n- Content specificity and detail level\n- Actionability of information\n- Temporal relevance\n- Uniqueness of content\n\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\n### ImplicitSignalsEvaluator\n\nThe `ImplicitSignalsEvaluator` analyzes behavioral patterns to infer memory importance without explicit user feedback. This component detects signals that suggest a memory's value based on how it's accessed and used.\n\n**Implicit Signals:**\n- Retrieval frequency\n- Retrieval timing patterns\n- Context of retrieval requests\n- Cross-referencing with other memories\n\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\n## Module Exports\n\nAll quality scoring components are exported through the main quality module interface:\n\n```python\nfrom mcp_memory_service.quality import (\n QualityScorer,\n ONNXRankerModel,\n QualityEvaluator,\n ImplicitSignalsEvaluator,\n QualityConfig\n)\n```\n\n资料来源：[src/mcp_memory_service/quality/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/__init__.py)\n\n## API Integration\n\n### Quality-Aware Search\n\nThe quality scoring system integrates with the search API through the `quality_boost` parameter. When performing semantic or hybrid searches, memories with higher quality scores receive ranking boosts.\n\n**Search Parameters Related to Quality:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `quality_boost` | float | 0.0 | Weight for quality-based ranking (0.0-1.0) |\n| `min_quality` | float | 0.0 | Minimum quality threshold filter |\n| `include_debug` | bool | false | Include quality scoring details in response |\n\n**Implementation in Memory Handler:**\n```python\nquality_boost=arguments.get(\"quality_boost\", 0.0),\nlimit=limit,\ninclude_debug=arguments.get(\"include_debug\", False),\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py:26-32](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### Quality Scoring in Results\n\nThe `CompactSearchResult` type includes a `score` field that represents the relevance score, which incorporates quality assessment when `quality_boost` is enabled.\n\n**CompactMemory Score Field:**\n```python\nclass CompactMemory(NamedTuple):\n hash: str # 8-character content hash\n preview: str # First 200 characters\n tags: tuple[str, ...] # Immutable tags tuple\n created: float # Unix timestamp\n score: float # Relevance score 0-1\n```\n\n资料来源：[src/mcp_memory_service/api/types.py:48-56](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/types.py)\n\n## Quality Actions Handler\n\nThe quality system exposes several actions through the `memory_quality` tool handler, providing programmatic access to quality operations.\n\n### Action Types\n\n| Action | Description | Required Parameters |\n|--------|-------------|---------------------|\n| `rate` | Manually rate a memory's quality | `content_hash`, `rating` |\n| `analyze` | Analyze quality distribution | `min_quality`, `max_quality` |\n| `maintain` | Run quality-based maintenance | varies |\n| `maintain_status` | Check maintenance status | none |\n\n### Rate Memory Action\n\nAllows explicit user feedback on memory quality:\n\n```python\nasync def handle_rate_memory(server, arguments: dict) -> List[types.TextContent]:\n content_hash = arguments.get(\"content_hash\")\n rating = arguments.get(\"rating\")\n feedback = arguments.get(\"feedback\", \"\")\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content_hash` | string | Yes | Hash of the memory to rate |\n| `rating` | integer/string | Yes | Quality rating (converted to integer) |\n| `feedback` | string | No | Optional feedback text |\n\n资料来源：[src/mcp_memory_service/server/handlers/quality.py:47-59](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)\n\n### Analyze Quality Distribution\n\nProvides statistical analysis of memory quality across the store:\n\n```python\nelif action == \"analyze\":\n return await handle_analyze_quality_distribution(server, {\n \"min_quality\": arguments.get(\"min_quality\", 0.0),\n \"max_quality\": arguments.get(\"max_quality\", 1.0)\n })\n```\n\n### Maintenance Operations\n\nThe maintain action provides automated quality-based memory management:\n\n```python\nelif action == \"maintain\":\n return await handle_maintain(server, arguments)\n\nelif action == \"maintain_status\":\n return await handle_maintain_status()\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/quality.py:30-38](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)\n\n## Workflow Diagrams\n\n### Quality Evaluation Flow\n\n```mermaid\ngraph LR\n A[Incoming Memory] --> B{Is cached?}\n B -->|No| C[Run ONNX Ranker]\n C --> D[Run AI Evaluator]\n D --> E[Run Implicit Signals]\n E --> F[Aggregate Scores]\n F --> G[Compute Final Quality]\n G --> H[Cache Result]\n H --> I[Return Score]\n \n B -->|Yes| I\n```\n\n### Quality-Aware Search Flow\n\n```mermaid\ngraph TD\n A[Search Query] --> B[Semantic Search]\n B --> C[Initial Results]\n C --> D{quality_boost > 0?}\n D -->|Yes| E[Fetch Quality Scores]\n D -->|No| H[Return Results]\n E --> F[Apply Quality Boost]\n F --> G[Re-rank Results]\n G --> H\n```\n\n## Usage Examples\n\n### Basic Quality Evaluation\n\n```python\nfrom mcp_memory_service.quality import QualityScorer, QualityConfig\n\nconfig = QualityConfig(min_quality=0.5, boost_weight=0.3)\nscorer = QualityScorer(config)\n\nquality_score = scorer.get_score(memory_content)\nprint(f\"Quality score: {quality_score}\")\n```\n\n### Quality-Boosted Search\n\nWhen searching with quality consideration:\n\n```python\nresults = await search_memories(\n query=\"architecture decisions\",\n quality_boost=0.5, # Apply quality weighting\n limit=10\n)\n```\n\n### Manual Rating\n\n```python\nresult = await handle_rate_memory(server, {\n \"content_hash\": \"abc12345\",\n \"rating\": 4,\n \"feedback\": \"Important architectural decision\"\n})\n```\n\n## Configuration Best Practices\n\n### Performance vs Accuracy\n\n| Use Case | Configuration | Rationale |\n|----------|--------------|-----------|\n| Real-time search | `quality_boost=0.2-0.3` | Balance relevance with performance |\n| High-precision retrieval | `quality_boost=0.5-0.7` | Prioritize quality over recall |\n| Maintenance/cleanup | `min_quality=0.3-0.5` | Filter low-value memories |\n\n### Thresholds\n\n| Memory Type | Recommended `min_quality` |\n|-------------|---------------------------|\n| Session summaries | 0.4 |\n| Implementation details | 0.5 |\n| Architectural decisions | 0.6 |\n| Bug fixes | 0.3 |\n| Reference documentation | 0.5 |\n\n## Summary\n\nThe Quality Scoring System provides a comprehensive framework for evaluating and managing memory content quality in the MCP Memory Service. By combining ONNX-based offline ranking, AI-powered evaluation, and implicit behavioral signals, the system ensures that high-value memories are surfaced first while providing tools for ongoing quality maintenance.\n\nThe modular architecture allows for:\n- **Scalability**: ONNX Runtime enables efficient inference at scale\n- **Flexibility**: Configurable weights and thresholds for different use cases\n- **Offline capability**: Core ranking works without network dependencies\n- **User control**: Manual rating provides explicit feedback pathways\n- **Maintenance**: Built-in tools for quality-based memory management\n\n---\n\n\n\n## REST API Reference\n\n### 相关页面\n\n相关主题：[Agent Framework Integration](#agent-frameworks), [Quick Start Guide](#quickstart)\n\n\nRelated Source Files
\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)\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- [src/mcp_memory_service/web/api/mcp.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.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- [scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/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 \n\n# REST API Reference\n\n## Overview\n\nThe MCP Memory Service exposes a comprehensive REST API for managing semantic memories, performing advanced searches, and subscribing to real-time events. The API serves as the primary interface for external clients, web applications, and programmatic integrations that need to interact with the memory storage backend without using the MCP (Model Context Protocol) tools.\n\nThe REST API provides four major functional areas:\n\n| Area | Description |\n|------|-------------|\n| **Memory Management** | Store, retrieve, list, and delete semantic memories |\n| **Search Operations** | Semantic similarity, tag-based, and time-based search |\n| **Real-time Events** | Server-Sent Events (SSE) for live updates |\n| **MCP Protocol** | JSON-RPC interface compatible with MCP clients |\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)\n\n## Architecture\n\nThe REST API is built on FastAPI and serves as a thin layer over the core `MemoryService` and storage backends. Requests flow through the API router to the appropriate handlers, which delegate business logic to shared services.\n\n```mermaid\ngraph TD\n A[HTTP Client] --> B[FastAPI Router]\n B --> C[/api/memories]\n B --> D[/api/search]\n B --> E[/api/events]\n B --> F[/api/mcp]\n C --> G[Memory Handler]\n D --> H[Search Handler]\n E --> I[SSE Publisher]\n F --> J[MCP Handler]\n G --> K[MemoryService]\n H --> K\n K --> L[(SQLite + sqlite_vec)]\n```\n\n资料来源：[src/mcp_memory_service/web/api/mcp.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)\n\n## Base Configuration\n\n### Server Address\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_HOST` | `0.0.0.0` | Bind address |\n| `MCP_PORT` | `8080` | HTTP port |\n| `MCP_MAX_RESPONSE_CHARS` | `0` (unlimited) | Response truncation limit |\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n## Memory Management Endpoints\n\n### Store a Memory\n\nCreates a new memory with automatic embedding generation.\n\n```\nPOST /api/memories\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `content` | string | body | Yes | Memory content text |\n| `tags` | string[] | body | No | List of tags |\n| `memory_type` | string | body | No | Classification type (default: \"note\") |\n| `metadata` | object | body | No | Custom metadata key-value pairs |\n\n**Response:**\n\n```json\n{\n \"content_hash\": \"abc12345\",\n \"message\": \"Memory stored successfully\"\n}\n```\n\n资料来源：[src/mcp_memory_service/api/operations.py:50-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n\n### List All Memories\n\nRetrieves memories with pagination and optional filtering.\n\n```\nGET /api/memories\n```\n\n| Parameter | Type | Location | Required | Default | Description |\n|-----------|------|----------|----------|---------|-------------|\n| `page` | integer | query | No | `1` | 1-based page number |\n| `page_size` | integer | query | No | `20` | Results per page (max: 100) |\n| `tags` | string | query | No | - | Comma-separated tag filter |\n| `tag_match` | string | query | No | `any` | Match logic: `any` (OR) or `all` (AND) |\n| `memory_type` | string | query | No | - | Filter by memory type |\n| `stale_days` | integer | query | No | - | Filter memories not accessed in N days |\n\n**Response:**\n\n```json\n{\n \"memories\": [\n {\n \"content\": \"Memory content here\",\n \"content_hash\": \"abc12345\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"memory_type\": \"note\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"updated_at\": \"2025-01-15T10:30:00Z\"\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"page_size\": 20,\n \"total_count\": 150\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### Retrieve a Memory\n\nRetrieves a specific memory by its content hash.\n\n```\nGET /api/memories/{hash}\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `hash` | string | path | Yes | 8-character content hash |\n\n**Response:**\n\n```json\n{\n \"content\": \"Memory content here\",\n \"content_hash\": \"abc12345\",\n \"tags\": [\"architecture\", \"database\"],\n \"memory_type\": \"reference\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"updated_at\": \"2025-01-15T10:30:00Z\",\n \"metadata\": {}\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)\n\n### Delete a Memory\n\nRemoves a memory and its associated embeddings.\n\n```\nDELETE /api/memories/{hash}\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `hash` | string | path | Yes | 8-character content hash |\n\n**Response:**\n\n```json\n{\n \"success\": true,\n \"message\": \"Memory deleted successfully\"\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)\n\n## Search Operations\n\n### Semantic Search\n\nPerforms vector similarity search using text embeddings.\n\n```\nPOST /api/search\n```\n\n| Parameter | Type | Location | Required | Default | Description |\n|-----------|------|----------|----------|---------|-------------|\n| `query` | string | body | Yes | - | Search query text |\n| `limit` | integer | body | No | `5` | Maximum results (1-100) |\n| `tags` | string[] | body | No | - | Filter by tags |\n| `threshold` | float | body | No | `0.0` | Minimum relevance score |\n| `hybrid` | boolean | body | No | `false` | Enable BM25 fallback at threshold 0.4 |\n\n**Response:**\n\n```json\n{\n \"memories\": [\n {\n \"content_hash\": \"abc12345\",\n \"content\": \"Memory content...\",\n \"tags\": [\"tag1\"],\n \"relevance_score\": 0.87,\n \"match_method\": \"vector\"\n }\n ],\n \"found\": 1,\n \"shown\": 1\n}\n```\n\n资料来源：[src/mcp_memory_service/api/operations.py:100-150](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n\n### Tag-Based Search\n\nSearches memories using tags with AND/OR logic.\n\n```\nPOST /api/search/by-tag\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `tags` | string[] | body | Yes | List of tags to search |\n| `match_all` | boolean | body | No | `true` for AND, `false` for OR |\n\n**Response:**\n\n```json\n{\n \"memories\": [\n {\n \"content\": \"Memory content\",\n \"content_hash\": \"abc12345\",\n \"tags\": [\"python\", \"reference\"]\n }\n ],\n \"total_found\": 5\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py:50-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### Time-Based Search\n\nNatural language time-based queries for temporal memory retrieval.\n\n```\nPOST /api/search/by-time\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `time_query` | string | body | Yes | Natural language time expression |\n| `time_start` | float | body | No | Unix timestamp start |\n| `time_end` | float | body | No | Unix timestamp end |\n\n**Example Queries:**\n\n| Expression | Interpretation |\n|------------|----------------|\n| `last week` | 7 days ago to now |\n| `yesterday's architectural discussions` | Previous day |\n| `between 2025-01-01 and 2025-01-31` | Date range |\n\n资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n\n### Find Similar Memories\n\nFinds memories semantically similar to a specific memory by hash.\n\n```\nGET /api/search/similar/{hash}\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `hash` | string | path | Yes | Content hash of reference memory |\n| `limit` | integer | query | No | Maximum similar memories to return |\n\n**Response:**\n\n```json\n{\n \"reference_hash\": \"abc12345\",\n \"similar\": [\n {\n \"content_hash\": \"def67890\",\n \"content\": \"Similar memory content...\",\n \"similarity_score\": 0.92\n }\n ]\n}\n```\n\n## Real-time Events (SSE)\n\n### Subscribe to Memory Events\n\nServer-Sent Events stream for live memory activity.\n\n```\nGET /api/events\n```\n\n**Event Types:**\n\n| Event | Description |\n|-------|-------------|\n| `memory_stored` | New memory added |\n| `memory_deleted` | Memory removed |\n| `memory_updated` | Memory modified |\n| `embedding_complete` | Async embedding finished |\n\n**Example SSE Payload:**\n\n```\nevent: memory_stored\ndata: {\"content_hash\": \"abc12345\", \"timestamp\": \"2025-01-15T10:30:00Z\"}\n\nevent: memory_deleted\ndata: {\"content_hash\": \"def67890\", \"timestamp\": \"2025-01-15T10:35:00Z\"}\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)\n\n### SSE Statistics\n\nView connection statistics for SSE endpoints.\n\n```\nGET /api/events/stats\n```\n\n**Response:**\n\n```json\n{\n \"active_connections\": 2,\n \"total_events_sent\": 1450,\n \"uptime_seconds\": 86400\n}\n```\n\n## MCP Protocol Endpoint\n\nThe MCP-compatible JSON-RPC endpoint enables integration with MCP clients.\n\n```\nPOST /api/mcp\n```\n\n### Supported Methods\n\n| Method | Description |\n|--------|-------------|\n| `initialize` | Initialize MCP session, returns server capabilities |\n| `tools/list` | List available MCP tools |\n| `tools/call` | Execute a named MCP tool |\n\n### Initialize Request\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {}\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {\"tools\": {}},\n \"serverInfo\": {\n \"name\": \"mcp-memory-service\",\n \"version\": \"4.1.1\"\n }\n }\n}\n```\n\n### Tools List\n\nReturns all available MCP tools with their schemas.\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/list\"\n}\n```\n\n### Tool Call\n\nExecute a named tool with arguments.\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"memory_search\",\n \"arguments\": {\n \"query\": \"architecture decisions\",\n \"limit\": 5\n }\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/web/api/mcp.py:20-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)\n\n## Response Limiting\n\nThe API implements automatic response truncation to prevent context window overflow.\n\n### Behavior\n\n| Scenario | Action |\n|----------|--------|\n| `MCP_MAX_RESPONSE_CHARS=0` | No limit (backward compatible) |\n| `MCP_MAX_RESPONSE_CHARS>0` | Truncate at memory boundaries |\n| Response truncated | Include warning header |\n\n### Truncation Metadata\n\nWhen responses are truncated, the following metadata is included:\n\n```json\n{\n \"warning\": \"RESPONSE TRUNCATED: Showing 5 of 25 results (15000 of 75000 chars)\",\n \"meta\": {\n \"truncated\": true,\n \"shown_results\": 5,\n \"total_results\": 25,\n \"shown_chars\": 15000,\n \"total_chars\": 75000,\n \"omitted_count\": 20\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:60-120](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n## Data Models\n\n### Memory Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `content` | string | Memory text content |\n| `content_hash` | string | 8-character SHA256 hash |\n| `tags` | string[] | Associated tags |\n| `memory_type` | string | Classification (note, reference, decision, etc.) |\n| `created_at` | ISO8601 | Creation timestamp |\n| `updated_at` | ISO8601 | Last modification timestamp |\n| `metadata` | object | Custom key-value pairs |\n| `created_at_iso` | string | ISO format creation time |\n| `updated_at_iso` | string | ISO format modification time |\n\n### Search Result\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `memories` | Memory[] | Matching memories |\n| `found` | integer | Total matches |\n| `shown` | integer | Results returned (after limit) |\n| `query_time_ms` | float | Search duration |\n\n## Export Endpoints\n\n### Export Memories\n\nExport memories in text or JSON format for backup and migration.\n\n```\nGET /api/export\n```\n\n| Parameter | Type | Location | Description |\n|-----------|------|----------|-------------|\n| `format` | string | query | `text` or `json` (default: `text`) |\n\n**JSON Export Format:**\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 \"exporter_version\": \"5.0.0\"\n },\n \"memories\": [\n {\n \"content\": \"Memory content here\",\n \"content_hash\": \"sha256hash\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": 1673545200.0,\n \"updated_at\": 1673545200.0,\n \"memory_type\": \"note\",\n \"metadata\": {},\n \"export_source\": \"machine-name\"\n }\n ]\n}\n```\n\n资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n\n## Performance Characteristics\n\n| Operation | First Call | Subsequent Calls |\n|------------|------------|-------------------|\n| Search | ~50ms | ~5-10ms |\n| Store | ~50ms | ~10-20ms |\n| Health Check | ~50ms | ~5ms |\n\n**Cost Estimate:** At $0.15/1M tokens: ~$16.43/year per 10-user deployment.\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## API Client Library\n\nFor programmatic access, use the Python client:\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# Store a memory\nhash = store(\"New memory\", tags=[\"note\", \"important\"])\n\n# Search memories\nresults = search(\"architecture decisions\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# Health check\ninfo = health()\nprint(f\"Backend: {info.backend}, Count: {info.count}\")\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## Error Handling\n\n### Standard Error Response\n\n```json\n{\n \"error\": {\n \"code\": -32601,\n \"message\": \"Method not found: {method}\"\n }\n}\n```\n\n### Error Codes\n\n| Code | Meaning |\n|------|---------|\n| `-32600` | Invalid Request |\n| `-32601` | Method not found |\n| `-32602` | Invalid params |\n| `-32603` | Internal error |\n| `-32000` | Storage unavailable |\n\n## Documentation\n\nInteractive API documentation is available at:\n\n| URL | Format |\n|-----|--------|\n| `/api/docs` | Swagger UI |\n| `/api/redoc` | ReDoc |\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)\n\n---\n\n\n\n## Agent Framework Integration\n\n### 相关页面\n\n相关主题：[REST API Reference](#rest-api), [Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/agents/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/README.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- [docs/agents/http-generic.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/http-generic.md)\n- [docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)\n \n\n# Agent Framework Integration\n\nThe MCP Memory Service provides comprehensive integration capabilities with various AI agent frameworks, enabling persistent semantic memory storage and retrieval across multi-agent architectures. This integration layer allows autonomous agents to maintain contextual awareness, share knowledge, and persist learning across sessions.\n\n## Overview\n\nThe MCP Memory Service functions as a central knowledge backbone for AI agent frameworks. Rather than requiring each agent to maintain isolated memory stores, the service provides a unified semantic memory layer that can be accessed via:\n\n- **Model Context Protocol (MCP) Tools**: Native integration for MCP-compatible agents\n- **REST API**: HTTP-based access for any framework with HTTP client capabilities\n- **Direct Python API**: Programmatic access for Python-native frameworks\n\nThis architecture enables agents to:\n\n- Store discovered facts and learned patterns\n- Retrieve contextually relevant memories during reasoning\n- Share knowledge across agent teams\n- Maintain persistent state across sessions\n\n资料来源：[src/mcp_memory_service/api/__init__.py:1-50]()\n\n## Supported Agent Frameworks\n\nThe MCP Memory Service integrates with the following agent frameworks through dedicated documentation and examples:\n\n| Framework | Integration Type | Documentation |\n|-----------|------------------|---------------|\n| LangGraph | SDK/Graph-based | `docs/agents/langgraph.md` |\n| CrewAI | Team-based agents | `docs/agents/crewai.md` |\n| AutoGen | Multi-agent conversations | `docs/agents/autogen.md` |\n| Custom Frameworks | HTTP/REST | `docs/agents/http-generic.md` |\n\n资料来源：[docs/agents/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/README.md)\n\n## Architecture for Multi-Agent Systems\n\n```mermaid\ngraph TD\n A[Agent Framework] --> B[MCP Memory Service API]\n B --> C[Memory Management Layer]\n C --> D[(SQLite-vec Storage)]\n C --> E[(Cloudflare D1)]\n \n F[Agent 1] --> B\n G[Agent 2] --> B\n H[Agent N] --> B\n \n I[Embedding Generation] --> C\n J[all-MiniLM-L6-v2] --> I\n```\n\n### Memory Flow in Agent Workflows\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP as MCP Memory Service\n participant Storage as Vector Storage\n \n Agent->>MCP: Store Memory (content, tags)\n MCP->>MCP: Generate Embedding\n MCP->>Storage: Store + Index\n Storage-->>MCP: Confirm\n MCP-->>Agent: Content Hash\n \n Agent->>MCP: Semantic Search (query)\n MCP->>MCP: Generate Query Embedding\n MCP->>Storage: Similarity Search\n Storage-->>MCP: Top-K Results\n MCP-->>Agent: Relevant Memories\n```\n\n资料来源：[docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)\n\n## MCP Prompt Integration\n\nThe service exposes specialized prompts for agent workflows beyond basic memory operations:\n\n### Available Agent Prompts\n\n| Prompt Name | Purpose | Required Arguments |\n|-------------|---------|-------------------|\n| `knowledge_export` | Export memories in specific formats | `format` (json/markdown/text) |\n| `memory_cleanup` | Remove duplicates/outdated memories | `older_than`, `similarity_threshold` |\n| `learning_session` | Store structured learning notes | `topic`, `key_points` |\n\n资料来源：[src/mcp_memory_service/server_impl.py:150-200]()\n\n### Prompt Argument Specifications\n\n```python\ntypes.PromptArgument(\n name=\"format\",\n description=\"Export format (json, markdown, text)\",\n required=True\n)\ntypes.PromptArgument(\n name=\"older_than\",\n description=\"Remove memories older than (e.g., '6 months', '1 year')\",\n required=False\n)\ntypes.PromptArgument(\n name=\"similarity_threshold\",\n description=\"Similarity threshold for duplicates (0.0-1.0)\",\n required=False\n)\n```\n\n## REST API Integration\n\nFor agent frameworks that prefer HTTP-based communication, the service provides a comprehensive REST API:\n\n### Core Endpoints\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| POST | `/api/memories` | Store new memory |\n| GET | `/api/memories` | List memories with pagination |\n| GET | `/api/memories/{hash}` | Retrieve specific memory |\n| DELETE | `/api/memories/{hash}` | Delete memory |\n| POST | `/api/search` | Semantic similarity search |\n| GET | `/api/search/similar/{hash}` | Find similar memories |\n\n资料来源：[src/mcp_memory_service/web/app.py:50-100]()\n\n### Response Truncation for Agent Context\n\nTo prevent context overflow in agent prompts, the response limiter intelligently truncates results:\n\n```\n[!] RESPONSE TRUNCATED: Showing 5 of 20 results\n(1500 of 8000 chars).\n3 result(s) omitted to prevent context overflow.\nUse specific queries or hash-based retrieval for full content.\n```\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:30-60]()\n\n## Claude Code Integration\n\nThe MCP Memory Service includes specialized hooks for Claude Code CLI integration:\n\n### Available Claude Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/memory-recall` | Time-based memory retrieval using natural language |\n| `/memory-search` | Tag and content search |\n| `/memory-context` | Session context integration with machine source ID |\n| `/memory-health` | Service health diagnostics |\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n### Session Hook Workflow\n\n```mermaid\ngraph LR\n A[Session Start] --> B[Load Relevant Memories]\n B --> C[Inject into Context]\n \n D[During Session] --> E[Track Decisions]\n E --> F[Store Key Insights]\n \n G[Session End] --> H[Save Decisions]\n H --> I[Archive Insights]\n I --> J[Persistent Storage]\n```\n\n## Performance Characteristics for Agents\n\n| Metric | Value | Notes |\n|--------|-------|-------|\n| First Call Latency | ~50ms | Includes storage initialization |\n| Subsequent Calls | ~5-10ms | Connection reused |\n| Memory Overhead | <10MB | Per agent instance |\n| Embedding Model | all-MiniLM-L6-v2 | 384-dimensional vectors |\n| Cost (10 users) | $16.43/year | At $0.15/1M tokens |\n\n资料来源：[src/mcp_memory_service/api/__init__.py:10-20]()\n\n## Installation and Setup\n\n### Automatic Installation\n\n```bash\n# Install with commands (detects Claude Code CLI)\npython scripts/installation/install.py\n\n# Force install commands\npython scripts/installation/install.py --install-claude-commands\n```\n\n### Manual HTTP Integration\n\nFor custom agent frameworks:\n\n```python\nimport httpx\n\nasync def store_agent_memory(content: str, tags: list[str]):\n async with httpx.AsyncClient() as client:\n response = await client.post(\n \"https://your-endpoint:8443/api/memories\",\n json={\"content\": content, \"tags\": tags}\n )\n return response.json()\n```\n\n资料来源：[docs/agents/http-generic.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/http-generic.md)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Hooks not detected | Check `ls ~/.claude/settings.json` and reinstall |\n| JSON parse errors | Update to latest version with Python dict conversion |\n| Connection failed | Verify `curl -k https://your-endpoint:8443/api/health` |\n| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |\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## Doramagic Pitfall Log\n\nProject: doobidoo/mcp-memory-service\n\nSummary: Found 39 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare).\n\n## 1. security_permissions · 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_d0f9028fc870496f9576de28c5355817 | https://github.com/doobidoo/mcp-memory-service/issues/950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. installation · 失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- User impact: Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_dd89642370c2dba2d6aacf12756658a6 | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare), failure_mode_cluster:github_issue | fmev_07b451a0081c6435e7494e041a6641bc | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n## 3. installation · 失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- User impact: Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_74209176888c160a35483f3156117496 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_d8321b2cf697c747506701fd9f641fef | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_89d7bb3a956afe53a7a303ded77ab494 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_4d3ba37fa05ae6ea3d30aa7e6acbf4a4 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n## 4. installation · 失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- User impact: Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_b14a35b730602b08a29e3abbdfa0c377 | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug, failure_mode_cluster:github_issue | fmev_a2aed67ef427fc7f9ddeebb038420d7d | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n## 5. installation · 失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- User impact: Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_d0ce94252816336aa4ecbd45eeb73603 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.0 | v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n## 6. installation · 失败模式：installation: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- User impact: Upgrade or migration may change expected behavior: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.1 — OAuth state parameter RFC 6749 compliance fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_a0594e0fe855897f4612a17f520e81d4 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.1 | v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n## 7. installation · 失败模式：installation: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- User impact: Upgrade or migration may change expected behavior: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_8a1390fb930fb3d5c55aee894e53c0e3 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.2 | v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n## 8. installation · 失败模式：installation: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- User impact: Upgrade or migration may change expected behavior: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_cce458b1322f9ccb8db2498d3499650d | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.63.0 | v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n## 9. installation · 来源证据：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_…\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_all_memories'\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_da505f8e644d4dedbe7b94f2026f2c47 | https://github.com/doobidoo/mcp-memory-service/issues/981 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. installation · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. installation · 来源证据：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_99e7481daede4079a5bb8c96cba781ba | https://github.com/doobidoo/mcp-memory-service/issues/957 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. installation · 来源证据：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2027915616af406998b039c789f84c69 | https://github.com/doobidoo/mcp-memory-service/issues/938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. installation · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. installation · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n\n## 16. configuration · 失败模式：configuration: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- User impact: Developers may misconfigure credentials, environment, or host setup: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`). Context: Observed when using python, linux\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_d1e6b62e41c0cf3c6d4867576ec205f2 | https://github.com/doobidoo/mcp-memory-service/issues/941 | Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n\n## 17. configuration · 失败模式：configuration: [automated] Contributor activity digest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: [automated] Contributor activity digest\n- User impact: Developers may misconfigure credentials, environment, or host setup: [automated] Contributor activity digest\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [automated] Contributor activity digest. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_cdd98907ecf0813d3cca5938d053939d | https://github.com/doobidoo/mcp-memory-service/issues/937 | [automated] Contributor activity digest\n\n## 18. configuration · 失败模式：configuration: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shippe...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_886eb379e3e7ddfb3838d01f459a2a13 | https://github.com/doobidoo/mcp-memory-service/issues/959 | bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n\n## 19. configuration · 失败模式：configuration: feat: cascading search fallback when semantic results are sparse\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: feat: cascading search fallback when semantic results are sparse\n- User impact: Developers may misconfigure credentials, environment, or host setup: feat: cascading search fallback when semantic results are sparse\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat: cascading search fallback when semantic results are sparse. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8fc694ce4bba9729e62b19e988a1d8b6 | https://github.com/doobidoo/mcp-memory-service/issues/873 | feat: cascading search fallback when semantic results are sparse\n\n## 20. configuration · 失败模式：configuration: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgemen...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n- User impact: Upgrade or migration may change expected behavior: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e88b18989bddcec0f1d8e4edabb3137e | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.58.0 | v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n\n## 21. configuration · 失败模式：configuration: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n- User impact: Upgrade or migration may change expected behavior: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_8d10e56924a64499b0765864db43f654 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.2 | v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n\n## 22. configuration · 失败模式：configuration: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n- User impact: Upgrade or migration may change expected behavior: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_df9c592e9c921338e81c926f496f3755 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.1 | v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n\n## 23. configuration · 来源证据：Support Kiro CLI JSONL format in memory_harvest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support Kiro CLI JSONL format in memory_harvest\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3c9e617ea7184d08ae031c4983f4787c | https://github.com/doobidoo/mcp-memory-service/issues/934 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 24. configuration · 来源证据：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_fdf4f21de0234532b94ed2ffe3673c4e | https://github.com/doobidoo/mcp-memory-service/issues/959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 25. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\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\n## 26. runtime · 来源证据：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_4c07b5794f0741d8b76a3e94ca317421 | https://github.com/doobidoo/mcp-memory-service/issues/972 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 27. maintenance · 失败模式：migration: Support Kiro CLI JSONL format in memory_harvest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Support Kiro CLI JSONL format in memory_harvest\n- User impact: Developers may hit a documented source-backed failure mode: Support Kiro CLI JSONL format in memory_harvest\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Support Kiro CLI JSONL format in memory_harvest. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_ccb1d35700dbdd7961b19ca816ab2ec2 | https://github.com/doobidoo/mcp-memory-service/issues/934 | Support Kiro CLI JSONL format in memory_harvest\n\n## 28. maintenance · 失败模式：migration: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Se...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- User impact: Developers may hit a documented source-backed failure mode: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix. Context: Observed when using python, docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_474dd77beac7531143e2c9c8c014d21e | https://github.com/doobidoo/mcp-memory-service/issues/938 | fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n\n## 29. maintenance · 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 30. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n\n## 31. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 32. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 33. security_permissions · 来源证据：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_aa1db2bf08304d3db87350b8cbc8e6ca | https://github.com/doobidoo/mcp-memory-service/issues/941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 34. security_permissions · 来源证据：[automated] Contributor activity digest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[automated] Contributor activity digest\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0676e682588642899da4243174241e7b | https://github.com/doobidoo/mcp-memory-service/issues/937 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 35. security_permissions · 来源证据：feat: cascading search fallback when semantic results are sparse\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 36. security_permissions · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 37. security_permissions · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 38. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown\n\n## 39. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: 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 output with a Doramagic pitfall appendix.",
"title": "mcp-memory-service 说明书",
"toc": [
"https://github.com/doobidoo/mcp-memory-service 项目说明书",
"目录",
"Overview and Key Concepts",
"What is MCP Memory Service?",
"Architecture Overview",
"Core Components",
"Key Features",
"Memory Types Taxonomy",
"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": "ea489a898a5c88ad458e8330c963ffcb75c7077f",
"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- 文件总数：1113\n- 重要文件覆盖：40/1113\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\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Overview and Key Concepts**：importance `high`\n - source_paths: README.md, src/mcp_memory_service/__init__.py, src/mcp_memory_service/mcp_server.py\n- **Installation and Setup**：importance `high`\n - source_paths: install.py, scripts/installation/install.py, .env.example, pyproject.toml\n- **Quick Start Guide**：importance `high`\n - source_paths: docs/setup-guide.md, docs/first-time-setup.md, examples/config/claude_desktop_config.json\n- **System Architecture**：importance `high`\n - source_paths: src/mcp_memory_service/mcp_server.py, src/mcp_memory_service/server_impl.py, src/mcp_memory_service/services/memory_service.py, src/mcp_memory_service/services/graph_service.py, src/mcp_memory_service/storage/factory.py\n- **Storage Backends**：importance `high`\n - source_paths: src/mcp_memory_service/storage/sqlite_vec.py, src/mcp_memory_service/storage/cloudflare.py, src/mcp_memory_service/storage/milvus.py, src/mcp_memory_service/storage/hybrid.py, docs/guides/STORAGE_BACKENDS.md\n- **Knowledge Graph and Entity Extraction**：importance `medium`\n - source_paths: 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/storage/graph.py, src/mcp_memory_service/storage/milvus_graph.py\n- **Memory Consolidation Engine**：importance `medium`\n - source_paths: src/mcp_memory_service/consolidation/consolidator.py, src/mcp_memory_service/consolidation/scheduler.py, src/mcp_memory_service/consolidation/decay.py, src/mcp_memory_service/consolidation/forgetting.py, src/mcp_memory_service/consolidation/insights.py\n- **Quality Scoring System**：importance `medium`\n - source_paths: src/mcp_memory_service/quality/onnx_ranker.py, src/mcp_memory_service/quality/scorer.py, src/mcp_memory_service/quality/ai_evaluator.py, src/mcp_memory_service/quality/config.py, src/mcp_memory_service/embeddings/onnx_embeddings.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `ea489a898a5c88ad458e8330c963ffcb75c7077f`\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\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_d0f9028fc870496f9576de28c5355817 | https://github.com/doobidoo/mcp-memory-service/issues/950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Trigger: Developers should check this installation risk before relying on the project: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos\n- Why it matters: Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Evidence: failure_mode_cluster:github_issue | fmev_dd89642370c2dba2d6aacf12756658a6 | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare), failure_mode_cluster:github_issue | fmev_07b451a0081c6435e7494e041a6641bc | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Trigger: Developers should check this installation risk before relying on the project: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker\n- Why it matters: Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Evidence: failure_mode_cluster:github_issue | fmev_74209176888c160a35483f3156117496 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_d8321b2cf697c747506701fd9f641fef | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_89d7bb3a956afe53a7a303ded77ab494 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_4d3ba37fa05ae6ea3d30aa7e6acbf4a4 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Trigger: Developers should check this installation risk before relying on the project: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows\n- Why it matters: Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- Evidence: failure_mode_cluster:github_issue | fmev_b14a35b730602b08a29e3abbdfa0c377 | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug, failure_mode_cluster:github_issue | fmev_a2aed67ef427fc7f9ddeebb038420d7d | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n- Trigger: Developers should check this installation risk before relying on the project: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python\n- Why it matters: Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- Evidence: failure_mode_cluster:github_release | fmev_d0ce94252816336aa4ecbd45eeb73603 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.0 | v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 失败模式：installation: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n- Trigger: Developers should check this installation risk before relying on the project: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.1 — OAuth state parameter RFC 6749 compliance fix. Context: Observed when using python\n- Why it matters: Upgrade or migration may change expected behavior: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- Evidence: failure_mode_cluster:github_release | fmev_a0594e0fe855897f4612a17f520e81d4 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.1 | v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 失败模式：installation: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n- Trigger: Developers should check this installation risk before relying on the project: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility. Context: Observed when using python\n- Why it matters: Upgrade or migration may change expected behavior: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- Evidence: failure_mode_cluster:github_release | fmev_8a1390fb930fb3d5c55aee894e53c0e3 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.2 | v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: 失败模式：installation: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n- Trigger: Developers should check this installation risk before relying on the project: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- Host AI rule: Before packaging this project, run the relevant install/config/quickstart check for: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix. Context: Observed when using python\n- Why it matters: Upgrade or migration may change expected behavior: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- Evidence: failure_mode_cluster:github_release | fmev_cce458b1322f9ccb8db2498d3499650d | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.63.0 | v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 9: 来源证据：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_all_memories'\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_da505f8e644d4dedbe7b94f2026f2c47 | https://github.com/doobidoo/mcp-memory-service/issues/981 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 10: 来源证据：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: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: doobidoo/mcp-memory-service\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare) (high): 可能阻塞安装或首次运行。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare) (medium): Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare) Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos\n- 失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps (medium): Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker\n- 失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug (medium): Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows\n- 失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix (medium): Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"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-15 14:48:14 UTC\n\n## 目录\n\n- [Overview and Key Concepts](#overview)\n- [Installation and Setup](#installation)\n- [Quick Start Guide](#quickstart)\n- [System Architecture](#architecture)\n- [Storage Backends](#storage-backends)\n- [Knowledge Graph and Entity Extraction](#knowledge-graph)\n- [Memory Consolidation Engine](#consolidation-engine)\n- [Quality Scoring System](#quality-scoring)\n- [REST API Reference](#rest-api)\n- [Agent Framework Integration](#agent-frameworks)\n\n\n\n## Overview and Key Concepts\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Installation and Setup](#installation), [Quick Start Guide](#quickstart)\n\n\nRelevant Source Files
\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/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n- [claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n- [claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n- [scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n \n\n# Overview and Key Concepts\n\nThe MCP Memory Service is a semantic memory storage and retrieval system designed for AI-assisted development workflows. It provides persistent memory capabilities for Claude Code and other MCP-compatible clients, enabling intelligent context retention across development sessions.\n\n## What is MCP Memory Service?\n\nMCP Memory Service solves the context loss problem in AI-assisted development by maintaining a persistent, searchable store of development decisions, architectural choices, and project knowledge. When you work on a project, the service captures important decisions and makes them available in future sessions.\n\n资料来源：[README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/README.md)\n\n## Architecture Overview\n\nThe system follows a layered architecture with clear separation between storage, API, and client integration layers.\n\n```mermaid\ngraph TD\n A[Claude Code / MCP Clients] -->|MCP Protocol| B[MCP Server Layer]\n B --> C[REST API Layer]\n C --> D[Service Layer]\n D --> E[Storage Backend]\n \n E -->|SQLite-vec| F[Local Vector Storage]\n E -->|Cloudflare| G[D1 + Vectorize]\n E -->|Hybrid| H[Combined Approach]\n \n I[Web Dashboard] -->|HTTP| C\n J[Claude Hooks] -->|Session Events| B\n```\n\n### Supported Storage Backends\n\n| Backend | Description | Use Case |\n|---------|-------------|----------|\n| SQLite-vec | Local vector storage with SQLite | Single-machine deployments |\n| Cloudflare D1 + Vectorize | Cloud-hosted serverless | Multi-device, global access |\n| Hybrid | Combined local and cloud | Redundancy and performance |\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## Core Components\n\n### 1. MCP Server\n\nThe MCP Server implements the Model Context Protocol, providing tools and prompts for memory operations. It handles tool execution, prompt management, and bidirectional communication with MCP clients.\n\n**Key Tools:**\n- `store_memory` - Store new memories with automatic embedding generation\n- `search_memories` - Semantic similarity search using embeddings\n- `retrieve_memory` - Retrieve specific memory by content hash\n- `delete_memory` - Remove memory and associated embeddings\n- `list_memories` - List all memories with pagination\n\n**Key Prompts:**\n- `knowledge_retrieval` - Structured memory retrieval with relevance ranking\n- `memory_summary` - Generate summaries of stored memories\n- `knowledge_export` - Export memories in various formats\n- `memory_cleanup` - Identify and remove duplicates\n\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\n### 2. REST API Layer\n\nThe REST API provides HTTP endpoints for direct access to memory operations, useful for integrations and the web dashboard.\n\n```mermaid\ngraph LR\n A[Memory Management] -->|POST /api/memories| B[Store]\n A -->|GET /api/memories| C[List]\n A -->|GET /api/memories/{hash}| D[Retrieve]\n A -->|DELETE /api/memories/{hash}| E[Delete]\n \n F[Search Operations] -->|POST /api/search| G[Semantic Search]\n F -->|GET /api/search/similar/{hash}| H[Similar Search]\n \n I[Real-time Events] -->|GET /api/events| J[SSE Stream]\n I -->|GET /api/events/stats| K[Statistics]\n```\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/memories` | POST | Store a new memory with automatic embedding generation |\n| `/api/memories` | GET | List all memories with pagination support |\n| `/api/memories/{hash}` | GET | Retrieve a specific memory by content hash |\n| `/api/memories/{hash}` | DELETE | Delete a memory and its embeddings |\n| `/api/search` | POST | Semantic similarity search using embeddings |\n| `/api/search/similar/{hash}` | GET | Find memories similar to a specific one |\n| `/api/events` | GET | Subscribe to real-time memory events stream |\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)\n\n### 3. Web Dashboard\n\nThe built-in web interface provides:\n- Interactive API documentation (Swagger UI and ReDoc)\n- Real-time statistics display\n- SSE testing interface\n- Health monitoring\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)\n\n## Key Features\n\n### Semantic Search with Embeddings\n\nThe service uses the `all-MiniLM-L6-v2` embedding model to convert memory content into vector representations. This enables semantic similarity search that understands meaning rather than just keyword matching.\n\n**Performance Characteristics:**\n| Metric | Value |\n|--------|-------|\n| First call latency | ~50ms (includes storage initialization) |\n| Subsequent calls | ~5-10ms (connection reused) |\n| Memory overhead | <10MB |\n| Cost at $0.15/1M tokens | $16.43/year per 10-user deployment |\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### Response Size Limiter\n\nTo prevent context window overflow in LLM clients, the service includes a response limiter that truncates large responses at memory boundaries. This ensures that large memory retrieval operations don't crash Claude or other LLM clients.\n\n**Configuration:**\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_MAX_RESPONSE_CHARS` | 0 (unlimited) | Maximum characters in responses |\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n### Claude Code Integration\n\nThe service provides deep integration with Claude Code through hooks and slash commands.\n\n**Available Commands:**\n| Command | Purpose |\n|---------|---------|\n| `/memory-store` | Store important decisions and context |\n| `/memory-recall` | Retrieve memories using natural language |\n| `/memory-search` | Search by tags and content keywords |\n| `/memory-context` | Capture current session context |\n| `/memory-health` | Check service health and statistics |\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n**Automatic Hooks:**\n- **Session Start**: Load relevant project memories when Claude Code starts\n- **Session End**: Store insights and decisions from completed sessions\n- **Memory Retrieval**: On-demand memory access during conversations\n- **Permission Requests**: Automated handling of MCP permission requests\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n## Memory Types Taxonomy\n\nThe service organizes memories into a standardized taxonomy:\n\n| Category | Types |\n|----------|-------|\n| Content Types | note, reference, document, guide |\n| Activity Types | session, implementation, analysis |\n\nThis standardized taxonomy helps with memory organization and retrieval. The maintenance scripts can consolidate fragmented types into this standardized set.\n\n资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n\n## Data Model\n\nEach memory in the system has the following structure:\n\n```json\n{\n \"content\": \"Memory content here\",\n \"content_hash\": \"sha256hash\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": 1673545200.0,\n \"updated_at\": 1673545200.0,\n \"memory_type\": \"note\",\n \"metadata\": {},\n \"export_source\": \"machine-name\"\n}\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| content | string | The actual memory content |\n| content_hash | string | SHA256 hash of content for deduplication |\n| tags | array | User-defined tags for categorization |\n| created_at | float | Unix timestamp of creation |\n| updated_at | float | Unix timestamp of last update |\n| memory_type | string | Standardized type classification |\n| metadata | object | Additional metadata storage |\n| export_source | string | Source machine identifier |\n\n## Synchronization and Backup\n\n### Export/Import\n\nMemories can be exported and imported in JSON format for backup and migration purposes:\n\n- **Export**: ~1000 memories/second\n- **Import**: ~500 memories/second with deduplication\n- **File Size**: ~1KB per memory\n\n### Litestream Integration\n\nFor real-time replication, the service supports Litestream configuration, providing continuous backup to object storage.\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/sync/litestream_config.py)\n\n## Maintenance Tools\n\nThe service includes several maintenance scripts:\n\n| Script | Purpose |\n|--------|---------|\n| `check_memory_types.py` | Analyze type distribution and fragmentation |\n| `consolidate_memory_types.py` | Consolidate fragmented types into standardized taxonomy |\n| `export_memories.py` | Export memories to JSON format |\n| `import_memories.py` | Import memories from JSON with deduplication |\n\n资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n\n## Installation Methods\n\n### Python Package Installation\n```bash\npip install mcp-memory-service\n```\n\n### Claude Code Integration\n```bash\ncd claude-hooks\npython install_hooks.py --natural-triggers\n```\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n## Summary\n\nMCP Memory Service provides a comprehensive solution for maintaining persistent, searchable memory across AI-assisted development sessions. Its layered architecture supports multiple storage backends, while deep Claude Code integration enables seamless workflow integration. The system prioritizes reliability through response limiting, data deduplication, and maintenance tools that keep the memory store organized and efficient.\n\n---\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [install.py](https://github.com/doobidoo/mcp-memory-service/blob/main/install.py)\n- [scripts/installation/install.py](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/installation/install.py)\n- [.env.example](https://github.com/doobidoo/mcp-memory-service/blob/main/.env.example)\n- [pyproject.toml](https://github.com/doobidoo/mcp-memory-service/blob/main/pyproject.toml)\n \n\n# Installation and Setup\n\n## Overview\n\nThe MCP Memory Service provides a comprehensive installation framework supporting multiple deployment scenarios including pip installation, Claude Code integration, OpenCode plugin support, and standalone HTTP server deployment. The setup system is designed to be modular, allowing users to install only the components they need while maintaining cross-platform compatibility across Windows, macOS, and Linux environments.\n\n## System Requirements\n\n### Prerequisites\n\nThe installation system requires several external dependencies that must be present before deployment:\n\n| Dependency | Purpose | Platform-Specific Notes |\n|------------|---------|------------------------|\n| Python 3.10+ | Runtime environment | Required on all platforms |\n| Node.js | Hooks execution | Required for Claude Code hooks |\n| `jq` | Status line features | macOS: `brew install jq`; Linux: `sudo apt install jq`; Windows: `choco install jq` |\n| pip | Package management | Included with Python 3.10+ |\n\nThe dependency checking system (`src/mcp_memory_service/dependency_check.py`) validates all required dependencies during initialization and provides clear guidance if any are missing.\n\n### Environment Requirements\n\nThe service requires specific directory structures and environment variables:\n\n```bash\n# Standard data directory\n~/.local/share/mcp-memory/\n\n# Database file\n~/.local/share/mcp-memory/sqlite_vec.db\n\n# Configuration directory\n~/.claude/hooks/config.json # For Claude Code integration\n```\n\n## Installation Methods\n\n### Method 1: Pip Installation\n\nThe primary installation method uses pip to install the `mcp-memory-service` package:\n\n```bash\npip install mcp-memory-service\n```\n\nThe `pyproject.toml` file defines all package dependencies and metadata for PyPI distribution. This installation provides:\n\n- Core memory service library\n- HTTP server implementation\n- API endpoints\n- CLI tools\n\n资料来源：[pyproject.toml]()\n\n### Method 2: Standalone HTTP Server Installation\n\nFor HTTP server deployment, the installation script provides a guided setup process:\n\n```bash\n# From the repository root\npython scripts/installation/install.py\n\n# With specific options\npython scripts/installation/install.py --install-claude-commands # Install Claude commands\npython scripts/installation/install.py --skip-claude-commands-prompt # Skip command prompt\n```\n\nThe installer performs the following operations:\n\n1. Validates system prerequisites\n2. Installs the `mcp-memory-service` package\n3. Creates required directories\n4. Configures environment variables\n5. Sets up systemd services (on Linux)\n6. Optionally installs Claude Code commands\n\n资料来源：[scripts/installation/install.py]()\n\n### Method 3: Claude Code Hooks Installation\n\nClaude Code hooks provide automatic memory awareness and context injection. The unified installer supports multiple installation modes:\n\n```bash\ncd claude-hooks\n\n# Install Natural Memory Triggers (recommended)\npython install_hooks.py --natural-triggers\n\n# OR install basic memory awareness hooks\npython install_hooks.py --basic\n```\n\nThe hooks system consists of several components:\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| Session Start Hook | `session-start.js` | Loads relevant memories when Claude Code starts |\n| Session End Hook | `session-end.js` | Stores session insights and decisions |\n| Memory Retrieval | `memory-retrieval.js` | On-demand memory retrieval |\n| Permission Request | `permission-request.js` | MCP server permission automation |\n\n资料来源：[claude-hooks/README.md]()\n\n### Method 4: Claude Commands Installation\n\nFor Claude Code CLI integration, custom commands can be installed:\n\n```bash\n# Automatic installation during main setup\npython scripts/installation/install.py --install-claude-commands\n\n# Manual installation\npython scripts/claude_commands_utils.py\n\n# Test prerequisites\npython scripts/claude_commands_utils.py --test\n\n# Uninstall\npython scripts/claude_commands_utils.py --uninstall\n```\n\nCommands are installed to `~/.claude/commands/` and provide:\n\n- `/memory-save` - Save memories with tags\n- `/memory-recall` - Time-based memory retrieval\n- `/memory-search` - Tag and content search\n- `/memory-context` - Session context integration\n- `/memory-health` - Service health check\n\n资料来源：[claude_commands/README.md]()\n\n### Method 5: OpenCode Plugin Installation\n\nThe OpenCode plugin provides memory awareness for the OpenCode editor:\n\n```bash\n# Install plugin file\nmkdir -p ~/.config/opencode/plugins\ncp opencode/memory-plugin.js ~/.config/opencode/plugins/\n\n# Install example configuration\ncp opencode/memory-plugin.config.example.json ~/.config/opencode/memory-plugin.json\n```\n\n资料来源：[opencode/README.md]()\n\n## Environment Configuration\n\n### Environment Variables\n\nThe `.env.example` file provides configuration templates:\n\n```bash\n# MCP Memory Service Configuration\nMCP_API_KEY=your-api-key-here\nMCP_MEMORY_ENDPOINT=https://localhost:8443\nMCP_MEMORY_TIMEOUT_MS=30000\nMCP_MEMORY_LOAD_TIMEOUT_MS=10000\n```\n\n### Configuration Hierarchy\n\nThe OpenCode plugin demonstrates the configuration precedence system:\n\n```mermaid\ngraph TD\n A[Config Options] --> B[Environment Variables]\n A --> C[Default Config File]\n B --> D[OPENCODE_MEMORY_ENDPOINT]\n B --> E[OPENCODE_MEMORY_API_KEY]\n B --> F[OPENCODE_MEMORY_TIMEOUT_MS]\n C --> G[~/.config/opencode/memory-plugin.json]\n```\n\nConfiguration order of precedence (highest to lowest):\n\n1. Explicit plugin options\n2. Environment variables\n3. User config file (`~/.config/opencode/memory-plugin.json`)\n4. Project-local config (`.opencode/memory-plugin.json`)\n\n资料来源：[opencode/README.md]()\n\n## HTTP Server Deployment\n\n### Service Setup on Linux/macOS\n\nThe Litestream configuration system supports streaming SQLite replication for data durability:\n\n```bash\n# Install Litestream\ncurl -LsS https://github.com/benbjohnson/litestream/releases/latest/download/litestream-linux-amd64.tar.gz | tar -xzf -\nsudo mv litestream /usr/local/bin/\n\n# Generate configuration\npython scripts/sync/litestream_config.py\n```\n\n### Systemd Service Configuration\n\nProduction deployment uses systemd for service management:\n\n```bash\n# Start the service\nsystemctl --user start mcp-memory-http.service\n\n# Enable on boot\nsystemctl --user enable mcp-memory-http.service\n\n# Check status\nsystemctl --user status mcp-memory-http.service\n```\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py]()\n\n### Windows Service Setup\n\nFor Windows deployment, a LaunchAgent plist configuration is provided:\n\n```xml\n\n Label\n com.mcp-memory-service\n ProgramArguments\n \n /local/bin/litestream\n replicate\n -config\n {config_path}\n \n RunAtLoad\n \n\n```\n\n资料来源：[src/mcp_memory_service/sync/litestream_config.py]()\n\n## Data Synchronization\n\n### Database Export/Import\n\nFor cross-machine synchronization, the sync scripts provide export and import functionality:\n\n```bash\n# Export memories to JSON\npython scripts/sync/export_memories.py --output ./memories_export.json\n\n# Import memories from JSON\npython scripts/sync/import_memories.py --input ./memories_export.json\n```\n\nThe export format preserves all memory metadata:\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 },\n \"memories\": [\n {\n \"content\": \"Memory content\",\n \"content_hash\": \"sha256hash\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": 1673545200.0,\n \"memory_type\": \"note\"\n }\n ]\n}\n```\n\nDeduplication is based on content hash during import.\n\n资料来源：[scripts/sync/README.md]()\n\n## Maintenance Procedures\n\n### Database Type Consolidation\n\nOver time, memory types may become fragmented. The consolidation script standardizes the taxonomy:\n\n```bash\n# Preview changes (safe, read-only)\npython scripts/maintenance/consolidate_memory_types.py --dry-run\n\n# Execute consolidation\npython scripts/maintenance/consolidate_memory_types.py\n\n# With custom mapping\npython scripts/maintenance/consolidate_memory_types.py --config custom_mappings.json\n```\n\nThe standard 24-type taxonomy includes:\n\n| Category | Types |\n|----------|-------|\n| Content Types | `note`, `reference`, `document`, `guide` |\n| Activity Types | `session`, `implementation`, `analysis` |\n\n资料来源：[scripts/maintenance/README.md]()\n\n## Verification\n\nAfter installation, verify the setup with these checks:\n\n```bash\n# Verify Claude hooks installation\nclaude --debug hooks\n\n# Run integration tests\ncd ~/.claude/hooks && node tests/integration-test.js\n\n# Test API health\ncurl -k https://your-endpoint:8443/api/health\n\n# Verify database\nsqlite3 ~/.local/share/mcp-memory/sqlite_vec.db \"SELECT COUNT(*) FROM memories;\"\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Hooks not detected | Check `ls ~/.claude/settings.json`; reinstall if missing |\n| JSON parse errors | Update to latest version |\n| Connection failed | Verify endpoint with `curl -k https://your-endpoint:8443/api/health` |\n| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |\n| Missing `jq` | Install per platform instructions in prerequisites |\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n```bash\n# Claude Code debug mode\nclaude --debug hooks\n\n# Test individual hooks\nnode ~/.claude/hooks/core/session-start.js\n```\n\n## PyPI Placeholder Packages\n\nFor users who may install the wrong package name, placeholder packages redirect to the correct installation:\n\n```bash\n# These packages emit deprecation warnings and redirect to mcp-memory-service\npip install mcp-memory\npip install memory-service\npip install agent-mem\n```\n\n资料来源：[tools/pypi-placeholders/README.md]()\n\n## Architecture Overview\n\n```mermaid\ngraph TD\n subgraph \"Installation Methods\"\n A[Pip Installation] --> E[Core Service]\n B[Claude Hooks] --> F[Memory Awareness]\n C[Claude Commands] --> G[CLI Integration]\n D[OpenCode Plugin] --> H[Editor Integration]\n end\n \n subgraph \"Runtime Components\"\n E --> I[HTTP Server]\n I --> J[API Endpoints]\n J --> K[Memory Storage]\n K --> L[sqlite_vec]\n end\n \n subgraph \"Data Layer\"\n L --> M[Local Storage]\n L --> N[LitekStream Sync]\n end\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Overview and Key Concepts](#overview), [REST API Reference](#rest-api), [Agent Framework Integration](#agent-frameworks)\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)\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- [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- [scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n \n\n# Quick Start Guide\n\n## Overview\n\nThe MCP Memory Service Quick Start Guide provides developers and users with a streamlined path to deploy and begin using the persistent semantic memory system for AI agents. This guide covers installation methods, initial configuration, core functionality verification, and essential commands for day-to-day operations.\n\nThe service serves as a centralized memory backend that stores, retrieves, and manages semantic memories with automatic embedding generation. It supports multiple deployment configurations including local SQLite-vec storage, Cloudflare D1 + Vectorize for cloud deployments, and hybrid configurations for distributed workflows across multiple machines.\n\n## Prerequisites\n\nBefore beginning the installation, ensure your development environment meets the following requirements:\n\n| Requirement | Minimum Version | Notes |\n|-------------|-----------------|-------|\n| Python | 3.10+ | Required for core service |\n| Node.js | 16+ | Required for hooks execution |\n| SQLite | 3.35+ | Bundled with Python |\n| jq | 1.6+ | Required for statusLine feature |\n| Claude Code CLI | Latest | Optional, for Claude command integration |\n\n### Installing jq (Required for StatusLine Feature)\n\n```bash\n# macOS\nbrew install jq\n\n# Linux (Ubuntu/Debian)\nsudo apt install jq\n\n# Windows\nchoco install jq\n```\n\n## Installation Methods\n\n### Automatic Installation (Recommended)\n\nThe recommended approach uses the unified installer which handles all components:\n\n```bash\ncd claude-hooks\npython install_hooks.py\n```\n\nThe installer supports multiple installation modes:\n\n| Mode | Command | Description |\n|------|---------|-------------|\n| Full Installation | `python install_hooks.py` | Installs all features including basic hooks and natural triggers |\n| Basic Only | `python install_hooks.py --basic` | Installs memory hooks only |\n| Natural Triggers | `python install_hooks.py --natural-triggers` | Installs natural memory triggers only |\n\n### MCP Memory Service Installation\n\nFor the core memory service with HTTP server:\n\n```bash\n# Install with commands (will prompt if Claude Code CLI is detected)\npython scripts/installation/install.py\n\n# Force install commands\npython scripts/installation/install.py --install-claude-commands\n\n# Skip command installation prompt\npython scripts/installation/install.py --skip-claude-commands-prompt\n```\n\n## Initial Configuration\n\n### Claude Desktop Configuration\n\nTo integrate MCP Memory Service with Claude Desktop, create or modify the Claude Desktop configuration file. The configuration path varies by operating system:\n\n- **macOS/Linux**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nExample configuration structure:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-memory-service\": {\n \"command\": \"python\",\n \"args\": [\n \"-m\",\n \"mcp_memory_service\",\n \"server\"\n ],\n \"env\": {\n \"MCP_MEMORY_DB_PATH\": \"~/.local/share/mcp-memory/sqlite_vec.db\"\n }\n }\n }\n}\n```\n\n### Environment Variables\n\nThe service recognizes several environment variables for configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_MEMORY_DB_PATH` | `~/.local/share/mcp-memory/sqlite_vec.db` | Database storage path |\n| `MCP_MEMORY_BACKEND` | `sqlite_vec` | Storage backend type |\n| `MCP_MEMORY_PORT` | `8443` | HTTP server port |\n| `MCP_MEMORY_API_KEY` | None | Optional API key authentication |\n\n### Backend Configuration Options\n\nThe service supports multiple backend configurations:\n\n| Backend | Use Case | Configuration Value |\n|---------|----------|---------------------|\n| SQLite-vec | Local development, single machine | `sqlite_vec` or `sqlite-vec` |\n| Cloudflare D1 | Cloud deployment | `cloudflare` |\n| Hybrid | Multi-machine sync | `hybrid` |\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)\n\n## Starting the Service\n\n### HTTP Server Mode\n\nStart the HTTP server for REST API access:\n\n```bash\npython -m mcp_memory_service server\n```\n\nThe server provides an interactive dashboard at the root URL (`/`) displaying:\n\n- Total memory count\n- Active embedding model\n- Server health status\n- Response time metrics\n\n### MCP Server Mode\n\nStart as an MCP server for Claude integration:\n\n```bash\npython -m mcp_memory_service mcp\n```\n\n### Service Health Verification\n\nVerify the installation by checking service health:\n\n```bash\ncurl -k https://localhost:8443/api/health\n```\n\nExpected response includes:\n\n- `backend`: Current storage backend (e.g., `sqlite_vec`)\n- `count`: Total number of stored memories\n- `status`: Service health status\n\n## Core API Endpoints\n\nThe service exposes RESTful endpoints for memory operations:\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)\n\n### Memory Management Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/memories` | Store a new memory with automatic embedding |\n| GET | `/api/memories` | List all memories with pagination |\n| GET | `/api/memories/{hash}` | Retrieve specific memory by content hash |\n| DELETE | `/api/memories/{hash}` | Delete a memory and its embeddings |\n\n### Search Operations\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/search` | Semantic similarity search using embeddings |\n| GET | `/api/search/tags/{tag}` | Find memories by specific tag |\n| GET | `/api/search/similar/{hash}` | Find memories similar to a specific one |\n\n### Real-time Events\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/events` | Subscribe to real-time memory event stream (SSE) |\n| GET | `/api/events/stats` | View SSE connection statistics |\n\n### API Documentation\n\nInteractive API documentation is available at:\n\n- **Swagger UI**: `/api/docs`\n- **ReDoc**: `/api/redoc`\n\n## Claude Commands Integration\n\nAfter installation, several slash commands become available within Claude Code:\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n### Available Commands\n\n#### `/memory-store` - Store New Memories\n\nStore a new memory with automatic content hashing and embedding generation.\n\n```bash\nclaude /memory-store \"Implemented OAuth 2.1 authentication for improved security\"\nclaude /memory-store \"Refactored storage backend to support sqlite-vec for performance\"\n```\n\n#### `/memory-recall` - Time-based Memory Retrieval\n\nRetrieve memories using natural language time expressions.\n\n```bash\nclaude /memory-recall \"what did we decide about the database last week?\"\nclaude /memory-recall \"yesterday's architectural discussions\"\n```\n\n#### `/memory-search` - Tag and Content Search\n\nSearch through stored memories using tags, content keywords, and semantic similarity.\n\n```bash\nclaude /memory-search --tags \"architecture,database\"\nclaude /memory-search \"SQLite performance optimization\"\n```\n\n#### `/memory-context` - Session Context Integration\n\nCapture the current conversation and project context as a memory.\n\n```bash\nclaude /memory-context\nclaude /memory-context --summary \"Architecture planning session\"\n```\n\n#### `/memory-health` - Service Health Check\n\nCheck the health and status of the MCP Memory Service.\n\n```bash\nclaude /memory-health\nclaude /memory-health --detailed\n```\n\n## Claude Hooks Configuration\n\nThe hooks system provides automatic memory capture during Claude Code sessions:\n\n资料来源：[claude-hooks/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)\n\n### Hook Types\n\n| Hook | Trigger | Action |\n|------|---------|--------|\n| `session-start` | Claude Code launch | Load relevant project memories |\n| `session-end` | Claude Code exit | Store insights and decisions |\n| `auto-capture` | Automatic capture trigger | Capture important context |\n| `mid-conversation` | Periodic intervals | Summarize and store progress |\n\n### Configuration File\n\nEdit `~/.claude/hooks/config.json` to customize hook behavior:\n\n```json\n{\n \"memoryService\": {\n \"endpoint\": \"https://your-server:8443\",\n \"apiKey\": \"optional-api-key\"\n },\n \"hooks\": {\n \"verbose\": true,\n \"showMemoryDetails\": false,\n \"cleanMode\": false,\n \"autoCapture\": true,\n \"forceRemember\": \"#remember\",\n \"forceSkip\": \"#skip\",\n \"applyTo\": [\"auto-capture\", \"session-start\", \"mid-conversation\", \"session-end\"]\n }\n}\n```\n\n### Verbosity Levels\n\n| Level | Settings | Output |\n|-------|----------|--------|\n| Normal | `verbose: true`, others `false` | Essential information only |\n| Detailed | `showMemoryDetails: true` | Includes memory scoring details |\n| Clean | `cleanMode: true` | Minimal output, success/error only |\n| Silent | `verbose: false` | Background operation only |\n\n## Multi-Machine Synchronization\n\nFor users working across multiple machines, the service supports database synchronization:\n\n资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n\n### Export/Import Workflow\n\n```mermaid\ngraph TD\n A[Machine A] -->|export| B[JSON File]\n B -->|import| C[Machine B]\n B -->|import| D[Machine C]\n \n E[Central Database] -->|replicate| A\n E -->|replicate| C\n```\n\n### Export Command\n\n```bash\npython scripts/sync/export_memories.py \\\n --source-db ~/.local/share/mcp-memory/sqlite_vec.db \\\n --output ~/memories-export.json \\\n --machine-name \"workstation-1\"\n```\n\n### Import Command\n\n```bash\npython scripts/sync/import_memories.py \\\n --input ~/memories-export.json \\\n --target-db ~/.local/share/mcp-memory/sqlite_vec.db\n```\n\n### Deduplication\n\nMemories are deduplicated based on content hash during import:\n\n- **Same content hash**: Treated as duplicate, skipped\n- **Different content hash**: Imported as unique memory\n- **Original timestamps**: Preserved from source\n- **Source machine tags**: Added automatically for tracking\n\n### Litestream Configuration\n\nFor continuous database replication, configure Litestream:\n\n```yaml\ndbs:\n - path: ~/.local/share/mcp-memory/sqlite_vec.db\n replicas:\n - url: s3://your-bucket/memory-db\n sync-interval: 1s\n```\n\n## Verification\n\n### Verify Hook Installation\n\n```bash\nclaude --debug hooks\n```\n\nExpected output: `Found 1 hook matchers in settings`\n\n### Run Integration Tests\n\n```bash\ncd ~/.claude/hooks\nnode tests/integration-test.js\n```\n\nExpected: All 14 integration tests pass\n\n### Test API Endpoints\n\n```bash\n# Health check\ncurl -s https://localhost:8443/api/health | jq\n\n# Store a test memory\ncurl -X POST https://localhost:8443/api/memories \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Test memory from quick start\", \"tags\": [\"test\"]}'\n\n# Search memories\ncurl -X POST https://localhost:8443/api/search \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"test\", \"limit\": 5}'\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Hooks not detected | Verify `~/.claude/settings.json` exists; reinstall if missing |\n| JSON parse errors | Update to latest version with Python dict conversion |\n| Connection failed | Check `curl -k https://your-endpoint:8443/api/health` |\n| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |\n\n### Debug Mode\n\nEnable verbose debugging:\n\n```bash\n# Claude hooks debug\nclaude --debug hooks\n\n# Individual hook testing\nnode ~/.claude/hooks/core/session-start.js\n```\n\n### Windows-Specific Considerations\n\n- **Directory Structure**: Hooks install to `%USERPROFILE%\\.claude\\hooks\\`\n- **JSON Path Format**: Use backslashes or forward slashes\n- **Python Executable**: Ensure Python is in PATH\n\n## Performance Characteristics\n\nThe service is optimized for low-latency operations:\n\n| Operation | First Call | Subsequent Calls |\n|-----------|------------|-------------------|\n| Search | ~50ms | ~5-10ms |\n| Store | ~50ms | ~5-10ms |\n| Health Check | ~5ms | ~1ms |\n\n| Metric | Value |\n|--------|-------|\n| Memory Overhead | <10MB |\n| Cost per 10-user deployment | ~$16.43/year |\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## Next Steps\n\nAfter completing this quick start guide, consider exploring:\n\n- **API Reference**: Full endpoint documentation at `/api/docs`\n- **Maintenance Scripts**: Database cleanup and type consolidation tools in `scripts/maintenance/`\n- **Advanced Configuration**: Backend switching and hybrid deployment options\n- **Claude Hooks Customization**: Fine-tune auto-capture behavior and verbosity levels\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Storage Backends](#storage-backends), [Knowledge Graph and Entity Extraction](#knowledge-graph), [Memory Consolidation Engine](#consolidation-engine)\n\n\nRelated Source Files
\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_impl.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.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- [src/mcp_memory_service/storage/factory.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)\n- [docs/architecture.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/architecture.md)\n \n\n# System Architecture\n\n## Overview\n\nThe MCP Memory Service is a semantic memory service built on the Model Context Protocol (MCP). It provides storage, retrieval, and search capabilities for AI-assisted workflows by maintaining a persistent vector-based memory store with automatic embedding generation.\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:1-20](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\nThe architecture follows a layered design pattern with clear separation between the MCP protocol layer, business logic services, and storage abstraction layer.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n Claude[Claude Code]\n CLI[CLI Client]\n HTTP[HTTP Client]\n MCP[MCP Client]\n end\n\n subgraph \"Interface Layer\"\n FastAPI[FastAPI Server]\n MCP_Server[MCP Server]\n CLI_Interface[CLI Interface]\n end\n\n subgraph \"Service Layer\"\n Memory_Service[Memory Service]\n Graph_Service[Graph Service]\n Response_Limiter[Response Limiter]\n end\n\n subgraph \"Storage Layer\"\n Factory[Storage Factory]\n SQLiteVec[sqlite_vec]\n Litestream[Litestream Sync]\n end\n\n Client_Layer --> Interface_Layer\n Claude --> MCP_Server\n CLI --> CLI_Interface\n HTTP --> FastAPI\n\n Interface_Layer --> Service_Layer\n Memory_Service --> Factory\n Graph_Service --> Factory\n Factory --> SQLiteVec\n SQLiteVec --> Litestream\n```\n\n## Core Components\n\n### MCP Server\n\nThe MCP Server (`mcp_server.py`) implements the Model Context Protocol, allowing AI assistants like Claude Code to interact with the memory service directly through standardized MCP tools.\n\n**Key responsibilities:**\n- Expose MCP tools for memory operations\n- Handle tool invocation requests from MCP clients\n- Coordinate with the Memory Service for all operations\n\n**资料来源：[src/mcp_memory_service/mcp_server.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/mcp_server.py)**\n\n### Server Implementation\n\nThe `server_impl.py` serves as the primary server implementation, providing the HTTP/REST interface alongside MCP support.\n\n**资料来源：[src/mcp_memory_service/server_impl.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server_impl.py)**\n\n### Memory Service\n\nThe Memory Service (`memory_service.py`) is the core business logic layer that handles:\n\n| Operation | Description |\n|-----------|-------------|\n| `store()` | Store new memories with automatic embedding generation |\n| `search()` | Semantic similarity search using vector embeddings |\n| `recall()` | Time-based memory retrieval with natural language expressions |\n| `delete()` | Remove memories and their associated embeddings |\n| `list_memories()` | Paginated listing of all memories |\n\n**资料来源：[src/mcp_memory_service/services/memory_service.py:1-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/memory_service.py)**\n\n### Graph Service\n\nThe Graph Service (`graph_service.py`) manages relationship tracking between memories, enabling complex queries about memory connections and dependencies.\n\n**资料来源：[src/mcp_memory_service/services/graph_service.py:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/services/graph_service.py)**\n\n## Storage Architecture\n\n### Storage Factory Pattern\n\nThe storage layer uses a factory pattern (`storage/factory.py`) to abstract the underlying database implementation:\n\n```mermaid\ngraph LR\n Factory[Storage Factory] -->|Creates| SQLiteVec_Storage[SQLite Vec Storage]\n Factory -->|Creates| InMemory_Storage[In-Memory Storage]\n \n SQLiteVec_Storage -->|Uses| SQLite[(SQLite with vec extension)]\n InMemory_Storage -->|Uses| RAM[(In-Memory)]\n```\n\n**资料来源：[src/mcp_memory_service/storage/factory.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/factory.py)**\n\n### SQLite Vec Backend\n\nThe default storage backend uses `sqlite_vec`, which provides:\n\n- **Vector storage**: Native support for embedding storage and similarity search\n- **SQLite reliability**: ACID transactions, proven durability\n- **Low overhead**: <10MB memory footprint\n- **Performance**: ~5-10ms subsequent calls after first call initialization\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:15-18](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\n### Litestream Synchronization\n\nFor production deployments, Litestream provides continuous database replication:\n\n**资料来源：[src/mcp_memory_service/sync/litestream_config.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/sync/litestream_config.py)**\n\n| Platform | Installation Command |\n|----------|---------------------|\n| macOS | `brew install benbjohnson/litestream/litestream` |\n| Linux | `curl -LsS https://... \\| tar -xzf -` |\n| Windows | Manual download from GitHub releases |\n\n## API Architecture\n\n### REST API Endpoints\n\n**资料来源：[src/mcp_memory_service/web/app.py:30-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/app.py)**\n\n#### Memory Management\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/memories` | Store a new memory with automatic embedding generation |\n| GET | `/api/memories` | List all memories with pagination support |\n| GET | `/api/memories/{hash}` | Retrieve a specific memory by content hash |\n| DELETE | `/api/memories/{hash}` | Delete a memory and its embeddings |\n\n#### Search Operations\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/api/search` | Semantic similarity search using embeddings |\n| GET | `/api/search/similar/{hash}` | Find memories similar to a specific one |\n\n#### Real-time Events\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/events` | Subscribe to real-time memory events stream (SSE) |\n| GET | `/api/events/stats` | View SSE connection statistics |\n\n### Python API\n\nThe Python API provides programmatic access with low token overhead:\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# Search memories (~20 tokens)\nresults = search(\"architecture decisions\", limit=5)\n\n# Store memory (~15 tokens)\nhash = store(\"New memory\", tags=[\"note\", \"important\"])\n\n# Health check (~5 tokens)\ninfo = health()\n```\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:20-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\n## Response Management\n\n### Response Limiter\n\nThe `response_limiter.py` module prevents context window overflow by truncating responses at memory boundaries.\n\n**资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)**\n\n```mermaid\ngraph TD\n Request[Large Memory Request] --> Check{Under limit?}\n Check -->|Yes| Return_Full[Return all memories]\n Check -->|No| Truncate[Truncate at boundary]\n Truncate --> Add_Header[Add truncation header]\n Add_Header --> Return_Partial[Return partial results]\n```\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_MAX_RESPONSE_CHARS` | `0` (unlimited) | Maximum characters in responses |\n\n## CLI Architecture\n\n**资料来源：[src/mcp_memory_service/cli/main.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/cli/main.py)**\n\nThe CLI provides command-line access to all memory operations:\n\n```bash\nmemory server # Start HTTP server\nmemory health # Check service health\nmemory logs --lines 30 # Show recent log entries\n```\n\nCompatibility entry points:\n- `memory-server` (deprecated, redirects to `memory server`)\n\n## Integration Points\n\n### Claude Code Hooks\n\nThe system integrates with Claude Code through hooks that provide:\n\n- Automatic memory loading on session start\n- Context injection of relevant memories\n- Session insight storage on session end\n\n**资料来源：[claude-hooks/README.md:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/claude-hooks/README.md)**\n\n### Claude Commands\n\nCustom slash commands for memory operations:\n\n| Command | Purpose |\n|---------|---------|\n| `/memory-save` | Save current conversation as memory |\n| `/memory-recall` | Time-based memory retrieval |\n| `/memory-search` | Tag and content search |\n| `/memory-context` | Session context integration |\n| `/memory-health` | Service health check |\n\n**资料来源：[claude_commands/README.md:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)**\n\n## Data Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant API\n participant MemoryService\n participant Storage\n participant Litestream\n\n Client->>API: Store memory request\n API->>MemoryService: Save operation\n MemoryService->>MemoryService: Generate embedding\n MemoryService->>Storage: Store content + vector\n Storage->>Litestream: Replicate to S3/GCS\n Storage-->>MemoryService: Confirmation\n MemoryService-->>API: Success response\n API-->>Client: Memory hash returned\n\n Client->>API: Search request\n API->>MemoryService: Query\n MemoryService->>MemoryService: Generate query embedding\n MemoryService->>Storage: Vector similarity search\n Storage-->>MemoryService: Top K results\n MemoryService-->>API: Ranked results\n API-->>Client: Search results\n```\n\n## Maintenance Operations\n\n### Memory Type Consolidation\n\nThe system supports consolidating fragmented memory types into a standardized taxonomy:\n\n**资料来源：[scripts/maintenance/README.md:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)**\n\n**Standard 24-Type Taxonomy:**\n- Content Types: `note`, `reference`, `document`, `guide`\n- Activity Types: `session`, `implementation`, `analysis`\n\n### Sync Export/Import\n\n**资料来源：[scripts/sync/README.md:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)**\n\n| Operation | Performance |\n|-----------|-------------|\n| Export | ~1000 memories/second |\n| Import | ~500 memories/second with deduplication |\n| File Size | ~1KB per memory |\n\n## Performance Characteristics\n\n| Metric | Value |\n|--------|-------|\n| First call latency | ~50ms (includes storage initialization) |\n| Subsequent calls | ~5-10ms (connection reused) |\n| Memory overhead | <10MB |\n| Annual cost | ~$16.43/year per 10-user deployment (at $0.15/1M tokens) |\n\n**资料来源：[src/mcp_memory_service/api/__init__.py:12-15](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/__init__.py)**\n\n## Architecture Summary\n\nThe MCP Memory Service architecture is designed around three principles:\n\n1. **Separation of Concerns**: Clear boundaries between protocol handling, business logic, and storage\n2. **Multiple Interfaces**: Support for MCP, REST, Python API, and CLI access patterns\n3. **Production Ready**: Built-in replication, response limiting, and maintenance tools\n\n---\n\n\n\n## Storage Backends\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/milvus.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/milvus.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- [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/sqlite-vec-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/sqlite-vec-backend.md)\n \n\n# Storage Backends\n\nThe mcp-memory-service project implements a **pluggable storage backend architecture** that enables users to choose between different vector database technologies for storing and searching semantic memories. This abstraction layer decouples the core memory service logic from specific database implementations, providing flexibility in deployment scenarios.\n\n## Architecture Overview\n\nThe storage system follows a factory pattern with a unified interface. All storage implementations inherit from a common base class that defines the contract for memory operations: store, retrieve, search, and delete.\n\n```mermaid\ngraph TD\n A[Memory Service] --> B[Storage Factory]\n B --> C[sqlite_vec Storage]\n B --> D[Cloudflare Storage]\n B --> E[Milvus Storage]\n B --> F[Hybrid Storage]\n \n C --> G[(Local SQLite DB)]\n D --> H[(Cloudflare D1 + Vectorize)]\n E --> I[(Milvus Collection)]\n F --> J[(Cloudflare + SQLite)]\n```\n\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\n## Supported Storage Backends\n\n| Backend | Description | Best For |\n|---------|-------------|----------|\n| `sqlite_vec` | Local SQLite database with vec0 extension | Single-user, offline-first, privacy-focused |\n| `cloudflare` | Cloudflare D1 database + Vectorize API | Cloud-native, multi-device sync |\n| `milvus` | Milvus vector database | Enterprise-scale, high-performance |\n| `hybrid` | Cloudflare + SQLite combination | Multi-device with local backup |\n\n资料来源：[docs/guides/STORAGE_BACKENDS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/STORAGE_BACKENDS.md)\n\n## Core Interface\n\nAll storage backends implement a common interface defined through the base storage class. The interface includes:\n\n### Storage Methods\n\n| Method | Purpose | Parameters |\n|--------|---------|------------|\n| `store(memory)` | Store a new memory with embedding | Memory object with content, tags, metadata |\n| `retrieve(hash)` | Retrieve memory by content hash | content_hash: str |\n| `search(query, limit)` | Semantic search using embeddings | query: str, limit: int |\n| `search_by_tag(tags, match_all)` | Tag-based filtering | tags: list, match_all: bool |\n| `list_memories(page, page_size)` | Paginated memory listing | page: int, page_size: int |\n| `delete(hash)` | Remove memory and embeddings | content_hash: str |\n\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\n## SQLite Vec Backend\n\nThe `sqlite_vec` backend is the default and most widely-used storage option. It leverages the `sqlite-vec` extension to enable vector similarity search directly within SQLite.\n\n### Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `SQLITE_VEC_DB_PATH` | `~/.local/share/mcp-memory/sqlite_vec.db` | Path to SQLite database file |\n| `EMBEDDING_MODEL_NAME` | `sentence-transformers/all-MiniLM-L6-v2` | Embedding model for vectorization |\n\n### Database Schema\n\nThe SQLite backend stores memories in a relational table with the following structure:\n\n```sql\nCREATE TABLE memories (\n content TEXT NOT NULL,\n content_hash TEXT PRIMARY KEY,\n tags TEXT,\n memory_type TEXT,\n metadata TEXT,\n created_at REAL,\n updated_at REAL,\n created_at_iso TEXT,\n updated_at_iso TEXT\n);\n\nCREATE VIRTUAL TABLE memories_embeddings USING vec0(\n content_hash TEXT PRIMARY KEY,\n embedding FLOAT[384]\n);\n```\n\n资料来源：[docs/sqlite-vec-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/sqlite-vec-backend.md)\n\n### Performance Characteristics\n\n| Metric | Value |\n|--------|-------|\n| Search latency | 5-10ms |\n| Store latency | 10-20ms (includes embedding) |\n| Memory overhead | <10MB |\n| Capacity | Limited by disk space |\n\n## Cloudflare Backend\n\nThe Cloudflare backend provides cloud-native storage using Cloudflare's D1 (SQLite-compatible) database and Vectorize (vector search) API.\n\n### Configuration\n\n| Environment Variable | Required | Description |\n|---------------------|----------|-------------|\n| `CLOUDFLARE_API_TOKEN` | Yes | Cloudflare API authentication token |\n| `CLOUDFLARE_ACCOUNT_ID` | Yes | Cloudflare account identifier |\n| `CLOUDFLARE_VECTORIZE_INDEX` | Yes | Vectorize index name |\n| `CLOUDFLARE_D1_DATABASE_ID` | Yes | D1 database identifier |\n| `CLOUDFLARE_R2_BUCKET` | No | R2 bucket for large content storage |\n| `CLOUDFLARE_EMBEDDING_MODEL` | No | Embedding model override |\n| `CLOUDFLARE_LARGE_CONTENT_THRESHOLD` | No | Size threshold for R2 storage |\n| `CLOUDFLARE_MAX_RETRIES` | No | Retry attempts for API calls |\n| `CLOUDFLARE_BASE_DELAY` | No | Initial retry delay in seconds |\n\n### Initialization\n\n```python\nstorage = CloudflareStorage(\n api_token=CLOUDFLARE_API_TOKEN,\n account_id=CLOUDFLARE_ACCOUNT_ID,\n vectorize_index=CLOUDFLARE_VECTORIZE_INDEX,\n d1_database_id=CLOUDFLARE_D1_DATABASE_ID,\n r2_bucket=CLOUDFLARE_R2_BUCKET,\n embedding_model=CLOUDFLARE_EMBEDDING_MODEL,\n large_content_threshold=CLOUDFLARE_LARGE_CONTENT_THRESHOLD,\n max_retries=CLOUDFLARE_MAX_RETRIES,\n base_delay=CLOUDFLARE_BASE_DELAY\n)\n```\n\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\n## Milvus Backend\n\nThe Milvus backend targets enterprise deployments requiring high-performance, distributed vector search capabilities.\n\n### Configuration\n\n| Environment Variable | Required | Description |\n|---------------------|----------|-------------|\n| `MILVUS_URI` | Yes | Milvus server URI |\n| `MILVUS_TOKEN` | No | Authentication token |\n| `MILVUS_COLLECTION_NAME` | No | Collection name (default: `memories`) |\n| `EMBEDDING_MODEL_NAME` | No | Embedding model |\n\n### Initialization\n\n```python\nstorage = MilvusMemoryStorage(\n uri=MILVUS_URI,\n token=MILVUS_TOKEN,\n collection_name=MILVUS_COLLECTION_NAME,\n embedding_model=EMBEDDING_MODEL_NAME,\n)\n```\n\n资料来源：[docs/milvus-backend.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/milvus-backend.md)\n\n## Hybrid Backend\n\nThe hybrid backend combines Cloudflare storage with local SQLite-vec backup, enabling multi-device synchronization while maintaining offline capability.\n\n### Architecture\n\n```mermaid\ngraph LR\n A[Local SQLite DB] <--> B[Hybrid Storage]\n B <--> C[Cloudflare D1]\n B <--> D[Cloudflare Vectorize]\n \n E[Write Operations] --> B\n F[Read Operations] --> B\n```\n\n### Configuration\n\nThe hybrid backend requires both Cloudflare and SQLite configuration:\n\n```python\ncloudflare_config = {\n 'api_token': CLOUDFLARE_API_TOKEN,\n 'account_id': CLOUDFLARE_ACCOUNT_ID,\n 'vectorize_index': CLOUDFLARE_VECTORIZE_INDEX,\n 'd1_database_id': CLOUDFLARE_D1_DATABASE_ID,\n}\n\nstorage = HybridMemoryStorage(\n cloudflare_config=cloudflare_config,\n local_db_path=LOCAL_DB_PATH,\n)\n```\n\n## Storage Factory\n\nThe `get_storage()` function in the factory module handles backend instantiation based on configuration:\n\n```python\nasync def get_storage(backend: Optional[str] = None) -> BaseStorage:\n \"\"\"Get storage instance based on configured or specified backend.\"\"\"\n backend = backend or os.getenv(\"MCP_MEMORY_STORAGE_BACKEND\", \"sqlite_vec\")\n \n if backend == \"cloudflare\":\n return CloudflareStorage(...)\n elif backend == \"milvus\":\n return MilvusMemoryStorage(...)\n elif backend == \"hybrid\":\n return HybridMemoryStorage(...)\n else:\n return SQLiteVecStorage(...)\n```\n\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\n## HTTP Client Backend\n\nFor distributed deployments, the project supports HTTP-based storage access through an `HttpStorage` client. This enables communication with remote MCP Memory Service instances.\n\n### HTTP API Endpoints\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| POST | `/api/memories` | Store a new memory |\n| GET | `/api/memories` | List memories with pagination |\n| GET | `/api/memories/{hash}` | Retrieve specific memory |\n| DELETE | `/api/memories/{hash}` | Delete memory |\n| POST | `/api/search` | Semantic search |\n| GET | `/api/search/similar/{hash}` | Find similar memories |\n| GET | `/api/events` | SSE event stream |\n\n### Time Filter Format\n\nWhen searching by time ranges, the HTTP client converts Unix timestamps to ISO date format:\n\n```python\ndef _build_time_filter(time_start: Optional[float], time_end: Optional[float]) -> Optional[str]:\n if time_start and time_end:\n return f\"between {_to_date(time_start)} and {_to_date(time_end)}\"\n elif time_start:\n return _to_date(time_start)\n return _to_date(time_end)\n```\n\n资料来源：[src/mcp_memory_service/storage/http_client.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/http_client.py)\n\n## Backend Selection\n\n### Decision Matrix\n\n| Use Case | Recommended Backend |\n|----------|---------------------|\n| Single machine, privacy-sensitive | `sqlite_vec` |\n| Multi-device with cloud sync | `cloudflare` |\n| Enterprise with high volume | `milvus` |\n| Local backup + cloud sync | `hybrid` |\n\n### Selecting Backend via CLI\n\nWhen using the CLI for operations:\n\n```bash\n# Use SQLite backend (default)\nmemory ingest-document doc.pdf\n\n# Use Cloudflare backend\nmemory ingest-document doc.pdf --storage-backend cloudflare\n\n# Use hybrid backend\nmemory ingest-document doc.pdf --storage-backend hybrid\n```\n\n## Maintenance Operations\n\n### Embedding Migration\n\nTo migrate to a different embedding model (handles dimension changes):\n\n```bash\npython scripts/maintenance/migrate_embeddings.py --url http://localhost:8000 --model new-model --dry-run\n```\n\n### Database Repair Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `repair_memories.py` | Repair corrupted memory entries |\n| `repair_sqlite_vec_embeddings.py` | Fix embedding inconsistencies |\n| `repair_zero_embeddings.py` | Fix zero/null embeddings |\n| `cleanup_corrupted_encoding.py` | Fix corrupted emoji encoding |\n\n### Backup Strategy\n\nFor `sqlite_vec` backend, Litestream provides continuous replication:\n\n```bash\n# Configure in litestream.yml\ndbs:\n - path: ~/.local/share/mcp-memory/sqlite_vec.db\n replicas:\n - url: s3://your-bucket/mcp-memory/\n```\n\n资料来源：[scripts/sync/litestream/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/litestream/README.md)\n\n## Response Limiting\n\nAll storage backends support response size limiting through the `ResponseLimiter` utility to prevent oversized responses:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_chars` | 10000 | Maximum characters in response |\n| `max_results` | 50 | Maximum memories to return |\n\nThe limiter calculates estimated memory sizes including overhead and truncates at memory boundaries to ensure consistent response sizes.\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n---\n\n\n\n## Knowledge Graph and Entity Extraction\n\n### 相关页面\n\n相关主题：[System Architecture](#architecture), [Memory Consolidation Engine](#consolidation-engine), [Quality Scoring System](#quality-scoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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/storage/graph.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.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- [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- [src/mcp_memory_service/consolidation/consolidator.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n \n\n# Knowledge Graph and Entity Extraction\n\n## Overview\n\nThe MCP Memory Service includes a sophisticated Knowledge Graph system that enables semantic relationships between memories, automatic entity extraction, and intelligent relationship inference. This feature transforms isolated memory entries into an interconnected knowledge network that supports advanced queries like graph traversal, entity-based retrieval, and similarity analysis.\n\nThe knowledge graph layer sits above the core memory storage, providing:\n\n- **Entity Extraction**: Automatic identification of people, organizations, locations, and concepts from memory content\n- **Relationship Mapping**: Discovery and storage of connections between memories based on semantic similarity and content analysis\n- **Graph Traversal**: Navigation of memory relationships using configurable depth and radius parameters\n- **Association Memory**: Automatic creation of memory entries that document discovered relationships between existing memories\n- **Relationship Inference**: AI-powered inference of relationship types (causes, fixes, contradicts, supports, follows)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Memory Layer\"\n M1[Memory 1]\n M2[Memory 2]\n M3[Memory 3]\n end\n\n subgraph \"Entity Extraction\"\n EE[EntityExtractor]\n NER[NER Processing]\n PAT[Pattern Matching]\n end\n\n subgraph \"Graph Storage\"\n GS[GraphStorage]\n RI[RelationshipInference]\n AM[AssociationMemory]\n end\n\n subgraph \"Query Interfaces\"\n GT[Graph Tools]\n ST[Search Tools]\n end\n\n M1 --> EE\n M2 --> EE\n M3 --> EE\n\n EE --> NER\n EE --> PAT\n\n NER --> GS\n PAT --> GS\n\n GS --> RI\n RI --> AM\n AM --> GS\n\n GT --> GS\n ST --> GS\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| `EntityExtractor` | `src/mcp_memory_service/reasoning/entities.py` | Extracts entities from memory content |\n| `RelationshipInferenceEngine` | `src/mcp_memory_service/reasoning/inference.py` | Infers relationship types between memories |\n| `GraphStorage` | `src/mcp_memory_service/storage/graph.py` | SQLite-based graph storage backend |\n| `MilvusGraphStorage` | `src/mcp_memory_service/storage/milvus_graph.py` | Milvus vector database backend |\n| `MemoryConsolidator` | `src/mcp_memory_service/consolidation/consolidator.py` | Creates and manages association memories |\n| `Association` | `src/mcp_memory_service/models/association.py` | Data model for memory associations |\n\n资料来源：[src/mcp_memory_service/reasoning/entities.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)\n\n## Entity Extraction\n\n### Overview\n\nEntity extraction automatically identifies and categorizes entities within memory content. The system supports multiple entity types and uses both pattern-based and NER (Named Entity Recognition) approaches.\n\n资料来源：[src/mcp_memory_service/reasoning/entities.py:1-30](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/entities.py)\n\n### Supported Entity Types\n\nThe system recognizes the following entity categories:\n\n| Entity Type | Description | Examples |\n|-------------|-------------|----------|\n| `person` | Human individuals | \"John\", \"Alice Chen\" |\n| `organization` | Companies, teams, agencies | \"Acme Corp\", \"Engineering Team\" |\n| `location` | Physical places | \"San Francisco\", \"Building A\" |\n| `concept` | Abstract ideas and concepts | \"machine learning\", \"agile methodology\" |\n| `technology` | Tools, frameworks, languages | \"Python\", \"React\", \"Docker\" |\n| `date` | Temporal references | \"December 2024\", \"Q1\" |\n| `project` | Named projects or initiatives | \"Project Alpha\", \"Apollo Initiative\" |\n\n### Extraction Process\n\n```mermaid\ngraph LR\n A[Memory Content] --> B[Pattern Matching]\n A --> C[NER Processing]\n B --> D[Entity Deduplication]\n C --> D\n D --> E[Entity Metadata]\n E --> F[Store Entity Links]\n```\n\nThe extraction process follows these steps:\n\n1. **Pattern Matching**: Initial scan for known patterns (email, URL, date formats, capitalization patterns)\n2. **NER Processing**: Language model-based entity recognition for contextual entity types\n3. **Entity Deduplication**: Normalization and merging of duplicate entities\n4. **Metadata Generation**: Creation of entity metadata including confidence scores\n5. **Storage**: Persisting entity links to the graph storage\n\n### MCP Tool Interface\n\nEntities can be extracted and stored via the MCP `memory_graph` tool:\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:50-75](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n```json\n{\n \"action\": \"extract_entities\",\n \"hash\": \"abc123def456\"\n}\n```\n\n**Response Example:**\n```json\n{\n \"hash\": \"abc123def456\",\n \"entities_extracted\": 5,\n \"entities\": [\n {\"name\": \"Python\", \"type\": \"technology\", \"confidence\": 0.95},\n {\"name\": \"FastAPI\", \"type\": \"technology\", \"confidence\": 0.92}\n ]\n}\n```\n\n## Knowledge Graph Storage\n\n### Storage Backends\n\nThe knowledge graph supports multiple storage backends:\n\n| Backend | File | Use Case |\n|---------|------|----------|\n| SQLite Graph | `src/mcp_memory_service/storage/graph.py` | Default, single-node deployments |\n| Milvus Graph | `src/mcp_memory_service/storage/milvus_graph.py` | Large-scale, distributed deployments |\n\n资料来源：[src/mcp_memory_service/storage/graph.py:1-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)\n\n### Graph Data Model\n\nThe graph storage maintains the following data structures:\n\n#### Entities Table\nStores extracted entities linked to memories:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `entity_id` | TEXT | Unique entity identifier |\n| `name` | TEXT | Entity name |\n| `entity_type` | TEXT | Entity category |\n| `memory_hash` | TEXT | Associated memory hash |\n| `confidence` | REAL | Extraction confidence score |\n\n#### Relationships Table\nStores relationships between memories:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `relationship_id` | TEXT | Unique relationship identifier |\n| `source_hash` | TEXT | Source memory hash |\n| `target_hash` | TEXT | Target memory hash |\n| `relationship_type` | TEXT | Type (similar, causes, fixes, etc.) |\n| `similarity_score` | REAL | Calculated similarity (0.0-1.0) |\n| `metadata` | JSON | Additional relationship metadata |\n\n资料来源：[src/mcp_memory_service/models/association.py:1-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/models/association.py)\n\n### Graph Operations\n\n#### Store Entity Link\n\n```python\nasync def store_entity_link(\n memory_hash: str,\n entity_name: str,\n entity_type: str\n) -> bool:\n```\n\nLinks an extracted entity to a memory for future retrieval and graph queries.\n\n资料来源：[src/mcp_memory_service/storage/graph.py:150-180](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/storage/graph.py)\n\n#### Get Memory Subgraph\n\nRetrieves a local subgraph centered on a specific memory:\n\n```python\nasync def get_memory_subgraph(\n memory_hash: str,\n radius: int = 2\n) -> Dict[str, Any]:\n```\n\nParameters:\n- `memory_hash`: Center memory for subgraph traversal\n- `radius`: Maximum traversal depth (default: 2)\n\n#### Graph Traversal\n\n```python\nasync def traverse_graph(\n hash1: str,\n hash2: str,\n max_depth: int = 5\n) -> List[Dict[str, Any]]:\n```\n\nFinds paths between two memories up to a specified depth.\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:20-45](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n## Relationship Inference\n\n### RelationshipInferenceEngine\n\nThe relationship inference engine analyzes memory content pairs to determine semantic relationships:\n\n资料来源：[src/mcp_memory_service/reasoning/inference.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/reasoning/inference.py)\n\n### Supported Relationship Types\n\n| Type | Description | Example |\n|------|-------------|---------|\n| `causes` | Source leads to target | \"Changed config\" → \"System crashed\" |\n| `fixes` | Source resolves target | \"Applied patch\" → \"Bug #123\" |\n| `contradicts` | Sources conflict | \"Use X\" vs \"Don't use X\" |\n| `supports` | Source validates target | \"Test results\" → \"Implementation works\" |\n| `follows` | Temporal sequence | \"Phase 1 complete\" → \"Phase 2 started\" |\n| `related` | General connection | Topic similarity without specific type |\n\n### Inference Process\n\n```mermaid\ngraph TD\n M1[Memory 1] --> C1[Content Analysis]\n M2[Memory 2] --> C2[Content Analysis]\n C1 --> SIM[Similarity Check]\n C2 --> SIM\n SIM --> RT{Relationship Type?}\n RT -->|High Similarity| SA[Same Aspect]\n RT -->|Causal Keywords| CA[Causal Link]\n RT -->|Action Keywords| AC[Action Link]\n RT -->|Negation| CN[Contradiction]\n SA --> ST[Store Relationship]\n CA --> ST\n AC --> ST\n CN --> ST\n```\n\n## Association Memory\n\n### Overview\n\nAssociation memories are automatically generated entries that document discovered relationships between existing memories. They provide a memory-level representation of graph connections, enabling search and retrieval of relationship information.\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:150-200](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n\n### Association Data Model\n\n```python\nclass Association:\n source_memory_hashes: List[str]\n similarity_score: float\n connection_type: str\n discovery_method: str\n discovery_date: datetime\n metadata: Dict[str, Any]\n```\n\n### Association Memory Structure\n\nWhen an association is stored as a memory:\n\n```python\nassociation_memory = Memory(\n content=f\"Connected {source_hashes[0][:8]} and {source_hashes[1][:8]} by {connection_type}\",\n content_hash=f\"assoc_{source_hashes[0][:8]}_{source_hashes[1][:8]}\",\n tags=[\"association\", \"discovered\", connection_type],\n memory_type=\"observation\",\n metadata={\n \"source_memory_hashes\": source_hashes,\n \"similarity_score\": similarity,\n \"connection_type\": connection_type,\n \"discovery_method\": association.discovery_method,\n \"discovery_date\": association.discovery_date.isoformat(),\n }\n)\n```\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:170-195](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n\n### Storage Process\n\n```mermaid\ngraph LR\n A[Memory Pair] --> B[Similarity Analysis]\n B --> C{Score >= Threshold?}\n C -->|Yes| D[Type Classification]\n C -->|No| E[Skip]\n D --> F[Create Association]\n F --> G[Store Association Memory]\n G --> H[Update Graph]\n```\n\nThe consolidator stores association memories with `skip_semantic_dedup=True` to prevent deduplication conflicts with templated content.\n\n资料来源：[src/mcp_memory_service/consolidation/consolidator.py:195-210](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/consolidator.py)\n\n## MCP Tools Reference\n\n### memory_graph\n\nMain tool for graph operations:\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `action` | string | Yes | Operation: `traverse`, `subgraph`, `extract_entities` |\n| `hash` | string | Conditional | Memory hash for subgraph/entities actions |\n| `hash1` | string | Conditional | Source hash for traversal |\n| `hash2` | string | Conditional | Target hash for traversal |\n| `radius` | integer | No | Subgraph radius (default: 2) |\n| `max_depth` | integer | No | Traversal max depth (default: 5) |\n\n#### Action Examples\n\n**Extract Entities:**\n```json\n{\n \"action\": \"extract_entities\",\n \"hash\": \"memory_hash_here\"\n}\n```\n\n**Get Subgraph:**\n```json\n{\n \"action\": \"subgraph\",\n \"hash\": \"memory_hash_here\",\n \"radius\": 3\n}\n```\n\n**Traverse Graph:**\n```json\n{\n \"action\": \"traverse\",\n \"hash1\": \"memory_hash_1\",\n \"hash2\": \"memory_hash_2\",\n \"max_depth\": 5\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:1-80](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n## Maintenance Scripts\n\n### update_graph_relationship_types.py\n\nLocated in `scripts/maintenance/`, this script infers relationship types for existing graph associations:\n\n```bash\n# Dry run (preview changes)\npython scripts/maintenance/update_graph_relationship_types.py --dry-run\n\n# Execute inference\npython scripts/maintenance/update_graph_relationship_types.py\n```\n\n**Features:**\n- Uses `RelationshipInferenceEngine` for type inference\n- Supports dry-run mode for safety\n- Automatic backup before execution\n- Updates relationship metadata in graph storage\n\n资料来源：[scripts/maintenance/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/maintenance/README.md)\n\n## Configuration\n\n### Graph Storage Configuration\n\nThe graph storage is automatically initialized when the storage service starts. No explicit configuration is required for SQLite-based storage.\n\nFor Milvus-based storage, configure the following environment variables:\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MILVUS_HOST` | Milvus server host | localhost |\n| `MILVUS_PORT` | Milvus server port | 19530 |\n| `MILVUS_COLLECTION` | Collection name | memory_graph |\n\n### Entity Extraction Configuration\n\nEntity extraction settings can be configured in the service configuration:\n\n| Setting | Type | Description |\n|---------|------|-------------|\n| `entity_types` | List[str] | Enabled entity types |\n| `min_confidence` | float | Minimum confidence threshold (0.0-1.0) |\n| `enable_ner` | bool | Enable NER processing |\n| `pattern_weight` | float | Weight for pattern matching |\n\n## Error Handling\n\nThe graph operations return standardized error responses:\n\n```json\n{\n \"error\": \"Error message describing the issue\"\n}\n```\n\nCommon error scenarios:\n- Memory not found for entity extraction\n- Graph storage not initialized\n- Invalid hash format\n- Maximum depth exceeded during traversal\n\n资料来源：[src/mcp_memory_service/server/handlers/graph.py:55-65](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/graph.py)\n\n## Best Practices\n\n1. **Entity Naming**: Use consistent entity naming conventions for better graph queries\n2. **Memory Organization**: Group related content in the same memory to strengthen association discovery\n3. **Regular Maintenance**: Run `update_graph_relationship_types.py` periodically to classify new associations\n4. **Tag Usage**: Tag memories with semantic tags to improve entity and relationship extraction\n5. **Graph Traversal**: Use appropriate radius/depth limits to prevent performance issues with highly connected memories\n\n## See Also\n\n- [Memory Storage](storage-overview.md) - Core memory storage architecture\n- [Consolidation System](consolidation.md) - Association memory generation\n- [Reasoning Engine](reasoning.md) - Entity extraction and inference details\n- [Maintenance Scripts](../scripts/maintenance/README.md) - Graph maintenance utilities\n\n---\n\n\n\n## Memory Consolidation Engine\n\n### 相关页面\n\n相关主题：[Knowledge Graph and Entity Extraction](#knowledge-graph), [Quality Scoring System](#quality-scoring), [System Architecture](#architecture)\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/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/insights.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/consolidation/insights.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# Memory Consolidation Engine\n\nThe Memory Consolidation Engine is a core subsystem of the MCP Memory Service that manages the lifecycle of stored memories through intelligent compression, decay analysis, and selective forgetting mechanisms. It ensures the memory store remains efficient, relevant, and optimized for long-term semantic retrieval.\n\n## Overview\n\nAs memories accumulate over time, the consolidation engine performs background operations to:\n\n- **Compress redundant memories** into consolidated summaries\n- **Apply decay algorithms** to age out less relevant information\n- **Forget obsolete entries** based on configurable time horizons\n- **Generate insights** from consolidated memory patterns\n\n```mermaid\ngraph TD\n A[New Memory] --> B[Memory Store]\n B --> C{Consolidation Scheduler}\n C --> D[Decay Analysis]\n C --> E[Compression]\n C --> F[Forgetting Check]\n D --> G[Relevance Score Update]\n E --> H[Consolidated Memory]\n F --> I[Memory Deletion]\n G --> H\n H --> J[Insights Generation]\n J --> K[Updated Memory Store]\n```\n\n## Architecture\n\nThe consolidation engine comprises five primary modules located in `src/mcp_memory_service/consolidation/`:\n\n| Module | Purpose | Key Functions |\n|--------|---------|---------------|\n| `consolidator.py` | Core consolidation orchestration | Main consolidation loop, memory merging |\n| `scheduler.py` | Automated scheduling of consolidation tasks | Daily, weekly, monthly job scheduling |\n| `decay.py` | Relevance decay calculations | Age-based score reduction algorithms |\n| `forgetting.py` | Selective memory removal | Time-horizon based forgetting policies |\n| `insights.py` | Post-consolidation analysis | Pattern detection, summary generation |\n\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\n## Consolidation Time Horizons\n\nThe engine operates on three configurable time horizons that determine consolidation aggressiveness:\n\n### Weekly Consolidation\n- Processes recent memories (typically 7 days)\n- Light compression to maintain detail\n- Preserves high-relevance memories unchanged\n\n### Monthly Consolidation\n- Reviews memories from past 30 days\n- Moderate compression and decay application\n- Identifies patterns across recent sessions\n\n### Quarterly Consolidation\n- Full store analysis\n- Aggressive forgetting of stale entries\n- Major compression of redundant information\n\n资料来源：[src/mcp_memory_service/api/operations.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n\n## API Integration\n\n### REST API Endpoint\n\n```\nPOST /api/consolidate\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `time_horizon` | string | Yes | One of: `daily`, `weekly`, `monthly` |\n\n**Example Request:**\n```bash\ncurl -X POST https://localhost:8443/api/consolidate \\\n -H \"Content-Type: application/json\" \\\n -d '{\"time_horizon\": \"weekly\"}'\n```\n\n**Example Response:**\n```json\n{\n \"status\": \"completed\",\n \"time_horizon\": \"weekly\",\n \"memories_processed\": 2418,\n \"compressed\": 156,\n \"forgotten\": 43\n}\n```\n\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\n### Python API\n\n```python\nfrom mcp_memory_service.api import consolidate\n\n# Async consolidation\nresult = await consolidate('weekly')\nprint(f\"Compressed: {result.compressed}, Forgotten: {result.forgotten}\")\n```\n\n**Return Value Properties:**\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `status` | string | Completion status |\n| `time_horizon` | string | Horizon used |\n| `memories_processed` | int | Total memories reviewed |\n| `compressed` | int | Number of memories consolidated |\n| `forgotten` | int | Number of memories deleted |\n\n## Scheduler Configuration\n\nThe consolidation scheduler runs automated tasks based on configured schedules:\n\n```mermaid\ngraph LR\n A[Scheduler Init] --> B{Job Queue}\n B --> C[Daily Job
T+00:00]\n B --> D[Weekly Job
Sunday T+02:00]\n B --> E[Monthly Job
1st T+03:00]\n```\n\n**Scheduler Status Model:**\n\n```python\nCompactSchedulerStatus:\n running: bool\n next_daily: datetime | None\n next_weekly: datetime | None\n next_monthly: datetime | None\n jobs_executed: int\n jobs_failed: int\n```\n\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\n## Decay Algorithm\n\nThe decay module applies relevance scoring based on memory age and access patterns:\n\n```python\ndef calculate_decay_score(memory_age_days: int, access_frequency: float) -> float:\n \"\"\"\n Returns relevance score between 0.0 and 1.0\n Lower scores indicate memories approaching forgetting threshold\n \"\"\"\n```\n\n**Decay Factors:**\n\n| Factor | Description | Weight |\n|--------|-------------|--------|\n| Time Since Creation | Older memories decay faster | 0.4 |\n| Access Frequency | Frequently accessed memories decay slower | 0.3 |\n| Tag Relevance | Tagged memories maintain higher scores | 0.2 |\n| Memory Type | System vs user memory decay rates differ | 0.1 |\n\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\n## Forgetting Mechanism\n\nThe forgetting module determines which memories should be permanently removed:\n\n```python\ndef should_forget(memory: Memory, horizon: str) -> bool:\n \"\"\"\n Evaluates if a memory meets forgetting criteria\n Returns True if memory should be deleted\n \"\"\"\n```\n\n**Forgetting Criteria by Horizon:**\n\n| Horizon | Age Threshold | Min Decay Score | Additional Checks |\n|---------|--------------|-----------------|-------------------|\n| `daily` | 90 days | 0.1 | None |\n| `weekly` | 180 days | 0.2 | Duplicate detection |\n| `monthly` | 365 days | 0.3 | Pattern analysis |\n\n**Safety Features:**\n- Automatic backup before deletion\n- Transaction-based deletion (atomic rollback on failure)\n- Database lock detection to prevent concurrent access issues\n- Disk space verification before execution\n\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\n## Performance Characteristics\n\n| Metric | Value |\n|--------|-------|\n| Typical Duration | 10-30 seconds (varies with memory count) |\n| Scaling | ~10ms per memory processed |\n| Memory Overhead | <10MB during operation |\n| Background Operation | Non-blocking in HTTP server context |\n\n**Performance Tips:**\n- Schedule consolidation during low-usage periods\n- Large stores (>10,000 memories) may take longer\n- Disable automatic scheduling for resource-constrained environments\n\n## Insights Generation\n\nAfter consolidation, the insights module analyzes patterns:\n\n```python\ndef generate_insights(consolidated_memories: List[Memory]) -> List[Insight]:\n \"\"\"\n Produces actionable insights from consolidated memory patterns\n \"\"\"\n```\n\n**Insight Types:**\n\n| Type | Description |\n|------|-------------|\n| `pattern` | Recurring themes detected |\n| `summary` | Condensed representation of grouped memories |\n| `recommendation` | Suggestions based on memory patterns |\n| `conflict` | Detected contradictions between memories |\n\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\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MCP_CONSOLIDATION_ENABLED` | `true` | Enable/disable automatic consolidation |\n| `MCP_CONSOLIDATION_SCHEDULE` | `daily` | Default schedule |\n| `MCP_MAX_RESPONSE_CHARS` | `0` | Response truncation (0 = unlimited) |\n\n### Scheduler Settings\n\nConfigure in `~/.claude/hooks/config.json`:\n\n```json\n{\n \"consolidation\": {\n \"schedule\": {\n \"daily\": \"0 0 * * *\",\n \"weekly\": \"0 2 * * 0\",\n \"monthly\": \"0 3 1 * *\"\n },\n \"enabled\": true,\n \"horizons\": [\"daily\", \"weekly\"]\n }\n}\n```\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Cause | Solution |\n|-------|-------|----------|\n| Consolidation fails silently | Database locked | Stop MCP clients before running |\n| High memory usage during consolidation | Large store size | Increase `MCP_MAX_RESPONSE_CHARS` |\n| Scheduler not running | Service not started | Check `systemctl --user status mcp-memory.service` |\n\n### Verification\n\n```bash\n# Check scheduler status\ncurl https://localhost:8443/api/consolidate/status\n\n# Manual consolidation (dry-run)\ncurl -X POST https://localhost:8443/api/consolidate \\\n -d '{\"time_horizon\": \"weekly\", \"dry_run\": true}'\n```\n\n## Further Reference\n\n- [Memory Consolidation Guide](docs/guides/memory-consolidation-guide.md) - Detailed usage documentation\n- [API Reference](src/mcp_memory_service/api/operations.py) - Full API specification\n- [CLI Commands](claude_commands/README.md) - Command-line consolidation tools\n\n---\n\n\n\n## Quality Scoring System\n\n### 相关页面\n\n相关主题：[Memory Consolidation Engine](#consolidation-engine), [System Architecture](#architecture), [Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp_memory_service/quality/\\_\\_init\\_\\_.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/__init__.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/scorer.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/scorer.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/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/quality/config.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/config.py)\n- [src/mcp_memory_service/server/handlers/quality.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)\n \n\n# Quality Scoring System\n\nThe Quality Scoring System is a multi-layered evaluation framework within the MCP Memory Service that assesses, ranks, and maintains memory content quality. It provides both automatic quality assessment through machine learning models and explicit user feedback mechanisms to ensure that memories retain high-value information over time.\n\n## Overview\n\nThe system addresses a fundamental challenge in semantic memory systems: not all stored memories have equal importance or relevance. Over time, memory stores can become cluttered with transient information, low-value summaries, and outdated content that degrades the overall utility of the memory service.\n\nThe Quality Scoring System solves this by implementing:\n\n- **Automatic Quality Assessment**: Uses ONNX-based ML models to evaluate content quality without manual intervention\n- **Implicit Signal Detection**: Analyzes behavioral patterns to infer memory importance\n- **Manual Rating Support**: Allows users to explicitly rate memory quality\n- **Quality-Aware Search**: Boosts high-quality memories in search results\n- **Maintenance Operations**: Provides tools for quality-based memory management\n\n## Architecture\n\nThe Quality Scoring System follows a modular architecture with four primary components that work together to provide comprehensive quality evaluation.\n\n```mermaid\ngraph TD\n A[Memory Content] --> B[QualityScorer]\n B --> C[ONNXRankerModel]\n B --> D[QualityEvaluator]\n B --> E[ImplicitSignalsEvaluator]\n \n C --> F[CompactSearchResult]\n D --> F\n E --> F\n \n G[User Rating] --> H[handle_rate_memory]\n H --> B\n \n I[Search Query] --> J[quality_boost Parameter]\n J --> F\n \n K[Maintenance Operations] --> L[handle_maintain]\n L --> B\n```\n\n## Core Components\n\n### QualityConfig\n\nThe `QualityConfig` class provides centralized configuration for the quality scoring system. It defines thresholds, weights, and behavioral parameters that control how quality is evaluated.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `min_quality` | float | 0.0 | Minimum quality threshold for inclusion |\n| `max_quality` | float | 1.0 | Maximum possible quality score |\n| `boost_weight` | float | varies | Weight given to quality in search ranking |\n| `implicit_weight` | float | varies | Weight for implicit signal evaluation |\n\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\n### QualityScorer\n\nThe `QualityScorer` is the main orchestrator class that coordinates quality evaluation across all sub-components. It aggregates scores from different evaluation methods and produces a unified quality score.\n\n```python\nclass QualityScorer:\n def __init__(self, config: QualityConfig):\n self.config = config\n self.ranker = ONNXRankerModel()\n self.evaluator = QualityEvaluator()\n self.implicit_evaluator = ImplicitSignalsEvaluator()\n```\n\n**Key Responsibilities:**\n- Aggregates scores from ONNX ranker, AI evaluator, and implicit signals\n- Provides a unified `get_score()` interface\n- Handles caching and optimization for repeated evaluations\n- Manages configuration propagation to sub-components\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\n### ONNXRankerModel\n\nThe `ONNXRankerModel` provides fast, offline-capable quality ranking using ONNX Runtime. This model evaluates content based on learned patterns of what constitutes high-quality memory content.\n\n**Advantages of ONNX-based ranking:**\n- Runs entirely offline without external API dependencies\n- Fast inference suitable for real-time evaluation\n- Portable across different platforms and hardware\n- No per-token costs unlike cloud-based alternatives\n\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\n### QualityEvaluator\n\nThe `QualityEvaluator` provides AI-based quality assessment, likely utilizing more sophisticated language model analysis for nuanced content quality determination.\n\n**Evaluation Criteria:**\n- Content specificity and detail level\n- Actionability of information\n- Temporal relevance\n- Uniqueness of content\n\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\n### ImplicitSignalsEvaluator\n\nThe `ImplicitSignalsEvaluator` analyzes behavioral patterns to infer memory importance without explicit user feedback. This component detects signals that suggest a memory's value based on how it's accessed and used.\n\n**Implicit Signals:**\n- Retrieval frequency\n- Retrieval timing patterns\n- Context of retrieval requests\n- Cross-referencing with other memories\n\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\n## Module Exports\n\nAll quality scoring components are exported through the main quality module interface:\n\n```python\nfrom mcp_memory_service.quality import (\n QualityScorer,\n ONNXRankerModel,\n QualityEvaluator,\n ImplicitSignalsEvaluator,\n QualityConfig\n)\n```\n\n资料来源：[src/mcp_memory_service/quality/__init__.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/quality/__init__.py)\n\n## API Integration\n\n### Quality-Aware Search\n\nThe quality scoring system integrates with the search API through the `quality_boost` parameter. When performing semantic or hybrid searches, memories with higher quality scores receive ranking boosts.\n\n**Search Parameters Related to Quality:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `quality_boost` | float | 0.0 | Weight for quality-based ranking (0.0-1.0) |\n| `min_quality` | float | 0.0 | Minimum quality threshold filter |\n| `include_debug` | bool | false | Include quality scoring details in response |\n\n**Implementation in Memory Handler:**\n```python\nquality_boost=arguments.get(\"quality_boost\", 0.0),\nlimit=limit,\ninclude_debug=arguments.get(\"include_debug\", False),\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py:26-32](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### Quality Scoring in Results\n\nThe `CompactSearchResult` type includes a `score` field that represents the relevance score, which incorporates quality assessment when `quality_boost` is enabled.\n\n**CompactMemory Score Field:**\n```python\nclass CompactMemory(NamedTuple):\n hash: str # 8-character content hash\n preview: str # First 200 characters\n tags: tuple[str, ...] # Immutable tags tuple\n created: float # Unix timestamp\n score: float # Relevance score 0-1\n```\n\n资料来源：[src/mcp_memory_service/api/types.py:48-56](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/types.py)\n\n## Quality Actions Handler\n\nThe quality system exposes several actions through the `memory_quality` tool handler, providing programmatic access to quality operations.\n\n### Action Types\n\n| Action | Description | Required Parameters |\n|--------|-------------|---------------------|\n| `rate` | Manually rate a memory's quality | `content_hash`, `rating` |\n| `analyze` | Analyze quality distribution | `min_quality`, `max_quality` |\n| `maintain` | Run quality-based maintenance | varies |\n| `maintain_status` | Check maintenance status | none |\n\n### Rate Memory Action\n\nAllows explicit user feedback on memory quality:\n\n```python\nasync def handle_rate_memory(server, arguments: dict) -> List[types.TextContent]:\n content_hash = arguments.get(\"content_hash\")\n rating = arguments.get(\"rating\")\n feedback = arguments.get(\"feedback\", \"\")\n```\n\n**Parameters:**\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content_hash` | string | Yes | Hash of the memory to rate |\n| `rating` | integer/string | Yes | Quality rating (converted to integer) |\n| `feedback` | string | No | Optional feedback text |\n\n资料来源：[src/mcp_memory_service/server/handlers/quality.py:47-59](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)\n\n### Analyze Quality Distribution\n\nProvides statistical analysis of memory quality across the store:\n\n```python\nelif action == \"analyze\":\n return await handle_analyze_quality_distribution(server, {\n \"min_quality\": arguments.get(\"min_quality\", 0.0),\n \"max_quality\": arguments.get(\"max_quality\", 1.0)\n })\n```\n\n### Maintenance Operations\n\nThe maintain action provides automated quality-based memory management:\n\n```python\nelif action == \"maintain\":\n return await handle_maintain(server, arguments)\n\nelif action == \"maintain_status\":\n return await handle_maintain_status()\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/quality.py:30-38](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/quality.py)\n\n## Workflow Diagrams\n\n### Quality Evaluation Flow\n\n```mermaid\ngraph LR\n A[Incoming Memory] --> B{Is cached?}\n B -->|No| C[Run ONNX Ranker]\n C --> D[Run AI Evaluator]\n D --> E[Run Implicit Signals]\n E --> F[Aggregate Scores]\n F --> G[Compute Final Quality]\n G --> H[Cache Result]\n H --> I[Return Score]\n \n B -->|Yes| I\n```\n\n### Quality-Aware Search Flow\n\n```mermaid\ngraph TD\n A[Search Query] --> B[Semantic Search]\n B --> C[Initial Results]\n C --> D{quality_boost > 0?}\n D -->|Yes| E[Fetch Quality Scores]\n D -->|No| H[Return Results]\n E --> F[Apply Quality Boost]\n F --> G[Re-rank Results]\n G --> H\n```\n\n## Usage Examples\n\n### Basic Quality Evaluation\n\n```python\nfrom mcp_memory_service.quality import QualityScorer, QualityConfig\n\nconfig = QualityConfig(min_quality=0.5, boost_weight=0.3)\nscorer = QualityScorer(config)\n\nquality_score = scorer.get_score(memory_content)\nprint(f\"Quality score: {quality_score}\")\n```\n\n### Quality-Boosted Search\n\nWhen searching with quality consideration:\n\n```python\nresults = await search_memories(\n query=\"architecture decisions\",\n quality_boost=0.5, # Apply quality weighting\n limit=10\n)\n```\n\n### Manual Rating\n\n```python\nresult = await handle_rate_memory(server, {\n \"content_hash\": \"abc12345\",\n \"rating\": 4,\n \"feedback\": \"Important architectural decision\"\n})\n```\n\n## Configuration Best Practices\n\n### Performance vs Accuracy\n\n| Use Case | Configuration | Rationale |\n|----------|--------------|-----------|\n| Real-time search | `quality_boost=0.2-0.3` | Balance relevance with performance |\n| High-precision retrieval | `quality_boost=0.5-0.7` | Prioritize quality over recall |\n| Maintenance/cleanup | `min_quality=0.3-0.5` | Filter low-value memories |\n\n### Thresholds\n\n| Memory Type | Recommended `min_quality` |\n|-------------|---------------------------|\n| Session summaries | 0.4 |\n| Implementation details | 0.5 |\n| Architectural decisions | 0.6 |\n| Bug fixes | 0.3 |\n| Reference documentation | 0.5 |\n\n## Summary\n\nThe Quality Scoring System provides a comprehensive framework for evaluating and managing memory content quality in the MCP Memory Service. By combining ONNX-based offline ranking, AI-powered evaluation, and implicit behavioral signals, the system ensures that high-value memories are surfaced first while providing tools for ongoing quality maintenance.\n\nThe modular architecture allows for:\n- **Scalability**: ONNX Runtime enables efficient inference at scale\n- **Flexibility**: Configurable weights and thresholds for different use cases\n- **Offline capability**: Core ranking works without network dependencies\n- **User control**: Manual rating provides explicit feedback pathways\n- **Maintenance**: Built-in tools for quality-based memory management\n\n---\n\n\n\n## REST API Reference\n\n### 相关页面\n\n相关主题：[Agent Framework Integration](#agent-frameworks), [Quick Start Guide](#quickstart)\n\n\nRelated Source Files
\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)\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- [src/mcp_memory_service/web/api/mcp.py](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.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- [scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/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 \n\n# REST API Reference\n\n## Overview\n\nThe MCP Memory Service exposes a comprehensive REST API for managing semantic memories, performing advanced searches, and subscribing to real-time events. The API serves as the primary interface for external clients, web applications, and programmatic integrations that need to interact with the memory storage backend without using the MCP (Model Context Protocol) tools.\n\nThe REST API provides four major functional areas:\n\n| Area | Description |\n|------|-------------|\n| **Memory Management** | Store, retrieve, list, and delete semantic memories |\n| **Search Operations** | Semantic similarity, tag-based, and time-based search |\n| **Real-time Events** | Server-Sent Events (SSE) for live updates |\n| **MCP Protocol** | JSON-RPC interface compatible with MCP clients |\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)\n\n## Architecture\n\nThe REST API is built on FastAPI and serves as a thin layer over the core `MemoryService` and storage backends. Requests flow through the API router to the appropriate handlers, which delegate business logic to shared services.\n\n```mermaid\ngraph TD\n A[HTTP Client] --> B[FastAPI Router]\n B --> C[/api/memories]\n B --> D[/api/search]\n B --> E[/api/events]\n B --> F[/api/mcp]\n C --> G[Memory Handler]\n D --> H[Search Handler]\n E --> I[SSE Publisher]\n F --> J[MCP Handler]\n G --> K[MemoryService]\n H --> K\n K --> L[(SQLite + sqlite_vec)]\n```\n\n资料来源：[src/mcp_memory_service/web/api/mcp.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)\n\n## Base Configuration\n\n### Server Address\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `MCP_HOST` | `0.0.0.0` | Bind address |\n| `MCP_PORT` | `8080` | HTTP port |\n| `MCP_MAX_RESPONSE_CHARS` | `0` (unlimited) | Response truncation limit |\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:1-40](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n## Memory Management Endpoints\n\n### Store a Memory\n\nCreates a new memory with automatic embedding generation.\n\n```\nPOST /api/memories\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `content` | string | body | Yes | Memory content text |\n| `tags` | string[] | body | No | List of tags |\n| `memory_type` | string | body | No | Classification type (default: \"note\") |\n| `metadata` | object | body | No | Custom metadata key-value pairs |\n\n**Response:**\n\n```json\n{\n \"content_hash\": \"abc12345\",\n \"message\": \"Memory stored successfully\"\n}\n```\n\n资料来源：[src/mcp_memory_service/api/operations.py:50-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n\n### List All Memories\n\nRetrieves memories with pagination and optional filtering.\n\n```\nGET /api/memories\n```\n\n| Parameter | Type | Location | Required | Default | Description |\n|-----------|------|----------|----------|---------|-------------|\n| `page` | integer | query | No | `1` | 1-based page number |\n| `page_size` | integer | query | No | `20` | Results per page (max: 100) |\n| `tags` | string | query | No | - | Comma-separated tag filter |\n| `tag_match` | string | query | No | `any` | Match logic: `any` (OR) or `all` (AND) |\n| `memory_type` | string | query | No | - | Filter by memory type |\n| `stale_days` | integer | query | No | - | Filter memories not accessed in N days |\n\n**Response:**\n\n```json\n{\n \"memories\": [\n {\n \"content\": \"Memory content here\",\n \"content_hash\": \"abc12345\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"memory_type\": \"note\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"updated_at\": \"2025-01-15T10:30:00Z\"\n }\n ],\n \"pagination\": {\n \"page\": 1,\n \"page_size\": 20,\n \"total_count\": 150\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py:1-50](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### Retrieve a Memory\n\nRetrieves a specific memory by its content hash.\n\n```\nGET /api/memories/{hash}\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `hash` | string | path | Yes | 8-character content hash |\n\n**Response:**\n\n```json\n{\n \"content\": \"Memory content here\",\n \"content_hash\": \"abc12345\",\n \"tags\": [\"architecture\", \"database\"],\n \"memory_type\": \"reference\",\n \"created_at\": \"2025-01-15T10:30:00Z\",\n \"updated_at\": \"2025-01-15T10:30:00Z\",\n \"metadata\": {}\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)\n\n### Delete a Memory\n\nRemoves a memory and its associated embeddings.\n\n```\nDELETE /api/memories/{hash}\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `hash` | string | path | Yes | 8-character content hash |\n\n**Response:**\n\n```json\n{\n \"success\": true,\n \"message\": \"Memory deleted successfully\"\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)\n\n## Search Operations\n\n### Semantic Search\n\nPerforms vector similarity search using text embeddings.\n\n```\nPOST /api/search\n```\n\n| Parameter | Type | Location | Required | Default | Description |\n|-----------|------|----------|----------|---------|-------------|\n| `query` | string | body | Yes | - | Search query text |\n| `limit` | integer | body | No | `5` | Maximum results (1-100) |\n| `tags` | string[] | body | No | - | Filter by tags |\n| `threshold` | float | body | No | `0.0` | Minimum relevance score |\n| `hybrid` | boolean | body | No | `false` | Enable BM25 fallback at threshold 0.4 |\n\n**Response:**\n\n```json\n{\n \"memories\": [\n {\n \"content_hash\": \"abc12345\",\n \"content\": \"Memory content...\",\n \"tags\": [\"tag1\"],\n \"relevance_score\": 0.87,\n \"match_method\": \"vector\"\n }\n ],\n \"found\": 1,\n \"shown\": 1\n}\n```\n\n资料来源：[src/mcp_memory_service/api/operations.py:100-150](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/api/operations.py)\n\n### Tag-Based Search\n\nSearches memories using tags with AND/OR logic.\n\n```\nPOST /api/search/by-tag\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `tags` | string[] | body | Yes | List of tags to search |\n| `match_all` | boolean | body | No | `true` for AND, `false` for OR |\n\n**Response:**\n\n```json\n{\n \"memories\": [\n {\n \"content\": \"Memory content\",\n \"content_hash\": \"abc12345\",\n \"tags\": [\"python\", \"reference\"]\n }\n ],\n \"total_found\": 5\n}\n```\n\n资料来源：[src/mcp_memory_service/server/handlers/memory.py:50-100](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/handlers/memory.py)\n\n### Time-Based Search\n\nNatural language time-based queries for temporal memory retrieval.\n\n```\nPOST /api/search/by-time\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `time_query` | string | body | Yes | Natural language time expression |\n| `time_start` | float | body | No | Unix timestamp start |\n| `time_end` | float | body | No | Unix timestamp end |\n\n**Example Queries:**\n\n| Expression | Interpretation |\n|------------|----------------|\n| `last week` | 7 days ago to now |\n| `yesterday's architectural discussions` | Previous day |\n| `between 2025-01-01 and 2025-01-31` | Date range |\n\n资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n\n### Find Similar Memories\n\nFinds memories semantically similar to a specific memory by hash.\n\n```\nGET /api/search/similar/{hash}\n```\n\n| Parameter | Type | Location | Required | Description |\n|-----------|------|----------|----------|-------------|\n| `hash` | string | path | Yes | Content hash of reference memory |\n| `limit` | integer | query | No | Maximum similar memories to return |\n\n**Response:**\n\n```json\n{\n \"reference_hash\": \"abc12345\",\n \"similar\": [\n {\n \"content_hash\": \"def67890\",\n \"content\": \"Similar memory content...\",\n \"similarity_score\": 0.92\n }\n ]\n}\n```\n\n## Real-time Events (SSE)\n\n### Subscribe to Memory Events\n\nServer-Sent Events stream for live memory activity.\n\n```\nGET /api/events\n```\n\n**Event Types:**\n\n| Event | Description |\n|-------|-------------|\n| `memory_stored` | New memory added |\n| `memory_deleted` | Memory removed |\n| `memory_updated` | Memory modified |\n| `embedding_complete` | Async embedding finished |\n\n**Example SSE Payload:**\n\n```\nevent: memory_stored\ndata: {\"content_hash\": \"abc12345\", \"timestamp\": \"2025-01-15T10:30:00Z\"}\n\nevent: memory_deleted\ndata: {\"content_hash\": \"def67890\", \"timestamp\": \"2025-01-15T10:35:00Z\"}\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)\n\n### SSE Statistics\n\nView connection statistics for SSE endpoints.\n\n```\nGET /api/events/stats\n```\n\n**Response:**\n\n```json\n{\n \"active_connections\": 2,\n \"total_events_sent\": 1450,\n \"uptime_seconds\": 86400\n}\n```\n\n## MCP Protocol Endpoint\n\nThe MCP-compatible JSON-RPC endpoint enables integration with MCP clients.\n\n```\nPOST /api/mcp\n```\n\n### Supported Methods\n\n| Method | Description |\n|--------|-------------|\n| `initialize` | Initialize MCP session, returns server capabilities |\n| `tools/list` | List available MCP tools |\n| `tools/call` | Execute a named MCP tool |\n\n### Initialize Request\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {}\n }\n}\n```\n\n**Response:**\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {\"tools\": {}},\n \"serverInfo\": {\n \"name\": \"mcp-memory-service\",\n \"version\": \"4.1.1\"\n }\n }\n}\n```\n\n### Tools List\n\nReturns all available MCP tools with their schemas.\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/list\"\n}\n```\n\n### Tool Call\n\nExecute a named tool with arguments.\n\n```json\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"memory_search\",\n \"arguments\": {\n \"query\": \"architecture decisions\",\n \"limit\": 5\n }\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/web/api/mcp.py:20-60](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/web/api/mcp.py)\n\n## Response Limiting\n\nThe API implements automatic response truncation to prevent context window overflow.\n\n### Behavior\n\n| Scenario | Action |\n|----------|--------|\n| `MCP_MAX_RESPONSE_CHARS=0` | No limit (backward compatible) |\n| `MCP_MAX_RESPONSE_CHARS>0` | Truncate at memory boundaries |\n| Response truncated | Include warning header |\n\n### Truncation Metadata\n\nWhen responses are truncated, the following metadata is included:\n\n```json\n{\n \"warning\": \"RESPONSE TRUNCATED: Showing 5 of 25 results (15000 of 75000 chars)\",\n \"meta\": {\n \"truncated\": true,\n \"shown_results\": 5,\n \"total_results\": 25,\n \"shown_chars\": 15000,\n \"total_chars\": 75000,\n \"omitted_count\": 20\n }\n}\n```\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:60-120](https://github.com/doobidoo/mcp-memory-service/blob/main/src/mcp_memory_service/server/utils/response_limiter.py)\n\n## Data Models\n\n### Memory Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `content` | string | Memory text content |\n| `content_hash` | string | 8-character SHA256 hash |\n| `tags` | string[] | Associated tags |\n| `memory_type` | string | Classification (note, reference, decision, etc.) |\n| `created_at` | ISO8601 | Creation timestamp |\n| `updated_at` | ISO8601 | Last modification timestamp |\n| `metadata` | object | Custom key-value pairs |\n| `created_at_iso` | string | ISO format creation time |\n| `updated_at_iso` | string | ISO format modification time |\n\n### Search Result\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `memories` | Memory[] | Matching memories |\n| `found` | integer | Total matches |\n| `shown` | integer | Results returned (after limit) |\n| `query_time_ms` | float | Search duration |\n\n## Export Endpoints\n\n### Export Memories\n\nExport memories in text or JSON format for backup and migration.\n\n```\nGET /api/export\n```\n\n| Parameter | Type | Location | Description |\n|-----------|------|----------|-------------|\n| `format` | string | query | `text` or `json` (default: `text`) |\n\n**JSON Export Format:**\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 \"exporter_version\": \"5.0.0\"\n },\n \"memories\": [\n {\n \"content\": \"Memory content here\",\n \"content_hash\": \"sha256hash\",\n \"tags\": [\"tag1\", \"tag2\"],\n \"created_at\": 1673545200.0,\n \"updated_at\": 1673545200.0,\n \"memory_type\": \"note\",\n \"metadata\": {},\n \"export_source\": \"machine-name\"\n }\n ]\n}\n```\n\n资料来源：[scripts/sync/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/scripts/sync/README.md)\n\n## Performance Characteristics\n\n| Operation | First Call | Subsequent Calls |\n|------------|------------|-------------------|\n| Search | ~50ms | ~5-10ms |\n| Store | ~50ms | ~10-20ms |\n| Health Check | ~50ms | ~5ms |\n\n**Cost Estimate:** At $0.15/1M tokens: ~$16.43/year per 10-user deployment.\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## API Client Library\n\nFor programmatic access, use the Python client:\n\n```python\nfrom mcp_memory_service.api import search, store, health\n\n# Store a memory\nhash = store(\"New memory\", tags=[\"note\", \"important\"])\n\n# Search memories\nresults = search(\"architecture decisions\", limit=5)\nfor m in results.memories:\n print(f\"{m.hash}: {m.preview[:50]}...\")\n\n# Health check\ninfo = health()\nprint(f\"Backend: {info.backend}, Count: {info.count}\")\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## Error Handling\n\n### Standard Error Response\n\n```json\n{\n \"error\": {\n \"code\": -32601,\n \"message\": \"Method not found: {method}\"\n }\n}\n```\n\n### Error Codes\n\n| Code | Meaning |\n|------|---------|\n| `-32600` | Invalid Request |\n| `-32601` | Method not found |\n| `-32602` | Invalid params |\n| `-32603` | Internal error |\n| `-32000` | Storage unavailable |\n\n## Documentation\n\nInteractive API documentation is available at:\n\n| URL | Format |\n|-----|--------|\n| `/api/docs` | Swagger UI |\n| `/api/redoc` | ReDoc |\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)\n\n---\n\n\n\n## Agent Framework Integration\n\n### 相关页面\n\n相关主题：[REST API Reference](#rest-api), [Quick Start Guide](#quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/agents/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/README.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- [docs/agents/http-generic.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/http-generic.md)\n- [docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)\n \n\n# Agent Framework Integration\n\nThe MCP Memory Service provides comprehensive integration capabilities with various AI agent frameworks, enabling persistent semantic memory storage and retrieval across multi-agent architectures. This integration layer allows autonomous agents to maintain contextual awareness, share knowledge, and persist learning across sessions.\n\n## Overview\n\nThe MCP Memory Service functions as a central knowledge backbone for AI agent frameworks. Rather than requiring each agent to maintain isolated memory stores, the service provides a unified semantic memory layer that can be accessed via:\n\n- **Model Context Protocol (MCP) Tools**: Native integration for MCP-compatible agents\n- **REST API**: HTTP-based access for any framework with HTTP client capabilities\n- **Direct Python API**: Programmatic access for Python-native frameworks\n\nThis architecture enables agents to:\n\n- Store discovered facts and learned patterns\n- Retrieve contextually relevant memories during reasoning\n- Share knowledge across agent teams\n- Maintain persistent state across sessions\n\n资料来源：[src/mcp_memory_service/api/__init__.py:1-50]()\n\n## Supported Agent Frameworks\n\nThe MCP Memory Service integrates with the following agent frameworks through dedicated documentation and examples:\n\n| Framework | Integration Type | Documentation |\n|-----------|------------------|---------------|\n| LangGraph | SDK/Graph-based | `docs/agents/langgraph.md` |\n| CrewAI | Team-based agents | `docs/agents/crewai.md` |\n| AutoGen | Multi-agent conversations | `docs/agents/autogen.md` |\n| Custom Frameworks | HTTP/REST | `docs/agents/http-generic.md` |\n\n资料来源：[docs/agents/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/README.md)\n\n## Architecture for Multi-Agent Systems\n\n```mermaid\ngraph TD\n A[Agent Framework] --> B[MCP Memory Service API]\n B --> C[Memory Management Layer]\n C --> D[(SQLite-vec Storage)]\n C --> E[(Cloudflare D1)]\n \n F[Agent 1] --> B\n G[Agent 2] --> B\n H[Agent N] --> B\n \n I[Embedding Generation] --> C\n J[all-MiniLM-L6-v2] --> I\n```\n\n### Memory Flow in Agent Workflows\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP as MCP Memory Service\n participant Storage as Vector Storage\n \n Agent->>MCP: Store Memory (content, tags)\n MCP->>MCP: Generate Embedding\n MCP->>Storage: Store + Index\n Storage-->>MCP: Confirm\n MCP-->>Agent: Content Hash\n \n Agent->>MCP: Semantic Search (query)\n MCP->>MCP: Generate Query Embedding\n MCP->>Storage: Similarity Search\n Storage-->>MCP: Top-K Results\n MCP-->>Agent: Relevant Memories\n```\n\n资料来源：[docs/guides/AGENTS.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/guides/AGENTS.md)\n\n## MCP Prompt Integration\n\nThe service exposes specialized prompts for agent workflows beyond basic memory operations:\n\n### Available Agent Prompts\n\n| Prompt Name | Purpose | Required Arguments |\n|-------------|---------|-------------------|\n| `knowledge_export` | Export memories in specific formats | `format` (json/markdown/text) |\n| `memory_cleanup` | Remove duplicates/outdated memories | `older_than`, `similarity_threshold` |\n| `learning_session` | Store structured learning notes | `topic`, `key_points` |\n\n资料来源：[src/mcp_memory_service/server_impl.py:150-200]()\n\n### Prompt Argument Specifications\n\n```python\ntypes.PromptArgument(\n name=\"format\",\n description=\"Export format (json, markdown, text)\",\n required=True\n)\ntypes.PromptArgument(\n name=\"older_than\",\n description=\"Remove memories older than (e.g., '6 months', '1 year')\",\n required=False\n)\ntypes.PromptArgument(\n name=\"similarity_threshold\",\n description=\"Similarity threshold for duplicates (0.0-1.0)\",\n required=False\n)\n```\n\n## REST API Integration\n\nFor agent frameworks that prefer HTTP-based communication, the service provides a comprehensive REST API:\n\n### Core Endpoints\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| POST | `/api/memories` | Store new memory |\n| GET | `/api/memories` | List memories with pagination |\n| GET | `/api/memories/{hash}` | Retrieve specific memory |\n| DELETE | `/api/memories/{hash}` | Delete memory |\n| POST | `/api/search` | Semantic similarity search |\n| GET | `/api/search/similar/{hash}` | Find similar memories |\n\n资料来源：[src/mcp_memory_service/web/app.py:50-100]()\n\n### Response Truncation for Agent Context\n\nTo prevent context overflow in agent prompts, the response limiter intelligently truncates results:\n\n```\n[!] RESPONSE TRUNCATED: Showing 5 of 20 results\n(1500 of 8000 chars).\n3 result(s) omitted to prevent context overflow.\nUse specific queries or hash-based retrieval for full content.\n```\n\n资料来源：[src/mcp_memory_service/server/utils/response_limiter.py:30-60]()\n\n## Claude Code Integration\n\nThe MCP Memory Service includes specialized hooks for Claude Code CLI integration:\n\n### Available Claude Commands\n\n| Command | Purpose |\n|---------|---------|\n| `/memory-recall` | Time-based memory retrieval using natural language |\n| `/memory-search` | Tag and content search |\n| `/memory-context` | Session context integration with machine source ID |\n| `/memory-health` | Service health diagnostics |\n\n资料来源：[claude_commands/README.md](https://github.com/doobidoo/mcp-memory-service/blob/main/claude_commands/README.md)\n\n### Session Hook Workflow\n\n```mermaid\ngraph LR\n A[Session Start] --> B[Load Relevant Memories]\n B --> C[Inject into Context]\n \n D[During Session] --> E[Track Decisions]\n E --> F[Store Key Insights]\n \n G[Session End] --> H[Save Decisions]\n H --> I[Archive Insights]\n I --> J[Persistent Storage]\n```\n\n## Performance Characteristics for Agents\n\n| Metric | Value | Notes |\n|--------|-------|-------|\n| First Call Latency | ~50ms | Includes storage initialization |\n| Subsequent Calls | ~5-10ms | Connection reused |\n| Memory Overhead | <10MB | Per agent instance |\n| Embedding Model | all-MiniLM-L6-v2 | 384-dimensional vectors |\n| Cost (10 users) | $16.43/year | At $0.15/1M tokens |\n\n资料来源：[src/mcp_memory_service/api/__init__.py:10-20]()\n\n## Installation and Setup\n\n### Automatic Installation\n\n```bash\n# Install with commands (detects Claude Code CLI)\npython scripts/installation/install.py\n\n# Force install commands\npython scripts/installation/install.py --install-claude-commands\n```\n\n### Manual HTTP Integration\n\nFor custom agent frameworks:\n\n```python\nimport httpx\n\nasync def store_agent_memory(content: str, tags: list[str]):\n async with httpx.AsyncClient() as client:\n response = await client.post(\n \"https://your-endpoint:8443/api/memories\",\n json={\"content\": content, \"tags\": tags}\n )\n return response.json()\n```\n\n资料来源：[docs/agents/http-generic.md](https://github.com/doobidoo/mcp-memory-service/blob/main/docs/agents/http-generic.md)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| Hooks not detected | Check `ls ~/.claude/settings.json` and reinstall |\n| JSON parse errors | Update to latest version with Python dict conversion |\n| Connection failed | Verify `curl -k https://your-endpoint:8443/api/health` |\n| Wrong directory | Move `~/.claude-code/hooks/*` to `~/.claude/hooks/` |\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## Doramagic Pitfall Log\n\nProject: doobidoo/mcp-memory-service\n\nSummary: Found 39 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare).\n\n## 1. security_permissions · 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_d0f9028fc870496f9576de28c5355817 | https://github.com/doobidoo/mcp-memory-service/issues/950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. installation · 失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- User impact: Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_dd89642370c2dba2d6aacf12756658a6 | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare), failure_mode_cluster:github_issue | fmev_07b451a0081c6435e7494e041a6641bc | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n## 3. installation · 失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- User impact: Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_74209176888c160a35483f3156117496 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_d8321b2cf697c747506701fd9f641fef | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_89d7bb3a956afe53a7a303ded77ab494 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_4d3ba37fa05ae6ea3d30aa7e6acbf4a4 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n## 4. installation · 失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- User impact: Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_b14a35b730602b08a29e3abbdfa0c377 | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug, failure_mode_cluster:github_issue | fmev_a2aed67ef427fc7f9ddeebb038420d7d | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n## 5. installation · 失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- User impact: Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_d0ce94252816336aa4ecbd45eeb73603 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.0 | v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n## 6. installation · 失败模式：installation: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- User impact: Upgrade or migration may change expected behavior: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.1 — OAuth state parameter RFC 6749 compliance fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_a0594e0fe855897f4612a17f520e81d4 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.1 | v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n## 7. installation · 失败模式：installation: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- User impact: Upgrade or migration may change expected behavior: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_8a1390fb930fb3d5c55aee894e53c0e3 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.2 | v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n## 8. installation · 失败模式：installation: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- User impact: Upgrade or migration may change expected behavior: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_cce458b1322f9ccb8db2498d3499650d | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.63.0 | v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n## 9. installation · 来源证据：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_…\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_all_memories'\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_da505f8e644d4dedbe7b94f2026f2c47 | https://github.com/doobidoo/mcp-memory-service/issues/981 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. installation · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. installation · 来源证据：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_99e7481daede4079a5bb8c96cba781ba | https://github.com/doobidoo/mcp-memory-service/issues/957 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. installation · 来源证据：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2027915616af406998b039c789f84c69 | https://github.com/doobidoo/mcp-memory-service/issues/938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. installation · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. installation · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n\n## 16. configuration · 失败模式：configuration: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- User impact: Developers may misconfigure credentials, environment, or host setup: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`). Context: Observed when using python, linux\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_d1e6b62e41c0cf3c6d4867576ec205f2 | https://github.com/doobidoo/mcp-memory-service/issues/941 | Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n\n## 17. configuration · 失败模式：configuration: [automated] Contributor activity digest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: [automated] Contributor activity digest\n- User impact: Developers may misconfigure credentials, environment, or host setup: [automated] Contributor activity digest\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [automated] Contributor activity digest. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_cdd98907ecf0813d3cca5938d053939d | https://github.com/doobidoo/mcp-memory-service/issues/937 | [automated] Contributor activity digest\n\n## 18. configuration · 失败模式：configuration: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shippe...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_886eb379e3e7ddfb3838d01f459a2a13 | https://github.com/doobidoo/mcp-memory-service/issues/959 | bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n\n## 19. configuration · 失败模式：configuration: feat: cascading search fallback when semantic results are sparse\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: feat: cascading search fallback when semantic results are sparse\n- User impact: Developers may misconfigure credentials, environment, or host setup: feat: cascading search fallback when semantic results are sparse\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat: cascading search fallback when semantic results are sparse. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8fc694ce4bba9729e62b19e988a1d8b6 | https://github.com/doobidoo/mcp-memory-service/issues/873 | feat: cascading search fallback when semantic results are sparse\n\n## 20. configuration · 失败模式：configuration: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgemen...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n- User impact: Upgrade or migration may change expected behavior: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e88b18989bddcec0f1d8e4edabb3137e | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.58.0 | v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n\n## 21. configuration · 失败模式：configuration: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n- User impact: Upgrade or migration may change expected behavior: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_8d10e56924a64499b0765864db43f654 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.2 | v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n\n## 22. configuration · 失败模式：configuration: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n- User impact: Upgrade or migration may change expected behavior: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_df9c592e9c921338e81c926f496f3755 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.1 | v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n\n## 23. configuration · 来源证据：Support Kiro CLI JSONL format in memory_harvest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support Kiro CLI JSONL format in memory_harvest\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3c9e617ea7184d08ae031c4983f4787c | https://github.com/doobidoo/mcp-memory-service/issues/934 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 24. configuration · 来源证据：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_fdf4f21de0234532b94ed2ffe3673c4e | https://github.com/doobidoo/mcp-memory-service/issues/959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 25. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\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\n## 26. runtime · 来源证据：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_4c07b5794f0741d8b76a3e94ca317421 | https://github.com/doobidoo/mcp-memory-service/issues/972 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 27. maintenance · 失败模式：migration: Support Kiro CLI JSONL format in memory_harvest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Support Kiro CLI JSONL format in memory_harvest\n- User impact: Developers may hit a documented source-backed failure mode: Support Kiro CLI JSONL format in memory_harvest\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Support Kiro CLI JSONL format in memory_harvest. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_ccb1d35700dbdd7961b19ca816ab2ec2 | https://github.com/doobidoo/mcp-memory-service/issues/934 | Support Kiro CLI JSONL format in memory_harvest\n\n## 28. maintenance · 失败模式：migration: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Se...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- User impact: Developers may hit a documented source-backed failure mode: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix. Context: Observed when using python, docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_474dd77beac7531143e2c9c8c014d21e | https://github.com/doobidoo/mcp-memory-service/issues/938 | fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n\n## 29. maintenance · 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 30. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n\n## 31. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 32. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 33. security_permissions · 来源证据：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_aa1db2bf08304d3db87350b8cbc8e6ca | https://github.com/doobidoo/mcp-memory-service/issues/941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 34. security_permissions · 来源证据：[automated] Contributor activity digest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[automated] Contributor activity digest\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0676e682588642899da4243174241e7b | https://github.com/doobidoo/mcp-memory-service/issues/937 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 35. security_permissions · 来源证据：feat: cascading search fallback when semantic results are sparse\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 36. security_permissions · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 37. security_permissions · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 38. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown\n\n## 39. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: doobidoo/mcp-memory-service\n\nSummary: Found 39 potential pitfall items; 1 are high/blocking. Highest priority: security_permissions - 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare).\n\n## 1. security_permissions · 来源证据：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Severity: high\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_d0f9028fc870496f9576de28c5355817 | https://github.com/doobidoo/mcp-memory-service/issues/950 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. installation · 失败模式：installation: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- User impact: Developers may fail before the first successful local run: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare). Context: Observed when using node, python, docker, macos\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_dd89642370c2dba2d6aacf12756658a6 | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare), failure_mode_cluster:github_issue | fmev_07b451a0081c6435e7494e041a6641bc | https://github.com/doobidoo/mcp-memory-service/issues/950 | [Bug]: hardcoded port in memory-client.js, breaking HTTP/HTTPS tunnels (e.g., Cloudflare)\n\n## 3. installation · 失败模式：installation: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- User impact: Developers may fail before the first successful local run: chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: chore(milvus): track optional BaseStorage overrides + test coverage gaps. Context: Observed when using docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_74209176888c160a35483f3156117496 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_d8321b2cf697c747506701fd9f641fef | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_89d7bb3a956afe53a7a303ded77ab494 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps, failure_mode_cluster:github_issue | fmev_4d3ba37fa05ae6ea3d30aa7e6acbf4a4 | https://github.com/doobidoo/mcp-memory-service/issues/888 | chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n## 4. installation · 失败模式：installation: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- User impact: Developers may fail before the first successful local run: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug. Context: Observed when using windows\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_b14a35b730602b08a29e3abbdfa0c377 | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug, failure_mode_cluster:github_issue | fmev_a2aed67ef427fc7f9ddeebb038420d7d | https://github.com/doobidoo/mcp-memory-service/issues/957 | fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n## 5. installation · 失败模式：installation: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- User impact: Upgrade or migration may change expected behavior: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_d0ce94252816336aa4ecbd45eeb73603 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.0 | v10.59.0 — OAuth PEM key files, IDE redirect URI schemes, memory-scorer affinity fix\n\n## 6. installation · 失败模式：installation: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- User impact: Upgrade or migration may change expected behavior: v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.1 — OAuth state parameter RFC 6749 compliance fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_a0594e0fe855897f4612a17f520e81d4 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.1 | v10.59.1 — OAuth state parameter RFC 6749 compliance fix\n\n## 7. installation · 失败模式：installation: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- User impact: Upgrade or migration may change expected behavior: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_8a1390fb930fb3d5c55aee894e53c0e3 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.2 | v10.60.2 — fix(milvus): brute-force query() for semantic dedup growing-segment visibility\n\n## 8. installation · 失败模式：installation: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this installation risk before relying on the project: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- User impact: Upgrade or migration may change expected behavior: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_cce458b1322f9ccb8db2498d3499650d | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.63.0 | v10.63.0 — Milvus Issue #888 Complete + Kiro CLI Harvest Fix\n\n## 9. installation · 来源证据：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_…\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Quality trends endpoint AttributeError on sqlite_vec backend: 'SqliteVecMemoryStorage' object has no attribute 'search_all_memories'\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_da505f8e644d4dedbe7b94f2026f2c47 | https://github.com/doobidoo/mcp-memory-service/issues/981 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. installation · 来源证据：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(milvus): track optional BaseStorage overrides + test coverage gaps\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_520e5021db184be199bf78f1b662b13c | https://github.com/doobidoo/mcp-memory-service/issues/888 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 11. installation · 来源证据：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(hooks): PR #952 missed `core/session-end.js` — same Cloudflare Tunnel port-fallback bug\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_99e7481daede4079a5bb8c96cba781ba | https://github.com/doobidoo/mcp-memory-service/issues/957 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 12. installation · 来源证据：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_2027915616af406998b039c789f84c69 | https://github.com/doobidoo/mcp-memory-service/issues/938 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 13. installation · 来源证据：v10.54.0 — AND/OR tag filtering for memory_search\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.54.0 — AND/OR tag filtering for memory_search\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_5aa57485baf04502a8291b6694828c38 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.54.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. installation · 来源证据：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v10.55.0 — Entity Extraction, Insight Cards, urllib3 bump\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c50e5d07aa964a89a80ade8ee3055612 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 15. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | host_targets=mcp_host, claude\n\n## 16. configuration · 失败模式：configuration: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- User impact: Developers may misconfigure credentials, environment, or host setup: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`). Context: Observed when using python, linux\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_d1e6b62e41c0cf3c6d4867576ec205f2 | https://github.com/doobidoo/mcp-memory-service/issues/941 | Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n\n## 17. configuration · 失败模式：configuration: [automated] Contributor activity digest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: [automated] Contributor activity digest\n- User impact: Developers may misconfigure credentials, environment, or host setup: [automated] Contributor activity digest\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: [automated] Contributor activity digest. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_cdd98907ecf0813d3cca5938d053939d | https://github.com/doobidoo/mcp-memory-service/issues/937 | [automated] Contributor activity digest\n\n## 18. configuration · 失败模式：configuration: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shippe...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- User impact: Developers may misconfigure credentials, environment, or host setup: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0. Context: Observed when using python\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_886eb379e3e7ddfb3838d01f459a2a13 | https://github.com/doobidoo/mcp-memory-service/issues/959 | bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n\n## 19. configuration · 失败模式：configuration: feat: cascading search fallback when semantic results are sparse\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: feat: cascading search fallback when semantic results are sparse\n- User impact: Developers may misconfigure credentials, environment, or host setup: feat: cascading search fallback when semantic results are sparse\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: feat: cascading search fallback when semantic results are sparse. Context: Source discussion did not expose a precise runtime context.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_8fc694ce4bba9729e62b19e988a1d8b6 | https://github.com/doobidoo/mcp-memory-service/issues/873 | feat: cascading search fallback when semantic results are sparse\n\n## 20. configuration · 失败模式：configuration: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgemen...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n- User impact: Upgrade or migration may change expected behavior: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_e88b18989bddcec0f1d8e4edabb3137e | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.58.0 | v10.58.0 — InsightGenerator: configurable exclusion, automated-type heuristic, acknowledgement flow\n\n## 21. configuration · 失败模式：configuration: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n- User impact: Upgrade or migration may change expected behavior: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_8d10e56924a64499b0765864db43f654 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.59.2 | v10.59.2 — fix(oauth): AnyUrl for redirect_uri, IDE schemes now functional\n\n## 22. configuration · 失败模式：configuration: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this configuration risk before relying on the project: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n- User impact: Upgrade or migration may change expected behavior: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_release | fmev_df9c592e9c921338e81c926f496f3755 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.60.1 | v10.60.1 — Milvus tag_match + session-end port fallback + contradiction detection repair\n\n## 23. configuration · 来源证据：Support Kiro CLI JSONL format in memory_harvest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Support Kiro CLI JSONL format in memory_harvest\n- User impact: 可能影响升级、迁移或版本选择。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_3c9e617ea7184d08ae031c4983f4787c | https://github.com/doobidoo/mcp-memory-service/issues/934 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 24. configuration · 来源证据：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：bug(consolidation): contradiction detection crashes on missing storage.list_memories — shipped broken in v10.60.0\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_fdf4f21de0234532b94ed2ffe3673c4e | https://github.com/doobidoo/mcp-memory-service/issues/959 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 25. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\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\n## 26. runtime · 来源证据：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：bug(harvest): Kiro CLI parser misses 80% of messages — wrong kind mapping + overzealous filter\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_4c07b5794f0741d8b76a3e94ca317421 | https://github.com/doobidoo/mcp-memory-service/issues/972 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 27. maintenance · 失败模式：migration: Support Kiro CLI JSONL format in memory_harvest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: Support Kiro CLI JSONL format in memory_harvest\n- User impact: Developers may hit a documented source-backed failure mode: Support Kiro CLI JSONL format in memory_harvest\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: Support Kiro CLI JSONL format in memory_harvest. Context: Observed during version upgrade or migration.\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_ccb1d35700dbdd7961b19ca816ab2ec2 | https://github.com/doobidoo/mcp-memory-service/issues/934 | Support Kiro CLI JSONL format in memory_harvest\n\n## 28. maintenance · 失败模式：migration: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Se...\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: Developers should check this migration risk before relying on the project: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- User impact: Developers may hit a documented source-backed failure mode: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n- Suggested check: Before packaging this project, run the relevant install/config/quickstart check for: fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix. Context: Observed when using python, docker\n- Guardrail action: State this as source-backed community evidence, not as Doramagic reproduction.\n- Evidence: failure_mode_cluster:github_issue | fmev_474dd77beac7531143e2c9c8c014d21e | https://github.com/doobidoo/mcp-memory-service/issues/938 | fix(milvus): test_semantic_dedup_blocks_near_duplicate still fails after consistency_level=Session fix\n\n## 29. maintenance · 来源证据：v10.55.1 — Entity Link Storage Fix\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v10.55.1 — Entity Link Storage Fix\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0d033317867f482985c4e395b8825cfe | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.55.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 30. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | last_activity_observed missing\n\n## 31. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 32. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | no_demo; severity=medium\n\n## 33. security_permissions · 来源证据：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Project-affinity hard filter zeroes all scores when project name is a superset of memory tags (asymmetric `.includes()`)\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_aa1db2bf08304d3db87350b8cbc8e6ca | https://github.com/doobidoo/mcp-memory-service/issues/941 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 34. security_permissions · 来源证据：[automated] Contributor activity digest\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[automated] Contributor activity digest\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_0676e682588642899da4243174241e7b | https://github.com/doobidoo/mcp-memory-service/issues/937 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 35. security_permissions · 来源证据：feat: cascading search fallback when semantic results are sparse\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat: cascading search fallback when semantic results are sparse\n- User impact: 可能影响授权、密钥配置或安全边界。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_274fcdb5c1ed4290ac86171131d9db90 | https://github.com/doobidoo/mcp-memory-service/issues/873 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 36. security_permissions · 来源证据：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.52.0 — Cascading Search Fallback + Embedding Hydration on Bulk Reads\n- User impact: 可能阻塞安装或首次运行。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_60ded0d65a2c417e9ce3c9ed7501cbad | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.52.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 37. security_permissions · 来源证据：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v10.53.0 — Milvus Consolidation Embedding Hydration + GitPython Security\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_42c0d95dd5b247d79790b6f92024a048 | https://github.com/doobidoo/mcp-memory-service/releases/tag/v10.53.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 38. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | issue_or_pr_quality=unknown\n\n## 39. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:908539519 | https://github.com/doobidoo/mcp-memory-service | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-memory-service - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for doobidoo/mcp-memory-service.\n\nProject:\n- Name: mcp-memory-service\n- Repository: https://github.com/doobidoo/mcp-memory-service\n- Summary: Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Open-source persistent memory for AI agent pipelines (LangGraph, CrewAI, AutoGen) and Claude. REST API + knowledge graph + autonomous consolidation.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Overview and Key Concepts. Produce one small intermediate artifact and wait for confirmation.\n2. quickstart: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. storage-backends: Storage Backends. Produce one small intermediate artifact and wait for confirmation.\n5. rest-api: REST API Reference. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\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- src/mcp_memory_service/mcp_server.py\n- docs/setup-guide.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: doobidoo/mcp-memory-service\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install mcp-memory-service\n```\n\nSource：https://github.com/doobidoo/mcp-memory-service#readme\n\n## Sources\n\n- repo: https://github.com/doobidoo/mcp-memory-service\n- docs: https://github.com/doobidoo/mcp-memory-service#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_7899c8707642490e861a62147ece645b"
}