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.

Stars
★ 240
Last updated
3d ago
License
MIT
Primary language
JavaScript

At a glance

How it runs
Agent plugin / skillCLI
Works with
Universal · cross-platformCodex · Claude Code
Cost
Free, no paid service needed
Setup effort
Low · running in minutes
You'll need
Node.js (for npx skills CLI) or GitHub CLI v2.90.0+Shell / CLINetwork accessLocal filesystem
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.

  1. A team running coding agents on a long-lived codebase wants to stop re-litigating settled architecture questions in every fresh session
  2. 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
  3. Before a veteran maintainer leaves, the interview mode analyzes the codebase and asks targeted questions — or just listens — to capture tacit knowledge
  4. 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
  5. 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-why
  • pip 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-why

Prompts 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@latest

As 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-why

In CI (GitHub Actions):

yaml

uses: oliver-zehentleitner/keep-the-why@lint-latest

Or locally:

bash

pip install keep-the-why-lint

How 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?

Pros
  • 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)
Limitations
  • 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?

FollowAgents source review · FARS-2.1
Good
83/ 100 5-point scale 4.2 / 5
Trust 21/29
Reliability 11/14
Adaptability 16/18
Convention 16/18
Effectiveness 12/13
Verifiability 7/8
Why each dimension lost points
Trust21 / 29 · 3.6/5

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.

Reliability11 / 14 · 3.9/5

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.

Adaptability16 / 18 · 4.4/5

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.

Convention16 / 18 · 4.4/5

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.

Effectiveness12 / 13 · 4.6/5

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.

Verifiability7 / 8 · 4.4/5

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.

Risks and how to mitigate them
  • 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.
Evidence confidence: Low Reviewed Nov 08, 2026 Reviewed revision 28bfdc94abff New commits since this review; the score may not cover them
See the full review method →
Maintain this project? Add the FARS badge to your README

The badge shows the current review score and verdict and links back to this page. It refreshes about once an hour after a re-review.

FARS

[![FARS review](https://followagents.com/badge/keep-the-why.svg)](https://followagents.com/en/agents/keep-the-why)
<a href="https://followagents.com/en/agents/keep-the-why"><img src="https://followagents.com/badge/keep-the-why.svg" alt="FARS review"></a>

Recent releases

Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.

  1. v0.20.3
    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 ↗
  2. v0.20.2
    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 ↗
  3. v0.20.1
    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?
No. Storage is your repo's Git and Markdown — no database, no daemon, no account; MIT licensed. Whatever you pay to run your coding agent's model is unrelated to this project.
Does it work on an existing repository?
Yes, but the docs state the limits honestly: history, issues and code give back only part of the why; a maintainer must fill in the rest, and that takes real effort.
Will it work with an agent tool not listed?
The skill is the open SKILL.md format and installs broadly, but automatic per-session loading relies on platform hooks or entry-point sections. Unlisted tools are unmeasured, not failed — verified-example PRs are welcome.
What if a captured reason is wrong?
Entries carry Status (active/superseded/open/needs-review/pending-confirmation) and Evidence (confirmed/inferred/unknown); maintenance mode resolves contradictions and marks superseded entries. The linter checks structure only — truth stays a human judgment.
Is this the same as session memory?
No. Session memory remembers what happened; project state remembers where the project is; Keep the Why preserves why it became what it is — a third layer, not a transcript or activity log.
Is Keep the Why open source?
Yes. The source code is on GitHub (oliver-zehentleitner/keep-the-why) under the MIT licence.
Is Keep the Why safe to use?
FollowAgents' FARS review (Nov 08, 2026) scored Keep the Why 21/29 on trust and safety. None of the eight safety controls the review checks for was missing outright. The repository has changed since that review.
Is Keep the Why still maintained?
Yes. The latest commit on GitHub is from 2026-11-18, within the last 30 days. The latest release is v0.20.3 (2026-10-21).
Who makes Keep the Why?
Keep the Why is published on GitHub by the account oliver-zehentleitner. FollowAgents has not verified which person or company is behind that account.
What is Keep the Why's official website?
The project's GitHub repository lists https://keepthewhy.com as its website. That link is set by the repository owner; the source code itself is on GitHub (oliver-zehentleitner/keep-the-why).
Was this page helpful?
View on GitHub ↗ Install ↓

Compare agents like this one

The same FARS review applied across the shortlist this agent qualifies for.

Related concepts