Keep the Why
The why layer of repo-native project memory: preserve your codebase's reasoning as Git-versioned Markdown, so coding agents and humans never re-propose what was already rejected.
- Source repo
- oliver-zehentleitner/keep-the-why
- Stars
- ★ 240
- Last updated
- 3d ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 83/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A team running coding agents on a long-lived codebase wants to stop re-litigating settled architecture questions in every fresh session
- Not a fit if
- Teams wanting session memory, transcripts or task tracking — this does none of those
- One-off scripts with no long-lived maintenance burden to protect
- Workflows unwilling to commit context/ Markdown into the repository
- Website
- keepthewhy.com ↗ set on GitHub
- Maintenance
- Commits in the last 30 dayslast commit 2026-11-18latest release v0.20.3 (2026-10-21)
- Source review
- 83/100 · Good
What does this agent do, and when should you use it?
Keep the Why is a SKILL.md-format agent skill that preserves the reasoning a codebase can't explain on its own: architecture decisions, rejected alternatives, workarounds, incident learnings, and operational constraints. Everything is plain Markdown in the repository's context/ directory, committed with the code — Git provides the storage, history and distribution, with no database, no daemon, and no account. The skill works in four modes: continuous capture during development, retrospective recovery on existing repos, knowledge-transfer interviews, and maintenance of existing entries. Companion tools built in this repository include keep-the-why-lint, a structural validator on PyPI and the GitHub Marketplace, and keep-the-why-dashboard, a read-only viewer. It supports 70+ agent tools (Claude Code, Codex CLI, Gemini CLI, Cursor, and more) and backs its core claim with a controlled experiment: with a context/ record, zero of ten fresh agent sessions re-proposed an already-rejected simplification; without one, seven of ten did. MIT-licensed, one-command install, and after a one-time setup it keeps working with the project automatically.
Once installed, the agent notices rationale worth keeping during normal development and writes it to topic files in context/, located via context/index.md, using fields like a UUIDv4 Id, Status (active/superseded/…), Evidence (confirmed/inferred/unknown), rejected alternatives and reasons. The flow: install the skill package via npx skills add or gh skill install, tell your agent "initialize Keep the Why in this project", complete the one-time setup wizard (creating a .keep-the-why marker file at the project root, configuring capture mode, CI linting, and how the skill loads in future sessions), after which the agent reads that marker at each session start and keeps capturing. keep-the-why-lint validates required fields, value sets and index consistency in CI; keep-the-why-dashboard serves a local read-only view (or a static export) over context/, the config, lint findings and Git history, with a topic-reference graph and queues of what needs a person.
- A team running coding agents on a long-lived codebase wants to stop re-litigating settled architecture questions in every fresh session
- A new maintainer or a fresh agent inheriting a legacy project needs to know whether odd code is a Chesterton's Fence or safe to delete
- Before a veteran maintainer leaves, the interview mode analyzes the codebase and asks targeted questions — or just listens — to capture tacit knowledge
- An agent abandons a proposed simplification after discovering a real constraint (no commit, no PR); the skill still records the reason so the next person doesn't rediscover it
- A team wants mechanically checkable structure for context/ in CI via the keep-the-why-lint GitHub Action
Key setup facts
Pulled from the install and usage notes below. The project README has the current values.
- Install / run
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-whypip install keep-the-why-lint
How do you install or deploy this agent?
Recommended — skills CLI (needs Node.js; npx ships with it):
bash
npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-whyPrompts for one of 70+ agents and project/personal scope. Or via GitHub CLI (v2.90.0+):
bash
gh skill install oliver-zehentleitner/keep-the-why keep-the-why@latestAs a Claude Code plugin:
bash
claude plugin marketplace add oliver-zehentleitner/keep-the-why --sparse .claude-plugin skills
claude plugin install keep-the-why@keep-the-whyIn CI (GitHub Actions):
yaml
uses: oliver-zehentleitner/keep-the-why@lint-latestOr locally:
bash
pip install keep-the-why-lintHow do you use this agent?
After installing, start a new session and tell your agent "initialize Keep the Why in this project" — on a brand-new project, setup only runs from such a request. The wizard is one list; answering "defaults" gives the fully integrated setup: proactive capture, a project-carried start path, and lint installed from PyPI. Then work as usual — the agent writes to context/ when rationale surfaces; entries live one file per topic, found through context/index.md. Retrospective mode reconstructs what it can from git history, issues and code on an existing repo; interview mode asks targeted questions or listens to free narration before knowledge departs. The dashboard shows entry statuses and what still needs a human.
What are this agent's strengths and limitations?
- No database, no daemon, no account: context/ is Markdown in the repo, so a PR shows the reasoning diff beside the code diff
- The core claim is measured: across 20 fresh sessions, 10/10 avoided the rejected simplification with a record vs. 7/10 repeating it without one
- Open Agent Skills format spanning 70+ tools with multiple install paths (skills CLI, gh, Claude/Codex/Copilot plugins)
- Complete in-repo ecosystem: structural validator (keep-the-why-lint, with a GitHub Marketplace action) and read-only dashboard (keep-the-why-dashboard)
- Retrospective recovery on existing repos is limited — history, issues and code give back only part of the why, and the docs admit filling the rest takes real effort
- Whether captured rationale is true stays a human judgment; the linter only checks structure, and the project ships no opinion on keeping docs honest over time
- A skill cannot load itself — session-start loading depends on hooks or entry-point sections set up by the wizard, and unlisted agent tools are unmeasured
- Requires committing and reviewing context/ files in the repo — a workflow change for teams unwilling to carry docs in their diffs
How does this agent compare with similar options?
Architecture Decision Records remain the right tool for major, discrete architectural decisions; Keep the Why's topic files handle the larger, messier volume of smaller rationale — complementary, not competing. AGENTS.md is treated as the lean agent entry point rather than a rival. Unlike session memory (e.g. Claude Code's auto memory), it preserves project-level why, not a transcript of agent activity. The maintainer publishes a dated comparison against Claude Code Auto Memory, MemoryCustodian and AgentsRoom (September 2026, on the blog).
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Keep the Why This agent | 83 · Good | Agent plugin / skillFree | ★ 240 | 3d ago | JavaScript | Codex · Claude Code |
| Softaworks Agent Skills | 44 · Major gaps | Agent plugin / skillFree + model costs | ★ 2.7k | 8mo ago | Python | Claude Code |
| Agent Skills for Context Engineering | 66 · Some gaps | Agent plugin / skillFree + model costs | ★ 18k | 1mo ago | Python | Codex · Claude Code |
| AOCI-CODE — a Git-versioned cognition index for coding agents | 82 · Good | CLIFree + model costs | ★ 2.8k | 1d ago | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The evidence says repository content must be treated as data rather than instructions, asks when rationale is uncertain, and classifies entries as confirmed, inferred, or unknown. The security documentation specifies path boundaries, read-only caches, and network requests. Deductions: proactive capture and automatic local lint can still write files or install and run a PyPI package; permissions rely on the host agent, with no separate permission layer; sensitive information is expressly prohibited, but the sample shows no automatic secret detection.
The README, skill, and security documentation broadly agree on Markdown/Git storage, capture, and maintenance, and state that structural lint cannot judge whether rationale is true. Deductions: the package sample does not cover every implementation behind its many optional components and supported platforms; availability depends on external agents, installers, Git, and PyPI. The CLIs give specific errors and exit codes for cases such as missing projects, invalid directories, and bind failures, supporting a high failure-message score.
The skill defines four scenarios—continuous capture, retrospective recovery, knowledge-transfer interviews, and maintenance—excludes routine implementation details, and sets a specific activation boundary. Installation documentation covers multiple agents, project or personal scope, and startup options. Deduction: operation depends on each host's skill-loading and startup support; the documentation acknowledges that some platforms remain unmeasured, so environment fit does not merit full marks.
The sample provides clear information architecture, detailed installation routes, command examples, an FAQ, stated limitations, an MIT license, and versioned configuration guidance. Deductions: version and update documentation is evident, but the complete changelog is not included in this sample; SECURITY.md names an individual maintainer and disclosure channels but shows no succession or team-maintenance arrangement.
The product keeps rationale in reviewable, searchable Markdown distributed with Git, with an index, entry format, and optional lint/dashboard tools. The sample also states that there is no similarity search and points to an experiment supporting its central claim. Deductions: ongoing capture, initial recovery, and maintenance still require agent and maintainer effort; the experiment's result is only a repository claim in this static review, so cost-benefit cannot be fully established.
The entry specification calls for Source, Verification, and evidence classification; the documentation distinguishes structural checks from factual judgment and points to traceable experiment, eval, and matrix materials. Deduction: the sample does not include the experiment results, full eval data, or all corroborating sources, so the README's effectiveness claims cannot be independently verified here.
- Defaults may allow proactive rationale writes; review the project's capture-confirmation setting and who reviews context/ changes.
- Automatic local lint may install and run a program from PyPI; check the personal local-lint setting, and account for third-party installers' separate data policies.
- Structural checks cannot establish that recorded rationale is true; retain unknown/inferred labels during retrospective recovery and have a maintainer verify the result.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * dashboard: an entry's Source, Verification and Revisit when are inline Markdown in the pills and the side pane by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/694 * FAQ: a live example of an entry whose Source is an issue by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/695 * Project config: source-reference always by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/696 …View on GitHub ↗ -
Release notes excerpt
What's Changed * FAQ: how to carry an existing ADR folder into context/ by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/686 * Dashboard: find a project in the registry from the search dropdown by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/687 * keep-the-why-dashboard 0.11.0 by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/688 …View on GitHub ↗ -
Release notes excerpt
What's Changed * Evals: the 0.20.0 series — 103 · 104 · 103 of 104, every gate passed by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/629 * Dashboard page: the opening says projects connect, and the graph and the globe let you walk them by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/630 * README: npm badge as the second badge by @oliver-zehentleitner-aigent in https://github.com/oliver-zehentleitner/keep-the-why/pull/631 …View on GitHub ↗
FAQ
Does it need a paid service or account?
Does it work on an existing repository?
Will it work with an agent tool not listed?
What if a captured reason is wrong?
Is this the same as session memory?
Is Keep the Why open source?
Is Keep the Why safe to use?
Is Keep the Why still maintained?
Who makes Keep the Why?
What is Keep the Why's official website?
Thanks — we use this to improve the page.