ADR files vs a decision graph. You probably want both.
Every few months a team decides to take architecture decision records seriously. A docs/adr folder appears, five records get written, and the habit dies in the first busy sprint. Later someone asks why the payment service talks to the queue directly, and the answer is in nobody's head and no file.
The usual conclusion is that ADRs failed. The usual conclusion is wrong. ADRs do one job well and were never built for the other one.
What ADR files are for
An ADR is a human document. Prose, written with care, reviewed in a pull request, readable in five years with no tooling at all. When a decision deserves three paragraphs of context and trade-offs, an ADR is the right place for them. Keep writing them.
Where files alone fall short
Nothing makes an AI agent read the right ADR at the moment it edits the code that ADR governs. Supersession is a status line a human must remember to change, so ADR-031 can quietly contradict ADR-014 for a year. And you can't query files by area. Asking what's decided about payment retries is a grep and some hope. git blame tells you who, not why.
The machine-readable companion
ADRs stay the human-readable record your team edits. A decision graph is the machine-readable companion, not a replacement for the files.
In kgai, which we build, the graph is projected from an append-only, immutable decision log. Each decision carries what changed, why, and what was rejected. Supersession is an explicit link with a reason, so nothing is edited in place and contradictions can't hide. Recall happens before the agent touches an area, through lexical matching plus graph traversal, and returns only decisions still in force. The log replays deterministically to the same graph on every teammate's machine, and the dead ends stay queryable with the reason they lost. Even repealing something needs a record.
Both, concretely
Write ADRs for the decisions that deserve prose. Let the graph catch the rest at the write boundary, captured by a skill and hooks while the agent works, so the small decisions that never earn a file stop evaporating. Then seed the graph with the ADRs you already have. kgai imports past decisions with their real dates, so the timeline is honest from day one. There's no daemon and no server, sync is opt-in over an S3 bucket you own, and it's MIT.
Your ADR folder is the start of the record, not the whole of it. Give your team's AI the part it can actually read.
Try it on your repo. Two commands, MIT, nothing leaves your machine until you configure a bucket.
See how kgai compares to other tools on the comparison page, or browse the other notes.