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 repo remembers: not the code, not the changelog, not the docs.
Keep the Why is the part that remembers. 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 94/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 →