Stop re-litigating settled questions.
An agent that can't see why you chose Postgres over Redis will cheerfully propose Redis again — confidently, and with a good argument. A decision log it can query turns settled questions into constraints it designs around.
Code says what. It doesn't say why.
Point a capable agent at your repository and it will read the code accurately. It will see that rate limiting runs on Redis. What it can't see is that you tried Postgres first, that the sliding-window implementation fell over at your write volume, and that moving back is the one change nobody wants to make twice.
That reasoning existed. It's in a pull request description from March, a thread in Slack, and someone's memory. None of those are places an agent looks, so every fresh session starts from a clean slate and re-derives an answer from first principles. Sometimes it lands on what you already chose. Sometimes it confidently proposes the thing you rejected for reasons it has no way to know about.
The fix isn't a smarter model. It's giving the reasoning a durable home that agents can reach — and a shape they can query rather than read cover to cover.
A decision log, in the shape agents read
Make a Decisions/ folder in your workspace a typed
collection: drop a _schema.md in it and every record from
then on carries the same frontmatter — a title, a status, the area it
touches, a one-line summary, and a pointer to whatever it supersedes.
The records stay ordinary Markdown files with the full argument in the
body.
The typing is what makes it usable at scale. An agent about to touch
authentication doesn't need your whole decision history; it needs the
accepted decisions tagged Security. It asks for exactly
those, gets four records back, and reads the two that matter. A hundred
decisions in, that query costs the same as it did at ten.
Append, supersede, never overwrite
The convention that makes a decision log trustworthy is that entries are never edited in place. When something changes, you write a new record and mark the old one superseded, pointing at its replacement.
This matters more for agents than it does for people. A human reading an edited decision might notice the tone shift and go looking. An agent reads whatever is there and treats it as current. Keeping the old record — visibly superseded, with its replacement one hop away — means an agent that lands on the stale one still ends up in the right place, and the question "why did we change our minds?" survives the change.
We build Markbase this way
This isn't a hypothetical layout. Markbase's own workspace has a
Decisions/ collection, and every feature described on this
site has a record in it — what we chose, what we rejected and why, and
what it cost us. The site's copy decisions live there too.
When an agent picks up work on the product, that collection is the first thing it reads. It's the difference between an assistant that needs the history re-explained and one that opens by telling you which constraint your idea runs into.
In practice
The agent checks before it designs.
A coding agent asked for a spec, reading the accepted decisions for the area it's about to touch — and changing its plan when they rule its first instinct out.
What makes it work
Three primitives, doing the work.
Typed collections
A _schema.md in the folder fixes the shape — status, area, date, what it supersedes. Agents filter and sort by those fields instead of grepping fifty files for the one that matters.
Conventions in the folder
An _markbase.md beside the records says *check here before proposing architecture, and supersede rather than edit*. Agents read it on the way in, so the habit doesn't depend on you remembering to ask.
Every write is a version
Decisions change. The old text stays readable, so "when did this become true, and what did it say before?" is a question with an answer.
More use cases
Other jobs a shared workspace does.
- Session handoff Context windows end; the work doesn't. Write a handoff into the workspace and resume it in a fresh session — on another machine, or with another agent.
- Agents from different vendors Different models are genuinely better at different jobs. The one thing they have in common is MCP — so make the memory the thing they share.
- Parallel agent fleets Fan a job out across a fleet and they all reach for the same file. Every write says which version it's changing, so the loser of a race is told, not silently overwritten.
- Onboarding an agent The first thing a fresh agent does is read the workspace — what the system is, what's settled, how to work here — instead of asking you or guessing.
- Background & scheduled agents A nightly run has nowhere to put what it found. Give it a folder and the report is waiting in the morning — for you, and for the next run.
- Research & deliverables Agents produce spreadsheets, PDFs and rendered charts. Keeping them at the same paths as the notes that cite them is what makes the analysis reproducible later.
Free plan, no card
If your agents keep proposing the thing you already rejected.
If you've ever watched a capable agent argue for the architecture you abandoned six months ago, this is the gap. Start a decision log your agents can actually query — starting costs nothing, and the first record takes about a minute.