Agent Handoff Notes That Keep Teammates in Context

Your workday ends mid-task; your teammate's starts hours later. Agent handoff notes close that gap: a 60-second end-of-session note — state, decision, next step — stored in shared project memory, so the next engineer and their agent start informed. The quickstart shows the setup behind it.

Handoffs lose context between people, not just agents

You end your day mid-refactor. Your teammate in another time zone starts eight hours later, opens the repo, and finds a half-split module with no explanation. Your status update says "auth split in progress" — it does not say which layout you chose, why you rejected the alternative, or what the next step is. She spends her first hour re-deriving decisions you already made.

This is the human version of why context vanishes between people and sessions. Agent context dies with the chat; human context dies with the workday. Chat threads scroll away, pasted summaries drop the reasons behind decisions, and anything you told only your agent stays in your terminal. The receiving engineer — and her agent — both start uninformed.

The companion post on the agent-to-agent handoff covers switching tools mid-task, with two agents reading one project memory. This post covers the other direction of the same problem: handing work from one person to another across shifts and time zones. The storage mechanism is shared, but the writer and the reader are humans on different schedules.

The fix is a short end-of-session note stored as memories in the shared project memory, not in chat. Three sentences: where the work stands, what you decided and why, and what happens next. The next engineer recalls it before reading code, and her agent injects it at session start. Time zones stop mattering because the note waits in memory instead of expiring in a thread.

What agent handoff notes contain: state, decision, next step

Agent handoff notes carry exactly three kinds of facts. Each part answers one question the receiver would otherwise re-derive from code:

State must be verifiable, not impressionistic. Name the files touched, the tests that pass, and the failures still open. "Almost done" helps nobody; "refresh extracted, session store pending, one staging failure open" tells the receiver exactly where to look.

Decisions need their reasons attached. A bare rule — use three modules — invites the next engineer to consolidate them again. A rule with a one-line cause — the single file hid circular imports — survives contact with a fresh pair of eyes. Store the decision plus the cause, never the discussion thread.

The next step is singular and concrete. If the receiver has to choose between three possible continuations, the note failed. Name one action with its constraints: which path, which rule still applies, which command verifies the result.

Keep each memory atomic — one fact per entry. Atomic entries let either teammate correct a single rule with PUT /update or remove a finished item with DELETE /delete/{memory_id} without untangling a paragraph. Leave out transcripts, diffs, and temporary debugging state: the repo holds file contents, and single-session scratch reasoning has no reuse value.

Write the note in 60 seconds at session end

The routine takes the last minute of a session. Finish your turn, then state three sentences in plain language: one for state, one for the decision with its reason, one for the next step. Your agent's plugin extracts those as individual facts into project memory. No summary document or special command is needed. The quickstart shows the save-and-inject loop.

Use this template so every note has the same shape:

State: <what is done, what is pending, what is failing>
Decision: <what you chose> because <one-line reason>
Next step: <the single first action, with constraints>

A filled example for the auth split looks like this:

State: Token refresh extracted to auth/refresh.js; session store still in
the monolith; billing-service tests pass except one staging-only failure.
Decision: Three modules, not two, because the single file hid circular
imports; staging calls keep the backoff rule after the rate-limit failure.
Next step: Extract the session store into the agreed path and run the
stored billing-service test command before touching anything else.

If you prefer the API, the same three sentences go through the add endpoint as a POST /add call against the data plane with your ak_ project key. Either path writes to the same project memory. What matters is timing: write the note while the session is fresh, not the next morning when half the reasoning has faded.

Make it a closing habit, not a sometimes-task. The note costs a minute and saves the receiver's first hour. Teams that write agent handoff notes every session build a running log of how the work evolved; teams that write them occasionally get fragments nobody trusts.

The receiver's first move: recall before reading code

The receiver mirrors the writer: recall first, read code second. Before opening the diff, ask your agent for the state, the decision with its reason, and the next step. The plugin injects relevant memories at session start, so the note should already be in context. If anything is unclear, run POST /search with the task terms as described in the search endpoint docs.

Confirm all three parts landed. You need the state (where to look), the decision and its reason (what not to re-litigate), and the next step (what to do first). If the next step is missing, ask your teammate directly rather than guessing — a wrong first move on a half-finished refactor costs more than one message.

Then verify against the repo. Check that the files named in the state match what is on disk and that the decision still fits the code. Memory records what the writer believed at session end; the receiver confirms it before building on it. This check takes minutes and catches the case where a late commit or a reverted change made part of the note stale.

Start the continuation from the recalled next step, not from a fresh exploration. Run the stored test command, make the named change under the stated constraints, and let the session write back what it teaches you. The receiver who recalls first avoids repeating the writer's dead ends; the receiver who skips recall repeats them.

One project memory across agents and time zones

The note works across tools because both teammates' agents read the same project memory. One project per repo, one ak_ project key per agent — that scoping keeps recall precise, so opening the checkout service returns checkout facts rather than rules from an unrelated side project. For the team setup, see the shared agent memory guide.

Writer and reader can use completely different agents. You work in Claude Code, your teammate works in Codex, a third reviewer reads through an MCP-compatible client — all three read and write the same memory because the memory belongs to the project, not the tool. The handoff note does not care which plugin stored it or which client recalls it.

No overlap window is needed once the note lives in memory. The writer stores it at 6pm; the reader recalls it at 9am their time with nothing lost in between. Async handoffs depend on a habit both sides keep, not on schedules.

Use the right credential for the job. Data-plane writes — storing and recalling notes — use ak_ project keys. The at_ tokens are management-plane only, scoped to operations like projects and key management, and do not belong in agent configurations or handoff calls.

Keep notes fresh: update when plans change, delete when done

A handoff note is a living entry, not an archive. When the plan changes — the layout decision gets reversed, the backoff rule gets replaced, the next step is done and a new one takes its place — correct the stored fact with PUT /update instead of adding a competing entry. Two contradicting facts force every future search to return both and make the next receiver guess which one holds.

When an item lands, remove it. A finished next step that stays in memory keeps surfacing in searches weeks later, and a decision about code that no longer exists misleads more than it helps. DELETE /delete/{memory_id} retracts a single atomic entry without touching the rest of the note, which is why one-fact-per-entry matters from the start.

Audit on a rhythm that fits the project. Pull GET /list with a small limit — paginated with limit and offset — and scan for duplicates, contradictions, and entries whose code is gone. A weekly five-minute pass keeps recall trustworthy. A stale memory layer trains teammates to stop recalling, which breaks the loop.

End every session the same way: state the one new thing the project should keep. Update what changed, delete what landed, and write the next note. Teammates in any time zone, on any agent, start informed.

FAQ

Written by Efe — Oct 11, 2026 · More articles · X @AudaxicTech