# 恢复与 agent 移交

捕获显式会话检查点，恢复项目上下文，追踪带有来源的决定与阻塞项，并在 agent 之间移交工作且避免范围蔓延。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/resume-and-handoff
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: f7f1e02f35c3c797c1b7fcc4aee1048fa1f409ef7ed79ecaf362c4d2d5f7b15a
- Edition-Digest: e1b6aa315b34b79be175f9140b1ba3099dc1cfdec414accdbd46f08aa34cadcc
- Source-Revision: sha256:dacab21c9fc471e388ff6bbe4a84e7266ffca6eed88baebabcf7f68ee9957d6a

## 用户目标与工作流边界

这一实用工作流使开发者和 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 记录其当前任务和活动阻塞项：

```bash
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 捕获完整的会话连续性包：

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

## 在接收方 agent 会话中恢复

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

```bash
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 了解底层工具参数。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。