Keeping Markdown as the source of truth once decisions start referencing each other

Francis Marzynski — Tue, 15 Sep 2026 08:49:55 +0000

A few people who reached out about Operating Memory this month are all building some version of the same thing: decisions or ADRs kept as files in git, read by hand for a while, until the files start referencing each other. This one supersedes that one. This one only applies if the other one holds. This one contradicts a decision from three months ago that nobody remembered to update.

At that point the question is always the same. Keep reading the files by hand, or reach for a graph or triple store to hold the relationships.

Operating Memory's answer so far is neither, and I want to write down why rather than just ship an opinion.

The files stay canonical. Every import is a revision, not an overwrite, so supersession is explicit: a new decision can say what it replaces, and the old one does not disappear, it becomes historical. That's stored relationally, in plain SQL, because supersession, applicability, and "what is current right now" are exactly the kind of question a relational model answers well, and it means nothing has to leave the files to be true.

What that doesn't solve is the harder version of the question: not "what's current" but "what else changes if this one does." Cross-references, multi-hop chains, the reasoning graph between decisions rather than just their sequence. That's the part a graph model is actually built for, and it's also the part I don't think should be added by default, because a graph is one more structure to keep in sync with the files, and "keep it in sync" is the exact problem this project exists to avoid creating a second version of.

So the current approach is to test it against real cases instead of assuming the answer. Pick a handful of actual cross-referencing, multi-hop questions people have, and see whether a graph read on top of the relational core answers them meaningfully faster or more accurately than walking the relational links by hand. If it doesn't earn its keep on real questions, it doesn't go in.

I don't have a clean verdict yet. What I do have is a relational core that already tracks revisions and supersession without a second database, and a short list of real questions to test the graph idea against before building it.

If you've built something similar: did a graph or triple store end up worth the sync cost for you, or did it become one more thing to maintain?

Repo, if useful: github.com/FrancisMarzynski/operating-memory-public

DEV Community: Francis Marzynski

Keeping Markdown as the source of truth once decisions start referencing each other