neurodivergent-memory

neurodivergent-memory MCP 服务

📽️ 点击预览

项目预览 这是一个围绕神经多样性思维模式设计的知识图谱 Model Context Protocol 服务。 这个基于 TypeScript 的 MCP 服务实现了一个受神经多样性认知风格启发的记忆系统。它将想法组织到五个区域（知识领域）中，使用BM25 语义排序对搜索结果排序，并将记忆存储为具有双向连接的持久化知识图谱。 设计说明：区域模型源自 FractalSemantics (FractalStat) 寻址，其中每个实体都继承自一个名为 LUCA（Last Universal Common Ancestor，最后的共同祖先）的锚点。这些概念也应用于 Warbler-CDA 和 the seed。五个规范区域是默认架构中 LUCA 的五个直接子节点。后续里程碑中的自定义区域必须声明有效的 LUCA 派生地址，使其祖先关系明确且可追溯，而非依赖假定。

快速开始

Windows

# Download and install Chocolatey:
powershell -c "irm https://community.chocolatey.org/install.ps1|iex"

# Download and install Node.js:
choco install nodejs --version="24.14.1"

# Verify the Node.js version:
node -v # Should print a Node.js 24.x version.

# Verify npm version:
npm -v # Should print an npm 11.x version.

# Run the packaged neurodivergent-memory CLI without a global install
npx neurodivergent-memory@latest init-agent-kit

Linux/macOS

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# in lieu of restarting the shell
. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 24

# Verify the Node.js version:
node -v # Should print a Node.js 24.x version.

# Verify npm version:
npm -v # Should print an npm 11.x version.

# Run the packaged neurodivergent-memory CLI without a global install
npx neurodivergent-memory@latest init-agent-kit

模型流程

flowchart LR
  A[Client MCP Request] --> B[MCP Server Stdio Transport]
  B --> C{Request Type}
  C -->|Tools| D[Tool Handler]
  C -->|Resources| E[Resource Handler]
  C -->|Prompts| F[Prompt Handler]

  D --> G[NeurodivergentMemory Core]
  E --> G
  F --> G

  G --> H[Memory Graph Store]
  G --> I[BM25 Index]
  H --> J[Persisted JSON Snapshot]

  D --> K[MCP JSON Response]
  E --> K
  F --> K
  K --> A

流程说明：

• 记忆操作会同时更新图状态和 BM25 索引。
• 持久化会写入本地快照文件，以便重启后继续使用。
• 所有 MCP 响应均通过 stdio 传输返回。

功能

五个记忆区域

记忆按认知领域组织：

• logical_analysis — 结构化思维、问题解决和分析过程
• emotional_processing — 感受、情绪反应和情感状态
• practical_execution — 面向行动的想法、任务和实施
• vigilant_monitoring — 意识、安全顾虑和防护性思维
• creative_synthesis — 新颖的联系、创意洞见和创新思维

资源

• 通过 memory:// URI 浏览记忆区域和单条记忆
• 每条记忆均包含内容、标签、情绪元数据和连接信息
• 以 JSON 资源形式访问带有完整元数据的记忆

工具

• store_memory — 创建新的记忆节点，可选设置情感效价和强度
• retrieve_memory — 按 ID 获取指定记忆
• update_memory — 修改内容、标签、区域、情感效价、强度或项目归属
• delete_memory — 删除记忆及其所有连接
• connect_memories — 在记忆节点之间创建双向边
• search_memories — 按 BM25 排序的语义搜索，可选目标上下文、近期性偏置和筛选条件（区域、project_id、标签、认知状态、情感效价、强度、min_score）
• traverse_from — 从起始记忆开始，最多遍历 N 跳图结构
• related_to — 结合图邻近度与 BM25 语义结果，查找相关记忆；可选目标上下文和认知状态筛选条件
• list_memories — 分页列出记忆，可选按区域／原型／project_id／认知状态筛选
• memory_stats — 聚合统计数据（总数、按区域／项目统计的数量、访问次数最多的记忆、孤立记忆），可选限定项目范围
• server_handshake — 返回运行时服务身份／版本详情，供客户端显式确认版本
• storage_diagnostics — 在一次响应中显示解析后的快照路径、WAL 路径和实际使用的持久化来源
• import_memories — 从内联 JSON 条目或快照 file_path 批量导入，支持 dry_run、去重策略和显式快照迁移标志
• prepare_memory_city_context — explore_memory_city 的工具镜像，供支持工具但不调用 MCP 提示词的客户端使用
• prepare_synthesis_context — synthesize_memories 的工具镜像，供提示词受限的客户端使用
• prepare_packetized_synthesis_context — synthesize_memory_packets 的工具镜像，供提示词受限或附件受限的客户端使用

