Scratchpad

Scratchpad

Write working memory to a file instead of carrying it in context — then read back only what the current step needs.

When to use

• A multi-step task where state accumulates (research findings, a todo list, partial results).
• Long agentic runs with many tool calls, where early findings would scroll out of the window.
• The user asks to "track", "remember", or "take notes" across steps.
• You need durability across a context compaction or a fresh session.

When NOT to use

• A short, single-shot task — the file is overhead with no payoff.
• Truly ephemeral scratch math that's consumed in the very next step.
• Secrets or sensitive data that shouldn't be written to disk.

The method (numbered, concrete — the heart)

1. Create one canonical file. Pick a stable path and stick to it (e.g. scratchpad.md or NOTES.md in the working dir). One file the agent always knows where to find.
2. Structure it for selective reads. Use clear headed sections — ## Goal, ## Decisions, ## Todo, ## Findings, ## Open questions, ## Dead ends — so you can pull back one section without loading the whole file.
3. Write as you go, not at the end. Append a finding the moment you discover it. The point is to get it out of context, so don't hoard it in the conversation first.
4. Record decisions with reasons and timestamps. "Chose X over Y because Z" — future reads (and a future you) need the rationale, not just the verdict.
5. Keep a live todo with status. Mark items [ ] / [x] / [blocked]. This is the agent's task ledger; update it after each step.
6. Log dead ends. Write down what didn't work and why, so neither you nor a successor repeats it.
7. Read back surgically. When you need state, read the relevant section — not the entire file. Treat the file as a database you query, not a blob you reload.
8. Reconcile before finishing. At the end (or before a handoff/compaction), make sure the file reflects final reality, then it doubles as your summary source.

What good looks like

• At any moment you could lose the conversation and reconstruct the task from the file.
• The file is the source of truth for todos and decisions; the conversation just acts on it.
• Reads are targeted (one section), keeping live context lean.
• Dead ends and rationales are captured, so the same mistake never gets made twice.

Anti-patterns

• Notes that never leave context — narrating findings in chat but never writing them, so they vanish on compaction.
• Many scattered files — losing track of where state lives; keep it canonical.
• Reloading the whole file every step — re-bloating the window you were trying to protect.
• Write-only scratchpad — recording but never reading back, so the notes do no work.
• Stale ledger — a todo list that no longer matches reality, which is worse than none.

Example (short, vivid)

A migration touching 40 files. Instead of holding progress in context:

# scratchpad.md
## Goal: migrate all API routes from v1 → v2 auth middleware
## Todo
- [x] users.ts
- [x] orders.ts
- [blocked] billing.ts  — uses removed `legacyToken`; need product decision
- [ ] 37 remaining (see grep results below)
## Decisions
- 2026-06-28: keep v1 shim for `/webhook/*` (third parties pin old format)
## Dead ends
- Codemod via regex broke template strings — doing AST-based pass instead

The agent appends after each file, reads only ## Todo to pick the next one, and the run survives any reset.