On Monday you and your coding agent agree to stop touching v1 of your public API: no new endpoints, security fixes only. The agent works that way all day.
On Wednesday a new session picks up a bug that happens to live in a v1 endpoint. The agent fixes it carefully, adds a test, and suggests back-porting two new endpoints "for consistency". Nothing about it is careless. It simply never received Monday.
If this sounds familiar, the instinct is to give the agent more memory: a DECISIONS.md, a vector store, a summary the last session writes for the next one. Those solve storage. Storage was never the hard part.
Forgetting is a missing read
When an agent contradicts last week's decision, the decision usually still exists somewhere — a chat log, a notes file, a summary. What failed is that nothing put it in front of the model before the new session started working.
So the first rule of a decision record that works with agents is about when it is read, not where it is stored:
Every session opens by reading the decisions in force, before the agent forms its own view of the task.
If that read depends on the agent remembering to open a file, it will be skipped on exactly the day it matters.
Remembering the wrong version is worse
An agent that forgets asks again or makes a visible mistake. An agent that remembers a decision you reversed acts on it with confidence, and nothing in its output looks wrong.
Append-only stores make this worse: the old decision and the new one are both there, both relevant to the question, and the model picks one silently.
A decision record an agent can act on
Classic ADRs (Architecture Decision Records) are written for people reading a repo. An agent needs a few extra fields, and it needs them on every decision, not just the architectural ones:
Decision: v1 of the public API is frozen — no new endpoints, security fixes only.
Decided by: Dana (in the 2026-10-05 session)
Status: in force
Ends when: v1 is switched off
Replaces: "keep v1 and v2 in parity" (2026-08-12)
Why each field matters:
- Decided by — separates what a person decided from what the agent inferred. An agent's guess written on Tuesday should come back on Wednesday as a proposal, not as a rule.
- Ends when — every decision carries the condition that kills it. Without it, nothing ever expires, and the record turns into the long prompt you were trying to avoid.
- Replaces — a new decision names the one it retires. The old one leaves the read (with the reason kept in history), so the next session never sees both as equally valid.
- Status — two entries that contradict each other should arrive marked as a conflict, never resolved by the model on its own.
Who writes it down?
Mostly the agent, at the end of the session — that is the step people skip. What you stated or approved in the conversation is recorded as decided by you; what the agent concluded on its own is recorded as a proposal until a person approves it.
Where the usual setup breaks
The usual attempt is a decisions file plus a line in the system prompt telling the agent to read it first. It breaks on the three things above: the read is optional, reversals have to be found and edited by hand in every copy, and the file grows until it is either loaded in full every time or quietly trimmed. It breaks again the moment you switch agents mid-task or a teammate's AI needs the same decisions as yours.
That is what Arroway is built for: sessions open by reading the project, ordered by the task at hand; each decision carries who made it and what ends it; a replacement retires the old one; and an agent that has not read cannot write over the rules. It works the same with one agent and no team — the reader is just the same agent, tomorrow. The install page has the step for Claude, ChatGPT, Codex and Cursor: arroway.app/install.
Originally published at arroway.app.
Top comments (0)