提示词

• explore_memory_city — 引导探索各个区域和记忆组织方式
• synthesize_memories — 通过关联现有记忆创建新的见解
• synthesize_memory_packets — 面向附件受限客户端的分包综合提示词；生成一份覆盖清单，以及概述更广泛图结构的有限记忆片段

当 MCP 客户端能够轻松处理大量原始记忆资源时，请使用 synthesize_memories。当调用方路径受附件限制，或需要用少量结构化资源覆盖更广泛的图结构时，请使用 synthesize_memory_packets。

为最大限度地提高与 MCP 客户端的互操作性，服务以两种形式提供相同的综合／探索上下文：

• 通过 prompts/list + prompts/get 提供提示词，供实现 MCP 提示词调用的客户端使用。
• 通过 prepare_*_context 工具提供工具，供支持 MCP 工具但忽略或支持不足提示词的客户端使用。

一些客户端（例如 Cline）会将 MCP 提示词显示为带命名空间的斜杠命令，格式为 /mcp:<server-name>:<prompt-name>，而不是 /<prompt-name>。

核心概念

记忆原型

每条记忆都会被分配一个与其区域对应的原型：

• scholar — logical_analysis
• merchant — practical_execution
• mystic — emotional_processing and creative_synthesis
• guard — vigilant_monitoring

语义排序

搜索采用 Okapi BM25 排序（k1=1.5，b=0.75），无需嵌入或云端调用。结果会归一化至 0–1 的分数范围。

情感元数据

每条记忆都可以选择携带以下信息：

• emotional_valence（-1 到 1）— 情感效价或情绪基调
• intensity（0–1）— 心智能量或重要性权重

认知状态

记忆可以选择携带 epistemic_status，以区分暂定计划和已验证的知识。

• draft — 暂定或以规划为导向
• validated — 已确认，可视为既定事实
• outdated — 已被取代，但为保留历史而留存

当 store_memory 或 import_memories 创建新的 practical_execution 记忆，且未显式指定 epistemic_status 时，如果该记忆带有任务标签，服务会将其默认设为 draft。规范的任务标签是 kind:task，服务也接受兼容性同义标签 type:task 和裸标签 task。这样可以避免规划笔记在不知不觉中被当作既定事实。

项目归属与范围检索

记忆可以选择包含一等属性 project_id，用于多项目图谱中的归属标记和范围检索。

• 写入时（store_memory、update_memory、import_memories）可选提供 project_id。
• update_memory 接受 project_id: null，用于清除现有项目归属。
• search_memories、list_memories 和 memory_stats 接受可选的 project_id 过滤条件。
• search_memories、list_memories 和 related_to 接受可选的 epistemic_statuses 过滤条件，以便调用方在适当时排除过时的规划记忆。
• search_memories 接受可选的 context 和 recency_weight 参数。context 会作为轻量级 BM25 加权融入排序；recency_weight 必须介于 0 和 1 之间，并会增加时间新近度权重，而不会取代语义相关性。
• search_memories 接受 min_intensity / max_intensity 作为首选强度过滤参数名。为保持兼容性，仍支持旧别名 intensity_min / intensity_max。
• related_to 接受可选的 context 参数，使相关记忆排序偏向调用方当前的目标。
• 统计数据现在包含 perProject 分项。
• 范围限定的 memory_stats 仅针对两个端点都在范围内的边报告 totalConnections。
• list_memories 会在每行中包含 project: ... 字段（无项目归属时为 unset）。
• 校验约定：project_id 必须匹配 ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$（最长 64 个字符）。
• 无效值会返回稳定的错误代码 NM_E020，并提供恢复指导。

