Decision Memory

An engineer opens a file an AI session touched three weeks ago and finds something that looks wrong. A retry loop capped at two attempts instead of the project’s usual five. A cache invalidated on every write instead of every ten. Nothing throws an error, nothing fails a test, but it reads like a mistake — the kind a reviewer would flag if they had been paying closer attention at the time. The question that follows is always the same one: was this deliberate, or did nobody catch it?

Answering that question today means archaeology. The engineer can re-read the session transcript, if the tool still has it and the session was not compacted past the point where the reasoning survived. They can ask around, hoping someone remembers a conversation from three weeks and forty other sessions ago. Failing both, they guess — usually toward caution, reverting a choice that might have been entirely correct, because a guess that preserves a working system feels safer than a guess that doesn’t. None of these are answers. They are substitutes for a record that was never kept in a form anyone could query, and the guess costs real time whether it turns out right or wrong. Multiply that one file by every session an AI tool has run against the codebase this year, and the archaeology stops being an occasional annoyance and starts being how the team spends a nontrivial share of its week.

What sessions forget on the way out

The industry has started taking half of this problem seriously. Long-running agents now practice what Anthropic calls structured note-taking — regularly writing progress to a file outside the context window so a session can survive its own compaction and pick up where it left off after a summary discards the fine-grained history. It works: an agent maintaining a running to-do list or a scratch file can execute coherently across thousands of steps it would otherwise have forgotten by step two hundred, and Anthropic’s own testing found the combination of that note-taking with automatic context pruning meaningfully improved task performance.

But that memory is built to serve the session, for the length of the session. It answers “what was I doing” for the agent mid-task. It was never designed to answer “why did you do that” for a human, three weeks later, who was not in the conversation and may not have been born as a Slack thread, a ticket, or anything else searchable. The note that would have explained the retry cap was written to survive until the next compaction. It was not written to survive the session ending at all.

Postmortems already made the case — for failures

Engineering organizations have already accepted, in one specific corner of practice, that reasoning deserves to outlive the moment it happened in. A postmortem, in Google’s formulation, is “a written record of an incident, its impact, the actions taken to mitigate or resolve it, the root cause(s), and the follow-up actions to prevent the incident from recurring” — filed into a repository, aggregated across teams to surface patterns no single incident would reveal on its own. Nobody argues that postmortems are excessive process. The value of a queryable “what happened and why” is uncontested, for the one category of decision an organization is institutionally forced to examine: the one that already broke something.

A template already exists — and AI work needs it more

Software teams do have a template for capturing reasoning before something breaks, and it predates AI-assisted development by well over a decade. In 2011, Michael Nygard proposed keeping a collection of short, numbered documents — Architecture Decision Records — for anything that affects a system’s structure, dependencies, or interfaces: a title, the context and forces at play, the decision itself stated in active voice, its consequences, and a status. The format is deliberately lightweight, small enough that ThoughtWorks was recommending it for general adoption in its Technology Radar within seven years, filed in source control so the record stays versioned alongside the code it explains rather than drifting apart on a separate wiki. The status field does most of the quiet work: a decision is proposed, accepted, deprecated, or superseded, and that last state is the one this chapter cares about most.

If a decision is reversed, we will keep the old one around, but mark it as superseded.

Michael Nygard, on the discipline of documenting architecture decisions

An AI session does not ration decisions the way the ADR format assumes a human team will. A team might open two or three ADRs in a sprint, reserved for choices big enough to justify asking a teammate to review a markdown file. A single AI session can make a dozen decisions of that shape in an hour and never surface any of them as a discrete artifact: which of two plausible retry strategies to implement, whether an edge case gets handled inline or pushed to a caller, which of an existing migration’s assumptions to keep and which to quietly break. None of them alone would clear the bar Nygard set for “architecturally significant.” Together, they are most of what the session actually decided.

And the moment the session ends, that reasoning evaporates in exactly the shape this volume’s companion, Volume I, calls Context Debt: a cost deferred, not avoided, paid back later by whoever has to reconstruct it without a record. A human engineer who never writes anything down is at least a person you can eventually ask. A session that ends leaves no one to ask at all — the reasoning either got captured somewhere queryable, or it is simply gone.

Decision Memory

Call the record that closes this gap Decision Memory: decisions persisted as first-class, queryable records — what was decided, why, and what it superseded. Not a database entry for every micro-action a session produces, but the subset of its actions that has the shape of a decision — a point where the agent, or the person directing it, chose one plausible path over another for a reason that can be stated. Reading a file is not a decision. Choosing to cap retries at two instead of the project’s default of five, because the downstream service rate-limits aggressively, is.

Chapter 7 described the top rung of the memory ladder as agent memory: the point where a system does not just retrieve context but writes to the store itself. Decision Memory is what that write path looks like when the thing being written is reasoning rather than a fact. Chapter 8 named a real strength of file-based memory — AGENTS.md, progress logs, git history — and a real limit of it: those channels carry facts and conventions forward well and answer a structured question about a specific choice poorly. A prose file can tell a reader that retries are capped at two attempts. It cannot easily answer which decisions touched the payment module this quarter, or show that the two-attempt cap superseded an earlier five-attempt default and why. That is a shape problem, not a diligence problem — no amount of careful prose-writing turns a text file into something you can query.

What a decision record needs

Three properties separate a decision record that actually gets used from one that quietly stops being trusted, and each is a direct answer to a way manual note-taking or a plain memory file already fails.

The third property is the one teams most often skip, because deleting an old decision feels like housekeeping rather than data loss. It is not. The record of why the two-attempt retry cap replaced the earlier five-attempt default is exactly what stops a future session — human or AI — from re-litigating a question that was already argued out, this time without the context that settled it the first time around. A superseded decision, kept and marked as such, is not clutter. It is the only thing standing between a team and having the same argument twice, a year apart, with neither side remembering the first one happened.

What to check this against

Where this leaves the memory ladder

Decision Memory is not a replacement for the memory ladder this volume has been climbing — it is what the top rung looks like applied to one specific, high-value category of content. Chapter 7 drew the line between retrieval and memory: a system that only fetches what already exists, versus one that also writes what it learns. Chapter 8 showed that file-based memory, for all its convenience, is the wrong shape for a structured “why” query — it was built to carry facts and conventions forward, not to preserve the reasoning behind a specific, supersedable choice. Decision Memory is the answer to the one question plain files answer worst: not what the codebase does, but why someone, or something, decided it should do it that way — and whether that reasoning still holds. None of the ladder’s lower rungs make that question answerable; only a record built for exactly this shape of content does.