本地云记忆 yonro/xmemo-deepseek-plugin

XMemo for DeepSeek Harness

为 dsh 打造的原生本地优先 + 云端记忆。

本地混合存储，带离线持久化写入队列，再加上真正的 OAuth 2.1 登录 —— 重新实现为一个普通的 Cordis 插件，而不是一层薄薄的 MCP 桥接。

快速开始 ·认证 ·配置 · Web GUI 卡片 ·工具 ·能力 ·限制

一个原生 DeepSeek Harness（dsh）插件：本地 + XMemo 云端混合记忆，带离线持久化写入队列、活跃状态、时间线、TODO、决策和重启快照 —— 工具面与 xmemo-cindy-plugin 一致，但重新实现为一个普通的 Cordis 插件，而不是走 Cindy 那套宿主专属的插件协议。

这个插件直接对接 MemoryOS REST API（XMemo 背后的真正后端），并维护自己的本地存储，而不是走 XMemo 托管的 MCP 服务器（https://xmemo.dev/mcp）—— dsh 也能通过 harness 自带的 @deepseek-ai/dsh-mcp-client 桥接，用 MCP 方式访问 XMemo，但这个仓库是更深入的原生替代方案。端点路径、请求/响应字段名和认证头都对照 MemoryOS 源码核实过，不是从别的客户端猜的 —— 包括针对生产环境 xmemo.dev 的 OAuth 流程端到端实测。

[!NOTE]
DeepSeek Harness 本身还是开发者预览版。这个插件已在本地针对生产环境 xmemo.dev（单元测试、实时 Web GUI 会话，以及一次真实的 OAuth 注册 + 授权往返）验证过，但尚未经过大规模多用户使用检验。

概览

| 包 | dsh-xmemo |
| 插件 ID | xmemo |
| 运行时 | DeepSeek Harness（dsh） |
| 版本 | 0.1.0 |
| 打包形态 | 原生 Cordis 插件（宿主）+ Web GUI 设置卡片（浏览器） |
| 后端 | MemoryOS REST API — https://xmemo.dev |
| 认证 | OAuth 2.1 + PKCE（推荐），或静态 API key（兼容） |
| 本地存储 | JSON 混合存储，带持久化离线写入队列 |
| 工具面 | 16 个工具，名称与 schema 和 xmemo-cindy-plugin 一致 |
| 许可证 | MIT |

新增能力

- 聚焦召回 —— 本地 token 重叠匹配与云端召回合并，任何 bucket/scope 不匹配都按失败关闭处理。
- 持久结果 —— 记住决策、偏好和事实；记录时间线事件；跟踪 TODO 和决策。
- 工作连续性 —— 保存活动任务状态和重启快照，让会话能恢复，而不是重放历史。
- 离线韧性 —— 每次写入先落本地；安全（幂等）的写入自动重放到云端，不确定的写入等待显式批准。
- 真实账号登录 —— 对接 XMemo 真实授权服务器的 OAuth 2.1 + PKCE，不只是粘贴 API key。
- 可恢复删除 —— xmemo_forget 默认执行软删除，可恢复。

快速开始

dsh plugin --profile <name> add dsh-xmemo
or, to track main instead of the latest npm release:
dsh plugin --profile <name> add github:yonro/xmemo-deepseek-plugin
or, from a local checkout:
dsh plugin --profile <name> add ./xmemo-deepseek-plugin

从 git 安装拉取的是源码，不是构建好的 lib/，所以 pnpm 会在首次 add 时拦截这个包的 prepare 脚本（该脚本构建两半——见开发），并打印出需要放行的确切 key。把它加到配置档的 pnpm-workspace.yaml，再重新运行 add：

allowBuilds:
dsh-xmemo: true

连接 XMemo 账号或设置 API key（见下方认证），然后确认这一行已加载：

dsh --profile <name> --dump-config # look for "# == dsh-xmemo"

认证

两种方式，每次请求按此顺序解析（src/auth.ts）——绝不同时使用：

