Keep the Why

Keep a Changelog records what changed. Keep the Why preserves why it changed.

Keep the Why is the why layer of repo-native project memory: your repository already holds what the project is, how it works and what changed; this is the agent skill, and the file convention it maintains, that preserve the one thing it was missing — the reasoning behind a codebase — architecture decisions, rejected alternatives, workarounds, incident learnings, operational constraints that the code alone can't explain — in the repo. That memory is plain Markdown in context/, committed with the code, so Git already provides the storage, the history and the distribution: it travels with every clone, branch and fork, and a pull request shows the reasoning diff beside the code diff. It captures that reasoning as a byproduct of working with your agent, so every later session can use it. Your agent, and every other agent that works in the repository, understands not just the code but everything around it: why it is the way it is, what was tried and rejected, which constraints the source doesn't show. So does the next person. Onboarding gets faster, legacy projects become tractable again. It works continuously as you develop, where the reasoning comes for free.

It pays off most where re-debated decisions, forgotten workarounds and departed knowledge cost the most: maintainers and teams running coding agents on long-lived codebases. Starting on an existing repository works too, within limits — history, issues and code give back only part of the why, a maintainer has to fill in the rest, and that takes real effort. It is never too late to begin, though.

The payoff, made concrete: a new hire, or an AI agent that's never touched the codebase before, doesn't have to track down whoever wrote the original code — and doesn't just repeat what was already tried and rejected. That part is measured: 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). Every wrong turn the agent doesn't take is work nobody has to do and undo — it saves time, money in tokens, and nerves. The same context makes changes safer across the board — no more guessing whether an odd piece of code is a Chesterton's Fence worth keeping or just cruft nobody got around to removing — turning a legacy project back into something tractable instead of a black box only one person ever understood. "Ask Bob" stops being the fallback.

Documentation is normally extra work that happens after the code is done — reload the reasoning from memory, write it down again, file it somewhere else: a wiki, an ADR, a PR description nobody reopens. That's exactly why it so often doesn't happen. When an agent is already how you work — deciding, weighing trade-offs, explaining itself in the same conversation that produces the change — the reasoning shows up for free, as a byproduct of that conversation, not separate effort. Keep the Why's actual job is narrower than it sounds: don't let that reasoning get thrown away.

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.

Installable with one command on Claude Code, Codex, GitHub Copilot, Cursor, OpenClaw, Hermes Agent, Cline, OpenCode, Pi, Antigravity and 60+ more agents.

Website: https://keepthewhy.com · llms.txt for AI agents/assistants looking up this project

The problem

Important project knowledge gets created in conversation — with a teammate, or with an AI coding agent — and then evaporates once the conversation ends. The code shows what was built. It rarely shows why. Tests preserve expected behavior; they don't preserve the reasoning behind it — a project can be fully tested and still hard to maintain because nobody can explain why any of it works the way it does. Missing reasoning costs you in four concrete ways:

• Re-debate — the same architecture question gets re-litigated because nobody remembers it was already settled.
• Silent regression — someone "cleans up" a workaround that looks unnecessary, not knowing it's the fix for a bug that then comes back.
• Onboarding stall — new contributors (human or AI) don't touch code they don't understand, so progress slows out of caution.
• Repeated agent mistakes — a fresh AI session, with no memory of the last one, proposes or re-implements something already tried and rejected, because nothing on disk records that it was.

How it works

Keep the Why's agent skill is SKILL.md-based — an open, cross-agent format (Claude Code, Codex CLI, Gemini CLI, Cursor, and others). It operates in four modes:

1. Continuous capture — during normal development, the agent notices rationale worth keeping and records it alongside the code as it happens.
2. Retrospective recovery — pointed at an existing or legacy repository, the agent reconstructs what it can from git history, issues, and code, and is explicit about what it couldn't.
3. Knowledge-transfer interview — before a maintainer's knowledge becomes unavailable (leaving, retiring, changing teams), the agent analyzes the codebase first, then either asks targeted questions about exactly what the code couldn't explain, or — for someone whose knowledge is broad and tacit after many years on one system — just listens while they narrate freely and extracts the rationale from that instead.
4. Maintenance — existing rationale docs get kept current: contradictions resolved, superseded entries marked, oversized files split.

