通过 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 任何代码。
前置条件
- 已安装
dshCLI(组合包依赖其内置的@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 验证):
src/memos/api/config.py——load_dotenv(override=True)→load_dotenv(),宿主机环境变量覆盖不再被.env冲掉。src/memos/log.py—— 控制台日志改到 stderr;stdout 是 MCP 协议通道,日志行会污染 stdio 流。src/memos/api/mcp_serve.py—— 把EMBEDDING_DIMENSION映射进默认配置,让 Neo4j 向量索引维度与 embedder 一致。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,在部分网络不可达。
- embedder 构造改为读取
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
链接
同类插件
vectorize-io/hindsight#coding-agents★ 62057
Hindsight:会学习的 Agent 长期记忆系统,自动召回/保存、知识页、深度反思与按仓库隔离的记忆银行。
volcengine/OpenViking#examples/dsh-memory-plugin★ 42489
面向 DeepSeek Harness 的 OpenViking 记忆与上下文插件:pre-step 自动召回与画像注入、会话捕获、`viking://` URI 防护,以及对接 OpenViking 服务端的 recall/write 记忆工具。
MemTensor/MemOS#memos-local-plugin★ 12457
DeepSeek Harness 本地记忆插件:分层 L1/L2/L3 记忆,自动沉淀与手动 memos_* 检索工具并存,内置记忆浏览器。
agentscope-ai/ReMe#dsh★ 3826
将 DeepSeek Harness 接入 ReMe 本地优先、自进化的个人知识库:自动把已完成的主 Agent 对话沉淀为用户掌控的 Markdown 记忆,通过 reme_search 结合 BM25、可选向量检索和 wikilink 展开搜索对话与资料,并按日整理长期记忆。
zilliztech/memsearch#MemSearch★ 2909
供 DSH 与其他编程 Agent 共享的 Markdown 记忆,支持自动捕获、步骤前上下文注入、搜索召回,以及通过审阅面板实现 memory-to-skill 自进化。
vshulcz/deja-vu#extensions/dsh★ 1627
跨会话长期记忆与上下文恢复:读取本机上其他四十五个(45+)编程智能体已经写下的会话文件,支持安装前历史找回与中断恢复(Claude Code、Codex、Cursor、Windsurf、Trae、Antigravity、VS Code Copilot Chat、opencode、OpenClaw、Hermes、Kimi、Qoder、Cline、Zed、Magpie 等):提供 deja_recall、deja_session、deja_blame、deja_fix、deja_how、deja_remember 六个工具与 /deja 命令,并可选地把召回结果加入运行时上下文。共享本地 BM25 CLI/MCP 索引,不用大模型,不用向量嵌入,不联网(dsh plugin --profile web add dsh-deja)。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。