A session handoff is how I stopped losing hours of context every time a Cursor chat ends. AI coding agents are stateless: close the session, and everything the agent built up about your work is gone. The next chat starts from zero.
I solved this for my projects with two small custom skills and a per-project wiki folder. This post is a deep dive into Layer 2 of my Cursor workflow, the personal harness from the pillar post. Here I explain exactly how the system works.
The problem: every new session starts from zero
Closing a chat destroys more than the transcript; it destroys the working state. What actually gets lost when a session ends:
- the decision history, and the reasoning behind each decision
- what was tried and rejected
- the current state of half-done work
- known gotchas and workarounds
Re-explaining all of that by hand is a tax. Across several projects it compounds: either I waste time rebuilding context, or the agent repeats mistakes we already paid for once.
The tax is worst on projects I return to after a gap. After a week away, I do not remember the details well enough to re-explain them, so the re-explanation itself becomes unreliable. The agent then works from my degraded memory instead of the actual state.
Chat history and search exist, but a pile of transcripts is not a working memory. Digging through old conversations to find one decision is slower than making it again. A new session needs a curated summary, not a recording.
The design: treat context as a document, not a conversation
The core idea is to treat context as a document instead of a conversation. At the end of a meaningful session, the agent itself writes a structured handoff document. At the start of the next one, the agent reads it back.
The agent maintains its own memory; the human just triggers it. I do not write the summaries, and I do not want to. The agent knows what happened in the session better than my end-of-day memory does.
Writing the handoff at the end of the session is the key timing decision. That is the moment when the full context still exists and the summary costs almost nothing. Reconstructing the same summary a week later, from a transcript, would be slow and lossy.
The implementation is two skills and one folder convention:
session-handoffis the write side; it runs when a session endssession-startis the read side; it runs when a new session begins- every project keeps a
docs/wiki/folder, with anindex.mdas the agent’s entry point and ahandoffs/folder holding one dated file per handoff (for example,2026-07-19.md)
Nothing here is exotic. It is markdown files in a predictable place, and that plainness is exactly why any agent can work with them.
How the session handoff works (the write side)
The session handoff skill is not a “dump everything” command; it has judgment rules. It decides when a handoff is worth writing, what goes into it, and what to clean up on the way out.
When it writes
A handoff gets written when any of these apply:
- the conversation has grown long enough to feel context-window pressure
- a large chunk of work just finished
- the next task has a completely different scope
- I ask for one
Small sessions skip the handoff on purpose. A couple of trivial fixes or a pure Q&A chat produces no document, because there is no meaningful progress to preserve.
What it writes
Each handoff is a dated markdown file with four fixed sections: Done, Current state, Next steps, and Warnings. The Warnings section holds known issues, workarounds, and environment notes. Warnings earn their place: they are the section that prevents a fresh session from rediscovering an old trap.
The fixed shape matters because the reader is another agent. Predictable structure beats free-form prose when the consumer is a program that needs to act on the content.
Where it writes
The skill also updates the wiki index, so the index alone tells you where things stand. It refreshes the handoff log table with the date, a link, and a one-line summary. It also updates a “last handoff note” field in the index frontmatter.
That index maintenance is what makes the wiki more than a pile of dated files. Anyone, human or agent, can open one file and see the whole project’s trajectory at a glance.
Cleanup duty
Before finishing, the skill deletes temporary debug files and scripts created during the session. The next session opens a clean repo, not an archaeology site of leftover experiments.
The read side: restoring in seconds
session-start mirrors the write side and restores context at the start of a new session. It runs four steps:
- locate the project’s document index, trying a priority list of conventional paths so it works across differently structured repos
- read the index and the latest handoff file in parallel
- post a four-line summary: done, current state, next steps, warnings
- propose continuing from the next-steps list
The experience is what sold me. Starting a new session on a project I have not touched in days takes seconds, and the agent proposes the correct next task without me explaining anything.
This very blog runs that way between writing sessions. The agent reads the wiki, tells me where the last session stopped, and suggests what to publish or draft next.
The four-line summary format also acts as a quick sanity check. If the “current state” line surprises me, I know the handoff and reality have drifted, and I fix that before doing new work.
Honest limits
The system restores working context, not everything. Being clear about the gaps matters more than selling the idea:
- fine-grained reasoning from the old session is gone; the handoff is only as good as the summary the agent wrote
- it needs light discipline: the wiki index has to stay truthful, and a stale index is worse than none
- it is a convention, not a product: two markdown skill files and a folder layout
I want to be precise about the first limit. A handoff tells the next session what was decided, not the full chain of reasoning behind the decision. For most work that is enough, but when the reasoning itself matters, I ask the agent to record it in the Warnings or Next steps sections explicitly.
The last point cuts both ways. There is nothing to install, nothing to subscribe to, and nothing that breaks when tools change, because the same convention works in any repo. The cost of trying it is one folder and two skill files.
Wrap-up
Statelessness is not something to wait for model vendors to fix. A documented handoff between sessions works today, with plain markdown and a little discipline, in whatever agent tool you already use. Start with one project, one wiki folder, and one honest handoff at the end of your next long session.
This is Layer 2 of the five-layer harness from the pillar post. The next deep dive covers letting the agent see runtime behavior, the log-for-ai pattern.