{
"canonical_name": "danielsimonjr/memory-mcp",
"compilation_id": "pack_56dc958686d14e2694f00b9b889756eb",
"created_at": "2026-05-16T09:23:06.294647+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 `npm install -g @danielsimonjr/memory-mcp` 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": "npm install -g @danielsimonjr/memory-mcp",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_b66f6c24f51c4be6aa1ee68feec7a242"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_a7ea2dadbf21fea1d8967a96b0942d26",
"canonical_name": "danielsimonjr/memory-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/danielsimonjr/memory-mcp",
"slug": "memory-mcp",
"source_packet_id": "phit_7dcd0b8a90bc424597533084105fbaae",
"source_validation_id": "dval_34874bd3c6f3464c8fd118ee38eb5781"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 1,
"github_stars": 2,
"one_liner_en": "Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities",
"one_liner_zh": "Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "memory-mcp",
"title_zh": "memory-mcp 能力包",
"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": "Code Review",
"label_zh": "代码审查",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-code-review",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_7dcd0b8a90bc424597533084105fbaae",
"page_model": {
"artifacts": {
"artifact_slug": "memory-mcp",
"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": "npm install -g @danielsimonjr/memory-mcp",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/danielsimonjr/memory-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"代码审查",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 936,
"forks": 1,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 2
},
"source_url": "https://github.com/danielsimonjr/memory-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities",
"title": "memory-mcp 能力包",
"trial_prompt": "# memory-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 memory-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-entities-relations：实体与关系模型。围绕“实体与关系模型”模拟一次用户任务，不展示安装或运行结果。\n5. page-storage-backends：存储后端。围绕“存储后端”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-entities-relations\n输入：用户提供的“实体与关系模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-storage-backends\n输入：用户提供的“存储后端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-entities-relations：Step 4 必须围绕“实体与关系模型”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-storage-backends：Step 5 必须围绕“存储后端”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/danielsimonjr/memory-mcp\n- https://github.com/danielsimonjr/memory-mcp#readme\n- README.md\n- package.json\n- docs/guides/MIGRATION.md\n- src/index.ts\n- src/server/MCPServer.ts\n- src/server/toolDefinitions.ts\n- src/server/toolHandlers.ts\n- docs/architecture/ARCHITECTURE.md\n- docs/architecture/COMPONENTS.md\n- docs/architecture/API.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 memory-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：reddit。reddit: MCP server that indexes codebases into a knowledge graph - Reddit（https://www.reddit.com/r/LocalLLaMA/comments/1rjt4hh/mcp_server_that_indexes_codebases_into_a/）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "searxng_indexed",
"source": "reddit",
"title": "MCP server that indexes codebases into a knowledge graph - Reddit",
"url": "https://www.reddit.com/r/LocalLLaMA/comments/1rjt4hh/mcp_server_that_indexes_codebases_into_a/"
}
],
"status": "已收录 1 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities",
"effort": "安装已验证",
"forks": 1,
"icon": "link",
"name": "memory-mcp 能力包",
"risk": "需复核",
"slug": "memory-mcp",
"stars": 2,
"tags": [
"MCP 工具",
"知识库问答",
"代码审查",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/danielsimonjr/memory-mcp 项目说明书\n\n生成时间：2026-05-16 08:51:38 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-architecture)\n- [数据流处理](#page-data-flow)\n- [实体与关系模型](#page-entities-relations)\n- [存储后端](#page-storage-backends)\n- [层级嵌套](#page-hierarchical-nesting)\n- [搜索能力](#page-search-capabilities)\n- [高级功能](#page-advanced-features)\n- [工具参考手册](#page-tool-reference)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/danielsimonjr/memory-mcp/blob/main/package.json)\n- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n \n\n# 项目介绍\n\n## 概述\n\nMemory MCP 是一个基于 **Model Context Protocol (MCP)** 的增强型记忆管理服务器，通过 MCP 协议为 AI 代理提供持久化记忆能力。该项目作为 MCP 服务器运行，封装了 `@danielsimonjr/memoryjs` 核心库的所有功能，向 AI 代理暴露 213 个工具函数，覆盖 58 个功能类别。资料来源：[README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)\n\n### 核心定位\n\nMemory MCP 的设计目标是为 AI 代理提供类似于人类记忆的长期记忆存储与检索能力。通过知识图谱结构，代理可以：\n\n- **持久化存储** - 将重要信息写入长期记忆\n- **智能检索** - 根据语义、关键词、时间等多种维度检索记忆\n- **层级管理** - 支持父子关系的层级记忆结构\n- **衰减机制** - 自动对低价值记忆进行时间衰减\n- **协同推理** - 支持多代理协作式的记忆综合分析\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n## 技术架构\n\n### 分层架构设计\n\nMemory MCP 采用清晰的分层架构，核心层由 `memoryjs` 库提供，MCP 层负责协议适配与工具暴露。\n\n```mermaid\ngraph TD\n subgraph \"Memory MCP (本项目)\"\n A[src/index.ts] --> B[MCPServer]\n B --> C[toolDefinitions.ts]\n B --> D[toolHandlers.ts]\n C --> D\n end\n \n subgraph \"@danielsimonjr/memoryjs\"\n E[ManagerContext] --> F[EntityManager]\n E --> G[RelationManager]\n E --> H[ObservationManager]\n E --> I[SearchManager]\n E --> J[TagManager]\n E --> K[HierarchyManager]\n E --> L[CompressionManager]\n E --> M[AnalyticsManager]\n E --> N[GraphStorage]\n end\n \n D --> E\n```\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n### ManagerContext 核心组件\n\n`ManagerContext` 是 memoryjs 库的核心类，采用懒加载模式初始化所有管理器实例。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 管理器组件 | 访问方式 | 功能说明 |\n|-----------|---------|---------|\n| EntityManager | `ctx.entityManager` | 图节点（实体）的增删改查 |\n| RelationManager | `ctx.relationManager` | 有向边管理，连接实体间关系 |\n| ObservationManager | `ctx.observationManager` | 附加到实体的观察事实，支持归一化 |\n| SearchManager | `ctx.searchManager` | 基础搜索、布尔搜索、模糊搜索 |\n| TagManager | `ctx.tagManager` | 标签管理与重要性评分 |\n| HierarchyManager | `ctx.hierarchyManager` | 父子树结构与子树遍历 |\n| AnalyticsManager | `ctx.analyticsManager` | 图统计与完整性验证 |\n| CompressionManager | `ctx.compressionManager` | 去重、合并、自动压缩、归档 |\n| ArchiveManager | `ctx.archiveManager` | 记忆归档管理 |\n| IOManager | `ctx.ioManager` | 数据导入导出 |\n| SemanticSearch | `ctx.semanticSearch` | OpenAI 或本地模型的语义搜索 |\n| RankedSearch | `ctx.rankedSearch` | TF-IDF 排序搜索 |\n\n### 向后兼容性\n\n`src/index.ts` 将 `ManagerContext` 重新导出为 `KnowledgeGraphManager` 别名，同时导出核心类型定义，确保与旧版 API 的兼容性。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n## 工具体系\n\n### 工具分类总览\n\nMemory MCP 提供 213 个工具函数，覆盖 58 个功能类别。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 类别 | 工具数量 | 核心功能 |\n|------|---------|---------|\n| Entity | 4 | 图节点的创建、读取、更新、删除 |\n| Relation | 2 | 实体间的有向边管理 |\n| Observation | 3 | 附加事实的增删改查，支持归一化 |\n| Search | 7 | 基础搜索、排序搜索、布尔搜索、模糊搜索、自动选择 |\n| Intelligent Search | 3 | 混合多层搜索、查询分析、基于反思的搜索 |\n| Semantic Search | 3 | 通过 OpenAI 或本地模型的嵌入相似度搜索 |\n| Saved Searches | 5 | 存储和重新执行常用查询 |\n| Tag Management | 6 | 标签管理、批量操作、重要性评分 |\n| Tag Aliases | 5 | 标签同义词/别名管理 |\n| Hierarchy | 9 | 父子树结构、子树遍历 |\n| Graph Algorithms | 4 | BFS/DFS 路径查找、中心性、连通分量 |\n| Analytics | 2 | 图统计和完整性验证 |\n| Compression | 4 | 去重检测、合并、自动压缩、归档 |\n| Import/Export | 2 | 7 种导出格式 |\n\n### 工具处理流程\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP 客户端\n participant Server as MCPServer\n participant Handler as toolHandlers.ts\n participant Manager as ManagerContext\n \n MCP->>Server: 工具调用请求\n Server->>Handler: 路由到对应 handler\n Handler->>Manager: 调用 ManagerContext 方法\n Manager->>Manager: 执行业务逻辑\n Manager-->>Handler: 返回结果\n Handler-->>Server: 格式化响应\n Server-->>MCP: MCP 格式响应\n```\n\n资料来源：[src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n\n## 存储方案\n\n### 存储类型\n\nMemory MCP 支持两种存储后端，数据文件位于**项目根目录**（非 `dist/` 目录）。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 存储类型 | 文件 | 环境变量 |\n|---------|------|---------|\n| JSONL (默认) | `memory.jsonl`, `memory-saved-searches.jsonl`, `memory-tag-aliases.jsonl` | - |\n| SQLite | `memory.db` | `MEMORY_STORAGE_TYPE=sqlite` |\n\n### 数据迁移工具\n\n`tools/migrate-from-jsonl-to-sqlite` 目录提供了独立的迁移工具，支持 JSONL 与 SQLite 格式之间的双向转换。资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)\n\n```bash\n# 基本用法\nmigrate-from-jsonl-to-sqlite --from --to \n\n# 显示详细进度\nmigrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db --verbose\n```\n\n## 依赖管理\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| @modelcontextprotocol/sdk | ^1.0.0 | MCP 协议实现 |\n| @danielsimonjr/memoryjs | ^2.1.0 | 核心记忆管理库 |\n| zod | ^3.23.8 | Schema 验证 |\n| better-sqlite3 | ^11.7.0 | SQLite 存储后端 |\n\n### 开发依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| typescript | ^5.7.0 | TypeScript 编译 |\n| @types/node | ^22.0.0 | Node.js 类型定义 |\n| vitest | ^2.0.0 | 单元测试框架 |\n\n## 版本演进\n\n### 版本历史要点\n\n| 阶段 | 版本 | 主要内容 |\n|------|------|---------|\n| Phase 13 | 初始版本 | 仅保留 5 个 TypeScript 源文件，核心逻辑移至 memoryjs |\n| Phase 15 | v12.2.0 | 新增 23 个工具，暴露 memoryjs v1.14+ 功能 |\n| Phase 16 | v12.3.0 | 新增 53 个工具，暴露 memoryjs v2.1.0 功能 |\n\nPhase 16 (v12.3.0) 新增的功能包括：排除规则 (5)、决策理由与 ADR markdown 双写 (10)、结构化项目上下文 (12)、启发式指南 (10)、工具能力与观察管道 (11)、观察去重 (2)、拼写纠正 (3)。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n## 安装与使用\n\n### npm 包信息\n\n```bash\n# 安装\nnpm install @danielsimonjr/memory-mcp\n\n# 或使用最新版本\nnpm install @danielsimonjr/memory-mcp@latest\n```\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n### 构建与发布\n\n项目使用 `prepare` 脚本在安装时自动构建，因此发布前无需单独执行构建命令。资料来源：[CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n\n```bash\n# 发布到 npm\n# 需要具有绕过 2FA 权限的 token\nnpm config set //registry.npmjs.org/:_authToken=$(cat ~/.npm_token)\nnpm publish --access public\n\n# 发布前验证 tarball 内容\nnpm pack --dry-run\n```\n\n## 独立工具集\n\n`tools/` 目录包含可独立运行的工具，每个工具拥有自己的 `package.json`，可通过 `pkg` 编译为 Windows 可执行文件。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 工具目录 | 用途 |\n|---------|------|\n| `chunking-for-files` | 将大文件拆分为小块以适应上下文限制 |\n| `compress-for-context` | CTON 压缩以适应 LLM 上下文窗口 |\n| `create-dependency-graph` | 生成 TypeScript 项目依赖图 |\n| `migrate-from-jsonl-to-sqlite` | JSONL 与 SQLite 格式转换 |\n\n## 开发指南\n\n### 代码规范\n\n- 遵循 TypeScript 最佳实践\n- 使用有意义的变量命名\n- 为公共方法添加 JSDoc 注释\n- 保持函数专注于小而简洁\n- 统一使用 2 空格缩进\n\n### 测试要求\n\n- 全面测试新功能\n- 包含边界情况测试\n- 测试向后兼容性\n- 验证导出格式有效性\n- 测试空图和大图场景\n\n### 提交流程\n\n1. **创建功能分支**: `git checkout -b feature/your-feature-name`\n2. **提交更改**: `git add . && git commit -m \"Description\"`\n3. **推送并创建 PR**: `git push origin feature/your-feature-name`\n4. PR 应包含：标题、描述、测试结果、文档更新、向后兼容性确认\n\n资料来源：[CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n\n## 配置选项\n\n### 环境变量\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|-------|\n| `MEMORY_STORAGE_TYPE` | 存储类型选择 | `jsonl` |\n| `MEMORY_DB_PATH` | SQLite 数据库路径 | `memory.db` |\n\n### TypeScript 配置\n\n- 编译目标: ES2022\n- 模块解析: Node16\n\n## 相关资源\n\n- **npm 包**: [@danielsimonjr/memory-mcp](https://www.npmjs.com/package/@danielsimonjr/memory-mcp)\n- **核心库**: [@danielsimonjr/memoryjs](https://www.npmjs.com/package/@danielsimonjr/memoryjs)\n- **MCP 协议**: [Model Context Protocol](https://modelcontextprotocol.io/)\n- **社区指南**: [MCP Community Guidelines](https://modelcontextprotocol.io/community/communication)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)\n- [src/server/MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts)\n \n\n# 快速开始\n\n本文档帮助你在 5 分钟内完成 memory-mcp 的安装、配置和首次使用。\n\n## 项目概述\n\nmemory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱记忆管理服务器。它为 AI 助手提供持久化记忆存储、语义搜索和层次化组织能力。\n\n**核心依赖：**\n- **npm 包**：`@danielsimonjr/memory-mcp`\n- **核心库**：`@danielsimonjr/memoryjs`\n- **协议层**：Model Context Protocol\n- **存储后端**：JSONL 文件或 SQLite 数据库\n\n资料来源：[README.md:1-15]()\n\n## 系统架构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ memory-mcp (本仓库) │\n├─────────────────────────────────────────────────────────────┤\n│ src/index.ts │ 入口文件，导出公共 API │\n│ src/server/MCPServer │ MCP 服务器实现 │\n│ src/server/toolDefs │ 工具定义 (213 个工具，58 个类别) │\n│ src/server/toolHandlers│ 工具处理逻辑 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ @danielsimonjr/memoryjs (npm 依赖) │\n├─────────────────────────────────────────────────────────────┤\n│ ManagerContext │ 懒加载管理器上下文 │\n│ EntityManager │ 实体/节点管理 │\n│ RelationManager │ 关系/边管理 │\n│ SearchManager │ 搜索管理 │\n│ IOManager │ 导入/导出管理 │\n│ GraphStorage/SQLiteStorage │ 图存储/SQLite 存储后端 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[CLAUDE.md:1-30]()\n\n## 前置要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 18.0.0 | 推荐使用 LTS 版本 |\n| npm | 9.0.0 | 用于安装依赖 |\n| 操作系统 | Windows/macOS/Linux | 跨平台支持 |\n| 磁盘空间 | 50MB | 基础安装占用 |\n\n## 安装步骤\n\n### 1. 全局安装\n\n```bash\nnpm install -g @danielsimonjr/memory-mcp\n```\n\n### 2. 验证安装\n\n安装完成后，系统会创建以下组件：\n\n| 组件 | 位置 | 说明 |\n|------|------|------|\n| 构建产物 | `dist/index.js` | 编译后的入口文件 |\n| CLI 二进制文件 | `mcp-server-memory` | 命令行工具 |\n| 源码入口 | `src/index.ts` | TypeScript 源码 |\n\n安装过程中 `prepare` 脚本会自动运行 `npm run build` 进行构建。 资料来源：[CLAUDE.md:40-45]()\n\n## 存储配置\n\nmemory-mcp 支持两种存储后端，在项目根目录创建配置文件即可：\n\n### JSONL 存储（默认）\n\n默认使用 JSONL 格式存储，数据文件位于**项目根目录**（不是 `dist/`）：\n\n```\n├── memory.jsonl # 主记忆数据\n├── memory-saved-searches.jsonl # 保存的搜索\n├── memory-tag-aliases.jsonl # 标签别名\n└── memory.db # (可选) SQLite 数据库\n```\n\n### SQLite 存储\n\n设置环境变量切换到 SQLite 存储：\n\n```bash\nexport MEMORY_STORAGE_TYPE=sqlite\n```\n\n使用 SQLite 时，所有数据存储在 `memory.db` 文件中。 资料来源：[CLAUDE.md:30-35]()\n\n## 工具类别总览\n\nmemory-mcp 提供 **213 个工具**，分为 **58 个类别**：\n\n| 类别 | 工具数量 | 核心功能 |\n|------|----------|----------|\n| 实体 (Entity) | 4 | 图节点的基础增删改查 |\n| 关系 (Relation) | 2 | 实体间的有向边管理 |\n| 观察 (Observation) | 3 | 附加到实体的属性和事实 |\n| 搜索 (Search) | 7 | 基础、布尔、模糊搜索 |\n| 智能搜索 (Intelligent Search) | 3 | 混合多层、查询分析 |\n| 语义搜索 (Semantic Search) | 3 | OpenAI 或本地模型嵌入 |\n| 标签管理 (Tag Management) | 6 | 标签及重要性评分 |\n| 层级管理 (Hierarchy) | 9 | 父子树和子树遍历 |\n| 图算法 (Graph Algorithms) | 4 | BFS/DFS、中心性计算 |\n| 分析 (Analytics) | 2 | 图统计和完整性验证 |\n| 压缩 (Compression) | 4 | 去重、合并、自动压缩 |\n| 导入/导出 (Import/Export) | 2 | 7 种导出格式 |\n\n资料来源：[CLAUDE.md:15-25]()\n\n## 首次使用\n\n### 1. 启动服务器\n\n在支持 MCP 的客户端（如 Claude Desktop）中配置服务器连接。服务器通过 Model Context Protocol 暴露所有工具。\n\n### 2. 创建第一个实体\n\n使用 `create_entity` 工具创建记忆节点：\n\n```\n工具：create_entity\n参数：\n - name: \"我的第一个记忆\"\n - entityType: \"memory\"\n```\n\n### 3. 添加观察数据\n\n使用 `create_observation` 为实体添加属性：\n\n```\n工具：create_observation\n参数：\n - entityName: \"我的第一个记忆\"\n - content: \"这是一个测试记忆\"\n - importance: 0.8\n```\n\n### 4. 执行搜索\n\n使用 `search` 或 `semantic_search` 查找记忆：\n\n```\n工具：search\n参数：\n - query: \"测试\"\n - limit: 10\n```\n\n## 数据流图\n\n```mermaid\ngraph TD\n A[用户请求] --> B[MCP 客户端]\n B --> C[MCPServer]\n C --> D[ToolHandlers]\n D --> E[memoryjs ManagerContext]\n E --> F{存储类型判断}\n F -->|JSONL| G[GraphStorage]\n F -->|SQLite| H[SQLiteStorage]\n G --> I[memory.jsonl]\n H --> J[memory.db]\n J --> K[结果返回]\n I --> K\n K --> C\n C --> B\n B --> L[用户响应]\n```\n\n## 常见操作示例\n\n### 层级组织\n\n创建实体间的父子关系：\n\n```\n工具：set_entity_parent\n参数：\n - entityName: \"项目A\"\n - parentName: \"工作\"\n```\n\n### 标签管理\n\n为实体添加标签：\n\n```\n工具：add_tag\n参数：\n - entityName: \"项目A\"\n - tag: \"重要\"\n - importance: 0.9\n```\n\n### 导入导出\n\n导出记忆为指定格式：\n\n```\n工具：export_graph\n参数：\n - format: \"json\"\n - includeObservations: true\n```\n\n## 开发指南\n\n如果你想为 memory-mcp 做贡献：\n\n```bash\n# 克隆仓库\ncd c:/mcp-servers/memory-mcp\n\n# 创建功能分支\ngit checkout -b feature/your-feature-name\n\n# 安装依赖\nnpm install\n\n# 编写代码，遵循以下规范：\n# - TypeScript 最佳实践\n# - 使用有意义的变量名\n# - 为公共方法添加 JSDoc 注释\n# - 保持函数小而专注\n# - 使用 2 空格缩进\n\n# 运行类型检查\nnpm run typecheck\n\n# 提交更改\ngit add .\ngit commit -m \"Description of your changes\"\n\n# 推送并创建 PR\ngit push origin feature/your-feature-name\n```\n\n资料来源：[CONTRIBUTING.md:1-25]()\n\n## 独立工具\n\n`tools/` 目录包含独立工具，每个都有独立的 `package.json`：\n\n| 工具 | 用途 |\n|------|------|\n| `chunking-for-files` | 拆分/合并大文件以适应上下文限制 |\n| `compress-for-context` | CTON 压缩以适应 LLM 上下文窗口 |\n| `create-dependency-graph` | 生成 TypeScript 项目依赖图 |\n| `migrate-from-jsonl-to-sqlite` | 在 JSONL 和 SQLite 格式间转换 |\n\n资料来源：[CLAUDE.md:50-55]()\n\n## 下一步\n\n- 阅读 [架构文档](./ARCHITECTURE.md) 深入了解系统设计\n- 查看 [工具参考](./TOOLS.md) 完整工具列表\n- 参考 [迁移指南](./MIGRATION.md) 从旧版本升级\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [数据流处理](#page-data-flow), [实体与关系模型](#page-entities-relations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)\n- [src/server/MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts)\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)\n \n\n# 系统架构\n\n## 概述\n\nmemory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱管理服务器，为 AI 代理提供持久化记忆能力。该项目采用分层架构设计，核心逻辑委托给 `@danielsimonjr/memoryjs` 库处理，而本仓库专注于 MCP 协议适配层、工具定义和请求处理。\n\n**核心职责：**\n\n- 将 memoryjs 的知识图谱能力暴露为 MCP 工具（当前版本共 213 个工具，覆盖 58 个类别）\n- 处理 MCP 协议的请求/响应生命周期\n- 提供多格式存储支持（JSONL 和 SQLite）\n- 支持语义搜索、嵌入向量、权限控制等高级功能\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 架构分层\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端层\"\n CLIENT[AI 代理 / Claude Desktop]\n end\n \n subgraph \"memory-mcp 服务层\"\n INDEX[src/index.ts
入口点]\n SERVER[MCPServer.ts
服务器核心]\n TOOL_DEFS[toolDefinitions.ts
工具定义]\n HANDLERS[toolHandlers.ts
工具处理器]\n end\n \n subgraph \"memoryjs 核心库\"\n CTX[ManagerContext
管理器上下文]\n EM[EntityManager]\n RM[RelationManager]\n SM[SearchManager]\n IOM[IOManager]\n STORAGE[(GraphStorage
存储层)]\n end\n \n subgraph \"存储层\"\n JSONL[(memory.jsonl)]\n SQLITE[(memory.db)]\n end\n \n CLIENT <--> INDEX\n INDEX --> SERVER\n SERVER --> TOOL_DEFS\n SERVER --> HANDLERS\n HANDLERS <--> CTX\n CTX --> EM\n CTX --> RM\n CTX --> SM\n CTX --> IOM\n CTX --> STORAGE\n STORAGE --> JSONL\n STORAGE --> SQLITE\n```\n\n### 层级说明\n\n| 层级 | 组件 | 职责 | 资料来源 |\n|------|------|------|----------|\n| **协议层** | MCP 客户端 | 与 AI 代理通信，发送 JSON-RPC 请求 | — |\n| **适配层** | `MCPServer.ts` | 初始化服务器、注册工具、处理 MCP 生命周期 | [MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts) |\n| **定义层** | `toolDefinitions.ts` | 定义每个工具的输入模式（Zod schema） | [toolDefinitions.ts:1-50](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts) |\n| **处理层** | `toolHandlers.ts` | 实现工具业务逻辑，调用 memoryjs | [toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts) |\n| **核心层** | `memoryjs` | 管理器上下文、图谱操作、搜索算法 | [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) |\n| **存储层** | GraphStorage | 多格式数据持久化 | — |\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 核心组件详解\n\n### 1. 入口点 (src/index.ts)\n\n`src/index.ts` 是整个应用的入口文件，负责导出核心类型和初始化逻辑。\n\n**主要导出：**\n\n```typescript\n// ManagerContext 作为 KnowledgeGraphManager 别名导出\nexport { ManagerContext as KnowledgeGraphManager } from '@danielsimonjr/memoryjs';\n\n// 核心类型重导出\nexport type { Entity, Relation, Observation, SearchResult } from '@danielsimonjr/memoryjs';\n```\n\n该模块采用延迟初始化模式，仅在需要时才创建 ManagerContext 实例，以优化冷启动性能。\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n### 2. 服务器核心 (MCPServer.ts)\n\n`MCPServer.ts` 是 MCP 服务器的核心实现，负责：\n\n- 初始化 MCP 服务器实例\n- 注册所有工具定义\n- 绑定工具处理器到对应工具\n- 处理请求生命周期\n\n**架构特点：**\n\n```mermaid\nsequenceDiagram\n participant CLIENT as MCP 客户端\n participant SERVER as MCPServer\n participant HANDLER as ToolHandler\n participant MEMORYJS as memoryjs\n\n CLIENT->>SERVER: JSON-RPC 请求\n SERVER->>SERVER: 解析工具名称和参数\n SERVER->>HANDLER: 调用对应处理器\n HANDLER->>MEMORYJS: 调用 ManagerContext 方法\n MEMORYJS-->>HANDLER: 返回结果\n HANDLER-->>SERVER: 格式化响应\n SERVER-->>CLIENT: JSON-RPC 响应\n```\n\n### 3. 工具定义 (toolDefinitions.ts)\n\n`toolDefinitions.ts` 使用 JSON Schema 风格的定义来描述每个 MCP 工具的接口。\n\n**工具类别统计：**\n\n| 类别 | 工具数量 | 主要功能 |\n|------|----------|----------|\n| Entity | 4 | 图谱节点 CRUD |\n| Relation | 2 | 有向边管理 |\n| Observation | 3 | 实体事实附加 |\n| Search | 7 | 基础/排名/模糊搜索 |\n| Intelligent Search | 3 | 混合多层搜索 |\n| Semantic Search | 3 | 嵌入向量相似度 |\n| Saved Searches | 5 | 搜索存储与重执行 |\n| Tag Management | 6 | 标签和重要性评分 |\n| Hierarchy | 9 | 父子树遍历 |\n| Graph Algorithms | 4 | BFS/DFS/中心性 |\n| Analytics | 2 | 图谱统计 |\n| Compression | 4 | 去重和压缩 |\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n**工具定义结构示例：**\n\n```typescript\n{\n name: 'compress_for_context',\n description: '使用 CTON 格式压缩文本以适应 LLM 上下文窗口',\n inputSchema: {\n type: 'object',\n properties: {\n text: { type: 'string', description: '要压缩的文本' },\n level: { \n type: 'string', \n enum: ['light', 'medium', 'aggressive'],\n description: '压缩级别'\n },\n },\n required: ['text'],\n },\n}\n```\n\n资料来源：[toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n\n### 4. 工具处理器 (toolHandlers.ts)\n\n`toolHandlers.ts` 是工具的业务逻辑实现层，采用注册表模式管理所有处理函数。\n\n**处理器模式：**\n\n```typescript\n// 典型处理器结构\n工具名称: async (ctx, args) => {\n // 1. 参数验证（使用 Zod schema）\n const validatedArg = validateWithSchema(args.param, z.string(), '错误信息');\n \n // 2. 调用 memoryjs 管理器方法\n const result = await getManager(ctx).someMethod(validatedArg);\n \n // 3. 格式化响应\n return formatToolResponse(result);\n}\n```\n\n**关键处理器示例：**\n\n| 处理器 | 功能 | 调用管理器 |\n|--------|------|----------|\n| `create_artifact` | 创建工具输出工件 | `getArtifactManager()` |\n| `get_artifact` | 获取工件引用 | `getArtifactManager()` |\n| `set_governance_policy` | 设置权限策略 | `getGovernance()` |\n| `audit_query` | 查询审计日志 | `getAuditLog()` |\n| `run_decay_cycle` | 运行重要性衰减 | 核心引擎 |\n\n资料来源：[toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n\n---\n\n## ManagerContext 管理器上下文\n\n`ManagerContext` 是与 memoryjs 核心库交互的主要接口，提供对各功能管理器的访问。\n\n### 可用管理器\n\n```mermaid\ngraph LR\n CTX[ManagerContext] --> EM[EntityManager]\n CTX --> RM[RelationManager]\n CTX --> OM[ObservationManager]\n CTX --> SM[SearchManager]\n CTX --> TM[TagManager]\n CTX --> HM[HierarchyManager]\n CTX --> AM[AnalyticsManager]\n CTX --> CM[CompressionManager]\n CTX --> IOM[IOManager]\n CTX --> GT[GraphTraversal]\n CTX --> SS[SemanticSearch]\n CTX --> RS[RankedSearch]\n CTX --> ST[(Storage)]\n```\n\n### 管理器功能表\n\n| 管理器 | 方法 | 功能描述 |\n|--------|------|----------|\n| **EntityManager** | `create`, `get`, `update`, `delete`, `merge` | 图谱节点操作 |\n| **RelationManager** | `create`, `get`, `delete` | 有向边管理 |\n| **ObservationManager** | `add`, `get`, `normalize` | 实体事实附加 |\n| **SearchManager** | `basic`, `ranked`, `boolean`, `fuzzy` | 多种搜索模式 |\n| **SemanticSearch** | `similarity`, `hybrid` | 嵌入向量搜索 |\n| **TagManager** | `add`, `remove`, `bulk`, `score` | 标签管理 |\n| **HierarchyManager** | `parent`, `children`, `subtree` | 层级结构遍历 |\n| **AuditLog** | `query`, `record` | 操作审计 |\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 存储架构\n\n### 存储类型\n\nmemory-mcp 支持两种存储后端，通过环境变量 `MEMORY_STORAGE_TYPE` 切换：\n\n| 存储类型 | 文件 | 配置值 | 适用场景 |\n|----------|------|--------|----------|\n| **JSONL** | `memory.jsonl` | `jsonl` | 小规模数据、开发环境 |\n| **SQLite** | `memory.db` | `sqlite` | 生产环境、大规模数据 |\n\n### 数据文件位置\n\n数据文件位于**项目根目录**（而非 `dist/` 构建目录）：\n\n```\nproject-root/\n├── memory.jsonl # JSONL 存储\n├── memory-saved-searches.jsonl # 保存的搜索\n├── memory-tag-aliases.jsonl # 标签别名\n├── memory.db # SQLite 数据库\n├── dist/ # 构建输出\n│ └── index.js\n└── src/ # 源代码\n └── index.ts\n```\n\n### 存储层抽象\n\n```mermaid\ngraph TB\n subgraph \"应用层\"\n HANDLERS[工具处理器]\n end\n \n subgraph \"存储抽象层\"\n GS[GraphStorage]\n end\n \n subgraph \"后端实现\"\n JSONL[JSONLStorage]\n SQLITE[SQLiteStorage]\n end\n \n HANDLERS --> GS\n GS --> JSONL\n GS --> SQLITE\n```\n\n---\n\n## 工具处理流程\n\n### 完整请求生命周期\n\n```mermaid\nsequenceDiagram\n participant CLI as MCP 客户端\n participant SERVER as MCPServer\n participant DEF as ToolDefinitions\n participant HANDLER as ToolHandler\n participant CTX as ManagerContext\n participant DB as 存储层\n\n CLI->>SERVER: list_tools 请求\n SERVER->>DEF: 获取所有工具定义\n DEF-->>SERVER: 返回工具 schema 数组\n SERVER-->>CLI: 工具列表\n\n CLI->>SERVER: call_tool 请求\n SERVER->>HANDLER: 分派到对应处理器\n HANDLER->>HANDLER: 参数验证\n HANDLER->>CTX: 调用管理器方法\n CTX->>DB: 持久化操作\n DB-->>CTX: 返回数据\n CTX-->>HANDLER: 业务结果\n HANDLER-->>SERVER: 格式化响应\n SERVER-->>CLI: JSON-RPC 响应\n```\n\n### 参数验证模式\n\n所有工具处理器统一使用 Zod 进行参数验证：\n\n```typescript\n// 标准验证模式\nconst validated = validateWithSchema(\n args.paramName, // 待验证值\n z.string().min(1), // Zod schema\n '错误提示信息' // 验证失败消息\n);\n\n// 枚举验证\nz.enum(['option1', 'option2', 'option3']);\n\n// 数字范围验证\nz.number().int().min(1).max(1000);\n```\n\n资料来源：[toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n\n---\n\n## 独立工具集\n\n除 MCP 服务器外，`tools/` 目录还包含独立的命令行工具：\n\n### 工具列表\n\n| 工具 | 文件 | 功能 |\n|------|------|------|\n| **chunking-for-files** | `chunking-for-files.ts` | 将大文件拆分为可编辑的区块 |\n| **compress-for-context** | `compress-for-context.ts` | CTON 格式压缩以适应 LLM 上下文 |\n| **create-dependency-graph** | `create-dependency-graph.ts` | 生成 TypeScript 项目依赖图 |\n| **migrate-from-jsonl-to-sqlite** | `migrate-from-jsonl-to-sqlite.ts` | JSONL 与 SQLite 格式互转 |\n\n### 独立工具架构\n\n```mermaid\ngraph LR\n subgraph \"tools/ 目录\"\n CHUNK[chunking-for-files]\n COMPRESS[compress-for-context]\n DEPS[create-dependency-graph]\n MIGRATE[migrate-from-jsonl-to-sqlite]\n end\n \n CHUNK --> FS[文件系统]\n COMPRESS --> FS\n DEPS --> TS[TypeScript AST]\n MIGRATE --> JSONL[JSONL 解析]\n MIGRATE --> SQL[SQLite]\n```\n\n资料来源：[tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)\n\n---\n\n## 环境配置\n\n### 配置变量表\n\n| 变量名 | 描述 | 默认值 | 资料来源 |\n|--------|------|--------|----------|\n| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl` | [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) |\n| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` | 同上 |\n| `MEMORY_EMBEDDING_PROVIDER` | 嵌入提供商 | `none` | 同上 |\n| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — | 同上 |\n| `MEMORY_EMBEDDING_MODEL` | 嵌入模型名 | `text-embedding-3-small` | 同上 |\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 创建时自动索引 | `false` | 同上 |\n\n---\n\n## 编译与发布\n\n### 构建输出\n\n| 输出物 | 路径 | 说明 |\n|--------|------|------|\n| **构建产物** | `dist/index.js` | TypeScript 编译输出 |\n| **CLI 二进制** | `mcp-server-memory` | package.json 中定义 |\n\n### 发布流程\n\n```bash\n# 1. 设置 npm token\nnpm config set //registry.npmjs.org/:_authToken=$(cat c:\\mcp-servers\\npm_key.txt)\n\n# 2. 发布（prepare 脚本会自动构建）\nnpm publish --access public\n\n# 3. 验证 tarball 内容\nnpm pack --dry-run 2>&1 | grep -E \"jsonl|\\.db|total files|package size\"\n```\n\n**注意：** 发布前必须更新 `package.json` 中的版本号，npm 不会重新发布相同版本。\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 版本演进\n\n| 版本 | 阶段 | 主要内容 |\n|------|------|----------|\n| **v12.3.0** (最新) | Phase 16 | 53 个新工具：排除规则、ADR 双写、结构化上下文、启发式指南、工具调用观察管道、拼写纠正 |\n| **v12.2.0** | Phase 15 | 23 个工具：双时间有效性、OCC、RBAC、程序记忆、主动检索、因果推理、世界模型 |\n| **v2.1.0** | — | memoryjs 核心库升级 |\n\n---\n\n## 扩展指南\n\n### 添加新工具流程\n\n```mermaid\ngraph LR\n A[定义 schema] --> B[添加处理器]\n B --> C[添加 e2e 测试]\n C --> D[更新文档]\n \n subgraph \"步骤 1\"\n A[toolDefinitions.ts]\n end\n \n subgraph \"步骤 2\"\n B[toolHandlers.ts]\n end\n \n subgraph \"步骤 3\"\n C[tests/e2e/tools/]\n end\n```\n\n1. **定义 Schema**：在 `toolDefinitions.ts` 相应类别区域添加 JSON Schema\n2. **实现处理器**：在 `toolHandlers.ts` 注册表中添加处理函数\n3. **编写测试**：在 `tests/e2e/tools/` 添加端到端测试\n\n### 处理器最佳实践\n\n- 使用 `validateWithSchema()` 进行参数验证\n- 大响应使用 `withCompression()` 包装\n- 返回 `formatToolResponse()` 或 `formatTextResponse()`\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 总结\n\nmemory-mcp 采用清晰的**分层架构**：\n\n1. **协议适配层**处理 MCP 通信\n2. **工具定义层**声明接口契约\n3. **处理层**实现业务逻辑\n4. **核心库层**执行图谱操作\n5. **存储层**管理数据持久化\n\n这种设计使得核心图谱逻辑与 MCP 协议解耦，便于独立演进和测试。通过 213 个精心设计的工具，AI 代理能够高效地存储、检索和管理持久化记忆。\n\n---\n\n\n\n## 数据流处理\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [存储后端](#page-storage-backends), [工具参考手册](#page-tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [src/server/responseCompressor.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/responseCompressor.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)\n \n\n# 数据流处理\n\n## 概述\n\n数据流处理是 memory-mcp 架构的核心机制，负责将 MCP（Model Context Protocol）工具调用转化为底层知识图谱操作，并确保大规模响应的有效传输。该系统采用分层架构，上层为 MCP 服务器，下层为核心库 `@danielsimonjr/memoryjs`，两者通过 `ManagerContext` 进行解耦通信。\n\n**核心职责：**\n- 接收并验证工具调用参数\n- 路由至对应的 Manager 处理器\n- 管理知识图谱实体的 CRUD 操作\n- 对超过 256KB 的大规模响应自动压缩\n- 支持多种存储后端（JSONL / SQLite）\n\n资料来源：[CLAUDE.md:1-5]()\n\n## 系统架构\n\n### 分层架构图\n\n```mermaid\ngraph TD\n subgraph \"memory-mcp (本仓库)\"\n A[\"src/index.ts
入口点\"] --> B[\"MCPServer.ts
MCP服务器\"]\n B --> C[\"toolHandlers.ts
工具处理器\"]\n C --> D[\"responseCompressor.ts
响应压缩器\"]\n end\n \n subgraph \"@danielsimonjr/memoryjs (npm依赖)\"\n E[\"ManagerContext
管理器上下文\"]\n E --> F[\"EntityManager
实体管理器\"]\n E --> G[\"RelationManager
关系管理器\"]\n E --> H[\"SearchManager
搜索管理器\"]\n E --> I[\"ObservationManager
观察管理器\"]\n E --> J[\"IOManager
IO管理器\"]\n end\n \n D --> E\n F --> K[\"GraphStorage
图存储\"]\n G --> K\n H --> K\n I --> K\n J --> K\n \n K --> L[\"JSONL / SQLite
存储后端\"]\n```\n\n资料来源：[CLAUDE.md:10-18]()\n\n### 组件职责表\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| 入口点 | `src/index.ts` | 初始化 MCP 服务器，导出 ManagerContext 别名 |\n| MCP 服务器 | `src/server/MCPServer.ts` | 处理协议握手、工具定义分发 |\n| 工具处理器 | `src/server/toolHandlers.ts` | 工具业务逻辑、参数验证、响应格式化 |\n| 响应压缩器 | `src/server/responseCompressor.ts` | 检测并压缩大规模响应 |\n| ManagerContext | memoryjs 内部 | 懒加载初始化所有管理器实例 |\n\n资料来源：[CLAUDE.md:22-25]()\n\n## 工具处理流程\n\n### 标准处理管道\n\n```mermaid\nsequenceDiagram\n participant Client as MCP客户端\n participant Server as MCPServer\n participant Handler as toolHandlers\n participant Compressor as withCompression\n participant Manager as ManagerContext\n participant Storage as GraphStorage\n\n Client->>Server: 工具调用请求\n Server->>Handler: 路由至对应handler\n \n Handler->>Handler: 参数验证 (zod schemas)\n Handler->>Handler: 数据预处理\n \n Handler->>Manager: 调用manager方法\n Manager->>Storage: 持久化/查询\n \n Storage-->>Manager: 返回结果\n Manager-->>Handler: 格式化响应\n \n Handler->>Compressor: 包装响应\n Compressor->>Compressor: 检查大小 >256KB?\n \n alt 响应过大\n Compressor->>Compressor: CTON压缩\n Compressor-->>Server: 压缩后的JSON\n else 响应正常\n Compressor-->>Server: 原始响应\n end\n \n Server-->>Client: ToolResponse\n```\n\n### 工具处理器模式\n\n所有工具处理器遵循统一模式：`参数验证 → 调用管理器 → 格式化响应` 资料来源：[CLAUDE.md:33-34]()\n\n```typescript\n// 标准处理器示例 - create_artifact\ncreate_artifact: async (ctx, args) => {\n // 1. 参数验证\n const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');\n const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');\n const artifactType = validateWithSchema(\n args.artifactType,\n z.enum(['tool_output', 'code_snippet', 'api_response', 'search_result', 'file_content', 'user_input']),\n 'Invalid artifactType'\n );\n \n // 2. 调用管理器\n const artifact = await getArtifactManager(ctx).createArtifact({\n content,\n toolName,\n artifactType,\n description: args.description,\n sessionId: args.sessionId,\n });\n \n // 3. 格式化响应\n return formatToolResponse(artifact);\n},\n```\n\n资料来源：[src/server/toolHandlers.ts:1-25]()\n\n### 参数验证机制\n\n系统使用 `zod` 进行参数模式验证，支持类型约束和错误消息自定义：\n\n```typescript\nfunction validateWithSchema(\n value: unknown,\n schema: z.ZodType,\n errorMessage: string\n): T\n```\n\n验证失败时抛出错误，中断处理流程。 资料来源：[src/server/toolHandlers.ts:3-5]()\n\n### 过滤参数验证\n\n对于可选的过滤参数，采用宽松验证策略——单个无效字段不会导致整个请求失败，而是使用管理器默认值：\n\n```typescript\nfunction parseObservationDedupFilter(args: Record): {\n entityType?: string | string[];\n projectId?: string;\n sessionId?: string;\n minOccurrences?: number;\n maxGroups?: number;\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:85-93]()\n\n## 响应压缩机制\n\n### 压缩触发条件\n\n| 条件 | 阈值 | 处理方式 |\n|------|------|----------|\n| 文本响应大小 | > 256KB | CTON 压缩 |\n| 非文本响应 | 任何大小 | 直接返回 |\n\n资料来源：[src/server/toolHandlers.ts:95-97]()\n\n### 压缩工作流\n\n```mermaid\ngraph TD\n A[\"handler返回ToolResponse\"] --> B{\"textContent?.type
=== 'text'?\"}\n \n B -->|是| C{\"text.length
> 256KB?\"}\n B -->|否| Z[\"直接返回原始响应\"]\n \n C -->|是| D[\"maybeCompressResponse\"]\n C -->|否| Z\n \n D --> E{\"compressed?\"}\n E -->|是| F[\"包装为JSON.stringify
{compressed: true, data}\"]\n E -->|否| Z\n \n F --> G[\"返回压缩后的响应\"]\n Z --> H[\"返回给客户端\"]\n G --> H\n```\n\n### 压缩配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | boolean | 实体创建时自动索引嵌入向量 |\n| `MEMORY_EMBEDDING_PROVIDER` | `openai` \\| `local` \\| `none` | 嵌入向量生成提供者 |\n| `MEMORY_EMBEDDING_MODEL` | string | 嵌入模型名称 |\n\n资料来源：[CLAUDE.md:42-48]()\n\n## 存储层数据流\n\n### 存储类型支持\n\n| 存储类型 | 默认路径 | 环境变量 |\n|----------|----------|----------|\n| JSONL | `memory.jsonl` | `MEMORY_STORAGE_TYPE=jsonl` |\n| SQLite | `memory.db` | `MEMORY_STORAGE_TYPE=sqlite` |\n\n存储文件位于**项目根目录**，而非 `dist/` 构建目录。 资料来源：[CLAUDE.md:54-56]()\n\n### 数据流层级\n\n```mermaid\ngraph LR\n subgraph \"访问接口层\"\n A[\"ManagerContext
入口\"]\n end\n \n subgraph \"管理器层\"\n B[\"EntityManager\"]\n C[\"RelationManager\"]\n D[\"SearchManager\"]\n E[\"ObservationManager\"]\n F[\"TagManager\"]\n G[\"HierarchyManager\"]\n end\n \n subgraph \"存储抽象层\"\n H[\"GraphStorage
统一接口\"]\n end\n \n subgraph \"存储实现层\"\n I[\"JSONLStorage\"]\n J[\"SQLiteStorage\"]\n end\n \n A --> B\n A --> C\n A --> D\n A --> E\n A --> F\n A --> G\n \n B --> H\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I\n H --> J\n```\n\n### 可用管理器接口\n\n`ManagerContext` 提供以下管理器访问：\n\n| 管理器 | 访问方式 | 主要功能 |\n|--------|----------|----------|\n| 实体管理 | `ctx.entityManager` | 创建、读取、更新、删除图节点 |\n| 关系管理 | `ctx.relationManager` | 管理有向边 |\n| 观察管理 | `ctx.observationManager` | 附加到实体的观察/事实 |\n| 搜索管理 | `ctx.searchManager` | 基础和高级搜索 |\n| 标签管理 | `ctx.tagManager` | 标签 CRUD 和批量操作 |\n| 层级管理 | `ctx.hierarchyManager` | 父子树结构 |\n| 分析管理 | `ctx.analyticsManager` | 图统计和完整性验证 |\n| 压缩管理 | `ctx.compressionManager` | 去重和自动压缩 |\n| IO 管理 | `ctx.ioManager` | 导入导出操作 |\n| 图遍历 | `ctx.graphTraversal` | BFS/DFS 路径查找 |\n| 语义搜索 | `ctx.semanticSearch` | 嵌入相似度搜索 |\n| 排名搜索 | `ctx.rankedSearch` | TF-IDF 排名搜索 |\n| 存储 | `ctx.storage` | 直接访问 GraphStorage |\n\n资料来源：[CLAUDE.md:25-30]()\n\n## 工具分类数据流\n\n### 按功能分类的处理器组\n\n系统包含 **213 个工具**，分布在 **58 个类别**中：\n\n| 类别 | 数量 | 数据流特点 |\n|------|------|------------|\n| Entity | 4 | 直接写入存储，可能触发自动嵌入索引 |\n| Relation | 2 | 边创建涉及关系完整性验证 |\n| Observation | 3 | 支持规范化处理和去重检测 |\n| Search | 7 | 查询密集型，结果可能超过 256KB 阈值 |\n| Semantic Search | 3 | 嵌入向量计算，延迟较高 |\n| Import/Export | 2 | IO 密集型，大文件处理 |\n| Compression | 4 | 涉及存储重写和数据压缩 |\n\n资料来源：[CLAUDE.md:31-46]()\n\n### 大数据量工具处理\n\n以下工具因可能返回无界结果集而被标记为需要压缩处理：\n\n| 工具名 | 潜在问题 |\n|--------|----------|\n| `read_graph` | 全图数据可能极大 |\n| `search_nodes` | 匹配结果无明确上界 |\n| `get_subtree` | 子树深度不可预测 |\n| `open_nodes` | 展开节点可能指数增长 |\n\n资料来源：[src/server/toolHandlers.ts:98-101]()\n\n## 响应格式化\n\n### 格式化函数\n\n系统提供两种响应格式化函数：\n\n```typescript\n// 结构化响应 - 用于成功操作的 JSON 结构\nfunction formatToolResponse(data: unknown): ToolResponse\n\n// 文本响应 - 用于简单消息或未找到结果\nfunction formatTextResponse(message: string): ToolResponse\n```\n\n### ToolResponse 结构\n\n```typescript\ninterface ToolResponse {\n content: Array<{\n type: 'text';\n text: string | CompressedPayload;\n }>;\n}\n\ninterface CompressedPayload {\n compressed: true;\n originalSize: number;\n compressedSize: number;\n algorithm: 'cton';\n data: string;\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:108-120]()\n\n## 独立压缩工具\n\n除了 MCP 服务器内置的压缩机制，项目还提供独立的命令行压缩工具 `compress-for-context`： 资料来源：[tools/compress-for-context/compress-for-context.ts:1-50]()\n\n### 功能特性\n\n| 功能 | 说明 |\n|------|------|\n| 批量压缩 | 支持批量处理多个文件 |\n| 递归压缩 | 可递归处理子目录 |\n| 格式支持 | JSON、YAML、Markdown、CSV、TSV、Text、Log、TypeScript、JavaScript、XML、HTML |\n| 压缩级别 | light（轻度）、medium（中度）、aggressive（激进） |\n| 解压缩 | 支持从 `.compact` 文件恢复原始内容 |\n\n### 命令行用法\n\n```bash\n# 单文件压缩\nnode compress-for-context.js data.json\nnode compress-for-context.js README.md -l aggressive\n\n# 批量递归压缩\nnode compress-for-context.js -b -r -p \"*.md\" ./docs\n\n# 预览压缩（不写入文件）\nnode compress-for-context.js log.txt --dry-run\n\n# 解压缩\nnode compress-for-context.js -d data.json.compact\n```\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:15-40]()\n\n## 数据迁移工具\n\n### JSONL 与 SQLite 互转\n\n独立工具 `migrate-from-jsonl-to-sqlite` 支持存储格式间的迁移：\n\n```bash\nmigrate-from-jsonl-to-sqlite --from --to [--verbose]\n```\n\n使用 `better-sqlite3` 实现原生 SQLite 性能。 资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30]()\n\n## 测试覆盖\n\n### 测试统计\n\n| 指标 | 数值 |\n|------|------|\n| 测试文件数 | 26 |\n| 测试用例数 | ~665 |\n| 语句覆盖率 | 80.7% |\n| 行覆盖率 | 81.4% |\n| 函数覆盖率 | 79% |\n\n资料来源：[CLAUDE.md:58-59]()\n\n### 数据流相关测试\n\n新增工具应按以下流程添加测试：\n\n1. 在 `tests/e2e/tools/` 目录添加端到端测试\n2. 测试空图和大图场景\n3. 验证导出格式正确性\n4. 验证压缩机制触发条件\n\n资料来源：[CONTRIBUTING.md:25-30]()\n\n## 扩展新工具数据流\n\n### 添加新工具的标准流程\n\n```mermaid\ngraph TD\n A[\"定义工具schema\"] --> B[\"添加handler函数\"]\n B --> C[\"注册到handler映射表\"]\n C --> D[\"添加端到端测试\"]\n D --> E[\"更新文档\"]\n \n subgraph \"步骤1: toolDefinitions.ts\"\n A\n end\n \n subgraph \"步骤2: toolHandlers.ts\"\n B\n end\n \n subgraph \"步骤3: 注册\"\n C\n end\n```\n\n### Handler 注册模式\n\n```typescript\n// 在 toolHandlers.ts 中\nexport const toolHandlers = {\n [TOOL_NAME]: async (ctx, args) => {\n // 1. 参数验证\n // 2. 调用 manager\n // 3. 格式化响应\n },\n};\n```\n\n资料来源：[CLAUDE.md:33-37]()\n\n## 最佳实践\n\n### 性能优化建议\n\n| 场景 | 建议 |\n|------|------|\n| 大结果集查询 | 使用分页参数限制返回量 |\n| 频繁搜索 | 利用 `saved_searches` 缓存查询 |\n| 批量操作 | 优先使用 bulk API 而非循环单条 |\n| 嵌入搜索 | 设置 `MEMORY_AUTO_INDEX_EMBEDDINGS=true` |\n\n### 错误处理\n\n- 参数验证失败：抛出包含具体字段名的错误\n- 存储操作失败：向上传递错误，不做静默处理\n- 网络相关：内存 MCP 无外部网络依赖，此项不适用\n\n### 压缩策略选择\n\n| 压缩级别 | 适用场景 |\n|----------|----------|\n| light | 需要保留可读性的配置文件、日志 |\n| medium | 日常开发文档和中等复杂度数据（默认） |\n| aggressive | 传输给 LLM 的上下文、极限压缩场景 |\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:18-22]()\n\n---\n\n*最后更新：基于 v12.3.0 版本*\n\n---\n\n\n\n## 实体与关系模型\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [存储后端](#page-storage-backends), [层级嵌套](#page-hierarchical-nesting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n \n\n# 实体与关系模型\n\nmemory-mcp 是一个基于 Model Context Protocol 的记忆管理服务器，其核心数据模型采用**属性图模型（Property Graph Model）**。系统以实体（Entity）作为图节点，以关系（Relation）作为有向边，通过观察（Observation）附加事实信息，构建具有语义关联的知识图谱。\n\n资料来源：[CLAUDE.md:1-10]()\n\n## 1. 架构概述\n\nmemory-mcp 的实体与关系模型构建在 `@danielsimonjr/memoryjs` 库之上，通过分层架构提供服务能力。\n\n```mermaid\ngraph TD\n subgraph \"memory-mcp (本仓库)\"\n A[MCPServer] --> B[toolHandlers]\n B --> C[ManagerContext]\n C --> D[memoryjs 核心库]\n end\n \n subgraph \"@danielsimonjr/memoryjs\"\n E[EntityManager]\n F[RelationManager]\n G[ObservationManager]\n H[GraphStorage]\n end\n \n C --> E\n C --> F\n C --> G\n H --> I[(SQLite/JSONL)]\n \n D --> E\n D --> F\n D --> G\n D --> H\n```\n\n### 1.1 核心管理器\n\n| 管理器 | 职责 | 存储后端 |\n|--------|------|----------|\n| EntityManager | 实体 CRUD 操作 | GraphStorage |\n| RelationManager | 关系创建、查询、删除 | GraphStorage |\n| ObservationManager | 观察事实的添加与检索 | GraphStorage |\n| SearchManager | 全文与语义搜索 | 索引层 |\n| TagManager | 标签分类管理 | GraphStorage |\n| HierarchyManager | 层级结构管理 | GraphStorage |\n\n资料来源：[CLAUDE.md:18-28]()\n\n## 2. 实体模型\n\n实体是知识图谱中的核心节点，代表现实世界中的概念对象。\n\n### 2.1 实体数据结构\n\n```typescript\ninterface Entity {\n id: string; // 唯一标识符（UUID）\n name: string; // 实体名称\n entityType?: string; // 实体类型（如 \"person\", \"project\"）\n observations: string[]; // 关联的观察 ID 列表\n tags: string[]; // 标签数组\n metadata?: Record; // 扩展元数据\n importance?: number; // 重要性评分 (0-10)\n createdAt: string; // ISO 时间戳\n updatedAt: string; // ISO 时间戳\n archived?: boolean; // 归档状态\n}\n```\n\n### 2.2 实体操作工具\n\n| 工具名称 | 功能 | 核心参数 |\n|----------|------|----------|\n| create_entity | 创建新实体 | name, entityType, metadata, tags |\n| get_entity | 获取实体详情 | name 或 id |\n| update_entity | 更新实体属性 | name/id, updates |\n| delete_entity | 删除实体 | name 或 id |\n| list_entities | 列出实体 | filter, limit, offset |\n| merge_entities | 合并实体 | sourceIds, targetName |\n| archive_entities | 批量归档 | filter |\n\n资料来源：[src/server/toolDefinitions.ts:1-150]()\n\n### 2.3 实体创建示例\n\n```typescript\n// 工具调用示例：create_entity\n{\n name: \"create_entity\",\n arguments: {\n name: \"Alice Developer\",\n entityType: \"person\",\n metadata: {\n role: \"software_engineer\",\n company: \"TechCorp\"\n },\n tags: [\"developer\", \"ai-expert\"],\n importance: 8\n }\n}\n```\n\n## 3. 关系模型\n\n关系是有向边，连接两个实体并携带语义信息。\n\n### 3.1 关系数据结构\n\n```typescript\ninterface Relation {\n id: string; // 唯一标识符\n from: string; // 源实体 ID 或名称\n to: string; // 目标实体 ID 或名称\n relationType: string; // 关系类型（如 \"works_for\", \"knows\"）\n metadata?: Record; // 关系属性\n bidirectional?: boolean; // 是否双向关系\n createdAt: string;\n}\n```\n\n### 3.2 关系类型示例\n\n| 关系类型 | 语义 | 示例 |\n|----------|------|------|\n| works_for | 雇佣关系 | Alice → TechCorp |\n| knows | 社交关系 | Alice → Bob |\n| created | 创建关系 | Alice → ProjectX |\n| depends_on | 依赖关系 | ModuleA → ModuleB |\n| part_of | 包含关系 | Chapter1 → Book |\n\n### 3.3 关系操作工具\n\n| 工具名称 | 功能 | 核心参数 |\n|----------|------|----------|\n| create_relation | 创建关系 | from, to, relationType, bidirectional |\n| get_relation | 获取关系 | from, to, relationType |\n| delete_relation | 删除关系 | from, to, relationType |\n| list_relations | 列出关系 | filter, entityName, limit |\n\n资料来源：[src/server/toolHandlers.ts:1-100]()\n\n## 4. 观察模型\n\n观察（Observation）是附加在实体上的事实片段，是知识图谱的信息载体。\n\n### 4.1 观察数据结构\n\n```typescript\ninterface Observation {\n id: string; // 唯一标识符\n entityId: string; // 关联实体\n content: string; // 事实内容\n normalizedContent?: string; // 规范化后的内容\n source?: string; // 信息来源\n importance?: number; // 重要性评分\n tags?: string[]; // 观察标签\n metadata?: Record;\n createdAt: string;\n updatedAt: string;\n}\n```\n\n### 4.2 观察操作工具\n\n| 工具名称 | 功能 | 核心参数 |\n|----------|------|----------|\n| create_observation | 添加观察 | entityName/id, content, source, tags |\n| get_observations | 获取观察 | entityName/id, limit |\n| update_observation | 更新观察 | observationId, updates |\n| delete_observation | 删除观察 | observationId |\n| normalize_observation | 规范化文本 | observationId |\n| create_observation_ref | 创建观察引用 | observationId, entityName, relationType |\n\n资料来源：[src/server/toolDefinitions.ts:200-350]()\n\n### 4.3 观察流程图\n\n```mermaid\ngraph LR\n A[实体] -->|关联| B[观察]\n B -->|内容| C[规范化处理]\n C -->|索引| D[SearchManager]\n D -->|检索| E[全文搜索]\n D -->|检索| F[语义搜索]\n \n B --> G[重要性评分]\n G --> H[衰减引擎]\n H --> I[遗忘决策]\n```\n\n## 5. 存储模型\n\n### 5.1 存储类型\n\nmemory-mcp 支持两种存储后端，通过环境变量 `MEMORY_STORAGE_TYPE` 配置。\n\n| 存储类型 | 环境变量 | 文件位置 | 适用场景 |\n|----------|----------|----------|----------|\n| JSONL | `MEMORY_STORAGE_TYPE=jsonl` | memory.jsonl | 小规模数据、开发测试 |\n| SQLite | `MEMORY_STORAGE_TYPE=sqlite` | memory.db | 生产环境、大规模数据 |\n\n资料来源：[CLAUDE.md:50-55]()\n\n### 5.2 数据文件\n\n```bash\n# 项目根目录下的数据文件\nmemory.jsonl # 主数据（JSONL 格式）\nmemory-saved-searches.jsonl # 保存的搜索查询\nmemory-tag-aliases.jsonl # 标签别名映射\nmemory.db # SQLite 数据库\n```\n\n### 5.3 环境变量配置\n\n| 变量名 | 描述 | 默认值 |\n|--------|------|--------|\n| MEMORY_FILE_PATH | 存储文件路径 | memory.jsonl |\n| MEMORY_STORAGE_TYPE | 存储类型 | jsonl |\n| MEMORY_EMBEDDING_PROVIDER | 向量化 provider | none |\n| MEMORY_OPENAI_API_KEY | OpenAI API 密钥 | — |\n| MEMORY_EMBEDDING_MODEL | 向量化模型 | text-embedding-3-small |\n| MEMORY_AUTO_INDEX_EMBEDDINGS | 自动索引嵌入 | false |\n\n资料来源：[CLAUDE.md:45-49]()\n\n## 6. 图遍历与算法\n\n### 6.1 图遍历管理器\n\n`ctx.graphTraversal` 提供图结构遍历能力：\n\n```typescript\n// 可用的遍历方法\nctx.graphTraversal.bfs(from, to); // 广度优先搜索\nctx.graphTraversal.dfs(from, to); // 深度优先搜索\nctx.graphTraversal.findPath(from, to); // 最短路径\nctx.graphTraversal.findAllPaths(from, to); // 所有路径\n```\n\n### 6.2 图算法工具\n\n| 工具名称 | 功能 | 描述 |\n|----------|------|------|\n| find_path | 路径查找 | BFS/DFS 查找两实体间路径 |\n| find_shortest_path | 最短路径 | 实体间的最短关系路径 |\n| find_connected_entities | 连通分量 | 查找所有连通的实体群组 |\n| compute_centrality | 中心性计算 | 计算实体的图中心性指标 |\n\n### 6.3 图遍历示例\n\n```mermaid\ngraph TD\n A[Alice] -->|works_for| B[TechCorp]\n A -->|knows| C[Bob]\n C -->|works_for| B\n A -->|knows| D[Carol]\n D -->|created| E[ProjectX]\n B -->|created| E\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style E fill:#e8f5e8\n```\n\n查询 Alice 到 ProjectX 的路径：\n- Alice → TechCorp → ProjectX（2跳）\n- Alice → Carol → ProjectX（2跳）\n\n## 7. 标签与层级\n\n### 7.1 标签系统\n\n```typescript\n// 标签操作\nctx.tagManager.add(entityId, tag); // 添加标签\nctx.tagManager.remove(entityId, tag); // 移除标签\nctx.tagManager.findByTag(tag); // 按标签查询\nctx.tagManager.setImportance(entityId, score); // 设置重要性\n```\n\n### 7.2 层级结构\n\n```typescript\n// 层级操作\nctx.hierarchyManager.setParent(childId, parentId); // 设置父节点\nctx.hierarchyManager.getChildren(parentId); // 获取子节点\nctx.hierarchyManager.getSubtree(nodeId); // 获取子树\nctx.hierarchyManager.getAncestors(nodeId); // 获取祖先链\n```\n\n## 8. 搜索功能\n\n### 8.1 搜索类型\n\n| 搜索类型 | 工具 | 描述 |\n|----------|------|------|\n| 基础搜索 | search_entities | 关键词全文搜索 |\n| 布尔搜索 | boolean_search | AND/OR/NOT 逻辑组合 |\n| 模糊搜索 | fuzzy_search | 容错匹配 |\n| 语义搜索 | semantic_search | 向量相似度检索 |\n| 排名搜索 | ranked_search | TF-IDF 加权排序 |\n| 自动选择 | auto_select_search | 自适应最佳搜索策略 |\n\n### 8.2 语义搜索配置\n\n启用语义搜索需要配置嵌入模型：\n\n```bash\n# OpenAI 嵌入\nMEMORY_EMBEDDING_PROVIDER=openai\nMEMORY_OPENAI_API_KEY=sk-...\nMEMORY_EMBEDDING_MODEL=text-embedding-3-small\nMEMORY_AUTO_INDEX_EMBEDDINGS=true\n\n# 本地嵌入\nMEMORY_EMBEDDING_PROVIDER=local\nMEMORY_EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2\n```\n\n## 9. 数据导出\n\n### 9.1 导出格式\n\n| 格式 | 工具 | 用途 |\n|------|------|------|\n| JSON | export_graph | 通用数据交换 |\n| CSV | export_graph | 电子表格分析 |\n| Markdown | export_graph | 文档生成 |\n| XML | export_graph | 企业系统集成 |\n| JSON-LD | export_graph | 语义网应用 |\n| GraphML | export_graph | 图可视化工具 |\n\n### 9.2 导出工具\n\n```typescript\n// 导出图数据\nexport_graph({\n format: \"json\", // json|csv|markdown|xml|json-ld\n includeArchived: false,\n redactPii: true // PII 脱敏\n})\n```\n\n资料来源：[CLAUDE.md:30-35]()\n\n## 10. 完整工作流示例\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCPServer\n participant ToolHandlers\n participant EntityManager\n participant GraphStorage\n\n Client->>MCPServer: create_entity\n MCPServer->>ToolHandlers: route to create_entity handler\n ToolHandlers->>EntityManager: createEntity(data)\n EntityManager->>GraphStorage: persist\n GraphStorage-->>EntityManager: entity with id\n EntityManager-->>ToolHandlers: result\n ToolHandlers-->>MCPServer: formatted response\n MCPServer-->>Client: MCP response\n\n Note over Client,GraphStorage: 创建实体后添加观察\n\n Client->>MCPServer: create_observation\n MCPServer->>ToolHandlers: route to create_observation handler\n ToolHandlers->>EntityManager: getEntity(name)\n EntityManager-->>ToolHandlers: entity\n ToolHandlers->>ObservationManager: createObservation(data)\n ObservationManager->>GraphStorage: persist\n GraphStorage-->>ObservationManager: observation with id\n ObservationManager-->>ToolHandlers: result\n ToolHandlers-->>MCPServer: formatted response\n MCPServer-->>Client: MCP response\n```\n\n## 11. 相关资源\n\n- **核心库文档**: [@danielsimonjr/memoryjs](https://www.npmjs.com/package/@danielsimonjr/memoryjs)\n- **项目地址**: https://github.com/danielsimonjr/memory-mcp\n- **npm 包**: @danielsimonjr/memory-mcp\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[实体与关系模型](#page-entities-relations), [数据流处理](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)\n- [tools/migrate-from-jsonl-to-sqlite/README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/README.md)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [SECURITY.md](https://github.com/danielsimonjr/memory-mcp/blob/main/SECURITY.md)\n- [package.json](https://github.com/danielsimonjr/memory-mcp/blob/main/package.json)\n \n\n# 存储后端\n\n## 概述\n\nMemory MCP 的存储后端是整个系统的核心基础设施，负责持久化知识图谱数据。系统支持两种存储格式：**JSONL**（基于文本行的 JSON 格式）和 **SQLite**（关系型数据库）。存储后端通过 `@danielsimonjr/memoryjs` 库提供统一的访问接口，实现了数据的抽象化存储，使得上层业务逻辑无需关心底层存储细节。\n\n项目的存储架构采用分层设计，memory-mcp 作为前端封装，通过 ManagerContext 访问 memoryjs 核心库提供的各种管理器，这些管理器再与底层存储层（GraphStorage 或 SQLiteStorage）进行交互。资料来源：[CLAUDE.md]()\n\n## 支持的存储格式\n\nMemory MCP 支持两种存储后端格式，开发者可根据数据规模、性能需求和使用场景选择合适的格式。\n\n| 格式 | 文件扩展名 | 适用场景 | 性能特点 |\n|------|------------|----------|----------|\n| JSONL | `.jsonl`, `.json` | 小规模数据、简单部署、调试 | 易于阅读和编辑，人类可读 |\n| SQLite | `.db`, `.sqlite`, `.sqlite3` | 大规模数据、生产环境 | 原生 C++ 实现，性能提升 3-10 倍 |\n\nSQLite 后端通过 `better-sqlite3` 原生绑定实现，比 WASM 实现快 3-10 倍。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n## 存储文件布局\n\n根据架构规范，数据文件位于**项目根目录**（而非 `dist/` 输出目录）。这种设计确保了数据文件的独立性和可移植性。\n\n### JSONL 格式文件\n\n```\n项目根目录/\n├── memory.jsonl # 实体和关系数据\n├── memory-saved-searches.jsonl # 保存的搜索查询\n└── memory-tag-aliases.jsonl # 标签别名映射\n```\n\n### SQLite 格式文件\n\n```\n项目根目录/\n└── memory.db # 单一数据库文件（所有数据）\n```\n\n配置环境变量 `MEMORY_STORAGE_TYPE=sqlite` 可启用 SQLite 存储模式。资料来源：[CLAUDE.md]()\n\n## 架构分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ memory-mcp (本项目) │\n├─────────────────────────────────────────────────────────────┤\n│ src/index.ts │ 入口点，重新导出核心类型 │\n│ src/server/MCPServer.ts │ MCP 服务器实现 │\n│ src/server/toolDefs.ts │ 工具定义 │\n│ src/server/toolHandlers │ 工具处理器 │\n└───────────────────────────┼─────────────────────────────────┘\n │ 依赖导入\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ @danielsimonjr/memoryjs (npm 依赖) │\n├─────────────────────────────────────────────────────────────┤\n│ ManagerContext (延迟初始化) │\n│ ├── EntityManager │ 实体管理器 │\n│ ├── RelationManager │ 关系管理器 │\n│ ├── ObservationManager │ 观察数据管理器 │\n│ ├── SearchManager │ 搜索管理器 │\n│ ├── TagManager │ 标签管理器 │\n│ ├── HierarchyManager │ 层级管理器 │\n│ ├── AnalyticsManager │ 分析管理器 │\n│ ├── CompressionManager │ 压缩管理器 │\n│ ├── ArchiveManager │ 归档管理器 │\n│ ├── IOManager │ IO 管理器 │\n│ ├── GraphTraversal │ 图遍历 │\n│ ├── SemanticSearch │ 语义搜索 │\n│ ├── RankedSearch │ 排名搜索 │\n│ └── Storage │ 直接访问 GraphStorage │\n├─────────────────────────────────────────────────────────────┤\n│ 存储层 (GraphStorage) │\n│ ├── SQLiteStorage │ SQLite 原生实现 │\n│ └── JsonlStorage │ JSONL 文件实现 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[CLAUDE.md]()\n\n## SQLite 存储特性\n\nSQLite 后端实现了多项企业级特性，以提供高性能和可靠的数据存储。\n\n### 自动全文搜索索引\n\nSQLite 后端会自动创建 **FTS5**（Full-Text Search version 5）索引，启用高级全文搜索功能。这使得系统能够支持复杂的文本搜索查询，无需额外的搜索基础设施。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### WAL 模式\n\nSQLite 数据库启用 **WAL（Write-Ahead Logging）模式**，该模式允许读写操作并发进行，显著提升多客户端访问场景下的性能。WAL 模式相比传统的回滚日志模式，在大多数场景下提供更好的并发性能。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### 原子事务\n\n所有数据写入操作都使用**原子事务**包装，确保在系统崩溃或异常断电情况下的数据完整性。原子事务保证要么所有操作成功提交，要么全部回滚，不会出现部分写入的损坏状态。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n## 存储迁移工具\n\n项目提供了独立的迁移工具 `migrate-from-jsonl-to-sqlite`，支持在两种存储格式之间双向转换。\n\n### 工具位置\n\n```\ntools/\n└── migrate-from-jsonl-to-sqlite/\n ├── migrate-from-jsonl-to-sqlite.ts # TypeScript 源码\n ├── package.json # 工具依赖配置\n └── README.md # 使用文档\n```\n\n### 安装与构建\n\n```bash\ncd tools/migrate-from-jsonl-to-sqlite\nnpm install\nnpm run build\n```\n\n构建完成后可生成 Windows 可执行文件 `migrate-from-jsonl-to-sqlite.exe`。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### 命令行参数\n\n| 参数 | 简写 | 描述 | 示例 |\n|------|------|------|------|\n| `--from` | `-f` | 源文件路径（JSONL 或 SQLite） | `--from memory.jsonl` |\n| `--to` | `-t` | 目标文件路径（JSONL 或 SQLite） | `--to memory.db` |\n| `--verbose` | `-v` | 显示详细进度信息 | `--verbose` |\n| `--help` | `-h` | 显示帮助信息 | `--help` |\n\n### 使用示例\n\n```bash\n# JSONL 转换为 SQLite\nmigrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db\n\n# SQLite 转换为 JSONL\nmigrate-from-jsonl-to-sqlite --from memory.db --to memory.jsonl\n\n# 使用位置参数\nmigrate-from-jsonl-to-sqlite memory.jsonl memory.db\n\n# 详细输出模式\nmigrate-from-jsonl-to-sqlite -f memory.jsonl -t memory.db -v\n```\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### 迁移流程\n\n```mermaid\ngraph TD\n A[开始迁移] --> B{检测源文件类型}\n B -->|JSONL| C[loadFromJsonl]\n B -->|SQLite| D[loadFromSqlite]\n C --> E[加载数据到内存]\n D --> E\n E --> F{实体数=0 且 关系数=0?}\n F -->|是| G[输出警告，终止]\n F -->|否| H[写入目标文件]\n H --> I{目标类型}\n I -->|SQLite| J[创建数据库 + FTS5 索引 + WAL 模式]\n I -->|JSONL| K[逐行写入 JSONL]\n J --> L[使用原子事务提交]\n K --> L\n L --> M[迁移完成]\n```\n\n### 注意事项\n\n- 目标文件不存在时会自动创建\n- 目标文件已存在时会**覆盖**原有数据\n- 迁移会保留所有实体、关系和元数据\n- 缺失的时间戳会被设置为迁移时间并输出警告\n- **已保存的搜索**和**标签别名**不会迁移到 SQLite 格式\n- 迁移工具使用 `better-sqlite3` 原生绑定，性能优于 WASM 实现\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts]()\n\n## 核心数据模型\n\nMemory MCP 的存储后端管理以下核心数据结构：\n\n### 实体 (Entity)\n\n实体是知识图谱中的节点，代表独立的概念、对象或事物。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| name | string | 实体名称 |\n| observation | string | 主要观察/描述数据 |\n| metadata | object | 附加元数据 |\n| createdAt | timestamp | 创建时间 |\n| updatedAt | timestamp | 更新时间 |\n\n### 关系 (Relation)\n\n关系是连接两个实体的有向边，定义实体间的关联。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| from | string | 源实体 ID |\n| to | string | 目标实体 ID |\n| relationType | string | 关系类型 |\n\n### 观察数据 (Observation)\n\n观察数据是附加到实体的客观事实，支持数据归一化。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| entityId | string | 所属实体 ID |\n| content | string | 观察内容 |\n| normalized | object | 归一化后的数据 |\n\n### 产物 (Artifact)\n\n产物是工具输出、代码片段、API 响应等内容的存储容器。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| ref | string | 稳定的引用标识符 |\n| content | string | 产物内容 |\n| toolName | string | 产生该产物的工具名 |\n| artifactType | enum | 产物类型 |\n| sessionId | string | 会话上下文（可选） |\n\n产物类型枚举值包括：`tool_output`、`code_snippet`、`api_response`、`search_result`、`file_content`、`user_input`。资料来源：[src/server/toolDefinitions.ts]()\n\n## 存储配置\n\n### 环境变量\n\n| 变量名 | 值 | 描述 |\n|--------|-----|------|\n| `MEMORY_STORAGE_TYPE` | `sqlite` | 启用 SQLite 存储 |\n| `MEMORY_FILE_PATH` | 文件路径 | 指定自定义存储路径 |\n\n### 安全配置示例\n\n在容器化环境中，建议通过环境变量或 Kubernetes Secret 管理存储路径：\n\n```yaml\napiVersion: v1\nkind: Pod\nspec:\n containers:\n - name: memory-mcp\n env:\n - name: MEMORY_FILE_PATH\n value: \"/secure/path/memory.jsonl\"\n```\n\n资料来源：[SECURITY.md]()\n\n## 安全考量\n\n存储后端的安全性直接影响整体系统的数据保护能力。\n\n### 静态数据安全\n\n| 风险 | 描述 | 缓解措施 |\n|------|------|----------|\n| 文件可读性 | 本地文件可被任何有权限的进程读取 | 限制文件权限，使用专用存储路径 |\n| 无内置加密 | 存储文件未加密 | 依赖文件系统加密或全磁盘加密 |\n| 无访问控制 | 无用户认证授权机制 | 通过系统权限和网络隔离实现 |\n\n### 导出安全\n\nCSV 和 JSON 导出包含完整的实体数据，在分享前应检查敏感信息。GraphML 格式需要正确的 XML 实体转义处理。资料来源：[SECURITY.md]()\n\n### 备份建议\n\n```bash\n# 备份存储文件\ncp memory.jsonl memory.jsonl.backup\n# 或对于 SQLite\ncp memory.db memory.db.backup\n```\n\n## 性能优化\n\n### SQLite 性能特性\n\n| 特性 | 作用 | 性能影响 |\n|------|------|----------|\n| better-sqlite3 原生绑定 | 直接调用 SQLite C 库 | 比 WASM 快 3-10x |\n| WAL 模式 | 支持读写并发 | 提升多客户端性能 |\n| FTS5 全文索引 | 自动创建的全文搜索索引 | 加速文本搜索 |\n| 原子事务 | 保证数据一致性 | 防止数据损坏 |\n\n### 压缩管理\n\n存储后端集成压缩管理器，支持以下操作：\n\n- **重复检测**：识别知识图谱中的重复实体\n- **智能合并**：合并重复数据，保留最新信息\n- **自动压缩**：根据配置阈值自动触发压缩\n- **归档**：将历史数据归档以优化活跃数据访问\n\n资料来源：[CLAUDE.md]()\n\n## 依赖配置\n\n### npm 依赖\n\n```json\n{\n \"dependencies\": {\n \"@danielsimonjr/memoryjs\": \"^2.1.0\",\n \"@modelcontextprotocol/sdk\": \"^1.21.1\",\n \"zod\": \"^3.24.1\"\n }\n}\n```\n\n### 迁移工具依赖\n\n```json\n{\n \"dependencies\": {\n \"better-sqlite3\": \"^11.7.0\"\n },\n \"devDependencies\": {\n \"@types/better-sqlite3\": \"^7.6.12\",\n \"@yao-pkg/pkg\": \"^6.11.0\",\n \"typescript\": \"^5.6.2\"\n }\n}\n```\n\n资料来源：[package.json]()\n\n## 工具构建\n\n项目提供了便捷的脚本用于构建所有独立工具：\n\n```bash\n# 安装所有工具依赖\nnpm run tools:install\n\n# 构建所有工具（包括迁移工具）\nnpm run tools:build\n```\n\n构建后的迁移工具位于 `tools/migrate-from-jsonl-to-sqlite/` 目录，可生成独立的 Windows 可执行文件。资料来源：[package.json]()\n\n## 总结\n\nMemory MCP 的存储后端提供了灵活、高效、可靠的数据持久化能力。通过支持 JSONL 和 SQLite 两种格式，开发者可以根据实际需求选择合适的存储方案。SQLite 后端凭借原生绑定、WAL 模式、FTS5 索引等特性，在生产环境中提供卓越的性能表现。独立的迁移工具简化了格式转换过程，而分层架构则确保了系统的可维护性和扩展性。\n\n---\n\n\n\n## 层级嵌套\n\n### 相关页面\n\n相关主题：[实体与关系模型](#page-entities-relations), [搜索能力](#page-search-capabilities)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts) — 层级工具处理器实现\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts) — 层级工具定义\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) — 项目架构文档\n \n\n# 层级嵌套\n\n## 概述\n\n层级嵌套（Hieararchy）是 memory-mcp 知识图谱系统中用于管理实体间父子关系和树形结构的核心功能模块。该模块通过 `ctx.hierarchyManager` 提供9个专用工具，支持实体间的父子树构建和子树遍历操作。\n\n层级管理是知识图谱组织结构化信息的重要手段，允许用户将实体组织成树形层级关系，便于表达分类、归属、继承等概念。资料来源：[CLAUDE.md:1]()。\n\n## 架构设计\n\n### 访问方式\n\n层级管理器通过 `ManagerContext` 实例访问：\n\n```typescript\nctx.hierarchyManager\n```\n\n可用的层级操作方法包括：\n\n| 方法 | 功能描述 |\n|------|----------|\n| `setEntityParent(entityName, parentName)` | 设置实体的父节点 |\n| `getChildren(entityName)` | 获取直接子节点 |\n| `getParent(entityName)` | 获取父节点 |\n| `getAncestors(entityName)` | 获取所有祖先节点 |\n| `getDescendants(entityName)` | 获取所有后代节点 |\n| `getSubtree(entityName)` | 获取完整子树结构 |\n\n资料来源：[src/server/toolHandlers.ts:1]()\n\n### 与其他模块的关系\n\n```\n┌─────────────────────────────────────────────┐\n│ ManagerContext │\n├─────────────────────────────────────────────┤\n│ hierarchyManager ──────────────────────────▶│\n│ ├── setEntityParent() │\n│ ├── getChildren() │\n│ ├── getParent() │\n│ ├── getAncestors() │\n│ ├── getDescendants() │\n│ └── getSubtree() │\n└─────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────┐\n│ @danielsimonjr/memoryjs │\n│ (底层存储: EntityManager + 层级索引) │\n└─────────────────────────────────────────────┘\n```\n\n## 工具清单\n\n### 工具分类：Hierarchy（共9个）\n\n| 工具名称 | 功能描述 | 核心参数 |\n|----------|----------|----------|\n| `set_entity_parent` | 设置实体的父节点 | `entityName`, `parentName` |\n| `get_children` | 获取实体的直接子节点 | `entityName` |\n| `get_parent` | 获取实体的直接父节点 | `entityName` |\n| `get_ancestors` | 获取实体的所有祖先节点 | `entityName` |\n| `get_descendants` | 获取实体的所有后代节点 | `entityName` |\n| `get_subtree` | 获取实体的完整子树 | `entityName` |\n\n资料来源：[CLAUDE.md:1]()\n\n## API 详细说明\n\n### set_entity_parent\n\n设置或更新实体的父节点关系。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 要设置父节点的实体名称 |\n| `parentName` | `string \\| null` | 否 | 父实体名称，设为 `null` 可移除父子关系 |\n\n**处理器实现：**\n\n```typescript\nset_entity_parent: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n const parentName = args.parentName !== undefined \n ? validateWithSchema(args.parentName, z.string().min(1).nullable(), 'Invalid parent name') \n : null;\n return formatToolResponse(await ctx.hierarchyManager.setEntityParent(entityName, parentName));\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:1]()\n\n### get_children\n\n获取指定实体的所有直接子节点。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_children: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getChildren(entityName));\n}\n```\n\n### get_parent\n\n获取指定实体的直接父节点。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_parent: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getParent(entityName));\n}\n```\n\n### get_ancestors\n\n获取指定实体的所有祖先节点（从直接父节点到根节点）。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_ancestors: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getAncestors(entityName));\n}\n```\n\n### get_descendants\n\n获取指定实体的所有后代节点（所有子节点、孙节点等）。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_descendants: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getDescendants(entityName));\n}\n```\n\n### get_subtree\n\n获取指定实体及其所有后代组成的完整子树结构。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 子树根节点实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_subtree: async (ctx, args) => {\n // 处理器定义（截断显示）\n return formatToolResponse(await ctx.hierarchyManager.getSubtree(entityName));\n}\n```\n\n## 使用流程\n\n### 典型操作流程\n\n```mermaid\ngraph TD\n A[开始] --> B[创建或获取实体]\n B --> C{是否需要设置父子关系}\n C -->|是| D[调用 set_entity_parent]\n C -->|否| E[直接进行层级查询]\n D --> F[关联层级索引]\n F --> G[查询层级关系]\n E --> G\n G --> H{查询类型}\n H -->|直接子节点| I[get_children]\n H -->|父节点| J[get_parent]\n H -->|所有祖先| K[get_ancestors]\n H -->|所有后代| L[get_descendants]\n H -->|完整子树| M[get_subtree]\n I --> N[返回结果]\n J --> N\n K --> N\n L --> N\n M --> N\n N --> O[结束]\n```\n\n### 使用示例\n\n**1. 构建组织层级结构：**\n\n```json\n// 设置公司 -> 部门 -> 团队的层级关系\n{\n \"entityName\": \"后端团队\",\n \"parentName\": \"技术部\"\n}\n```\n\n```json\n{\n \"entityName\": \"技术部\",\n \"parentName\": \"XX公司\"\n}\n```\n\n**2. 查询实体信息：**\n\n```json\n// 获取某实体的所有祖先\n{\n \"entityName\": \"后端团队\"\n}\n```\n\n**3. 遍历子树：**\n\n```json\n// 获取完整子树结构\n{\n \"entityName\": \"XX公司\"\n}\n```\n\n## 层级遍历算法\n\n### 树形结构示意\n\n```\n ┌─────────────┐\n │ 根节点 │\n │ (Root) │\n └──────┬──────┘\n │\n ┌───────────────┼───────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ 节点A │ │ 节点B │ │ 节点C │\n │ (Child 1) │ │ (Child 2) │ │ (Child 3) │\n └──────┬─────┘ └──────┬─────┘ └─────────────┘\n │\n ▼\n ┌─────────────┐\n │ 节点D │\n │ (Grandchild)│\n └─────────────┘\n```\n\n### 各方法返回范围\n\n| 方法 | 返回内容 | 说明 |\n|------|----------|------|\n| `get_parent` | `[A]` | 仅返回直接父节点 |\n| `get_children` | `[A, B, C]` | 仅返回直接子节点 |\n| `get_ancestors` | `[A]` → `[Root]` | 从父到根的完整路径 |\n| `get_descendants` | `[D]` → `[D]` | 所有后代节点的扁平列表 |\n| `get_subtree` | 完整树结构 | 包含根节点及其所有后代 |\n\n## 存储机制\n\n层级关系数据存储于项目的存储文件中，支持两种存储格式：\n\n| 存储类型 | 文件路径 | 说明 |\n|----------|----------|------|\n| JSONL | `memory.jsonl` | 默认存储格式 |\n| SQLite | `memory.db` | 设置 `MEMORY_STORAGE_TYPE=sqlite` 启用 |\n\n层级数据以实体属性的形式存储，由 `memoryjs` 库的底层存储系统管理。资料来源：[CLAUDE.md:1]()\n\n## 错误处理\n\n工具处理器使用 `validateWithSchema` 进行参数校验：\n\n| 错误类型 | 校验规则 | 处理方式 |\n|----------|----------|----------|\n| 空字符串 | `z.string().min(1)` | 返回验证错误信息 |\n| 类型错误 | Zod schema | 返回类型不匹配提示 |\n| 层级不存在 | 运行时检查 | 返回空结果或 `not found` 提示 |\n\n## 最佳实践\n\n### 1. 避免循环引用\n\n设置父子关系时，应避免创建环形结构：\n\n```mermaid\ngraph LR\n A --> B\n B --> C\n C --> A\n```\n\n系统不会自动检测循环引用，创建时请确保层级结构的有效性。\n\n### 2. 合理设置层级深度\n\n过深的层级会增加查询复杂度，建议：\n\n- 保持层级深度在合理范围内（建议 ≤ 10 层）\n- 对于过深的结构，考虑拆分为多个独立树\n\n### 3. 批量操作优化\n\n如需创建多个层级关系，建议按拓扑顺序执行，确保父节点先于子节点存在。\n\n## 相关文档\n\n| 文档 | 路径 | 说明 |\n|------|------|------|\n| 工具定义 | `src/server/toolDefinitions.ts` | 层级工具的 MCP schema 定义 |\n| 工具处理器 | `src/server/toolHandlers.ts` | 层级工具的业务逻辑实现 |\n| 核心架构 | `CLAUDE.md` | 项目整体架构说明 |\n\n## 更新日志\n\n| 版本 | 更新内容 |\n|------|----------|\n| v12.2.0 | 基础层级管理工具集（6个） |\n| v12.3.0 | 扩展层级操作，新增子树查询能力 |\n\n---\n\n\n\n## 搜索能力\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [工具参考手册](#page-tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n \n\n# 搜索能力\n\n## 概述\n\nmemory-mcp 的搜索能力是该知识图谱系统的核心功能之一，通过多层架构提供从基础关键词匹配到高级语义理解的全面搜索能力。系统支持超过 20 种搜索工具，涵盖基础搜索、智能搜索、语义搜索三大类别，并提供保存搜索和定时搜索等高级功能。\n\n搜索功能由 `ManagerContext` 中的多个管理器协同工作实现，包括 `SearchManager`（基础和高级搜索）、`semanticSearch`（语义向量搜索）和 `rankedSearch`（TF-IDF 排名搜索）。\n\n## 搜索架构\n\n### 分层搜索模型\n\n```mermaid\ngraph TD\n A[用户查询] --> B[搜索路由层]\n B --> C{查询类型判断}\n C -->|基础关键词| D[SearchManager
基础搜索]\n C -->|TF-IDF排名| E[rankedSearch
排名搜索]\n C -->|向量相似度| F[semanticSearch
语义搜索]\n C -->|时间范围| G[temporalSearch
时序搜索]\n C -->|复合条件| H[IntelligentSearch
智能搜索]\n \n D --> I[GraphStorage
数据存储]\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[结果聚合]\n J --> K[排序与去重]\n K --> L[返回结果]\n```\n\n### 核心组件\n\n| 组件名称 | 类型 | 功能描述 |\n|----------|------|----------|\n| `SearchManager` | 管理器 | 基础搜索、布尔搜索、模糊搜索的入口 |\n| `semanticSearch` | 访问器 | 基于嵌入向量的语义相似度搜索 |\n| `rankedSearch` | 访问器 | TF-IDF 算法的排名搜索 |\n| `SearchByTimeHandler` | 处理器 | 基于时间范围的时序搜索 |\n| `GraphStorage` | 存储层 | 底层图数据库查询接口 |\n\n## 搜索工具分类\n\n### 1. 基础搜索（7 个工具）\n\n基础搜索提供最常用的关键词和模式匹配功能。\n\n| 工具名称 | 功能 | 关键参数 |\n|----------|------|----------|\n| `search_entities` | 基础实体搜索 | `query`, `limit` |\n| `search_by_time` | 时间范围搜索 | `query`, `field`, `since`, `until` |\n| `search_by_relation` | 关系路径搜索 | `entity`, `relationType`, `depth` |\n| `search_by_tag` | 标签关联搜索 | `tags`, `matchAll` |\n| `fuzzy_search` | 模糊匹配搜索 | `query`, `threshold` |\n| `auto_search` | 自动选择最佳搜索 | `query` |\n| `boolean_search` | 布尔逻辑搜索 | `query`, `operators` |\n\n#### 时间范围搜索\n\n`search_by_time` 工具支持时序查询，允许用户限定搜索结果的时间范围：\n\n```typescript\n// toolHandlers.ts 中的实现\nsearch_by_time: async (ctx, args) => {\n const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');\n const options: { field: string; since?: Date; until?: Date } = {};\n // 支持 since/until 参数进行时间过滤\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:1-50]()\n\n#### 模糊搜索\n\n模糊搜索通过编辑距离算法容忍拼写错误，支持配置相似度阈值：\n\n- `threshold`：相似度阈值（0-1 之间）\n- 自动纠错和建议\n\n### 2. 智能搜索（3 个工具）\n\n智能搜索提供更高级的查询理解和结果优化能力。\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `intelligent_search` | 多层混合搜索，结合多种搜索策略 |\n| `analyze_query` | 查询分析，理解用户意图 |\n| `reflected_search` | 基于反思的搜索优化 |\n\n```mermaid\ngraph LR\n A[原始查询] --> B[analyze_query
查询分析]\n B --> C[查询重写]\n C --> D[intelligent_search
智能搜索]\n D --> E[reflected_search
反思优化]\n E --> F[最终结果]\n```\n\n### 3. 语义搜索（3 个工具）\n\n语义搜索基于嵌入向量（embeddings）实现语义级别的相似度匹配。\n\n| 工具名称 | 功能描述 | 嵌入提供者 |\n|----------|----------|------------|\n| `semantic_search` | 向量相似度搜索 | OpenAI / 本地模型 |\n| `hybrid_search` | 混合向量+关键词搜索 | 两者结合 |\n| `semantic_filter` | 基于语义的过滤 | 两者结合 |\n\n#### 环境配置\n\n```bash\n# 环境变量配置\nMEMORY_EMBEDDING_PROVIDER=openai|local|none # 嵌入提供者\nMEMORY_OPENAI_API_KEY=sk-xxx # OpenAI API 密钥\nMEMORY_EMBEDDING_MODEL=text-embedding-3-small # OpenAI 模型\n # 本地默认: Xenova/all-MiniLM-L6-v2\nMEMORY_AUTO_INDEX_EMBEDDINGS=false # 是否自动索引\n```\n\n资料来源：[CLAUDE.md:95-100]()\n\n### 4. 保存搜索（5 个工具）\n\n保存搜索允许用户存储和重用常用查询。\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `save_search` | 保存当前搜索条件 |\n| `list_saved_searches` | 列出所有保存的搜索 |\n| `execute_saved_search` | 执行已保存的搜索 |\n| `update_saved_search` | 更新保存的搜索 |\n| `delete_saved_search` | 删除保存的搜索 |\n\n保存的搜索存储在 `memory-saved-searches.jsonl` 文件中。\n\n## 搜索 API\n\n### 核心参数\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `query` | string | 是 | 搜索查询字符串 |\n| `limit` | number | 否 | 返回结果数量限制（默认 50） |\n| `offset` | number | 否 | 结果偏移量 |\n| `since` | string | 否 | ISO 8601 格式起始时间 |\n| `until` | string | 否 | ISO 8601 格式结束时间 |\n\n### 搜索工具定义示例\n\n```typescript\n// toolDefinitions.ts 中的时间搜索定义\n{\n name: 'search_by_time',\n description: 'Search for entities by time range and query string',\n inputSchema: {\n type: 'object',\n properties: {\n query: { type: 'string', description: 'Search query' },\n field: { type: 'string', description: 'Time field to search' },\n since: { type: 'string', description: 'Start time (ISO 8601)' },\n until: { type: 'string', description: 'End time (ISO 8601)' },\n },\n required: ['query'],\n },\n}\n```\n\n资料来源：[src/server/toolDefinitions.ts:200-220]()\n\n## 搜索流程\n\n### 完整搜索流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant H as ToolHandler\n participant SM as SearchManager\n participant SS as SemanticSearch\n participant RS as RankedSearch\n participant G as GraphStorage\n\n U->>H: search_entities(query)\n H->>SM: 路由到基础搜索\n \n alt 语义搜索模式\n SM->>SS: 执行向量搜索\n SS->>G: 查询嵌入向量\n G-->>SS: 相似度结果\n SS-->>SM: 语义匹配结果\n end\n \n alt 排名搜索模式\n SM->>RS: 执行TF-IDF排名\n RS->>G: 词频统计\n G-->>RS: 排名结果\n RS-->>SM: 排名匹配结果\n end\n \n SM->>SM: 结果聚合去重\n SM-->>H: 排序后结果\n H-->>U: 返回最终结果\n```\n\n### 查询验证流程\n\n所有搜索请求都经过以下验证流程：\n\n1. **参数校验**：使用 `validateWithSchema` 验证输入参数\n2. **类型检查**：确保数据类型符合 schema 定义\n3. **边界处理**：限制 `limit` 在 1-1000 范围内\n4. **错误处理**：返回格式化的错误信息\n\n```typescript\n// toolHandlers.ts 中的查询验证\nconst limit = args.limit !== undefined\n ? validateWithSchema(args.limit, z.number().int().min(1).max(1000), 'Invalid limit')\n : 50;\n```\n\n## 存储与索引\n\n### 存储位置\n\n搜索索引和数据文件位于项目根目录：\n\n| 文件类型 | 文件路径 | 描述 |\n|----------|----------|------|\n| 主数据 | `memory.jsonl` | 实体和关系数据 |\n| 保存搜索 | `memory-saved-searches.jsonl` | 预设查询 |\n| 标签别名 | `memory-tag-aliases.jsonl` | 标签同义词 |\n| SQLite | `memory.db` | 结构化查询（需配置） |\n\n### 索引策略\n\n| 索引类型 | 触发条件 | 配置项 |\n|----------|----------|--------|\n| 全文索引 | 实体创建时 | `MEMORY_AUTO_INDEX_EMBEDDINGS` |\n| 向量索引 | 嵌入生成后 | 自动 |\n| 标签索引 | 标签赋值时 | 自动 |\n| 时间索引 | 时间字段更新时 | 自动 |\n\n## 最佳实践\n\n### 1. 搜索策略选择\n\n```mermaid\ngraph TD\n A[开始搜索] --> B{知道确切实体名?}\n B -->|是| C{需要语义匹配?}\n B -->|否| D{需要模糊匹配?}\n \n C -->|是| E[semantic_search
语义搜索]\n C -->|否| F{需要排名?}\n \n D -->|是| G[fuzzy_search
模糊搜索]\n D -->|否| H{需要布尔逻辑?}\n \n F -->|是| I[ranked_search
排名搜索]\n F -->|否| J[search_entities
基础搜索]\n \n H -->|是| K[boolean_search
布尔搜索]\n H -->|否| L[auto_search
自动选择]\n```\n\n### 2. 性能优化建议\n\n- **批量搜索**：使用 `list_saved_searches` 预加载常用查询\n- **时间过滤**：在有明确时间范围时使用 `search_by_time`\n- **限制结果**：合理设置 `limit` 参数避免返回过多结果\n- **选择存储**：大数据量场景使用 SQLite 存储\n\n### 3. 常见查询模式\n\n| 场景 | 推荐工具 | 示例 |\n|------|----------|------|\n| 快速查找 | `auto_search` | 未知最佳搜索方式时 |\n| 精确匹配 | `search_entities` | 知道实体名称 |\n| 容忍错别字 | `fuzzy_search` | 用户输入可能有误 |\n| 学术研究 | `semantic_search` | 概念相似但表述不同 |\n| 时间追溯 | `search_by_time` | 查看某时间段的记忆 |\n\n## 总结\n\nmemory-mcp 的搜索能力通过分层架构实现了从基础到高级的完整搜索覆盖。基础搜索满足日常查询需求，智能搜索提供查询理解和优化，语义搜索实现深度的语义理解能力。开发者应根据具体使用场景选择合适的搜索工具，以获得最佳的用户体验和性能表现。\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[搜索能力](#page-search-capabilities), [工具参考手册](#page-tool-reference), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)\n \n\n# 高级功能\n\nmemory-mcp 是一个基于 Model Context Protocol 的知识图谱管理工具，提供超过 213 个工具，分布在 58 个类别中。Phase 15 和 Phase 16 引入的大量高级功能使该系统具备企业级特性，包括双时态有效性、并发控制、访问控制、程序化记忆、因果推理等能力。\n\n## 1. 版本演进与功能概览\n\nmemory-mcp 的高级功能通过两个主要版本迭代实现：\n\n| 版本 | 版本号 | 新增工具数 | 核心功能 |\n|------|--------|-----------|---------|\n| Phase 15 | v12.2.0 | 23 | 双时态有效性、OCC、RBAC、程序化记忆、主动检索、因果推理、世界模型 |\n| Phase 16 | v12.3.0 | 53 | do_not_remember 排除、决策理由与 ADR 双写、结构化项目上下文、启发式指南、ToolCallObserver 管道、观察去重、拼写纠正 |\n\n资料来源：[CLAUDE.md:3-10]()\n\n## 2. 记忆衰减与优先级管理\n\n系统提供基于时间的记忆重要性衰减机制，用于自动管理长期记忆的价值。\n\n### 2.1 衰减工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `run_decay_cycle` | 对所有 agent 记忆执行单次时间衰减，返回衰减和遗忘的记忆数量 |\n| `get_decayed_memories` | 列出重要性降至阈值以下的记忆（不同于 `get_stale_entities` 使用新鲜度时间戳） |\n| `forget_weak_memories` | 批量删除低于衰减阈值的记忆（不同于 `forget_memory` 的内容匹配或 `archive_entities` 的条件移动） |\n\n资料来源：[src/server/toolDefinitions.ts:衰减工具定义]()\n\n### 2.2 衰减流程\n\n```mermaid\ngraph TD\n A[运行 run_decay_cycle] --> B{计算记忆重要性}\n B --> C{是否低于阈值?}\n C -->|是| D[标记为弱记忆]\n C -->|否| E[保留记忆]\n D --> F[get_decayed_memories 查询]\n F --> G{forget_weak_memories}\n G -->|dryRun=true| H[预览待删除列表]\n G -->|dryRun=false| I[批量删除]\n```\n\n### 2.3 阈值配置\n\n- `threshold`：重要性阈值，低于此值将被遗忘（默认 0.1）\n- `maxCount`：单次操作最大遗忘数量\n- `dryRun`：预览模式，不执行实际删除\n\n资料来源：[src/server/toolDefinitions.ts:衰减工具参数]()\n\n## 3. 访问控制与治理\n\nPhase 15 引入的 RBAC 功能提供细粒度的访问控制。\n\n### 3.1 治理策略\n\n| 操作 | 说明 |\n|------|------|\n| `set_governance_policy` | 设置全局治理策略，控制创建、更新、删除权限 |\n| `audit_query` | 查询审计日志，支持按操作类型、agentId、实体名称、时间范围过滤 |\n\n资料来源：[src/server/toolHandlers.ts:治理处理器]()\n\n### 3.2 审计过滤器\n\n```typescript\ninterface AuditFilter {\n operation?: 'create' | 'update' | 'delete' | 'merge' | 'archive';\n agentId?: string;\n entityName?: string;\n fromTime?: string; // 注意：使用 fromTime/toTime 而非 since/until\n toTime?: string;\n}\n```\n\n### 3.3 治理架构\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Tool Call]\n B --> C{Governance Policy Check}\n C -->|canCreate| D[允许创建]\n C -->|canUpdate| E[允许更新]\n C -->|canDelete| F[允许删除]\n C -->|禁止| G[返回权限错误]\n D --> H[写入审计日志]\n E --> H\n F --> H\n H --> I[Audit Log]\n```\n\n资料来源：[src/server/toolHandlers.ts:audit_query 实现]()\n\n## 4. 工件管理系统\n\nArtifacts 是系统用于存储工具输出、代码片段、API 响应等内容的实体。\n\n### 4.1 工件类型\n\n| 类型标识 | 用途 |\n|---------|------|\n| `tool_output` | 工具执行输出 |\n| `code_snippet` | 代码片段 |\n| `api_response` | API 响应数据 |\n| `search_result` | 搜索结果 |\n| `file_content` | 文件内容 |\n| `user_input` | 用户输入 |\n\n资料来源：[src/server/toolDefinitions.ts:工件类型定义]()\n\n### 4.2 工件管理工具\n\n| 工具 | 功能 |\n|------|------|\n| `create_artifact` | 创建带稳定自动生成 ref 的工件实体 |\n| `get_artifact` | 通过 ref 或实体名称检索工件 |\n| `list_artifacts` | 列出工件，支持按 toolName、artifactType、sessionId 过滤 |\n\n### 4.3 工件创建参数\n\n```typescript\n{\n content: string; // 必填：存储为实体观察的内容\n toolName: string; // 必填：生成此工件的来源工具名\n artifactType: ArtifactType; // 必填：工件分类\n description?: string; // 可选：人类可读描述\n sessionId?: string; // 可选：会话上下文，用于分组相关工件\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:工件处理器]()\n\n## 5. 上下文压缩工具\n\n`compress-for-context` 工具用于将大型文件压缩至 LLM 上下文窗口可接受的大小。\n\n### 5.1 压缩级别\n\n| 级别 | 说明 |\n|------|------|\n| `light` | 最小改动，保持可读性 |\n| `medium` | 平衡大小与可读性（默认） |\n| `aggressive` | 最大压缩，可能降低可读性 |\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:压缩级别定义]()\n\n### 5.2 支持格式\n\n- JSON、YAML、Markdown、CSV、TSV\n- Text、Log、TypeScript、JavaScript\n- XML、HTML\n\n### 5.3 使用示例\n\n```bash\n# 单文件压缩\nnode compress-for-context.js data.json\nnode compress-for-context.js README.md -l aggressive\n\n# 批量压缩\nnode compress-for-context.js -b -p \"*.json\" ./src\nnode compress-for-context.js -b -r -p \"*.md\" ./docs\n\n# 解压还原\nnode compress-for-context.js -d input.compact\n```\n\n### 5.4 压缩算法\n\n工具使用类 CTON（Concise Textual Notation）风格的压缩：\n\n- 移除多余空白字符\n- 缩写键名\n- 提取图例（Legend）映射完整名称\n- 批量处理时按缩写长度降序替换以避免冲突\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:压缩实现]()\n\n## 6. 文件分块工具\n\n`chunking-for-files` 工具将大型文件分割为可管理的块。\n\n### 6.1 命令\n\n| 命令 | 功能 |\n|------|------|\n| `split` | 将文件分割为多个块 |\n| `merge` | 合并块文件还原原文件 |\n| `status` | 显示分块状态 |\n\n### 6.2 分块元数据\n\n```typescript\ninterface Manifest {\n version: '1.1.0';\n sourceFile: string; // 原始文件路径\n sourceHash: string; // 原始文件哈希\n createdAt: string; // ISO 时间戳\n fileType: string; // 文件类型\n splitLevel: string; // 分割级别\n chunks: Chunk[]; // 块信息数组\n}\n\ninterface Chunk {\n index: number;\n filename: string;\n title: string;\n startLine: number;\n endLine: number;\n lineCount: number;\n hash: string;\n modified: boolean;\n}\n```\n\n资料来源：[tools/chunking-for-files/chunking-for-files.ts:分块实现]()\n\n### 6.3 分块流程\n\n```mermaid\ngraph TD\n A[输入文件] --> B[解析文件结构]\n B --> C{文件类型}\n C -->|Markdown| D[按标题级别分块]\n C -->|TypeScript| E[按类型声明/函数分块]\n C -->|其他| F[按行数/语义分块]\n D --> G[生成 Manifest]\n E --> G\n F --> G\n G --> H[写入块文件]\n H --> I[生成 manifest.json]\n```\n\n## 7. Phase 16 新增特性 (v12.3.0)\n\n### 7.1 功能分类\n\n| 类别 | 工具数 | 描述 |\n|------|--------|------|\n| `do_not_remember` 排除 | 5 | 主动排除特定记忆被检索 |\n| 决策理由与 ADR 双写 | 10 | 同时生成决策理由和架构决策记录 |\n| 结构化项目上下文 | 12 | 提取和管理项目结构化元数据 |\n| 启发式指南 | 10 | 基于规则的推荐和指导 |\n| ToolCallObserver 管道 | 11 | 工具调用观察和监控 |\n| 观察去重 | 2 | 自动去除重复观察 |\n| 拼写纠正 | 3 | 搜索和输入的拼写纠正 |\n\n资料来源：[CLAUDE.md:6-10]()\n\n### 7.2 ToolCallObserver 管道\n\n该管道允许观察和记录工具调用模式，支持：\n\n- 工具使用频率统计\n- 调用链追踪\n- 异常模式检测\n- 性能监控\n\n### 7.3 观察去重机制\n\n自动检测并合并语义相同的观察，避免知识图谱中的冗余信息。\n\n### 7.4 拼写纠正\n\n支持三种语言的拼写纠正功能，提升搜索准确性：\n\n- 搜索查询的拼写纠正\n- 实体名称的拼写纠正\n- 观察内容的拼写纠正\n\n## 8. 依赖图生成工具\n\n`create-dependency-graph` 工具扫描代码库并生成依赖文档。\n\n### 8.1 功能特性\n\n- 扫描 `src/` 下所有 TypeScript 文件\n- 解析导入和导出\n- 检测循环依赖\n- 生成统计信息\n- 输出 Markdown 和 JSON 两种格式\n\n### 8.2 生成的文档结构\n\n```markdown\ndocs/architecture/\n├── DEPENDENCY_GRAPH.md # 人类可读文档\n└── dependency-graph.json # 机器可读数据\n```\n\n### 8.3 输出内容\n\n| 内容 | 说明 |\n|------|------|\n| 外部依赖 | npm 包依赖 |\n| Node.js 内置依赖 | fs, path 等 |\n| 内部依赖 | 相对路径导入 |\n| 循环依赖分析 | 运行时和类型级别 |\n| 导出统计 | 类、接口、函数、常量数量 |\n\n资料来源：[tools/create-dependency-graph/README.md:功能说明]()\n\n## 9. 存储与迁移\n\n### 9.1 存储格式\n\n| 格式 | 文件位置 | 说明 |\n|------|---------|------|\n| JSONL | `memory.jsonl` | 项目根目录 |\n| SQLite | `memory.db` | 设置 `MEMORY_STORAGE_TYPE=sqlite` |\n\n### 9.2 迁移工具\n\n`migrate-from-jsonl-to-sqlite` 工具支持两种格式的双向转换：\n\n```bash\n# 基本用法\nmigrate-from-jsonl-to-sqlite --from --to \n\n# 详细输出\nmigrate-from-jsonl-to-sqlite --from source.jsonl --to target.db --verbose\n```\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:迁移实现]()\n\n## 10. 环境变量配置\n\n| 变量 | 描述 | 默认值 |\n|------|------|--------|\n| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl` |\n| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` |\n| `MEMORY_EMBEDDING_PROVIDER` | 向量化提供者 | `none` |\n| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — |\n| `MEMORY_EMBEDDING_MODEL` | 向量化模型 | `text-embedding-3-small` |\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 自动索引 | `false` |\n\n资料来源：[CLAUDE.md:环境变量配置]()\n\n## 11. 贡献与扩展指南\n\n### 11.1 添加新工具流程\n\n```mermaid\ngraph TD\n A[定义工具架构] --> B[添加 schema 到 toolDefinitions.ts]\n B --> C[添加处理器到 toolHandlers.ts]\n C --> D[验证参数和错误处理]\n D --> E[添加端到端测试]\n E --> F[更新文档]\n```\n\n### 11.2 代码规范\n\n- 遵循 TypeScript 最佳实践\n- 使用有意义的变量名\n- 公共方法添加 JSDoc 注释\n- 保持函数小而专注\n- 一致缩进（2 空格）\n\n资料来源：[CONTRIBUTING.md:代码风格指南]()\n\n---\n\n\n\n## 工具参考手册\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [搜索能力](#page-search-capabilities), [层级嵌套](#page-hierarchical-nesting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)\n- [tools/chunking-for-files/chunking-for-files.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/chunking-for-files/chunking-for-files.ts)\n- [tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)\n- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)\n \n\n# 工具参考手册\n\n本文档是 Memory MCP 项目的完整工具参考手册，详细介绍所有 MCP（Model Context Protocol）工具的定义、参数、返回值以及使用方法。\n\n## 概述\n\nMemory MCP 提供了一套基于 Model Context Protocol 的工具集，用于与知识图谱进行交互。该项目包含 **213 个工具**，分布在 **58 个分类**中，涵盖了知识图谱的创建、查询、更新、压缩、导入导出等完整生命周期管理。\n\n### 工具系统架构\n\n工具系统采用分层架构设计：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[MCPServer]\n B --> C[toolHandlers.ts]\n C --> D[memoryjs ManagerContext]\n D --> E[EntityManager]\n D --> F[RelationManager]\n D --> G[ObservationManager]\n D --> H[SearchManager]\n D --> I[TagManager]\n D --> J[其他管理器]\n J --> K[SQLiteStorage]\n J --> L[JSONLStorage]\n```\n\n核心组件包括：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 工具定义 | `src/server/toolDefinitions.ts` | 定义所有工具的 JSON Schema |\n| 工具处理器 | `src/server/toolHandlers.ts` | 实现工具的业务逻辑 |\n| 管理器上下文 | `@danielsimonjr/memoryjs` | 提供底层数据操作接口 |\n\n资料来源：[CLAUDE.md:1-10]()\n\n### 工具分类总览\n\n| 分类 | 工具数量 | 核心功能 |\n|------|----------|----------|\n| 实体 (Entity) | 4 | 图谱节点的 CRUD 操作 |\n| 关系 (Relation) | 2 | 实体间的有向边管理 |\n| 观察 (Observation) | 3 | 附加到实体的知识事实 |\n| 搜索 (Search) | 7 | 基础、排名、布尔、模糊搜索 |\n| 智能搜索 (Intelligent Search) | 3 | 混合多层、查询分析、反思搜索 |\n| 语义搜索 (Semantic Search) | 3 | OpenAI 或本地模型的嵌入相似度 |\n| 保存的搜索 (Saved Searches) | 5 | 存储和重用频繁查询 |\n| 标签管理 (Tag Management) | 6 | 标签及其重要性评分 |\n| 标签别名 (Tag Aliases) | 5 | 标签同义词管理 |\n| 层级结构 (Hierarchy) | 9 | 父子树结构和子树遍历 |\n| 图算法 (Graph Algorithms) | 4 | BFS/DFS 路径发现、中心性、连通分量 |\n| 分析 (Analytics) | 2 | 图谱统计和完整性验证 |\n| 压缩 (Compression) | 4 | 重复检测、合并、自动压缩、归档 |\n| 导入/导出 (Import/Export) | 2 | 多种格式的数据交换 |\n\n资料来源：[CLAUDE.md:18-33]()\n\n## 核心实体工具\n\n### 创建实体 (create_entity)\n\n在知识图谱中创建新的实体节点。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| name | string | 是 | 实体名称 |\n| entityType | string | 否 | 实体类型，用于分类 |\n| observations | string[] | 否 | 初始观察/知识列表 |\n| tags | string[] | 否 | 关联标签 |\n| importance | number | 否 | 重要性分数 (0-1) |\n\n**返回值：** 创建成功的实体对象，包含自动生成的唯一引用 ID\n\n### 获取实体 (get_entity)\n\n通过名称或引用 ID 检索实体信息。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用或名称 |\n\n### 更新实体 (update_entity)\n\n修改现有实体的属性。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n| name | string | 否 | 新名称 |\n| entityType | string | 否 | 新类型 |\n| tags | string[] | 否 | 新的标签列表 |\n\n### 删除实体 (delete_entity)\n\n从知识图谱中移除实体及其关联的关系和观察。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 要删除的实体引用 |\n\n## 关系工具\n\n### 创建关系 (create_relation)\n\n在两个实体之间创建有向关系边。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| from | string | 是 | 源实体引用 |\n| to | string | 是 | 目标实体引用 |\n| relationType | string | 是 | 关系类型（如 \"depends_on\"、\"implements\"） |\n| bidirectional | boolean | 否 | 是否双向关系（默认 false） |\n\n### 获取关系 (get_relations)\n\n查询满足特定条件的实体关系。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| from | string | 否 | 源实体过滤 |\n| to | string | 否 | 目标实体过滤 |\n| relationType | string | 否 | 关系类型过滤 |\n\n## 搜索工具\n\n### 基础搜索 (search_entities)\n\n在知识图谱中搜索实体。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 搜索查询词 |\n| limit | number | 否 | 结果上限（默认 10） |\n| entityType | string | 否 | 按类型过滤 |\n\n### 排名搜索 (search_entities_ranked)\n\n基于 TF-IDF 算法的加权排名搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 搜索查询 |\n| limit | number | 否 | 结果上限 |\n| boostRecent | boolean | 否 | 是否提升近期结果 |\n\n### 模糊搜索 (search_entities_fuzzy)\n\n支持拼写容错的模糊匹配搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 可能包含拼写错误的查询 |\n| threshold | number | 否 | 匹配阈值（0-1，默认 0.6） |\n\n### 布尔搜索 (search_entities_boolean)\n\n支持 AND、OR、NOT 运算符的布尔搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 布尔表达式（如 \"AI AND (machine OR deep)\"） |\n\n### 语义搜索 (semantic_search)\n\n基于向量嵌入的语义相似度搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 自然语言查询 |\n| limit | number | 否 | 返回结果数 |\n| provider | string | 否 | 嵌入提供者（openai/local/none） |\n\n资料来源：[CLAUDE.md:26-27]()\n\n## 标签管理工具\n\n### 添加标签 (add_tags)\n\n为实体添加一个或多个标签。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n| tags | string[] | 是 | 要添加的标签列表 |\n\n### 移除标签 (remove_tags)\n\n从实体移除指定标签。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n| tags | string[] | 是 | 要移除的标签列表 |\n\n### 获取标签 (get_tags)\n\n获取实体的所有标签。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n\n### 列出所有标签 (list_tags)\n\n返回知识图谱中的所有标签及其使用统计。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| limit | number | 否 | 返回数量上限 |\n\n### 标签别名管理\n\n用于管理标签的同义词和别名关系。\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| create_tag_alias | 创建标签别名映射 |\n| get_tag_alias | 获取标签的别名 |\n| list_tag_aliases | 列出所有标签别名 |\n| delete_tag_alias | 删除标签别名 |\n| resolve_tag_alias | 将别名解析为规范标签 |\n\n## 图算法工具\n\n### 路径发现 (find_path)\n\n使用 BFS 或 DFS 算法查找两个实体之间的路径。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| from | string | 是 | 起始实体 |\n| to | string | 是 | 目标实体 |\n| algorithm | string | 否 | BFS 或 DFS（默认 BFS） |\n| maxDepth | number | 否 | 最大深度限制 |\n\n### 连通分量 (get_connected_components)\n\n识别知识图谱中的连通分量。\n\n### 中心性分析 (calculate_centrality)\n\n计算实体的度中心性或介数中心性。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| entityRef | string | 是 | 实体引用 |\n| type | string | 否 | 中心性类型（degree/betweenness） |\n\n## 导入导出工具\n\n### 导出图谱 (export_graph)\n\n将知识图谱导出为多种格式。\n\n**支持的格式：**\n\n| 格式 | 描述 |\n|------|------|\n| json | 标准 JSON 格式 |\n| jsonl | JSON Lines 格式 |\n| xml | XML 格式 |\n| markdown | Markdown 格式 |\n| csv | CSV 表格格式 |\n| ttl | Turtle RDF 格式 |\n| json-ld | JSON-LD 格式 |\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| format | string | 是 | 输出格式 |\n| includeObservations | boolean | 否 | 是否包含观察数据 |\n| redactPii | boolean | 否 | 是否进行 PII 脱敏 |\n\n资料来源：[CLAUDE.md:32]()\n\n### 导入图谱 (import_graph)\n\n从外部文件导入知识图谱数据。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| source | string | 是 | 导入源（路径或内容） |\n| format | string | 是 | 数据格式 |\n| mergeStrategy | string | 否 | 合并策略（replace/merge/skip） |\n\n## 压缩与归档工具\n\n### 检测重复 (find_duplicates)\n\n识别知识图谱中的重复或高度相似的实体。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| threshold | number | 否 | 相似度阈值（默认 0.85） |\n\n### 合并实体 (merge_entities)\n\n将多个相似实体合并为一个。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| refs | string[] | 是 | 要合并的实体引用列表 |\n| keepRef | string | 否 | 保留的主实体引用 |\n\n### 运行压缩 (run_compression)\n\n自动压缩知识图谱，移除冗余数据。\n\n### 归档旧数据 (archive_old_entities)\n\n将长期未访问的实体移至归档存储。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| daysOld | number | 否 | 天数阈值（默认 90） |\n| archiveType | string | 否 | 归档类型标签 |\n\n## 工件管理工具\n\n用于存储和管理工具输出、代码片段、API 响应等工件。\n\n### 创建工件 (create_artifact)\n\n创建工件实体并获取稳定的自动生成引用。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| content | string | 是 | 工件内容 |\n| toolName | string | 是 | 生成工件的源工具名称 |\n| artifactType | string | 是 | 工件类型枚举 |\n| description | string | 否 | 人类可读描述 |\n| sessionId | string | 否 | 会话上下文标识 |\n\n**artifactType 枚举值：**\n\n| 类型 | 描述 |\n|------|------|\n| tool_output | 工具执行输出 |\n| code_snippet | 代码片段 |\n| api_response | API 响应内容 |\n| search_result | 搜索结果 |\n| file_content | 文件内容 |\n| user_input | 用户输入 |\n\n### 获取工件 (get_artifact)\n\n通过引用或实体名称检索工件。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 工件引用或实体名称 |\n\n### 列出工件 (list_artifacts)\n\n列出满足过滤条件的工件。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| toolName | string | 否 | 按工具名称过滤 |\n| artifactType | string | 否 | 按类型过滤 |\n| since | string | 否 | ISO 8601 时间过滤 |\n\n## 治理与审计工具\n\n### 设置治理策略 (set_governance_policy)\n\n配置实体的创建、更新、删除权限策略。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| entityType | string | 否 | 应用策略的实体类型 |\n| canCreate | boolean | 是 | 是否允许创建 |\n| canUpdate | boolean | 是 | 是否允许更新 |\n| canDelete | boolean | 是 | 是否允许删除 |\n\n### 审计查询 (audit_query)\n\n查询实体的操作历史日志。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| operation | string | 否 | 操作类型（create/update/delete/merge/archive） |\n| agentId | string | 否 | 代理 ID 过滤 |\n| entityName | string | 否 | 实体名称过滤 |\n| since | string | 否 | 开始时间 |\n| until | string | 否 | 结束时间 |\n| limit | number | 否 | 结果上限（默认 50） |\n\n## 衰减与显著性工具\n\n### 运行衰减周期 (run_decay_cycle)\n\n执行基于时间的显著性衰减计算。\n\n### 获取衰减记忆 (get_decayed_memories)\n\n列出重要性已降至阈值以下的记忆。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| threshold | number | 否 | 重要性阈值（默认 0.1） |\n\n### 遗忘弱记忆 (forget_weak_memories)\n\n批量删除重要性低于衰减阈值的记忆。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| threshold | number | 是 | 重要性阈值 |\n| maxCount | number | 否 | 最大遗忘数量 |\n| dryRun | boolean | 否 | 是否为试运行模式 |\n\n## 时间查询工具\n\n### 按时间搜索 (search_by_time)\n\n基于时间范围查询知识图谱数据。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 查询内容 |\n| startTime | string | 否 | 开始时间 |\n| endTime | string | 否 | 结束时间 |\n| field | string | 否 | 查询字段（created/updated/observed） |\n\n## 独立工具集\n\n项目还包含一组独立的命令行工具，位于 `tools/` 目录下。\n\n### 文件分块工具 (chunking-for-files)\n\n用于将大型文件分割为适合编辑的块，或合并已分割的文件块。\n\n```bash\n# 分割文件\nchunker split [options]\n\n# 合并块\nchunker merge [options]\n\n# 查看状态\nchunker status \n```\n\n**分割选项：**\n\n| 选项 | 描述 |\n|------|------|\n| -o, --output | 输出目录 |\n| -l, --max-lines | 每块最大行数（默认 500） |\n| --by-structure | 按代码结构分割（类、函数等） |\n| --dry-run | 预览分割结果 |\n\n资料来源：[tools/chunking-for-files/chunking-for-files.ts:1-50]()\n\n### 上下文压缩工具 (compress-for-context)\n\n使用 CTON（Context-optimized Notation）压缩格式压缩文件以适应 LLM 上下文窗口。\n\n```bash\n# 单文件压缩\nnode compress-for-context.js data.json\n\n# 批量压缩\nnode compress-for-context.js -b -p \"*.json\" ./src\n\n# 解压缩\nnode compress-for-context.js -d file.compact.json\n```\n\n**压缩级别：**\n\n| 级别 | 描述 |\n|------|------|\n| light | 最小化改动，保留可读性 |\n| medium | 平衡压缩率和可读性（默认） |\n| aggressive | 最大压缩，可能降低可读性 |\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:1-40]()\n\n### 存储迁移工具 (migrate-from-jsonl-to-sqlite)\n\n在 JSONL 和 SQLite 存储格式之间迁移数据。\n\n```bash\n# 从 JSONL 迁移到 SQLite\nmigrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db\n\n# 从 SQLite 迁移到 JSONL\nmigrate-from-jsonl-to-sqlite --from memory.db --to memory.jsonl\n\n# 详细输出模式\nmigrate-from-jsonl-to-sqlite -f source.jsonl -t target.db -v\n```\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30]()\n\n### 依赖图生成工具 (create-dependency-graph)\n\n分析 TypeScript 项目并生成依赖关系文档。\n\n```bash\n# 通过 npm 脚本运行（推荐）\nnpm run docs:deps\n\n# 直接使用 tsx 运行\nnpx tsx tools/create-dependency-graph.ts\n```\n\n**输出文件：**\n\n- `docs/architecture/DEPENDENCY_GRAPH.md` - Markdown 格式文档\n- `docs/architecture/dependency-graph.json` - JSON 数据结构\n\n**生成内容包括：**\n\n- 外部依赖（npm 包）\n- Node.js 内置依赖\n- 内部依赖（相对导入）\n- 导出的类、接口、函数、常量\n- 循环依赖分析\n- Mermaid 可视化图表\n- 统计摘要\n\n资料来源：[tools/create-dependency-graph/README.md:1-50]()\n\n## 环境变量配置\n\n工具行为可通过以下环境变量配置：\n\n| 变量 | 描述 | 默认值 |\n|------|------|--------|\n| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl`（当前目录） |\n| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` |\n| `MEMORY_EMBEDDING_PROVIDER` | 嵌入提供者 | `none` |\n| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — |\n| `MEMORY_EMBEDDING_MODEL` | 嵌入模型名称 | `text-embedding-3-small` / `Xenova/all-MiniLM-L6-v2` |\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 自动索引嵌入 | `false` |\n\n资料来源：[CLAUDE.md:45-52]()\n\n## 添加工具流程\n\n在项目中添加新的 MCP 工具需要以下步骤：\n\n```mermaid\ngraph LR\n A[定义工具 Schema] --> B[实现工具处理器]\n B --> C[添加 E2E 测试]\n C --> D[更新文档]\n \n A1[toolDefinitions.ts] --> |同一分类区域| A\n B1[toolHandlers.ts] --> |handler 逻辑| B\n```\n\n### 步骤 1：定义工具 Schema\n\n在 `src/server/toolDefinitions.ts` 的适当分类区域添加 JSON Schema 定义：\n\n```typescript\n{\n name: 'tool_name',\n description: '工具功能描述',\n inputSchema: {\n type: 'object',\n properties: {\n paramName: { type: 'string', description: '参数描述' }\n },\n required: ['paramName'],\n additionalProperties: false,\n },\n},\n```\n\n### 步骤 2：实现工具处理器\n\n在 `src/server/toolHandlers.ts` 中添加工具处理器：\n\n```typescript\ntool_name: async (ctx, args) => {\n // 1. 验证参数\n const param = validateWithSchema(args.paramName, z.string(), 'Invalid param');\n \n // 2. 调用管理器方法\n const result = await getManager(ctx).method(param);\n \n // 3. 返回格式化响应\n return formatToolResponse(result);\n},\n```\n\n### 步骤 3：添加测试\n\n在 `tests/e2e/tools/` 目录下添加端到端测试。\n\n资料来源：[CLAUDE.md:35-44]()\n\n## 工具响应格式\n\n所有工具返回遵循 MCP 协议的统一响应格式：\n\n```typescript\n// 成功响应\n{\n content: [{ type: 'text', text: JSON.stringify(result) }]\n}\n\n// 错误响应\n{\n isError: true,\n content: [{ type: 'text', text: errorMessage }]\n}\n```\n\n### 格式化辅助函数\n\n| 函数 | 用途 |\n|------|------|\n| `formatToolResponse()` | 格式化工具返回数据为 MCP 响应 |\n| `formatTextResponse()` | 格式化纯文本响应 |\n| `validateWithSchema()` | 使用 Zod schema 验证输入参数 |\n\n## 错误处理\n\n工具调度采用统一的错误处理机制：\n\n```mermaid\ngraph TD\n A[工具调用] --> B[handleToolCall]\n B --> C{执行中异常?}\n C -->|是| D[捕获异常]\n D --> E[返回 MCP 错误响应]\n C -->|否| F[返回正常响应]\n \n E --> G{isError 字段}\n F --> G\n```\n\n`handleToolCall` 会捕获处理器中的所有异常，并将其作为 MCP 格式的错误响应返回。调试时可检查响应的 `isError` 字段。\n\n资料来源：[CLAUDE.md:57-59]()\n\n## 存储后端\n\n工具支持两种存储后端：\n\n### JSONL 存储\n\n- 数据文件：`memory.jsonl`、`memory-saved-searches.jsonl`、`memory-tag-aliases.jsonl`\n- 位于项目根目录\n- 适合小型部署和版本控制\n\n### SQLite 存储\n\n- 数据文件：`memory.db`\n- 设置 `MEMORY_STORAGE_TYPE=sqlite` 启用\n- 使用 `better-sqlite3` 实现原生性能\n- 适合生产环境和大规模数据\n\n资料来源：[CLAUDE.md:12-16]()\n\n## 版本历史\n\n| 版本 | 描述 |\n|------|------|\n| v12.3.0 (Phase 16) | 添加 53 个工具，涵盖 do_not_remember、决策理由、工具能力等 |\n| v12.2.0 (Phase 15) | 添加 23 个工具，支持双时态有效性、OCC、RBAC、程序性记忆等 |\n| v2.1.0 | memoryjs 核心库版本，支持完整工具集 |\n\n资料来源：[CLAUDE.md:3-7]()\n\n---\n\n本参考手册涵盖了 Memory MCP 的所有工具定义和使用方法。如需更多信息，请参考项目文档或查看源代码。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：danielsimonjr/memory-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | release_recency=unknown\n\n\n",
"markdown_key": "memory-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1093926095",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/danielsimonjr/memory-mcp"
},
{
"evidence_id": "art_fc807c0c51ad4a7c841e0addd977c506",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/danielsimonjr/memory-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "memory-mcp 说明书",
"toc": [
"https://github.com/danielsimonjr/memory-mcp 项目说明书",
"目录",
"项目介绍",
"概述",
"技术架构",
"工具体系",
"存储方案",
"基本用法",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @danielsimonjr/memory-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @danielsimonjr/memory-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install -g @danielsimonjr/memory-mcp` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npx @danielsimonjr/memory-mcp` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `git clone https://github.com/danielsimonjr/memory-mcp.git` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npm install && npm run build` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install # Install dependencies` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npm install # Install all dependencies` 证据：`CLAUDE.md` Claim：`clm_0008` supported 0.86\n- `npx vitest run tests/e2e/tools/entity-tools.test.ts` 证据：`CLAUDE.md` Claim：`clm_0009` supported 0.86\n- `npx vitest run -t \"should create entities\"` 证据：`CLAUDE.md` Claim：`clm_0010` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`CLAUDE.md`, `README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`CLAUDE.md`, `README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`CHANGELOG.md`, `CLAUDE.md`, `README.md`, `docs/planning/PHASE_4_PERFORMANCE_CACHING_PLAN.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- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0012` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`CLAUDE.md`, `README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：248\n- 重要文件覆盖：40/248\n- 证据索引条目：80\n- 角色 / Skill 条目：68\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请基于 @danielsimonjr/memory-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @danielsimonjr/memory-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 @danielsimonjr/memory-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 68 个角色 / Skill / 项目文档条目。\n\n- **Documentation Index**（project_doc）：Welcome to the Enhanced Memory MCP documentation! This directory contains comprehensive documentation for developers, users, and contributors. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **Memory MCP Server**（project_doc）：! Version https://img.shields.io/badge/version-12.3.0-blue.svg https://github.com/danielsimonjr/memory-mcp ! NPM https://img.shields.io/npm/v/@danielsimonjr/memory-mcp.svg https://www.npmjs.com/package/@danielsimonjr/memory-mcp ! License https://img.shields.io/badge/license-MIT-green.svg LICENSE ! MCP https://img.shields.io/badge/MCP-1.0-purple.svg https://modelcontextprotocol.io ! TypeScript https://img.shields.io/… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **DeepThinking MCP Tools**（project_doc）：This directory contains utility scripts for maintaining the DeepThinking MCP codebase. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tools/create-dependency-graph/README.md`\n- **Memory MCP Migration Tool**（project_doc）：Migrate knowledge graph data between JSONL and SQLite storage formats for the Memory MCP server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tools/migrate-from-jsonl-to-sqlite/README.md`\n- **Contributing to Enhanced Memory MCP**（project_doc）：Contributing to Enhanced Memory MCP 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Brutally Honest Codebase Analysis — Final Cut**（project_doc）：Brutally Honest Codebase Analysis — Final Cut 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/analysis/BRUTALLY_HONEST_ANALYSIS.md`\n- **Comprehensive Codebase Review: memory-mcp**（project_doc）：Comprehensive Codebase Review: memory-mcp 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/analysis/Comprehensive_Codebase_Review.md`\n- **Implementation Verification Report**（project_doc）：Date: 2026-01-01 Original Analysis: 2026-01-01 Version Before: 0.11.5 / 0.59.0 Version After: 8.50.24 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/analysis/IMPLEMENTATION_VERIFICATION.md`\n- **Memory MCP - API Reference**（project_doc）：Version : 12.2.0 Last Updated : 2026-04-26 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/API.md`\n- **Memory MCP - System Architecture**（project_doc）：Version : 12.2.0 Last Updated : 2026-04-26 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/ARCHITECTURE.md`\n- **Memory MCP - Component Reference**（project_doc）：Version : 12.2.0 Last Updated : 2026-04-26 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/COMPONENTS.md`\n- **Memory MCP - Data Flow Documentation**（project_doc）：Memory MCP - Data Flow Documentation 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/DATAFLOW.md`\n- **@danielsimonjr/memory-mcp - Dependency Graph**（project_doc）：@danielsimonjr/memory-mcp - Dependency Graph 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/DEPENDENCY_GRAPH.md`\n- **Memory MCP Server - Project Overview**（project_doc）：Memory MCP Server - Project Overview 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/OVERVIEW.md`\n- **Unused Files and Exports Analysis**（project_doc）：- Potentially unused files : 0 - Potentially unused exports : 9 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/unused-analysis.md`\n- **Context/Token Optimization Refactoring Plan**（project_doc）：Context/Token Optimization Refactoring Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development/CONTEXT_OPTIMIZATION_PLAN.md`\n- **Implementation Plan - Memory MCP Server**（project_doc）：Implementation Plan - Memory MCP Server 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development/IMPLEMENTATION_PLAN.md`\n- **Index.ts Refactoring - Detailed Implementation Tasks**（project_doc）：Index.ts Refactoring - Detailed Implementation Tasks 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development/IMPLEMENTATION_TASKS.md`\n- **Memory MCP Improvement Plan**（project_doc）：Memory MCP Improvement Plan Comprehensive Roadmap for Advanced Features 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development/IMPROVEMENT_PLAN.md`\n- **Index.ts Refactoring Plan**（project_doc）：This document outlines a comprehensive plan to refactor the monolithic src/memory/index.ts file 4,187 lines into a modular, maintainable architecture. The refactoring will improve code organization, testability, maintainability, and developer experience while preserving all existing functionality. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development/REFACTORING_PLAN.md`\n- **Memory MCP Development Workflow**（project_doc）：Updated 2026-04-26 for v12.2.0. The previous version of this file referenced a pre-Phase-13 layout and a 15-tool count — both obsolete. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/development/WORKFLOW.md`\n- **Memory Archiving Guide**（project_doc）：Memory Archiving Guide Managing Memory Lifecycle and Long-Term Storage 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/ARCHIVING.md`\n- **Memory Compression Guide**（project_doc）：Memory Compression Guide Brotli Compression, Response Compression, and Entity Deduplication 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/COMPRESSION.md`\n- **Hierarchical Nesting Guide**（project_doc）：Hierarchical Nesting Guide Organizing Knowledge with Parent-Child Relationships 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/HIERARCHY.md`\n- **Migration Guide: v0.7.0 → v0.8.0**（project_doc）：Migration Guide: v0.7.0 → v0.8.0 Upgrading to Enhanced Memory MCP v0.8.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/MIGRATION.md`\n- **Query Language Reference**（project_doc）：Query Language Reference Boolean Search Syntax for Advanced Queries 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/QUERY_LANGUAGE.md`\n- **TaskScheduler Integration Guide**（project_doc）：Phase 9B : This guide documents how to integrate the TaskScheduler's progress tracking and cancellation support with long-running operations in the Memory MCP server. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/guides/TASKSCHEDULER_INTEGRATION.md`\n- **Phase 10: Advanced Features & Developer Experience**（project_doc）：Phase 10: Advanced Features & Developer Experience 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_10_IMPROVEMENT_PLAN.md`\n- **Phase 11: Three-Layer Hybrid Search & Intelligent Retrieval**（project_doc）：Phase 11: Three-Layer Hybrid Search & Intelligent Retrieval 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_11_IMPROVEMENT_PLAN.md`\n- **Phase 12: Performance Optimization Plan**（project_doc）：Phase 12: Performance Optimization Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_12_PERFORMANCE_OPTIMIZATION_PLAN.md`\n- **MemoryJS Extraction Plan**（project_doc）：Project Refactoring: memory-mcp → memoryjs + memory-mcp 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_13_MEMORYJS_EXTRACTION_PLAN.md`\n- **Phase 1 Refactoring Plan: Performance & Architecture Fixes**（project_doc）：Phase 1 Refactoring Plan: Performance & Architecture Fixes 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_1_REFACTORING_PLAN.md`\n- **Phase 2 Test Plan: Achieve 90% Test Coverage**（project_doc）：Phase 2 Test Plan: Achieve 90% Test Coverage 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_2A_TEST_PLAN_SERVER_SIDE.md`\n- **Phase 2B Test Plan: MCP Client-Side Tool Testing**（project_doc）：Phase 2B Test Plan: MCP Client-Side Tool Testing 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_2B_TEST_PLAN_CLIENT_SIDE.md`\n- **Phase 3 Refactoring Plan: Brotli Compression Integration**（project_doc）：Phase 3 Refactoring Plan: Brotli Compression Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_3_REFACTORING_PLAN.md`\n- **Phase 4: Performance Caching & Graph Algorithms Plan**（project_doc）：Phase 4: Performance Caching & Graph Algorithms Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_4_PERFORMANCE_CACHING_PLAN.md`\n- **Phase 5: Folder Restructuring Plan**（project_doc）：Version: 8.57.0 → 8.58.0 Date: 2026-01-02 Status: Planning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_5_FOLDER_RESTRUCTURING_PLAN.md`\n- **Phase 6: Performance Optimization Plan**（project_doc）：Phase 6: Performance Optimization Plan 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_6_PERFORMANCE_OPTIMIZATION_PLAN.md`\n- **Phase 7: Parallel Processing & Advanced I/O**（project_doc）：Phase 7: Parallel Processing & Advanced I/O 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_7_IMPROVEMENT_PLAN.md`\n- **Phase 8: Workerpool Library Integration**（project_doc）：Phase 8: Workerpool Library Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_8_WORKERPOOL_INTEGRATION.md`\n- **Phase 9B: TaskScheduler Integration**（project_doc）：Phase 9B: TaskScheduler Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_9B_IMPROVEMENT_PLAN.md`\n- **Phase 9: Advanced Optimizations**（project_doc）：Version : 1.0.0 Created : 2026-01-04 Status : PLANNED Total Sprints : 3 Total Tasks : 11 tasks organized into sprints of 3-4 items Prerequisites : Phase 8 Workerpool Integration complete, All 2209+ tests passing 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/planning/PHASE_9_IMPROVEMENT_PLAN.md`\n- **Documentation Inventory & Organization**（project_doc）：Documentation Inventory & Organization 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/DOCUMENTATION_INVENTORY.md`\n- **Code Quality Improvements Summary**（project_doc）：This document provides a comprehensive summary of all code quality improvements made to the memory-mcp project during the systematic code review and enhancement process from November 24, 2025. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/IMPROVEMENTS_SUMMARY.md`\n- **Phase 6 Performance Optimization - Baseline Metrics**（project_doc）：Phase 6 Performance Optimization - Baseline Metrics 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/PHASE_6_BASELINE_METRICS.md`\n- **Refactoring Summary**（project_doc）：Overview Successfully refactored monolithic src/memory/index.ts 4,187 lines into a modular, maintainable architecture with 40 TypeScript files across 8 phases. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/REFACTORING_SUMMARY.md`\n- **Sprint Progress Summary**（project_doc）：Sprint 3: Performance Optimizations ✅ COMPLETE 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/SPRINT_PROGRESS.md`\n- **Sprint Summary: Code Review Implementation v0.11.6 → v0.14.0**（project_doc）：Sprint Summary: Code Review Implementation v0.11.6 → v0.14.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/SPRINT_SUMMARY.md`\n- **Refactoring Task Summary**（project_doc）：This document summarizes the comprehensive planning created for the index.ts refactoring project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reports/TASK_SUMMARY.md`\n- **Future Features Roadmap**（project_doc）：Version: 3.2.0 Last Updated: 2026-04-26 Current Version: 12.2.0 Target Version: 13.0.0 post-v12.2.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/roadmap/FUTURE_FEATURES.md`\n- **Performance & Optimization Roadmap**（project_doc）：Version: 3.1.0 Last Updated: 2026-04-26 Current Version: 12.2.0 Target Version: 13.0.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/roadmap/PERFORMANCE_AND_CAPABILITIES.md`\n- **Test Coverage Analysis**（project_doc）：Generated : 2026-01-09 pre-Phase 13 extraction Status : Historical — see note below. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/architecture/TEST_COVERAGE.md`\n- **Comprehensive Code Review - Memory MCP Server**（project_doc）：Comprehensive Code Review - Memory MCP Server 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/CODE_REVIEW.md`\n- **File Size Policy**（project_doc）：This project enforces strict file size limits to maintain code quality, readability, and maintainability. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/FILE_SIZE_POLICY.md`\n- **Description**（project_doc）：Server Details - Server: - Changes to: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n- **Changelog**（project_doc）：All notable changes to the Enhanced Memory MCP will be documented in this file. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Code of Conduct - Enhanced Memory MCP**（project_doc）：Code of Conduct - Enhanced Memory MCP 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **Security Policy**（project_doc）：Thank you for helping keep the Enhanced Memory MCP server secure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Chunking for Files**（project_doc）：Split or merge large files for editing within context limits 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/CHUNK.md`\n- **Project Commit Workflow**（project_doc）：Full project commit workflow - typecheck, test, version bump, changelog, and push to GitHub 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/COMMIT.md`\n- **Compress for Context CTON**（project_doc）：Compress files using CTON format for LLM context optimization 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/CTON.md`\n- **Dependency Graph Analysis**（project_doc）：Generate and analyze project dependency graph 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/DEPS.md`\n- **Project Exploration & Knowledge Indexing**（project_doc）：Index project and update knowledge graph + CLAUDE.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/EXPLORE.md`\n- **Create Dependency Graph**（project_doc）：Generate a dependency graph for a TypeScript project 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/GRAPH.md`\n- **Memory Graph Operations**（project_doc）：Comprehensive memory graph operations - CRUD, search, and maintenance 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/MEMORY.md`\n- **Migrate Storage Format**（project_doc）：Migrate memory storage between JSONL and SQLite formats 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/MIGRATE.md`\n- **File Search**（project_doc）：Search files using Everything fast indexed or fzf fuzzy matching 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/SEARCH.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Documentation Index**（documentation）：Welcome to the Enhanced Memory MCP documentation! This directory contains comprehensive documentation for developers, users, and contributors. 证据：`docs/README.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **Memory MCP Server**（documentation）：! Version https://img.shields.io/badge/version-12.3.0-blue.svg https://github.com/danielsimonjr/memory-mcp ! NPM https://img.shields.io/npm/v/@danielsimonjr/memory-mcp.svg https://www.npmjs.com/package/@danielsimonjr/memory-mcp ! License https://img.shields.io/badge/license-MIT-green.svg LICENSE ! MCP https://img.shields.io/badge/MCP-1.0-purple.svg https://modelcontextprotocol.io ! TypeScript https://img.shields.io/badge/TypeScript-5.6-blue.svg https://www.typescriptlang.org/ ! Coverage https://img.shields.io/badge/coverage-80.7%25-yellow.svg docs/architecture/TEST COVERAGE.md 证据：`README.md`\n- **DeepThinking MCP Tools**（documentation）：This directory contains utility scripts for maintaining the DeepThinking MCP codebase. 证据：`tools/create-dependency-graph/README.md`\n- **Memory MCP Migration Tool**（documentation）：Migrate knowledge graph data between JSONL and SQLite storage formats for the Memory MCP server. 证据：`tools/migrate-from-jsonl-to-sqlite/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@danielsimonjr/memory-mcp\", \"version\": \"12.3.0\", \"description\": \"Enhanced MCP memory server with hierarchies, compression, archiving, graph algorithms, semantic search, temporal KG, RBAC, bitemporal validity, OCC, procedural memory, causal reasoning, world model, do not remember exclusions, decision rationale, project context, heuristic guidelines, tool affordance + observer, observation dedup, spell correction, and 213 advanced tools\", \"license\": \"MIT\", \"engines\": { \"node\": \" =18.0.0\" }, \"author\": \"Daniel Simon Jr. https://github.com/danielsimonjr \", \"homepage\": \"https://github.com/danielsimonjr/memory-mcp\", \"bugs\": \"https://github.com/danielsimonjr/memory-mcp/issues\", \"reposito… 证据：`package.json`\n- **Contributing to Enhanced Memory MCP**（documentation）：Contributing to Enhanced Memory MCP 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"chunking-for-files\", \"version\": \"1.0.0\", \"description\": \"Split and merge large files for editing within context limits\", \"main\": \"./dist/chunking-for-files.js\", \"bin\": { \"chunking-for-files\": \"./dist/chunking-for-files.js\" }, \"scripts\": { \"build\": \"npm run build:ts && npm run build:exe\", \"build:ts\": \"tsc\", \"build:exe\": \"npx @yao-pkg/pkg . --target node22-win-x64 --output chunking-for-files.exe\", \"start\": \"node dist/chunking-for-files.js\" }, \"pkg\": { \"scripts\": \"dist/ / .js\" , \"targets\": \"node22-win-x64\" }, \"keywords\": \"markdown\", \"chunker\", \"chunking\", \"split\", \"merge\", \"llm\", \"context\" , \"author\": \"DeepThinking MCP\", \"license\": \"MIT\", \"devDependencies\": { \"@types/node\": \"^22\", \"… 证据：`tools/chunking-for-files/package.json`\n- **Package**（package_manifest）：{ \"name\": \"compress-for-context\", \"version\": \"1.0.0\", \"description\": \"Compress files for LLM context windows\", \"type\": \"module\", \"scripts\": { \"build\": \"npm run build:ts && npm run build:exe\", \"build:ts\": \"tsc\", \"build:exe\": \"npx @yao-pkg/pkg . --target node22-win-x64 --output compress-for-context.exe\", \"start\": \"node dist/compress-for-context.js\" }, \"bin\": { \"compress-for-context\": \"./dist/compress-for-context.js\" }, \"pkg\": { \"scripts\": \"dist/ / .js\" , \"targets\": \"node22-win-x64\" }, \"devDependencies\": { \"@types/node\": \"^25.0.2\", \"@yao-pkg/pkg\": \"^6.11.0\", \"typescript\": \"^5.3.0\" }, \"engines\": { \"node\": \" =18.0.0\" } } 证据：`tools/compress-for-context/package.json`\n- **Package**（package_manifest）：{ \"name\": \"create-dependency-graph\", \"version\": \"1.0.0\", \"description\": \"Generate dependency graph documentation for TypeScript projects\", \"scripts\": { \"build\": \"npm run build:ts && npm run build:exe\", \"build:ts\": \"tsc\", \"build:exe\": \"npx @yao-pkg/pkg . --target node22-win-x64 --output create-dependency-graph.exe\", \"start\": \"node dist/create-dependency-graph.js\" }, \"bin\": { \"create-dependency-graph\": \"./dist/create-dependency-graph.js\" }, \"pkg\": { \"scripts\": \"dist/ / .js\" , \"targets\": \"node22-win-x64\" }, \"dependencies\": { \"js-yaml\": \"^4.1.0\" }, \"devDependencies\": { \"@types/js-yaml\": \"^4.0.9\", \"@types/node\": \"^25.0.2\", \"@yao-pkg/pkg\": \"^6.11.0\", \"typescript\": \"^5.3.0\" }, \"engines\": { \"node\":… 证据：`tools/create-dependency-graph/package.json`\n- **Package**（package_manifest）：{ \"name\": \"migrate-from-jsonl-to-sqlite\", \"version\": \"1.1.0\", \"description\": \"Migration tool for Memory MCP - converts between JSONL and SQLite storage formats\", \"scripts\": { \"build\": \"npm run build:ts && npm run build:exe\", \"build:ts\": \"tsc\", \"build:exe\": \"npx @yao-pkg/pkg . --target node22-win-x64 --output migrate-from-jsonl-to-sqlite.exe\", \"start\": \"node dist/migrate-from-jsonl-to-sqlite.js\" }, \"bin\": { \"migrate-from-jsonl-to-sqlite\": \"./dist/migrate-from-jsonl-to-sqlite.js\" }, \"pkg\": { \"scripts\": \"dist/ / .js\" , \"assets\": \"node modules/better-sqlite3/build/Release/ .node\", \"node modules/better-sqlite3/prebuilds/ / \" , \"targets\": \"node22-win-x64\" }, \"dependencies\": { \"better-sqlite3\": \"^… 证据：`tools/migrate-from-jsonl-to-sqlite/package.json`\n- **License**（source_file）：Copyright c 2025 Anthropic, PBC Original Memory MCP Server Copyright c 2025 Daniel Simon Jr. Phase 1-4 Enhancements 证据：`LICENSE`\n- **Brutally Honest Codebase Analysis — Final Cut**（documentation）：Brutally Honest Codebase Analysis — Final Cut 证据：`docs/analysis/BRUTALLY_HONEST_ANALYSIS.md`\n- **Comprehensive Codebase Review: memory-mcp**（documentation）：Comprehensive Codebase Review: memory-mcp 证据：`docs/analysis/Comprehensive_Codebase_Review.md`\n- **Implementation Verification Report**（documentation）：Date: 2026-01-01 Original Analysis: 2026-01-01 Version Before: 0.11.5 / 0.59.0 Version After: 8.50.24 证据：`docs/analysis/IMPLEMENTATION_VERIFICATION.md`\n- **Memory MCP - API Reference**（documentation）：Version : 12.2.0 Last Updated : 2026-04-26 证据：`docs/architecture/API.md`\n- **Memory MCP - System Architecture**（documentation）：Version : 12.2.0 Last Updated : 2026-04-26 证据：`docs/architecture/ARCHITECTURE.md`\n- **Memory MCP - Component Reference**（documentation）：Version : 12.2.0 Last Updated : 2026-04-26 证据：`docs/architecture/COMPONENTS.md`\n- **Memory MCP - Data Flow Documentation**（documentation）：Memory MCP - Data Flow Documentation 证据：`docs/architecture/DATAFLOW.md`\n- **@danielsimonjr/memory-mcp - Dependency Graph**（documentation）：@danielsimonjr/memory-mcp - Dependency Graph 证据：`docs/architecture/DEPENDENCY_GRAPH.md`\n- **Memory MCP Server - Project Overview**（documentation）：Memory MCP Server - Project Overview 证据：`docs/architecture/OVERVIEW.md`\n- **Unused Files and Exports Analysis**（documentation）：- Potentially unused files : 0 - Potentially unused exports : 9 证据：`docs/architecture/unused-analysis.md`\n- **Context/Token Optimization Refactoring Plan**（documentation）：Context/Token Optimization Refactoring Plan 证据：`docs/development/CONTEXT_OPTIMIZATION_PLAN.md`\n- **Implementation Plan - Memory MCP Server**（documentation）：Implementation Plan - Memory MCP Server 证据：`docs/development/IMPLEMENTATION_PLAN.md`\n- **Index.ts Refactoring - Detailed Implementation Tasks**（documentation）：Index.ts Refactoring - Detailed Implementation Tasks 证据：`docs/development/IMPLEMENTATION_TASKS.md`\n- **Memory MCP Improvement Plan**（documentation）：Memory MCP Improvement Plan Comprehensive Roadmap for Advanced Features 证据：`docs/development/IMPROVEMENT_PLAN.md`\n- **Index.ts Refactoring Plan**（documentation）：This document outlines a comprehensive plan to refactor the monolithic src/memory/index.ts file 4,187 lines into a modular, maintainable architecture. The refactoring will improve code organization, testability, maintainability, and developer experience while preserving all existing functionality. 证据：`docs/development/REFACTORING_PLAN.md`\n- **Memory MCP Development Workflow**（documentation）：Updated 2026-04-26 for v12.2.0. The previous version of this file referenced a pre-Phase-13 layout and a 15-tool count — both obsolete. 证据：`docs/development/WORKFLOW.md`\n- **Memory Archiving Guide**（documentation）：Memory Archiving Guide Managing Memory Lifecycle and Long-Term Storage 证据：`docs/guides/ARCHIVING.md`\n- **Memory Compression Guide**（documentation）：Memory Compression Guide Brotli Compression, Response Compression, and Entity Deduplication 证据：`docs/guides/COMPRESSION.md`\n- **Hierarchical Nesting Guide**（documentation）：Hierarchical Nesting Guide Organizing Knowledge with Parent-Child Relationships 证据：`docs/guides/HIERARCHY.md`\n- **Migration Guide: v0.7.0 → v0.8.0**（documentation）：Migration Guide: v0.7.0 → v0.8.0 Upgrading to Enhanced Memory MCP v0.8.0 证据：`docs/guides/MIGRATION.md`\n- **Query Language Reference**（documentation）：Query Language Reference Boolean Search Syntax for Advanced Queries 证据：`docs/guides/QUERY_LANGUAGE.md`\n- **TaskScheduler Integration Guide**（documentation）：Phase 9B : This guide documents how to integrate the TaskScheduler's progress tracking and cancellation support with long-running operations in the Memory MCP server. 证据：`docs/guides/TASKSCHEDULER_INTEGRATION.md`\n- **Phase 10: Advanced Features & Developer Experience**（documentation）：Phase 10: Advanced Features & Developer Experience 证据：`docs/planning/PHASE_10_IMPROVEMENT_PLAN.md`\n- **Phase 11: Three-Layer Hybrid Search & Intelligent Retrieval**（documentation）：Phase 11: Three-Layer Hybrid Search & Intelligent Retrieval 证据：`docs/planning/PHASE_11_IMPROVEMENT_PLAN.md`\n- **Phase 12: Performance Optimization Plan**（documentation）：Phase 12: Performance Optimization Plan 证据：`docs/planning/PHASE_12_PERFORMANCE_OPTIMIZATION_PLAN.md`\n- **MemoryJS Extraction Plan**（documentation）：Project Refactoring: memory-mcp → memoryjs + memory-mcp 证据：`docs/planning/PHASE_13_MEMORYJS_EXTRACTION_PLAN.md`\n- **Phase 1 Refactoring Plan: Performance & Architecture Fixes**（documentation）：Phase 1 Refactoring Plan: Performance & Architecture Fixes 证据：`docs/planning/PHASE_1_REFACTORING_PLAN.md`\n- **Phase 2 Test Plan: Achieve 90% Test Coverage**（documentation）：Phase 2 Test Plan: Achieve 90% Test Coverage 证据：`docs/planning/PHASE_2A_TEST_PLAN_SERVER_SIDE.md`\n- **Phase 2B Test Plan: MCP Client-Side Tool Testing**（documentation）：Phase 2B Test Plan: MCP Client-Side Tool Testing 证据：`docs/planning/PHASE_2B_TEST_PLAN_CLIENT_SIDE.md`\n- **Phase 3 Refactoring Plan: Brotli Compression Integration**（documentation）：Phase 3 Refactoring Plan: Brotli Compression Integration 证据：`docs/planning/PHASE_3_REFACTORING_PLAN.md`\n- **Phase 4: Performance Caching & Graph Algorithms Plan**（documentation）：Phase 4: Performance Caching & Graph Algorithms Plan 证据：`docs/planning/PHASE_4_PERFORMANCE_CACHING_PLAN.md`\n- **Phase 5: Folder Restructuring Plan**（documentation）：Version: 8.57.0 → 8.58.0 Date: 2026-01-02 Status: Planning 证据：`docs/planning/PHASE_5_FOLDER_RESTRUCTURING_PLAN.md`\n- **Phase 6: Performance Optimization Plan**（documentation）：Phase 6: Performance Optimization Plan 证据：`docs/planning/PHASE_6_PERFORMANCE_OPTIMIZATION_PLAN.md`\n- **Phase 7: Parallel Processing & Advanced I/O**（documentation）：Phase 7: Parallel Processing & Advanced I/O 证据：`docs/planning/PHASE_7_IMPROVEMENT_PLAN.md`\n- **Phase 8: Workerpool Library Integration**（documentation）：Phase 8: Workerpool Library Integration 证据：`docs/planning/PHASE_8_WORKERPOOL_INTEGRATION.md`\n- **Phase 9B: TaskScheduler Integration**（documentation）：Phase 9B: TaskScheduler Integration 证据：`docs/planning/PHASE_9B_IMPROVEMENT_PLAN.md`\n- **Phase 9: Advanced Optimizations**（documentation）：Version : 1.0.0 Created : 2026-01-04 Status : PLANNED Total Sprints : 3 Total Tasks : 11 tasks organized into sprints of 3-4 items Prerequisites : Phase 8 Workerpool Integration complete, All 2209+ tests passing 证据：`docs/planning/PHASE_9_IMPROVEMENT_PLAN.md`\n- **Documentation Inventory & Organization**（documentation）：Documentation Inventory & Organization 证据：`docs/reports/DOCUMENTATION_INVENTORY.md`\n- **Code Quality Improvements Summary**（documentation）：This document provides a comprehensive summary of all code quality improvements made to the memory-mcp project during the systematic code review and enhancement process from November 24, 2025. 证据：`docs/reports/IMPROVEMENTS_SUMMARY.md`\n- **Phase 6 Performance Optimization - Baseline Metrics**（documentation）：Phase 6 Performance Optimization - Baseline Metrics 证据：`docs/reports/PHASE_6_BASELINE_METRICS.md`\n- **Refactoring Summary**（documentation）：Overview Successfully refactored monolithic src/memory/index.ts 4,187 lines into a modular, maintainable architecture with 40 TypeScript files across 8 phases. 证据：`docs/reports/REFACTORING_SUMMARY.md`\n- **Sprint Progress Summary**（documentation）：Sprint 3: Performance Optimizations ✅ COMPLETE 证据：`docs/reports/SPRINT_PROGRESS.md`\n- **Sprint Summary: Code Review Implementation v0.11.6 → v0.14.0**（documentation）：Sprint Summary: Code Review Implementation v0.11.6 → v0.14.0 证据：`docs/reports/SPRINT_SUMMARY.md`\n- **Refactoring Task Summary**（documentation）：This document summarizes the comprehensive planning created for the index.ts refactoring project. 证据：`docs/reports/TASK_SUMMARY.md`\n- **Future Features Roadmap**（documentation）：Version: 3.2.0 Last Updated: 2026-04-26 Current Version: 12.2.0 Target Version: 13.0.0 post-v12.2.0 证据：`docs/roadmap/FUTURE_FEATURES.md`\n- **Performance & Optimization Roadmap**（documentation）：Version: 3.1.0 Last Updated: 2026-04-26 Current Version: 12.2.0 Target Version: 13.0.0 证据：`docs/roadmap/PERFORMANCE_AND_CAPABILITIES.md`\n- **Test Coverage Analysis**（documentation）：Generated : 2026-01-09 pre-Phase 13 extraction Status : Historical — see note below. 证据：`docs/architecture/TEST_COVERAGE.md`\n- **Comprehensive Code Review - Memory MCP Server**（documentation）：Comprehensive Code Review - Memory MCP Server 证据：`.github/CODE_REVIEW.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json\n- **快速开始**：importance `high`\n - source_paths: README.md, docs/guides/MIGRATION.md\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/server/MCPServer.ts, src/server/toolDefinitions.ts, src/server/toolHandlers.ts, docs/architecture/ARCHITECTURE.md\n- **数据流处理**：importance `medium`\n - source_paths: src/server/toolHandlers.ts, src/server/responseCompressor.ts, docs/architecture/DATAFLOW.md\n- **实体与关系模型**：importance `high`\n - source_paths: docs/architecture/API.md, README.md\n- **存储后端**：importance `high`\n - source_paths: tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts, tools/migrate-from-jsonl-to-sqlite/README.md, README.md\n- **层级嵌套**：importance `medium`\n - source_paths: docs/guides/HIERARCHY.md, docs/architecture/API.md\n- **搜索能力**：importance `high`\n - source_paths: docs/guides/QUERY_LANGUAGE.md, docs/architecture/API.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：danielsimonjr/memory-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/danielsimonjr/memory-mcp 项目说明书\n\n生成时间：2026-05-16 08:51:38 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [快速开始](#page-quick-start)\n- [系统架构](#page-architecture)\n- [数据流处理](#page-data-flow)\n- [实体与关系模型](#page-entities-relations)\n- [存储后端](#page-storage-backends)\n- [层级嵌套](#page-hierarchical-nesting)\n- [搜索能力](#page-search-capabilities)\n- [高级功能](#page-advanced-features)\n- [工具参考手册](#page-tool-reference)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [快速开始](#page-quick-start)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/danielsimonjr/memory-mcp/blob/main/package.json)\n- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n \n\n# 项目介绍\n\n## 概述\n\nMemory MCP 是一个基于 **Model Context Protocol (MCP)** 的增强型记忆管理服务器，通过 MCP 协议为 AI 代理提供持久化记忆能力。该项目作为 MCP 服务器运行，封装了 `@danielsimonjr/memoryjs` 核心库的所有功能，向 AI 代理暴露 213 个工具函数，覆盖 58 个功能类别。资料来源：[README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)\n\n### 核心定位\n\nMemory MCP 的设计目标是为 AI 代理提供类似于人类记忆的长期记忆存储与检索能力。通过知识图谱结构，代理可以：\n\n- **持久化存储** - 将重要信息写入长期记忆\n- **智能检索** - 根据语义、关键词、时间等多种维度检索记忆\n- **层级管理** - 支持父子关系的层级记忆结构\n- **衰减机制** - 自动对低价值记忆进行时间衰减\n- **协同推理** - 支持多代理协作式的记忆综合分析\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n## 技术架构\n\n### 分层架构设计\n\nMemory MCP 采用清晰的分层架构，核心层由 `memoryjs` 库提供，MCP 层负责协议适配与工具暴露。\n\n```mermaid\ngraph TD\n subgraph \"Memory MCP (本项目)\"\n A[src/index.ts] --> B[MCPServer]\n B --> C[toolDefinitions.ts]\n B --> D[toolHandlers.ts]\n C --> D\n end\n \n subgraph \"@danielsimonjr/memoryjs\"\n E[ManagerContext] --> F[EntityManager]\n E --> G[RelationManager]\n E --> H[ObservationManager]\n E --> I[SearchManager]\n E --> J[TagManager]\n E --> K[HierarchyManager]\n E --> L[CompressionManager]\n E --> M[AnalyticsManager]\n E --> N[GraphStorage]\n end\n \n D --> E\n```\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n### ManagerContext 核心组件\n\n`ManagerContext` 是 memoryjs 库的核心类，采用懒加载模式初始化所有管理器实例。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 管理器组件 | 访问方式 | 功能说明 |\n|-----------|---------|---------|\n| EntityManager | `ctx.entityManager` | 图节点（实体）的增删改查 |\n| RelationManager | `ctx.relationManager` | 有向边管理，连接实体间关系 |\n| ObservationManager | `ctx.observationManager` | 附加到实体的观察事实，支持归一化 |\n| SearchManager | `ctx.searchManager` | 基础搜索、布尔搜索、模糊搜索 |\n| TagManager | `ctx.tagManager` | 标签管理与重要性评分 |\n| HierarchyManager | `ctx.hierarchyManager` | 父子树结构与子树遍历 |\n| AnalyticsManager | `ctx.analyticsManager` | 图统计与完整性验证 |\n| CompressionManager | `ctx.compressionManager` | 去重、合并、自动压缩、归档 |\n| ArchiveManager | `ctx.archiveManager` | 记忆归档管理 |\n| IOManager | `ctx.ioManager` | 数据导入导出 |\n| SemanticSearch | `ctx.semanticSearch` | OpenAI 或本地模型的语义搜索 |\n| RankedSearch | `ctx.rankedSearch` | TF-IDF 排序搜索 |\n\n### 向后兼容性\n\n`src/index.ts` 将 `ManagerContext` 重新导出为 `KnowledgeGraphManager` 别名，同时导出核心类型定义，确保与旧版 API 的兼容性。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n## 工具体系\n\n### 工具分类总览\n\nMemory MCP 提供 213 个工具函数，覆盖 58 个功能类别。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 类别 | 工具数量 | 核心功能 |\n|------|---------|---------|\n| Entity | 4 | 图节点的创建、读取、更新、删除 |\n| Relation | 2 | 实体间的有向边管理 |\n| Observation | 3 | 附加事实的增删改查，支持归一化 |\n| Search | 7 | 基础搜索、排序搜索、布尔搜索、模糊搜索、自动选择 |\n| Intelligent Search | 3 | 混合多层搜索、查询分析、基于反思的搜索 |\n| Semantic Search | 3 | 通过 OpenAI 或本地模型的嵌入相似度搜索 |\n| Saved Searches | 5 | 存储和重新执行常用查询 |\n| Tag Management | 6 | 标签管理、批量操作、重要性评分 |\n| Tag Aliases | 5 | 标签同义词/别名管理 |\n| Hierarchy | 9 | 父子树结构、子树遍历 |\n| Graph Algorithms | 4 | BFS/DFS 路径查找、中心性、连通分量 |\n| Analytics | 2 | 图统计和完整性验证 |\n| Compression | 4 | 去重检测、合并、自动压缩、归档 |\n| Import/Export | 2 | 7 种导出格式 |\n\n### 工具处理流程\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP 客户端\n participant Server as MCPServer\n participant Handler as toolHandlers.ts\n participant Manager as ManagerContext\n \n MCP->>Server: 工具调用请求\n Server->>Handler: 路由到对应 handler\n Handler->>Manager: 调用 ManagerContext 方法\n Manager->>Manager: 执行业务逻辑\n Manager-->>Handler: 返回结果\n Handler-->>Server: 格式化响应\n Server-->>MCP: MCP 格式响应\n```\n\n资料来源：[src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n\n## 存储方案\n\n### 存储类型\n\nMemory MCP 支持两种存储后端，数据文件位于**项目根目录**（非 `dist/` 目录）。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 存储类型 | 文件 | 环境变量 |\n|---------|------|---------|\n| JSONL (默认) | `memory.jsonl`, `memory-saved-searches.jsonl`, `memory-tag-aliases.jsonl` | - |\n| SQLite | `memory.db` | `MEMORY_STORAGE_TYPE=sqlite` |\n\n### 数据迁移工具\n\n`tools/migrate-from-jsonl-to-sqlite` 目录提供了独立的迁移工具，支持 JSONL 与 SQLite 格式之间的双向转换。资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)\n\n```bash\n# 基本用法\nmigrate-from-jsonl-to-sqlite --from --to \n\n# 显示详细进度\nmigrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db --verbose\n```\n\n## 依赖管理\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| @modelcontextprotocol/sdk | ^1.0.0 | MCP 协议实现 |\n| @danielsimonjr/memoryjs | ^2.1.0 | 核心记忆管理库 |\n| zod | ^3.23.8 | Schema 验证 |\n| better-sqlite3 | ^11.7.0 | SQLite 存储后端 |\n\n### 开发依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|------|------|\n| typescript | ^5.7.0 | TypeScript 编译 |\n| @types/node | ^22.0.0 | Node.js 类型定义 |\n| vitest | ^2.0.0 | 单元测试框架 |\n\n## 版本演进\n\n### 版本历史要点\n\n| 阶段 | 版本 | 主要内容 |\n|------|------|---------|\n| Phase 13 | 初始版本 | 仅保留 5 个 TypeScript 源文件，核心逻辑移至 memoryjs |\n| Phase 15 | v12.2.0 | 新增 23 个工具，暴露 memoryjs v1.14+ 功能 |\n| Phase 16 | v12.3.0 | 新增 53 个工具，暴露 memoryjs v2.1.0 功能 |\n\nPhase 16 (v12.3.0) 新增的功能包括：排除规则 (5)、决策理由与 ADR markdown 双写 (10)、结构化项目上下文 (12)、启发式指南 (10)、工具能力与观察管道 (11)、观察去重 (2)、拼写纠正 (3)。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n## 安装与使用\n\n### npm 包信息\n\n```bash\n# 安装\nnpm install @danielsimonjr/memory-mcp\n\n# 或使用最新版本\nnpm install @danielsimonjr/memory-mcp@latest\n```\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n### 构建与发布\n\n项目使用 `prepare` 脚本在安装时自动构建，因此发布前无需单独执行构建命令。资料来源：[CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n\n```bash\n# 发布到 npm\n# 需要具有绕过 2FA 权限的 token\nnpm config set //registry.npmjs.org/:_authToken=$(cat ~/.npm_token)\nnpm publish --access public\n\n# 发布前验证 tarball 内容\nnpm pack --dry-run\n```\n\n## 独立工具集\n\n`tools/` 目录包含可独立运行的工具，每个工具拥有自己的 `package.json`，可通过 `pkg` 编译为 Windows 可执行文件。资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n| 工具目录 | 用途 |\n|---------|------|\n| `chunking-for-files` | 将大文件拆分为小块以适应上下文限制 |\n| `compress-for-context` | CTON 压缩以适应 LLM 上下文窗口 |\n| `create-dependency-graph` | 生成 TypeScript 项目依赖图 |\n| `migrate-from-jsonl-to-sqlite` | JSONL 与 SQLite 格式转换 |\n\n## 开发指南\n\n### 代码规范\n\n- 遵循 TypeScript 最佳实践\n- 使用有意义的变量命名\n- 为公共方法添加 JSDoc 注释\n- 保持函数专注于小而简洁\n- 统一使用 2 空格缩进\n\n### 测试要求\n\n- 全面测试新功能\n- 包含边界情况测试\n- 测试向后兼容性\n- 验证导出格式有效性\n- 测试空图和大图场景\n\n### 提交流程\n\n1. **创建功能分支**: `git checkout -b feature/your-feature-name`\n2. **提交更改**: `git add . && git commit -m \"Description\"`\n3. **推送并创建 PR**: `git push origin feature/your-feature-name`\n4. PR 应包含：标题、描述、测试结果、文档更新、向后兼容性确认\n\n资料来源：[CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n\n## 配置选项\n\n### 环境变量\n\n| 环境变量 | 说明 | 默认值 |\n|---------|------|-------|\n| `MEMORY_STORAGE_TYPE` | 存储类型选择 | `jsonl` |\n| `MEMORY_DB_PATH` | SQLite 数据库路径 | `memory.db` |\n\n### TypeScript 配置\n\n- 编译目标: ES2022\n- 模块解析: Node16\n\n## 相关资源\n\n- **npm 包**: [@danielsimonjr/memory-mcp](https://www.npmjs.com/package/@danielsimonjr/memory-mcp)\n- **核心库**: [@danielsimonjr/memoryjs](https://www.npmjs.com/package/@danielsimonjr/memoryjs)\n- **MCP 协议**: [Model Context Protocol](https://modelcontextprotocol.io/)\n- **社区指南**: [MCP Community Guidelines](https://modelcontextprotocol.io/community/communication)\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/README.md)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)\n- [src/server/MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts)\n \n\n# 快速开始\n\n本文档帮助你在 5 分钟内完成 memory-mcp 的安装、配置和首次使用。\n\n## 项目概述\n\nmemory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱记忆管理服务器。它为 AI 助手提供持久化记忆存储、语义搜索和层次化组织能力。\n\n**核心依赖：**\n- **npm 包**：`@danielsimonjr/memory-mcp`\n- **核心库**：`@danielsimonjr/memoryjs`\n- **协议层**：Model Context Protocol\n- **存储后端**：JSONL 文件或 SQLite 数据库\n\n资料来源：[README.md:1-15]()\n\n## 系统架构\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ memory-mcp (本仓库) │\n├─────────────────────────────────────────────────────────────┤\n│ src/index.ts │ 入口文件，导出公共 API │\n│ src/server/MCPServer │ MCP 服务器实现 │\n│ src/server/toolDefs │ 工具定义 (213 个工具，58 个类别) │\n│ src/server/toolHandlers│ 工具处理逻辑 │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ @danielsimonjr/memoryjs (npm 依赖) │\n├─────────────────────────────────────────────────────────────┤\n│ ManagerContext │ 懒加载管理器上下文 │\n│ EntityManager │ 实体/节点管理 │\n│ RelationManager │ 关系/边管理 │\n│ SearchManager │ 搜索管理 │\n│ IOManager │ 导入/导出管理 │\n│ GraphStorage/SQLiteStorage │ 图存储/SQLite 存储后端 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[CLAUDE.md:1-30]()\n\n## 前置要求\n\n| 要求 | 最低版本 | 说明 |\n|------|----------|------|\n| Node.js | 18.0.0 | 推荐使用 LTS 版本 |\n| npm | 9.0.0 | 用于安装依赖 |\n| 操作系统 | Windows/macOS/Linux | 跨平台支持 |\n| 磁盘空间 | 50MB | 基础安装占用 |\n\n## 安装步骤\n\n### 1. 全局安装\n\n```bash\nnpm install -g @danielsimonjr/memory-mcp\n```\n\n### 2. 验证安装\n\n安装完成后，系统会创建以下组件：\n\n| 组件 | 位置 | 说明 |\n|------|------|------|\n| 构建产物 | `dist/index.js` | 编译后的入口文件 |\n| CLI 二进制文件 | `mcp-server-memory` | 命令行工具 |\n| 源码入口 | `src/index.ts` | TypeScript 源码 |\n\n安装过程中 `prepare` 脚本会自动运行 `npm run build` 进行构建。 资料来源：[CLAUDE.md:40-45]()\n\n## 存储配置\n\nmemory-mcp 支持两种存储后端，在项目根目录创建配置文件即可：\n\n### JSONL 存储（默认）\n\n默认使用 JSONL 格式存储，数据文件位于**项目根目录**（不是 `dist/`）：\n\n```\n├── memory.jsonl # 主记忆数据\n├── memory-saved-searches.jsonl # 保存的搜索\n├── memory-tag-aliases.jsonl # 标签别名\n└── memory.db # (可选) SQLite 数据库\n```\n\n### SQLite 存储\n\n设置环境变量切换到 SQLite 存储：\n\n```bash\nexport MEMORY_STORAGE_TYPE=sqlite\n```\n\n使用 SQLite 时，所有数据存储在 `memory.db` 文件中。 资料来源：[CLAUDE.md:30-35]()\n\n## 工具类别总览\n\nmemory-mcp 提供 **213 个工具**，分为 **58 个类别**：\n\n| 类别 | 工具数量 | 核心功能 |\n|------|----------|----------|\n| 实体 (Entity) | 4 | 图节点的基础增删改查 |\n| 关系 (Relation) | 2 | 实体间的有向边管理 |\n| 观察 (Observation) | 3 | 附加到实体的属性和事实 |\n| 搜索 (Search) | 7 | 基础、布尔、模糊搜索 |\n| 智能搜索 (Intelligent Search) | 3 | 混合多层、查询分析 |\n| 语义搜索 (Semantic Search) | 3 | OpenAI 或本地模型嵌入 |\n| 标签管理 (Tag Management) | 6 | 标签及重要性评分 |\n| 层级管理 (Hierarchy) | 9 | 父子树和子树遍历 |\n| 图算法 (Graph Algorithms) | 4 | BFS/DFS、中心性计算 |\n| 分析 (Analytics) | 2 | 图统计和完整性验证 |\n| 压缩 (Compression) | 4 | 去重、合并、自动压缩 |\n| 导入/导出 (Import/Export) | 2 | 7 种导出格式 |\n\n资料来源：[CLAUDE.md:15-25]()\n\n## 首次使用\n\n### 1. 启动服务器\n\n在支持 MCP 的客户端（如 Claude Desktop）中配置服务器连接。服务器通过 Model Context Protocol 暴露所有工具。\n\n### 2. 创建第一个实体\n\n使用 `create_entity` 工具创建记忆节点：\n\n```\n工具：create_entity\n参数：\n - name: \"我的第一个记忆\"\n - entityType: \"memory\"\n```\n\n### 3. 添加观察数据\n\n使用 `create_observation` 为实体添加属性：\n\n```\n工具：create_observation\n参数：\n - entityName: \"我的第一个记忆\"\n - content: \"这是一个测试记忆\"\n - importance: 0.8\n```\n\n### 4. 执行搜索\n\n使用 `search` 或 `semantic_search` 查找记忆：\n\n```\n工具：search\n参数：\n - query: \"测试\"\n - limit: 10\n```\n\n## 数据流图\n\n```mermaid\ngraph TD\n A[用户请求] --> B[MCP 客户端]\n B --> C[MCPServer]\n C --> D[ToolHandlers]\n D --> E[memoryjs ManagerContext]\n E --> F{存储类型判断}\n F -->|JSONL| G[GraphStorage]\n F -->|SQLite| H[SQLiteStorage]\n G --> I[memory.jsonl]\n H --> J[memory.db]\n J --> K[结果返回]\n I --> K\n K --> C\n C --> B\n B --> L[用户响应]\n```\n\n## 常见操作示例\n\n### 层级组织\n\n创建实体间的父子关系：\n\n```\n工具：set_entity_parent\n参数：\n - entityName: \"项目A\"\n - parentName: \"工作\"\n```\n\n### 标签管理\n\n为实体添加标签：\n\n```\n工具：add_tag\n参数：\n - entityName: \"项目A\"\n - tag: \"重要\"\n - importance: 0.9\n```\n\n### 导入导出\n\n导出记忆为指定格式：\n\n```\n工具：export_graph\n参数：\n - format: \"json\"\n - includeObservations: true\n```\n\n## 开发指南\n\n如果你想为 memory-mcp 做贡献：\n\n```bash\n# 克隆仓库\ncd c:/mcp-servers/memory-mcp\n\n# 创建功能分支\ngit checkout -b feature/your-feature-name\n\n# 安装依赖\nnpm install\n\n# 编写代码，遵循以下规范：\n# - TypeScript 最佳实践\n# - 使用有意义的变量名\n# - 为公共方法添加 JSDoc 注释\n# - 保持函数小而专注\n# - 使用 2 空格缩进\n\n# 运行类型检查\nnpm run typecheck\n\n# 提交更改\ngit add .\ngit commit -m \"Description of your changes\"\n\n# 推送并创建 PR\ngit push origin feature/your-feature-name\n```\n\n资料来源：[CONTRIBUTING.md:1-25]()\n\n## 独立工具\n\n`tools/` 目录包含独立工具，每个都有独立的 `package.json`：\n\n| 工具 | 用途 |\n|------|------|\n| `chunking-for-files` | 拆分/合并大文件以适应上下文限制 |\n| `compress-for-context` | CTON 压缩以适应 LLM 上下文窗口 |\n| `create-dependency-graph` | 生成 TypeScript 项目依赖图 |\n| `migrate-from-jsonl-to-sqlite` | 在 JSONL 和 SQLite 格式间转换 |\n\n资料来源：[CLAUDE.md:50-55]()\n\n## 下一步\n\n- 阅读 [架构文档](./ARCHITECTURE.md) 深入了解系统设计\n- 查看 [工具参考](./TOOLS.md) 完整工具列表\n- 参考 [迁移指南](./MIGRATION.md) 从旧版本升级\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [数据流处理](#page-data-flow), [实体与关系模型](#page-entities-relations)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/index.ts)\n- [src/server/MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts)\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)\n \n\n# 系统架构\n\n## 概述\n\nmemory-mcp 是一个基于 Model Context Protocol (MCP) 的知识图谱管理服务器，为 AI 代理提供持久化记忆能力。该项目采用分层架构设计，核心逻辑委托给 `@danielsimonjr/memoryjs` 库处理，而本仓库专注于 MCP 协议适配层、工具定义和请求处理。\n\n**核心职责：**\n\n- 将 memoryjs 的知识图谱能力暴露为 MCP 工具（当前版本共 213 个工具，覆盖 58 个类别）\n- 处理 MCP 协议的请求/响应生命周期\n- 提供多格式存储支持（JSONL 和 SQLite）\n- 支持语义搜索、嵌入向量、权限控制等高级功能\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 架构分层\n\n### 整体架构图\n\n```mermaid\ngraph TB\n subgraph \"MCP 客户端层\"\n CLIENT[AI 代理 / Claude Desktop]\n end\n \n subgraph \"memory-mcp 服务层\"\n INDEX[src/index.ts
入口点]\n SERVER[MCPServer.ts
服务器核心]\n TOOL_DEFS[toolDefinitions.ts
工具定义]\n HANDLERS[toolHandlers.ts
工具处理器]\n end\n \n subgraph \"memoryjs 核心库\"\n CTX[ManagerContext
管理器上下文]\n EM[EntityManager]\n RM[RelationManager]\n SM[SearchManager]\n IOM[IOManager]\n STORAGE[(GraphStorage
存储层)]\n end\n \n subgraph \"存储层\"\n JSONL[(memory.jsonl)]\n SQLITE[(memory.db)]\n end\n \n CLIENT <--> INDEX\n INDEX --> SERVER\n SERVER --> TOOL_DEFS\n SERVER --> HANDLERS\n HANDLERS <--> CTX\n CTX --> EM\n CTX --> RM\n CTX --> SM\n CTX --> IOM\n CTX --> STORAGE\n STORAGE --> JSONL\n STORAGE --> SQLITE\n```\n\n### 层级说明\n\n| 层级 | 组件 | 职责 | 资料来源 |\n|------|------|------|----------|\n| **协议层** | MCP 客户端 | 与 AI 代理通信，发送 JSON-RPC 请求 | — |\n| **适配层** | `MCPServer.ts` | 初始化服务器、注册工具、处理 MCP 生命周期 | [MCPServer.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/MCPServer.ts) |\n| **定义层** | `toolDefinitions.ts` | 定义每个工具的输入模式（Zod schema） | [toolDefinitions.ts:1-50](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts) |\n| **处理层** | `toolHandlers.ts` | 实现工具业务逻辑，调用 memoryjs | [toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts) |\n| **核心层** | `memoryjs` | 管理器上下文、图谱操作、搜索算法 | [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) |\n| **存储层** | GraphStorage | 多格式数据持久化 | — |\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 核心组件详解\n\n### 1. 入口点 (src/index.ts)\n\n`src/index.ts` 是整个应用的入口文件，负责导出核心类型和初始化逻辑。\n\n**主要导出：**\n\n```typescript\n// ManagerContext 作为 KnowledgeGraphManager 别名导出\nexport { ManagerContext as KnowledgeGraphManager } from '@danielsimonjr/memoryjs';\n\n// 核心类型重导出\nexport type { Entity, Relation, Observation, SearchResult } from '@danielsimonjr/memoryjs';\n```\n\n该模块采用延迟初始化模式，仅在需要时才创建 ManagerContext 实例，以优化冷启动性能。\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n### 2. 服务器核心 (MCPServer.ts)\n\n`MCPServer.ts` 是 MCP 服务器的核心实现，负责：\n\n- 初始化 MCP 服务器实例\n- 注册所有工具定义\n- 绑定工具处理器到对应工具\n- 处理请求生命周期\n\n**架构特点：**\n\n```mermaid\nsequenceDiagram\n participant CLIENT as MCP 客户端\n participant SERVER as MCPServer\n participant HANDLER as ToolHandler\n participant MEMORYJS as memoryjs\n\n CLIENT->>SERVER: JSON-RPC 请求\n SERVER->>SERVER: 解析工具名称和参数\n SERVER->>HANDLER: 调用对应处理器\n HANDLER->>MEMORYJS: 调用 ManagerContext 方法\n MEMORYJS-->>HANDLER: 返回结果\n HANDLER-->>SERVER: 格式化响应\n SERVER-->>CLIENT: JSON-RPC 响应\n```\n\n### 3. 工具定义 (toolDefinitions.ts)\n\n`toolDefinitions.ts` 使用 JSON Schema 风格的定义来描述每个 MCP 工具的接口。\n\n**工具类别统计：**\n\n| 类别 | 工具数量 | 主要功能 |\n|------|----------|----------|\n| Entity | 4 | 图谱节点 CRUD |\n| Relation | 2 | 有向边管理 |\n| Observation | 3 | 实体事实附加 |\n| Search | 7 | 基础/排名/模糊搜索 |\n| Intelligent Search | 3 | 混合多层搜索 |\n| Semantic Search | 3 | 嵌入向量相似度 |\n| Saved Searches | 5 | 搜索存储与重执行 |\n| Tag Management | 6 | 标签和重要性评分 |\n| Hierarchy | 9 | 父子树遍历 |\n| Graph Algorithms | 4 | BFS/DFS/中心性 |\n| Analytics | 2 | 图谱统计 |\n| Compression | 4 | 去重和压缩 |\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n**工具定义结构示例：**\n\n```typescript\n{\n name: 'compress_for_context',\n description: '使用 CTON 格式压缩文本以适应 LLM 上下文窗口',\n inputSchema: {\n type: 'object',\n properties: {\n text: { type: 'string', description: '要压缩的文本' },\n level: { \n type: 'string', \n enum: ['light', 'medium', 'aggressive'],\n description: '压缩级别'\n },\n },\n required: ['text'],\n },\n}\n```\n\n资料来源：[toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n\n### 4. 工具处理器 (toolHandlers.ts)\n\n`toolHandlers.ts` 是工具的业务逻辑实现层，采用注册表模式管理所有处理函数。\n\n**处理器模式：**\n\n```typescript\n// 典型处理器结构\n工具名称: async (ctx, args) => {\n // 1. 参数验证（使用 Zod schema）\n const validatedArg = validateWithSchema(args.param, z.string(), '错误信息');\n \n // 2. 调用 memoryjs 管理器方法\n const result = await getManager(ctx).someMethod(validatedArg);\n \n // 3. 格式化响应\n return formatToolResponse(result);\n}\n```\n\n**关键处理器示例：**\n\n| 处理器 | 功能 | 调用管理器 |\n|--------|------|----------|\n| `create_artifact` | 创建工具输出工件 | `getArtifactManager()` |\n| `get_artifact` | 获取工件引用 | `getArtifactManager()` |\n| `set_governance_policy` | 设置权限策略 | `getGovernance()` |\n| `audit_query` | 查询审计日志 | `getAuditLog()` |\n| `run_decay_cycle` | 运行重要性衰减 | 核心引擎 |\n\n资料来源：[toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n\n---\n\n## ManagerContext 管理器上下文\n\n`ManagerContext` 是与 memoryjs 核心库交互的主要接口，提供对各功能管理器的访问。\n\n### 可用管理器\n\n```mermaid\ngraph LR\n CTX[ManagerContext] --> EM[EntityManager]\n CTX --> RM[RelationManager]\n CTX --> OM[ObservationManager]\n CTX --> SM[SearchManager]\n CTX --> TM[TagManager]\n CTX --> HM[HierarchyManager]\n CTX --> AM[AnalyticsManager]\n CTX --> CM[CompressionManager]\n CTX --> IOM[IOManager]\n CTX --> GT[GraphTraversal]\n CTX --> SS[SemanticSearch]\n CTX --> RS[RankedSearch]\n CTX --> ST[(Storage)]\n```\n\n### 管理器功能表\n\n| 管理器 | 方法 | 功能描述 |\n|--------|------|----------|\n| **EntityManager** | `create`, `get`, `update`, `delete`, `merge` | 图谱节点操作 |\n| **RelationManager** | `create`, `get`, `delete` | 有向边管理 |\n| **ObservationManager** | `add`, `get`, `normalize` | 实体事实附加 |\n| **SearchManager** | `basic`, `ranked`, `boolean`, `fuzzy` | 多种搜索模式 |\n| **SemanticSearch** | `similarity`, `hybrid` | 嵌入向量搜索 |\n| **TagManager** | `add`, `remove`, `bulk`, `score` | 标签管理 |\n| **HierarchyManager** | `parent`, `children`, `subtree` | 层级结构遍历 |\n| **AuditLog** | `query`, `record` | 操作审计 |\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 存储架构\n\n### 存储类型\n\nmemory-mcp 支持两种存储后端，通过环境变量 `MEMORY_STORAGE_TYPE` 切换：\n\n| 存储类型 | 文件 | 配置值 | 适用场景 |\n|----------|------|--------|----------|\n| **JSONL** | `memory.jsonl` | `jsonl` | 小规模数据、开发环境 |\n| **SQLite** | `memory.db` | `sqlite` | 生产环境、大规模数据 |\n\n### 数据文件位置\n\n数据文件位于**项目根目录**（而非 `dist/` 构建目录）：\n\n```\nproject-root/\n├── memory.jsonl # JSONL 存储\n├── memory-saved-searches.jsonl # 保存的搜索\n├── memory-tag-aliases.jsonl # 标签别名\n├── memory.db # SQLite 数据库\n├── dist/ # 构建输出\n│ └── index.js\n└── src/ # 源代码\n └── index.ts\n```\n\n### 存储层抽象\n\n```mermaid\ngraph TB\n subgraph \"应用层\"\n HANDLERS[工具处理器]\n end\n \n subgraph \"存储抽象层\"\n GS[GraphStorage]\n end\n \n subgraph \"后端实现\"\n JSONL[JSONLStorage]\n SQLITE[SQLiteStorage]\n end\n \n HANDLERS --> GS\n GS --> JSONL\n GS --> SQLITE\n```\n\n---\n\n## 工具处理流程\n\n### 完整请求生命周期\n\n```mermaid\nsequenceDiagram\n participant CLI as MCP 客户端\n participant SERVER as MCPServer\n participant DEF as ToolDefinitions\n participant HANDLER as ToolHandler\n participant CTX as ManagerContext\n participant DB as 存储层\n\n CLI->>SERVER: list_tools 请求\n SERVER->>DEF: 获取所有工具定义\n DEF-->>SERVER: 返回工具 schema 数组\n SERVER-->>CLI: 工具列表\n\n CLI->>SERVER: call_tool 请求\n SERVER->>HANDLER: 分派到对应处理器\n HANDLER->>HANDLER: 参数验证\n HANDLER->>CTX: 调用管理器方法\n CTX->>DB: 持久化操作\n DB-->>CTX: 返回数据\n CTX-->>HANDLER: 业务结果\n HANDLER-->>SERVER: 格式化响应\n SERVER-->>CLI: JSON-RPC 响应\n```\n\n### 参数验证模式\n\n所有工具处理器统一使用 Zod 进行参数验证：\n\n```typescript\n// 标准验证模式\nconst validated = validateWithSchema(\n args.paramName, // 待验证值\n z.string().min(1), // Zod schema\n '错误提示信息' // 验证失败消息\n);\n\n// 枚举验证\nz.enum(['option1', 'option2', 'option3']);\n\n// 数字范围验证\nz.number().int().min(1).max(1000);\n```\n\n资料来源：[toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n\n---\n\n## 独立工具集\n\n除 MCP 服务器外，`tools/` 目录还包含独立的命令行工具：\n\n### 工具列表\n\n| 工具 | 文件 | 功能 |\n|------|------|------|\n| **chunking-for-files** | `chunking-for-files.ts` | 将大文件拆分为可编辑的区块 |\n| **compress-for-context** | `compress-for-context.ts` | CTON 格式压缩以适应 LLM 上下文 |\n| **create-dependency-graph** | `create-dependency-graph.ts` | 生成 TypeScript 项目依赖图 |\n| **migrate-from-jsonl-to-sqlite** | `migrate-from-jsonl-to-sqlite.ts` | JSONL 与 SQLite 格式互转 |\n\n### 独立工具架构\n\n```mermaid\ngraph LR\n subgraph \"tools/ 目录\"\n CHUNK[chunking-for-files]\n COMPRESS[compress-for-context]\n DEPS[create-dependency-graph]\n MIGRATE[migrate-from-jsonl-to-sqlite]\n end\n \n CHUNK --> FS[文件系统]\n COMPRESS --> FS\n DEPS --> TS[TypeScript AST]\n MIGRATE --> JSONL[JSONL 解析]\n MIGRATE --> SQL[SQLite]\n```\n\n资料来源：[tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)\n\n---\n\n## 环境配置\n\n### 配置变量表\n\n| 变量名 | 描述 | 默认值 | 资料来源 |\n|--------|------|--------|----------|\n| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl` | [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) |\n| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` | 同上 |\n| `MEMORY_EMBEDDING_PROVIDER` | 嵌入提供商 | `none` | 同上 |\n| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — | 同上 |\n| `MEMORY_EMBEDDING_MODEL` | 嵌入模型名 | `text-embedding-3-small` | 同上 |\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 创建时自动索引 | `false` | 同上 |\n\n---\n\n## 编译与发布\n\n### 构建输出\n\n| 输出物 | 路径 | 说明 |\n|--------|------|------|\n| **构建产物** | `dist/index.js` | TypeScript 编译输出 |\n| **CLI 二进制** | `mcp-server-memory` | package.json 中定义 |\n\n### 发布流程\n\n```bash\n# 1. 设置 npm token\nnpm config set //registry.npmjs.org/:_authToken=$(cat c:\\mcp-servers\\npm_key.txt)\n\n# 2. 发布（prepare 脚本会自动构建）\nnpm publish --access public\n\n# 3. 验证 tarball 内容\nnpm pack --dry-run 2>&1 | grep -E \"jsonl|\\.db|total files|package size\"\n```\n\n**注意：** 发布前必须更新 `package.json` 中的版本号，npm 不会重新发布相同版本。\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 版本演进\n\n| 版本 | 阶段 | 主要内容 |\n|------|------|----------|\n| **v12.3.0** (最新) | Phase 16 | 53 个新工具：排除规则、ADR 双写、结构化上下文、启发式指南、工具调用观察管道、拼写纠正 |\n| **v12.2.0** | Phase 15 | 23 个工具：双时间有效性、OCC、RBAC、程序记忆、主动检索、因果推理、世界模型 |\n| **v2.1.0** | — | memoryjs 核心库升级 |\n\n---\n\n## 扩展指南\n\n### 添加新工具流程\n\n```mermaid\ngraph LR\n A[定义 schema] --> B[添加处理器]\n B --> C[添加 e2e 测试]\n C --> D[更新文档]\n \n subgraph \"步骤 1\"\n A[toolDefinitions.ts]\n end\n \n subgraph \"步骤 2\"\n B[toolHandlers.ts]\n end\n \n subgraph \"步骤 3\"\n C[tests/e2e/tools/]\n end\n```\n\n1. **定义 Schema**：在 `toolDefinitions.ts` 相应类别区域添加 JSON Schema\n2. **实现处理器**：在 `toolHandlers.ts` 注册表中添加处理函数\n3. **编写测试**：在 `tests/e2e/tools/` 添加端到端测试\n\n### 处理器最佳实践\n\n- 使用 `validateWithSchema()` 进行参数验证\n- 大响应使用 `withCompression()` 包装\n- 返回 `formatToolResponse()` 或 `formatTextResponse()`\n\n资料来源：[CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n\n---\n\n## 总结\n\nmemory-mcp 采用清晰的**分层架构**：\n\n1. **协议适配层**处理 MCP 通信\n2. **工具定义层**声明接口契约\n3. **处理层**实现业务逻辑\n4. **核心库层**执行图谱操作\n5. **存储层**管理数据持久化\n\n这种设计使得核心图谱逻辑与 MCP 协议解耦，便于独立演进和测试。通过 213 个精心设计的工具，AI 代理能够高效地存储、检索和管理持久化记忆。\n\n---\n\n\n\n## 数据流处理\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [存储后端](#page-storage-backends), [工具参考手册](#page-tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [src/server/responseCompressor.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/responseCompressor.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)\n \n\n# 数据流处理\n\n## 概述\n\n数据流处理是 memory-mcp 架构的核心机制，负责将 MCP（Model Context Protocol）工具调用转化为底层知识图谱操作，并确保大规模响应的有效传输。该系统采用分层架构，上层为 MCP 服务器，下层为核心库 `@danielsimonjr/memoryjs`，两者通过 `ManagerContext` 进行解耦通信。\n\n**核心职责：**\n- 接收并验证工具调用参数\n- 路由至对应的 Manager 处理器\n- 管理知识图谱实体的 CRUD 操作\n- 对超过 256KB 的大规模响应自动压缩\n- 支持多种存储后端（JSONL / SQLite）\n\n资料来源：[CLAUDE.md:1-5]()\n\n## 系统架构\n\n### 分层架构图\n\n```mermaid\ngraph TD\n subgraph \"memory-mcp (本仓库)\"\n A[\"src/index.ts
入口点\"] --> B[\"MCPServer.ts
MCP服务器\"]\n B --> C[\"toolHandlers.ts
工具处理器\"]\n C --> D[\"responseCompressor.ts
响应压缩器\"]\n end\n \n subgraph \"@danielsimonjr/memoryjs (npm依赖)\"\n E[\"ManagerContext
管理器上下文\"]\n E --> F[\"EntityManager
实体管理器\"]\n E --> G[\"RelationManager
关系管理器\"]\n E --> H[\"SearchManager
搜索管理器\"]\n E --> I[\"ObservationManager
观察管理器\"]\n E --> J[\"IOManager
IO管理器\"]\n end\n \n D --> E\n F --> K[\"GraphStorage
图存储\"]\n G --> K\n H --> K\n I --> K\n J --> K\n \n K --> L[\"JSONL / SQLite
存储后端\"]\n```\n\n资料来源：[CLAUDE.md:10-18]()\n\n### 组件职责表\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| 入口点 | `src/index.ts` | 初始化 MCP 服务器，导出 ManagerContext 别名 |\n| MCP 服务器 | `src/server/MCPServer.ts` | 处理协议握手、工具定义分发 |\n| 工具处理器 | `src/server/toolHandlers.ts` | 工具业务逻辑、参数验证、响应格式化 |\n| 响应压缩器 | `src/server/responseCompressor.ts` | 检测并压缩大规模响应 |\n| ManagerContext | memoryjs 内部 | 懒加载初始化所有管理器实例 |\n\n资料来源：[CLAUDE.md:22-25]()\n\n## 工具处理流程\n\n### 标准处理管道\n\n```mermaid\nsequenceDiagram\n participant Client as MCP客户端\n participant Server as MCPServer\n participant Handler as toolHandlers\n participant Compressor as withCompression\n participant Manager as ManagerContext\n participant Storage as GraphStorage\n\n Client->>Server: 工具调用请求\n Server->>Handler: 路由至对应handler\n \n Handler->>Handler: 参数验证 (zod schemas)\n Handler->>Handler: 数据预处理\n \n Handler->>Manager: 调用manager方法\n Manager->>Storage: 持久化/查询\n \n Storage-->>Manager: 返回结果\n Manager-->>Handler: 格式化响应\n \n Handler->>Compressor: 包装响应\n Compressor->>Compressor: 检查大小 >256KB?\n \n alt 响应过大\n Compressor->>Compressor: CTON压缩\n Compressor-->>Server: 压缩后的JSON\n else 响应正常\n Compressor-->>Server: 原始响应\n end\n \n Server-->>Client: ToolResponse\n```\n\n### 工具处理器模式\n\n所有工具处理器遵循统一模式：`参数验证 → 调用管理器 → 格式化响应` 资料来源：[CLAUDE.md:33-34]()\n\n```typescript\n// 标准处理器示例 - create_artifact\ncreate_artifact: async (ctx, args) => {\n // 1. 参数验证\n const content = validateWithSchema(args.content, z.string().min(1), 'Invalid content');\n const toolName = validateWithSchema(args.toolName, z.string().min(1), 'Invalid toolName');\n const artifactType = validateWithSchema(\n args.artifactType,\n z.enum(['tool_output', 'code_snippet', 'api_response', 'search_result', 'file_content', 'user_input']),\n 'Invalid artifactType'\n );\n \n // 2. 调用管理器\n const artifact = await getArtifactManager(ctx).createArtifact({\n content,\n toolName,\n artifactType,\n description: args.description,\n sessionId: args.sessionId,\n });\n \n // 3. 格式化响应\n return formatToolResponse(artifact);\n},\n```\n\n资料来源：[src/server/toolHandlers.ts:1-25]()\n\n### 参数验证机制\n\n系统使用 `zod` 进行参数模式验证，支持类型约束和错误消息自定义：\n\n```typescript\nfunction validateWithSchema(\n value: unknown,\n schema: z.ZodType,\n errorMessage: string\n): T\n```\n\n验证失败时抛出错误，中断处理流程。 资料来源：[src/server/toolHandlers.ts:3-5]()\n\n### 过滤参数验证\n\n对于可选的过滤参数，采用宽松验证策略——单个无效字段不会导致整个请求失败，而是使用管理器默认值：\n\n```typescript\nfunction parseObservationDedupFilter(args: Record): {\n entityType?: string | string[];\n projectId?: string;\n sessionId?: string;\n minOccurrences?: number;\n maxGroups?: number;\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:85-93]()\n\n## 响应压缩机制\n\n### 压缩触发条件\n\n| 条件 | 阈值 | 处理方式 |\n|------|------|----------|\n| 文本响应大小 | > 256KB | CTON 压缩 |\n| 非文本响应 | 任何大小 | 直接返回 |\n\n资料来源：[src/server/toolHandlers.ts:95-97]()\n\n### 压缩工作流\n\n```mermaid\ngraph TD\n A[\"handler返回ToolResponse\"] --> B{\"textContent?.type
=== 'text'?\"}\n \n B -->|是| C{\"text.length
> 256KB?\"}\n B -->|否| Z[\"直接返回原始响应\"]\n \n C -->|是| D[\"maybeCompressResponse\"]\n C -->|否| Z\n \n D --> E{\"compressed?\"}\n E -->|是| F[\"包装为JSON.stringify
{compressed: true, data}\"]\n E -->|否| Z\n \n F --> G[\"返回压缩后的响应\"]\n Z --> H[\"返回给客户端\"]\n G --> H\n```\n\n### 压缩配置参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | boolean | 实体创建时自动索引嵌入向量 |\n| `MEMORY_EMBEDDING_PROVIDER` | `openai` \\| `local` \\| `none` | 嵌入向量生成提供者 |\n| `MEMORY_EMBEDDING_MODEL` | string | 嵌入模型名称 |\n\n资料来源：[CLAUDE.md:42-48]()\n\n## 存储层数据流\n\n### 存储类型支持\n\n| 存储类型 | 默认路径 | 环境变量 |\n|----------|----------|----------|\n| JSONL | `memory.jsonl` | `MEMORY_STORAGE_TYPE=jsonl` |\n| SQLite | `memory.db` | `MEMORY_STORAGE_TYPE=sqlite` |\n\n存储文件位于**项目根目录**，而非 `dist/` 构建目录。 资料来源：[CLAUDE.md:54-56]()\n\n### 数据流层级\n\n```mermaid\ngraph LR\n subgraph \"访问接口层\"\n A[\"ManagerContext
入口\"]\n end\n \n subgraph \"管理器层\"\n B[\"EntityManager\"]\n C[\"RelationManager\"]\n D[\"SearchManager\"]\n E[\"ObservationManager\"]\n F[\"TagManager\"]\n G[\"HierarchyManager\"]\n end\n \n subgraph \"存储抽象层\"\n H[\"GraphStorage
统一接口\"]\n end\n \n subgraph \"存储实现层\"\n I[\"JSONLStorage\"]\n J[\"SQLiteStorage\"]\n end\n \n A --> B\n A --> C\n A --> D\n A --> E\n A --> F\n A --> G\n \n B --> H\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I\n H --> J\n```\n\n### 可用管理器接口\n\n`ManagerContext` 提供以下管理器访问：\n\n| 管理器 | 访问方式 | 主要功能 |\n|--------|----------|----------|\n| 实体管理 | `ctx.entityManager` | 创建、读取、更新、删除图节点 |\n| 关系管理 | `ctx.relationManager` | 管理有向边 |\n| 观察管理 | `ctx.observationManager` | 附加到实体的观察/事实 |\n| 搜索管理 | `ctx.searchManager` | 基础和高级搜索 |\n| 标签管理 | `ctx.tagManager` | 标签 CRUD 和批量操作 |\n| 层级管理 | `ctx.hierarchyManager` | 父子树结构 |\n| 分析管理 | `ctx.analyticsManager` | 图统计和完整性验证 |\n| 压缩管理 | `ctx.compressionManager` | 去重和自动压缩 |\n| IO 管理 | `ctx.ioManager` | 导入导出操作 |\n| 图遍历 | `ctx.graphTraversal` | BFS/DFS 路径查找 |\n| 语义搜索 | `ctx.semanticSearch` | 嵌入相似度搜索 |\n| 排名搜索 | `ctx.rankedSearch` | TF-IDF 排名搜索 |\n| 存储 | `ctx.storage` | 直接访问 GraphStorage |\n\n资料来源：[CLAUDE.md:25-30]()\n\n## 工具分类数据流\n\n### 按功能分类的处理器组\n\n系统包含 **213 个工具**，分布在 **58 个类别**中：\n\n| 类别 | 数量 | 数据流特点 |\n|------|------|------------|\n| Entity | 4 | 直接写入存储，可能触发自动嵌入索引 |\n| Relation | 2 | 边创建涉及关系完整性验证 |\n| Observation | 3 | 支持规范化处理和去重检测 |\n| Search | 7 | 查询密集型，结果可能超过 256KB 阈值 |\n| Semantic Search | 3 | 嵌入向量计算，延迟较高 |\n| Import/Export | 2 | IO 密集型，大文件处理 |\n| Compression | 4 | 涉及存储重写和数据压缩 |\n\n资料来源：[CLAUDE.md:31-46]()\n\n### 大数据量工具处理\n\n以下工具因可能返回无界结果集而被标记为需要压缩处理：\n\n| 工具名 | 潜在问题 |\n|--------|----------|\n| `read_graph` | 全图数据可能极大 |\n| `search_nodes` | 匹配结果无明确上界 |\n| `get_subtree` | 子树深度不可预测 |\n| `open_nodes` | 展开节点可能指数增长 |\n\n资料来源：[src/server/toolHandlers.ts:98-101]()\n\n## 响应格式化\n\n### 格式化函数\n\n系统提供两种响应格式化函数：\n\n```typescript\n// 结构化响应 - 用于成功操作的 JSON 结构\nfunction formatToolResponse(data: unknown): ToolResponse\n\n// 文本响应 - 用于简单消息或未找到结果\nfunction formatTextResponse(message: string): ToolResponse\n```\n\n### ToolResponse 结构\n\n```typescript\ninterface ToolResponse {\n content: Array<{\n type: 'text';\n text: string | CompressedPayload;\n }>;\n}\n\ninterface CompressedPayload {\n compressed: true;\n originalSize: number;\n compressedSize: number;\n algorithm: 'cton';\n data: string;\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:108-120]()\n\n## 独立压缩工具\n\n除了 MCP 服务器内置的压缩机制，项目还提供独立的命令行压缩工具 `compress-for-context`： 资料来源：[tools/compress-for-context/compress-for-context.ts:1-50]()\n\n### 功能特性\n\n| 功能 | 说明 |\n|------|------|\n| 批量压缩 | 支持批量处理多个文件 |\n| 递归压缩 | 可递归处理子目录 |\n| 格式支持 | JSON、YAML、Markdown、CSV、TSV、Text、Log、TypeScript、JavaScript、XML、HTML |\n| 压缩级别 | light（轻度）、medium（中度）、aggressive（激进） |\n| 解压缩 | 支持从 `.compact` 文件恢复原始内容 |\n\n### 命令行用法\n\n```bash\n# 单文件压缩\nnode compress-for-context.js data.json\nnode compress-for-context.js README.md -l aggressive\n\n# 批量递归压缩\nnode compress-for-context.js -b -r -p \"*.md\" ./docs\n\n# 预览压缩（不写入文件）\nnode compress-for-context.js log.txt --dry-run\n\n# 解压缩\nnode compress-for-context.js -d data.json.compact\n```\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:15-40]()\n\n## 数据迁移工具\n\n### JSONL 与 SQLite 互转\n\n独立工具 `migrate-from-jsonl-to-sqlite` 支持存储格式间的迁移：\n\n```bash\nmigrate-from-jsonl-to-sqlite --from --to [--verbose]\n```\n\n使用 `better-sqlite3` 实现原生 SQLite 性能。 资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30]()\n\n## 测试覆盖\n\n### 测试统计\n\n| 指标 | 数值 |\n|------|------|\n| 测试文件数 | 26 |\n| 测试用例数 | ~665 |\n| 语句覆盖率 | 80.7% |\n| 行覆盖率 | 81.4% |\n| 函数覆盖率 | 79% |\n\n资料来源：[CLAUDE.md:58-59]()\n\n### 数据流相关测试\n\n新增工具应按以下流程添加测试：\n\n1. 在 `tests/e2e/tools/` 目录添加端到端测试\n2. 测试空图和大图场景\n3. 验证导出格式正确性\n4. 验证压缩机制触发条件\n\n资料来源：[CONTRIBUTING.md:25-30]()\n\n## 扩展新工具数据流\n\n### 添加新工具的标准流程\n\n```mermaid\ngraph TD\n A[\"定义工具schema\"] --> B[\"添加handler函数\"]\n B --> C[\"注册到handler映射表\"]\n C --> D[\"添加端到端测试\"]\n D --> E[\"更新文档\"]\n \n subgraph \"步骤1: toolDefinitions.ts\"\n A\n end\n \n subgraph \"步骤2: toolHandlers.ts\"\n B\n end\n \n subgraph \"步骤3: 注册\"\n C\n end\n```\n\n### Handler 注册模式\n\n```typescript\n// 在 toolHandlers.ts 中\nexport const toolHandlers = {\n [TOOL_NAME]: async (ctx, args) => {\n // 1. 参数验证\n // 2. 调用 manager\n // 3. 格式化响应\n },\n};\n```\n\n资料来源：[CLAUDE.md:33-37]()\n\n## 最佳实践\n\n### 性能优化建议\n\n| 场景 | 建议 |\n|------|------|\n| 大结果集查询 | 使用分页参数限制返回量 |\n| 频繁搜索 | 利用 `saved_searches` 缓存查询 |\n| 批量操作 | 优先使用 bulk API 而非循环单条 |\n| 嵌入搜索 | 设置 `MEMORY_AUTO_INDEX_EMBEDDINGS=true` |\n\n### 错误处理\n\n- 参数验证失败：抛出包含具体字段名的错误\n- 存储操作失败：向上传递错误，不做静默处理\n- 网络相关：内存 MCP 无外部网络依赖，此项不适用\n\n### 压缩策略选择\n\n| 压缩级别 | 适用场景 |\n|----------|----------|\n| light | 需要保留可读性的配置文件、日志 |\n| medium | 日常开发文档和中等复杂度数据（默认） |\n| aggressive | 传输给 LLM 的上下文、极限压缩场景 |\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:18-22]()\n\n---\n\n*最后更新：基于 v12.3.0 版本*\n\n---\n\n\n\n## 实体与关系模型\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [存储后端](#page-storage-backends), [层级嵌套](#page-hierarchical-nesting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n \n\n# 实体与关系模型\n\nmemory-mcp 是一个基于 Model Context Protocol 的记忆管理服务器，其核心数据模型采用**属性图模型（Property Graph Model）**。系统以实体（Entity）作为图节点，以关系（Relation）作为有向边，通过观察（Observation）附加事实信息，构建具有语义关联的知识图谱。\n\n资料来源：[CLAUDE.md:1-10]()\n\n## 1. 架构概述\n\nmemory-mcp 的实体与关系模型构建在 `@danielsimonjr/memoryjs` 库之上，通过分层架构提供服务能力。\n\n```mermaid\ngraph TD\n subgraph \"memory-mcp (本仓库)\"\n A[MCPServer] --> B[toolHandlers]\n B --> C[ManagerContext]\n C --> D[memoryjs 核心库]\n end\n \n subgraph \"@danielsimonjr/memoryjs\"\n E[EntityManager]\n F[RelationManager]\n G[ObservationManager]\n H[GraphStorage]\n end\n \n C --> E\n C --> F\n C --> G\n H --> I[(SQLite/JSONL)]\n \n D --> E\n D --> F\n D --> G\n D --> H\n```\n\n### 1.1 核心管理器\n\n| 管理器 | 职责 | 存储后端 |\n|--------|------|----------|\n| EntityManager | 实体 CRUD 操作 | GraphStorage |\n| RelationManager | 关系创建、查询、删除 | GraphStorage |\n| ObservationManager | 观察事实的添加与检索 | GraphStorage |\n| SearchManager | 全文与语义搜索 | 索引层 |\n| TagManager | 标签分类管理 | GraphStorage |\n| HierarchyManager | 层级结构管理 | GraphStorage |\n\n资料来源：[CLAUDE.md:18-28]()\n\n## 2. 实体模型\n\n实体是知识图谱中的核心节点，代表现实世界中的概念对象。\n\n### 2.1 实体数据结构\n\n```typescript\ninterface Entity {\n id: string; // 唯一标识符（UUID）\n name: string; // 实体名称\n entityType?: string; // 实体类型（如 \"person\", \"project\"）\n observations: string[]; // 关联的观察 ID 列表\n tags: string[]; // 标签数组\n metadata?: Record; // 扩展元数据\n importance?: number; // 重要性评分 (0-10)\n createdAt: string; // ISO 时间戳\n updatedAt: string; // ISO 时间戳\n archived?: boolean; // 归档状态\n}\n```\n\n### 2.2 实体操作工具\n\n| 工具名称 | 功能 | 核心参数 |\n|----------|------|----------|\n| create_entity | 创建新实体 | name, entityType, metadata, tags |\n| get_entity | 获取实体详情 | name 或 id |\n| update_entity | 更新实体属性 | name/id, updates |\n| delete_entity | 删除实体 | name 或 id |\n| list_entities | 列出实体 | filter, limit, offset |\n| merge_entities | 合并实体 | sourceIds, targetName |\n| archive_entities | 批量归档 | filter |\n\n资料来源：[src/server/toolDefinitions.ts:1-150]()\n\n### 2.3 实体创建示例\n\n```typescript\n// 工具调用示例：create_entity\n{\n name: \"create_entity\",\n arguments: {\n name: \"Alice Developer\",\n entityType: \"person\",\n metadata: {\n role: \"software_engineer\",\n company: \"TechCorp\"\n },\n tags: [\"developer\", \"ai-expert\"],\n importance: 8\n }\n}\n```\n\n## 3. 关系模型\n\n关系是有向边，连接两个实体并携带语义信息。\n\n### 3.1 关系数据结构\n\n```typescript\ninterface Relation {\n id: string; // 唯一标识符\n from: string; // 源实体 ID 或名称\n to: string; // 目标实体 ID 或名称\n relationType: string; // 关系类型（如 \"works_for\", \"knows\"）\n metadata?: Record; // 关系属性\n bidirectional?: boolean; // 是否双向关系\n createdAt: string;\n}\n```\n\n### 3.2 关系类型示例\n\n| 关系类型 | 语义 | 示例 |\n|----------|------|------|\n| works_for | 雇佣关系 | Alice → TechCorp |\n| knows | 社交关系 | Alice → Bob |\n| created | 创建关系 | Alice → ProjectX |\n| depends_on | 依赖关系 | ModuleA → ModuleB |\n| part_of | 包含关系 | Chapter1 → Book |\n\n### 3.3 关系操作工具\n\n| 工具名称 | 功能 | 核心参数 |\n|----------|------|----------|\n| create_relation | 创建关系 | from, to, relationType, bidirectional |\n| get_relation | 获取关系 | from, to, relationType |\n| delete_relation | 删除关系 | from, to, relationType |\n| list_relations | 列出关系 | filter, entityName, limit |\n\n资料来源：[src/server/toolHandlers.ts:1-100]()\n\n## 4. 观察模型\n\n观察（Observation）是附加在实体上的事实片段，是知识图谱的信息载体。\n\n### 4.1 观察数据结构\n\n```typescript\ninterface Observation {\n id: string; // 唯一标识符\n entityId: string; // 关联实体\n content: string; // 事实内容\n normalizedContent?: string; // 规范化后的内容\n source?: string; // 信息来源\n importance?: number; // 重要性评分\n tags?: string[]; // 观察标签\n metadata?: Record;\n createdAt: string;\n updatedAt: string;\n}\n```\n\n### 4.2 观察操作工具\n\n| 工具名称 | 功能 | 核心参数 |\n|----------|------|----------|\n| create_observation | 添加观察 | entityName/id, content, source, tags |\n| get_observations | 获取观察 | entityName/id, limit |\n| update_observation | 更新观察 | observationId, updates |\n| delete_observation | 删除观察 | observationId |\n| normalize_observation | 规范化文本 | observationId |\n| create_observation_ref | 创建观察引用 | observationId, entityName, relationType |\n\n资料来源：[src/server/toolDefinitions.ts:200-350]()\n\n### 4.3 观察流程图\n\n```mermaid\ngraph LR\n A[实体] -->|关联| B[观察]\n B -->|内容| C[规范化处理]\n C -->|索引| D[SearchManager]\n D -->|检索| E[全文搜索]\n D -->|检索| F[语义搜索]\n \n B --> G[重要性评分]\n G --> H[衰减引擎]\n H --> I[遗忘决策]\n```\n\n## 5. 存储模型\n\n### 5.1 存储类型\n\nmemory-mcp 支持两种存储后端，通过环境变量 `MEMORY_STORAGE_TYPE` 配置。\n\n| 存储类型 | 环境变量 | 文件位置 | 适用场景 |\n|----------|----------|----------|----------|\n| JSONL | `MEMORY_STORAGE_TYPE=jsonl` | memory.jsonl | 小规模数据、开发测试 |\n| SQLite | `MEMORY_STORAGE_TYPE=sqlite` | memory.db | 生产环境、大规模数据 |\n\n资料来源：[CLAUDE.md:50-55]()\n\n### 5.2 数据文件\n\n```bash\n# 项目根目录下的数据文件\nmemory.jsonl # 主数据（JSONL 格式）\nmemory-saved-searches.jsonl # 保存的搜索查询\nmemory-tag-aliases.jsonl # 标签别名映射\nmemory.db # SQLite 数据库\n```\n\n### 5.3 环境变量配置\n\n| 变量名 | 描述 | 默认值 |\n|--------|------|--------|\n| MEMORY_FILE_PATH | 存储文件路径 | memory.jsonl |\n| MEMORY_STORAGE_TYPE | 存储类型 | jsonl |\n| MEMORY_EMBEDDING_PROVIDER | 向量化 provider | none |\n| MEMORY_OPENAI_API_KEY | OpenAI API 密钥 | — |\n| MEMORY_EMBEDDING_MODEL | 向量化模型 | text-embedding-3-small |\n| MEMORY_AUTO_INDEX_EMBEDDINGS | 自动索引嵌入 | false |\n\n资料来源：[CLAUDE.md:45-49]()\n\n## 6. 图遍历与算法\n\n### 6.1 图遍历管理器\n\n`ctx.graphTraversal` 提供图结构遍历能力：\n\n```typescript\n// 可用的遍历方法\nctx.graphTraversal.bfs(from, to); // 广度优先搜索\nctx.graphTraversal.dfs(from, to); // 深度优先搜索\nctx.graphTraversal.findPath(from, to); // 最短路径\nctx.graphTraversal.findAllPaths(from, to); // 所有路径\n```\n\n### 6.2 图算法工具\n\n| 工具名称 | 功能 | 描述 |\n|----------|------|------|\n| find_path | 路径查找 | BFS/DFS 查找两实体间路径 |\n| find_shortest_path | 最短路径 | 实体间的最短关系路径 |\n| find_connected_entities | 连通分量 | 查找所有连通的实体群组 |\n| compute_centrality | 中心性计算 | 计算实体的图中心性指标 |\n\n### 6.3 图遍历示例\n\n```mermaid\ngraph TD\n A[Alice] -->|works_for| B[TechCorp]\n A -->|knows| C[Bob]\n C -->|works_for| B\n A -->|knows| D[Carol]\n D -->|created| E[ProjectX]\n B -->|created| E\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style E fill:#e8f5e8\n```\n\n查询 Alice 到 ProjectX 的路径：\n- Alice → TechCorp → ProjectX（2跳）\n- Alice → Carol → ProjectX（2跳）\n\n## 7. 标签与层级\n\n### 7.1 标签系统\n\n```typescript\n// 标签操作\nctx.tagManager.add(entityId, tag); // 添加标签\nctx.tagManager.remove(entityId, tag); // 移除标签\nctx.tagManager.findByTag(tag); // 按标签查询\nctx.tagManager.setImportance(entityId, score); // 设置重要性\n```\n\n### 7.2 层级结构\n\n```typescript\n// 层级操作\nctx.hierarchyManager.setParent(childId, parentId); // 设置父节点\nctx.hierarchyManager.getChildren(parentId); // 获取子节点\nctx.hierarchyManager.getSubtree(nodeId); // 获取子树\nctx.hierarchyManager.getAncestors(nodeId); // 获取祖先链\n```\n\n## 8. 搜索功能\n\n### 8.1 搜索类型\n\n| 搜索类型 | 工具 | 描述 |\n|----------|------|------|\n| 基础搜索 | search_entities | 关键词全文搜索 |\n| 布尔搜索 | boolean_search | AND/OR/NOT 逻辑组合 |\n| 模糊搜索 | fuzzy_search | 容错匹配 |\n| 语义搜索 | semantic_search | 向量相似度检索 |\n| 排名搜索 | ranked_search | TF-IDF 加权排序 |\n| 自动选择 | auto_select_search | 自适应最佳搜索策略 |\n\n### 8.2 语义搜索配置\n\n启用语义搜索需要配置嵌入模型：\n\n```bash\n# OpenAI 嵌入\nMEMORY_EMBEDDING_PROVIDER=openai\nMEMORY_OPENAI_API_KEY=sk-...\nMEMORY_EMBEDDING_MODEL=text-embedding-3-small\nMEMORY_AUTO_INDEX_EMBEDDINGS=true\n\n# 本地嵌入\nMEMORY_EMBEDDING_PROVIDER=local\nMEMORY_EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2\n```\n\n## 9. 数据导出\n\n### 9.1 导出格式\n\n| 格式 | 工具 | 用途 |\n|------|------|------|\n| JSON | export_graph | 通用数据交换 |\n| CSV | export_graph | 电子表格分析 |\n| Markdown | export_graph | 文档生成 |\n| XML | export_graph | 企业系统集成 |\n| JSON-LD | export_graph | 语义网应用 |\n| GraphML | export_graph | 图可视化工具 |\n\n### 9.2 导出工具\n\n```typescript\n// 导出图数据\nexport_graph({\n format: \"json\", // json|csv|markdown|xml|json-ld\n includeArchived: false,\n redactPii: true // PII 脱敏\n})\n```\n\n资料来源：[CLAUDE.md:30-35]()\n\n## 10. 完整工作流示例\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCPServer\n participant ToolHandlers\n participant EntityManager\n participant GraphStorage\n\n Client->>MCPServer: create_entity\n MCPServer->>ToolHandlers: route to create_entity handler\n ToolHandlers->>EntityManager: createEntity(data)\n EntityManager->>GraphStorage: persist\n GraphStorage-->>EntityManager: entity with id\n EntityManager-->>ToolHandlers: result\n ToolHandlers-->>MCPServer: formatted response\n MCPServer-->>Client: MCP response\n\n Note over Client,GraphStorage: 创建实体后添加观察\n\n Client->>MCPServer: create_observation\n MCPServer->>ToolHandlers: route to create_observation handler\n ToolHandlers->>EntityManager: getEntity(name)\n EntityManager-->>ToolHandlers: entity\n ToolHandlers->>ObservationManager: createObservation(data)\n ObservationManager->>GraphStorage: persist\n GraphStorage-->>ObservationManager: observation with id\n ObservationManager-->>ToolHandlers: result\n ToolHandlers-->>MCPServer: formatted response\n MCPServer-->>Client: MCP response\n```\n\n## 11. 相关资源\n\n- **核心库文档**: [@danielsimonjr/memoryjs](https://www.npmjs.com/package/@danielsimonjr/memoryjs)\n- **项目地址**: https://github.com/danielsimonjr/memory-mcp\n- **npm 包**: @danielsimonjr/memory-mcp\n\n---\n\n\n\n## 存储后端\n\n### 相关页面\n\n相关主题：[实体与关系模型](#page-entities-relations), [数据流处理](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)\n- [tools/migrate-from-jsonl-to-sqlite/README.md](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/README.md)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [SECURITY.md](https://github.com/danielsimonjr/memory-mcp/blob/main/SECURITY.md)\n- [package.json](https://github.com/danielsimonjr/memory-mcp/blob/main/package.json)\n \n\n# 存储后端\n\n## 概述\n\nMemory MCP 的存储后端是整个系统的核心基础设施，负责持久化知识图谱数据。系统支持两种存储格式：**JSONL**（基于文本行的 JSON 格式）和 **SQLite**（关系型数据库）。存储后端通过 `@danielsimonjr/memoryjs` 库提供统一的访问接口，实现了数据的抽象化存储，使得上层业务逻辑无需关心底层存储细节。\n\n项目的存储架构采用分层设计，memory-mcp 作为前端封装，通过 ManagerContext 访问 memoryjs 核心库提供的各种管理器，这些管理器再与底层存储层（GraphStorage 或 SQLiteStorage）进行交互。资料来源：[CLAUDE.md]()\n\n## 支持的存储格式\n\nMemory MCP 支持两种存储后端格式，开发者可根据数据规模、性能需求和使用场景选择合适的格式。\n\n| 格式 | 文件扩展名 | 适用场景 | 性能特点 |\n|------|------------|----------|----------|\n| JSONL | `.jsonl`, `.json` | 小规模数据、简单部署、调试 | 易于阅读和编辑，人类可读 |\n| SQLite | `.db`, `.sqlite`, `.sqlite3` | 大规模数据、生产环境 | 原生 C++ 实现，性能提升 3-10 倍 |\n\nSQLite 后端通过 `better-sqlite3` 原生绑定实现，比 WASM 实现快 3-10 倍。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n## 存储文件布局\n\n根据架构规范，数据文件位于**项目根目录**（而非 `dist/` 输出目录）。这种设计确保了数据文件的独立性和可移植性。\n\n### JSONL 格式文件\n\n```\n项目根目录/\n├── memory.jsonl # 实体和关系数据\n├── memory-saved-searches.jsonl # 保存的搜索查询\n└── memory-tag-aliases.jsonl # 标签别名映射\n```\n\n### SQLite 格式文件\n\n```\n项目根目录/\n└── memory.db # 单一数据库文件（所有数据）\n```\n\n配置环境变量 `MEMORY_STORAGE_TYPE=sqlite` 可启用 SQLite 存储模式。资料来源：[CLAUDE.md]()\n\n## 架构分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ memory-mcp (本项目) │\n├─────────────────────────────────────────────────────────────┤\n│ src/index.ts │ 入口点，重新导出核心类型 │\n│ src/server/MCPServer.ts │ MCP 服务器实现 │\n│ src/server/toolDefs.ts │ 工具定义 │\n│ src/server/toolHandlers │ 工具处理器 │\n└───────────────────────────┼─────────────────────────────────┘\n │ 依赖导入\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ @danielsimonjr/memoryjs (npm 依赖) │\n├─────────────────────────────────────────────────────────────┤\n│ ManagerContext (延迟初始化) │\n│ ├── EntityManager │ 实体管理器 │\n│ ├── RelationManager │ 关系管理器 │\n│ ├── ObservationManager │ 观察数据管理器 │\n│ ├── SearchManager │ 搜索管理器 │\n│ ├── TagManager │ 标签管理器 │\n│ ├── HierarchyManager │ 层级管理器 │\n│ ├── AnalyticsManager │ 分析管理器 │\n│ ├── CompressionManager │ 压缩管理器 │\n│ ├── ArchiveManager │ 归档管理器 │\n│ ├── IOManager │ IO 管理器 │\n│ ├── GraphTraversal │ 图遍历 │\n│ ├── SemanticSearch │ 语义搜索 │\n│ ├── RankedSearch │ 排名搜索 │\n│ └── Storage │ 直接访问 GraphStorage │\n├─────────────────────────────────────────────────────────────┤\n│ 存储层 (GraphStorage) │\n│ ├── SQLiteStorage │ SQLite 原生实现 │\n│ └── JsonlStorage │ JSONL 文件实现 │\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[CLAUDE.md]()\n\n## SQLite 存储特性\n\nSQLite 后端实现了多项企业级特性，以提供高性能和可靠的数据存储。\n\n### 自动全文搜索索引\n\nSQLite 后端会自动创建 **FTS5**（Full-Text Search version 5）索引，启用高级全文搜索功能。这使得系统能够支持复杂的文本搜索查询，无需额外的搜索基础设施。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### WAL 模式\n\nSQLite 数据库启用 **WAL（Write-Ahead Logging）模式**，该模式允许读写操作并发进行，显著提升多客户端访问场景下的性能。WAL 模式相比传统的回滚日志模式，在大多数场景下提供更好的并发性能。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### 原子事务\n\n所有数据写入操作都使用**原子事务**包装，确保在系统崩溃或异常断电情况下的数据完整性。原子事务保证要么所有操作成功提交，要么全部回滚，不会出现部分写入的损坏状态。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n## 存储迁移工具\n\n项目提供了独立的迁移工具 `migrate-from-jsonl-to-sqlite`，支持在两种存储格式之间双向转换。\n\n### 工具位置\n\n```\ntools/\n└── migrate-from-jsonl-to-sqlite/\n ├── migrate-from-jsonl-to-sqlite.ts # TypeScript 源码\n ├── package.json # 工具依赖配置\n └── README.md # 使用文档\n```\n\n### 安装与构建\n\n```bash\ncd tools/migrate-from-jsonl-to-sqlite\nnpm install\nnpm run build\n```\n\n构建完成后可生成 Windows 可执行文件 `migrate-from-jsonl-to-sqlite.exe`。资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### 命令行参数\n\n| 参数 | 简写 | 描述 | 示例 |\n|------|------|------|------|\n| `--from` | `-f` | 源文件路径（JSONL 或 SQLite） | `--from memory.jsonl` |\n| `--to` | `-t` | 目标文件路径（JSONL 或 SQLite） | `--to memory.db` |\n| `--verbose` | `-v` | 显示详细进度信息 | `--verbose` |\n| `--help` | `-h` | 显示帮助信息 | `--help` |\n\n### 使用示例\n\n```bash\n# JSONL 转换为 SQLite\nmigrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db\n\n# SQLite 转换为 JSONL\nmigrate-from-jsonl-to-sqlite --from memory.db --to memory.jsonl\n\n# 使用位置参数\nmigrate-from-jsonl-to-sqlite memory.jsonl memory.db\n\n# 详细输出模式\nmigrate-from-jsonl-to-sqlite -f memory.jsonl -t memory.db -v\n```\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/README.md]()\n\n### 迁移流程\n\n```mermaid\ngraph TD\n A[开始迁移] --> B{检测源文件类型}\n B -->|JSONL| C[loadFromJsonl]\n B -->|SQLite| D[loadFromSqlite]\n C --> E[加载数据到内存]\n D --> E\n E --> F{实体数=0 且 关系数=0?}\n F -->|是| G[输出警告，终止]\n F -->|否| H[写入目标文件]\n H --> I{目标类型}\n I -->|SQLite| J[创建数据库 + FTS5 索引 + WAL 模式]\n I -->|JSONL| K[逐行写入 JSONL]\n J --> L[使用原子事务提交]\n K --> L\n L --> M[迁移完成]\n```\n\n### 注意事项\n\n- 目标文件不存在时会自动创建\n- 目标文件已存在时会**覆盖**原有数据\n- 迁移会保留所有实体、关系和元数据\n- 缺失的时间戳会被设置为迁移时间并输出警告\n- **已保存的搜索**和**标签别名**不会迁移到 SQLite 格式\n- 迁移工具使用 `better-sqlite3` 原生绑定，性能优于 WASM 实现\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts]()\n\n## 核心数据模型\n\nMemory MCP 的存储后端管理以下核心数据结构：\n\n### 实体 (Entity)\n\n实体是知识图谱中的节点，代表独立的概念、对象或事物。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| name | string | 实体名称 |\n| observation | string | 主要观察/描述数据 |\n| metadata | object | 附加元数据 |\n| createdAt | timestamp | 创建时间 |\n| updatedAt | timestamp | 更新时间 |\n\n### 关系 (Relation)\n\n关系是连接两个实体的有向边，定义实体间的关联。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| from | string | 源实体 ID |\n| to | string | 目标实体 ID |\n| relationType | string | 关系类型 |\n\n### 观察数据 (Observation)\n\n观察数据是附加到实体的客观事实，支持数据归一化。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| id | string | 唯一标识符 |\n| entityId | string | 所属实体 ID |\n| content | string | 观察内容 |\n| normalized | object | 归一化后的数据 |\n\n### 产物 (Artifact)\n\n产物是工具输出、代码片段、API 响应等内容的存储容器。\n\n| 字段 | 类型 | 描述 |\n|------|------|------|\n| ref | string | 稳定的引用标识符 |\n| content | string | 产物内容 |\n| toolName | string | 产生该产物的工具名 |\n| artifactType | enum | 产物类型 |\n| sessionId | string | 会话上下文（可选） |\n\n产物类型枚举值包括：`tool_output`、`code_snippet`、`api_response`、`search_result`、`file_content`、`user_input`。资料来源：[src/server/toolDefinitions.ts]()\n\n## 存储配置\n\n### 环境变量\n\n| 变量名 | 值 | 描述 |\n|--------|-----|------|\n| `MEMORY_STORAGE_TYPE` | `sqlite` | 启用 SQLite 存储 |\n| `MEMORY_FILE_PATH` | 文件路径 | 指定自定义存储路径 |\n\n### 安全配置示例\n\n在容器化环境中，建议通过环境变量或 Kubernetes Secret 管理存储路径：\n\n```yaml\napiVersion: v1\nkind: Pod\nspec:\n containers:\n - name: memory-mcp\n env:\n - name: MEMORY_FILE_PATH\n value: \"/secure/path/memory.jsonl\"\n```\n\n资料来源：[SECURITY.md]()\n\n## 安全考量\n\n存储后端的安全性直接影响整体系统的数据保护能力。\n\n### 静态数据安全\n\n| 风险 | 描述 | 缓解措施 |\n|------|------|----------|\n| 文件可读性 | 本地文件可被任何有权限的进程读取 | 限制文件权限，使用专用存储路径 |\n| 无内置加密 | 存储文件未加密 | 依赖文件系统加密或全磁盘加密 |\n| 无访问控制 | 无用户认证授权机制 | 通过系统权限和网络隔离实现 |\n\n### 导出安全\n\nCSV 和 JSON 导出包含完整的实体数据，在分享前应检查敏感信息。GraphML 格式需要正确的 XML 实体转义处理。资料来源：[SECURITY.md]()\n\n### 备份建议\n\n```bash\n# 备份存储文件\ncp memory.jsonl memory.jsonl.backup\n# 或对于 SQLite\ncp memory.db memory.db.backup\n```\n\n## 性能优化\n\n### SQLite 性能特性\n\n| 特性 | 作用 | 性能影响 |\n|------|------|----------|\n| better-sqlite3 原生绑定 | 直接调用 SQLite C 库 | 比 WASM 快 3-10x |\n| WAL 模式 | 支持读写并发 | 提升多客户端性能 |\n| FTS5 全文索引 | 自动创建的全文搜索索引 | 加速文本搜索 |\n| 原子事务 | 保证数据一致性 | 防止数据损坏 |\n\n### 压缩管理\n\n存储后端集成压缩管理器，支持以下操作：\n\n- **重复检测**：识别知识图谱中的重复实体\n- **智能合并**：合并重复数据，保留最新信息\n- **自动压缩**：根据配置阈值自动触发压缩\n- **归档**：将历史数据归档以优化活跃数据访问\n\n资料来源：[CLAUDE.md]()\n\n## 依赖配置\n\n### npm 依赖\n\n```json\n{\n \"dependencies\": {\n \"@danielsimonjr/memoryjs\": \"^2.1.0\",\n \"@modelcontextprotocol/sdk\": \"^1.21.1\",\n \"zod\": \"^3.24.1\"\n }\n}\n```\n\n### 迁移工具依赖\n\n```json\n{\n \"dependencies\": {\n \"better-sqlite3\": \"^11.7.0\"\n },\n \"devDependencies\": {\n \"@types/better-sqlite3\": \"^7.6.12\",\n \"@yao-pkg/pkg\": \"^6.11.0\",\n \"typescript\": \"^5.6.2\"\n }\n}\n```\n\n资料来源：[package.json]()\n\n## 工具构建\n\n项目提供了便捷的脚本用于构建所有独立工具：\n\n```bash\n# 安装所有工具依赖\nnpm run tools:install\n\n# 构建所有工具（包括迁移工具）\nnpm run tools:build\n```\n\n构建后的迁移工具位于 `tools/migrate-from-jsonl-to-sqlite/` 目录，可生成独立的 Windows 可执行文件。资料来源：[package.json]()\n\n## 总结\n\nMemory MCP 的存储后端提供了灵活、高效、可靠的数据持久化能力。通过支持 JSONL 和 SQLite 两种格式，开发者可以根据实际需求选择合适的存储方案。SQLite 后端凭借原生绑定、WAL 模式、FTS5 索引等特性，在生产环境中提供卓越的性能表现。独立的迁移工具简化了格式转换过程，而分层架构则确保了系统的可维护性和扩展性。\n\n---\n\n\n\n## 层级嵌套\n\n### 相关页面\n\n相关主题：[实体与关系模型](#page-entities-relations), [搜索能力](#page-search-capabilities)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts) — 层级工具处理器实现\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts) — 层级工具定义\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md) — 项目架构文档\n \n\n# 层级嵌套\n\n## 概述\n\n层级嵌套（Hieararchy）是 memory-mcp 知识图谱系统中用于管理实体间父子关系和树形结构的核心功能模块。该模块通过 `ctx.hierarchyManager` 提供9个专用工具，支持实体间的父子树构建和子树遍历操作。\n\n层级管理是知识图谱组织结构化信息的重要手段，允许用户将实体组织成树形层级关系，便于表达分类、归属、继承等概念。资料来源：[CLAUDE.md:1]()。\n\n## 架构设计\n\n### 访问方式\n\n层级管理器通过 `ManagerContext` 实例访问：\n\n```typescript\nctx.hierarchyManager\n```\n\n可用的层级操作方法包括：\n\n| 方法 | 功能描述 |\n|------|----------|\n| `setEntityParent(entityName, parentName)` | 设置实体的父节点 |\n| `getChildren(entityName)` | 获取直接子节点 |\n| `getParent(entityName)` | 获取父节点 |\n| `getAncestors(entityName)` | 获取所有祖先节点 |\n| `getDescendants(entityName)` | 获取所有后代节点 |\n| `getSubtree(entityName)` | 获取完整子树结构 |\n\n资料来源：[src/server/toolHandlers.ts:1]()\n\n### 与其他模块的关系\n\n```\n┌─────────────────────────────────────────────┐\n│ ManagerContext │\n├─────────────────────────────────────────────┤\n│ hierarchyManager ──────────────────────────▶│\n│ ├── setEntityParent() │\n│ ├── getChildren() │\n│ ├── getParent() │\n│ ├── getAncestors() │\n│ ├── getDescendants() │\n│ └── getSubtree() │\n└─────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────┐\n│ @danielsimonjr/memoryjs │\n│ (底层存储: EntityManager + 层级索引) │\n└─────────────────────────────────────────────┘\n```\n\n## 工具清单\n\n### 工具分类：Hierarchy（共9个）\n\n| 工具名称 | 功能描述 | 核心参数 |\n|----------|----------|----------|\n| `set_entity_parent` | 设置实体的父节点 | `entityName`, `parentName` |\n| `get_children` | 获取实体的直接子节点 | `entityName` |\n| `get_parent` | 获取实体的直接父节点 | `entityName` |\n| `get_ancestors` | 获取实体的所有祖先节点 | `entityName` |\n| `get_descendants` | 获取实体的所有后代节点 | `entityName` |\n| `get_subtree` | 获取实体的完整子树 | `entityName` |\n\n资料来源：[CLAUDE.md:1]()\n\n## API 详细说明\n\n### set_entity_parent\n\n设置或更新实体的父节点关系。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 要设置父节点的实体名称 |\n| `parentName` | `string \\| null` | 否 | 父实体名称，设为 `null` 可移除父子关系 |\n\n**处理器实现：**\n\n```typescript\nset_entity_parent: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n const parentName = args.parentName !== undefined \n ? validateWithSchema(args.parentName, z.string().min(1).nullable(), 'Invalid parent name') \n : null;\n return formatToolResponse(await ctx.hierarchyManager.setEntityParent(entityName, parentName));\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:1]()\n\n### get_children\n\n获取指定实体的所有直接子节点。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_children: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getChildren(entityName));\n}\n```\n\n### get_parent\n\n获取指定实体的直接父节点。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_parent: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getParent(entityName));\n}\n```\n\n### get_ancestors\n\n获取指定实体的所有祖先节点（从直接父节点到根节点）。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_ancestors: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getAncestors(entityName));\n}\n```\n\n### get_descendants\n\n获取指定实体的所有后代节点（所有子节点、孙节点等）。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 目标实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_descendants: async (ctx, args) => {\n const entityName = validateWithSchema(args.entityName, z.string().min(1), 'Invalid entity name');\n return formatToolResponse(await ctx.hierarchyManager.getDescendants(entityName));\n}\n```\n\n### get_subtree\n\n获取指定实体及其所有后代组成的完整子树结构。\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `entityName` | `string` | 是 | 子树根节点实体名称 |\n\n**处理器实现：**\n\n```typescript\nget_subtree: async (ctx, args) => {\n // 处理器定义（截断显示）\n return formatToolResponse(await ctx.hierarchyManager.getSubtree(entityName));\n}\n```\n\n## 使用流程\n\n### 典型操作流程\n\n```mermaid\ngraph TD\n A[开始] --> B[创建或获取实体]\n B --> C{是否需要设置父子关系}\n C -->|是| D[调用 set_entity_parent]\n C -->|否| E[直接进行层级查询]\n D --> F[关联层级索引]\n F --> G[查询层级关系]\n E --> G\n G --> H{查询类型}\n H -->|直接子节点| I[get_children]\n H -->|父节点| J[get_parent]\n H -->|所有祖先| K[get_ancestors]\n H -->|所有后代| L[get_descendants]\n H -->|完整子树| M[get_subtree]\n I --> N[返回结果]\n J --> N\n K --> N\n L --> N\n M --> N\n N --> O[结束]\n```\n\n### 使用示例\n\n**1. 构建组织层级结构：**\n\n```json\n// 设置公司 -> 部门 -> 团队的层级关系\n{\n \"entityName\": \"后端团队\",\n \"parentName\": \"技术部\"\n}\n```\n\n```json\n{\n \"entityName\": \"技术部\",\n \"parentName\": \"XX公司\"\n}\n```\n\n**2. 查询实体信息：**\n\n```json\n// 获取某实体的所有祖先\n{\n \"entityName\": \"后端团队\"\n}\n```\n\n**3. 遍历子树：**\n\n```json\n// 获取完整子树结构\n{\n \"entityName\": \"XX公司\"\n}\n```\n\n## 层级遍历算法\n\n### 树形结构示意\n\n```\n ┌─────────────┐\n │ 根节点 │\n │ (Root) │\n └──────┬──────┘\n │\n ┌───────────────┼───────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌─────────────┐ ┌─────────────┐ ┌─────────────┐\n │ 节点A │ │ 节点B │ │ 节点C │\n │ (Child 1) │ │ (Child 2) │ │ (Child 3) │\n └──────┬─────┘ └──────┬─────┘ └─────────────┘\n │\n ▼\n ┌─────────────┐\n │ 节点D │\n │ (Grandchild)│\n └─────────────┘\n```\n\n### 各方法返回范围\n\n| 方法 | 返回内容 | 说明 |\n|------|----------|------|\n| `get_parent` | `[A]` | 仅返回直接父节点 |\n| `get_children` | `[A, B, C]` | 仅返回直接子节点 |\n| `get_ancestors` | `[A]` → `[Root]` | 从父到根的完整路径 |\n| `get_descendants` | `[D]` → `[D]` | 所有后代节点的扁平列表 |\n| `get_subtree` | 完整树结构 | 包含根节点及其所有后代 |\n\n## 存储机制\n\n层级关系数据存储于项目的存储文件中，支持两种存储格式：\n\n| 存储类型 | 文件路径 | 说明 |\n|----------|----------|------|\n| JSONL | `memory.jsonl` | 默认存储格式 |\n| SQLite | `memory.db` | 设置 `MEMORY_STORAGE_TYPE=sqlite` 启用 |\n\n层级数据以实体属性的形式存储，由 `memoryjs` 库的底层存储系统管理。资料来源：[CLAUDE.md:1]()\n\n## 错误处理\n\n工具处理器使用 `validateWithSchema` 进行参数校验：\n\n| 错误类型 | 校验规则 | 处理方式 |\n|----------|----------|----------|\n| 空字符串 | `z.string().min(1)` | 返回验证错误信息 |\n| 类型错误 | Zod schema | 返回类型不匹配提示 |\n| 层级不存在 | 运行时检查 | 返回空结果或 `not found` 提示 |\n\n## 最佳实践\n\n### 1. 避免循环引用\n\n设置父子关系时，应避免创建环形结构：\n\n```mermaid\ngraph LR\n A --> B\n B --> C\n C --> A\n```\n\n系统不会自动检测循环引用，创建时请确保层级结构的有效性。\n\n### 2. 合理设置层级深度\n\n过深的层级会增加查询复杂度，建议：\n\n- 保持层级深度在合理范围内（建议 ≤ 10 层）\n- 对于过深的结构，考虑拆分为多个独立树\n\n### 3. 批量操作优化\n\n如需创建多个层级关系，建议按拓扑顺序执行，确保父节点先于子节点存在。\n\n## 相关文档\n\n| 文档 | 路径 | 说明 |\n|------|------|------|\n| 工具定义 | `src/server/toolDefinitions.ts` | 层级工具的 MCP schema 定义 |\n| 工具处理器 | `src/server/toolHandlers.ts` | 层级工具的业务逻辑实现 |\n| 核心架构 | `CLAUDE.md` | 项目整体架构说明 |\n\n## 更新日志\n\n| 版本 | 更新内容 |\n|------|----------|\n| v12.2.0 | 基础层级管理工具集（6个） |\n| v12.3.0 | 扩展层级操作，新增子树查询能力 |\n\n---\n\n\n\n## 搜索能力\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [工具参考手册](#page-tool-reference)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n \n\n# 搜索能力\n\n## 概述\n\nmemory-mcp 的搜索能力是该知识图谱系统的核心功能之一，通过多层架构提供从基础关键词匹配到高级语义理解的全面搜索能力。系统支持超过 20 种搜索工具，涵盖基础搜索、智能搜索、语义搜索三大类别，并提供保存搜索和定时搜索等高级功能。\n\n搜索功能由 `ManagerContext` 中的多个管理器协同工作实现，包括 `SearchManager`（基础和高级搜索）、`semanticSearch`（语义向量搜索）和 `rankedSearch`（TF-IDF 排名搜索）。\n\n## 搜索架构\n\n### 分层搜索模型\n\n```mermaid\ngraph TD\n A[用户查询] --> B[搜索路由层]\n B --> C{查询类型判断}\n C -->|基础关键词| D[SearchManager
基础搜索]\n C -->|TF-IDF排名| E[rankedSearch
排名搜索]\n C -->|向量相似度| F[semanticSearch
语义搜索]\n C -->|时间范围| G[temporalSearch
时序搜索]\n C -->|复合条件| H[IntelligentSearch
智能搜索]\n \n D --> I[GraphStorage
数据存储]\n E --> I\n F --> I\n G --> I\n H --> I\n \n I --> J[结果聚合]\n J --> K[排序与去重]\n K --> L[返回结果]\n```\n\n### 核心组件\n\n| 组件名称 | 类型 | 功能描述 |\n|----------|------|----------|\n| `SearchManager` | 管理器 | 基础搜索、布尔搜索、模糊搜索的入口 |\n| `semanticSearch` | 访问器 | 基于嵌入向量的语义相似度搜索 |\n| `rankedSearch` | 访问器 | TF-IDF 算法的排名搜索 |\n| `SearchByTimeHandler` | 处理器 | 基于时间范围的时序搜索 |\n| `GraphStorage` | 存储层 | 底层图数据库查询接口 |\n\n## 搜索工具分类\n\n### 1. 基础搜索（7 个工具）\n\n基础搜索提供最常用的关键词和模式匹配功能。\n\n| 工具名称 | 功能 | 关键参数 |\n|----------|------|----------|\n| `search_entities` | 基础实体搜索 | `query`, `limit` |\n| `search_by_time` | 时间范围搜索 | `query`, `field`, `since`, `until` |\n| `search_by_relation` | 关系路径搜索 | `entity`, `relationType`, `depth` |\n| `search_by_tag` | 标签关联搜索 | `tags`, `matchAll` |\n| `fuzzy_search` | 模糊匹配搜索 | `query`, `threshold` |\n| `auto_search` | 自动选择最佳搜索 | `query` |\n| `boolean_search` | 布尔逻辑搜索 | `query`, `operators` |\n\n#### 时间范围搜索\n\n`search_by_time` 工具支持时序查询，允许用户限定搜索结果的时间范围：\n\n```typescript\n// toolHandlers.ts 中的实现\nsearch_by_time: async (ctx, args) => {\n const query = validateWithSchema(args.query, z.string().min(1), 'Invalid query');\n const options: { field: string; since?: Date; until?: Date } = {};\n // 支持 since/until 参数进行时间过滤\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:1-50]()\n\n#### 模糊搜索\n\n模糊搜索通过编辑距离算法容忍拼写错误，支持配置相似度阈值：\n\n- `threshold`：相似度阈值（0-1 之间）\n- 自动纠错和建议\n\n### 2. 智能搜索（3 个工具）\n\n智能搜索提供更高级的查询理解和结果优化能力。\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `intelligent_search` | 多层混合搜索，结合多种搜索策略 |\n| `analyze_query` | 查询分析，理解用户意图 |\n| `reflected_search` | 基于反思的搜索优化 |\n\n```mermaid\ngraph LR\n A[原始查询] --> B[analyze_query
查询分析]\n B --> C[查询重写]\n C --> D[intelligent_search
智能搜索]\n D --> E[reflected_search
反思优化]\n E --> F[最终结果]\n```\n\n### 3. 语义搜索（3 个工具）\n\n语义搜索基于嵌入向量（embeddings）实现语义级别的相似度匹配。\n\n| 工具名称 | 功能描述 | 嵌入提供者 |\n|----------|----------|------------|\n| `semantic_search` | 向量相似度搜索 | OpenAI / 本地模型 |\n| `hybrid_search` | 混合向量+关键词搜索 | 两者结合 |\n| `semantic_filter` | 基于语义的过滤 | 两者结合 |\n\n#### 环境配置\n\n```bash\n# 环境变量配置\nMEMORY_EMBEDDING_PROVIDER=openai|local|none # 嵌入提供者\nMEMORY_OPENAI_API_KEY=sk-xxx # OpenAI API 密钥\nMEMORY_EMBEDDING_MODEL=text-embedding-3-small # OpenAI 模型\n # 本地默认: Xenova/all-MiniLM-L6-v2\nMEMORY_AUTO_INDEX_EMBEDDINGS=false # 是否自动索引\n```\n\n资料来源：[CLAUDE.md:95-100]()\n\n### 4. 保存搜索（5 个工具）\n\n保存搜索允许用户存储和重用常用查询。\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `save_search` | 保存当前搜索条件 |\n| `list_saved_searches` | 列出所有保存的搜索 |\n| `execute_saved_search` | 执行已保存的搜索 |\n| `update_saved_search` | 更新保存的搜索 |\n| `delete_saved_search` | 删除保存的搜索 |\n\n保存的搜索存储在 `memory-saved-searches.jsonl` 文件中。\n\n## 搜索 API\n\n### 核心参数\n\n| 参数名 | 类型 | 必填 | 描述 |\n|--------|------|------|------|\n| `query` | string | 是 | 搜索查询字符串 |\n| `limit` | number | 否 | 返回结果数量限制（默认 50） |\n| `offset` | number | 否 | 结果偏移量 |\n| `since` | string | 否 | ISO 8601 格式起始时间 |\n| `until` | string | 否 | ISO 8601 格式结束时间 |\n\n### 搜索工具定义示例\n\n```typescript\n// toolDefinitions.ts 中的时间搜索定义\n{\n name: 'search_by_time',\n description: 'Search for entities by time range and query string',\n inputSchema: {\n type: 'object',\n properties: {\n query: { type: 'string', description: 'Search query' },\n field: { type: 'string', description: 'Time field to search' },\n since: { type: 'string', description: 'Start time (ISO 8601)' },\n until: { type: 'string', description: 'End time (ISO 8601)' },\n },\n required: ['query'],\n },\n}\n```\n\n资料来源：[src/server/toolDefinitions.ts:200-220]()\n\n## 搜索流程\n\n### 完整搜索流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant H as ToolHandler\n participant SM as SearchManager\n participant SS as SemanticSearch\n participant RS as RankedSearch\n participant G as GraphStorage\n\n U->>H: search_entities(query)\n H->>SM: 路由到基础搜索\n \n alt 语义搜索模式\n SM->>SS: 执行向量搜索\n SS->>G: 查询嵌入向量\n G-->>SS: 相似度结果\n SS-->>SM: 语义匹配结果\n end\n \n alt 排名搜索模式\n SM->>RS: 执行TF-IDF排名\n RS->>G: 词频统计\n G-->>RS: 排名结果\n RS-->>SM: 排名匹配结果\n end\n \n SM->>SM: 结果聚合去重\n SM-->>H: 排序后结果\n H-->>U: 返回最终结果\n```\n\n### 查询验证流程\n\n所有搜索请求都经过以下验证流程：\n\n1. **参数校验**：使用 `validateWithSchema` 验证输入参数\n2. **类型检查**：确保数据类型符合 schema 定义\n3. **边界处理**：限制 `limit` 在 1-1000 范围内\n4. **错误处理**：返回格式化的错误信息\n\n```typescript\n// toolHandlers.ts 中的查询验证\nconst limit = args.limit !== undefined\n ? validateWithSchema(args.limit, z.number().int().min(1).max(1000), 'Invalid limit')\n : 50;\n```\n\n## 存储与索引\n\n### 存储位置\n\n搜索索引和数据文件位于项目根目录：\n\n| 文件类型 | 文件路径 | 描述 |\n|----------|----------|------|\n| 主数据 | `memory.jsonl` | 实体和关系数据 |\n| 保存搜索 | `memory-saved-searches.jsonl` | 预设查询 |\n| 标签别名 | `memory-tag-aliases.jsonl` | 标签同义词 |\n| SQLite | `memory.db` | 结构化查询（需配置） |\n\n### 索引策略\n\n| 索引类型 | 触发条件 | 配置项 |\n|----------|----------|--------|\n| 全文索引 | 实体创建时 | `MEMORY_AUTO_INDEX_EMBEDDINGS` |\n| 向量索引 | 嵌入生成后 | 自动 |\n| 标签索引 | 标签赋值时 | 自动 |\n| 时间索引 | 时间字段更新时 | 自动 |\n\n## 最佳实践\n\n### 1. 搜索策略选择\n\n```mermaid\ngraph TD\n A[开始搜索] --> B{知道确切实体名?}\n B -->|是| C{需要语义匹配?}\n B -->|否| D{需要模糊匹配?}\n \n C -->|是| E[semantic_search
语义搜索]\n C -->|否| F{需要排名?}\n \n D -->|是| G[fuzzy_search
模糊搜索]\n D -->|否| H{需要布尔逻辑?}\n \n F -->|是| I[ranked_search
排名搜索]\n F -->|否| J[search_entities
基础搜索]\n \n H -->|是| K[boolean_search
布尔搜索]\n H -->|否| L[auto_search
自动选择]\n```\n\n### 2. 性能优化建议\n\n- **批量搜索**：使用 `list_saved_searches` 预加载常用查询\n- **时间过滤**：在有明确时间范围时使用 `search_by_time`\n- **限制结果**：合理设置 `limit` 参数避免返回过多结果\n- **选择存储**：大数据量场景使用 SQLite 存储\n\n### 3. 常见查询模式\n\n| 场景 | 推荐工具 | 示例 |\n|------|----------|------|\n| 快速查找 | `auto_search` | 未知最佳搜索方式时 |\n| 精确匹配 | `search_entities` | 知道实体名称 |\n| 容忍错别字 | `fuzzy_search` | 用户输入可能有误 |\n| 学术研究 | `semantic_search` | 概念相似但表述不同 |\n| 时间追溯 | `search_by_time` | 查看某时间段的记忆 |\n\n## 总结\n\nmemory-mcp 的搜索能力通过分层架构实现了从基础到高级的完整搜索覆盖。基础搜索满足日常查询需求，智能搜索提供查询理解和优化，语义搜索实现深度的语义理解能力。开发者应根据具体使用场景选择合适的搜索工具，以获得最佳的用户体验和性能表现。\n\n---\n\n\n\n## 高级功能\n\n### 相关页面\n\n相关主题：[搜索能力](#page-search-capabilities), [工具参考手册](#page-tool-reference), [系统架构](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [CONTRIBUTING.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CONTRIBUTING.md)\n- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)\n \n\n# 高级功能\n\nmemory-mcp 是一个基于 Model Context Protocol 的知识图谱管理工具，提供超过 213 个工具，分布在 58 个类别中。Phase 15 和 Phase 16 引入的大量高级功能使该系统具备企业级特性，包括双时态有效性、并发控制、访问控制、程序化记忆、因果推理等能力。\n\n## 1. 版本演进与功能概览\n\nmemory-mcp 的高级功能通过两个主要版本迭代实现：\n\n| 版本 | 版本号 | 新增工具数 | 核心功能 |\n|------|--------|-----------|---------|\n| Phase 15 | v12.2.0 | 23 | 双时态有效性、OCC、RBAC、程序化记忆、主动检索、因果推理、世界模型 |\n| Phase 16 | v12.3.0 | 53 | do_not_remember 排除、决策理由与 ADR 双写、结构化项目上下文、启发式指南、ToolCallObserver 管道、观察去重、拼写纠正 |\n\n资料来源：[CLAUDE.md:3-10]()\n\n## 2. 记忆衰减与优先级管理\n\n系统提供基于时间的记忆重要性衰减机制，用于自动管理长期记忆的价值。\n\n### 2.1 衰减工具\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `run_decay_cycle` | 对所有 agent 记忆执行单次时间衰减，返回衰减和遗忘的记忆数量 |\n| `get_decayed_memories` | 列出重要性降至阈值以下的记忆（不同于 `get_stale_entities` 使用新鲜度时间戳） |\n| `forget_weak_memories` | 批量删除低于衰减阈值的记忆（不同于 `forget_memory` 的内容匹配或 `archive_entities` 的条件移动） |\n\n资料来源：[src/server/toolDefinitions.ts:衰减工具定义]()\n\n### 2.2 衰减流程\n\n```mermaid\ngraph TD\n A[运行 run_decay_cycle] --> B{计算记忆重要性}\n B --> C{是否低于阈值?}\n C -->|是| D[标记为弱记忆]\n C -->|否| E[保留记忆]\n D --> F[get_decayed_memories 查询]\n F --> G{forget_weak_memories}\n G -->|dryRun=true| H[预览待删除列表]\n G -->|dryRun=false| I[批量删除]\n```\n\n### 2.3 阈值配置\n\n- `threshold`：重要性阈值，低于此值将被遗忘（默认 0.1）\n- `maxCount`：单次操作最大遗忘数量\n- `dryRun`：预览模式，不执行实际删除\n\n资料来源：[src/server/toolDefinitions.ts:衰减工具参数]()\n\n## 3. 访问控制与治理\n\nPhase 15 引入的 RBAC 功能提供细粒度的访问控制。\n\n### 3.1 治理策略\n\n| 操作 | 说明 |\n|------|------|\n| `set_governance_policy` | 设置全局治理策略，控制创建、更新、删除权限 |\n| `audit_query` | 查询审计日志，支持按操作类型、agentId、实体名称、时间范围过滤 |\n\n资料来源：[src/server/toolHandlers.ts:治理处理器]()\n\n### 3.2 审计过滤器\n\n```typescript\ninterface AuditFilter {\n operation?: 'create' | 'update' | 'delete' | 'merge' | 'archive';\n agentId?: string;\n entityName?: string;\n fromTime?: string; // 注意：使用 fromTime/toTime 而非 since/until\n toTime?: string;\n}\n```\n\n### 3.3 治理架构\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Tool Call]\n B --> C{Governance Policy Check}\n C -->|canCreate| D[允许创建]\n C -->|canUpdate| E[允许更新]\n C -->|canDelete| F[允许删除]\n C -->|禁止| G[返回权限错误]\n D --> H[写入审计日志]\n E --> H\n F --> H\n H --> I[Audit Log]\n```\n\n资料来源：[src/server/toolHandlers.ts:audit_query 实现]()\n\n## 4. 工件管理系统\n\nArtifacts 是系统用于存储工具输出、代码片段、API 响应等内容的实体。\n\n### 4.1 工件类型\n\n| 类型标识 | 用途 |\n|---------|------|\n| `tool_output` | 工具执行输出 |\n| `code_snippet` | 代码片段 |\n| `api_response` | API 响应数据 |\n| `search_result` | 搜索结果 |\n| `file_content` | 文件内容 |\n| `user_input` | 用户输入 |\n\n资料来源：[src/server/toolDefinitions.ts:工件类型定义]()\n\n### 4.2 工件管理工具\n\n| 工具 | 功能 |\n|------|------|\n| `create_artifact` | 创建带稳定自动生成 ref 的工件实体 |\n| `get_artifact` | 通过 ref 或实体名称检索工件 |\n| `list_artifacts` | 列出工件，支持按 toolName、artifactType、sessionId 过滤 |\n\n### 4.3 工件创建参数\n\n```typescript\n{\n content: string; // 必填：存储为实体观察的内容\n toolName: string; // 必填：生成此工件的来源工具名\n artifactType: ArtifactType; // 必填：工件分类\n description?: string; // 可选：人类可读描述\n sessionId?: string; // 可选：会话上下文，用于分组相关工件\n}\n```\n\n资料来源：[src/server/toolHandlers.ts:工件处理器]()\n\n## 5. 上下文压缩工具\n\n`compress-for-context` 工具用于将大型文件压缩至 LLM 上下文窗口可接受的大小。\n\n### 5.1 压缩级别\n\n| 级别 | 说明 |\n|------|------|\n| `light` | 最小改动，保持可读性 |\n| `medium` | 平衡大小与可读性（默认） |\n| `aggressive` | 最大压缩，可能降低可读性 |\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:压缩级别定义]()\n\n### 5.2 支持格式\n\n- JSON、YAML、Markdown、CSV、TSV\n- Text、Log、TypeScript、JavaScript\n- XML、HTML\n\n### 5.3 使用示例\n\n```bash\n# 单文件压缩\nnode compress-for-context.js data.json\nnode compress-for-context.js README.md -l aggressive\n\n# 批量压缩\nnode compress-for-context.js -b -p \"*.json\" ./src\nnode compress-for-context.js -b -r -p \"*.md\" ./docs\n\n# 解压还原\nnode compress-for-context.js -d input.compact\n```\n\n### 5.4 压缩算法\n\n工具使用类 CTON（Concise Textual Notation）风格的压缩：\n\n- 移除多余空白字符\n- 缩写键名\n- 提取图例（Legend）映射完整名称\n- 批量处理时按缩写长度降序替换以避免冲突\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:压缩实现]()\n\n## 6. 文件分块工具\n\n`chunking-for-files` 工具将大型文件分割为可管理的块。\n\n### 6.1 命令\n\n| 命令 | 功能 |\n|------|------|\n| `split` | 将文件分割为多个块 |\n| `merge` | 合并块文件还原原文件 |\n| `status` | 显示分块状态 |\n\n### 6.2 分块元数据\n\n```typescript\ninterface Manifest {\n version: '1.1.0';\n sourceFile: string; // 原始文件路径\n sourceHash: string; // 原始文件哈希\n createdAt: string; // ISO 时间戳\n fileType: string; // 文件类型\n splitLevel: string; // 分割级别\n chunks: Chunk[]; // 块信息数组\n}\n\ninterface Chunk {\n index: number;\n filename: string;\n title: string;\n startLine: number;\n endLine: number;\n lineCount: number;\n hash: string;\n modified: boolean;\n}\n```\n\n资料来源：[tools/chunking-for-files/chunking-for-files.ts:分块实现]()\n\n### 6.3 分块流程\n\n```mermaid\ngraph TD\n A[输入文件] --> B[解析文件结构]\n B --> C{文件类型}\n C -->|Markdown| D[按标题级别分块]\n C -->|TypeScript| E[按类型声明/函数分块]\n C -->|其他| F[按行数/语义分块]\n D --> G[生成 Manifest]\n E --> G\n F --> G\n G --> H[写入块文件]\n H --> I[生成 manifest.json]\n```\n\n## 7. Phase 16 新增特性 (v12.3.0)\n\n### 7.1 功能分类\n\n| 类别 | 工具数 | 描述 |\n|------|--------|------|\n| `do_not_remember` 排除 | 5 | 主动排除特定记忆被检索 |\n| 决策理由与 ADR 双写 | 10 | 同时生成决策理由和架构决策记录 |\n| 结构化项目上下文 | 12 | 提取和管理项目结构化元数据 |\n| 启发式指南 | 10 | 基于规则的推荐和指导 |\n| ToolCallObserver 管道 | 11 | 工具调用观察和监控 |\n| 观察去重 | 2 | 自动去除重复观察 |\n| 拼写纠正 | 3 | 搜索和输入的拼写纠正 |\n\n资料来源：[CLAUDE.md:6-10]()\n\n### 7.2 ToolCallObserver 管道\n\n该管道允许观察和记录工具调用模式，支持：\n\n- 工具使用频率统计\n- 调用链追踪\n- 异常模式检测\n- 性能监控\n\n### 7.3 观察去重机制\n\n自动检测并合并语义相同的观察，避免知识图谱中的冗余信息。\n\n### 7.4 拼写纠正\n\n支持三种语言的拼写纠正功能，提升搜索准确性：\n\n- 搜索查询的拼写纠正\n- 实体名称的拼写纠正\n- 观察内容的拼写纠正\n\n## 8. 依赖图生成工具\n\n`create-dependency-graph` 工具扫描代码库并生成依赖文档。\n\n### 8.1 功能特性\n\n- 扫描 `src/` 下所有 TypeScript 文件\n- 解析导入和导出\n- 检测循环依赖\n- 生成统计信息\n- 输出 Markdown 和 JSON 两种格式\n\n### 8.2 生成的文档结构\n\n```markdown\ndocs/architecture/\n├── DEPENDENCY_GRAPH.md # 人类可读文档\n└── dependency-graph.json # 机器可读数据\n```\n\n### 8.3 输出内容\n\n| 内容 | 说明 |\n|------|------|\n| 外部依赖 | npm 包依赖 |\n| Node.js 内置依赖 | fs, path 等 |\n| 内部依赖 | 相对路径导入 |\n| 循环依赖分析 | 运行时和类型级别 |\n| 导出统计 | 类、接口、函数、常量数量 |\n\n资料来源：[tools/create-dependency-graph/README.md:功能说明]()\n\n## 9. 存储与迁移\n\n### 9.1 存储格式\n\n| 格式 | 文件位置 | 说明 |\n|------|---------|------|\n| JSONL | `memory.jsonl` | 项目根目录 |\n| SQLite | `memory.db` | 设置 `MEMORY_STORAGE_TYPE=sqlite` |\n\n### 9.2 迁移工具\n\n`migrate-from-jsonl-to-sqlite` 工具支持两种格式的双向转换：\n\n```bash\n# 基本用法\nmigrate-from-jsonl-to-sqlite --from --to \n\n# 详细输出\nmigrate-from-jsonl-to-sqlite --from source.jsonl --to target.db --verbose\n```\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:迁移实现]()\n\n## 10. 环境变量配置\n\n| 变量 | 描述 | 默认值 |\n|------|------|--------|\n| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl` |\n| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` |\n| `MEMORY_EMBEDDING_PROVIDER` | 向量化提供者 | `none` |\n| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — |\n| `MEMORY_EMBEDDING_MODEL` | 向量化模型 | `text-embedding-3-small` |\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 自动索引 | `false` |\n\n资料来源：[CLAUDE.md:环境变量配置]()\n\n## 11. 贡献与扩展指南\n\n### 11.1 添加新工具流程\n\n```mermaid\ngraph TD\n A[定义工具架构] --> B[添加 schema 到 toolDefinitions.ts]\n B --> C[添加处理器到 toolHandlers.ts]\n C --> D[验证参数和错误处理]\n D --> E[添加端到端测试]\n E --> F[更新文档]\n```\n\n### 11.2 代码规范\n\n- 遵循 TypeScript 最佳实践\n- 使用有意义的变量名\n- 公共方法添加 JSDoc 注释\n- 保持函数小而专注\n- 一致缩进（2 空格）\n\n资料来源：[CONTRIBUTING.md:代码风格指南]()\n\n---\n\n\n\n## 工具参考手册\n\n### 相关页面\n\n相关主题：[高级功能](#page-advanced-features), [搜索能力](#page-search-capabilities), [层级嵌套](#page-hierarchical-nesting)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/server/toolDefinitions.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolDefinitions.ts)\n- [src/server/toolHandlers.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/src/server/toolHandlers.ts)\n- [CLAUDE.md](https://github.com/danielsimonjr/memory-mcp/blob/main/CLAUDE.md)\n- [tools/create-dependency-graph/create-dependency-graph.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/create-dependency-graph/create-dependency-graph.ts)\n- [tools/chunking-for-files/chunking-for-files.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/chunking-for-files/chunking-for-files.ts)\n- [tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts)\n- [tools/compress-for-context/compress-for-context.ts](https://github.com/danielsimonjr/memory-mcp/blob/main/tools/compress-for-context/compress-for-context.ts)\n \n\n# 工具参考手册\n\n本文档是 Memory MCP 项目的完整工具参考手册，详细介绍所有 MCP（Model Context Protocol）工具的定义、参数、返回值以及使用方法。\n\n## 概述\n\nMemory MCP 提供了一套基于 Model Context Protocol 的工具集，用于与知识图谱进行交互。该项目包含 **213 个工具**，分布在 **58 个分类**中，涵盖了知识图谱的创建、查询、更新、压缩、导入导出等完整生命周期管理。\n\n### 工具系统架构\n\n工具系统采用分层架构设计：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[MCPServer]\n B --> C[toolHandlers.ts]\n C --> D[memoryjs ManagerContext]\n D --> E[EntityManager]\n D --> F[RelationManager]\n D --> G[ObservationManager]\n D --> H[SearchManager]\n D --> I[TagManager]\n D --> J[其他管理器]\n J --> K[SQLiteStorage]\n J --> L[JSONLStorage]\n```\n\n核心组件包括：\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| 工具定义 | `src/server/toolDefinitions.ts` | 定义所有工具的 JSON Schema |\n| 工具处理器 | `src/server/toolHandlers.ts` | 实现工具的业务逻辑 |\n| 管理器上下文 | `@danielsimonjr/memoryjs` | 提供底层数据操作接口 |\n\n资料来源：[CLAUDE.md:1-10]()\n\n### 工具分类总览\n\n| 分类 | 工具数量 | 核心功能 |\n|------|----------|----------|\n| 实体 (Entity) | 4 | 图谱节点的 CRUD 操作 |\n| 关系 (Relation) | 2 | 实体间的有向边管理 |\n| 观察 (Observation) | 3 | 附加到实体的知识事实 |\n| 搜索 (Search) | 7 | 基础、排名、布尔、模糊搜索 |\n| 智能搜索 (Intelligent Search) | 3 | 混合多层、查询分析、反思搜索 |\n| 语义搜索 (Semantic Search) | 3 | OpenAI 或本地模型的嵌入相似度 |\n| 保存的搜索 (Saved Searches) | 5 | 存储和重用频繁查询 |\n| 标签管理 (Tag Management) | 6 | 标签及其重要性评分 |\n| 标签别名 (Tag Aliases) | 5 | 标签同义词管理 |\n| 层级结构 (Hierarchy) | 9 | 父子树结构和子树遍历 |\n| 图算法 (Graph Algorithms) | 4 | BFS/DFS 路径发现、中心性、连通分量 |\n| 分析 (Analytics) | 2 | 图谱统计和完整性验证 |\n| 压缩 (Compression) | 4 | 重复检测、合并、自动压缩、归档 |\n| 导入/导出 (Import/Export) | 2 | 多种格式的数据交换 |\n\n资料来源：[CLAUDE.md:18-33]()\n\n## 核心实体工具\n\n### 创建实体 (create_entity)\n\n在知识图谱中创建新的实体节点。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| name | string | 是 | 实体名称 |\n| entityType | string | 否 | 实体类型，用于分类 |\n| observations | string[] | 否 | 初始观察/知识列表 |\n| tags | string[] | 否 | 关联标签 |\n| importance | number | 否 | 重要性分数 (0-1) |\n\n**返回值：** 创建成功的实体对象，包含自动生成的唯一引用 ID\n\n### 获取实体 (get_entity)\n\n通过名称或引用 ID 检索实体信息。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用或名称 |\n\n### 更新实体 (update_entity)\n\n修改现有实体的属性。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n| name | string | 否 | 新名称 |\n| entityType | string | 否 | 新类型 |\n| tags | string[] | 否 | 新的标签列表 |\n\n### 删除实体 (delete_entity)\n\n从知识图谱中移除实体及其关联的关系和观察。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 要删除的实体引用 |\n\n## 关系工具\n\n### 创建关系 (create_relation)\n\n在两个实体之间创建有向关系边。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| from | string | 是 | 源实体引用 |\n| to | string | 是 | 目标实体引用 |\n| relationType | string | 是 | 关系类型（如 \"depends_on\"、\"implements\"） |\n| bidirectional | boolean | 否 | 是否双向关系（默认 false） |\n\n### 获取关系 (get_relations)\n\n查询满足特定条件的实体关系。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| from | string | 否 | 源实体过滤 |\n| to | string | 否 | 目标实体过滤 |\n| relationType | string | 否 | 关系类型过滤 |\n\n## 搜索工具\n\n### 基础搜索 (search_entities)\n\n在知识图谱中搜索实体。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 搜索查询词 |\n| limit | number | 否 | 结果上限（默认 10） |\n| entityType | string | 否 | 按类型过滤 |\n\n### 排名搜索 (search_entities_ranked)\n\n基于 TF-IDF 算法的加权排名搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 搜索查询 |\n| limit | number | 否 | 结果上限 |\n| boostRecent | boolean | 否 | 是否提升近期结果 |\n\n### 模糊搜索 (search_entities_fuzzy)\n\n支持拼写容错的模糊匹配搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 可能包含拼写错误的查询 |\n| threshold | number | 否 | 匹配阈值（0-1，默认 0.6） |\n\n### 布尔搜索 (search_entities_boolean)\n\n支持 AND、OR、NOT 运算符的布尔搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 布尔表达式（如 \"AI AND (machine OR deep)\"） |\n\n### 语义搜索 (semantic_search)\n\n基于向量嵌入的语义相似度搜索。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 自然语言查询 |\n| limit | number | 否 | 返回结果数 |\n| provider | string | 否 | 嵌入提供者（openai/local/none） |\n\n资料来源：[CLAUDE.md:26-27]()\n\n## 标签管理工具\n\n### 添加标签 (add_tags)\n\n为实体添加一个或多个标签。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n| tags | string[] | 是 | 要添加的标签列表 |\n\n### 移除标签 (remove_tags)\n\n从实体移除指定标签。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n| tags | string[] | 是 | 要移除的标签列表 |\n\n### 获取标签 (get_tags)\n\n获取实体的所有标签。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 实体引用 |\n\n### 列出所有标签 (list_tags)\n\n返回知识图谱中的所有标签及其使用统计。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| limit | number | 否 | 返回数量上限 |\n\n### 标签别名管理\n\n用于管理标签的同义词和别名关系。\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| create_tag_alias | 创建标签别名映射 |\n| get_tag_alias | 获取标签的别名 |\n| list_tag_aliases | 列出所有标签别名 |\n| delete_tag_alias | 删除标签别名 |\n| resolve_tag_alias | 将别名解析为规范标签 |\n\n## 图算法工具\n\n### 路径发现 (find_path)\n\n使用 BFS 或 DFS 算法查找两个实体之间的路径。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| from | string | 是 | 起始实体 |\n| to | string | 是 | 目标实体 |\n| algorithm | string | 否 | BFS 或 DFS（默认 BFS） |\n| maxDepth | number | 否 | 最大深度限制 |\n\n### 连通分量 (get_connected_components)\n\n识别知识图谱中的连通分量。\n\n### 中心性分析 (calculate_centrality)\n\n计算实体的度中心性或介数中心性。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| entityRef | string | 是 | 实体引用 |\n| type | string | 否 | 中心性类型（degree/betweenness） |\n\n## 导入导出工具\n\n### 导出图谱 (export_graph)\n\n将知识图谱导出为多种格式。\n\n**支持的格式：**\n\n| 格式 | 描述 |\n|------|------|\n| json | 标准 JSON 格式 |\n| jsonl | JSON Lines 格式 |\n| xml | XML 格式 |\n| markdown | Markdown 格式 |\n| csv | CSV 表格格式 |\n| ttl | Turtle RDF 格式 |\n| json-ld | JSON-LD 格式 |\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| format | string | 是 | 输出格式 |\n| includeObservations | boolean | 否 | 是否包含观察数据 |\n| redactPii | boolean | 否 | 是否进行 PII 脱敏 |\n\n资料来源：[CLAUDE.md:32]()\n\n### 导入图谱 (import_graph)\n\n从外部文件导入知识图谱数据。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| source | string | 是 | 导入源（路径或内容） |\n| format | string | 是 | 数据格式 |\n| mergeStrategy | string | 否 | 合并策略（replace/merge/skip） |\n\n## 压缩与归档工具\n\n### 检测重复 (find_duplicates)\n\n识别知识图谱中的重复或高度相似的实体。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| threshold | number | 否 | 相似度阈值（默认 0.85） |\n\n### 合并实体 (merge_entities)\n\n将多个相似实体合并为一个。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| refs | string[] | 是 | 要合并的实体引用列表 |\n| keepRef | string | 否 | 保留的主实体引用 |\n\n### 运行压缩 (run_compression)\n\n自动压缩知识图谱，移除冗余数据。\n\n### 归档旧数据 (archive_old_entities)\n\n将长期未访问的实体移至归档存储。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| daysOld | number | 否 | 天数阈值（默认 90） |\n| archiveType | string | 否 | 归档类型标签 |\n\n## 工件管理工具\n\n用于存储和管理工具输出、代码片段、API 响应等工件。\n\n### 创建工件 (create_artifact)\n\n创建工件实体并获取稳定的自动生成引用。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| content | string | 是 | 工件内容 |\n| toolName | string | 是 | 生成工件的源工具名称 |\n| artifactType | string | 是 | 工件类型枚举 |\n| description | string | 否 | 人类可读描述 |\n| sessionId | string | 否 | 会话上下文标识 |\n\n**artifactType 枚举值：**\n\n| 类型 | 描述 |\n|------|------|\n| tool_output | 工具执行输出 |\n| code_snippet | 代码片段 |\n| api_response | API 响应内容 |\n| search_result | 搜索结果 |\n| file_content | 文件内容 |\n| user_input | 用户输入 |\n\n### 获取工件 (get_artifact)\n\n通过引用或实体名称检索工件。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| ref | string | 是 | 工件引用或实体名称 |\n\n### 列出工件 (list_artifacts)\n\n列出满足过滤条件的工件。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| toolName | string | 否 | 按工具名称过滤 |\n| artifactType | string | 否 | 按类型过滤 |\n| since | string | 否 | ISO 8601 时间过滤 |\n\n## 治理与审计工具\n\n### 设置治理策略 (set_governance_policy)\n\n配置实体的创建、更新、删除权限策略。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| entityType | string | 否 | 应用策略的实体类型 |\n| canCreate | boolean | 是 | 是否允许创建 |\n| canUpdate | boolean | 是 | 是否允许更新 |\n| canDelete | boolean | 是 | 是否允许删除 |\n\n### 审计查询 (audit_query)\n\n查询实体的操作历史日志。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| operation | string | 否 | 操作类型（create/update/delete/merge/archive） |\n| agentId | string | 否 | 代理 ID 过滤 |\n| entityName | string | 否 | 实体名称过滤 |\n| since | string | 否 | 开始时间 |\n| until | string | 否 | 结束时间 |\n| limit | number | 否 | 结果上限（默认 50） |\n\n## 衰减与显著性工具\n\n### 运行衰减周期 (run_decay_cycle)\n\n执行基于时间的显著性衰减计算。\n\n### 获取衰减记忆 (get_decayed_memories)\n\n列出重要性已降至阈值以下的记忆。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| threshold | number | 否 | 重要性阈值（默认 0.1） |\n\n### 遗忘弱记忆 (forget_weak_memories)\n\n批量删除重要性低于衰减阈值的记忆。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| threshold | number | 是 | 重要性阈值 |\n| maxCount | number | 否 | 最大遗忘数量 |\n| dryRun | boolean | 否 | 是否为试运行模式 |\n\n## 时间查询工具\n\n### 按时间搜索 (search_by_time)\n\n基于时间范围查询知识图谱数据。\n\n**输入参数：**\n\n| 参数 | 类型 | 必需 | 描述 |\n|------|------|------|------|\n| query | string | 是 | 查询内容 |\n| startTime | string | 否 | 开始时间 |\n| endTime | string | 否 | 结束时间 |\n| field | string | 否 | 查询字段（created/updated/observed） |\n\n## 独立工具集\n\n项目还包含一组独立的命令行工具，位于 `tools/` 目录下。\n\n### 文件分块工具 (chunking-for-files)\n\n用于将大型文件分割为适合编辑的块，或合并已分割的文件块。\n\n```bash\n# 分割文件\nchunker split [options]\n\n# 合并块\nchunker merge [options]\n\n# 查看状态\nchunker status \n```\n\n**分割选项：**\n\n| 选项 | 描述 |\n|------|------|\n| -o, --output | 输出目录 |\n| -l, --max-lines | 每块最大行数（默认 500） |\n| --by-structure | 按代码结构分割（类、函数等） |\n| --dry-run | 预览分割结果 |\n\n资料来源：[tools/chunking-for-files/chunking-for-files.ts:1-50]()\n\n### 上下文压缩工具 (compress-for-context)\n\n使用 CTON（Context-optimized Notation）压缩格式压缩文件以适应 LLM 上下文窗口。\n\n```bash\n# 单文件压缩\nnode compress-for-context.js data.json\n\n# 批量压缩\nnode compress-for-context.js -b -p \"*.json\" ./src\n\n# 解压缩\nnode compress-for-context.js -d file.compact.json\n```\n\n**压缩级别：**\n\n| 级别 | 描述 |\n|------|------|\n| light | 最小化改动，保留可读性 |\n| medium | 平衡压缩率和可读性（默认） |\n| aggressive | 最大压缩，可能降低可读性 |\n\n资料来源：[tools/compress-for-context/compress-for-context.ts:1-40]()\n\n### 存储迁移工具 (migrate-from-jsonl-to-sqlite)\n\n在 JSONL 和 SQLite 存储格式之间迁移数据。\n\n```bash\n# 从 JSONL 迁移到 SQLite\nmigrate-from-jsonl-to-sqlite --from memory.jsonl --to memory.db\n\n# 从 SQLite 迁移到 JSONL\nmigrate-from-jsonl-to-sqlite --from memory.db --to memory.jsonl\n\n# 详细输出模式\nmigrate-from-jsonl-to-sqlite -f source.jsonl -t target.db -v\n```\n\n资料来源：[tools/migrate-from-jsonl-to-sqlite/migrate-from-jsonl-to-sqlite.ts:1-30]()\n\n### 依赖图生成工具 (create-dependency-graph)\n\n分析 TypeScript 项目并生成依赖关系文档。\n\n```bash\n# 通过 npm 脚本运行（推荐）\nnpm run docs:deps\n\n# 直接使用 tsx 运行\nnpx tsx tools/create-dependency-graph.ts\n```\n\n**输出文件：**\n\n- `docs/architecture/DEPENDENCY_GRAPH.md` - Markdown 格式文档\n- `docs/architecture/dependency-graph.json` - JSON 数据结构\n\n**生成内容包括：**\n\n- 外部依赖（npm 包）\n- Node.js 内置依赖\n- 内部依赖（相对导入）\n- 导出的类、接口、函数、常量\n- 循环依赖分析\n- Mermaid 可视化图表\n- 统计摘要\n\n资料来源：[tools/create-dependency-graph/README.md:1-50]()\n\n## 环境变量配置\n\n工具行为可通过以下环境变量配置：\n\n| 变量 | 描述 | 默认值 |\n|------|------|--------|\n| `MEMORY_FILE_PATH` | 存储文件路径 | `memory.jsonl`（当前目录） |\n| `MEMORY_STORAGE_TYPE` | 存储类型 | `jsonl` |\n| `MEMORY_EMBEDDING_PROVIDER` | 嵌入提供者 | `none` |\n| `MEMORY_OPENAI_API_KEY` | OpenAI API 密钥 | — |\n| `MEMORY_EMBEDDING_MODEL` | 嵌入模型名称 | `text-embedding-3-small` / `Xenova/all-MiniLM-L6-v2` |\n| `MEMORY_AUTO_INDEX_EMBEDDINGS` | 自动索引嵌入 | `false` |\n\n资料来源：[CLAUDE.md:45-52]()\n\n## 添加工具流程\n\n在项目中添加新的 MCP 工具需要以下步骤：\n\n```mermaid\ngraph LR\n A[定义工具 Schema] --> B[实现工具处理器]\n B --> C[添加 E2E 测试]\n C --> D[更新文档]\n \n A1[toolDefinitions.ts] --> |同一分类区域| A\n B1[toolHandlers.ts] --> |handler 逻辑| B\n```\n\n### 步骤 1：定义工具 Schema\n\n在 `src/server/toolDefinitions.ts` 的适当分类区域添加 JSON Schema 定义：\n\n```typescript\n{\n name: 'tool_name',\n description: '工具功能描述',\n inputSchema: {\n type: 'object',\n properties: {\n paramName: { type: 'string', description: '参数描述' }\n },\n required: ['paramName'],\n additionalProperties: false,\n },\n},\n```\n\n### 步骤 2：实现工具处理器\n\n在 `src/server/toolHandlers.ts` 中添加工具处理器：\n\n```typescript\ntool_name: async (ctx, args) => {\n // 1. 验证参数\n const param = validateWithSchema(args.paramName, z.string(), 'Invalid param');\n \n // 2. 调用管理器方法\n const result = await getManager(ctx).method(param);\n \n // 3. 返回格式化响应\n return formatToolResponse(result);\n},\n```\n\n### 步骤 3：添加测试\n\n在 `tests/e2e/tools/` 目录下添加端到端测试。\n\n资料来源：[CLAUDE.md:35-44]()\n\n## 工具响应格式\n\n所有工具返回遵循 MCP 协议的统一响应格式：\n\n```typescript\n// 成功响应\n{\n content: [{ type: 'text', text: JSON.stringify(result) }]\n}\n\n// 错误响应\n{\n isError: true,\n content: [{ type: 'text', text: errorMessage }]\n}\n```\n\n### 格式化辅助函数\n\n| 函数 | 用途 |\n|------|------|\n| `formatToolResponse()` | 格式化工具返回数据为 MCP 响应 |\n| `formatTextResponse()` | 格式化纯文本响应 |\n| `validateWithSchema()` | 使用 Zod schema 验证输入参数 |\n\n## 错误处理\n\n工具调度采用统一的错误处理机制：\n\n```mermaid\ngraph TD\n A[工具调用] --> B[handleToolCall]\n B --> C{执行中异常?}\n C -->|是| D[捕获异常]\n D --> E[返回 MCP 错误响应]\n C -->|否| F[返回正常响应]\n \n E --> G{isError 字段}\n F --> G\n```\n\n`handleToolCall` 会捕获处理器中的所有异常，并将其作为 MCP 格式的错误响应返回。调试时可检查响应的 `isError` 字段。\n\n资料来源：[CLAUDE.md:57-59]()\n\n## 存储后端\n\n工具支持两种存储后端：\n\n### JSONL 存储\n\n- 数据文件：`memory.jsonl`、`memory-saved-searches.jsonl`、`memory-tag-aliases.jsonl`\n- 位于项目根目录\n- 适合小型部署和版本控制\n\n### SQLite 存储\n\n- 数据文件：`memory.db`\n- 设置 `MEMORY_STORAGE_TYPE=sqlite` 启用\n- 使用 `better-sqlite3` 实现原生性能\n- 适合生产环境和大规模数据\n\n资料来源：[CLAUDE.md:12-16]()\n\n## 版本历史\n\n| 版本 | 描述 |\n|------|------|\n| v12.3.0 (Phase 16) | 添加 53 个工具，涵盖 do_not_remember、决策理由、工具能力等 |\n| v12.2.0 (Phase 15) | 添加 23 个工具，支持双时态有效性、OCC、RBAC、程序性记忆等 |\n| v2.1.0 | memoryjs 核心库版本，支持完整工具集 |\n\n资料来源：[CLAUDE.md:3-7]()\n\n---\n\n本参考手册涵盖了 Memory MCP 的所有工具定义和使用方法。如需更多信息，请参考项目文档或查看源代码。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：danielsimonjr/memory-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：danielsimonjr/memory-mcp\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。\n\n## 1. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | README/documentation is current enough for a first validation pass.\n\n## 2. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | last_activity_observed missing\n\n## 3. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n\n## 4. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | no_demo; severity=medium\n\n## 6. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1093926095 | https://github.com/danielsimonjr/memory-mcp | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# memory-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 memory-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Enhanced Model Context Protocol memory server with timestamps, tags, importance, search, and export capabilities 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-quick-start：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-entities-relations：实体与关系模型。围绕“实体与关系模型”模拟一次用户任务，不展示安装或运行结果。\n5. page-storage-backends：存储后端。围绕“存储后端”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quick-start\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-entities-relations\n输入：用户提供的“实体与关系模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-storage-backends\n输入：用户提供的“存储后端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quick-start：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-entities-relations：Step 4 必须围绕“实体与关系模型”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-storage-backends：Step 5 必须围绕“存储后端”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/danielsimonjr/memory-mcp\n- https://github.com/danielsimonjr/memory-mcp#readme\n- README.md\n- package.json\n- docs/guides/MIGRATION.md\n- src/index.ts\n- src/server/MCPServer.ts\n- src/server/toolDefinitions.ts\n- src/server/toolHandlers.ts\n- docs/architecture/ARCHITECTURE.md\n- docs/architecture/COMPONENTS.md\n- docs/architecture/API.md\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 memory-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：danielsimonjr/memory-mcp\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install -g @danielsimonjr/memory-mcp\n```\n\n来源：https://github.com/danielsimonjr/memory-mcp#readme\n\n## 来源\n\n- repo: https://github.com/danielsimonjr/memory-mcp\n- docs: https://github.com/danielsimonjr/memory-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_34874bd3c6f3464c8fd118ee38eb5781"
}