How Session Handoffs Keep Context Across AI Coding Sessions

AI coding agents forget everything when a session ends. A short handoff note carries what you did, what is unfinished, and what comes next.

An AI coding agent has a finite context window, and a real task rarely fits inside one. The session fills up, or you stop for the day, or you start a new conversation to keep the model fast. When that happens, everything the agent knew about the work is gone: what you changed, why you changed it, what is still broken, and what you meant to do next. The fix is old and boring. When a human hands off a shift, they leave a note. An AI session should leave the same note, and the next session should read it first.

Why AI sessions lose the thread

The context window is the agent's entire working memory. It holds the files you opened, the decisions you argued through, the dead ends you already ruled out, and the half-finished plan in your head that never got written down. All of it lives in one conversation and nowhere else.

That memory is volatile. It does not survive the end of the session for three common reasons. The window fills up on a long task and the earliest messages fall out of scope. You close the laptop and come back tomorrow to a fresh conversation. Or you deliberately start over because a bloated context makes the model slower and more likely to lose focus. In every case the next session starts blank, and you pay the same tax: you re-explain the codebase, re-state the goal, and re-derive the decisions you already made an hour ago. On a task that spans three or four sessions, most of that re-explaining is pure waste.

The problem is not that the agent is forgetful. The problem is that its memory was never written anywhere durable. Nothing you said this session is on disk. Fix that, and the session boundary stops being a cliff.

Externalize the memory to disk

The whole idea is one move: take the state that was living in the context window and put it in a file. A handoff note is that file. It is a small, durable record of where the work stands, written at the end of one session so the start of the next can load it.

This mirrors how people already work. A shift worker leaves a log. A developer going on vacation writes a handover doc so a teammate can pick up the ticket. Nobody expects the next person to reconstruct three days of reasoning from a diff. The note carries the reasoning across the gap. An AI session needs the same thing for the same reason, except the gap is not between two people, it is between two conversations with the same tool.

Once the state lives in a file, continuity stops depending on memory. Any session, today or next week, can read the note and resume with the full picture. The context window becomes disposable, because the part that matters was saved.

What a handoff actually holds

A good handoff answers four questions and nothing else. It is a status report, not a diary. Length is the enemy here, because a wall of text does not get read, by a person or by a model skimming for the relevant line.

Section	What it holds	Keep it to
Done	What this session finished, in one line each	A few bullets
Key decisions	The choices that shape the code, and why	The ones that would surprise someone
Open and next	What is unfinished, and the trap the next session should avoid	The single most important thing first
Pointers	Where to look: files, commits, tickets, logs	Exact paths, not vague hints

The first section is a summary of results, so the next session knows what ground is already covered. The second is the expensive part to reconstruct: the reasoning behind a decision, the option you rejected and why, the constraint that is not obvious from the code. The third is where continuity actually happens, because it names the next step and the landmine near it. The fourth turns the note into an index, so the next session reads three files instead of thirty.

Keep it dense. A handoff that hedges and repeats is a handoff nobody finishes reading, which defeats the point.

A handoff template

A fixed shape makes the note fast to write and fast to scan. The same headings every time mean the next session knows exactly where to look for the next step. Here is a template that has held up across long tasks:

# Handoff: <task name> (<date>)

## Done this session
- Wired the payment webhook to the new queue
- Added retry with backoff, capped at 5 attempts

## Key decisions
- Idempotency key is the provider event id, not our order id.
  The provider can resend an event, and order id is not unique per event.
- Chose an at-least-once queue over exactly-once. Handlers are already
  idempotent, so duplicates are safe and the setup is far simpler.

## Open / next
- NEXT: the dead-letter path is not wired yet. Failed events vanish
  after 5 retries. Start here.
- Trap: the staging webhook secret differs from prod. Do not copy the
  prod value into staging config.

## Pointers
- Handler: internal/payments/webhook.go
- Queue setup: internal/queue/consumer.go:42
- Failing test: TestWebhookRetry (currently skipped)
- Related commit: a1b9f30

Two details make it work. The next step is labeled and sits at the top of its section, so a resuming session acts on it without hunting. And the traps are stated as traps, not buried in prose, because the whole value of a handoff is warning the next session away from a mistake it cannot see coming.

Automating the handoff

Writing a note by hand every time is friction, and friction means it does not happen. The better version is automatic. Watch for the signals that a session is ending, and generate or refresh the handoff at that moment.

The signals are easy to catch. A person types something like "let us wrap up here", "that is enough for today", or "start a new session". A tool can detect a context window approaching its limit. Any of these can trigger the note. The content adapts to the state of the work. If the task is finished, the handoff is short, a couple of lines saying it is done and where it landed. If the work is mid-flight, the note leans on the open and next section, because that is what the following session needs most.

The payoff is that the note stays current without discipline. You do not have to remember to write it, and you do not have to remember to update it. The moment you signal that you are done, the state of the work is already on disk, and the next session already has something to read.

When a handoff is not worth it

A handoff is overhead, and overhead is only worth paying when it buys something back. For a short, one-shot task that starts and finishes inside a single session, it buys nothing. Renaming a variable, fixing a typo, writing one small function: there is no gap to bridge, so writing a note is pure cost. Do not do it.

The value shows up in two shapes of work. The first is a task too large for one session, where the note carries context across your own session boundaries. The second is work that passes between several people or several agents, where the note is the interface between them. In both, the cost of writing a few dense bullets is trivial next to the cost of reconstructing an afternoon of context from scratch.

The honest rule: reach for a handoff when the work will outlive the session. Skip it when it will not. Guessing wrong in the cheap direction, writing a note you did not need, costs you a minute. Guessing wrong in the expensive direction, skipping a note on a multi-session task, costs the next session an hour.

Keeping the handoff honest

A handoff has one failure mode that is worse than not having one: going stale. If the note says the dead-letter path is unwired, but you quietly wired it in the last session and did not update the note, the next session reads a lie. It works from a false picture and wastes time discovering that the map does not match the ground. A wrong handoff is more dangerous than a missing one, because a missing note makes you rebuild context knowing you have none, while a stale note makes you trust context that is already false.

This is why automation matters beyond convenience. A note refreshed at every session end is a note that tracks reality, because it is rewritten from the current state each time rather than edited by hand and slowly drifting. Keep one canonical handoff file and overwrite it. Do not accumulate a pile of dated notes where the reader has to guess which one is current.

The mechanism is old, and that is the point. People have handed off shifts with a log for as long as there have been shifts. The only new part is that the coworker on the next shift is another instance of the same tool, one with no memory of the last shift and no way to get it except the note you left. Write the note. Keep it short. Keep it true. The next session, whoever or whatever runs it, will pick up exactly where you left off.