Swd146296/dsh-memos-bridge

一个 DeepSeek Harness 组合包（bundle），通过 MCP 把 MemOS 记忆服务桥接进 agent。安装组合包、运行一次设置脚本、重启 Harness 后，agent 就获得了名为 mcp__memos__* 的持久记忆工具。

能获得什么

组合包激活后，agent 可以调用（MemOS MCP 工具面的子集）：

工具	用途
add_memory	从文本、文档或对话消息写入记忆
search_memories	跨用户记忆 Cube 做语义检索
get_memory / update_memory / delete_memory	查看 / 修正 / 删除单条记忆
create_cube / register_cube / share_cube	管理记忆 Cube
chat	带记忆增强的 MOS 对话
control_memory_scheduler	启停异步记忆调度器
…	共 16 个工具，可用冒烟测试列出

工作原理

DeepSeek Harness（web profile）
  └─ cordis.patch.yml  ──插入──►  @deepseek-ai/dsh-mcp-client  （dsh CLI 自带）
                                      │  stdio
                                      ▼
                              python -m memos.api.mcp_serve   （MemOS venv）
                                      │
                                      ▼
                       MemOS MOS 核心：Neo4j（图记忆）、Qdrant、
                       LLM + Embedding 网关（如百炼兼容代理）

组合包只贡献一层配置（dsh.bundle + cordis.patch.yml），挂载的是 Harness 自带的 @deepseek-ai/dsh-mcp-client 插件（stdio 服务行）。不改动 Harness 任何代码。

前置条件

• 已安装 dsh CLI（组合包依赖其内置的 @deepseek-ai/dsh-mcp-client）。
• MemOS 源码目录及其 docker 栈在运行（MemOS/docker 的 compose 提供 Neo4j + Qdrant + MemOS API）。
• Python ≥ 3.10（用于 MemOS venv）。
• 运行 MCP 子进程的机器能访问 MemOS 的 LLM 与 Embedding 网关（见宿主机端点覆盖）。

快速开始

0. 先启动 MemOS 基础设施——MCP server 启动时必须连 Neo4j，search/chat 还需要 LLM 与 Embedding 网关：

docker compose -f C:\path\to\MemOS\docker\docker-compose.yml up -d   # Neo4j + Qdrant + MemOS API
# 并确保 LLM/Embedding 网关（如 :18181/:18182）在运行

如果 dsh 启动时栈还没起来，runner 会打印一行清晰的提示并快速退出；客户端的重连策略会持续重试（上限 maxAttempts），之后把栈启动起来即可自动恢复，无需重启 GUI。

1. 准备 MemOS 侧（venv + 依赖 + 源码补丁 + 本地 tokenizer）：

# 在插件目录下
.\setup.ps1 --memos C:\path\to\MemOS

POSIX：./setup.sh --memos /path/to/MemOS。脚本会创建 MemOS/.venv，安装 MemoryOS[tree-mem] 及 python-dotenv、tqdm、langchain_text_splitters、chonkie，应用必需的源码补丁（见下文），并下载本地 gpt2 tokenizer.json（优先 HuggingFace 镜像）。

2. 把组合包安装进 profile：

dsh plugin --profile web add ./dsh-memos-bridge

3. 配置路径（patch 在启动时读取，均可选）：

# PowerShell: setx MEMOS_PYTHON "C:\path\to\MemOS\.venv\Scripts\python.exe"
#             setx MEMOS_HOME   "C:\path\to\MemOS"
export MEMOS_PYTHON=/path/to/MemOS/.venv/bin/python
export MEMOS_HOME=/path/to/MemOS

不设置 MEMOS_PYTHON 时回退到 PATH 上的 python；不设置 MEMOS_HOME 时子进程继承 Harness 的工作目录（MemOS 仍会读取自己的 .env，建议把 MEMOS_HOME 指向源码目录，除非 MemOS 就在启动目录下）。

4. 验证并重启：

dsh --profile web --dump-config    # 应看到 `id: memos-mcp` 行
dsh --profile web                  # 重启 GUI，工具以 mcp__memos__* 出现

随时可跑冒烟测试：

python scripts/smoke_test.py --python C:\path\to\MemOS\.venv\Scripts\python.exe --memos C:\path\to\MemOS --search

配置

组合包的 patch 插入两行：memos-bridge 提供方（通过 memosBridge 服务暴露 venv python、本包 runner 路径、MemOS cwd）和 memos-mcp（@deepseek-ai/dsh-mcp-client 行，serverName: memos，经 stdio 拉起 runner）。runner 会预检 Neo4j（硬依赖：一行清晰报错并快速退出）、在 LLM/Embedding 网关不可用时给出警告，并默认把端点指向 127.0.0.1（宿主机部署）。

挂载时读取的环境变量：

变量	默认值	含义
MEMOS_PYTHON	python	MemOS venv 的 python
MEMOS_HOME	''（继承 cwd）	作为子进程 cwd 的 MemOS 目录
MEMOS_MCP_SERVER	memos	工具命名空间（mcp__<name>__*）

想改其他字段（如 toolCallTimeoutMs、failOnStartupError），在你的 profile cordis.patch.yml 中按 id 覆盖该行——后层优先，但按 id 的 patch 会整体替换 config，需要重述所有键：