1. OAuth 2.1 + PKCE（推荐）。从 Web GUI 的插件卡片连接（见 Web GUI 卡片），或者以编程方式触发：向 XMEMO_OAUTH_ACTION 凭据写入 connect:<anything> 值——src/oauth.ts 通过 seam 级的 credentials/updated 事件监听它。连接过程：通过 MemoryOS 的动态客户端注册（POST /oauth/register，每次连接尝试注册一个全新的公共 OAuth 客户端——成本低，也避免缓存 client_id 带来的过期边界问题），打开默认浏览器到 /oauth/authorize 并带上 PKCE challenge，然后运行一个临时 127.0.0.1:<ephemeral-port> HTTP 监听器作为重定向目标——这正是 MemoryOS 为 Cindy 桌面端 OAuth 流程记录的 loopback 原生应用模式（已针对生产环境 xmemo.dev 实测验证：DCR 接受全新客户端的 loopback redirect_uri，/oauth/authorize 也接受该 client_id + PKCE + 显式 resource，端到端跑通）。得到的 access/refresh token 对存放在 XMEMO_OAUTH 凭据引用下，并在过期前一分钟自动刷新（带轮换——用过的 refresh token 绝不重放）。断开连接也用同样的方式，传入 disconnect:<anything> 值即可，同时会在服务端吊销两个 token。
2. 静态 API key（兜底方案）。通过 dsh 自己的凭据接缝设置 XMEMO_KEY 凭据——环境变量（XMEMO_KEY=... dsh --profile <name>）、$DSH_HOME/.credentials.yaml（XMEMO_KEY: ...）、<project>/.env / $DSH_HOME/.env，任选其一。发送时作为 X-API-Key 请求头发送（MemoryOS 的主要认证头——Authorization: Bearer 只是它的兜底；见 auth/api_key.py）。凭据引用名可配置（cordis.patch.yml 里的 apiKeyCredential），如果你不想用 XMEMO_KEY 的话。

Cindy 的宿主会为任何声明了「OAuth 凭据源」的插件通用地跑 OAuth 流程，dsh 则没有这种原语（见 Known Limitations）——本插件在 src/oauth.ts 里自己跑完整套流程，无需改动 deepseek-harness。

Config

在本 bundle 的 cordis.patch.yml 里设置，或按 profile/home 覆盖 cordis.patch.yml：

| Field | Default | Meaning |
| mode | hybrid | hybrid（本地优先 + 云端同步）、local-only（从不调用 MemoryOS）或 cloud-only（不做本地持久化）。可在运行时覆盖——见 Web GUI card。 |
| apiKeyCredential | XMEMO_KEY | 通过 ctx.credentials 解析的凭据引用。 |
| apiBaseUrl | https://xmemo.dev | MemoryOS REST API 基地址。本地开发服务器可覆盖，例如 http://localhost:8000。 |
| defaultScope | dsh | 工具调用未指定 scope 时的默认 scope 标签。 |
| agentId | DeepSeek Harness | 作为 X-Memory-OS-Agent-ID 发送。 |
| requestTimeoutMs | 30000 | 每个请求的默认超时。 |
| longRequestTimeoutMs | 60000 | xmemo_recall 和 xmemo_restore_progress 的超时。 |

mode 按每次工具调用解析（src/mode.ts，与 src/auth.ts 解析 API key 的方式一致），而不是在启动时读一次：存放在 XMEMO_MODE 凭据引用下的 hybrid/local-only/cloud-only 值优先于 cordis.patch.yml 里的默认值，所以通过 Web GUI 模式选择器保存的改动，无需重启就能在紧接着的下一次工具调用中生效。

Tools

xmemo_status、xmemo_update_state、xmemo_record_event、xmemo_list_timeline、xmemo_remember、xmemo_recall、xmemo_forget、xmemo_create_todo、xmemo_list_todos、xmemo_complete_todo、 xmemo_create_decision、xmemo_list_decisions、xmemo_resolve_decision、xmemo_save_progress、 xmemo_restore_progress、xmemo_sync —— 名称、schema 和行为都与 xmemo-cindy-plugin 的工具面一致。

| 领域 | 工具 |
| 状态与同步 | xmemo_status、xmemo_sync |
| 工作状态 | xmemo_update_state、xmemo_save_progress、xmemo_restore_progress |
| 时间线 | xmemo_record_event、xmemo_list_timeline |
| 记忆生命周期 | xmemo_remember、xmemo_recall、xmemo_forget |
| TODO | xmemo_create_todo、xmemo_list_todos、xmemo_complete_todo |
| 决策 | xmemo_create_decision、xmemo_list_decisions、xmemo_resolve_decision |

