keep-the-why
The why layer of repo-native project memory: the reasoning behind a codebase as Markdown in the repo, versioned by Git, for coding agents and humans, so nothing
What is keep-the-why?
The why layer of repo-native project memory: the reasoning behind a codebase as Markdown in the repo, versioned by Git, for coding agents and humans, so nothing rejected is proposed twice. No database, no daemon, no account.
Overview of keep-the-why
What it is
Keep the Why is a tool that preserves the reasoning behind a codebase as Markdown files in the context/ directory, versioned by Git. It captures architecture decisions, rejected alternatives, workarounds, incident learnings, and operational constraints that the code alone cannot explain. The project is described as the why layer of repo-native project memory, designed for both coding agents and humans. It requires no database, daemon, or account.
Key features
- Stores reasoning as plain Markdown in
context/, committed with code and versioned by Git. - Works with multiple AI coding agents: Claude Code, Codex, GitHub Copilot, Cursor, OpenClaw, Hermes Agent, Cline, OpenCode, Pi, Antigravity, and 60+ more.
- Operates in four modes: continuous capture, retrospective recovery, knowledge-transfer interview, and maintenance.
- Default proactive capture: the agent writes when reasoning is clear and asks only when unsure.
- Supports autonomous agents with no human in the loop, writing entries flagged
pending-confirmation. - Provides a one-time setup wizard with configurable defaults for capture style, confirmation level, and integration options.
Use cases
- Preventing re-debate of already settled architecture decisions.
- Avoiding silent regression when someone removes a workaround that looks unnecessary but fixes a bug.
- Reducing onboarding stall for new contributors (human or AI) who lack context.
- Preventing repeated agent mistakes where a fresh session proposes something already tried and rejected.
- Knowledge transfer before a maintainer leaves, retires, or changes teams.
Getting started
See the repository README for installation instructions.
License and pricing
Licensed under MIT. The project is open source.
Based on the project's public README and repository metadata.