I kept seeing SaaS products for coding-agent memory. The continuity I actually needed fit in one small, bounded Markdown file inside the repository.
I started seeing a whole bunch of vibe-coded SaaS solutions for giving coding agents memory between sessions. Some of them are interesting, but I thought there might be a much simpler way. For this particular problem, a full-blown SaaS is not really needed.
At least, not for what I was trying to solve.
I did not need another account, SDK, database, synchronization layer, or service running in the background. I needed an agent to remember what it had already tried, what state the task was in, and what it should do next.
So I made the smallest thing I could think of: a bounded Markdown scratchpad that lives inside the repository.
The problem I was actually trying to solve
Source code preserves implementation state, but it does not preserve all the reasoning around an unfinished task.
After a context reset or a handoff to another agent, the code can show what currently exists. It usually cannot explain:
- Which approaches were already attempted and why they failed.
- Whether an observed result came from the current code or a stale process.
- Which external facts were verified and which were assumptions.
- Which working-tree changes already belonged to the user.
- Which development server or process is currently relevant.
- What the next concrete action should be.
- Which discoveries might eventually deserve permanent documentation.
- This missing context causes agents to repeat investigations, retry failed approaches, overwrite existing work, or confidently continue from an assumption that is no longer true.
A conversation transcript can sometimes help, but it is chronological and much larger than the handful of facts required to continue a task. It may also be compacted, reset, unavailable to another agent, or full of details that no longer matter.
What I needed was not long-term semantic memory. I needed reliable task continuity. Just a good handoff note.
The smaller solution
The pattern uses two files:
- .ai_scratchpad.md holds the short-lived state for one active task.
- AGENTS.md tells coding agents when and how to maintain it.
The scratchpad is deliberately boring. It is a Markdown file in the root of the repository with four sections and a hard limit of 80 physical lines.
The important part is that it does not try to remember everything. It stores only the information another agent, or the same agent after a context reset, needs to continue the next few actions safely.
Check out the full gist with setup instructions here https://gist.github.com/corpulent/f7fbad0a4d9cdb6a5d4f31d249a2341c.
