Agent handoffs: keeping context when one session ends and the next begins

Real work rarely fits in one session. A migration spans days. A gnarly bug takes three sittings to corner. A feature gets built in pieces as you find time. Each time an agent's context window fills up or a session ends, there's a seam, and unless something crosses that seam, the next agent starts cold.

The thing that crosses the seam is a handoff. It's the single highest-leverage note an agent can write, because it's the difference between "continue where we left off" and "please re-read everything and guess what I was doing."

What a good handoff contains

A handoff isn't a transcript. Nobody, human or agent, wants to re-read a play-by-play. It's a tight summary aimed squarely at the next session. The pieces that matter:

• Goal. What are we actually trying to accomplish? One or two sentences.
• State. What's done, what's in progress, what's untouched. Be concrete: "auth middleware wired up and tested; rate limiting stubbed but not enforced."
• Decisions. The choices already made and why, so the next session doesn't relitigate them. This is the part that's hardest to recover if it's lost.
• Dead ends. What you already tried that didn't work. This quietly saves the most time: it stops the next agent from re-walking a path you've already proven is a wall.
• Next step. The single most useful thing to do next, stated plainly. A handoff that ends with a clear "do this next" is one an agent can act on immediately.
• Pointers. The specific files, functions, PRs, or line numbers involved, so the next session navigates straight there instead of searching.

What to leave out

Just as important: don't put the code in the handoff. Code lives in git. Duplicating it into a note means the note goes stale the moment someone edits the file, and now you have two sources of truth that disagree. Reference the code by path and line; let version control hold the actual bytes.

Also skip the moment-by-moment narrative. "Then I ran the tests, then I looked at the logs, then I noticed…" is noise. Capture the conclusion, "the flaky test was a timezone bug in parseDate," not the journey to it.

A template that works

You don't need anything fancy. A consistent shape is more valuable than a clever one, because agents learn to scan it:

# Handoff: <task name>

**Goal:** what we're trying to do

**Done:** what's finished and verified
**In progress:** what's half-built, and where it stands
**Blocked:** anything waiting on a decision or dependency

**Decisions:** choices made + why
**Dead ends:** what we tried that didn't work

**Next step:** the one thing to do next
**Pointers:** src/auth.js:120, PR #42

Decision records and debugging trails are close cousins of the handoff: same discipline, narrower scope. It's worth keeping a light template for each so your agents produce them consistently.

Where the handoff should live

A handoff is only useful if the next session can find it. Pasted into a chat that's now closed, it's gone. Buried in a commit message, it's neither searchable nor structured. The right home is a persistent memory layer the next agent can query.

That's where Knownbase comes in. An agent finishing a session calls upsert_note to save the handoff into the project; the next agent (the same tool or a different one, yours or a teammate's) calls search_notes and picks it up. Notes are versioned, so you can see how a handoff evolved, and they support [[links]] between related notes, so a handoff can point straight at the decision record it depends on.

New to connecting an agent to a memory server? Start with How to give Claude Code and Codex persistent memory over MCP.