技能说明（何时调用哪个工具）刻意不放进这个包 —— 直接复用 xmemo-claude-plugin/skills//SKILL.md，把它们放进项目的 .agents/skills/ 即可；
dsh 的 skill-filesystem 服务商会从该目录发现同样的 frontmatter 格式。

Web GUI 卡片

dsh --profile web GUI 的 Settings → 插件配置（Plugin Config）面板会显示一张「XMemo」卡片，与第一方的 Bash/Agent-loop/Web-search 卡片并列，靠的是同一个包附带的浏览器 bundle （src/client/，构建到 lib/client.js，通过 package.json 里的 dsh.client manifest 字段声明 ——无需改动 deepseek-harness 本身；dsh-client-modules 会扫描每个已加载插件的 package.json 查找该字段，不只是第一方插件）。

三个控件是真正生效的：

- XMemo 账号登录（推荐，排在最前）—— Connect/Disconnect 按钮驱动 Auth 里描述的 OAuth 流程。它的状态徽章会写明当前实际生效的方式 —— 已连接 · OAuth/Connected · OAuth 或 已连接 · API Key/Connected · API key —— 与 auth.ts 自身的「OAuth 优先，API key 兜底」优先级完全一致，只有两者都未配置时才回落到 未连接/Not connected，所以一套能用的 API-key 配置不会仅仅因为 OAuth 没连上就显示成坏的。
当两者恰好同时配置时，按钮下方会有一行短提示说明这一点，并指出实际使用的是 OAuth。由于这张卡片没有直通宿主侧代码的 RPC（同样受下面那条只能用 credentials. 的限制），按钮改为通过只写的 XMEMO_OAUTH_ACTION 信号凭据来转发，而不是直接调用任何东西，然后轮询
credentials.describe('XMEMO_OAUTH')（每 2 秒一次，最多约 5.5 分钟）来检测浏览器登录何时完成。
- API key（兼容兜底）—— 通过真实的 credentials.describe/credentials.set 调用反映并可以修改实际存储的 key，包括在 XMEMO_KEY 由启动环境而非凭据存储提供时，正确显示为只读。
- 记忆模式 —— 一个真正的 （hybrid / local-only / cloud-only），带明确的 Save 按钮，保存在 XMEMO_MODE 凭据引用下，由 src/mode.ts 在紧接下一次工具调用。和 API key 字段不同，这个下拉框无法显示当前存的是哪个值——credentials.describe 刻意从不暴露凭据的值，只说明它是否已配置（见 Known Limitations）——所以它总是从 hybrid 默认值开始，用一个「customized」/「default」徽标代替值本身，就像 API key 字段的「configured」徽标从不泄露密钥一样。

另外五个配置字段（apiBaseUrl/defaultScope/agentId/requestTimeoutMs/longRequestTimeoutMs）在卡片里根本不显示——它们的默认值对绝大多数场景都够用；需要时通过 cordis.patch.yml 覆盖（见 Config）。

用 npm run build:client 构建（与宿主构建分开——它需要自己的 tsconfig.client.json 和 scripts/build-client.mjs，因为宿主和浏览器两半面向不同的运行时）。

架构说明

业务逻辑移植自 xmemo-cindy-plugin/plugins/xmemo-memory/main.js：

- src/http.ts —— 请求与错误处理（AUTH_REQUIRED、RATE_LIMITED、XMEMO_SERVER_ERROR……）。与上游有一处结构差异：Cindy 的宿主根据请求主机名注入 Authorization；本插件自己解析并附加认证头（src/auth.ts、src/oauth.ts）。
- src/store.ts —— 本地 JSON 存储（schema、清理上限、配额保护、文件损坏时回退到备份、先写临时文件再重命名的原子性）。
- src/outbox.ts —— 持久化写入队列：staged → sent | pending | held | failed，幂等操作自动重试（5 次），非幂等操作直接进入 held，需要显式执行 xmemo_sync {action: 'push', include_held: true}，本地 id → 云端 id 的依赖解析，用于写入的目标实体尚未同步的情况（例如离线完成一条 TODO）。
- src/recall.ts —— 本地 token 重叠打分与云端召回合并，包括 fail-closed 的 bucket/scope 过滤（compactCloudRecallItems）：与请求不完全匹配的云端条目会被丢弃，任何一处违规都会抑制该响应中所有不透明的云端文本。
- src/redact.ts —— 7 类疑似凭据文本的脱敏，逐字移植。
- src/oauth.ts —— 完整的 OAuth 2.1 + PKCE 客户端：动态客户端注册、作为重定向目标的临时回环 HTTP 监听器、带轮换的 token 交换与刷新，以及撤销。

