ai-memory handoff

Use this skill for single-use cross-session handoffs. Handoffs are for the next agent, not durable project documentation.

Tools in this cluster

• memory_handoff_list is the read-only inspect path: it returns open handoffs without claiming or expiring them. Use it when no SessionStart handoff block is in context (Grok, Zero, and other no-stdout / MCP-only clients), when the user asks what is pending, or when you need an exact id.
• memory_handoff_accept consumes one open handoff. Prefer listing first when no prepended block is visible, then pass the listed handoff_id to claim that exact row. Omitting handoff_id claims the latest eligible open handoff. Use this when the user asks where we left off and no already-fetched handoff block is visible.
• memory_handoff_begin creates a terse next-session handoff only when the user is wrapping up, ending the session, or explicitly asks to save context for the next session.
• memory_handoff_cancel expires a mistaken pending handoff by exact handoff id from begin or list.

Single-use handoff behavior

The SessionStart hook usually fetches and consumes any pending handoff before the agent sees its first prompt. If the current context already contains a pending handoff block, answer from that block directly. Do not call the accept tool again to find it in another project, because handoffs are single-use: after SessionStart consumed it the tool returns no handoff, with status consumed_by_hook when the client forwards its session id and none_pending otherwise.

If no pending handoff block is visible, inspect with memory_handoff_list first. Listing does not claim or expire anything. When the user asks where we left off, claim one listed row with memory_handoff_accept and that handoff_id, using the client-aware project scope below. Do not treat list as a second accept path.

Reloading context after a compaction

A prompt that starts with reload context gets a "compaction recap" block from the hooks: the user's prompts and the last captured reply from the stretch of this session that the last compaction dropped, plus the project's open handoffs, none of them claimed. Claude Code, Codex and OpenCode add it to that turn; Grok shows it after the first tool result. Answer from that block, then do what the rest of the prompt asks. If no recap block is in context, use the ai-memory retrieval skill to read this session's raw prompts and replies (kinds: ["user-prompt", "stop"]).

Creating a handoff

Create a handoff only at session end or when the user explicitly asks to save context for the next session. Do not use handoffs for status checks, briefings, project notes, or permanent memory. Keep the summary to two or three concise sentences, and put details in open questions and next steps bullets.

Lifecycle hooks already capture routine prompts and tool calls, so do not manually write a handoff just to record normal progress.

On a shared server, a handoff belongs to the operator who created it. Set shared: true only when the user explicitly wants any operator in the project to receive the baton; do not infer sharing from ordinary collaboration prose.

Canceling a handoff

Cancel only when the user asks to discard a handoff or you created one by mistake. Use the exact handoff id returned by the begin or list tool. Cancellation is idempotent from the user's point of view, but it should still target only the known handoff.

Accept and cancel normally act only on the caller's own plus shared handoffs. any_owner: true is a root-only recovery action over another operator's context; use it only on an explicit user request.

Project scope

Choose scope from the MCP client's identity support:

• Session-aware MCP clients that forward the real lifecycle-hook session id on every request should use automatic current-project routing. Omit workspace, project, and cwd for the current repository; pass explicit scope only when the user names a different project.
• Static MCP clients (including clients with lifecycle hooks but no bridge connecting that hook session id to MCP requests) must pass workspace and project together on every project-scoped call, including requests about this project, here, or our work. Read the exact names from the nearest .ai-memory.toml when it declares both. Without a marker override, derive the project from normalized upstream, then origin, using the full repository path without its host (github.com/acme/api → acme-api); use the folder basename only when no valid remote exists. Never rely on the server's last active project.

This rule applies only to project-scoped calls. For cross-project retrieval, global=true must omit workspace, project, and scopes. For a standing preference written with scope: "global", omit workspace and project.