- id: memos-mcp
  config:
    transport: stdio
    serverName: memos
    command: 'C:/path/to/MemOS/.venv/Scripts/python.exe'
    args: ['C:/path/to/dsh-memos-bridge/scripts/memos_mcp_runner.py']
    cwd: 'C:/path/to/MemOS'
    toolCallTimeoutMs: 60000
    failOnStartupError: false

宿主机端点覆盖

MemOS 的 .env 通常指向 host.docker.internal:18181/18182（在 MemOS 的 docker 网络内部有效）。当 MCP 子进程跑在宿主机上时，端点必须从宿主机可达。自带的 runner 已默认把端点指向 127.0.0.1（常见的宿主机回环发布）；如果你的网关在别处（或只能经本地代理规则到达），在该行上加 env 块覆盖端点：

- id: memos-mcp
  config:
    transport: stdio
    serverName: memos
    command: 'C:/path/to/MemOS/.venv/Scripts/python.exe'
    args: ['C:/path/to/dsh-memos-bridge/scripts/memos_mcp_runner.py']
    cwd: 'C:/path/to/MemOS'
    env:
      OPENAI_API_BASE: 'http://127.0.0.1:18181/v1'
      MOS_EMBEDDER_API_BASE: 'http://127.0.0.1:18182/compatible-mode/v1'
      MEMRADER_API_BASE: 'http://127.0.0.1:18181/v1'
      QWEN_API_BASE: 'http://127.0.0.1:18181/v1'
    failOnStartupError: false

（这些值能生效的前提是补丁脚本把 MemOS 的 load_dotenv(override=True) 改成了 override=False——外部环境变量优先于 .env。）

MemOS 源码补丁

scripts/patch_memos.py 对 MemOS 目录应用如下幂等修复（针对 MemoryOS 2.0.30 验证）：

1. src/memos/api/config.py —— load_dotenv(override=True) → load_dotenv()，宿主机环境变量覆盖不再被 .env 冲掉。
2. src/memos/log.py —— 控制台日志改到 stderr；stdout 是 MCP 协议通道，日志行会污染 stdio 流。
3. src/memos/api/mcp_serve.py —— 把 EMBEDDING_DIMENSION 映射进默认配置，让 Neo4j 向量索引维度与 embedder 一致。
4. src/memos/mem_os/utils/default_config.py：
   • embedder 构造改为读取 MOS_EMBEDDER_BACKEND / MOS_EMBEDDER_API_BASE / MOS_EMBEDDER_API_KEY / MOS_EMBEDDER_MODEL / EMBEDDING_DIMENSION（对齐 APIConfig.get_embedder_config；MCP 默认路径原本会忽略这些并复用聊天端点）；
   • sentence chunker 的 tokenizer 指向本地 gpt2 tokenizer.json——否则 chonkie 会从 huggingface.co 下载 gpt2，在部分网络不可达。
5. src/memos/graph_dbs/neo4j.py、neo4j_community.py、tree_text_memory/retrieve/bm25_util.py、internet_retriever.py —— 把搜索路径里的裸 print()（原始 Cypher 查询、BM25 命中行等）重定向到 stderr；否则 stdout 上的这些输出会在搜索时污染 MCP stdio 流。

python scripts/patch_memos.py --list 可查看补丁清单。若某条补丁报"不在补丁前状态"，说明你的 MemOS 版本与 2.0.30 不同——对照差异手动应用。

常见问题

现象	原因 / 处理
dsh plugin add 装出 Gu 之类的拆分包	Windows 下插件路径含空格时，dsh 转发给 pnpm 会被拆分。改用 8.3 短路径（如 C:\Users\GULING~1\...）或从无空格目录执行 add .。
启动时一屏 Couldn't connect to localhost:7687 traceback	Neo4j 没起。先启动 MemOS docker 栈（docker compose up -d）；runner 会预检 Neo4j 并打印一行清晰提示，且该行会持续重试——栈起来后工具自动出现，无需重启 GUI。
重启后行一直 pending	MEMOS_PYTHON/MEMOS_HOME 配错，或 MemOS venv 未建。先看 dsh --profile web --dump-config。
启动报 Graph not found: memosdefaultuser	Neo4j Community 版 + .env 里 MOS_NEO4J_SHARED_DB=false → 改为 true 并设 NEO4J_AUTO_CREATE=false（共享单个 neo4j 库）。
Tokenizer 'gpt2' could not be loaded ... huggingface.co	运行 setup.py 下载本地 tokenizer，或设 HF_ENDPOINT=https://hf-mirror.com（补丁已把 tokenizer 指向本地文件）。
Embeddings request ended with error: Error code: 503	LLM/Embedding 网关（如 :18181/:18182）未启动或宿主机不可达——见宿主机端点覆盖，启动网关。
搜索时出现 Failed to parse JSONRPC message from server	搜索路径里有裸 print() 写到 stdout——重跑 patch_memos.py（补丁 #5）并重启。
启动时的 pydantic 序列化警告	无害；MemOS 序列化配置对象时会打印。

安全说明

MCP server 命令是沙箱之外执行的受信代码（这正是 Harness 默认不启用任何 MCP server 的原因）。只连接你自己运行的 MemOS 服务。

许可证

MIT