Workflow
The AI Agent Handoff Loop: How Work Carries Across Sessions
A practical model for carrying decisions, lessons, gotchas, and next steps from one AI work session into the next.
01
Session start: load relevant context before work begins.
02
During work: capture durable facts, decisions, gotchas, and follow-ups.
03
Session end: write a handoff so the next run knows what changed.
01
Why sessions need handoffs
AI work often fails at the boundary between sessions. The assistant did useful work, but the next run does not know what changed, what was decided, or where to continue.
A handoff loop turns that boundary into a habit. The next agent starts with the right context instead of replaying a full chat history.
02
The loop
Wenlan follows a simple rhythm: load context when a session starts, capture durable knowledge during work, write a handoff when the session ends, refine memory between sessions, and retrieve the right context next time.
The loop is deliberately practical. It focuses on what future agents need to act well: decisions, lessons, constraints, unresolved threads, and source provenance.
03
What belongs in a handoff
A good handoff is not a transcript. It should say what changed, what matters, what remains open, and which files, commands, or project areas are relevant.
The point is to compress the state of work into something useful for the next session.
- Decision made and why it was chosen.
- Lesson or gotcha discovered while debugging.
- Follow-up that should not be lost.
- Project context the next agent needs before editing.
04
How Wenlan supports it
Wenlan gives agents a place to save the durable parts of the session and a way to recall them through MCP later.
Between sessions, Wenlan keeps captures, handoffs, related entities, and source-backed pages connected. Manual /wenlan distill turns repeated context into readable pages, while optional local models or API keys can add background page work.
05
What /handoff writes in Claude Code and Codex
In Claude Code and Codex, /handoff writes a Markdown session log, applies one typed update to the project's Space Brief (last-session summary plus Active and Backlog items), and stores durable decisions, lessons, gotchas, and facts as MCP captures. The next session starts with /brief, which reads that Brief.
A handoff is not Claude Code resume. Use claude --resume or --continue when you want the same transcript; use a handoff for durable project status and context that crosses sessions or tools.
- Let /handoff preview pending captures from the current session before closing.
- Confirm the resolved space so the next session searches the right project context.
- Mention files or commands only when they orient the next agent and are not obvious from git.
~/.wenlan/sessions/<YYYY-MM-DD-HHmm>-<slug>.md
Space Brief update in the daemon DB
~/.wenlan/sessions/_status/<space>.md (read-only receipt)
Wenlan MCP captures in the daemon DB06
Keep project status for the next agent
The Space Brief is the live ledger /brief reads: last session, Active work, Backlog, and gated items. The _status Markdown file is a readable receipt of it, not something to edit. Write for resumption, not narration.
- Keep fresh next-move candidates in Active and older parked work in Backlog.
- Complete or move items explicitly; /handoff never auto-demotes untouched Active work.
- Summarize a verified result and the command that proved it instead of storing long logs.
- Leave temporary todos to task tools. Keep the durable status that matters when the chat is gone.
# <Project> - Current Status
## Last session (<date>)
- <accomplished bullet>
## Active
- <fresh next-move candidate> (added <YYYY-MM-DD>)
- <blocked item> (added <YYYY-MM-DD>) (gated: <trigger>)
## Backlog
- <older parked item> (added <YYYY-MM-DD>)Stop restarting from zero
Wenlan makes handoffs, decisions, and project context available when the next AI session begins.
FAQ