Giving Agents Memory Without Giving Them Amnesia

An agent that forgets the decision it made in the last step produces incoherent work. An agent that remembers everything bloats its context and loses focus. The art is in the middle: remember the right things, forget the noise. After months of iterating, here is the pattern I use.

The Three Memory Layers

Decision memory. Every architectural call: 'we use DynamoDB not Postgres', 'error format is {error, code}', 'dates are ISO strings not timestamps'. These live in a single DECISIONS.md file at the repo root. The agent reads it at the start of every session. Short, high-signal, stable.

Task memory. The current session's progress: which tasks done, which failed, which are blocked. This lives in a STATE.md file updated at the end of each task. When I resume the next day, the agent reads STATE.md and picks up exactly where we stopped.

Working memory. The live scratch notes: 'the user said try option B', 'the test on line 42 is flaky'. This belongs in the current context window, not on disk. It dies when the session ends, which is correct. Not everything deserves to persist.

The Write-Back Discipline

Memory only works if someone keeps it fresh. I end every session by asking the agent to propose updates to DECISIONS.md and STATE.md. I review, edit, commit. Five minutes. The cost of skipping this step is having to re-explain everything tomorrow.

A Simple Template

# DECISIONS.md
- 2025-10-14: Chose DynamoDB for posts. Reason: 0$ free tier, single-item access pattern.
- 2025-10-22: Error schema is {error: string, code: int}. Reason: frontend already parses this.
- 2025-11-02: Slugs are kebab-case, max 60 chars. Reason: URL-safe and readable.

Three lines. Each with a date, a call, a one-sentence reason. That is all the agent needs.

Why This Beats Long Prompts

Stuffing decisions into the system prompt works for one session. It does not compose across sessions or across agents. A file on disk is durable, reviewable, and diffable. See 12-factor app principles for the general pattern: state in explicit stores, not in processes. Agents are processes. Their memory belongs in files.

Memory is infrastructure. Treat it that way.

What Not to Persist

Code samples from the agent do not belong in memory files. They belong in the repo as real code or in commit history. The memory files are for decisions and progress, not for the artifacts themselves. Mixing the two inflates the memory and reduces its signal. Keep memory small enough that reading it takes under two minutes. Past that, agents skim it and humans ignore it, which defeats the purpose entirely.