Checkpointing for AI Agents
How to stop losing work when context windows fill up during long AI agent sessions.
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 2-Action Rule
After every 2 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.
Proactive Checkpointing in Long Sessions
If a session has gone through 15+ tool calls without writing to a project file, pause and checkpoint. Don't wait for the user to ask.
Mid-Session Pitfall Logging
When the agent gets corrected or something fails unexpectedly, immediately write it to a known-pitfalls file. Don't wait for session wrapup. Examples: wrong path used, API call that failed due to undocumented behavior, field name that was wrong, workflow assumption that turned out to be incorrect.
This compounds across sessions. By session 3-5, the agent catches these errors proactively instead of repeating them.
Prune While You Write
When updating a project file during a session, take 30 seconds to scan for stale content: status items completed 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.
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 | Project file |
| New contacts discovered | Project file |
| Decisions made | Project file |
| Action items assigned | Project file |
| Meeting notes / agendas | Separate file, linked from project |
| Reusable process patterns | Dedicated playbook file |
Anti-Patterns
Don't: Hold all findings in context, write at the end
Do: Write after every 2 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: Wait until wrapup to log mistakes
Do: Write to pitfalls file immediately
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.