DeepSeek Harness 插件

Swd146296/dsh-memos-bridge

Star 数 ★ 23 分类 记忆 收录于 2026-08-22

通过 MCP 桥接 MemOS 记忆服务:agent 获得 mcp__memos__* 记忆写入/检索/更新/删除、多 Cube 共享与记忆调度工具。

安装

# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)

dsh plugin --profile web add github:Swd146296/dsh-memos-bridge

装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。

README

English | 简体中文

一个 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
                                        ▼
                                scripts/memos_mcp_runner.py     (预检 + 端点解析)
                                        │
                                        ▼
                                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 网关(见端点解析)。

安装组合包

下面三条路径任选其一,装出来的文件完全一样。

A. 从 npm 安装(推荐)

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

不需要 git、不访问 GitHub、没有构建步骤。如果 registry 返回 404,说明包还没发布,请改用 B 或 C。

B. 从 git 安装

dsh plugin --profile web add github:Swd146296/dsh-memos-bridge

pnpm 内部会执行 git ls-remote,因此既要求 PATH 上有 git,也要求 github.com 可达。受限网络下这一环最先失败:

Command failed with exit code 1: git ls-remote "https://github.com/Swd146296/dsh-memos-bridge.git" HEAD "HEAD^{}"

先用 git --version 确认 git 存在;如果 git 缺失就装上,如果 github.com 不可达就用路径 C。

C. 从 release 压缩包或本地目录安装(不需要 git)

# 下载某个 release 附带的 tgz,再按路径安装
curl -LO https://github.com/Swd146296/dsh-memos-bridge/releases/download/v0.2.0/dsh-memos-bridge-0.2.0.tgz
dsh plugin --profile web add ./dsh-memos-bridge-0.2.0.tgz

也可以从源码副本自行打包:

npm pack                 # 生成 dsh-memos-bridge-<version>.tgz
dsh plugin --profile web add ./dsh-memos-bridge-<version>.tgz

Windows 路径含空格: pnpm 会把转发过去的插件路径按空格切开,于是 dsh plugin add 会装出名为 Gu 之类的拆分包。改用 8.3 短路径(如 C:\Users\GULING~1\...),或从无空格目录执行 add .。

快速开始

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 会打印一行清晰的提示并快速退出;客户端的重连策略会持续重试,之后把栈启动起来即可自动恢复,无需重启 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. 安装组合包——见安装组合包。

3. 配置路径(patch 在启动时读取,均可选):

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__* 出现

配置

组合包的 patch 插入两行:memos-bridge 提供方(通过 memosBridge 服务暴露 venv python、本包 runner 路径、子进程 cwd 和工具命名空间)和 memos-mcp(@deepseek-ai/dsh-mcp-client 行,经 stdio 拉起 runner)。runner 会预检 Neo4j(硬依赖:一行清晰报错并快速退出)、在 LLM/Embedding 网关不可用时给出警告,并解析宿主机部署的端点。

挂载时读取的环境变量:

变量 默认值 含义
MEMOS_PYTHON python MemOS venv 的 python
MEMOS_HOME Harness 的工作目录 作为子进程 cwd 的 MemOS 目录
MEMOS_MCP_SERVER memos 工具命名空间(mcp__<name>__*),需匹配 [A-Za-z0-9_-]{1,32}

cwd 永不为空:提供方先解析 MEMOS_HOME,取不到就回退到 Harness 进程的工作目录——空 cwd 会让 MCP SDK 的 spawn 直接失败并抛出一个裸 ENOENT,看起来像是解释器不存在。

该行自带的默认值:toolCallTimeoutMs: 120000(写记忆和带 LLM 的检索经常超过客户端默认的 60 秒)、failOnStartupError: false,以及给子进程的 PYTHONUTF8=1 / PYTHONIOENCODING=utf-8(Windows 控制台代码页会把一行非 ASCII 日志变成 server 内部的 UnicodeEncodeError)。

想改其他字段,在你的 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: 180000
    env:
      PYTHONUTF8: '1'
      PYTHONIOENCODING: 'utf-8'
    failOnStartupError: false

端点解析

MemOS 的 .env 通常指向 host.docker.internal:18181/18182(在 MemOS 的 docker 网络内部有效)。当 MCP 子进程跑在宿主机上时,runner 按下面的顺序解析端点:

优先级 来源 行为
1 外层环境变量(行的 env 块、shell) 原样使用,绝不改写
2 MEMOS_HOME / cwd 下的 .env 原样保留;仅当 docker 内部主机名对应的发布端口真能连上时,才映射到回环地址
3 本组合包的默认值 完全未设置的键才填 127.0.0.1:18181 / :18182

