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.
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.
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.
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.
The reasoning has to live somewhere the agent reads by default, in a form it can query. Some options, from lightest to most structured:
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:
decision_log records the decision with its why, rejected alternatives (and why each was rejected), assumptions, invalidate_if conditions and a review date.decision_check runs before the agent commits to a direction and returns clear, caution or conflict, with the original reasoning attached.decision_review surfaces decisions that are past their review date, or whose reopening conditions look like they have come true, so old calls do not get enforced forever.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.
Initialize BrainOS in your project, then connect it:
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.
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.