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.
Top comments (3)
The task-continuity vs. long-term-memory distinction is the part most people skip straight past, and it's the whole ballgame. We landed on almost exactly this — a bounded scratchpad file per active task — after watching agents burn tokens re-deriving state that a 20-line handoff note would have carried for free.
The bit you list that bit us hardest was "whether an observed result came from the current code or a stale process." An agent would run a check, get an empty result from a server that had died three steps earlier, and confidently mark the task done. Writing down which process the result came from fixed more phantom successes than any smarter reasoning did.
One thing I'd add from experience: the bounded part is load-bearing. The first version of ours had no size cap and agents treated it as a journal — it grew until it was as noisy as the transcript it was supposed to replace. Hard-capping it and forcing the agent to prune before appending is what kept it a handoff note instead of a second log. Did you find you needed an explicit eviction rule, or does the "one active task" scope keep it small enough on its own?
The bounded file is the right constraint. I keep seeing people treat continuity as a retrieval problem when most failures are handoff failures. An 80-line scratchpad also gives the human reviewer something auditable, which is harder to get from a memory service.
Useful read. My main lesson with agents was that the prompt matters less than the guardrails around it. I moved most of my rules into code checks and the flip rate dropped a lot. Do you do the same or do you keep it all in the prompt?