导入诊断与迁移语义

storage_diagnostics 会报告解析后的快照路径、WAL 路径，以及在持久化路径优先级检查中胜出的配置来源。

import_memories 支持两种来源模式：

• 普通批量预置使用内联 entries。
• 服务快照导入使用 file_path，以避免较大的 MCP 负载。

导入校验标志：

• dry_run: true 会在不写入数据的情况下校验请求，并返回确定性的 would_import、would_skip 和 would_fail 计数。
• dedupe 接受 none、content_hash 或 content_plus_tags。
• 去重后的行会使用稳定的原因代码报告：DEDUPE_CONTENT_HASH 或 DEDUPE_CONTENT_PLUS_TAGS。
• 默认情况下，快照 file_path 导入仅接受解析后的持久化目录下的 .json 文件。仅在有意导入外部快照文件时，才设置 NEURODIVERGENT_MEMORY_IMPORT_ALLOW_EXTERNAL_FILE=true。

快照迁移标志：

• preserve_ids 仅适用于 file_path；与现有存储中的任何 ID 冲突都会被确定性地拒绝。
• merge_connections 仅适用于 file_path；每个被引用的连接目标都必须存在于导入的快照或现有存储中，否则该行会因 INVALID_CONNECTION_TARGET 而校验失败。
• 如果存在校验失败项，非试运行导入会被整体拒绝。重试前先运行 dry_run: true，检查失败列表。

知识图谱持久化

记忆通过预写日志（WAL）和快照模型持久化：

• 每次变更操作都会先追加到 memories.json.wal.jsonl。
• 随后更新内存中的图谱，并定期将其快照保存到 memories.json。
• 启动时，服务会加载 memories.json，重放 WAL 条目，将内容压缩到新的快照中，然后截断 WAL。

与仅使用快照进行持久化相比，这种方式能改善崩溃恢复行为。

如需明确指定设置，请设置以下环境变量之一：

• NEURODIVERGENT_MEMORY_DIR：选择包含 memories.json 的目录
• NEURODIVERGENT_MEMORY_FILE：指定具体的快照文件
• NEURODIVERGENT_MEMORY_MAX：限制记忆总数（整数；默认不限制）
• NEURODIVERGENT_MEMORY_EVICTION：达到上限时选择淘汰策略：
  • lru（默认）
  • access_frequency
  • district_priority

挂载到 /home/node/.neurodivergent-memory 的方式仍然有效，无需覆盖任何环境变量——这是容器中 node 用户的主目录，系统会自动检查此路径。

⚠️ 重大变更（v0.2.0）： 镜像以 node 用户身份运行，且无法读取 /root，因此之前挂载到 /root/.neurodivergent-memory 的内容会被静默跳过。Agent 可能会看起来丢失了所有记忆。请参阅下文的升级后恢复记忆。

升级后恢复记忆

如果你之前将数据挂载到 /root/.neurodivergent-memory，快照仍完好保存在主机卷中。请使用以下任一方式重新挂载：

选项 A — 显式挂载到 /data（推荐）：

"-e", "NEURODIVERGENT_MEMORY_DIR=/data",
"-v", "mydata:/data"

选项 B — 挂载到 node 用户已拥有的路径：

"-v", "mydata:/home/node/.neurodivergent-memory"

选项 B 无需覆盖 NEURODIVERGENT_MEMORY_DIR——服务会自动找到现有快照。

对于 Agent：如果升级容器后记忆看似丢失，请使用 import_memories 从备份导出文件重新加载，或在正确重新挂载卷后，请 AI 助手重新运行 memory_stats 以确认记忆已恢复。

多层记忆持久化

该服务支持三层记忆架构，适用于跨多个项目工作的 Agent。每一层 都存储在独立目录中，可单独同步。

