恢复与 agent 移交

用户目标与工作流边界

这一实用工作流使开发者和 AI agent 能够恢复中断的会话，跨 CLI/IDE 重启恢复活动上下文，并在不同 agent 之间（例如 Claude Code、Codex、Cursor 或 Hermes）移交正在进行的工作，而不会丢失架构决定、活动阻塞项或任务连续性。该工作流保证上下文移交传递有边界的结构化状态，而不是转储不受限制的会话历史记录或泄露凭据。

可用性与前提条件

恢复与移交所需的能力跨独立 XMemo Skill 和具有明确权限边界的原生 MCP 客户端配置文件提供：

• 独立 Skill（Claude Code、Codex、OpenClaw）：来自服务版 1.1.35 help.mjs 的逐字 CLI 命令：save-state 和 restore-state（第 88-95 行）、restart-snapshot 和 restart-restore（第 104-111 行）、recall-context（第 84-87 行）、remember（第 72-75 行）以及 todo-add/list/done（第 112-123 行）。
• MCP claude-plugin 配置文件：包括 update_state、create_restart_snapshot、restore_restart_snapshot、record_event、recall_context、remember、recall、todo、create_pending_decision 和 resolve_decision。
• MCP cursor-plugin 与 ordinary-full 配置文件：包括 update_state、create_restart_snapshot、restore_restart_snapshot、record_event、recall_context、remember、recall、update_project_decision、update_project_todo、list_memory_todos、complete_memory_todo 和 query_audit。
• MCP generic-public、chatgpt-public 和 public-only 配置文件：公开只读摘要投影，如 get_project_summary(project_id, focus) 和 memory_overview；写入工具需要经过身份验证的插件会话。
• 前提条件：活动身份验证令牌（XMEMO_KEY 或本地 skill-credentials.json），带有用于检查点持久化的 memory:write 作用域和用于上下文检索的 memory:read 作用域。

一个完整任务：合成多 agent 移交

在此合成场景中，Agent Alpha（在 Claude Code CLI 中运行）在项目 proj_payments_v2 中处理数据库连接池重构，记录明确的决定和阻塞项，封装重启快照（restart snapshot），并将执行移交给 Agent Beta（在 Cursor IDE 中运行）。

捕获活动状态与阻塞项

Agent Alpha 在移交前使用 save-state 或 update_state 记录其当前任务和活动阻塞项：

node scripts/xmemo-skill.mjs save-state --key active_task --content "Refactoring database connection pooling to asyncpg: blocked on internal CA bundle" --ttl_seconds 86400

创建连续性重启快照

Agent Alpha 在移交前使用 restart-snapshot 或 create_restart_snapshot 捕获完整的会话连续性包：

node scripts/xmemo-skill.mjs restart-snapshot --state_key active_task --session_id sess_alpha_0928 --ttl_seconds 604800

在接收方 agent 会话中恢复

Agent Beta 在 Cursor IDE 中启动，恢复快照并检索有边界的背景上下文：

node scripts/xmemo-skill.mjs restart-restore --source_session_id sess_alpha_0928 --target_session_id sess_beta_0929
node scripts/xmemo-skill.mjs recall-context --query "internal CA bundle TLS root pin database pooling" --max_items 5 --max_tokens 2000

可观察结果

成功的移交会在工具响应中生成明确、可验证的确认，没有任何对话式修饰：

• 快照创建输出：create_restart_snapshot 返回："✅ Restart snapshot created. ID: snap_xxx Captured: state=1, events=1, reminders=0, decisions=1"。
• 恢复收据：restore_restart_snapshot 恢复活动状态槽位，在 target_session_id 下记录审计恢复事件，并返回精确恢复的状态内容和阻塞原因。
• 上下文根据：recall_context 返回标记有来源 session_id、agent_id 和确切创建时间戳的结构化记忆条目，允许 Agent Beta 立即验证决定来源。

Agent 可以访问的内容

跨会话的上下文访问严格受授权作用域和来源的约束：

• 有边界的记忆上下文：恢复的 agent 接收与查询匹配的结构化状态槽位、时间线里程碑和明确检索的记忆；它们不会接收无关的开发者记忆或无关的项目。
• 读己所写一致性（Read-Your-Writes）：状态更新和重启快照会立即写入事务性元数据存储，防止移交 agent 之间出现最终一致性竞态条件。
• 调用者来源：召回的上下文包括调用者身份（source_identity、agent_id 和 node_id），以便后续 agent 能够区分人类用户的指令与自动化对等 agent 的提议。

共享与存储边界

严格的隐私和安全隔离规则适用于所有恢复与移交操作：

• 禁止原始记录转储：切勿将完整的聊天记录或模型思维痕迹存储在状态或记忆中。移交仅传递结构化状态摘要、明确决定事件和经过验证的事实。
• 零凭据泄露：令牌、API 密钥、密码和授权标头切勿写入 state_key、content 或 metadata_json 中。
• 项目隔离边界：在未经明确团队许可的情况下，绑定到 project:proj_payments_v2 的快照在其他项目或个人作用域下认证的会话中完全不可访问。

故障恢复

使用确定性回退策略处理常见的恢复和移交错误：

• 快照已过期或 TTL 超限：当快照超过 ttl_seconds（快照默认为 7 天，活动状态为 24 小时）时，restore_restart_snapshot 会报告快照已过期。回退到 get_project_context(project_id="proj_payments_v2") 或带有项目作用域查询的 recall_context。
• 缺少会话 ID：如果 source_session_id 不可用或丢失，使用 node scripts/xmemo-skill.mjs restore-state --key active_task 恢复最新的状态记录，或使用 todo-list 列出活动 TODO。
• 作用域或租户不匹配：如果 agent 尝试跨未授权租户或不匹配的项目作用域恢复快照，服务器将拒绝请求并返回 HTTP 403 Forbidden。请在客户端配置中验证绑定的项目 ID。

相关参考

有关相关架构、作用域定义和工具目录，请参阅以下指南：

• 跨 agent 工作流：/docs/operations/cross-agent-workflow 了解编排概念。
• 作用域与隔离：/docs/concepts/scopes 了解 4 层正交作用域层次结构。
• 项目工作区：/docs/concepts/projects 了解项目关联和边界强制执行。
• 快速入门：/docs/quickstart 了解客户端配置和初始身份验证。
• MCP 工具参考：/docs/tools/recall-context 和 /docs/tools/remember 了解底层工具参数。