一处已知差异：main.js 的存储是一个动态 JSON blob，所以它能通用地重放排队的写入。本移植版的存储按实体类型区分类型，因此重放的写入（通过 xmemo_sync，可能发生在之后的进程里）只会通用地修补 cloud_id + sync_status；更丰富的字段回填只发生在首次尝试时，且在同一次工具调用内同步完成。见 src/outbox.ts 顶部的注释。

能力与边界

| 能力 | 是否包含 | 边界 |
| 本地优先的混合记忆 | 是 | 本地存储不加密落盘 |
| OAuth 2.1 + PKCE 登录 | 是 | 需要桌面会话才能打开浏览器；无头 dsh 会回退到 API key |
| 静态 API key 认证 | 是 | 仅作兼容回退 —— 连接 OAuth 会话时绝不并行发送 |
| 持久化离线写入队列 | 是 | 非幂等写入会停在 held，等待显式批准重放 |
| 可恢复删除 | 是 | xmemo_forget 默认是软删除 |
| Web GUI 设置卡片 | 是 | 浏览器里只能改 OAuth 登录、API key 和记忆模式 —— 另外五个配置字段需要 cordis.patch.yml |
| 召回与搜索 | 是 | 仅限已认证账号可见的记忆，且任何 bucket/scope 不匹配都会 fail-closed |
| 跨智能体连续性 | 是 | 其他智能体/客户端需要各自授权的 XMemo 连接 |
| PII 脱敏 | 否 | 只脱敏形似凭据的文本，与上游 xmemo-cindy-plugin 保持一致 |
| MCP 传输 | 否 | 直接与 MemoryOS REST 通信；dsh 自带的 dsh-mcp-client 桥接是另一条独立路径，未做改动 |
| 内置技能说明 | 否 | 改为复用 xmemo-claude-plugin/skills//SKILL.md —— 见 Tools |
| 静态加密 | 否 | 与上游一致 —— 老实说就是没有，见 Known Limitations |

Known Limitations

- dsh 按设计就没有中心化插件市场。 发现渠道只有 dsh-plugin 这个 GitHub topic（CONTRIBUTING.md 里的「Contribute to the ecosystem」），本仓库也打了这个标签；除此之外没有可选的提交、审核或基于 PR 的上架流程。
- OAuth 连接需要带浏览器的桌面环境。 流程会打开系统浏览器，并在回环监听器上等待重定向；无头 dsh 实例（没有桌面会话可打开浏览器）无法完成 —— 这种情况改用静态 API key。
- XMEMO_OAUTH 和 XMEMO_OAUTH_ACTION 会出现在 $DSH_HOME/.credentials.yaml 以及 Models 页面的凭据列表里，XMEMO_MODE 也在其中 —— 这是复用唯一一条对树外插件真正开放的通道所付出的代价，可以接受（见下方 Web GUI 卡片的限制）。
XMEMO_OAUTH 以不透明 JSON blob 的形式保存 access/refresh token 对；XMEMO_OAUTH_ACTION 是瞬时的只写信号，落盘时从不保存任何有意义的内容；XMEMO_MODE 根本不是密钥。
- 每次连接尝试都会注册新的 OAuth 客户端，而不是缓存 —— Dynamic Client Registration 正是为这类临时自注册而存在，跳过缓存可以避免再持久化第四个凭据引用及其自身的过期边界情况。每个注册的客户端都是自验证的签名 token，MemoryOS 无需在服务端存储，因此不会累积成本。
- 静态数据不加密。 与上游一致——Cindy 主机的存储加密（如果有的话）对插件是不透明的；这个移植版坦诚说明：没有加密。
- 单个进程内存储锁。 多个 dsh 进程同时写入同一个存储目录时不会协调；每个存储目录只运行一个实例。
- 未实现 PII 脱敏，与上游一致：xmemo-cindy-plugin 的工具描述声称会脱敏邮箱/电话，但 main.js 里也没有这样的代码——要么在服务端，要么只是愿景。这个移植版的工具描述只写代码实际做的事。
- 重放的写入只回填 cloud_id，不回填更丰富的响应字段——见架构说明。
- Web GUI 卡片只能编辑 OAuth 登录、apiKeyCredential 和 mode；其余五个配置字段在浏览器里完全无法编辑。 harness 的通用设置持久化流水线（ctx.settingsScope）受 deepseek-harness 自身 packages/host/apiproxy/src/api-proxy.ts 里硬编码的命名空间白名单（WEB_SETTINGS_NAMESPACES）限制，树外插件无法从自己的包里扩展它（那里的源码注释把泛化这件事称为「deferred work」）。目前只有不受门控的 credentials. RPC 对第三方插件开放——也就是 apiKeyCredential 早已用于其 API key 的同一条通道——所以 mode 和 OAuth 也都搭它的便车（XMEMO_MODE、XMEMO_OAUTH/XMEMO_OAUTH_ACTION），而剩下五个配置字段根本没有开放的通道可绑定。
- 模式选择器无法显示当前已保存的值，只能显示是否保存过。 credentials.describe 报告 configured/writable，但从不报告凭据的值——对密钥来说这是对的，但这意味着模式选择无法像 Cindy 由 /kv 支撑的选择器那样，用真正存储的模式预填。选择器总是从 hybrid 默认值开始；保存时总是盲目覆盖，和 API key 字段现在的行为一样。

