ADRs: finally give your AI agents memory

Your AI agent starts from scratch every session. With no written trace, it suggests an approach you already tried and dropped last week. You re-explain the same context, you rule out the same bad ideas. On a loop.

The solution already exists on the dev side, and it's nothing new: ADRs (Architecture Decision Records) for decisions, and a context log for the rest. Markdown, versioned in git, queryable by your agent.

The real memory gap: decisions and context

Everyone stores content: code, notes, docs. What's almost always missing are the decisions ("we picked X over Y, and here's why") and the context ("this module exists because of this constraint").

That's exactly what your agent needs to avoid going in circles. A model will never guess that you already rejected an approach three sessions ago. You have to write it down.

The ADR: one decision, one file

An ADR is one file = one decision, with three blocks:

Context: the problem, the constraints.
Decision: what you chose.
Consequences: what it implies, the trade-offs accepted.

Two important rules:

An ADR has a status: proposed, accepted, superseded.
An ADR is immutable. You don't edit a past decision: you write a new one that replaces it (superseded_by). The history stays readable.

The format comes from Michael Nygard and is documented by Martin Fowler; the MADR Markdown template is a good starting point.

The context log: keeping rejected approaches

Alongside decisions, I keep a context log that also records the rejected approaches and why. That's what stops the agent from re-suggesting an idea you already dismissed. The rule is simple: anything that must survive between two sessions lives in a file, not in the chat.

The structure I use (in Obsidian)

PLAINTEXT

Decisions/
  2026-07-14 - Store dates in UTC.md
Context/
  payments - context.md

With clear frontmatter on each decision:

type: decision
status: accepted        # proposed | accepted | superseded
date: 2026-07-14
tags: [arch, timezone]
superseded_by:

I follow Steph Ango's convention (Obsidian's CEO): the folder is the content type, the frontmatter is the metadata. A file never changes folder; you change its status. As a result, everything is directly indexed and queryable by the graph, so my agents can use it.

The takeaway

Everyone stores content. Decisions and context, almost no one — and that's exactly what your agents are missing. Write them in Markdown, version them, make them immutable. Your agent stops going in circles.

I show the full workflow on video: watch on YouTube.