# Resume & agent handoff

Capture explicit session checkpoints, recover project context, track decisions and blockers with sources, and hand off between agents without scope creep.

- Canonical: https://docs.xmemo.dev/docs/guides/resume-and-handoff
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 7fc560b1de2bb1f275fb3d798bf58bcaa2e9af0314dda2f39d5f35fdcce56e9a
- Edition-Digest: 16b0f1c17b3b115ced862bf19826d2ec7374b8273081c997a99a63269efb0bed
- Source-Revision: sha256:dacab21c9fc471e388ff6bbe4a84e7266ffca6eed88baebabcf7f68ee9957d6a

## User goal and workflow boundary

This practical workflow enables developers and AI agents to resume interrupted sessions, recover active context across CLI/IDE restarts, and hand off ongoing work between different agents (such as Claude Code, Codex, Cursor, or Hermes) without losing architectural decisions, active blockers, or task continuity. The workflow guarantees that context handoffs transmit bounded, structured state rather than dumping unrestricted conversational histories or leaking credentials.

## Availability and prerequisites

The capabilities required for resume and handoff are exposed across the standalone XMemo Skill and native MCP client profiles with explicit permission boundaries:

- Standalone Skill (Claude Code, Codex, OpenClaw): Verbatim CLI commands from served 1.1.35 help.mjs: save-state and restore-state (lines 88-95), restart-snapshot and restart-restore (lines 104-111), recall-context (lines 84-87), remember (lines 72-75), and todo-add/list/done (lines 112-123).
- MCP claude-plugin profile: Includes update_state, create_restart_snapshot, restore_restart_snapshot, record_event, recall_context, remember, recall, todo, create_pending_decision, and resolve_decision.
- MCP cursor-plugin and ordinary-full profiles: Include 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, and query_audit.
- MCP generic-public, chatgpt-public, and public-only profiles: Expose read-only summary projections like get_project_summary(project_id, focus) and memory_overview; write tools require an authenticated plugin session.
- Prerequisites: Active authentication token (XMEMO_KEY or local skill-credentials.json) with memory:write scope for checkpoint persistence and memory:read for contextual retrieval.

## One complete task: Synthetic multi-agent handoff

In this synthetic scenario, Agent Alpha (running in Claude Code CLI) works on a database connection pooling refactor in project proj_payments_v2, records an explicit decision and blocker, seals a restart snapshot, and hands off execution to Agent Beta (running in Cursor IDE).

## Capture active state and blocker

Agent Alpha records its current task and active blocker before handoff using save-state or 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
```

## Create continuity restart snapshot

Agent Alpha captures the complete session continuity package before handoff using restart-snapshot or create_restart_snapshot:

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

## Resume and restore in receiving agent session

Agent Beta launches in Cursor IDE, restores the snapshot, and retrieves bounded background context:

```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
```

## Observable result

A successful handoff produces explicit, verifiable confirmation in the tool response without conversational embellishment:

- Snapshot creation output: create_restart_snapshot returns: "✅ Restart snapshot created. ID: snap_xxx Captured: state=1, events=1, reminders=0, decisions=1".
- Restoration receipt: restore_restart_snapshot restores the active state slot, logs an audit restore event under target_session_id, and returns the exact restored state content and blocker reason.
- Contextual grounding: recall_context returns structured memory items tagged with source session_id, agent_id, and exact creation timestamps, allowing Agent Beta to immediately verify the decision source.

## What agents can access

Context access across sessions is strictly bounded by authorized scopes and provenance:

- Bounded memory context: Restoring agents receive structured state slots, timeline milestones, and explicitly retrieved memories matching the query; they do not receive irrelevant developer memories or unrelated projects.
- Read-your-writes consistency: State updates and restart snapshots are written to the transactional metadata store immediately, preventing eventual consistency race conditions between handoff agents.
- Caller provenance: Recalled context includes caller identity (source_identity, agent_id, and node_id) so subsequent agents can distinguish human user directives from automated peer agent proposals.

## Sharing and storage boundaries

Strict privacy and security isolation rules apply to all resume and handoff operations:

- No raw transcript dumps: Never store full chat transcripts or model thought traces in state or memory. Handoff transmits only structured state summaries, explicit decision events, and verified facts.
- Zero credential leakage: Tokens, API keys, passwords, and authorization headers must never be written into state_key, content, or metadata_json.
- Project isolation boundary: Snapshots bound to project:proj_payments_v2 are strictly inaccessible to sessions authenticated under a different project or personal scope without explicit team permissions.

## Failure recovery

Handle common resume and handoff errors using deterministic fallback strategies:

- Expired snapshot or TTL: When a snapshot exceeds ttl_seconds (default 7 days for snapshots, 24 hours for active state), restore_restart_snapshot reports snapshot expired. Fall back to get_project_context(project_id="proj_payments_v2") or recall_context with a project-scoped query.
- Missing session ID: If source_session_id is unavailable or lost, recover the latest state record using node scripts/xmemo-skill.mjs restore-state --key active_task or list active TODOs using todo-list.
- Scope or tenant mismatch: If an agent attempts to restore a snapshot across an unauthorized tenant or mismatched project scope, the server rejects the request with HTTP 403 Forbidden. Verify the bound project ID in your client configuration.

## Related reference

For related architecture, scope definitions, and tool catalogs, consult the following guides:

- Cross-agent workflow: /docs/operations/cross-agent-workflow for orchestration concepts.
- Scopes and isolation: /docs/concepts/scopes for the 4-tier orthogonal scope hierarchy.
- Project workspaces: /docs/concepts/projects for project associations and boundary enforcement.
- Quickstart: /docs/quickstart for client configuration and initial authentication.
- MCP tools reference: /docs/tools/recall-context and /docs/tools/remember for low-level tool parameters.

## ChatGPT user

Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.

Connect the hosted XMemo MCP server through the ChatGPT/OpenAI app OAuth flow, then approve the memory:read and memory:write grant for your XMemo account.

Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.

If OAuth fails or tools do not appear, sign out of the MCP server in the host app, reconnect the XMemo server URL, and retry before creating direct tokens.

## Copilot / Codex developer

Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.

Use OAuth for VS Code / GitHub Copilot and Gemini CLI when available. For Copilot CLI, Codex, Cursor, or other direct MCP clients, keep XMEMO_KEY in the local environment or secret store and set a stable XMEMO_AGENT_INSTANCE_ID.

Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.

If recalls are empty, verify the selected MCP config path, the XMEMO_KEY environment variable for direct clients, and any stale OAuth credential in the host app.

## Team / enterprise pilot owner

Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.

Create or enter the protected XMemo workspace, invite approved users, then connect each client through OAuth or a scoped direct credential according to the readiness badges.

Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.

If a member cannot connect, check role permissions, OAuth approval, client readiness status, and support guidance before issuing a new token.

## Autonomous agent operator

Let headless or scheduled agents record progress, retrieve prior decisions, and keep a stable non-secret instance identity.

Fetch /api/v1/mcp/config/autonomous-agent. Prefer auth_modes.oauth when the runner supports OAuth + custom headers; use auth_modes.xmemo_key with XMEMO_KEY from a secret store only for fully headless runners.

Run one synthetic task that writes progress to XMemo, restart the runner, and confirm it recalls that progress using the same XMEMO_AGENT_INSTANCE_ID.

If attribution changes or recalls split across instances, persist XMEMO_AGENT_INSTANCE_ID outside git and verify the runner is not regenerating it on every start.