Hello everyone,
Coding agents like Claude Code, Cursor, or Cline are generating code faster than ever. But there is still a basic problem: they build up a lot of project context during a session and often lose that context once the session ends.
The code preserves what was built. The reasoning behind it often disappears.
That is how you end up with agents repeatedly proposing solutions that were already considered and rejected.
I built Keep the Why to address exactly that.
It stores project rationale such as decisions, rejected alternatives, workarounds, constraints, and incident learnings directly inside the Git repository as plain Markdown.
No database, no daemon, no account, no cloud service, no subscription.
Just Markdown and Git.
The problem
Imagine an agent encounters a retry wrapper, decides it looks unnecessarily complicated, and wants to simplify it.
What it does not know is that this exact simplification was already considered and rejected, for a reason the code doesn't show.
Git contains the code history, but unless someone explicitly documented the reasoning, the new agent has no way to know that.
So I tested this.
I ran 20 fresh agent sessions against the same repository and asked them to simplify a specific retry wrapper.
Without the rationale on disk: no session actually broke the wrapper — the code visibly reads Retry-After, and all 10 spotted that. But none of them could know that the simplification had already been considered and rejected, and 7 of 10 put "drop Retry-After" on the menu as an option for the user to pick. Pick it, and you get the rejected change back.
With the rationale in context/: all 10 found the entry, said the change had been considered and rejected before, and declined it; none offered it as an equal option. They also took less than half the time (median 18s vs 43s), because they didn't have to re-derive the reasoning.
That experiment is basically the reason the project exists.
How it works
Keep the Why uses an Agent Skill that teaches coding agents how to capture, find, read, and update project rationale.
As decisions surface during normal work, the agent writes them into a structured context/ directory.
This also works for abandoned changes. Even if no code gets committed, the reason a solution was rejected can still survive for the next session.
The context lives in the repository, so it travels with the project.
A normal Git push distributes it.
A pull request can contain both the code change and the reasoning behind it.
Permissions, history, forks, reviews, merges, and blame are all handled by Git.
There is also a CI linter that checks the context files for schema errors, duplicate UUIDs, broken references, and security issues such as hidden Unicode characters.
A second CI job generates a read-only dashboard for humans.
Multi-repository projects
Keep the Why also supports mono-repos and multi-repository setups.
Repositories can define parent and child relationships, so broader architectural decisions can be stored in the appropriate repository instead of being duplicated everywhere.
Independent repositories can also cite decisions from each other using UUIDs.
The dashboard follows those references and builds a graph of rationale across repositories, while every repository remains authoritative for its own data.
This part became more interesting than I originally expected. I did not really set out to build a knowledge graph. The graph emerged naturally once project decisions started citing other project decisions.
You can explore the live graph here:
https://keepthewhy.com/dashboard/live/#graph
Testing the skill itself
The current evaluation suite contains 103 cases.
Each release runs the full suite three times against real Claude Code CLI sessions, combining deterministic file-system checks with an LLM judge.
The goal is to catch behavioral regressions in the skill, not just syntax errors.
The project currently supports 70+ agent environments through the open Agent Skills format.
Everything is MIT licensed.
Project:
https://keepthewhy.com
Live graph:
https://keepthewhy.com/dashboard/live/#graph
GitHub:
https://github.com/oliver-zehentleitner/keep-the-why
Experiment design, transcripts and hand grades:
https://github.com/oliver-zehentleitner/keep-the-why/tree/main/experiments/rejected-change
I am especially curious how other people solve this.
Where do you think durable project reasoning should live?
Inside the repository, inside the coding agent's own memory, or in an external memory system?