XMemo：DeepSeek Harness 的本地优先记忆插件

前言¶

DeepSeek Harness 处于开发者预览阶段。在构建具备长期记忆能力的智能体时，现有的方案往往依赖 MCP 桥接，这种“瘦包装器”模式在性能和灵活性上存在局限。XMemo 是一个原生 DeepSeek Harness 插件，它直接通过 Cordis 架构实现，并直接与 MemoryOS REST API 通信，而非通过中间层转发。

它是什么¶

这是一个为 DeepSeek Harness (dsh) 提供本地优先 + 云端记忆能力的原生插件。

名称：xmemo
维护者：yonro
许可证：MIT
核心价值：Native local-first + cloud memory for dsh。
后端：MemoryOS REST API (https://xmemo.dev)

核心功能¶

该插件实现了以下特性：
* 原生 Cordis 插件：直接实现，而非瘦 MCP 桥接。
* 混合存储：本地 JSON 混合存储配合离线持久写入队列。
* 聚焦召回：将本地 token 重叠匹配与云端召回合并，在 bucket/scope 不匹配时容错关闭。
* 持久结果：记录决策、偏好、事实、时间线事件、TODO 和决策。
* 工作连续性：提供活跃任务状态和重启快照，使会话可以恢复而非重放历史。
* 离线弹性：每条写入先落本地，安全（幂等）的云端重放，不确定的写入等待显式批准。
* 可恢复删除：xmemo_forget 默认为软删除。
* 工具兼容：包含 16 个工具，与 xmemo-cindy-plugin 的名称和架构兼容。

安装与启用¶

安装插件需要指定 profile 名称。

通过 npm 安装：

    dsh plugin --profile <name> add dsh-xmemo

通过 GitHub 安装：

    dsh plugin --profile <name> add github:yonro/xmemo-deepseek-plugin

通过本地路径安装：

    dsh plugin --profile <name> add ./xmemo-deepseek-plugin

注意：从 Git 或本地路径安装会拉取源码而非构建后的 lib/ 目录。由于 pnpm 会阻止首次 add 时的 prepare 脚本（该脚本会构建插件），你需要将插件添加到 profile 的 pnpm-workspace.yaml 中并重新运行 add：

allowBuilds:
  dsh-xmemo: true

安装完成后，验证配置是否加载：

dsh --profile <name> --dump-config   # 查找 "# == dsh-xmemo"

配置与认证¶

插件支持两种认证方式，按优先级顺序解析：

OAuth 2.1 + PKCE（推荐）
- 在 Web GUI 插件卡片中连接，或通过编程方式触发。
- 使用 connect:<anything> 值写入 XMEMO_OAUTH_ACTION 凭据。
- 插件通过动态客户端注册 (POST /oauth/register) 创建新的公共 OAuth 客户端，并监听本地端口处理重定向。
- 认证成功后，访问令牌对存储在 XMEMO_OAUTH 凭据引用下，并自动刷新。
静态 API 密钥（兼容模式）
- 通过 dsh 的凭据 seam 设置 XMEMO_KEY。
- 支持环境变量、$DSH_HOME/.credentials.yaml 或 <project>/.env。
- 认证头使用 X-API-Key（MemoryOS 的主要认证头）。

配置项位于插件的 cordis.patch.yml，可覆盖：
* mode：hybrid（默认，本地优先+云端同步）、local-only（仅本地）、cloud-only（仅云端）。
* apiKeyCredential：默认为 XMEMO_KEY。
* apiBaseUrl：默认为 https://xmemo.dev。

典型用法¶

连接账户：设置 XMemo 账户或 API 密钥。
验证状态：使用 dsh --profile <name> --dump-config 检查插件是否加载。
触发登录：在凭证中写入 connect:<任意值> 触发 OAuth 流程。
设置密钥：通过环境变量或 .credentials.yaml 设置 XMEMO_KEY。

适用场景与注意¶

适用场景：需要将记忆能力深度集成到 DeepSeek Harness 工作流中的开发者。
注意：
- DeepSeek Harness 本身处于开发者预览阶段。
- 该插件尚未在广泛的多人使用场景中验证。
- DeepSeek Harness 没有原生的 OAuth 原语，因此该插件自行实现了完整的 OAuth 2.1 + PKCE 流程。

总结¶

XMemo 插件通过原生 Cordis 实现，提供了本地优先的记忆存储、离线写入队列以及真实的 OAuth 2.1 认证能力。对于希望在 DeepSeek Harness 中构建持久化、可恢复智能体的开发者，这是一个直接与 MemoryOS 交互的可行方案。