因此,.env 里已经指向真实远端网关(百炼、DeepSeek、公司代理等)的配置不会被改动,显式 env 块也永远优先。若要让 docker 主机名原样保留(例如网关只能经本地代理规则到达),设 MEMOS_MCP_ENDPOINT_REWRITE=0 并显式覆盖:

- 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

参见 examples/host-run-override.yml。

排障与自检

"工具为什么没出现"这个问题,按顺序跑下面三条命令即可定位:

# 1. MemOS 侧是否就绪?(venv、import、补丁、tokenizer;不改动任何东西)
python scripts/setup.py --memos C:\path\to\MemOS --check

# 2. 基础设施是否可达?(端点、Neo4j、网关、import)
"C:\path\to\MemOS\.venv\Scripts\python.exe" scripts/memos_mcp_runner.py --check

# 3. MCP 握手是否成功?(与 dsh 拉起的是同一个入口)
"C:\path\to\MemOS\.venv\Scripts\python.exe" scripts/smoke_test.py --memos C:\path\to\MemOS --search

runner 的环境变量:

变量 默认值 含义
MEMOS_MCP_PREFLIGHT 1 0 完全跳过 Neo4j / 网关探测(适用于丢 SYN 的代理环境)
MEMOS_MCP_PREFLIGHT_TIMEOUT 2 单次 TCP 探测的秒数
MEMOS_MCP_ALLOW_NO_NEO4J 0 1 表示 Neo4j 不通也照常启动(带警告)
MEMOS_MCP_ENDPOINT_REWRITE 1 0 表示 docker 内部主机名原样保留
MEMOS_MCP_DEBUG 0 1 打印解析后的 python、版本与端点

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 流。

被改动的文件首次修改前会备份为 <file>.dsh-bridge.bak,写入是原子的,换行符与 BOM 均保持不变。

python scripts/patch_memos.py --list     # 列出脚本会改什么
python scripts/patch_memos.py --check    # 试运行:哪些补丁适配当前目录
python scripts/patch_memos.py --revert   # 从备份恢复

若某条补丁报"不在补丁前状态",说明你的 MemOS 版本与 2.0.30 不同——--check 会一次性列出所有不匹配项,对照差异手动应用即可。

常见问题

现象 原因 / 处理
dsh plugin add 报 git ls-remote ... exit code 1 该机器没装 git,或 github.com 不可达。改用 npm 包或 release 压缩包(路径 A/C)。
dsh plugin add 装出 Gu 之类的拆分包 Windows 下插件路径含空格时,dsh 转发给 pnpm 会被拆分。改用 8.3 短路径,或从无空格目录执行 add .。
MCP 行一直连不上,spawn 报 ENOENT 要么 cwd 为空(0.2.0 已修),要么 MEMOS_PYTHON 没指向真实解释器。跑 runner --check。
启动时一屏 Couldn't connect to localhost:7687 traceback Neo4j 没起。先启动 MemOS docker 栈;runner 会预检 Neo4j 并打印一行清晰提示,该行会持续重试。
重启后行一直 pending MEMOS_PYTHON/MEMOS_HOME 配错,或 MemOS venv 未建。先看 dsh --profile web --dump-config,再跑 setup.py --check。
工具出现了,但 search/chat 报 401/403 dsh 会从子进程环境里剔除"凭证形状"的变量名(*KEY*、*TOKEN*、*SECRET*、*PASSWORD*)。把密钥写进 MemOS 的 .env,或在行的 env 块里显式传入。
启动报 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)并重启。
子进程日志报 UnicodeEncodeError 控制台代码页不是 UTF-8。该行已默认设 PYTHONUTF8=1;如果你覆盖过该行,记得把那两个 env 键补回去。
启动时的 pydantic 序列化警告 无害;MemOS 序列化配置对象时会打印。

提 issue 时,请附上 scripts/memos_mcp_runner.py --check 的输出(涵盖 python、版本、端点、Neo4j、网关)以及 dsh --dump-config 里对应的行。

安全说明

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

两点值得注意:

  • patch_memos.py 会就地修改第三方源码目录。运行前先看 --list;--revert 可从备份恢复。
  • Harness 传给 MCP 子进程的是清洗过的环境变量:名字里含 KEY、TOKEN、SECRET、PASSWORD 的变量,以及所有 DSH_* 变量都会被丢弃。密钥请放在 MemOS 自己的 .env 或行的 env 块里。

开发

node --check index.js                  # 提供方插件语法
node --test tests/provider.test.mjs    # 提供方契约(cwd、命名空间、回退逻辑)
python -m unittest discover -s tests   # 补丁引擎、patch 层、runner 辅助函数

两套测试都可离线运行、不需要安装 MemOS,并且跨平台:Windows 与 Linux、Python 3.10+ 均通过。

许可证

MIT

内容来自项目 README(GitHub)↗

链接

同类插件

查看整个分类 →

社区评论

评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。