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 交互的可行方案。