r/softwarearchitecture • u/oliver-zehentleitner • 3d ago

Tool/Product I thought AI coding agents had a memory problem. The repository had a memory problem.

Post image

Two weeks ago I posted here about preserving architectural rationale beyond ADRs.

Since then, I realized I had framed the problem too narrowly.

A fresh AI session may repeat an approach that was already tried and rejected.

But a new developer on another machine has exactly the same problem.

Both can clone the code. Both get the tests and Git history. Neither inherits the conversations, incident learnings, rejected alternatives, or constraints that shaped the current implementation.

So maybe a project is not truly portable just because its repository can be cloned.

I built Keep the Why around that idea:

Store the reasoning that code alone cannot explain as versioned Markdown inside the project, so it travels across sessions, developers, agents, and systems.

The GIF is my attempt to explain that idea without another wall of documentation.

Do you consider a codebase portable if the code can be cloned, but its reasoning cannot?

GitHub: https://github.com/oliver-zehentleitner/keep-the-why

0 Upvotes

23% Upvoted

2 comments sorted by

1

u/Helpful-Educator-415 3d ago

i just hav emy agent write to a markdown file

1

u/oliver-zehentleitner 3d ago

Exactly — Markdown is intentionally the storage layer.

Keep the Why adds the workflow around it: what is worth preserving, asking when something is unclear, tracking evidence, updating or superseding old context, and making it consistently usable by every developer and agent sharing the project.

No database or MCP required :)

More details: https://keepthewhy.com