Handoffs

await hm.commitHandoff({
  facts: [
    "Deploy script is at ops/deploy.sh",
    "Staging runs Postgres 16 in eu-west-1",
  ],
  narrative: "Traced the timeout to connection pool exhaustion under retry.",
  decisions: [
    "Kept pgbouncer, raising the pool size just masks the retry storm",
  ],
  priorities: [
    "Cap retries before touching the pool",
    "Add a metric for pool wait time",
  ],
  warnings: [
    "Do not bump max_connections, we hit the RDS ceiling doing that in March",
  ],
});

All five layers are required. Each accepts a string or an array of strings.

Why all five

A summary that omits why leaves the next thread to rediscover it, usually by repeating the failure that produced the warning. Priorities and warnings are the two layers a summary drops first and the two the receiving agent misses most.

Reading them

const { handoffs } = await hm.handoffs();

Handoffs are also weighted heavily in ordinary recall, so an agent that never asks for one explicitly will still be handed it when relevant.

Handoffs versus threads

• A thread is automatic, a record of what happened.
• A handoff is deliberate, you choosing what the next agent needs, including judgements that appear nowhere in the transcript.

Use a thread to remember. Use a handoff to hand over.