层级	用途	常见路径	环境变量
项目	作用于代码仓库的记忆——临时，适合 CI	.github/agent-kit/memories	NEURODIVERGENT_MEMORY_PROJECT_DIR
用户	跨项目个人知识——持久，按开发者区分	~/.neurodivergent-memory	NEURODIVERGENT_MEMORY_USER_DIR
组织	共享的组织知识——可选，团队共用	任意共享挂载点	NEURODIVERGENT_MEMORY_ORG_DIR

主服务仍会从 NEURODIVERGENT_MEMORY_DIR（或自动发现的默认路径）读取当前使用的快照。层级变量仅供 sync-memories 辅助工具使用。

为记忆添加同步标签

为需要提升到用户层或组织层的记忆添加 persistence:durable 标签。不含此标签的记忆会被视为临时记忆，并保留在项目层。

["topic:typescript", "scope:global", "kind:pattern", "layer:architecture", "persistence:durable"]

对于你永远不希望提升的记忆，可使用 persistence:ephemeral 明确选择不提升。

在各层之间同步记忆

在构建、里程碑或会话结束后，将项目层中的持久记忆提升到用户层：

NEURODIVERGENT_MEMORY_PROJECT_DIR=.github/agent-kit/memories \
NEURODIVERGENT_MEMORY_USER_DIR=~/.neurodivergent-memory \
  npm run sync-memories -- --from project --to user

或者使用显式路径：

node build/scripts/sync-memories.js \
  --from .github/agent-kit/memories \
  --to ~/.neurodivergent-memory

完整选项参考：

--from <path|tier>      Source snapshot directory, or tier name: project | user | org
--to   <path|tier>      Target snapshot directory, or tier name: project | user | org
--tags <tag1,tag2,...>  Promote only memories matching ALL listed tags (default: persistence:durable)
--any-tag               Match memories that have ANY of the listed tags (OR logic)
--dry-run               Report counts without writing any data

安全提示： 运行同步前，请停止目标层的 MCP 服务——脚本会直接写入快照文件；如果检测到目标目录中存在打开的 WAL，则会发出警告。

发布安全

• GitHub Actions 使用 Node.js 24 LTS 运行 CI 和发布自动化
• npm 发布使用 OIDC 来源证明，并运行 npm publish --provenance --access public
• Docker 镜像使用 Buildx 构建并发布到 Docker Hub，同时生成 SBOM 和 来源证明元数据
• GitHub Actions 为 npm 压缩包和推送的容器镜像摘要生成制品证明
• 带标签的发布会将 npm 压缩包、校验和及证明包上传为发布资源

开发 RC 频道

推送到 development 分支会使用相同的 npm 包名称（neurodivergent-memory）和容器仓库发布候选版本。

• npm 预发布版本以 0.x.x-rc.N 格式发布，npm dist-tag 为 rc。
• npm 预发布版本后缀 N 使用 run_number.run_attempt，以避免工作流重新运行时发生冲突。
• Docker 镜像仅使用不可变的 rc-0.x.x-rc.N 标签发布，其中 N 根据 run_number.run_attempt 得出。
• RC 构建对应的 GitHub 发布会标记为预发布版本。

这些构建的稳定性有意低于研究预览版本线，仅应用于验证和早期集成测试。

在线就绪冒烟测试（project_id）

使用确定性的在线冒烟测试工具，端到端验证 project_id 归属与范围检索：

• 本地构建目标：

npm run smoke:project-id

• 最新 Docker RC 目标（PowerShell）：

$rc = (Invoke-RestMethod -Uri "https://hub.docker.com/v2/repositories/twgbellok/neurodivergent-memory/tags?page_size=25").results |
  Where-Object { $_.name -match '^rc-' } |
  Sort-Object { $_.last_updated } -Descending |
  Select-Object -First 1 -ExpandProperty name
node test/live-project-id-smoke.mjs "docker run --rm -i twgbellok/neurodivergent-memory:$rc"

断言失败时，冒烟测试工具会以非零状态码退出，适合作为发布就绪门禁。

错误约定

