There's a specific moment in every AI-assisted project that used to cost me real time: the point where a session is about to end. Maybe the context window is running low and responses are getting slower or vaguer. Maybe you're deliberately switching from one model to another because it's better at the next part of the work. Maybe you just need to close the laptop and pick this up tomorrow. Whatever the reason, there's a small window where the AI still remembers everything about what just happened — and one message later, that memory is gone for good.
If you're already using a project-memory folder like .ai-memory/ (I've written about the setup prompt and the day-to-day requirement prompt separately), this is the third piece that makes the whole system actually hold together: a handoff prompt, run at the end of a session, whose entire job is to get everything worth knowing out of the conversation and into the files before the conversation disappears.
Why this needs to be its own separate prompt
You might think the regular "implement this requirement" prompt already updates the memory files, and it does — but only for the specific task it just finished. A session often involves more than that: a few false starts, a decision you talked through but didn't fully implement, an error you're still chasing, a change of plan halfway through. None of that necessarily gets captured by a task-focused update. The handoff prompt exists specifically to step back and capture the whole session, not just the one requirement — and to write it in a way that assumes the next reader has zero access to anything that was just said.
That last part matters more than it sounds like it should. Most of us write notes for ourselves assuming we'll remember the context around them. This prompt forces the opposite: write it as if a stranger — or in this case, a different AI model entirely — has to pick this up cold.
What it actually asks the AI to do
Before anything gets written down, the prompt makes the AI look backward first:
- Read the current memory files, so it knows what state things were supposedly in before this session started.
- Review everything that actually happened in the session — not what was planned, what actually happened.
- Separate what was genuinely completed from what's still incomplete. This distinction is where a lot of handoffs quietly fail — it's easy to write "added feature X" when really 80% of it is done and one edge case is still broken.
- Note current errors and anything still unresolved.
- List which files were actually touched.
- Capture any real technical decisions made along the way — even ones made in passing, in conversation, that never got written anywhere else.
- And critically, work out the exact next step. Not "continue development" — the literal next action someone (or some AI) should take when they open this project again.
Only after all of that does it start writing, and it writes to four specific places: CURRENT-STATE.md gets brought up to date, TASKS.md reflects the real backlog now, CHANGELOG.md gets the session's meaningful changes, and HANDOFF.md gets the actual handoff note itself.
The one sentence that makes this prompt trustworthy
"HANDOFF.md must be sufficient for a completely new AI model that has NO access to this conversation to continue the project safely."
That single requirement is the test every other instruction in the prompt is really serving. It's not enough for the handoff note to be accurate — it has to be complete enough that a totally different model, with none of this session's context, can read it and know exactly where to pick up. If HANDOFF.md leaves out something that was only ever discussed verbally in the chat, the next session inherits a gap it doesn't even know exists.
And right alongside that is the same rule that shows up throughout this whole memory system: don't claim something was completed if it wasn't. A handoff note is only useful if it can be trusted at face value. The moment "completed" starts meaning "mostly completed" or "should be fine," the next session builds on a foundation that isn't actually there.
There's also a quiet but important line about not including secrets or credentials in the handoff. Worth repeating every time, because HANDOFF.md tends to get written under a bit of time pressure — right as a session is wrapping up — which is exactly when someone might paste an API key "just so the next session has it." Don't. Reference it by name instead.
When to actually run this
Three situations, specifically:
- You're wrapping up for the day and don't know exactly when you'll be back.
- You're deliberately switching models — maybe you started architecture discussions in one and want to hand the actual implementation to another.
- Context is running low and responses are starting to degrade — better to hand off cleanly on your terms than let the session trail off into vague, low-context answers that don't get written down anywhere.
Run it, let it update the four files, and the next session — regardless of which AI opens the project next — starts from a clean, accurate picture instead of picking through what's left of a conversation that no longer exists.
The prompt
Create a complete AI handoff for the current project state.
Before finishing:
1. Read the current .ai-memory files.
2. Review the work performed in this session.
3. Identify everything that was actually completed.
4. Identify incomplete work.
5. Identify current errors and unresolved issues.
6. Identify files that were modified.
7. Identify important technical decisions made during this session.
8. Identify the exact next steps required to continue the work.
9. Update .ai-memory/CURRENT-STATE.md.
10. Update .ai-memory/TASKS.md.
11. Update .ai-memory/CHANGELOG.md.
12. Update .ai-memory/HANDOFF.md.
HANDOFF.md must be sufficient for a completely new AI model that has NO
access to this conversation to continue the project safely.
Do not include secrets or credentials.
Do not claim anything was completed unless it actually was.
Putting the three prompts together
At this point the full system is three prompts, each with one job: one to set up the memory folder the first time a project folder exists, one to run every single time a new requirement comes in, and this one to close a session out properly whenever you're stepping away, switching models, or running low on context. None of them depend on a specific AI tool, which is really the point — the project's memory lives in the repository, not in whichever chat window happens to be open right now.
