Keep a Changelog records what changed.
Keep the Why preserves why it changed.
Same question. Same wrong turn. Same explanation, again. Your agent forgets between sessions. Nothing in the usual project structure is dedicated to remembering it.
Keep the Why is the part that remembers why. Your repository already is your project's memory — README, docs, tests, changelog, history; one layer was missing. The reasoning behind a codebase — decisions, rejected alternatives, workarounds, constraints the code alone can't explain — captured as a byproduct of working with your agent and kept as plain Markdown in context/, versioned and shared by Git. No database, no daemon, no account.
Install Read the README Linter Dashboard GitHub
Open source under the MIT license — the skill, the linter, the dashboard, and this site. No account, no telemetry, no cloud backend.
What it leaves behind
context/retries.md
Why retry_with_jitter isn't a plain retry loop
Type: constraint
Status: active
Evidence: confirmed
Source: discovered while considering simplifying it, 2026-07-22
The payment gateway's rate limiter returns 429 with a per-request Retry-After header. A fixed-delay retry loop would frequently retry before the limiter resets, causing repeated 429s under load.
Considered: replacing it with a plain retry loop, since the wrapper looked like unnecessary complexity with nothing documenting why. Not adopted once the Retry-After behavior surfaced during review.
Decisions that shipped, alternatives that lost, workarounds, constraints — Keep the Why keeps the reasoning behind all of them: one entry per topic, plain Markdown, reviewed in the same pull request as the code, and found through a one-line-per-topic index, so an agent loads only the topic a task touches. This one is the case where it matters most: a change that was started and then dropped, so there is no commit, no diff, no pull request — and without the entry, no trace. Every entry says how well its claim is backed (Evidence) and whether it still holds (Status); "unknown" is a valid answer. The full example → · Field reference →
Live Dashboard
The dashboard — a read-only view over context/ and its Git history: who recorded what, when a status changed, what still needs a person. Run locally, it updates as the project changes; the example behind the screenshot is a static export of this repository's own context/, rebuilt with every docs deploy. Dashboard → · Example →
How it works
Install it with one command. Say "set up Keep the Why here" once in a project and answer the setup — "defaults" is a complete answer. Then work as usual.
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why
That line covers any of 70+ agents (Claude Code, Codex, OpenCode, Cursor, …); plugin marketplaces, a manual copy and a vendored, pinned install are on the installation page. The defaults include the start path, so from then on every session in that project loads the skill by itself. The agent records the why as it surfaces and asks only when it is genuinely unsure. You never have to tell it what to write down.
Capture
The agent notices rationale as it surfaces — a decision, an alternative that lost, a workaround, a change that was started and abandoned — and writes it down, without being asked. No separate documentation step. An existing repository can start late too. History, issues and code give back only part of the past why — but from that point on the reasons that matter are written down once, never again, and the gaps close over time.
Check
keep-the-why-lint validates the structure — locally and in CI — required fields, valid values, index consistency, plus security checks such as hidden Unicode and others. It says plainly what it cannot check: whether a recorded reason is true. That part stays with review, in the same pull request as the code.
Keep & Share
Everything lives in context/, one file per topic, versioned with the code. A lean index tells an agent what to load. No daemon, no database, no service — anything that can read a repository can read it. Once merged, the why sits in the history under the same review, permissions and CI as the code. That layer — Git, on GitHub, GitLab or any other host — is what turns a local file into shared knowledge.
Use
The next session — yours, a colleague's, an agent's — loads the index first and reads the why before touching the code. An agent that finds the reason explains it and builds on it instead of repeating the attempt; one that finds nothing says so and asks, instead of guessing. That is what the capture was for.
Tested, measured, stated plainly
Tested with: Claude Code, opencode, Pi, Hermes, and more — see the full eval suite and the agent × model matrix for what's actually been run against what, and how.
The skill is validated against the Agent Skills spec on every push; this repository's own context/ is linted by its own linter, in strict mode; the package is scanned by two independent registries — one of them, the HOL AI Plugin Scanner, on every push in this repository's own CI — currently 94/100 with no high finding; the workflow fails below 80 or on any high finding.
And one controlled experiment on the core claim: twenty fresh agent sessions, the same codebase, the same request to simplify a retry wrapper. Without a recorded reason, seven of ten offered the already-rejected simplification again. With one context/ entry, all ten found it and none did. The experiment → · transcripts and grades
What this is not
Not session memory — and it does the job session memory is wanted for. Session memory remembers what happened; project state remembers where the project is; the why layer preserves why it became what it is. This is the third — not a transcript or activity log. But what people reach for session memory to fix — the agent forgetting between sessions — this fixes at the source: the reasoning is in the repository, so every session starts with it, on every machine and in every tool, for the whole team.
Not magic. No tool prevents knowledge from decaying on its own. This lowers the friction of the discipline that keeps documentation honest; it doesn't replace it.
Not a platform. No daemon, no database, no account. Just Markdown, Git, and the why your project would otherwise lose — and a read-only dashboard over both, for when you want to look.
The full list, and where Keep the Why fits next to ADRs, AGENTS.md and Keep a Changelog: README →