feat(xmemo-memory): propose XMemo Memory plugin

[yunze7373]

Plugin name & target service / 插件名与目标服务

XMemo Memory — a hybrid local-first project-memory integration for the XMemo service.

Scenario & scope / 场景与边界

Cindy users can ask the plugin to remember durable project context, recall bounded context, keep TODOs and decisions, checkpoint/restore progress, and work offline with a local outbox that synchronizes when XMemo is available.

The plugin is intentionally limited to XMemo-backed memory continuity. It does not provide generic search, arbitrary HTTP proxying, credential management outside Cindy's host vault, or access to other plugins' data. Local-only mode works without cloud credentials.

Overlap check / 与现有插件的查重

I checked the current official catalog. The closest plugins are productivity integrations such as Notion, but none provides local-first, offline-capable project memory synchronized to the XMemo service. XMemo Memory is complementary: it preserves working context and restart state across Cindy sessions rather than managing third-party documents, mail, source control, or web search.

Required capabilities / 所需能力声明

• Network hosts: xmemo.dev for OAuth and XMemo API requests; api.xmemo.dev for the compatibility API-key origin.
• Credentials: host-managed OAuth Authorization Code + PKCE, plus an optional existing user API key through Cindy's write-only secret vault. Plugin code never reads access tokens, refresh tokens, or API-key values, and never creates the Authorization header itself.
• Runtime: no Node Runtime and no node slot. Required sandbox slots are tool, network, session-context, and fs for Cindy-private local memory and the bounded outbox.
• Current candidate: v1.0.0, 16 direct tools, complete zh-CN / en / ja / ko locales; local Cindy end-to-end testing and automated tests have completed.

Irreversible side effects / 不可逆副作用

• Memory, state, event, TODO, decision, snapshot, and synchronization tools can write to the user's authorized XMemo account and/or Cindy-private local storage.
• xmemo_forget defaults to recoverable soft deletion. Permanent deletion requires both mode=hard and an explicit confirm_hard_delete=true after user confirmation.
• xmemo_sync never blindly retries an uncertain non-idempotent write; it holds it until explicit user approval. Its discard_failed action explicitly removes only permanently failed local outbox entries.
• TODO completion and decision resolution change their corresponding remote/local records. Errors report whether a mutation was not executed, completed, or has an unknown outcome where applicable.

Please confirm the positioning, capability declaration, and preferred initial audience (targeted rollout or all). Once aligned, I will submit a focused, DCO-signed PR against this repository.

[nanaco666]

该提案已按初审框架评估：涉及第三方 OAuth/PKCE 与可选 API Key 凭证注入、fs 本地存储与 session-context 槽位、以及对外同步/写副作用（含 xmemo_forget 硬删除），需要人工运营与安全审核确认数据边界与权限收敛；当前无维护者人工确认，也无关联 PR。

需要人工审核，已通知运营，请等待；维护者确认前不允许直接提交 PR。请重点确认 XMemo 服务的凭证与 workspace/account 边界、允许的 API mutation 清单、本地 outbox 数据外发范围、所有失败路径的 not_executed / executed / unknown 三态语义，以及 staged audience 方案。

[yunze7373]

感谢确认,补充说明如下:

1. 凭证与 workspace/account 边界
OAuth 走 xmemo.dev/oauth/authorize(Authorization Code + PKCE),scope 为 memory:read / memory:write,token 只对应发起授权的单个 XMemo 账号,没有跨账号/跨 workspace 切换能力。插件代码本身不读取 access/refresh token 或 API key 明文——请求头由宿主按 network.secrets[].inject 规则注入(xmemo.dev 走 OAuth token,api.xmemo.dev 走兼容 API key,互不混用)。

2. 允许的 API mutation 清单
会写入数据的工具:xmemo_update_state、xmemo_record_event、xmemo_remember、xmemo_forget(soft/hard)、xmemo_create_todo、xmemo_complete_todo、xmemo_create_decision、xmemo_resolve_decision、xmemo_save_progress、xmemo_restore_progress(默认写回恢复的 state 并记一条 restore 事件)、xmemo_sync(push / discard_failed)。全部作用于当前授权账号自己的数据;唯一的破坏性操作是 xmemo_forget 的硬删除,需要显式 mode=hard + confirm_hard_delete=true 双重确认,没有批量/账号级的破坏性操作。只读:xmemo_status、xmemo_list_timeline、xmemo_recall、xmemo_list_todos、xmemo_list_decisions。

3. 本地 outbox 数据外发范围
本地 outbox 只缓存用户主动要求持久化的 state/event/memory/todo/decision 内容,存在 Cindy 私有的 fs slot 里,不跨插件、不跨 scope 共享。客户端目前对凭证类字符串(API key、JWT、Bearer token)做正则脱敏后再落盘/同步;邮箱、电话等 PII 的脱敏目前是在 XMemo 云端按账号隐私设置执行的,本地 outbox 落盘时还是明文——已核对过工具描述的措辞与这一行为一致。

4. 失败路径三态语义
所有写操作统一走一个 pluginError(code, message, outcome, retryable) helper,outcome 取值 not_executed / executed / unknown(仅一处快照场景用 partial 表示"state 已保存但 snapshot 失败"这种复合状态,并在消息里说明)。网络错误、5xx、超时等不确定场景对写操作一律返回 unknown 并提示先去 XMemo 核实而不是盲目重试。

5. Staged audience 方案
建议先按 emails 定向给我自己的账号 + 几位早期使用者验证一段时间,观察本地/云端数据一致性和错误路径表现后,再考虑逐步扩大到 all,不做首发即全量。

[nanaco666]

感谢补充说明，已核对以下关键事实：\n\n- 凭证仅经宿主 secrets 注入通道注入（OAuth/PKCE 与兼容 API key 分开作用域），插件代码不读取 token/API key 明文；\n- 本地 outbox 落盘时邮箱、电话等 PII 仍为明文，脱敏在 XMemo 云端按账号隐私设置执行；\n- 写操作统一 not_executed / executed / unknown 三态语义，xmemo_forget 硬删除需双重确认；\n- 首发建议 staged audience（定向邮箱），不做首发全量。\n\n初审结论不变：需要人工审核，已通知运营，请等待。当前仍无维护者人工确认、无关联 PR；OAuth/API Key 注入、fs 本地存储与 session-context 槽位、对外写副作用（含硬删除）仍需运营与安全确认数据边界与最小权限方案，维护者确认前不允许直接提交 PR。\n\n