What you do: tell your agent to install it and set up the project — one sentence, for any of 70+ agents; "default settings" is a complete answer. Then work as usual. The defaults are the fully integrated setup: capture is proactive, the agent writes when the reasoning is clear and asks only when it is genuinely unsure, and the project carries its own start path, so every later session in that directory loads the skill by itself. You never have to tell it what to write down, and a project that was set up once stays set up: the start path is committed with it, so everyone who works in that directory gets the skill loaded — a new collaborator answers one short list of personal preferences the first time, and that is all. The longer version, with what that changes for pull requests and for teams: Keep the Why is not another workflow.

Works for autonomous agents too, with no human in the loop. Declare the session unattended and the agent doesn't ask into the void or drop what it found: it writes the entry and flags it pending-confirmation — recorded now, confirmed by the next person who looks.

That first activation runs a short one-time setup instead of guessing at defaults — where the why-knowledge should live, how to start, proactive or explicit-only capture, how much confirmation is needed before something gets written, whether to actively ask for a related issue or ticket, whether to periodically check for skill updates or context/ staleness, whether to wire the structural linter into the project's CI or publish the dashboard on the project's site (both optional, offered with the default no), whether the agent should run that linter locally on what it writes (installing it from PyPI — the default — or asking first), and how the skill gets loaded in future sessions (by default the project asks, through a section in its entry-point file and a hook where the platform has one). The defaults are the fully integrated setup, one word away; each wizard is one list with the defaults filled in, and whoever wants less picks less. See references/setup.md.

Set up the way the wizard proposes, the skill is loaded in every session — measured, and in my own daily use. Loading is the agent's job, and the skill hands it over explicitly: a skill package is instructions; no agent tool, and nothing in the open Agent Skills spec, gives a skill a way to load itself at session start. So the setup wizard asks how this project wants the skill loaded and has the agent set up what its own platform offers. references/autostart.md defines three start paths — every session machine-wide, the project asks (a hook, or a "Keep the Why" section in the project's AGENTS.md), or only when a developer asks — and lists per agent tool what is verified how. With a start path in place, loading does not depend on the conversation happening to match the skill's description — it is not a sometimes thing: Claude Code loads it in every measured session, by the hook (10/10 on the sessions that had gone 0/10 without one) and by the entry-point section (3/3, against 0/3 without it); Codex CLI, opencode and Cline load it by the section (3/3 each, against 0 or 1 of 3 without it); Hermes Agent by a live run. A tool that is not listed has not been measured, not failed — a pull request with a verified example is welcome any time; for anything else, open a new issue.

Because it's just Markdown in the repo, a context/ update ships in the same commit or PR as the code change it explains — reviewed the same way, versioned the same way, no separate system to trust or keep in sync. Git and your host do the rest: who may write the why is who may write the code (branch protection, CODEOWNERS on context/ if you want a named owner), every clone, branch and fork carries it, and git blame and git log are the audit trail — who recorded an entry, when its Status changed, where it is cited. Permissions, distribution, review, forks, branches, blame, card by card: Git does the rest; in one answer, with what blame does not show: FAQ.

The skill's behavior is exercised by a suite of eval cases, executed for real — a fixture project per case, a fresh agent session, LLM-judged verdicts. Full-suite numbers (case count, results, an honest failure analysis, the stated caveats) are tracked against Claude Code specifically: Evals. Which other agents and models the skill has actually been run against, and how: agent & model matrix. What changed per release, including what the evals found: CHANGELOG; open problems and ideas, one issue each: issues. One controlled experiment on the core claim — twenty fresh sessions asked to simplify a retry wrapper, ten with the rejected alternative recorded in context/ and ten without: What happens when a coding agent forgets why a change was rejected?, with every transcript, diff and grade under experiments/rejected-change/.

Where the captured knowledge actually lives, and how it relates to everything else a project already has, is one coherent picture — see "Where this fits" below.

Install

Your agent is the interface. Tell it:

Install the Keep the Why skill — pick the best installation method for you from https://keepthewhy.com/installation/ — then set up Keep the Why in this project with default settings, including autostart.

That is the whole setup: the skill is the one part a project needs. Three components are optional — the agent knows how to set up each one, offers them where they fit, and does it only when you say so:

By hand

main is active development, not guaranteed release-ready — pin to latest instead of tracking it directly (moved automatically by CI to the newest release; use an exact tag instead for full reproducibility).

Recommended — skills CLI (via npx, needs Node.js — npx ships with it, nothing extra to install):

npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why