修改和查找工具发生故障时，会在文本响应中返回稳定的、面向运维人员的格式：

❌ <summary>
Code: NM_EXXX
Message: Human-readable failure summary
Recovery: Suggested next action

开头的摘要行会根据上下文变化，而 Code/Message/Recovery 块对运维人员而言保持稳定，便于解析和搜索。这样既能让 MCP 响应在聊天客户端中易于阅读，也能为运维人员提供可在日志和发布说明中搜索的稳定代码。使用 Pino 将结构化日志写入 stderr，并在已知故障路径中包含相同的 code 字段。

并发安全

通过异步互斥锁对修改工具进行串行化，防止多个 Agent 同时调用服务时发生并发写入竞争。

写入队列行为：

• 待处理写入操作的数量受 NEURODIVERGENT_MEMORY_QUEUE_DEPTH 限制（默认值：50）。
• 队列已满时，修改工具会返回 NM_E010，并附带提示重试的恢复消息。
• 队列达到高水位和清空时的状态转换会以结构化 Pino 警告记录。

WIP 防护机制行为：

• 当任务标签包含进行中标记时，store_memory 会检查每个 agent_id 的实际进行中任务饱和度。
• 上限由 NEURODIVERGENT_MEMORY_WIP_LIMIT 控制（默认值：1；设为 0 可禁用）。
• 超出上限时，工具响应中会发出警告，并记录 NM_E011，供运维人员查看。

循环遥测与防护措施

服务器会跟踪循环信号，并提供有针对性的防护措施响应：

• store_memory 的重复检测会将传入内容与最近 10 条记忆进行比较（如果提供了 agent_id，则仅比较相同 agent_id 的记忆），使用与分词器一致的令牌重叠评分，并提供精确匹配快速路径。
• 达到重复阈值的存储会设置 repeat_detected: true，递增匹配记忆的 repeat_write_count，并在工具响应中添加 No net-new info 警告。
• 多次读取 emotional_processing 记忆的 logical_analysis 操作会在超过配置的阈值后添加 distill_memory 建议。
• 系统会在滚动操作窗口中跟踪读写乒乓转换，在满足阈值条件时递增 ping_pong_counter，并可选择启动临时的跨分区写入冷却期。
• memory_stats 现在包含一个 loop_telemetry 区块，其中有：
  • repeat_write_candidates（前 5 项）
  • ping_pong_candidates（前 5 项）
  • recent_high_similarity_writes（最近 5 项）

配置：

• NEURODIVERGENT_MEMORY_REPEAT_THRESHOLD（默认值：0.85）
• NEURODIVERGENT_MEMORY_LOOP_WINDOW（默认值：20）
• NEURODIVERGENT_MEMORY_PING_PONG_THRESHOLD（默认值：3）
• NEURODIVERGENT_MEMORY_DISTILL_SUGGEST_THRESHOLD（默认值：3）
• NEURODIVERGENT_MEMORY_CROSS_DISTRICT_COOLDOWN_MS（默认值：0，已禁用）

性能基准基线

Issue #19 添加了一个确定性基准测试工具，用于针对已构建的服务器进行端到端 MCP stdio 测量。

运行方式：

npm run benchmark

基准测试会：

• 使用隔离的临时持久化目录，因此不会修改本地记忆图谱。
• 为每个数据集层级植入数据，然后测量目标层级下 100 次写入的 store_memory 吞吐量。
• 在包含 1k、5k 和 10k 条记忆的数据集上，通过 100 次迭代测量 search_memories 和 list_memories 的延迟。
• 在包含 500 条记忆的连通图谱上，测量深度为 2、3 和 5 时的 traverse_from 延迟。
• 将结构化 JSON 报告打印到 stdout，便于自动化捕获。
• 将每次运行的输出写入 benchmark-results/ 目录下带时间戳的文件。
• 还会写入滚动更新的最新结果别名：
  • benchmark-results/memory-benchmark-latest.json
  • benchmark-results/memory-benchmark-latest.md

此外，还提供一个便捷别名：

npm run bench

