# Agent Note: 第三方记忆 MCP 示例

Status: implemented

[English](2026-07-31-third-party-memory-mcp-examples.md) | 中文

## 问题

直接集成某个提供方会使该提供方的 API、配置、健康状态行为和工具语义成为 DSH 的一部分。对于已经可以通过 MCP 表达的功能，这会让产品接口过于庞大，而且每接入一个记忆系统都需要重复同样的适配工作。用户需要的是一种精简、可检查的方式，在保留通用 MCP 边界的同时，选择启用一个外部记忆服务器。

验收标准不止于「套接字可以连接」：每份参考配置都必须支持 DSH 在会话 A 中实际写入，在新的 DSH 会话 B 中从提供方召回，并使用召回的值。与此同时，提供方下载、账户、模型、embedding、存储初始化和独立 HTTP 进程仍由上游负责。

## 决策

在 `apps/cli/config/examples/mcp-memory` 下交付三份默认关闭的 Cordis overlay 示例：Memorix、MCP Reference Memory 和 Engram。每个文件只插入一个 `@deepseek-ai/dsh-mcp-client` 配置项。默认组合不会引用这些文件；CLI（命令行界面）声明通用桥接器，使显式选择的 overlay 能在安装后与源码启动中解析。[记忆 MCP 指南](../../../../docs/user/guide/mcp-memory.zh.md)负责安装与验证步骤。

这些第三方配置仅作为互操作参考；收录不代表 DeepSeek 的认可、推荐、合作关系或持续支持承诺。系统没有记忆预设注册表、提供方专属 DSH 插件、通用记忆服务、安装 UI、迁移层、健康检查器或重连控制器。其他记忆 MCP 服务器可以使用同一份文档中的 stdio 或 Streamable HTTP 配置项。

## 职责边界

| 事项 | DSH | 上游提供方或用户 |
|---|---|---|
| 解析选中的 overlay | 是 | 选择一个文件 |
| 启动 stdio 命令，并在插件 dispose（资源释放）时将其停止 | 是 | 安装固定版本的可执行文件 |
| 连接 Streamable HTTP 并发现工具 | 是 | 运行并监管 HTTP 服务 |
| 以 `mcp__<serverName>__<rawName>` 注册工具 | 是 | 定义工具 schema 和行为 |
| 账户、认证、模型、embedding、存储初始化 | 否 | 是 |
| 提供方数据迁移、重试、崩溃恢复 | 否 | 是 |

通用 stdio 传输会清除环境中名称类似凭据的变量和 `DSH_*` 变量，同时继承其他环境变量。基线示例仅添加必需的覆盖项；可选的提供方密钥必须添加到 `config.env`，或配置在提供方自己的文件中。

## 版本固定、存储与身份

| 提供方 | 已测试约定 |
|---|---|
| Memorix | npm `1.3.0`，tag commit `500792cad3144142293bfbb20acb4841c9f7fcfa` |
| MCP Reference Memory | npm `2026.7.4`，package commit `6dd0a683e198783e30feabf7abaf42f925bd18b1` |
| Engram | tag `v1.20.0`，commit `ba9e46ced152c37a7cb9e576153c41995873e2fc` |

存储仍由提供方负责。Memorix 默认使用 `~/.memorix/data`，Engram 默认使用 `~/.engram`。Reference Memory 示例设置稳定的 `$HOME/.dsh-mcp-reference-memory.jsonl` 路径，而不是写入已安装的 npm 包目录。每个提供方自己的环境变量都可以在 DSH 启动前覆盖这些位置。

项目身份仍由提供方负责：Memorix 和 Engram 使用 DSH 工作目录中的 Git 项目，其中 Engram 还可以选择接受 `ENGRAM_PROJECT`。

## 模型指导

示例不会修改 `@deepseek-ai/dsh-system-prompt`：配置 patch 会替换某个配置项的完整配置，可能抹除已有 persona。README 改为提供一条可选的附加指令：

> 当用户要求你记住某件事时，调用记忆写入工具。当历史信息可能相关时，搜索记忆并使用相关结果。

提供方的工具描述仍然是权威定义。

## 验证约定

远程 CI 不会访问第三方服务或消耗密钥。无密钥套件解析全部三份 overlay 文件，检查其通用桥接器和密钥边界，将上游端点替换为包自带的 MCP fixture（测试前置数据）服务器，通过真实 Cordis Loader 启动，并验证工具发现。

合并前，每个固定版本的提供方都必须分别提供以下人工证据：

1. DSH 会话 A 调用写入工具，为一个唯一值写入记忆，并收到成功结果。
2. 新的 DSH 会话 B 在相同的提供方存储范围下调用搜索或召回，不借助会话 A 的 transcript（文本记录）便可返回该值。
3. 会话 B 在后续回答中使用该召回值。

「新会话」是指同一个 Host 中新建的 DSH 会话，不需要重启 Host。通用 MCP 客户端以异步方式发现工具，子进程或 HTTP 传输关闭后不会自动重连；验证会在第一轮之前等待工具出现，并且只在崩溃后使用 HMR 或重启 Host。

## 考虑过的替代方案

**每个提供方使用一个 DSH 插件。** 不予采纳，因为这会重复 MCP 已经标准化的认证、配置、生命周期和工具包装层，并随着每增加一个提供方而扩大维护范围。

**记忆提供方预设注册表。** 不予采纳，因为注册表会让第三方版本和推荐看起来像受支持的 DSH 产品接口。可复制的 overlay 让所有权和版本偏移保持可见。

**在 MCP 配置项内运行 `npx` 或 `go run`。** 不予采纳，因为探测表明首次 npm 下载可能超过 MCP 初始化超时，而中断的 `npx` 缓存可能变得不可用。DSH 负责启动服务器进程，不是提供方的包管理器。固定版本的安装命令属于显式前置条件。

**由通用 MCP 客户端注入共用指令。** 不予采纳，因为该桥接器也服务于非记忆类 MCP 服务器，而且通用提示词变更会把提供方语义重新带入共享运行时代码。

## 后果

选择一个文件后，模型可以使用提供方发现到的完整 MCP 工具接口；工具 schema 和 token 成本由提供方决定。移除 `--config` 就会移除记忆服务器。用户直接接受各上游的许可证、数据政策、云服务费用和运维模式。

通用方案取代了早期针对特定提供方的改动。未来出现提供方版本偏移时，只需更新并重新验证一份小型示例的固定版本，不必向 DSH 添加运行时分支。
