Keep a Changelog records what changed.
Keep the Why preserves why it changed.
Explaining the same decision to your agent again. New session, same codebase, no memory of why. The code doesn't carry the reasoning. Neither does the changelog.
Repo-native project memory for humans and coding agents. 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 GitHub
Open source under the MIT license — the skill, the linter, and this site. Nothing to sign up for, nothing that phones home.
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. 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 →
How it works
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. 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 every reason is written down once, never again, and the gaps that matter 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 92/100 with no high finding; the workflow fails below 80 or on any high finding.
What this is not
Not session memory. Project memory is the reasoning behind the project, not a transcript or activity log of how an agent or a developer got there.
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 dashboard, no account. Just Markdown, Git, and the why your project would otherwise lose.
The full list, and where Keep the Why fits next to ADRs, AGENTS.md and Keep a Changelog: README →