Every agent session I run ends the same way every human employee's last day ends: everything it learned walks out the door. The next session starts blank. If you run agents daily — and I run fleets of them across five brands — that reset is the single biggest tax on the whole operation. My fix is unglamorous and it works: a handoff document. One markdown file per project, the first thing any fresh agent session reads, containing the current state, the verified facts, the ordered backlog, and the guardrails. I name mine OPUS-HANDOFF.md, and some version of it now sits in nearly every active repo I own.
TL;DR
AI agent context handoff between sessions doesn't come from chat history, bigger context windows, or vendor memory features. It comes from a single source-of-truth markdown file per project — current state, verified facts (dated), an execution backlog in priority order, hard rules, and a definition of done — that every fresh session reads before touching anything. Pair it with a BLOCKERS.md for the things only a human can unblock. That's the whole system, and it turns stateless sessions into a continuous workforce.
Chat history is not memory
The obvious objection first: "just keep the conversation going." I tried. It fails for reasons that are structural, not fixable with a longer context window:
- Sessions end. Crashes, rate limits, machine restarts, or simply the next scheduled run. A launchd job that fires at 6AM does not inherit yesterday's conversation — it starts cold, every day.
- Chat history is a transcript, not a state file. It contains every dead end, every reverted decision, every "actually, ignore that." An agent re-reading 200 messages has to re-derive what's currently true from a record of everything that was ever said. That's an inference problem you're forcing onto every single session, and it goes wrong often enough to matter.
- History doesn't transfer between agents. I routinely have an orchestrator plan work and a different model execute it. They share zero conversation. The only channel between them is what got written to disk.
- Unverified beliefs compound. If session one assumed something wrong and session two reads that assumption in the transcript, the error propagates. A handoff doc forces the opposite discipline: facts get written down only after they're checked, with the date they were checked.
I made the same argument about instruction files in how I structure CLAUDE.md and skills so agents don't drift — but instruction files and handoff docs solve different problems. Instructions are timeless rules (how we always do things here). A handoff doc is current state (where this specific project stands right now, and what's next). You need both, and they must not be the same file, because state changes daily and rules shouldn't.
The OPUS-HANDOFF pattern
The name comes from my habit of having one model orchestrate and a stronger model execute: the orchestrator writes OPUS-HANDOFF.md, and the executing session's entire briefing is "read this file first, then work." Over dozens of projects the file converged on a stable anatomy. Here is the real section structure, drawn from three handoff docs currently live in my repos — the campilii.com site bake, a three-site client SEO engine, and my career-engine SEO plan:
| Section | What goes in it | Why it earns its place |
|---|---|---|
| Header block | Written date, who wrote it, who executes it, owner, repo path, deploy target | A fresh session knows instantly how stale the doc is and what role it's playing |
| Verified facts / baseline | What was actually checked, with dates — "verified 2026-07-14", curl results, what's live vs. assumed | Kills the compounding-assumption failure; my SEO-engine doc literally says "trust these over assumptions" |
| Mission | The outcome in two or three numbered items | Agents optimize what's in front of them; this keeps the front of them correct |
| Hard rules / guardrails | The nevers: no destructive git commands, never deploy X, never fabricate a metric, which account, which language rules | Rules stated where the work happens get followed; rules stated once in a chat get forgotten by session three |
| Execution backlog, in order | Numbered workstreams, P0 → P4, each item scoped, with inline ⚠️ warnings on the traps | The next session never has to decide what to do — only how to do the next item well |
| Definition of done | Concrete, checkable: "curl-200 spot-checks on ≥6 URLs, JSON-LD validates, launchd job armed and verified" | Without it, agents declare victory early — I wrote about that failure mode in the verification gap |
| Run/deploy snippets | The exact commands, copy-pasteable, with account IDs and env sources | Removes the most common way a session goes off-script: improvising infrastructure commands |
| Report-out requirement | "Write PROJECT-REPORT.md when done: what shipped, live URLs, what's pending" | The session's output becomes the next session's input — the loop closes |
Three details from the real files that make the pattern work harder than a generic template would:
Warnings live inline, at the point of danger. My client SEO-engine handoff doesn't have a "risks" appendix. It has a ⚠️ directly inside the site's own section: the working tree contains an overhaul that is preview-only, so do not deploy the working tree to production — build from a worktree of the pre-overhaul commit instead. An agent reading top-to-bottom hits the warning exactly when it's about to matter.
Facts are parameterized when they might change. The same doc anchors a whole schedule to one line: "everything below is parameterized on START_DATE=2026-07-02. If Italo corrects this date, it is ONE variable." When a human correction arrives, one edit updates the entire plan instead of leaving contradictions scattered through it.
Completed items get marked, not deleted. The career-engine doc strikes through finished backlog items and appends what was verified: ~~unblock AI crawlers~~ ✅ DONE 2026-07-14, with the exact toggle that fixed it and the curl output that proved it. The doc stays a live progress ledger. Deleting done items would throw away the how — which is precisely what the next debugging session needs.
The companion file: BLOCKERS.md
The handoff doc has a sibling: BLOCKERS.md. Its job is narrow — the list of things an agent cannot resolve alone, because they need me: a login, a payment, a 2FA code, an account approval, a judgment call about a client relationship.
The split matters operationally. Agents are instructed to log the blocker with a date and full context, then keep working the rest of the backlog — never stall the whole project on one human dependency. My career-engine handoff ends with exactly this instruction: "Update this file's checklist as items complete; log blockers in ~/career-engine/BLOCKERS.md." When I sit down, I don't ask "what's the status?" I open one short file that contains only the decisions and actions that are genuinely mine. Everything else already moved without me.
And the traffic flows both ways. When I clear a blocker, the resolution gets written back into the handoff doc as a dated, verified fact — the AI-crawler entry above cross-references "See BLOCKERS.md 2026-07-14 #1." Fresh sessions inherit the full trail: what was stuck, who unstuck it, how, and what was verified afterward.
Handoff docs turn honesty into a feature
One more thing the pattern does that surprised me: it becomes the natural place to record decisions against shortcuts, so no future session re-litigates them. My career-engine handoff contains a full section titled "Verdict on backdated blog" — a reasoned case for why we don't stamp fake publish dates on new posts (search engines timestamp by first crawl; the mismatch is a trust signal against you; and the site's entire product is credibility). My client SEO-engine doc has an equivalent section suspending a backdating plan and flagging it as the owner's call, not the agent's.
Without the handoff doc, that judgment lives in one session's chat and evaporates. With it, every future agent that touches the project reads the verdict before it can repeat the mistake. The file isn't just state transfer — it's precedent.
Why this beats "memory features"
Vendor memory features and my own memory index are useful for cross-project knowledge — standing preferences, infrastructure maps, lessons learned. But for AI agent context handoff between sessions on a specific project, a per-repo markdown file wins on every axis I care about:
- It's inspectable. I can read exactly what the next session will believe, and edit it in ten seconds when it's wrong. No opaque retrieval deciding what's relevant.
- It's versioned with the code. The state description lives next to the thing it describes and travels with the repo.
- It's model-agnostic. Any model, any harness, any future tool can read a markdown file. My handoffs have outlived two model generations already.
- It's deliberate. Automatic memory captures what happened; a handoff doc captures what a session concluded — which is a much smaller, much higher-quality set. The writing act itself is the filter.
This is context engineering at the project layer: instructions files define how we work, skills define repeatable procedures, and the handoff doc defines where we are. Together they're why a scheduled agent that fires at 6AM tomorrow — like the ones in my always-on agent setup — picks up mid-project as if the overnight gap never happened.
Adopting this on your team this week
If your team uses Claude Code or any session-based agent tooling, the migration is one afternoon:
- Create
HANDOFF.mdat the repo root of your most active project. Write the header block, the mission, and today's verified state. Date every fact. - Move the backlog in, ordered. Not a wish list — the actual next five items, each scoped tightly enough that a session could finish one.
- Write the hard rules and the definition of done. Steal my structure from the table above.
- Add
BLOCKERS.mdand the standing instruction: log human-dependencies there and keep working. - Make it the contract. Every session starts with "read HANDOFF.md first" and ends by updating it — state refreshed, done items struck through and dated, new facts added only after verification.
The compounding effect shows up fast. Sessions stop re-exploring the codebase to figure out where things stand. Two agents can work the same project in sequence without a human narrating between them. And when a person joins the project — new hire, contractor, you after two weeks away — they onboard from the same file the agents do. That's the quiet payoff: a handoff doc written well enough for a stateless machine is automatically written well enough for a human.
FAQ
What is an agent handoff document?
A single source-of-truth markdown file per project that carries state between AI agent sessions: current verified status, mission, hard rules, an ordered execution backlog, and a definition of done. Every fresh session reads it before doing anything, and updates it before finishing.
Why not just rely on chat history for agent context handoff between sessions?
Chat history is a transcript, not a state file — it mixes dead ends and reversed decisions with current truth, it doesn't survive crashes or scheduled cold starts, and it can't transfer between different agents or models. A handoff doc records only verified conclusions, dated, in a form any session can load in seconds.
What's the difference between a handoff doc and a CLAUDE.md instructions file?
Instructions files hold timeless rules — how work is always done in this repo. A handoff doc holds current state — where this project stands today and what's next, updated every session. Merging them breaks both: state churns daily, rules shouldn't.
What goes in BLOCKERS.md versus the handoff doc?
BLOCKERS.md holds only the items that need a human — logins, payments, 2FA, approvals, judgment calls — each logged with a date and context, while the agent keeps working everything else. Resolutions get written back into the handoff doc as dated, verified facts so future sessions inherit the full trail.
Does this scale beyond a solo operator?
Yes — it scales better with more people, because the file is simultaneously agent briefing and human onboarding. Teams adopting Claude Code get session-to-session continuity, agent-to-agent sequencing, and person-to-person handoff from the same document, with git as the audit trail.
WORK WITH ME
If the problem you're hiring for is agent continuity — building the handoff layer, the guardrails, and the verification loops so a fleet of agents runs your operation across sessions without a human narrating between them — that's the work I do. Get in touch.
— Italo Campilii