A small, bounded Markdown file that gives coding agents reliable task continuity without introducing another service, database, or vendor-specific memory layer.
The pattern uses two files:
.ai_scratchpad.mdholds short-lived state for one active task.AGENTS.mdtells coding agents when and how to maintain it.
The scratchpad records only what another agent—or the same agent after a context reset—needs to continue the next few actions safely. It is deliberately temporary, human-readable, and subordinate to the code, current user instructions, and permanent project documentation.
Source code preserves implementation state, but it does not preserve all of the reasoning around an unfinished task.
After a context reset or handoff, an agent may not know:
- which approaches were already attempted and why they failed;
- whether an observed behavior came from current code or a stale process;
- which external facts were verified and which were assumptions;
- which working-tree changes belong to the user;
- which server or process is currently relevant;
- what the next concrete action should be;
- which discoveries might deserve permanent documentation later.
The result is repeated investigation, contradictory changes, and avoidable risk. A repository-local scratchpad preserves this small amount of negative knowledge and continuation state beside the work itself.
The scratchpad maintains one task record with four sections:
- Dead Ends (Do Not Propose) — approaches that were actually attempted and failed.
- Current State & Assumptions — verified working state plus explicitly marked assumptions.
- Suggestions for Durable Changes — recommendations for a developer to review before promoting them into permanent documentation, configuration, or code.
- Next Immediate Steps — a short ordered continuation plan.
It is capped at 80 physical lines so it remains a checkpoint rather than becoming another knowledge base.
An agent can resume from a compact task checkpoint instead of reconstructing an entire conversation or rediscovering the state from scratch.
Recording genuinely attempted dead ends preserves information that is rarely visible in the final code. This prevents a new agent from confidently retrying an approach that already failed for a known reason.
The current-state section can identify user-owned edits, dirty-worktree constraints, active processes, and other boundaries that must be preserved.
Mutable external facts are marked as assumptions until reverified. This discourages agents from treating yesterday's deployment, API response, database state, or running process as permanently true.
Potential durable changes are placed in a review queue. Developers decide whether they belong in AGENTS.md, README.md, configuration, or code rather than allowing transient agent notes to become permanent rules automatically.
The pattern requires no account, SDK, API key, background synchronization, indexing pipeline, or external runtime dependency. It works anywhere an agent can read and edit Markdown.
Add this file at the root of the repository:
# No active task
## Dead Ends (Do Not Propose)
- Nothing is currently recorded.
## Current State & Assumptions
- Nothing is currently recorded.
## Suggestions for Durable Changes
- Nothing is currently recorded.
## Next Immediate Steps
1. Await the next task.Copy the reusable policy in AGENTS.md policy into the repository's root AGENTS.md. If the repository already has agent instructions, merge the block into them instead of replacing unrelated guidance.
The best choice depends on how the scratchpad will be used.
Workspace-local continuity: keep .ai_scratchpad.md out of commits. Add it to .git/info/exclude for a personal local exclusion, or to .gitignore when the whole team should ignore it.
.ai_scratchpad.md
Deliberate team handoff: track the file only when the team wants the sanitized current task state to travel with the branch. Review it like any other changed file and reset it after the handoff is complete.
Reusable repository template: commit an .ai_scratchpad.example.md, ignore .ai_scratchpad.md, and copy the example when preparing a new workspace.
Never place secrets or personal information in the file, regardless of whether it is tracked.
The key behavior is simple: before working on a task, the agent reads .ai_scratchpad.md, confirms that it applies to the current task, and treats current code and user instructions as more authoritative than scratchpad content.
Replace the empty title with one concrete task title. Remove stale information from a previous task rather than appending a new historical record.
Update the scratchpad only when something materially affects continuation:
- a tried approach fails for a specific reason;
- a blocker or external dependency appears;
- a mutable external fact remains unverified;
- a process or server becomes the active reference;
- a user-owned edit must be preserved;
- a developer should consider a durable change;
- the immediate continuation steps change.
Do not update it after every command or use it as a running transcript.
Edit existing bullets in place. Keep only the current process reference, current blocker, current assumptions, and next few actions. Remove superseded measurements and completed history.
Completion is a judgment, not something Git can prove. Once the requested outcome is verified:
- Inspect
git status --short. - Determine whether remaining changes are expected, task-related, or pre-existing.
- Tell the user whether the worktree is clean.
- Ask the user to confirm that the scratchpad can be reset.
- Reset only after confirmation or an explicit request to wipe it.
A clean worktree is supporting evidence, not proof, that the task is finished. A dirty worktree does not necessarily mean work remains; completed changes may simply be uncommitted.
The following block is designed to be copied into a repository-level AGENTS.md and adapted when necessary.
## Ephemeral Task Memory
`.ai_scratchpad.md` is short-lived, repository-local memory for the current task. It exists so a new agent can resume valuable work after a conversation is reset, compacted, or handed off without needing the previous chat.
The scratchpad is not a second `README.md`, `AGENTS.md`, changelog, or permanent task archive. It must contain only the current task's failed approaches, working state, assumptions, next actions, and pending developer-facing suggestions for durable changes. The suggestions section is a review queue, not authorization to change permanent project guidance. Durable architecture, setup instructions, standing rules, and completed decisions belong in the main project documentation after a developer approves them.
Before performing any task, read `.ai_scratchpad.md`. First confirm that its title and contents apply to the user's current task; do not blindly apply stale notes from an unrelated task.
### Scratchpad rules
1. Use one task title and one task record. Do not add operating instructions, schema explanations, status taxonomies, or multiple historical task entries to the scratchpad itself.
2. Keep the entire file at or below 80 physical lines, including blank lines. If it would exceed the limit, compact it before adding new material without discarding active blockers or required continuation steps.
3. Keep only information needed for the next few actions. Replace stale state in place instead of appending new status bullets, completed history, or repeated validation results.
4. Update it immediately after discovering a meaningful dead end, task-specific constraint, blocker, external dependency, assumption, or continuation step that is not already captured.
5. Under `Dead Ends (Do Not Propose)`, record only approaches that were actually attempted and explain concretely why they failed. Mark them with `[X]`. Do not list merely rejected or hypothetical ideas as attempted work.
6. Under `Current State & Assumptions`, record enough implementation state, relevant file paths, validation results, and external dependencies for another agent to resume without the previous conversation. Prefix unverified statements with `Assumption:`. Treat mutable external facts as assumptions until they are reverified for the current task.
7. Under `Suggestions for Durable Changes`, record concise recommendations that may belong in `AGENTS.md`, `README.md`, configuration, or the code but require developer judgment. Do not implement a suggestion merely because it is recorded there. Remove it after a developer accepts, implements, or rejects it; when the user explicitly requests the durable change, implement it normally and do not leave a duplicate suggestion.
8. Under `Next Immediate Steps`, provide ordered, concrete actions rather than broad intentions.
9. Never record secrets, tokens, API keys, credential assignments, copied environment-file contents, personal information, form values or submissions, or other sensitive data.
10. Link to relevant repository files instead of copying large code excerpts.
11. Keep only the current server, process, or session reference. Replace it when the process changes; never accumulate stale process identifiers.
12. Do not automatically reset the scratchpad merely because the task appears finished. After the requested outcome is verified, inspect `git status --short`. A clean worktree is supporting evidence, not proof, that the task is complete. Tell the user whether the worktree is clean and ask them to confirm the reset. If it is dirty, summarize whether the remaining changes are task-related or pre-existing and retain the scratchpad until the user confirms those changes are expected and approves the reset. An explicit user request to wipe or reset the scratchpad is sufficient confirmation.
13. When beginning a materially different task, replace stale task contents rather than accumulating historical entries, subject to the reset confirmation rule above.
14. If scratchpad content conflicts with current code, direct user instructions, or `AGENTS.md`, those sources are authoritative. Correct the scratchpad immediately.
### Required scratchpad schema
Use exactly this top-level structure. A section may say that nothing is currently recorded, but it should not be removed.
```markdown
# <Task title>
## Dead Ends (Do Not Propose)
- [X] Attempted <approach>. Failed because <specific evidence or reason>.
## Current State & Assumptions
- <confirmed state, constraint, validation result, or relevant file>
- Assumption: <unverified belief that the next agent must validate>
## Suggestions for Durable Changes
- Suggestion: <possible documentation, configuration, or code change for developer review>
## Next Immediate Steps
1. <first concrete action>
2. <second concrete action>
```It is large enough to preserve a non-trivial task's state while small enough to read at the start of every agent turn. The exact number is less important than enforcing a clear upper bound.
Usually not for private, same-workspace continuity. Commit it only when sanitized task state must travel with a branch or support a deliberate team handoff.
Issue trackers describe product work and durable collaboration. The scratchpad contains lower-level, short-lived execution state that would create noise in an issue but may be essential during a handoff.
Transcripts are chronological and often much larger than the small set of facts required to continue. They may also be unavailable after compaction, reset, tool handoff, or a change of agent.
Only recommendations that require developer judgment: a missing setup note, a recurring invariant, an environment-variable inventory update, a reusable validation rule, or a code-level cleanup discovered during the task.