已提交的基线用于 RC 与稳定版本之间的相对回归比较，并不代表不同机器上通用的绝对性能保证。

若要有意就地刷新已提交的基线文件：

npm run benchmark -- --update-baseline

开发

安装依赖：

npm install

构建服务器：

npm run build

在开发期间启用自动重新构建：

npm run watch

安装

若要与 Claude Desktop 配合使用，请添加服务器配置：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

使用 npm：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "command": "npx",
      "args": ["neurodivergent-memory"]
    }
  }
}

使用 Docker：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEURODIVERGENT_MEMORY_DIR=/data",
        "-v",
        "neurodivergent-memory-data:/data",
        "docker.io/twgbellok/neurodivergent-memory:0.3.0"
      ]
    }
  }
}

完全自动批准的工具：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "autoApprove": [
        "store_memory",
        "retrieve_memory",
        "connect_memories",
        "search_memories",
        "update_memory",
        "delete_memory",
        "traverse_from",
        "related_to",
        "list_memories",
        "memory_stats",
        "storage_diagnostics",
        "import_memories",
        "distill_memory",
        "prepare_memory_city_context",
        "prepare_synthesis_context",
        "prepare_packetized_synthesis_context",
        "register_district"
      ],
      "disabled": false,
      "timeout": 120,
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEURODIVERGENT_MEMORY_DIR=/data",
        "-v",
        "neurodivergent-memory-data:/data",
        "docker.io/twgbellok/neurodivergent-memory:0.3.0"
      ],
      "env": {}
    }
  }
}

若要在 Github Copilot Agent Workflows 中使用 MCP 服务（github 每次都会启动一个新的 VM，因此工作流之间无法共享记忆。会话记忆可用，但会在作业完成时清除）：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "[email protected]"
      ],
      "env": {
        "NEURODIVERGENT_MEMORY_DIR": ".neurodivergent-memory"
      },
      "tools": [
        "retrieve_memory",
        "connect_memories",
        "update_memory",
        "delete_memory",
        "traverse_from",
        "related_to",
        "import_memories",
        "storage_diagnostics",
        "distill_memory",
        "prepare_memory_city_context",
        "prepare_synthesis_context",
        "prepare_packetized_synthesis_context",
        "register_district",
        "list_memories",
        "store_memory",
        "search_memories",
        "memory_stats"
      ]
    }
  }
}

若要为每个项目单独隔离，而不是使用共享的全局记忆文件，请挂载项目专用的主机目录，并保持容器内的目标路径不变。请使用适用于操作系统的路径分隔符：

• Windows：${workspaceFolder}\.neurodivergent-memory:/data
• macOS / Linux：${workspaceFolder}/.neurodivergent-memory:/data

{
  "mcpServers": {
    "neurodivergent-memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEURODIVERGENT_MEMORY_DIR=/data",
        "-v",
        "${workspaceFolder}/.neurodivergent-memory:/data",
        "docker.io/twgbellok/neurodivergent-memory:0.3.0"
      ]
    }
  }
}

注意： 在 Windows 上将 / 替换为 \：${workspaceFolder}\.neurodivergent-memory:/data

Docker 运行时

请使用明确的版本标签。发布的 Docker 镜像不会维护浮动的 latest 标签。

你也可以直接运行打包好的服务器镜像：

docker run --rm -i twgbellok/neurodivergent-memory:0.3.0

调试

由于 MCP 服务通过 stdio 通信，调试可能颇具挑战。我们建议使用 MCP Inspector，它可作为包脚本使用：

npm run inspector

Inspector 会提供一个 URL，供你在浏览器中访问调试工具。

Agent 工作流设置

此仓库附带一套可复用的Agent 自定义工具包，其编写源文件位于 .github/agent-kit/。 请使用打包好的安装程序，将这些模板写入使用者仓库的 .github/... 文件夹，而不是在此仓库中跟踪实时生成的 Agent 文件。

内容