Prompts you to select one of 70+ supported agents (Claude Code, Codex, GitHub Copilot, Cursor, Pi, Antigravity, OpenCode, OpenClaw, Hermes Agent, Cline, and more) and choose whether to install the skill at project or personal scope, then symlinks or copies the skill package in. Also listed on skills.sh. Start a new session afterward so the skill is picked up, then tell your agent something like "initialize Keep the Why in this project" — a Skill activates when something in the conversation matches it, not automatically on session start, and setup on a brand-new project only runs from a request like this one, never from an unrelated question the skill's description happens to match. This is only needed once: setup creates a .keep-the-why file at the project root, checked directly by this skill at the start of every later session — later sessions pick the project back up without needing to be told again.

Also recommended — GitHub CLI (gh v2.90.0+):

gh skill install oliver-zehentleitner/keep-the-why keep-the-why@latest

Prompts for which agent and scope (project or personal) to install for. This installs just the skill package (skills/keep-the-why/), not the whole repo — no docs/, mkdocs config, or CI files end up in your project.

Also installable via asm (agent-skill-manager):

asm install "github:oliver-zehentleitner/keep-the-why#latest:skills/keep-the-why" --tool all --scope global

--tool all installs one shared copy to ~/.agents/skills/ and links it into every agent asm knows — Claude Code, Codex, OpenCode, Cursor, GitHub Copilot, Gemini CLI, Cline and more. For one agent only, replace all with its name (claude, codex, opencode, cline, gemini, … — asm install --help lists them); --scope project installs into the current project instead of your home.

Also installable as a Claude Code plugin — the repository is its own one-plugin marketplace (.claude-plugin/plugin.json and marketplace.json at the repo root): claude plugin marketplace add oliver-zehentleitner/keep-the-why --sparse .claude-plugin skills, then claude plugin install keep-the-why@keep-the-why (tested on Claude Code 2.1.273; /plugin … inside a session is the same). As a GitHub Copilot CLI plugin — copilot plugin install keep-the-why@awesome-copilot, from the Awesome Copilot marketplace, which pins a release tag (the root plugin.json serves that format). And as a Codex plugin — the repository is its own one-plugin marketplace: codex plugin marketplace add oliver-zehentleitner/keep-the-why, then codex plugin add keep-the-why@keep-the-why (tested on Codex CLI 0.149.0; details and pinning on the installation page). And as a Cursor plugin — .cursor-plugin/plugin.json plus one always-on rule that loads the skill in a workspace carrying a .keep-the-why file and does nothing elsewhere; marketplace submission pending.

Fallback — manual clone, if neither of the above is available. The skill lives under skills/keep-the-why/ in this repo, not at the root, so clone to a scratch location and copy just that folder rather than cloning straight into your agent's skills directory (cloning the whole repo there would nest an embedded git repository inside yours, and pull in unrelated project files):

git clone --branch latest https://github.com/oliver-zehentleitner/keep-the-why.git /tmp/keep-the-why
cp -r /tmp/keep-the-why/skills/keep-the-why <target-directory>/keep-the-why
rm -rf /tmp/keep-the-why

Where <target-directory> is your agent's skills directory — the folder name must stay keep-the-why:

Codex CLI, Antigravity, Amp, OpenCode, Warp, and more read the shared .agents/skills/keep-the-why path at project scope (Codex scans it from your current directory up to the repository root) and ~/.agents/skills/keep-the-why personally — check whether yours does before falling back to a vendor path. Pi and Kimi Code also fall back to this same shared path (project and personal) if their own brand directory above doesn't have it.

Also compatible with Windsurf, Goose, Roo Code, Trae, Factory, JetBrains Junie, and other tools supporting the open Agent Skills format — the directory convention varies, check your tool's own docs.

Full install detail for every method, including tools without a skill runtime at all: docs/installation.md or https://keepthewhy.com/installation/.

Then fill it

A new context/ starts empty and fills itself as you work. What the project already knows — scattered across commit messages, pull requests, issues, old docs and people's heads — can be gathered right away, one sentence each:

Keep it current

A new release of the skill can ask something of a project — a new field, a renamed file, a check the linter now makes. Two sentences, in two sessions:

Example

You: We're changing the retry mechanism because the previous
     implementation caused duplicate orders. Make sure future
     maintainers understand this.

Keep the Why updates the relevant topic file in context/ (or creates one if none exists), records the reason, and marks the old approach as superseded — without you having to ask for documentation separately.

Weeks later, a new maintainer — human or agent — can just ask:

You: Why does the retry mechanism track state instead of just retrying?

and get the real answer instead of reverse-engineering it from the diff.

What if nothing gets changed at all?

You: This retry wrapper looks over-engineered — a plain retry loop
     would do the same thing. Let's simplify it.