安全与隐私

- 凭据永远不会以浏览器可读状态进入插件内存。 Web GUI 卡片只能看到 configured/writable 布尔值（credentials.describe）——它可以修改 API key、OAuth token 和模式，但永远读不回它们的值。
- OAuth token 只存储，不记录日志。 access/refresh token 对存放在 XMEMO_OAUTH 凭据引用下；refresh token 每次使用都会轮换，重复使用（已被消费）的 refresh token 会被服务端拒绝，而不是静默接受。
- 明显的类凭据文本在写入内存和时间线之前会被脱敏（src/redact.ts，7 个类别，从上游逐字移植）——这是一道防护，不能替代把密钥挡在提示词之外。
- 本地内存是私密的，但本插件不加密——保护好设备，不要在内存内容里存密钥。
- 删除默认可恢复。 除非调用方明确请求硬删除，永久删除。
- 本仓库不包含任何生产凭据、token 或私有记忆 —— 只有凭据的引用名称（例如 XMEMO_KEY），绝不含具体值。

服务条款： 隐私政策 ·服务条款 · 支持

开发

npm install
npm run build # tsc -> lib/ (host half)
npm run build:client # tsc --emitDeclarationOnly + esbuild -> lib/client.js (browser half)
npm run typecheck
npm test # node --test over tests/.spec.ts

发布

修改 package.json 里的 version，提交，然后打标签并推送：

git tag -a v0.1.1 -m "v0.1.1"
git push origin v0.1.1

.github/workflows/publish.yml 会识别任何 v.. 标签，如果它与 package.json 中的版本不匹配就拒绝，然后运行 typecheck/test/build，使用 NPM_TOKEN 仓库 secret 以 provenance 方式发布到 npm，并创建对应的 GitHub Release。workflow_dispatch（带 version 输入）对已按该方式打标签的提交做手动重跑时，行为相同。

智能体可读元数据

| 字段 | 值 |
| 包 | dsh-xmemo |
| 插件 ID | xmemo |
| 运行时 | DeepSeek Harness (dsh) |
| 版本 | 0.1.0 |
| 角色 | 原生 Cordis 插件 + Web GUI 设置卡片 |
| 服务 | https://xmemo.dev |
| 后端 | MemoryOS REST API（不是 MCP） |
| 认证 | OAuth 2.1 + PKCE（推荐），或通过 XMEMO_KEY 使用静态 API key |
| OAuth 作用域 | memory:read memory:write |
| 工具配置档 | 16 个工具，名称/schema 与 xmemo-cindy-plugin 相同 |
| 本地存储 | 有 —— JSON 混合存储，带持久化 outbox，未加密 |
| 仓库 | https://github.com/yonro/xmemo-deepseek-plugin |
| 许可证 | MIT |

链接

- 产品：https://xmemo.dev
- 账户与 API key：https://xmemo.dev/me#api-keys
- 文档：https://xmemo.dev/product/docs
- 支持：https://xmemo.dev/support
- DeepSeek Harness：https://github.com/deepseek-ai/deepseek-harness
- 同类插件：Cindy · Claude · Codex · Hermes Agent · OpenClaw

许可证

MIT © 2026 Yonro