文件	用途
templates/neurodivergent-agent.agent.md	功能完整的记忆驱动开发协调 Agent。分为五个阶段：提取上下文 → 研究 → 改进记忆 → 规划 → 执行并交接。
templates/memory-driven-template.agent.md	精简的通用 Agent 模板；如果你想在此基础上构建自己的工作流，它是更轻量的起点。
templates/nd-memory-workflow.instructions.md	共享指令文件，可在日常编码会话中强化记忆驱动习惯，而无需显式调用 Agent。
templates/setup-nd-memory.prompt.md	引导式设置提示词，会先让用户选择安装策略，再进行任何安装。
templates/copilot-instructions.md	GitHub Copilot 会话的引导参考文件，包含标签架构、区域表、工具速查和会话检查清单。
templates/explore_memory_city.prompt.md	用于引导探索记忆区域和图结构的提示词。
templates/memory-driven-issue-execution.prompt.md	用于执行已跟踪问题的提示词，包含完整的记忆驱动上下文（提取 → 规划 → 执行 → 更新）。

将工具包安装到项目中

将当前打包的工具包安装到你所在的仓库中：

npx neurodivergent-memory@latest init-agent-kit

可用选项：

• --target <path> 将工具包安装到其他仓库根目录。
• --dry-run 显示将要复制的内容，但不写入文件。
• --force 覆盖现有目标文件。
• --mode prompt-first|auto-setup 在命令输出中记录预期的安装策略，同时保持模板文本不变。

安装程序会将模板复制到标准自定义位置，例如 .github/agents/、.github/instructions/、.github/prompts/ 和 .github/copilot-instructions.md。

编写源文件和生成文件

权威源文件仍位于 .github/agent-kit/templates/。已安装的实时 Agent 文件 .github/agents/neurodivergent-agent.agent.md 被有意视为生成的使用者状态，而不是受版本控制的仓库文件，这样远程 Copilot 更新就不会持续将其从此仓库中删除。

手动复制备用方案

复制你需要的文件到项目的标准自定义位置——不要移动它们，这样原始文件仍可供未来的 Agent 或贡献者参考。

适用的目标目录因 Agent 平台而异。使用 Agent 原生读取的任意位置即可。常见示例：

• .github/agents/ 用于 Agent 定义
• .github/instructions/ 用于共享指令
• .github/prompts/ 用于提示词
• .github/ 根目录用于 copilot-instructions.md

安装策略确认

在任何项目中安装 neurodivergent-memory MCP 之前，请先询问用户要采用哪种策略：

• prompt-first（默认）——安装前征求明确批准。
• auto-setup——无需询问，自动安装。

更新导入的 Agent 文件中的安装部分，以反映所选策略。如果用户未说明偏好，则默认为 prompt-first。

附录

以下是一个 copilot-instructions.md 示例

# neurodivergent-memory — Agent Bootstrap Instructions

This file is automatically read by GitHub Copilot and compatible agents at the start of every session.
It replaces the need to fetch the governance memory (`memory_11`) before working with this MCP server.

---

## What this server is

`neurodivergent-memory` is a **Model Context Protocol (MCP) server** that stores and retrieves memories as a
knowledge graph. It is designed for neurodivergent thinking patterns: non-linear, associative, tag-rich.

Memories are organised into five **districts** (knowledge domains) and connected via bidirectional edges.
Search uses **BM25 semantic ranking** — no embedding model or cloud LLM required.

---

## Canonical Tag Schema

Always apply tags from the five namespaces below when calling `store_memory`.
Multiple tags from different namespaces are expected on every memory.
When storing execution-heavy memories, include the reasoning behind the action and, when possible, connect the entry to a durable principle in `logical_analysis` or `creative_synthesis` so retrieval preserves understanding and not just activity.

| Namespace | Purpose | Examples |
|---|---|---|
| `topic:X` | Subject matter / domain | `topic:unity-ecs`, `topic:adhd-strategies`, `topic:rust-async` |
| `scope:X` | Breadth of the memory | `scope:concept`, `scope:project`, `scope:session`, `scope:global` |
| `kind:X` | Type of knowledge | `kind:insight`, `kind:decision`, `kind:pattern`, `kind:reference`, `kind:task` |
| `layer:X` | Abstraction level | `layer:architecture`, `layer:implementation`, `layer:debugging`, `layer:research` |
| `persistence:X` | Sync-tier eligibility | `persistence:durable`, `persistence:ephemeral` |