Working through why it could be simplified surfaces a real constraint (the gateway's rate limiter needs that backoff behavior) — the change gets abandoned before it happens. No commit, no diff, no PR ever results, so normally nothing would capture that reasoning at all. Keep the Why records it anyway, so the next person with the same instinct doesn't rediscover it the hard way — see examples/abandoned-change.md for the full walkthrough.

See examples/ for continuous, retrospective, and interview-mode walkthroughs.

Where this fits

A project's documentation is one coherent group of files, not a single practice: each answers a different question, has a clear and non-overlapping scope, and knowing which is which is what keeps you from ending up with duplicates. A project missing any one of them still has a real gap. The full argument — the repository as the project's memory, context/ as the row it was missing, and where that argument is thin — is a page of its own: repo-native project memory.

Michael Feathers' classic definition — legacy code is code without tests — covers only the tests/ row. Each of the others answers a different question, and none substitutes for another: contribution process belongs in CONTRIBUTING.md, not context/; rationale belongs in context/, not scattered into a README that's supposed to stay a quick pitch. That doesn't mean every project needs all of them fully built out from day one — use the ones justified by the project's size, lifetime, and number of maintainers, the same way a one-file script doesn't need a docs/ folder (see references/repository-structure.md). What it does mean: once you know which question you're answering, you know exactly which file it goes in — see references/repository-structure.md for the same routing table with more detail. Full methodology behind the docs//context/ split specifically: references/methodology.md. The format itself — every file, field and value, and what a conforming project or tool must do: Specification.

What none of them does by itself: stay honest over time. Tests get skipped under deadline pressure, docs rot, changelogs get forgotten mid-release, and rationale decays — a 2026 position paper reported that a retrospective audit of 62 architectural decisions across two internal projects found roughly 23% had stale supporting evidence within two months, most of it caught only reactively, during an incident or a refactor. It's a small, non-replicated sample studying traditional ADRs, not AI-generated decisions specifically — cited here as a directional data point on rationale decay in general, not as proof about AI-assisted work. Keep the Why doesn't solve that alone; it just gives "why" a place to live so it can be kept current, the same way a test suite only helps if it actually runs in CI. Keeping all of them honest over time (via CI checks, review habits, whatever fits the project) is a separate, necessary piece this project doesn't ship an opinion on yet.

This isn't a new pattern, either. Docs and changelogs are already commonly kept current almost incidentally today, maintained by a skill or an agent alongside the actual work rather than as separate effort. Keep the Why brings that same low-effort, agent-maintained model to the one layer that couldn't be kept current this way before: the why.

Format

context/ entries follow the same shape whether written by hand, by this skill, or by any other tool speaking the convention — a small set of fields, not a fixed template. They live one file per topic, found through context/index.md — one line per topic under a fixed heading skeleton — so an agent reads the index and opens only the topic a task touches, never all of context/ at once. The skeleton's thirty-six headings are always present, so two branches adding topics cannot collide in the index (One Index, Many Writers):

Not every field belongs on every entry — Id, Status, Evidence, and the rejected alternative carry the most weight even in a minimal one; an entry without an Id is a linter error from context-schema 0.18.0 on. The normative format — config files, the context directory, the index skeleton, every field and value: Specification. Where each file goes and which file a piece of knowledge belongs in: references/repository-structure.md.

The structural half of this format is mechanically checkable — in CI, and locally by the agent itself: keep-the-why-lint (developed in this repository under lint/) validates required fields, value sets, index consistency, and .keep-the-why integrity — schema-version-aware, so unmigrated projects don't fail on structure their version never defined. Content (whether the rationale is true) stays a human judgment; the linter doesn't pretend otherwise. One line in GitHub Actions (uses: oliver-zehentleitner/keep-the-why@lint-latest, published as keep-the-why-lint on the GitHub Marketplace), or pip install keep-the-why-lint anywhere else — see Linting. The skill runs it itself too, when a developer's personal local-lint setting says so (the default asks before installing, never installs unasked): after every entry it writes, and with --setup over the developer's own two home files after a settings change — the part a CI runner can't see. This repository lints its own context/ with it in CI.

Reading it back has a tool too: keep-the-why-dashboard (developed in this repository under dashboard/) is a read-only viewer over context/, the config, the linter's findings and the Git history of all of it — who created each entry, who last touched it, when its status changed — with a graph of topics and references that reaches into the project's family and its friends — other repositories its entries cite — and finds the thoughts in it: chains of linked entries, each citing the one before, and where they pass an unconfirmed or questioned entry. Queues of what still needs a person, a timeline and an author view come with it. ktw-dashboard serves it locally and keeps it current while you work; --export writes one static page. It writes nothing into any project and holds nothing the repository doesn't; see Dashboard.

One repository or many

A .keep-the-why file marks a project, and the project is the nearest one above wherever the agent works — the same way Git finds .git. That one rule covers every layout:

Families can nest — a suite, its cluster, the cluster's dashboard — and routing then follows the parent chain: what binds a level's family goes to that level, what is wider goes up, to the root at most. The agent writes into any family member that is checked out on the machine, under that project's own confirmation setting; a member that is not is fetched only after a question, as a full clone or a read-only context cache. Entries carry a UUID, so a See or Superseded by line in one repository can cite an entry in another and stays valid when a heading changes or a file is split. The dashboard shows the family, and its public mode reads the other members' published exports without a checkout. Layouts: Repository structure; the rules: Setup, "Family"; every field: Specification.

Projects outside a family can refer to each other too: any entry can cite an entry in any other repository with a See line — nothing is routed or shared, it is a citation. The dashboard shows those repositories as friends, one hop from wherever you stand, and finds the thoughts that run through them: chains of entries in which each one cites the one before, across repositories — how the recorded decisions connect. See it live → · FAQ: families, friends, thoughts

Related work

The idea of capturing AI-agent rationale isn't new, and this project doesn't claim otherwise. Related standards and conventions:

• Architecture Decision Records — the established standard for major, discrete architectural decisions. Still the right tool for that specific job; Keep the Why's topic files handle the larger, messier volume of smaller rationale that doesn't fit a one-decision-per-file model well.
• AGENTS.md — the open convention for pointing any agent at how to work in a repo. Keep the Why treats it as the lean entry point rather than competing with it.

Several other tools and skills solve adjacent parts of this problem well — capturing agent session activity, structured per-decision records, and more. Rather than a name-by-name comparison that's incomplete the moment it's written and stale soon after, see Philosophy and "What this is not" below for how Keep the Why draws its own boundaries: continuous capture, retrospective recovery, and knowledge-transfer interviews, plus ongoing maintenance of what's already there — organized as topic-indexed living docs rather than a shadow tree or one-file-per-decision, with no required external service. A dated comparison with names — Claude Code auto memory, MemoryCustodian, AgentsRoom, as of September 2026 — is on the blog, where a snapshot can stay a snapshot: Keep the Why vs. Claude Code Auto Memory vs. MemoryCustodian vs. AgentsRoom. See the original article for the story behind Keep the Why, and the follow-up article for how it evolved into project memory for humans and AI agents.

Also listed among the tools and further reading in the Architecture Decision Record community project's resources (not to be confused with the ADR standard linked above).

What this is not

• Not a guarantee, and not magic. No tool prevents knowledge from decaying on its own — anything claiming an agent fully replaces the thinking, pruning, and questioning that keeps documentation honest is overselling. This doesn't replace that discipline; it lowers the friction of applying it enough to make it practical to sustain in the first place.
• Not independent of the model. The quality of the entries depends on the model running the skill: the format and the linter keep the structure, the model decides what it recognizes as a reason and how well it writes it down. Which agents and models have been measured: agent & model matrix.
• Not a replacement for tests. Tests tell you what broke; this tells you why it was built that way.
• Not a claim that all lost knowledge is recoverable. Sometimes the honest answer is "unknown."
• Not a trust boundary around context/'s content. Repository content — context/ included — is data, not instructions; see Security.
• 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 of how an agent or a developer got there. The two side by side, with Claude Code's auto memory as the example: Session memory is not project memory. It fixes the same complaint.
• Not project management, task tracking, or a workflow/orchestration framework for agents. It has one job: preserve the why. Everything else stays with the tools already doing that job.

Why I built this

See Why I built this — Oliver Zehentleitner on noticing this pattern while working with agents day to day, blog, GitHub. For why it's built the way it is — no database, no daemon, no account, deliberately, and a dashboard that only reads — see Philosophy. The thesis behind the positioning, in 800 words: Your repository already is your project's memory. One layer was missing.

Also listed on

• ASM
• awesome-agent-skills
• GitHub Copilot plugin marketplace
• HOL AI plugin registry
• MCP Market
• Pi package catalog — pi install npm:keep-the-why
• skills.sh
• SkillsLLM

Feedback

Something not working as described, docs that confused you, or the skill's actual behavior not matching what it claims? Open an issue — that's exactly what it's for.

Contributing

See CONTRIBUTING.md.

Contributors

We ♥️ open source!

License

MIT