Keep the Why vs. Claude Code Auto Memory vs. MemoryCustodian vs. AgentsRoom

"Project memory for coding agents" now means several different things, and most comparisons put them in one list as if they competed. They mostly don't.

Before comparing tools, ask three questions.

Where does it live? In the repository, in a directory on one machine, or on a server. This decides who gets it with a clone, whether a pull request can review it, and how much of the normal Git workflow applies to the memory itself.

Who can read it? One person, everyone using one particular app, or anyone who can open the repository.

What does it remember? This is the question that gets skipped. A memory can hold three different things, and they are layers, not rivals: what happened (a session, a transcript, a fix that worked), where the project stands (status, next action, what shipped), and why the project became what it is (the decision, the rejected alternative, the constraint the code doesn't show).

Run the names that usually appear in these lists through those questions and most of them leave the room. mem0, Letta, Zep and similar systems are external long-term memory systems centered on what an agent or user should remember across sessions, rather than rationale stored with the repository. Aider, Mastra, Dify and Langflow are a coding agent and frameworks with memory as a feature. Other tools focus on session observations, task state, project plans or summaries.

What is left here is a narrower comparison: two repo-native approaches that preserve durable project knowledge, Claude Code's built-in auto memory, and a server-backed project-memory implementation.

The table

Checked on 2026-10-04 against Claude Code's memory documentation, MemoryCustodian's README, AgentsRoom's Project Memory page, the Keep the Why specification, repository structure, dashboard documentation and registry documentation.

The part that changed most in Keep the Why

Keep the Why started as a deliberately small idea: put durable rationale in context/, keep it in Git, and let the agent maintain it.

That part has not changed. What changed is the topology around it.

A .keep-the-why file now marks a project, and the nearest one above the working directory wins, similar to how Git finds .git. That one rule covers four layouts.

A single repository has one .keep-the-why and one context/.

A mono repository can either share one context/ across the whole tree or give sub-projects isolated contexts of their own.

A multi-repository project can form a family. The parent lists its children with one scope line each, and each child points back to its parent. That relationship is not just for visualization. It is routing: rationale belongs once, in the family member whose scope owns it, and other members cite it instead of copying it.

A nested repository, such as a submodule or vendored checkout, remains its own project. The nearest .keep-the-why wins, so its memory does not leak into the surrounding repository.

Families can nest as well.

That solves the close relationships. Independent repositories use a different mechanism.

A friend is simply another repository cited by an entry through a stable entry UUID and that repository's canonical identity. Nothing is routed or synchronized between friends. The citation is the relationship.

Once entries can cite entries in other repositories, something else appears naturally: thoughts. A thought is a chain of rationale entries where each step cites or supersedes another one. The dashboard can follow those chains through a project, through its family, and into friends.

The dashboard is still read-only. Locally it is a view over context/, .keep-the-why, linter findings and Git history. A static export is a rebuildable snapshot, not a second source of truth. Delete the dashboard and the project memory is still the Markdown in Git.

The globe takes that one step further. It loads published dashboard exports as a graph and can walk outward by repository hops. A repository can expose its family and the friends it cites without moving the rationale itself into a central service.

The registry makes public exports discoverable. It stores the project pointers and derived metadata needed by the globe, not the rationale itself. It also provides the direction citations alone cannot: discovery of projects that cite you.

That distinction matters. Family is ownership and routing. Friends are citations. Thoughts are chains through those citations. The registry is discovery. The globe is a view over all of it.

None of those changes the authority model: each repository remains authoritative for its own rationale.

Where the others are better

Claude Code Auto Memory still wins on setup. It is built in, on by default in normal local sessions, and it remembers a layer Keep the Why deliberately leaves out: your role, preferences, corrections and working patterns.

Claude Code has also moved since the first version of this comparison. It can now read AGENTS.md directly as project instructions, so shared repository instructions no longer necessarily need a Claude-specific import workaround. That makes the surrounding project-instruction story more portable, but auto memory itself is still machine-local by default and remains a Claude Code feature.

That is not a defect. It is personal and tool-local memory doing the job it was designed for.

MemoryCustodian is still the closest neighbour, but it has become a much stronger protocol since the earlier comparison.

It is repo-native, plain Markdown and deterministic about loading. It now has stable Subjects and Facets, evidence requirements, candidate memory in inbox.md, path-scoped areas, explicit forgetting, conflict checks, transaction journals, recovery, migrations, audit output and private local overlays.

The design difference is clearer now than it was before.

MemoryCustodian treats project memory as a controlled protocol operated through a CLI. Keep the Why treats the committed Markdown as the memory and the skill as the maintainer of that text. If you want stronger command-level enforcement, structural conflict handling and explicit mutation machinery, MemoryCustodian is the more opinionated tool. If you want the rationale to remain ordinary repository text with Git as the main system around it, Keep the Why stays deliberately thinner.

AgentsRoom Project Memory has the most integrated application experience of the four.

It has fuzzy search, a first-class editor, wiki-links, a graph, five project-memory folders, four scopes, automatic agent capture, update-in-place, append and edit operations, and a useful visual signal for notes that are getting old.

It also solves cross-project memory, but with a different ownership model. Folder, Account and Agent scopes let knowledge span projects inside AgentsRoom. Keep the Why instead keeps project rationale owned by repositories and connects repositories with explicit citations.

AgentsRoom stores Project Memory server-side. The local cache lets the UI show notes offline, but agent memory tools talk to the server on every call. The project id committed in the repository makes the shared memory follow the project inside AgentsRoom, but the notes themselves are not Git objects and are not reviewed in the repository's pull requests.

For a team already using AgentsRoom as the place where its agents live, that is a coherent trade. For a repository that should remain complete without the application, it is exactly the trade the repo-native approach avoids.

What Keep the Why doesn't do, on purpose

• No similarity search. Retrieval is the index, topic names and explicit references. Entries are synthesized and read as Markdown, not embedded and ranked. Any external search tool can index context/; Keep the Why does not require one.

• No server as the source of truth. Family, friends, thoughts, dashboard exports, the registry and the globe add views and relationships without moving ownership away from the repositories. A published state.json is derived output. The canonical rationale is still the project's committed Markdown.

• No automatic "this reasoning is stale" oracle. Entries can carry Revisit when, statuses such as needs-review, and evidence state. The dashboard queues them, but it does not decide that an old decision is wrong merely because time passed. Age is a signal; validity is a project judgement.

• No semantic commit gate. The linter checks structure, references and security properties, not whether a decision is good. Prevention happens earlier, in the session, by giving the next agent the reason before it proposes the same rejected path again. In the retry-wrapper experiment, 7 of 10 fresh sessions proposed the rejected simplification without the recorded rationale; with the entry present, 0 of 10 did (the experiment).

• No UI that becomes another knowledge store. GitHub can render context/ directly. The dashboard adds a much richer read-only view over the same data and its Git history, including family, friends, thoughts and the globe, but writing still happens in the repository.

The reasons for those choices are in the FAQ.

The part that is true of all four

Every one of these tools lives on the quality of what gets written into it.

A server full of notes, a MEMORY.md, a protocol full of stable IDs, or a context/ full of Evidence fields is not useful merely because it persists. None of them can recover reasoning that was never captured, and none can guarantee that a claim remains true forever.

The differences are in what gets written, who owns it, how it is retrieved, and what happens when the project grows beyond one session, one machine or one repository.

Keep the Why's answer is deliberately narrow: preserve the reasoning behind the code as structured Markdown owned by the repository. The agent synthesizes rather than records. A rejected alternative is stored as a rejected alternative with the reason it lost, not as a transcript a later reader has to interpret.

The newer family / friends model extends the same rule instead of replacing it. Related repositories can be routed as one family. Independent repositories can cite each other. The dashboard can connect those citations into thoughts and walk them through the globe. The registry can make published projects discoverable.

But Git still owns the memory.

Session memory remembers what happened. Project state remembers where the project is. The why layer remembers why it became what it is.

Three layers. Pick one tool per layer if you need all three, and don't let a comparison, this one included, tell you they are rivals.

I hope you found this informative and useful.

Follow me on GitHub, Bluesky, Mastodon, X, and LinkedIn, or join Telegram for updates on my latest publications. Constructive feedback is always appreciated.

Thank you for reading, and happy coding! ¯\(ツ)/¯