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.

Add this badge to your README

Featured on YunoDB Badge styles & help

Maintain this project? Show that it is featured on YunoDB.

Markdown[![Featured on YunoDB](https://yunodb.com/badge/oliver-zehentleitnerkeep-the-why.svg)](https://yunodb.com/tools/oliver-zehentleitnerkeep-the-why?utm_source=github&utm_medium=badge)
HTML<a href="https://yunodb.com/tools/oliver-zehentleitnerkeep-the-why?utm_source=github&utm_medium=badge"><img src="https://yunodb.com/badge/oliver-zehentleitnerkeep-the-why.svg" alt="Featured on YunoDB" height="20"></a>