Operations
Checkpointing for AI agents
The core principle
Context window = RAM (volatile, limited). Filesystem = disk (persistent, unlimited). Anything important gets written to disk immediately.
The problem
During research-heavy sessions, AI agents accumulate findings in context but don't write them to persistent files until the end. If context fills up or the session ends unexpectedly, everything discovered since the last write is lost.
Symptoms you'll recognize:
- Multiple conversations needed for a single deliverable
- Manually saying "write this down before you forget"
- Starting a new chat means re-reading emails already processed
- Final outputs missing details discussed mid-session
The rules
The two-action rule
After every two research actions (email reads, searches, thread analyses), write findings to your project file before continuing.
Don't wait for findings to be "clean." Write rough notes with a (working notes) tag if needed. Messy notes in the file beat perfect notes lost to context.
Mark checklists before doing the work
For multi-step workflows with a tracking checklist, update the checklist before starting each item, not after. If a session cuts out mid-item, the resume sees it marked and can verify or redo just that one.
Checkpoint before switching topics
If the session is moving from one subject area to another, commit everything from the current topic before starting the next one. This is a natural breakpoint. Use it.
Start by reading, end sections by writing
Start every session by reading the relevant project file to pick up where the last session left off. End every major section of work by writing updates back. The file is the handoff mechanism between conversations.
On resume, read and get oriented
When a session picks up from a handoff, its first job is to read the notes, get oriented, and report where things stand. A note that says "next: run the batch" records a plan. The go-ahead still has to come from a person. Resuming and executing are two different steps.
Disk records what you did
Your files are the source of truth for what the session has done. They aren't a reliable source for how things stand right now. A note that an invoice is unpaid or a ticket is open was true when someone wrote it. Before you assert the state of a live system, check the live system.
Proactive checkpointing in long sessions
If a session has gone through 15 or more tool calls without writing to a project file, pause and checkpoint. Don't wait for the user to ask.
Log corrections where they'll be read
When the agent gets corrected or something fails unexpectedly, write it down right away, in the place that will actually be read next time. A correction about how you work goes in the project's running notes file, which the agent reads when it starts work there. A quirk of one tool or API goes in that tool's own reference note.
A general pitfalls file is fine as a lookup. Nothing loads it at session start, though, so it can't stop a repeat on its own. If the same correction comes up a second time, promote it to a rule (see Should you remember this?).
A task is an accepted outcome
Write a task when someone asked for it, promised it, or is owed it. An idea you noticed along the way goes in the project's running notes file, or nowhere. One week, my sessions created ninety tasks while twenty-seven got closed. A list like that stops telling you what's actually open.
Prune while you write
When updating a project file during a session, take 30 seconds to scan for stale content: notes about work that finished more than a month ago, working notes from previous sessions that were never cleaned, contacts or details superseded by newer information. Keep docs lean so they're useful when loaded at session start.
Keep a daily handoff log
Keep one handoff file per day and append a section for each session: what changed, what's still open, what's next. Old days stay put as a searchable trail. The open-items list in each section is generated from the task files and never typed, so it can't keep listing something that already closed.
Update logs
When writing to a project file, add a dated entry to an update log section at the bottom. This creates a breadcrumb trail across sessions:
- 2026-04-11: Added contact info from email thread
- 2026-04-10: Updated venue status to confirmedWhat gets written where
| Finding type | Write to |
|---|---|
| Status changes | The task's own file, through the task tool |
| Action items assigned | A new task file, one per item |
| New contacts discovered | Project file |
| Decisions made | Project file |
| Meeting notes / agendas | Separate file, linked from project |
| Corrections to how the agent works | The project's running notes file |
| Quirks of a specific tool or API | That tool's reference note |
| What this session did | Today's handoff log |
| Reusable process patterns | Dedicated playbook file |
Anti-patterns
Don't: Hold all findings in context, write at the end
Do: Write after every two research actions
Don't: Wait for findings to be "perfect" before writing
Do: Write rough, tag as working notes
Don't: Only update files at session wrapup
Do: Write incrementally throughout
Don't: Assume the user will remind you to save
Do: Checkpoint proactively
Don't: Start a new session without reading the project file
Do: Always read first
Don't: Pick up a handoff and start executing its next step
Do: Read, get oriented, and confirm before acting
Don't: Quote a note on disk as the current state of a live system
Do: Re-check the live system first
Don't: Wait until wrapup to log mistakes
Do: Write corrections to the project's running notes file right away
Don't: Turn every idea into a task
Do: Create tasks only for accepted outcomes
Don't: Type the open-items list by hand
Do: Generate it from the task files
Don't: Never prune old content
Do: Prune stale items when you write updates
Origin
This playbook was created after a planning session required 4 separate AI conversations because context kept filling up before findings were committed to disk. The pattern draws from Manus AI's "markdown as working memory" architecture, Claude Code best practices around scratchpad files, and the developer pattern of writing to progress files during long sessions.
Updated October 2026
← Back to Tools & Resources