**Example tag set for a Unity ECS memory:**

```json
["topic:unity-ecs", "topic:dots", "scope:project", "kind:pattern", "layer:architecture"]

适用于持久化跨项目记忆的示例标签集：

["topic:typescript", "scope:global", "kind:pattern", "layer:architecture", "persistence:durable"]

---

区域

键	用途
logical_analysis	结构化思考、分析、研究发现
emotional_processing	感受、情绪状态、情感反应
practical_execution	任务、计划、实现、行动事项
vigilant_monitoring	风险、警告、约束、安全问题
creative_synthesis	新颖的联系、创意想法、跨领域洞见

---

可用的 MCP 工具（快速参考）

工具	用途
store_memory	创建新的记忆节点
retrieve_memory	按 ID 获取一条记忆
update_memory	修改内容、标签、区域、效价或强度
delete_memory	移除一条记忆及其所有连接
connect_memories	在两个记忆节点之间添加边
search_memories	按 BM25 排序搜索，可选用 context、recency_weight、min_score、区域、标签、效价和强度筛选
traverse_from	从一个节点开始，以 BFS 图遍历方式最多经过 N 跳
related_to	为指定记忆 ID 融合跳数邻近度与 BM25，可选提升目标上下文权重
list_memories	分页列出所有已存储记忆
memory_stats	记忆总数、各区域／各项目计数、访问次数最多的记忆及孤立记忆
storage_diagnostics	解析后的快照路径、WAL 路径及实际持久化来源
import_memories	从内联条目或快照文件批量导入，支持试运行和迁移控制
distill_memory	将 emotional_processing 记忆转化为结构化的逻辑产物
prepare_memory_city_context	面向提示词受限客户端的 explore_memory_city 工具镜像
prepare_synthesis_context	面向提示词受限客户端的 synthesize_memories 工具镜像
prepare_packetized_synthesis_context	面向附件受限客户端的 synthesize_memory_packets 工具镜像
register_district	注册自定义区域，并验证其 LUCA 祖先关系

---

持久化

每次写入时，记忆都会自动保存到 ~/.neurodivergent-memory/memories.json。 服务启动时会恢复图；重启后不会丢失数据。

---

记忆质量防护准则

• 不要只停留在“发生了什么”。重要记忆应记录采取行动的原因、背后的权衡或原则，以及这一洞见是否可复用。
• 将 practical_execution 视为行动日志；如果更深层的理由应比实现细节留存得更久，就将其与 logical_analysis 或 creative_synthesis 配对。
• 当调试过程、交接内容或情绪／原始记忆过于杂乱时，使用 distill_memory 或明确的后续记忆，在去除偶然细节的同时保留关键信息。
• 优先采用关联式综合，而非孤立的任务日志：将实现记忆关联到持久原则，例如显式状态优于隐式状态、限制增长或考虑环境的验证。

---

新 Agent 会话的引导清单

1. 调用 memory_stats，查看现有记忆数量。
2. 使用宽泛查询调用 search_memories，定位相关的既有上下文。
3. 检查近期记忆是否已说明任务背后的理由或持久原则，而不只是最后的执行步骤。
4. 调用 store_memory 时应用规范标签方案。
5. 使用 connect_memories 将新记忆与相关的现有记忆关联起来。
6. 使用 traverse_from 或 related_to 进行关联检索，而不是重复搜索。
7. 没有“快速任务”豁免：本仓库中的任何文件编辑、决定或发现都值得记录为记忆——继续之前先写入记忆。如果你发现自己在想“这件事太小了”，这正是应该记录的信号，而不是绕过记录的理由。
8. 没有“仅记录执行内容”豁免：如果一条记忆说明了发生的更改，也应说明更改原因，或关联到一条说明原因的记忆。

---