feat(examples): add generic memory MCP overlays

2026-07-31 01:57:19 -07:00
parent 85e766fa89
commit 7e929d3d50
17 changed files with 574 additions and 3 deletions
--- a/examples/mcp-memory/README.i18n.yaml
+++ b/examples/mcp-memory/README.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write examples/mcp-memory/README.md
+README.md: 7d1565f240738249b1e08eef135031bf81cc6146
+README.zh.md: 037670ed0110ad46d6f7e1b7160a1c4ae830ed4b
--- a/examples/mcp-memory/README.md
+++ b/examples/mcp-memory/README.md
@@ -0,0 +1,103 @@
+# Third-party memory MCP examples
+
+English | [中文](README.zh.md)
+
+These three **default-off reference configurations** connect one memory system to DSH through [`@deepseek-ai/dsh-mcp-client`](../../packages/mcp/mcp-client/README.md). Pick one, or copy the same generic MCP row for another server.
+
+These third-party configurations are provided as interoperability examples only. Their inclusion does not imply endorsement, recommendation, partnership, or ongoing support by DeepSeek.
+
+## What DSH does
+
+DSH parses the selected Cordis overlay, starts a configured stdio command or connects to a configured Streamable HTTP URL, discovers MCP tools, and exposes them as `mcp__<serverName>__<tool>`. DSH does **not** download the server, initialize its database, choose its model or embedding provider, create a cloud account, migrate vendor data, or supervise a separate HTTP service. For stdio, the generic client launches and stops the child with the DSH plugin lifecycle; for HTTP, the upstream service must already be running.
+
+The stdio bridge deliberately removes ambient credential-shaped and `DSH_*` variables before launching a child. Each example explicitly forwards only the variables needed for its baseline. If an optional upstream feature needs another secret, add that variable to the row's `config.env` instead of putting the secret directly in YAML.
+
+## Choose one
+
+| System | Tested pin | Transport | Upstream prerequisite |
+|---|---:|---|---|
+| [Memorix](https://github.com/AVIDS2/memorix) | `memorix@1.3.0` (`500792cad3144142293bfbb20acb4841c9f7fcfa`) | stdio | Node 22.18+ and `npm install --global memorix@1.3.0` |
+| [MCP Reference Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) | `@modelcontextprotocol/server-memory@2026.7.4` (`6dd0a683e198783e30feabf7abaf42f925bd18b1`) | stdio | `npm install --global @modelcontextprotocol/server-memory@2026.7.4` |
+| [Engram](https://github.com/Gentleman-Programming/engram) | `v1.20.0` (`ba9e46ced152c37a7cb9e576153c41995873e2fc`) | stdio | Go 1.25.10+ and `go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0`, or the matching release binary |
+
+## Enable one
+
+Use a stable user id across sessions, then pass one overlay to DSH:
+
+```sh
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/memorix.cordis.yml"
+```
+
+Replace the filename with `mcp-reference-memory.cordis.yml` or `engram.cordis.yml`. The path may point to a copied file anywhere on disk. No memory server is present in the shipped composition, so omitting `--config` keeps all three disabled.
+
+To keep the selection in personal configuration, merge the chosen file's single `insert` patch into `$DSH_HOME/config.yaml` (normally `~/.dsh/config.yaml`). Do not copy over an existing file: it may already contain unrelated personal patches.
+
+## Provider setup
+
+### Memorix
+
+```sh
+npm install --global memorix@1.3.0
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/memorix.cordis.yml"
+```
+
+Memorix works in local heuristic mode without an LLM or embedding service. Configure optional providers in Memorix's own `~/.memorix/config.toml` or project `memorix.toml`. The example keeps Memorix's Git-project identity from the DSH working directory and maps `DSH_MEMORY_USER_ID` to a private `MEMORIX_DATA_DIR`.
+
+### MCP Reference Memory
+
+```sh
+npm install --global @modelcontextprotocol/server-memory@2026.7.4
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/mcp-reference-memory.cordis.yml"
+```
+
+This reference server stores a local knowledge graph and exposes entity, relation, observation, read, search, and open tools. It needs no model or embedding service. The example maps `DSH_MEMORY_USER_ID` to an isolated `MEMORY_FILE_PATH`.
+
+### Engram
+
+```sh
+go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/engram.cordis.yml"
+```
+
+The example maps the user id to an isolated `ENGRAM_DATA_DIR`. Engram still owns project selection: it detects the Git project from the DSH working directory, or accepts `ENGRAM_PROJECT` as an explicit override.
+
+## Optional shared model instruction
+
+Add this short, vendor-neutral instruction to your existing model instructions if the server's tool descriptions do not trigger memory use reliably:
+
+> When the user asks you to remember something, call a memory write tool. When historical information may be relevant, search memory and use relevant results.
+
+This is additive guidance only. The examples do not replace DSH's system-prompt persona.
+
+## Verify write, fresh-session recall, and use
+
+Use one unique value, the same provider scope, and the same `DSH_MEMORY_USER_ID` throughout:
+
+1. In DSH session A, ask: `Remember that my validation drink is lapsang-<unique suffix>.` Confirm the model called the provider's write tool and the tool returned success.
+2. Create DSH session B in the same running Host. Do not copy session A's conversation. Ask: `What is my validation drink? Check memory.` Confirm the model called the provider's search or recall tool and returned the value.
+3. Still in session B, ask: `Use that preference to suggest one drink for the meeting.` Confirm the answer uses the recalled value.
+
+A new DSH session is required; a Host restart is not. Restart or HMR is needed only after an MCP child crashes because the current generic client unregisters tools on disconnect and does not auto-reconnect. Initial discovery is asynchronous, so wait for the provider's `mcp__...` tools before sending the first validation prompt.
+
+## Bring another MCP server
+
+Copy the same generic shape and use a unique `id` and `serverName`:
+
+```yaml
+- insert:
+    - id: memory-my-server
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: my-memory
+        transport: stdio
+        command: my-memory-mcp
+        args: []
+        env: {}
+        cwd: !!js process.cwd()
+```
+
+For a remote server, use `transport: streamable-http`, `url`, and `headers` instead. Provider-specific installation, identity, authentication, models, embeddings, persistence, and licensing remain the provider's responsibility.
--- a/examples/mcp-memory/README.zh.md
+++ b/examples/mcp-memory/README.zh.md
@@ -0,0 +1,103 @@
+# 第三方记忆 MCP 示例
+
+[English](README.md) | 中文
+
+这三份**默认关闭的参考配置** 通过 [`@deepseek-ai/dsh-mcp-client`](../../packages/mcp/mcp-client/README.md) 将一个记忆系统连接到 DSH。请选择其中一份，或复制相同的通用 MCP 配置项来连接其他服务器。
+
+这些第三方配置仅作为互操作参考；收录不代表 DeepSeek 的认可、推荐、合作关系或持续支持承诺。
+
+## DSH 负责什么
+
+DSH 解析选中的 Cordis overlay，启动已配置的 stdio 命令或连接已配置的 Streamable HTTP URL，发现 MCP 工具，并以 `mcp__<serverName>__<tool>` 的形式公开这些工具。DSH **不负责** 下载服务器、初始化其数据库、选择模型或 embedding 提供方、创建云端账户、迁移提供方数据，也不监管独立的 HTTP 服务。对于 stdio，通用客户端会随 DSH 插件生命周期启动和停止子进程；对于 HTTP，上游服务必须已经运行。
+
+stdio 桥接器在启动子进程前会主动移除环境中名称类似凭据的变量和 `DSH_*` 变量。每份示例仅显式转发其基线运行所需的变量。如果某个可选的上游功能还需要其他密钥，请将该变量添加到配置项的 `config.env`，不要把密钥直接写进 YAML。
+
+## 选择一个
+
+| 系统 | 已测试版本 | 传输方式 | 上游前置条件 |
+|---|---:|---|---|
+| [Memorix](https://github.com/AVIDS2/memorix) | `memorix@1.3.0`（`500792cad3144142293bfbb20acb4841c9f7fcfa`） | stdio | Node 22.18+，并执行 `npm install --global memorix@1.3.0` |
+| [MCP Reference Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) | `@modelcontextprotocol/server-memory@2026.7.4`（`6dd0a683e198783e30feabf7abaf42f925bd18b1`） | stdio | `npm install --global @modelcontextprotocol/server-memory@2026.7.4` |
+| [Engram](https://github.com/Gentleman-Programming/engram) | `v1.20.0`（`ba9e46ced152c37a7cb9e576153c41995873e2fc`） | stdio | Go 1.25.10+，并执行 `go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0`，或安装匹配的发布版二进制文件 |
+
+## 启用一个
+
+在多个会话间使用一个稳定的用户 id，然后将一份 overlay 传给 DSH：
+
+```sh
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/memorix.cordis.yml"
+```
+
+请将文件名替换为 `mcp-reference-memory.cordis.yml` 或 `engram.cordis.yml`。该路径可以指向磁盘任意位置的一份复制文件。交付组合不包含任何记忆服务器，因此不传 `--config` 就会让这三项全部保持关闭。
+
+如果要把所选配置保存在个人配置中，请将对应文件中的单个 `insert` patch 合并到 `$DSH_HOME/config.yaml`（通常是 `~/.dsh/config.yaml`）。不要覆盖已有文件，其中可能已经包含无关的个人 patch。
+
+## 提供方设置
+
+### Memorix
+
+```sh
+npm install --global memorix@1.3.0
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/memorix.cordis.yml"
+```
+
+Memorix 无需 LLM（大语言模型）或 embedding 服务，即可在本地启发式模式下运行。请在 Memorix 自己的 `~/.memorix/config.toml` 或项目 `memorix.toml` 中配置可选提供方。该示例沿用 DSH 工作目录中的 Git 项目标识，并将 `DSH_MEMORY_USER_ID` 映射到独立的 `MEMORIX_DATA_DIR`。
+
+### MCP Reference Memory
+
+```sh
+npm install --global @modelcontextprotocol/server-memory@2026.7.4
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/mcp-reference-memory.cordis.yml"
+```
+
+该参考服务器存储本地知识图谱，并公开实体、关系、观察、读取、搜索和打开工具。它不需要模型或 embedding 服务。该示例将 `DSH_MEMORY_USER_ID` 映射到隔离的 `MEMORY_FILE_PATH`。
+
+### Engram
+
+```sh
+go install github.com/Gentleman-Programming/engram/cmd/engram@v1.20.0
+export DSH_MEMORY_USER_ID=alice
+dsh --config "$PWD/examples/mcp-memory/engram.cordis.yml"
+```
+
+该示例将用户 id 映射到隔离的 `ENGRAM_DATA_DIR`。Engram 仍负责选择项目：它从 DSH 工作目录检测 Git 项目，也接受 `ENGRAM_PROJECT` 作为显式覆盖。
+
+## 可选的共用模型指令
+
+如果服务器的工具描述无法可靠触发记忆使用，请将以下简短、与提供方无关的指令添加到你现有的模型指令中：
+
+> 用户要求记住时调用写入工具；涉及历史信息时，主动检索并使用相关记忆。
+
+这只是附加指导。示例不会替换 DSH 系统提示词中的 persona。
+
+## 验证写入、新会话召回和使用
+
+请在整个过程中使用一个唯一值、相同的提供方范围和相同的 `DSH_MEMORY_USER_ID`：
+
+1. 在 DSH 会话 A 中提出：`Remember that my validation drink is lapsang-<unique suffix>.`。确认模型调用了提供方的写入工具，并且工具返回成功。
+2. 在同一个仍在运行的 Host 中创建 DSH 会话 B。不要复制会话 A 的对话。提出：`What is my validation drink? Check memory.`。确认模型调用了提供方的搜索或召回工具，并返回该值。
+3. 继续在会话 B 中提出：`Use that preference to suggest one drink for the meeting.`。确认回答使用了召回的值。
+
+必须新建 DSH 会话，但不需要重启 Host。只有 MCP 子进程崩溃后才需要重启或执行 HMR（热模块替换），因为当前的通用客户端会在连接断开时注销工具，且不会自动重连。初始发现过程是异步的，因此发送第一条验证提示词前，请等待提供方的 `mcp__...` 工具出现。
+
+## 接入其他 MCP 服务器
+
+复制相同的通用结构，并使用唯一的 `id` 和 `serverName`：
+
+```yaml
+- insert:
+    - id: memory-my-server
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: my-memory
+        transport: stdio
+        command: my-memory-mcp
+        args: []
+        env: {}
+        cwd: !!js process.cwd()
+```
+
+对于远程服务器，请改用 `transport: streamable-http`、`url` 和 `headers`。提供方专属的安装、身份、认证、模型、embedding、持久化和许可仍由提供方负责。
--- a/examples/mcp-memory/engram.cordis.yml
+++ b/examples/mcp-memory/engram.cordis.yml
@@ -0,0 +1,15 @@
+# Opt-in reference for Engram 1.20.0. Install the pinned `engram` executable
+# first; project selection remains Engram's cwd/ENGRAM_PROJECT contract.
+- insert:
+    - id: memory-engram
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: engram
+        transport: stdio
+        command: engram
+        args: [mcp]
+        cwd: !!js process.cwd()
+        env:
+          ENGRAM_PROJECT: !!js process.env.ENGRAM_PROJECT ?? ''
+          ENGRAM_DATA_DIR: !!js >-
+            process.env.ENGRAM_DATA_DIR ?? (() => { const path = process.getBuiltinModule('node:path'); const os = process.getBuiltinModule('node:os'); const crypto = process.getBuiltinModule('node:crypto'); const configured = process.env.DSH_HOME; const root = configured !== undefined && configured.trim().length > 0 ? configured : path.join(os.homedir(), '.dsh'); const user = process.env.DSH_MEMORY_USER_ID?.trim() || 'default'; const scope = crypto.createHash('sha256').update(user).digest('hex').slice(0, 16); return path.join(path.resolve(root), 'mcp-memory', 'engram', scope) })()
--- a/examples/mcp-memory/mcp-reference-memory.cordis.yml
+++ b/examples/mcp-memory/mcp-reference-memory.cordis.yml
@@ -0,0 +1,13 @@
+# Opt-in reference for @modelcontextprotocol/server-memory 2026.7.4. Install
+# the pinned executable first; DSH starts it but does not run a package manager.
+- insert:
+    - id: memory-mcp-reference
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: reference_memory
+        transport: stdio
+        command: mcp-server-memory
+        cwd: !!js process.cwd()
+        env:
+          MEMORY_FILE_PATH: !!js >-
+            (() => { const path = process.getBuiltinModule('node:path'); const os = process.getBuiltinModule('node:os'); const crypto = process.getBuiltinModule('node:crypto'); const configured = process.env.DSH_HOME; const root = configured !== undefined && configured.trim().length > 0 ? configured : path.join(os.homedir(), '.dsh'); const user = process.env.DSH_MEMORY_USER_ID?.trim() || 'default'; const scope = crypto.createHash('sha256').update(user).digest('hex').slice(0, 16); return path.join(path.resolve(root), `mcp-reference-memory-${scope}.jsonl`) })()
--- a/examples/mcp-memory/memorix.cordis.yml
+++ b/examples/mcp-memory/memorix.cordis.yml
@@ -0,0 +1,14 @@
+# Opt-in reference for Memorix 1.3.0. Install the pinned `memorix` executable
+# first; DSH starts it but does not run a package manager.
+- insert:
+    - id: memory-memorix
+      name: '@deepseek-ai/dsh-mcp-client'
+      config:
+        serverName: memorix
+        transport: stdio
+        command: memorix
+        args: [serve]
+        cwd: !!js process.cwd()
+        env:
+          MEMORIX_DATA_DIR: !!js >-
+            process.env.MEMORIX_DATA_DIR ?? (() => { const path = process.getBuiltinModule('node:path'); const os = process.getBuiltinModule('node:os'); const crypto = process.getBuiltinModule('node:crypto'); const configured = process.env.DSH_HOME; const root = configured !== undefined && configured.trim().length > 0 ? configured : path.join(os.homedir(), '.dsh'); const user = process.env.DSH_MEMORY_USER_ID?.trim() || 'default'; const scope = crypto.createHash('sha256').update(user).digest('hex').slice(0, 16); return path.join(path.resolve(root), 'mcp-memory', 'memorix', scope) })()