How do I keep the why behind a decision for my AI agent?

Your code shows what you chose. It does not show why, what you rejected, or what would make you change your mind. So a new session opens, your agent reads the code, and it confidently suggests the option you ruled out last month.

Short answer

Store each decision as a record your agent can read, not just as code: the call, the reason, the alternatives you rejected and why, the assumptions it rests on, and what should reopen it. Then have the agent check new ideas against those records before it acts. That is what BrainOS does.

Why the code alone loses the tradeoff

Code is the result of a decision, not the decision. Reading a Postgres schema tells an agent you use Postgres. It does not say you tried a document store first, hit a reporting problem, and chose to live with slower migrations. Without that, the agent treats your choice as an accident it is free to improve.

Commit messages and comments help a little. They are scattered across history, usually describe what changed rather than what you gave up, and an agent will not dig through git log before every suggestion.

What a decision needs to carry

A decision your agent can actually reuse has five parts:

If you write ADRs (architecture decision records), you already know this shape. The gap is that ADRs are documents for people. An agent only benefits if it reads the right one at the right moment.

Where your agent will actually look

The reasoning has to live somewhere the agent reads by default, in a form it can query. Some options, from lightest to most structured:

Notes and docs

CLAUDE.md, ADRs, comments
  • Easy to start
  • Grow long and drift
  • Agent has to find the right one

Structured decisions

BrainOS
  • Why and rejected options per decision
  • Checked before the agent acts
  • Flagged when it is due for review

How BrainOS keeps the why

BrainOS is an open-source, local-first MCP server. It creates a .brain/ folder in your project and gives your agent typed tools for decisions:

So when the agent proposes the option you rejected, it gets your reason back before it writes code, and you decide on purpose. You can see it in the decision_check demo, and read how it works day to day in How to give AI agents memory of decisions.

Set it up for Claude Code

Initialize BrainOS in your project, then connect it:

Claude Code persistent memory

claude mcp add brain-os -- npx brain-os serve

The same .brain/ folder works with Cursor, Zed and other MCP clients, so a tradeoff logged in one tool is there in the next.

Questions people ask

What's the best way to keep the why behind a decision so my AI agent understands past tradeoffs?

Store each decision as a structured record the agent can read: the call, why it was made, the alternatives you rejected and why, the assumptions it depends on, and what should reopen it. Code and commit messages show what changed, not the tradeoff. BrainOS keeps these records in a local .brain/ folder and gives the agent tools to read and check them in every session.

Isn't a commit message or code comment enough?

They help, but they are scattered and rarely say what you rejected. An agent will not search git history before every suggestion, so the reasoning stays invisible unless it lives somewhere the agent reads by default.

What about ADRs (architecture decision records)?

ADRs are a good habit and capture the same ingredients. The gap is that they are documents for people. An agent only benefits if it reads the right one at the right moment. BrainOS stores decisions as structured data and lets the agent check a proposed action against them before acting.

How does my agent know a new idea conflicts with a past decision?

With BrainOS, the agent calls decision_check before committing to a direction. It returns clear, caution or conflict, with the original reasoning attached, so you can decide on purpose instead of rediscovering an old tradeoff after shipping.

What if the decision is out of date?

Each decision has a review date and invalidate_if conditions. When a condition looks like it has come true, BrainOS flags the decision for review instead of enforcing it forever.

Does this work with Claude Code?

Yes. Run npx brain-os init in your project, then claude mcp add brain-os -- npx brain-os serve. The same .brain/ folder also works with Cursor, Zed and other MCP clients.