DEV Community: Oliver Zehentleitner

Keep the Why vs. past.dev vs. Agent Memory Repo vs. agentmemory

Oliver Zehentleitner — Tue, 13 Oct 2026 15:34:10 +0000

Four tools called agent memory. Four different approaches to what should survive. One puts decision rationale next to the code.

This is the third dated comparison. The first looked at Claude Code auto memory, MemoryCustodian and AgentsRoom. The second compared OKF Agent Memory and RepoWise, the two that work closest to the repository.

Since then, more names have joined the "memory for agents" lists. One I'll leave outside this table: WikiKB from GitHub Next is a knowledge base built from ingested sources and published to a repository wiki. Interesting work, but a different comparison.

Three stay. past.dev is a memory API that launched at the end of September. Agent Memory Repo is the Git-backed memory format Cognition released as an open standard in October. agentmemory, no space, is a local memory server that can capture coding-agent activity through hooks. They overlap in places, but they make different choices about what to preserve.

I built Keep the Why, so this isn't a neutral review. I've tried to be fair about the boundaries, including where the other tools are better. The questions are mostly the same ones I've used before, with one added.

Where does it live? On a vendor's server, on your own machine, in a Git repository of its own, or in the code repository itself. This decides who gets it with a clone, and whether the pull request changing the code can include the memory that explains it.

What does it hold? Facts that change over time. What an agent did in a session. Preferences and findings that should survive into the next one. Or the reasoning behind the code: the decision, the alternative that lost, the constraint the diff cannot show. These are layers, not rivals.

What happens to the old value? When a fact, memory or entry changes, can the next reader still find what came before? And can they find out why it changed?

The table

Checked on 2026-10-12 against past.dev, its launch post and docs; the Agent Memory Repo page, README and SPEC.md; the agentmemory site, docs and repository; and the Keep the Why specification. This is a snapshot, not a claim about what any project will support next month.

	Keep the Why	past.dev	Agent Memory Repo	agentmemory
Where it lives	`context/` in the code repository	managed cloud; on an Enterprise agreement, in your own cloud account, operated by past.dev	a separate Git repository, by design	local data directory, served by a process on your machine
What it holds	decisions, rejected alternatives, workarounds, incidents and constraints, with their reasons	dated claims extracted from emails, calls, tickets, chats and documents	short entries for preferences, decisions, facts, useful queries and shared agent findings	captured session observations, summaries, memories, lessons and knowledge-graph relationships
What happens to the old value	superseded entries point at their successors; Git preserves file history	previous values remain dated and retrievable; recall supports an earlier point in time	entries are updated or removed when stale; their earlier text survives in Git history	a close-match save creates a supersession chain; a looser match returns a hint; built-in decay and expiry sweeps run by default; LLM-backed consolidation depends on provider configuration
In the code pull request	yes, if the `context/` change is committed with the code	no	not automatically; its Git history and reviews live in the separate memory repo	no; supported tools can link commits back to captured sessions
Who writes, when	the agent during a task, under the project's confirmation rules	the application sends source records; the service derives memory	the agent updates the memory repo; Dreaming is a separate periodic-maintenance concept	hooks capture supported events; LLM-backed consolidation runs with a configured provider unless disabled; other processing depends on the integration and settings
What has to run	nothing; linter and read-only dashboard are optional	the service, via REST or MCP	Git and a skill; no memory server required	a local server and runtime; an LLM provider is optional
Retrieval	topic index, then the relevant `context/` file	question plus reader identity; ranked claims with dated evidence	`MEMORY.md`, grep and `[[links]]`	BM25 by default; vectors and graph where configured; context injection is configurable
License	MIT	proprietary, credits charged for ingestion	MIT	Apache-2.0

One example

A coding agent suggests replacing a retry wrapper with a plain loop. The team rejects it because the service returns a per-request Retry-After, and ignoring that header caused repeated 429s under load. Three months later, a fresh agent suggests the same simplification.

All four systems could help, but through different paths. past.dev might retrieve the decision if someone ingested the review discussion. Agent Memory Repo might have a note if an agent saved it. agentmemory might find the old session if the relevant activity was captured and retained. Keep the Why is built to put the rejection and its reason in context/, next to the code, so a new agent can find it before making the same suggestion.

That is the case I tested with fresh agent sessions. It doesn't prove the other systems would fail. I didn't test them against each other. It shows what keeping the rejected alternative in the repository can change.

Where the others are better

past.dev puts time into the data model itself. A claim has a value, a date and the source behind it. A recall can ask what was known on a given day, not just what is current now. Git gives Keep the Why a different kind of history: you can inspect an earlier revision of context/, and a superseded decision can point to its successor. But that's not the same as querying a timeline of individual facts across a year of emails. past.dev can do that across sources that never entered a repository. If that's what your agent needs, Keep the Why isn't trying to replace it. The trade is that you now depend on a service, in past.dev's cloud or in yours, outside the code review. The source may explain why a fact changed, but recording a decision rationale isn't the service's specific job.

Agent Memory Repo is the closest neighbour in form: Markdown, Git, wiki-links, no server, and a skill in the same Agent Skills format Keep the Why uses. Its README describes personal memory, team memory and agent swarms. It also makes an important distinction: memory is data, not instructions. I agree. Its design keeps the memory in a separate repository. That works well when the same person or swarm moves between projects. For code decisions, I prefer the opposite boundary. A memory edit in another repository won't automatically show up in the pull request that changes the code. Its format uses one-line entries, which is fine for "prefers concise summaries" but less useful for "we tried parallel replay, it corrupted state, and this is why we serialize". When an entry becomes stale, the spec says to update or remove it. Git keeps the earlier version, but the next reader doesn't normally see it. That's a reasonable trade for preferences and changing facts. It's not the one I want for a rejected technical decision.

The Agent Memory Repo README also describes a periodic Dreaming agent that merges duplicates, removes stale entries and finds patterns. Its local trial does not set up automatic startup or scheduled Dreaming, so I wouldn't count that as maintenance you get just by installing the skill.

agentmemory is one of the more ambitious session-memory systems I've looked at. Hooks capture supported events and tool activity without asking the model to decide what deserves a permanent note. It can search observations, derive summaries and lessons, link related memories and track versions. It also has a commit-context skill that runs git blame, looks the commit up, and shows the agent session that produced it. I like the rule behind that skill: don't invent intent that the observations don't support.

But a trace of what an agent did isn't always the reason the team made a decision. If the reason was stated in that captured session, great. If it was settled later in a review, on a call, or by someone using another machine, a local session trace may not contain it. And even with hooks, capture isn't literally everything: coverage depends on the agent integration, filters and delivery. The project documents buffering and retry behaviour, but also limits and failure cases. That's not a criticism of agentmemory in particular. It's a limit of observing activity instead of asking for an explicit decision record.

agentmemory also has lifecycle rules. Version chains preserve superseded memories, and the built-in sweeps for lesson decay and expired memories are enabled by default. That is separate from LLM-backed consolidation, which runs when an LLM provider is configured and can be disabled. These are useful policies for information that may become stale. A rejected alternative in context/ works differently. It stays relevant until someone revisits or supersedes it. Neither policy makes sense for every kind of information.

Where Keep the Why is weaker

There are tradeoffs on my side too.

It has to notice the decision. Keep the Why doesn't record a complete session and sift through it later. The agent has to recognize a decision or a rejected alternative while it's happening, or reconstruct it later from a trustworthy source. If nobody records it, it can be lost. Hooks give agentmemory a much wider record of observable activity, even if that record has limits too.
The model matters. The linter can verify structure, not whether a reason was understood or explained well. Different models and agent harnesses still behave differently, which is why I publish the agent and model matrix. I expect this weakness to shrink as models improve. They are getting better at recognizing meaningful decisions and following instructions. But "better models will fix it" isn't a result I can put in a benchmark table today.
The index isn't a search engine. The agent reads a short index and follows the relevant topic. It works for the scale I've tested. At hundreds of topics, I don't yet have evidence that the same routing stays as reliable. Stronger models may help here as well. For now I don't want to add a search backend just to solve a scaling problem I haven't seen in a real project.

What Keep the Why doesn't do, on purpose

No transcript capture. No hooks, full session logs or automatic summaries of everything an agent did. An entry is the reason behind a choice, written when it matters or recovered later from evidence.
No general fact store. The current value of a setting belongs in the code or configuration. context/ holds why it has that value, what was considered instead and what could justify changing it.
No separate memory repository. The rationale belongs with the code because the person reviewing the diff should be able to review the reason too. The next person cloning the project should get both.
No background service. No daemon, Dreaming process or decay sweep. Maintenance happens when the project is being worked on, under the same rules as a new entry.

The FAQ and Philosophy pages explain why.

Beyond one repository: a web of context

There's an obvious question about keeping the why next to the code: what happens when the decision affects more than one repository? A shared library, the service using it and the application above it may all depend on the same constraint. I don't want three copies of the explanation that slowly drift apart.

Keep the Why links the entries instead. A See reference can point to a decision in another repository by its canonical URL and entry ID. Each repository still owns its own context/. A family makes the relationship explicit for projects that belong together, like the eight repositories in the UNICORN Binance Suite. Friends are other repositories an entry cites, even if they aren't part of that family. Follow the citations and you get thoughts: chains of decisions connected across repository boundaries.

The live dashboard makes this visible as a graph. Its globe can also discover projects that opt into the registry, including links between them. The registry is for discovery, not the source of the memory. The decisions remain Markdown in their respective Git repositories; the dashboard reads them, it doesn't own them. And a link doesn't bypass access rights: the other repository or its published export still has to be reachable.

That's the web of context I wanted. Not one global memory database, and not a pile of duplicated notes. The reason stays where it belongs, but the trail doesn't have to stop at the repository boundary.

The part that is true of all four

Each tool is answering a different version of "what should the next session already know?"

past.dev: what was true, when, and according to which source. Agent Memory Repo: what earlier sessions and teammates learned. agentmemory: what happened during supported agent sessions, and what can be recovered from them. Keep the Why: why the code is the way it is, including changes that were considered and rejected.

A project could use all four. I wouldn't, unless it actually needed all four, but there's no architectural conflict in doing so.

The traditional memory categories, working, episodic, semantic and procedural, can all contain explanations. I'm not claiming a reason is impossible to store in any of them. The difference is what you choose to make durable, and where you put it.

A codebase already has its implementation, tests, documentation and Git history. Sometimes the reason for a decision is somewhere in an issue, a review comment or an old session transcript. Sometimes it only existed in a conversation and is gone. I built Keep the Why because I want that reason to have a predictable place: a small, reviewable piece of Markdown beside the code it explains. Not a replacement for everything else an agent might need to remember. Just the part I kept seeing us lose.

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! ¯\_(ツ)_/¯

The Model Changed. My Skill Didn't. The Score Still Dropped.

Oliver Zehentleitner — Wed, 07 Oct 2026 09:48:26 +0000

What agent evals taught me about moving model floors, noisy LLM judges, and treating the evaluator as part of the instrument

My rule for evaluating an agent skill is deliberately asymmetric:

Test the agent on the weakest model you intend to support. Choose the judge by measuring which model grades that task reliably.

Those are two different jobs. For the agent under test I want the floor: if a skill only works because a stronger model silently compensates for vague instructions, I have not tested the skill. For the judge I want a steady measuring instrument, and how strong it has to be for that is something to measure, not to assume.

I arrived at this while building the eval suite for Keep the Why, a repo-native project-memory skill for coding agents. The lesson applies to any setup where one model performs a task and another one grades it, because neither side of that measurement stays still. And if you do not record the instrument, a regression in the instrument looks exactly like a regression in your product.

The day the score dropped without the skill changing

The eval runner runs each case in a fresh fixture project through a real coding-agent session, captures transcript and disk diff, applies deterministic checks where possible and sends the rest to an LLM judge. Agent and judge were both called through the sonnet alias.

For the 0.18.0 series the alias resolved to Claude Sonnet 5. Three full runs scored 100 · 100 · 98 of 101. The median case took about 13 turns, 11 tool calls and 2,300 thinking tokens.

A few days later the 0.18.2 tag measured 92 · 96 · 93 of 101. The alias now resolved to Sonnet 5.5, for agent and judge. More telling than the pass count was the session shape: about 6 turns, 4 tool calls and 250 thinking tokens per case. Nothing in the repository explained a change that large. The instrument had changed underneath the test.

I could only see that because every run records more than a score: resolved model IDs, judge-prompt hash, CLI version and session-shape statistics. Without them the obvious reading would have been "0.18.2 regressed the skill", and the obvious response would have been to rewrite the skill. That would have been fixing the wrong thing.

Compare instruments before comparing pass counts. The same alias is not the same instrument.

The floor itself moves

Not even the same resolved model ID is enough. Four days after the 0.17.0 series scored 87 · 88 · 87 of 88, essentially the same skill text on the same Sonnet 5 ID measured 83 · 80 · 81, with the same halved session shape. A counter-run on the previous CLI behaved the same way. The next morning the sessions were back to normal length and the series measured 87 · 87 · 88. I changed nothing in the skill for that evening's failures, and both series stayed in the history. Rerunning until green would have published the instrument's good day, not the behavior of the skill.

This is also where "test on the weakest model" needs a qualification. I used to say: if the skill works on the weakest model, upward only gets easier. That is too simple. Sonnet 5.5 is newer than Sonnet 5, but for this skill it was the weaker reader: fewer steps, referenced files opened far less often. Newer is not stronger for a given skill. So the principle is:

Stabilize the skill on the weakest supported tier, then re-measure when the model inside that tier changes.

One caveat: the "upward gets easier" half is a principle, not something these series measured. They run the agent on Sonnet only. A stronger model can fail differently, for example by doing more than it was asked to, which is one reason hard prohibitions are checked deterministically and not left to a judge.

What the weaker reader exposed

The model change was not only noise. It exposed a structural weakness in the skill.

SKILL.md often named a rule and pointed to a reference file for the operational detail. That works as long as the agent opens the reference. Sonnet 5.5 often did not. In every failing local-lint-auto run the agent installed the linter into a virtual environment, which the referenced setup section forbids. None of those runs had opened that section. The one run that did, passed. Without the reference, the model fell back on a trained habit.

The rule that came out of it:

If missing a rule can cause harm, its operative clause belongs in SKILL.md, not only behind a pointer.

For procedures too long for a clause, the vague "see this reference" became a read-before trigger at the point of action. I rejected both extremes: always reading every reference multiplies the cost of every session, and moving everything into the main file bloats what is loaded on every activation.

The stronger reader had quietly compensated for that dependency. That is exactly why the agent under test belongs on the floor.

Then the judge turned out to be the bigger source of noise

Not every failure belonged to the skill either. One deterministic check had a schema version hard-coded and failed on every later release. One fixture sat under a setting where the behavior it was supposed to test never occurs, and the judge split pass/fail on identical behavior. Two expectation texts demanded things the skill never requires. Expectation texts are specs too: if the case says "must" where the product says "may", the eval is wrong, and rewriting the product to satisfy it means training your implementation against a bug in the test.

The harness stores transcript and disk diff for every run, so the judge can be asked again about the exact same agent behavior without a new agent session. That helper, regrade.py, dates back to the drift evening above. After the switch to 5.5 it became the first step for every failure, because it separates agent variance from judge variance. On one regrade of 15 stored failures, the Sonnet 5.5 judge confirmed only 6 of its own verdicts.

Regrade before reword. If the verdict moves on fixed evidence, you have a measurement problem first.

Eventually I regraded a complete candidate series, 309 stored records, with Opus 5.5 as the judge:

Judge	Run 1	Run 2	Run 3
Sonnet 5.5	98	100	98
Opus 5.5, same transcripts	102	102	102

(of 103 cases each)

The interesting part is not that the number went up. Opus kept all 296 passes as passes. Of the 13 failures it confirmed 3 and overturned 10, among them a "fail" whose own reasoning called the behavior pass-like and a deduction for a write the skill explicitly requires.

That does not make "use the strongest model as judge" a rule. It shows something narrower: for this suite, on these transcripts, Opus was a much steadier instrument than Sonnet 5.5. The method is to compare candidate judges on the same stored evidence and take the cheapest one that is steady enough. Here that threshold landed on Opus. In another suite Sonnet may be enough, or a model from a different vendor may be better.

The judge prompt stayed untouched across the switch, same hash, only the model changed. I rejected the other tempting path, a judge prompt extended for every known failure form. As the project's own rationale puts it:

"The judge should be reliable and not become a product of its own."

One variable at a time is slower. It is also how you learn which layer was actually wrong.

The rules I would carry into another eval project

Record the instrument. Resolved model IDs instead of aliases, judge-prompt hash, CLI version, session shape. A score without its instrument is worth much less than it looks.
Regrade before reword, and check the expectation text before either.
No sentence for a single flip. A new sentence goes into the skill only for a failure form seen twice. Nine sentences added for one-off flips bought no measurable improvement, grew the skill by 17 percent and caused regressions in neighboring cases.
Deterministic guards for deterministic prohibitions. "Do not write under context/" or "never put a secret on disk" is checked mechanically and tolerates zero violations.
A series gate instead of a perfect run. Three full runs and a repeatability rule say more than one lucky 100 percent.
Keep the failed measurements. A series that failed because the ruler changed can be more informative later than another clean one.

Did the thing change, or the ruler?

The 0.20.0 series, Sonnet 5.5 as agent and Opus 5.5 as judge, scored 103 · 104 · 103 of 104 and was the first to pass every line of the suite's release gate. That is a dated result, not the lesson. Case count, agent model, judge model and harness have all changed since the earlier series, so the raw numbers do not compare.

The lesson is the third thing between the system under test and the score: the measuring instrument. The model behind an alias, the CLI, the judge, its prompt, the fixtures, the checks. Any of them can move. So when an eval suddenly gets worse, I no longer start with "what should I change in the prompt?" but with "did the thing being measured change, or did the ruler?" That question has already kept me from "fixing" correct behavior several times.

Be pessimistic about the agent. Measure the judge. Record the instrument.

Keep the Why vs. OKF Agent Memory vs. RepoWise: Three Approaches to Git-Native Project Memory

Oliver Zehentleitner — Tue, 06 Oct 2026 08:44:02 +0000

Rationale, structured knowledge, or codebase intelligence for coding agents?

Three approaches to Git-native project memory for coding agents

"Project memory for coding agents" is becoming a broad category. Three projects are especially interesting because all are repository-oriented, all preserve knowledge beyond individual AI sessions, and all can deal with architectural decisions:

They overlap, but they start from different questions.

Keep the Why preserves rationale.

OKF Agent Memory structures durable knowledge.

RepoWise derives codebase intelligence.

I previously compared Keep the Why with Claude Code Auto Memory, MemoryCustodian, and AgentsRoom. This comparison is different because OKF Agent Memory and RepoWise operate much closer to the repository itself.

A note before going further: I built Keep the Why, so this is not a neutral product review. I am interested in the architectures, their boundaries, and the tradeoffs behind them rather than declaring a winner.

This article is a snapshot from October 5, 2026.

The short version

Keep the Why 0.20.0 is a complete, deliberately narrow rationale system. It preserves the why behind a codebase as Markdown in the repository.

OKF Agent Memory is a broader Git-native knowledge architecture. It structures persistent knowledge and provides dedicated local retrieval over it.

RepoWise is a codebase intelligence system. It indexes the repository, derives multiple intelligence layers, and includes architectural decisions as one of them.

The feature overlap is real. The architectural responsibility is different.

Keep the Why 0.20.0: preserve the part the repository usually loses

A software repository already contains a large amount of memory. Source code tells us what exists, tests describe expected behavior, documentation explains how things work, and Git records what changed.

What is often missing is the reasoning behind all of it.

Why was this architecture chosen? Why is an awkward workaround still there? Which alternative was tried and rejected? Which operational constraint is invisible from the code?

Keep the Why exists only for that layer.

It stores rationale as plain Markdown under context/. The files live with the project and can be versioned, reviewed, branched, merged, and distributed through Git like the rest of the repository.

The key mechanism is capture while the reasoning exists. Keep the Why is an agent skill, so when durable reasoning surfaces during normal development, the agent records it instead of letting it disappear with the session.

The current skill covers continuous capture during development, retrospective recovery from existing evidence, knowledge-transfer interviews, and maintenance of recorded rationale.

With version 0.20.0, I consider that core complete: the problem, boundaries, structure, and fundamental workflow are deliberately stable.

Deliberately narrow

Keep the Why is not a chat archive, task manager, agent orchestrator, vector database, project-management system, or general company knowledge base.

It has one job: preserve the why behind a codebase, including architectural decisions, rejected alternatives, workarounds, incident learnings, and constraints the code cannot explain.

A general memory system asks what information an agent may need again. Keep the Why asks what reasoning would be expensive or impossible to reconstruct later.

That narrow scope is intentional, not a missing feature set.

Why Keep the Why does not record everything

That narrow scope follows from a broader idea: the repository already is most of the project's durable memory.

A typical repository already answers most of the questions an agent needs. README.md says what the project is. docs/ explain how to use and operate it. Tests encode expected behaviour. Build and package files describe how it is assembled. CHANGELOG.md records what changed. Git history records who changed what and when.

Keep the Why deliberately does not duplicate those layers or record every conversation just because it happened.

The missing question is usually different:

Why is it built this way, and what was already tried and rejected?

That is the role of context/.

This is the broader repo-native project memory thesis behind Keep the Why: README, docs, tests, configuration and Git already hold most of the durable what and how. Keep the Why adds the durable why.

That also explains why it is not designed as a session recorder. Session memory remembers what happened in a conversation. Project state records where the project is. Keep the Why keeps only the reasoning that should still matter when the conversation is gone.

The result is intentionally selective: capture less, but keep the part the repository would otherwise lose.

From ADR tool to continuous why layer

Keep the Why grew out of the Architecture Decision Record problem. Classic ADRs are excellent for a small number of major, discrete decisions, but they depend on somebody deliberately writing a record and usually model one decision per file. Keep the Why expanded that idea into continuous, agent-maintained rationale: smaller decisions, rejected changes, workarounds, constraints, and incident learnings captured while the reasoning is present.

The ADR connection is still explicit today. Keep the Why is listed in the Architecture Decision Record community project's tools and resources, while its own ADR comparison describes ADRs as complementary rather than obsolete.

Structure without moving the source of truth

The Keep the Why specification defines stable IDs, status, evidence, sources, relationships, and revisit conditions. A linter checks the mechanical rules locally and in CI.

The read-only dashboard visualizes context/ and Git history without becoming another source of truth. Delete it and the rationale is still there.

The same principle extends across repositories through monorepos, families, nested repositories, external friends, and stable cross-repository links. The Keep the Why Registry adds discovery and backlinks without centralizing the underlying data.

I wrote more about that model in The reasoning behind a codebase, as a web you can walk and The globe: following your reasoning into other people's repositories.

Measured behavior, not only philosophy

Keep the Why also publishes a full eval suite that runs the skill against fresh fixture projects and agent sessions.

A separate controlled rejected-change experiment tested the core claim directly: twenty fresh sessions received the same request to simplify a retry wrapper. Without the recorded rationale, 7 of 10 sessions offered the already-rejected change as an option. With the rationale present in context/, 0 of 10 did, and all 10 of 10 explicitly identified it as already rejected.

It does not prove universal behavior, but it makes the core claim testable rather than purely philosophical.

OKF Agent Memory: persistent structured knowledge

OKF Agent Memory treats the repository as a persistent structured knowledge corpus. Its knowledge/ bundle can contain decisions, facts, observations, processes, research, people, goals, resources, and project-specific concepts.

It implements the Open Knowledge Format, the Markdown-plus-YAML format that originated in Google's knowledge-catalog project. OKF defines the representation; OKF Agent Memory adds the behavior and tooling for persistent agent memory.

Retrieval is part of the architecture

OKF separates compact push memory from a larger pull corpus retrieved when needed. Its local okf tool provides in-memory BM25 search, lookup, validation, graph operations, and mutations, with equivalent MCP tools for search, show, create, update, relate, and validate.

No external database or embedding API is required. Repository-owned text stays canonical while retrieval is derived locally.

Four scopes extend the model beyond one repository: Project, Vendor, User, and System, with project knowledge taking precedence on ID collisions. An optional Hub adds synchronization. OKF Agent Memory is licensed under MIT.

The result is broader than Keep the Why: representation, retrieval, provenance, trust, lifecycle, graph relationships, scopes, and synchronization all belong to the architecture.

RepoWise: derive intelligence from the codebase

RepoWise is primarily a codebase intelligence system. It derives code structure, dependency relationships, Git history, code health, dead-code signals, generated documentation, and architectural decisions, then exposes them through MCP tools such as get_context, search_codebase, get_risk, and get_why.

Unlike the other two, its core product is an additional intelligence model derived from the repository.

Decisions are a first-class layer

The architectural decision layer is what makes RepoWise especially relevant here.

Current decision sources include six index-time lanes: ADR files, inline markers, Git archaeology, PR bodies, code comments, and a harvest during LLM documentation generation. Decisions can also come from coding-agent sessions and manual CLI capture. Earlier CHANGELOG and README mining have been retired.

Session mining exists as a separate source; it is off in the default preset and enabled in the balanced, full, and local_only presets. The older decisions.session_mining key is still read for compatibility, but the current configuration uses sources.session.

RepoWise distinguishes candidates from accepted decisions. Its CLI documentation states:

"A candidate governs nothing. A decision is a candidate a person accepted with repowise decision confirm."

Acceptance is not just a status flip. A candidate needs a reason, a scope, and an evidence reference, otherwise acceptance is refused. The acceptance history is append-only, so granting, reviewing, superseding, or withdrawing authority remains visible.

This is a strong design choice because inferred evidence and governing decisions are not treated as the same thing.

Retrieval, hooks, and semantic search

Accepted decisions are linked to the files they govern and surfaced through get_why. When explicit rationale is missing, RepoWise can fall back to Git archaeology and rationale comments instead of presenting inference as authority.

RepoWise also has proactive agent hooks: editing a governed file can inject a short rationale notice into the agent's context.

Its retrieval combines full-text, graph, and specialized code intelligence. Semantic search is available only when an embedder such as Gemini, OpenAI, or local Ollama is configured; otherwise the vector layer remains empty.

Accepted decisions can be exported to .repowise/decisions.yaml and committed to Git. On import, RepoWise follows a simple authority rule: the file wins; the store is the copy.

That creates a hybrid architecture: accepted decisions can become durable repository data while the larger intelligence model remains derived and indexed. RepoWise's open-source core is AGPL-3.0, with hosted and commercial options.

Three architectures

The simplest way to separate the projects is by data flow.

Keep the Why

developer + coding agent
          |
          v
reasoning surfaces while working
          |
          v
       context/
          |
          v
   Markdown + Git
          |
          v
future agent / human

The agent is the interface. The files are the memory. No retrieval infrastructure is required.

OKF Agent Memory

project knowledge
       |
       v
structured concepts
       |
       v
    knowledge/
       |
       v
 local BM25 / CLI / MCP
       |
       v
      agent

The files remain canonical. A dedicated local retrieval layer helps the agent find and operate on relevant concepts.

RepoWise

code + Git + ADRs + PRs + comments + sessions
                      |
                      v
                RepoWise analysis
                      |
                      v
 graph + git + wiki + decisions + health + index
                      |
                      v
                     MCP
                      |
                      v
                    agent

RepoWise builds a derived intelligence model and exposes that model to the agent.

Side by side

	Keep the Why 0.20.0	OKF Agent Memory	RepoWise
Primary purpose	Preserve software rationale	Persistent structured agent knowledge	Codebase intelligence
Core unit	Rationale entry	Knowledge concept	Derived intelligence / decision record
Scope	Deliberately narrow	Broad and domain-neutral	Broad software-engineering analysis
Canonical project knowledge	Markdown in `context/`	Plain-text OKF bundle in `knowledge/`	Repository plus optional Git-tracked decision manifest
Main capture model	Agent captures reasoning while it happens	Agent creates and maintains structured concepts	Mine, derive, capture, review, and confirm
Retrospective recovery	Explicit workflow	Possible by creating concepts from existing evidence	Strong through repository archaeology
Dedicated retrieval required	No	No external service, but local search is central	Yes, the derived index is central
Local search	Normal file tools	Built-in BM25	Full-text, graph, specialized retrieval, semantic with configured embedder
Database required for core project memory	No	No	Derived local index
MCP required	No	No, optional	Main agent integration
Architectural decisions	Core purpose	One knowledge type among many	One intelligence layer among many
Rejected alternatives	First-class	Representable as structured knowledge	Supported in decision records
Evidence / provenance	Explicit	Provenance and trust metadata	Explicit evidence and acceptance authority
Cross-project model	Families, friends, thoughts	Project, vendor, user, system scopes	Multi-repo workspaces and cross-repo queries
Human-readable without special tooling	Yes	Yes	Decision manifest yes; full intelligence requires RepoWise
External service required	No	No	No for local self-hosted operation
License	MIT	MIT	AGPL-3.0 core, hosted/commercial options
Core idea	Preserve the missing why	Build durable structured knowledge	Derive understanding from the codebase

Capture, structure, reconstruction

A small example shows the difference better than a larger feature matrix.

Imagine a developer and an agent spend an hour simplifying a retry mechanism. The obvious replacement looks good but causes duplicate orders under one specific failure mode. They revert it and keep the existing implementation.

No production code changes. No useful commit. Possibly no pull request.

But the project learned something important.

Keep the Why: capture the learning while it exists

For Keep the Why, the conversation itself contains durable rationale. The agent records what was tried, why it failed, which constraint matters, and when the decision should be revisited.

The valuable artifact is what the project learned, even if no code change survives.

OKF Agent Memory: make it part of durable knowledge

OKF can represent the same learning as a structured decision or related concepts, with provenance, relationships, lifecycle metadata, and retrieval through the knowledge layer.

The information becomes part of a broader persistent knowledge corpus.

RepoWise: connect evidence to governed code

RepoWise is strongest when useful evidence exists in a source it can inspect: an ADR, commit, PR body, inline marker, code comment, session transcript, or manually entered decision.

It can connect that evidence to affected code, track authority and staleness, and surface the decision when the agent touches the relevant files.

These approaches are complementary in an important sense: capture prevents knowledge loss, structure makes knowledge manageable, and reconstruction extracts value from evidence that already exists.

Where the approaches overlap

The boundaries are not absolute. Keep the Why has grown structure and cross-repository relationships around a narrow rationale core. OKF's general knowledge model naturally includes software decisions. RepoWise's derived intelligence now includes rationale, alternatives, evidence, authority, hooks, and a Git-tracked manifest.

RepoWise's proactive decision hooks are especially close to Keep the Why's goal of surfacing rationale before an agent repeats an old mistake. The difference is where the knowledge comes from and which layer is responsible for delivering it.

What happens when the memory gets large?

OKF makes local BM25 retrieval part of the design. RepoWise makes retrieval fundamental to the product through a broader derived index.

Keep the Why currently relies on files, stable IDs, grep, rg, and its indexes. An open scaling issue deliberately waits for real repositories to reveal the limit instead of inventing one.

If retrieval ever becomes a real problem, an optional, derived, disposable local index would preserve the core rule: context/ remains the source of truth. There is no reason to build that infrastructure before the need exists.

"Git-native" means different things here

All three can reasonably describe themselves as Git-native, but they mean different things by it.

For Keep the Why, repository files are the durable memory layer. For OKF Agent Memory, repository files remain canonical while tooling adds retrieval and additional scopes. For RepoWise, Git is both evidence and an integration point: accepted decisions can be tracked there while the larger intelligence model is computed separately.

Which one solves which problem?

If your problem is:

"Our coding agents keep forgetting why this code exists, repeat rejected approaches, or lose reasoning that never became a commit."

That is the problem Keep the Why is designed for.

If your problem is:

"We want a broader structured knowledge architecture for agents, including project knowledge, reusable packages, multiple scopes, and local retrieval."

OKF Agent Memory is closer to that problem.

If your problem is:

"We want agents to understand a large existing codebase, including architecture, history, dependencies, health, decisions, and risk."

That is where RepoWise becomes especially interesting.

These systems could also coexist. RepoWise could index a repository that already contains context/. OKF could hold broader project or organizational knowledge while Keep the Why remains responsible specifically for rationale.

The important question is not whether tools overlap. It is which layer owns which truth.

Conclusion

Keep the Why, OKF Agent Memory, and RepoWise overlap enough to look similar from a distance. Up close, they answer different questions:

Keep the Why: How do we preserve the reasoning behind a codebase without turning it into another platform?

OKF Agent Memory: How do we represent, retrieve, compose, and govern durable knowledge for agents?

RepoWise: How do we derive a useful intelligence model from a codebase and surface it when an agent needs it?

My shorthand remains:

Keep the Why is a complete, deliberately narrow rationale system.

OKF Agent Memory is a general knowledge architecture.

RepoWise is a codebase intelligence system with a sophisticated decision layer.

They optimize for different things. Watching those boundaries evolve is more interesting than forcing all three into one definition of "AI memory."

Links and further reading

Keep the Why

OKF Agent Memory

RepoWise

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! ¯\_(ツ)_/¯

The Globe: Following Your Reasoning Into Other People's Repositories

Oliver Zehentleitner — Fri, 02 Oct 2026 08:22:03 +0000

Keep the Why records why a codebase is the way it is. Decisions can cite decisions in other repositories. The Globe follows those citations outward, one wave at a time, without turning project memory into a centralized service.

A decision rarely stands alone.

We retry three times may exist because the payment provider counts every attempt against our error budget.

We pinned this WebSocket library may exist because the upstream fix has not been released yet.

And sometimes the reasoning behind your decision does not live in your repository at all.

It lives in a sibling package.

An upstream library.

Another service maintained by your team.

Or a project maintained by someone you have never met.

That became increasingly interesting while working on Keep the Why, the open-source project on GitHub.

Keep the Why stores project reasoning as plain Markdown in the repository's context/ directory. Decisions, rejected alternatives, constraints, workarounds and incident learnings stay next to the code they explain.

An entry can also reference another entry.

And that other entry can live in another repository.

Once that existed, something slightly unexpected happened.

The project memory stopped looking like a collection of documents.

It started looking like a graph.

The graph was already there

The Keep the Why dashboard has visualized these relations for a while.

Load a project and you can see its entries, their relations, parent and child repositories, and references to rationale elsewhere. The live graph shows this directly on Keep the Why's own project memory.

Originally, that graph had a natural boundary: the project you opened.

External references appeared at the edge.

But if a decision says:

See: https://github.com/example/upstream#ktw:some-decision-id

then the interesting question is obvious:

What happens if we follow it?

And then follow the references from that repository?

And the references from those repositories?

That is what the Globe does.

Open the Globe

The Globe follows explicit reasoning links across repositories. Click the screenshot to open the live dashboard.

The public graph is still small. We are just starting to connect projects, so right now the Globe is more a demonstration of the model than a map of a mature ecosystem.

That is also why the registry exists: to give this network a place to start growing.

The Globe is not a new database or another memory backend.

It is the same project reasoning, with fewer artificial boundaries.

Follow the reasoning, one hop at a time

The Globe starts with the project you already loaded.

From there you decide how far it should follow external references:

Select the number of hops you want to follow, then press "go" to start loading the next wave.

Hop 1 loads repositories directly referenced by the current project.
Hop 2 follows references found inside those repositories.
The process continues outward, up to ten hops.

Each hop is a separate wave.

That matters because the next wave cannot be known in advance.

To know what repository B references, the browser first has to load repository B.

So before every wave, the Globe pauses and shows what it is about to fetch: which repositories were discovered and how many files that represents.

You can continue or stop there.

There is no background crawler walking the internet.

There is also no reason to load ten hops just because ten are possible.

Often one or two are enough to understand where a decision came from.

And off really means off.

With external loading disabled, the dashboard stays inside the project you opened.

Clear removes what the Globe loaded and leaves your own project family, friends and navigation path intact.

Reload the page and the external graph is gone.

Nothing is persisted between visits.

Repository families travel together

Repositories are not always independent units.

A project may be a suite with several packages, or a parent repository may explicitly declare child projects.

Keep the Why already supports those relationships through parent and children, defined as part of the project format.

The Globe keeps them.

If an external reference reaches one member of a declared project family, the family arrives together and remains connected according to the repositories' own metadata.

That is important because otherwise the graph would create a misleading picture.

A package that belongs to a larger project should not suddenly look like an isolated external dependency just because that happened to be the repository containing the cited decision.

You can also click any loaded project and make it the new centre.

The route you followed remains visible.

So if you started in repository A, followed a decision into B, then discovered C through B, you can still see how you got there.

The graph is not only showing what is connected.

It is showing how you walked through the reasoning.

There is still no server behind it

This was the part I cared about most.

I did not want the graph to turn Keep the Why into the kind of infrastructure it was originally designed to avoid.

There is no central service resolving these links.

There is no account.

No graph database.

No daemon crawling repositories.

No API storing everybody's project memory.

Each repository that publishes a dashboard export already declares where that export lives in its .keep-the-why file.

The export can simply be a static state.json hosted on GitHub Pages or another static host.

When the Globe finds another repository, the browser reads its .keep-the-why at HEAD, finds the dashboard-state location, fetches the export and draws what it contains.

The dashboard server never fetches the other repository.

Your browser does.

That distinction sounds small, but it keeps the architecture pleasantly boring.

The repository remains authoritative.

The published export is only a view of that repository.

And the graph exists because the repositories link to each other, not because a central system reconstructed the relationships afterwards.

A graph does not need all the prose

Following repositories also exposed a very practical problem.

Keep the Why entries contain text.

Sometimes quite a lot of it.

But the graph does not need the full explanation of every decision just to know that entry A references entry B.

Loading all prose for every repository in every wave would waste bandwidth quickly.

So the dashboard export was split.

state.json contains the structure:

projects
topics
entries
fields
relations
links

The actual entry bodies live beside it in:

state.body.json

Those bodies are fetched only when you open an entry.

For a prose-heavy project, that reduces what a graph wave needs to load to roughly a third of the previous size.

It is a small architectural change with a useful property:

The farther you explore, the less unnecessary text you move around.

Then there was one missing direction

Following references works well, but it has a blind spot.

You can discover what your project cites.

You can discover what those projects cite.

But you cannot discover a repository that nothing in your current graph points to.

More importantly, you cannot discover who cites you.

That information exists somewhere out there, but there is no link you can follow backwards to find it.

This is where the Keep the Why Registry came from.

Not as a replacement for the distributed graph.

As a discovery mechanism for the one thing the graph itself cannot do.

The registry is intentionally boring

The registry is a text file in the Keep the Why repository.

One canonical repository URL per line.

That is basically it.

To add a project, you open a pull request and add its repository URL.

A workflow then reads the repository's .keep-the-why, follows its dashboard-state declaration, loads the published export and verifies that the export actually identifies the repository being registered.

The registry therefore stores where to start looking.

It does not store your project memory.

It does not copy your entries.

And it does not even need to permanently store the location of your export.

If you move the published dashboard state later, the next registry build follows the repository configuration again and finds the new location.

Project families work here too.

Register the root project and its declared children arrive through the relationships already stored in those repositories.

If an export temporarily stops responding, it is not deleted immediately either.

It remains listed and marked as unavailable for a month before it is dropped.

Repositories disappear for temporary reasons.

Infrastructure should not turn one bad day into permanent metadata.

The registry is optional

This part matters.

Keep the Why works without the registry.

The dashboard works without it.

The Globe works without it.

Cross-repository references work without it.

Nothing requires a project to join a central list.

The registry only solves discovery.

Tick registry in the Globe and it becomes another wave you can load.

Suddenly you are not limited to projects already reachable from your own references.

You can see the first published Keep the Why projects joining the graph and then explore their reasoning exactly the same way.

Once loaded, there is no special registry graph.

They are just repositories again.

That was the design I wanted.

Centralize discovery where central discovery is useful.

Do not centralize the project memory itself.

It only draws relations that actually exist

A graph can become misleading very quickly if it starts guessing.

So the Globe does not infer relationships from prose.

It does not connect two repositories because they mention the same library.

It does not connect entries because they use similar words.

It does not create a relation because two projects share a topic name.

A connection exists when someone recorded one.

For example through See or Superseded by.

If two projects obviously belong together but no explicit relation exists in their project memory, they appear as separate islands.

I prefer that.

The graph may know less, but what it shows has provenance.

It came from the project records themselves.

The interesting part is not the visualization

The Globe looks nice.

But the visualization is not really the part I find interesting.

The useful part is what happens when reasoning crosses repository boundaries without changing ownership.

Repository A remains authoritative for its decisions.

Repository B remains authoritative for its decisions.

Neither needs to copy the other's rationale.

They can simply point at each other.

Git already distributes the files.

Static hosting distributes the read-only views.

The browser follows the references.

The graph appears as a consequence.

Nobody has to maintain one global knowledge graph containing everybody's project history.

And nobody owns the web of reasoning that emerges between repositories.

A decision three repositories away can still matter to you

There is another consequence of following these links.

A decision is not automatically trustworthy forever just because somebody wrote it down.

Keep the Why already records things such as status, evidence and supersession.

The Globe carries that information across repository boundaries.

So if a chain of reasoning starts from an unconfirmed entry, that remains visible.

If something in the chain is still open, that remains visible.

If a decision gets superseded, that remains visible too.

This becomes particularly useful when the decision is no longer in your own repository.

Imagine your local workaround exists because of an upstream constraint.

Later, the upstream project supersedes that constraint.

Your own code does not magically become wrong.

But the reasoning chain leading to it has changed.

That is exactly the kind of thing worth looking at again.

Not because a graph decided your code is stale.

Because the evidence your decision depended on changed.

Project memory does not have to stop at the repository boundary

When I started Keep the Why, the idea was intentionally narrow:

Keep the reasoning that is expensive to reconstruct close to the code.

Plain Markdown.

Git.

A small convention.

An agent skill that writes and reads it.

The repository remains the source of truth.

Cross-repository links did not change that model.

They made the consequence of it more visible.

Once repositories can cite reasoning in other repositories, project memory no longer has to mean isolated project memory.

It can stay local, independently owned and Git-native while still participating in something larger.

No shared database is required.

No global account is required.

No project has to hand its memory to another service.

The files were already there.

The links were already there.

The Globe just follows them.

Try it

Start with Keep the Why itself:

Open the Globe

Select one or two hops, press Go, and watch the graph expand one wave at a time.

Then load the registry and explore the first projects joining the graph.

The registry explains how discovery works and how to add a project.

The dashboard documentation covers publishing an export and the rest of the graph features.

The complete format is documented in the Keep the Why specification.

If your project already uses Keep the Why and publishes a dashboard, adding it to the registry is one line in a pull request.

If it does not use Keep the Why yet, the installation guide covers all supported methods. The recommended Skills CLI installation currently starts with:

npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why

Then tell your coding agent to initialize Keep the Why in the project.

The reasoning graph is not something you have to maintain separately.

It is a byproduct of projects remembering why they became what they are.

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! ¯\_(ツ)_/¯

The reasoning behind a codebase, as a web you can walk

Oliver Zehentleitner — Wed, 30 Sep 2026 06:10:54 +0000

Decisions that cite each other across repositories — no graph database, no central index, no account. Just Markdown and Git.

Open this before you read on:

keepthewhy.com/dashboard/live/#graph

Give it a few seconds to settle.

Then come back.

It looks like a knowledge graph.

It isn't.

There is no graph database behind it. Nobody maintains nodes and edges. There is no central service collecting project knowledge.

What you are looking at is reasoning that was already sitting in Git repositories as Markdown.

The graph is just what appears when those reasons start citing each other.

What you are looking at

The project in the centre is Keep the Why itself.

Its hubs are topics from context/. Around them are individual entries: decisions, rejected alternatives, workarounds, incident learnings and constraints — things the code can tell you happened, but usually cannot tell you why.

Each entry is an ordinary Markdown section in the repository.

For example:

## Keep dashboard exports read-only

**Id:** <uuid>
**Type:** decision
**Status:** active
**Evidence:** confirmed
**See:** https://github.com/owner/repo — <entry-id> — as of 2026-09-29

**Reason:**
...

**Rejected alternative:**
...

The colour of an entry shows how well its reason is supported. Its shape tells you whether it is still active, superseded, or needs another look.

Git provides the history: who first recorded it, who touched it later, when its status changed.

The dashboard adds none of that information.

It reads what is already there.

That distinction matters to me: delete the dashboard and the project has lost nothing.

Then the graph escaped the repository

The more interesting part is further out.

You will see other projects around Keep the Why.

One is repo-native project memory, the thesis Keep the Why belongs to.

Another is the UNICORN Binance Suite, a family of related repositories.

Nobody added those projects to a graph configuration.

They appear because an entry in one repository cites an entry in another.

That citation is still just text:

**See:** https://github.com/owner/repo — <entry-id> — as of 2026-09-29

The entry ID is stable. A heading can be reworded, a topic file can be split, and the reference still identifies the same piece of reasoning.

Once those references existed, something unexpected became possible:

the reasoning of several repositories could be viewed as one connected structure without moving any of it into a central store.

Family, friends, thoughts

I ended up with three different kinds of connection.

They sound informal, but the distinction turned out to be useful.

Family: where does this reasoning belong?

A family is a group of projects that belong together.

A backend, frontend, shared library and infrastructure repository may all be parts of one product.

The family describes that structure and, importantly, gives the agent routing information.

If a decision belongs to the shared library, it gets recorded there.

If it applies to the whole product, it belongs higher in the family.

The other repositories cite it instead of copying it.

That sounds like a small rule, but it avoids one of the ugliest problems in multi-repository documentation:

five slightly different copies of the same decision.

The reasoning has one owner.

Everything else can point to it.

Families can nest, so the same idea still works for a suite containing a cluster containing another project.

Friends: what does this project relate to?

Not every relationship means two repositories belong to the same system.

Any Keep the Why entry can cite an entry in any other repository.

Those repositories are friends.

Nothing is routed between them.

Nothing is merged.

They simply know about each other because their reasoning crossed paths.

A friend may be one repository or an entire family.

The dashboard follows those references and shows the relevant entries on both sides.

That is why the graph around Keep the Why contains projects that were never configured as part of Keep the Why itself.

They are there because the data says they are related.

Thoughts: how do the reasons connect?

This is the part I find most interesting.

An entry can cite an earlier entry with See, or say that another entry superseded it.

Once several of those links line up, they form a chain:

incident
   ↓
constraint discovered
   ↓
architecture decision
   ↓
later workaround
   ↓
replacement

Keep the Why calls such a chain a thought.

Nobody writes a thought.

There is no thoughts.md.

The individual decisions were recorded when they happened. Their references are enough for the chain to emerge later.

And importantly, a See link does not claim formal causality.

It says these pieces of rationale are related — often that one followed from the other, but not necessarily.

So a thought is not a proof.

It is a trail through the project's recorded reasoning.

Open Thoughts in the dashboard and you can read one from beginning to end, with every entry in full, even when the chain crosses repository boundaries.

The web is deliberately incomplete

There is an important limitation here.

There is no global Keep the Why index.

No service knows every repository that has ever cited yours.

From one project, the dashboard can see what that project points to.

Its friends form the first neighbourhood.

Click one and you can walk there, making it the new centre. The path you walked remains visible, so you can move back through the reasoning the same way you came.

Thoughts can go further.

If a chain continues into another repository, the dashboard says so. Ask it to continue and it loads exactly the repositories needed to follow that chain, hop by hop.

What it does not do is crawl every project reachable from every project.

That is intentional.

Each repository remains responsible for publishing its own state.

There is no central graph to submit your project's reasoning to.

The web exists because projects link to one another, not because a platform owns the web.

That also means there are things it cannot know.

If some repository elsewhere cites the newest entry in your chain, but you have never loaded that repository, there is no magic global backlink index that can tell you.

I prefer that limitation to needing one.

Once reasoning has links, you can ask different questions

At first I built the dashboard mostly because I wanted a quick way to understand what was already in context/.

Then the references made new questions possible.

One is:

Which chains of reasoning started from something nobody ever confirmed?

Every entry carries an evidence level.

If the first step of a thought is only inferred or unknown, every later decision may still be perfectly reasonable — but the chain started from an unconfirmed reason.

The Thoughts view can now surface those origins.

Another question is:

What later reasoning is connected to something we no longer trust?

Suppose an old assumption becomes needs-review.

The interesting part is not only that one entry.

What came after it?

Which later decisions link back to it?

Do those relationships cross into another repository?

The dashboard can show the later entries linked after that point and the projects they live in.

It still does not claim those decisions are wrong.

A link records a relationship, not a theorem.

But it tells a human where to look.

There are other shapes hiding in the same data:

places where many thoughts start;

entries several thoughts pass through;

chains that evolved over months;

decisions that were superseded but are still being cited.

None required another documentation process.

They became visible because the original reasoning was recorded once, with identity and relationships.

The graph is not the product

This distinction is important.

Keep the Why does not ask developers to maintain a graph.

The actual workflow is much more boring.

You work with a coding agent.

During that work a real reason surfaces:

an architectural decision,
an alternative that lost,
a workaround whose purpose is not visible from the code,
a production constraint,
an attempted change that gets abandoned.

The agent records it in context/.

Git versions it with the code.

A later session reads it before repeating the same discussion.

That is the product.

The dashboard is only a lens over the traces this process leaves behind.

And that is probably why I like the graph now more than I expected to.

I originally considered the dashboard almost secondary.

The value was in the agent using the reasoning.

It still is.

But the dashboard makes something visible in twenty seconds that is harder to explain in twenty paragraphs:

a project is not just a collection of files.

It is the result of a long sequence of decisions.

And once those decisions keep their reasons and can refer to one another, you can actually see that sequence.

Try it on your own project

Everything behind the page remains plain Markdown in context/, versioned by Git beside the code.

The dashboard only reads it.

pip install keep-the-why-dashboard
ktw-dashboard

Or export the whole view as a static page and publish it with the project's documentation.

No Keep the Why account.

No graph database.

No central memory service.

No new source of truth.

Just the reasoning the repository already carried — connected strongly enough that you can finally walk through it.

Keep a Changelog records what changed.

Keep the Why preserves why it changed.

And now you can see how those reasons connect.

Keep the Why · Live dashboard · Thoughts · Dashboard explained · GitHub

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! ¯\_(ツ)_/¯

Session memory is not project memory. It fixes the same complaint.

Oliver Zehentleitner — Thu, 24 Sep 2026 10:55:58 +0000

"My coding agent forgets everything between sessions." Two different things answer that, and they are not competing.

The most common complaint about coding agents is the same on every forum: a new session starts from nothing. The explanation you gave yesterday is gone, the decision you made together is gone, the wrong turn the agent took and you corrected is gone, and tomorrow it proposes it again. Everyone who has worked with an agent for more than a week knows the feeling.

Two different things answer that complaint. They get compared as if they were rivals, and they are layers.

Session memory: what the agent keeps for itself

Claude Code's auto memory is the clearest example, because it is built in and on by default. As it works, Claude writes notes for itself: your role and preferences, corrections you gave, project context it can't derive from the code, ongoing work, decisions, and references to things outside the repository. The notes live in a directory on your machine, one per repository, and the first part of the file is loaded into every session. No setup, nothing to decide.

Three properties define it, and none of them is a flaw:

It belongs to one person on one machine. The directory is under your home, not in the repository. A teammate's clone does not have it. Your second laptop does not have it. That is by design: a memory that holds your preferences and your corrections should not automatically travel with the code.
It belongs to one tool. The notes are Claude Code's; Codex, Cursor or Copilot on the same repository do not inherit them.
It is not reviewed with the code. You can inspect and edit the memory, but it is not part of the repository's normal Git and pull-request review flow.

This is the right shape for what it holds. Your preferences are yours. A note like "keep explanations short unless I ask for detail" is between you and your agent. Nobody needs that in a shared project file.

Claude Code also has repository-level CLAUDE.md and AGENTS.md files. Those are shared project instructions rather than auto memory: rules, workflows, architecture and things Claude should do. They can contain rationale too, but rationale is not their dedicated job. The distinction here is specifically between Claude's local auto memory and a repository-native rationale layer.

The complaint session memory answers is: the agent forgot what I told it.

Project memory: what the repository keeps for everyone

A repository already is a project's memory, and has been for decades. The README says what it is, the docs how to use it, the tests what it must do, the changelog what changed, the history who changed it and when. Whoever has the clone has all of it, in every tool, on every machine, reviewed in every pull request.

What the classic layout never had a clear place for is the why: the decision, the alternative that was rejected and the reason it lost, the constraint the code doesn't show, the workaround that must not be cleaned up. That reasoning used to live in people's heads, and left with them.

Keep the Why is the convention and the agent skill for that layer: the agent writes the reasoning into context/ as it comes up in the session, as Markdown, committed with the code.

Three properties again, and they are the mirror image:

It belongs to the project. It is in the repository, so the clone carries it. Your teammate's agent can read the same file yours wrote.
It belongs to no tool. Any agent that can read the repository can read it, and switching tools does not remove the information.
It is reviewed. The why arrives in the same pull request as the code, and a wrong entry is a diff somebody can see.

The complaint project memory answers is: the agent forgot why the code is the way it is.

The same complaint, two answers

"The agent forgets" covers several different losses. Sort them and the answer sorts itself:

What the agent forgot	Which memory answers it
that you prefer short commit messages	session memory: personal, one tool, one machine
what you two did yesterday afternoon	session memory, or `git log`
where the staging dashboard is	session memory as a personal reference, or the README if the team needs it
that the plain retry loop was rejected, and why	project memory, the why layer
that the ugly workaround exists because of a rate limiter	project memory, the why layer
that a teammate's agent already found the migration trap	project memory: it has to reach the other machine

The last three are the ones that come back as production incidents when they are lost.

A session memory may remember those facts locally. What it cannot do by itself is make them shared project knowledge across people, machines and tools.

That is the important distinction.

Why you keep both

The temptation is to pick one. Both directions are wrong.

Putting the why only into a personal memory is where many people start, because it is zero setup. It works until the second person, the second machine or the second tool. At that point the reasoning may still exist, but it is trapped in a memory the rest of the project does not carry.

Putting personal preferences into the repository is the opposite mistake. A shared context/ that holds one developer's habits is noise for everyone else, and a privacy problem on top.

Keep the Why refuses that on purpose: personal settings live outside the project, in the developer's own home directory, and the skill does not record who said what.

So: session memory for what is yours, project memory for what belongs to the project.

Leave auto memory on. Give the repository a why layer.

They may remember the same fact. Only one of them makes it part of the project.

The test

Clone the repository on a machine that has never seen it. Open it with a tool you have not used on it before. Hand it to a colleague.

What is still available to the agent is project memory. What has disappeared was session memory, however good that memory was on your laptop.

The complaint "my agent forgets everything between sessions" is really two complaints, and only one of them was ever about the session.

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! ¯\_(ツ)_/¯

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

Oliver Zehentleitner — Wed, 23 Sep 2026 07:15:56 +0000

Four tools that get called project memory. Three questions sort them. One table, as of September 2026.

"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.

	Keep the Why	Claude Code Auto Memory	MemoryCustodian	AgentsRoom Project Memory
Where it lives	Plain Markdown in `context/` inside each project, committed with the repository. `.keep-the-why` defines the project and its topology	By default `~/.claude/projects/<project>/memory/` on the user's machine; configurable to another local directory	Plain Markdown in `docs/memory/` in the repository, plus optional private local overlays	Server-side, keyed to a project id committed in the repo; the desktop app also keeps a gitignored local cache
Who reads it	Anyone with the clone, the reviewer in the pull request, any agent that can read the repository, and optionally humans through the read-only dashboard	Claude Code sessions that have access to that memory directory; all worktrees and subdirectories of the same Git repository share it	Anyone with the clone, plus supported agents through the skill / CLI workflow	Everyone logged in to AgentsRoom who opens the project and has the project id
Versioned / auditable	Git, alongside the code. Dashboard history is derived from Git	Not by default, unless the configured memory directory is versioned separately	Git, alongside the code, with additional CLI audit and conflict checks	Server-side note history; not Git history
Vendor-independent	Open Agent Skills format and plain Markdown; usable by supporting coding agents without a model-specific data store	Auto memory is a Claude Code feature	Plain Markdown plus a Python CLI and agent integrations for Codex, Claude Code, Gemini and generic agents	Provider-agnostic inside AgentsRoom through its MCP server, but the memory service itself is part of AgentsRoom
What has to run	Nothing continuously. The skill runs inside the coding agent when needed; linter and dashboard are optional. The dashboard server exists only while you run it, or it can export a static page	Nothing extra; built into Claude Code	A Python standard-library CLI / skill when reading, writing, checking, migrating or maintaining memory; no daemon or external server required	AgentsRoom desktop app, an account and its MCP / server path. Agent memory reads and writes require connectivity
Selective loading	`context/index.md` is a deterministic one-line-per-topic index under a fixed 36-heading skeleton; the agent opens only the topic the task touches. Family scope adds routing between related projects	The first 200 lines or 25 KB of `MEMORY.md` are loaded every session; detailed topic files are opened on demand	`manifest.md` routes a bounded context pack through task, path and scope, then loads `brief.md` and only relevant files / areas	`memory_list` returns notes and retrieval cues; `memory_get` fetches individual notes. The app adds fuzzy search over names, cues, bodies and tags
What gets written, by whom	Distilled rationale synthesized by the agent: decisions, rejected alternatives, workarounds, incidents and constraints, with stable UUIDs, Status, Evidence and optional cross-entry references. Superseded entries stay	Claude writes `user`, `feedback`, `project` and `reference` notes for itself. It deliberately skips things it can derive from the codebase	Typed, evidence-backed project memory with stable IDs, Subjects and Facets. Unconfirmed observations go to `inbox.md`; the CLI manages superseding, conflicts, forgetting and migrations	Agent-written notes in `architecture`, `decisions`, `conventions`, `pitfalls` and `features`, updated in place by default, with optional append / edit modes and no confirmation step
Repository topology	Single repo, shared-context mono repo, isolated-context mono repo, multi-repo families and nested repositories. Families can themselves nest	One auto-memory directory per Git repository, shared across its worktrees and subdirectories	Repository-scoped memory with optional area routing inside the repository; the current documented model does not define a multi-repository family topology	One project memory per project, plus Folder, Account and Agent scopes for knowledge that should span projects
Cross-repository model	Family for related projects with explicit routing, friends for independent repositories cited by rationale, and thoughts for chains of cited entries across those projects	No cross-repository relationship model in auto memory	Stable relations exist inside a project's memory, but the current documented model does not define cross-repository citations or a repository graph	Cross-project sharing is handled through Folder, Account and Agent scopes rather than repository-to-repository rationale citations
Human view	GitHub renders the Markdown directly. The optional dashboard adds Git authorship and status history, queues, search, timelines, graphs, family, friends, thoughts and the globe. It remains read-only	`/memory` exposes the files and opens them in an editor; no project-memory graph	Primarily files and CLI / audit output	Integrated Memory library with editor, fuzzy search, wiki-link graph and visual fading of older notes

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! ¯\(ツ)/¯

Keep the Why is not another workflow

Oliver Zehentleitner — Tue, 22 Sep 2026 14:55:22 +0000

Install it, initialize the project, keep coding.

There is a misconception about Keep the Why that I keep running into.

People see a structured context/ directory containing decisions, rejected alternatives, workarounds, constraints and incident learnings and assume there must be discipline behind it.

Someone has to remember what to record.

Someone has to tell the agent when something is important.

Someone has to maintain another documentation system.

That would defeat the point.

Keep the Why is designed so that after a very small initial setup, you keep working exactly as before.

The agent does the remembering.

Install the skill

Keep the Why is an Agent Skill using the open, cross-agent skill format.

For more than 70 supported agents, the recommended installation is documented on the installation page:

npx skills add https://github.com/oliver-zehentleitner/keep-the-why/tree/latest/skills/keep-the-why

There are also installation paths for GitHub CLI, Claude Code plugins, GitHub Copilot CLI, Codex plugins, Cursor, asm and manual installation.

There is no service to deploy. No database. No daemon. No account.

What you install is essentially the instructions that teach your coding agent how to recognize and preserve the reasoning behind a project.

If you start a session after installing the skill, you do not need a separate "load Keep the Why" step. Asking the agent to set it up in the project is enough to activate it.

If the agent session was already running before you installed the skill, tell that session to load Keep the Why once - or point it directly at its SKILL.md. After project setup, the start path handles future sessions automatically. The supported mechanisms are documented under autostart.

Initialize the project

Inside the project directory, follow the short project setup and tell the agent something like:

Initialize Keep the Why in this project.

This explicit request is intentional. Keep the Why does not silently turn itself on just because you installed it. A repository has to opt in once.

The agent then presents the project setup. With the defaults, there is very little to decide.

Among other things, the setup covers:

where the project's why-knowledge should live - context/ by default unless an existing decision location is a better fit
how you want to start capturing project knowledge
proactive capture during normal work
asking before writing only when something is genuinely unclear
no constant questions for issue or ticket references
structural linting where supported and detected
loading Keep the Why automatically in future sessions

The wizard is presented as a list with defaults already filled in where the setup defines them.

You can effectively answer:

defaults

There is a second short list for your personal workflow preferences.

Again:

defaults

And you are done.

This is not a configuration project. It is meant to be something you can set up in roughly the time it takes to explain why you wanted it.

Then forget about Keep the Why

This is probably the most important part.

After setup, there is no Keep the Why workflow. You do not periodically stop coding to document decisions, decide whether something belongs in context/, or tell the agent:

Store this in project memory.

You work with your coding agent normally. You ask it to implement something, debug a production problem, discuss an architectural choice, reject an apparently simpler implementation because of a constraint, or discover why a strange workaround exists.

That reasoning is already happening inside the conversation. Keep the Why's job is simply to stop throwing it away.

With the default setup, the agent proactively notices reasoning worth preserving and captures it while the work happens. If the situation is clear, it does not need to interrupt you. If something important is genuinely ambiguous, it asks.

That is the default.

What actually gets left behind

The result is deliberately boring: plain Markdown in the project.

A real example from the Keep the Why documentation, the file context/retries.md, looks like this:

# Retries

## Why retry_with_jitter isn't a plain retry loop

**Type:** constraint
**Status:** active
**Evidence:** confirmed
**Source:** discovered while considering simplifying it, 2026-07-22

The payment gateway's rate limiter returns 429 with a per-request
Retry-After header. A fixed-delay retry loop would frequently retry
before the limiter resets, causing repeated 429s under load.

**Considered:** replacing it with a plain retry loop, since the wrapper
looked like unnecessary complexity with nothing documenting why.
Not adopted once the Retry-After behavior surfaced during review.

That entry exists because somebody considered simplifying code that looked unnecessarily complicated.

Without the reason, a later agent sees complexity and may propose the same simplification again. With the reason in the repository, the next session can understand why the code looks the way it does without anyone having to retell the story.

That is what "the agent does the remembering" means in practice.

Your agent stops being a goldfish

A coding agent usually enters a repository with an interesting asymmetry.

It has the source code, tests, documentation and Git history, but it does not necessarily have the experience that produced them.

A previous session may have spent an hour discovering why an obvious implementation does not work. The next session sees the same code and happily proposes the same implementation again.

That is the goldfish problem.

Keep the Why puts that missing experience into the repository too.

project/
├── src/
├── tests/
├── docs/
├── context/
├── README.md
└── .keep-the-why

Now a future session can inherit more than the result.

It can inherit the reasoning.

Git already solves the distribution problem

Keep the Why deliberately does not build another synchronization system.

The memory is part of the project. context/ is Markdown. .keep-the-why records that the project has opted in and how it is configured. Both travel through Git like the rest of the repository.

Clone the repository somewhere else and the project memory comes with it. Switch machine and it comes with it. Open another branch and it comes with it. A different developer gets it. A different agent gets it. A different session gets it.

The personal workflow preferences of each developer remain personal, but the actual project knowledge is shared.

There is no memory database belonging to one AI provider and no conversation history that only one person can access.

The project carries the experience with it.

The PR contains the why too

Yes, this means a change can include both:

src/...
context/...

I increasingly think this is a feature, not a cost.

A reviewer normally receives the result of the coding process. The code changed. Maybe some tests changed. But much of the reasoning that led there disappeared with the coding session.

With repo-native project memory, some of that reasoning can arrive in the same pull request.

The reviewer can see not just:

This implementation changed.

but also:

This is why it changed, what alternative was rejected and which constraint mattered.

And the reviewer does not have to be human.

A coding agent can produce a change and capture the reasoning that surfaced while producing it. A review agent can read the same context/ when reviewing the change.

In that sense, context/ becomes a small but useful agent-to-agent communication layer. The coder passes experience forward; the reviewer can challenge it, verify it or notice when the code contradicts it.

And because it is ordinary Markdown in the PR, humans can do exactly the same thing.

Teams accumulate experience instead of isolated sessions

This becomes more interesting with multiple developers and agents.

Normally project knowledge spreads through conversations. One developer discovers something, another learns it in Slack, someone explains it during a call, and an agent discovers it independently three months later. Another agent may repeat the rejected approach six months after that.

Eventually the person who understood the original reason leaves. The code remains. The experience does not.

Keep the Why changes where that experience accumulates. That idea is the core of repo-native project memory.

Not in one developer's head, one agent's session memory or one vendor's conversation database.

In the project.

That means agents and developers working at different times can benefit from each other's discoveries. The knowledge compounds without everyone having to become more disciplined about documentation.

The complete workflow

The initial setup is basically this:

Install Keep the Why
        ↓
"Initialize Keep the Why in this project"
        ↓
Accept the defaults
        ↓
Keep coding

If the current agent session was already running before the skill was installed, load it once in that session first. That is the exception, not the normal workflow.

After setup:

normal development
        ↓
useful reasoning appears naturally
        ↓
the agent notices it
        ↓
context/ is updated
        ↓
Git carries it with the project
        ↓
future humans and agents inherit it

That is the system.

You should not have to become the librarian for your AI agent.

You should not have to remember to preserve the reasoning.

And you should not have to explain the same project history to every fresh session.

Install the skill. Initialize the project. Keep coding.

If Keep the Why requires you to constantly think about Keep the Why, it has failed at its job.

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! ¯\_(ツ)_/¯

Your repository already is your project's memory. One layer was missing.

Oliver Zehentleitner — Mon, 14 Sep 2026 14:37:33 +0000

Every coding agent starts the day as a goldfish. It can read the code, reason about it, and still have no idea why any of it is the way it is. So it proposes the simplification you rejected in March, for the reason you rejected it in March, and you explain it again.

A whole product category has grown around that: project memory for agents. Databases, MCP servers, knowledge graphs, subscriptions. I think much of it starts from the wrong question, because most of the memory already exists.

That is the idea behind repo-native project memory.

It is called the repository.

What a repository already remembers

Look at any well-kept project. README.md says what it is. docs/ says how to use it. tests/ say what it must do. CHANGELOG.md says what changed. CONTRIBUTING.md says how a change gets in. pyproject.toml or package.json says how it is built. AGENTS.md says where an agent should look first. Git says who changed what and when.

That is already a form of project memory: plain files, next to the code, versioned by Git, available in every clone. It has worked for people for decades without a separate platform, and it works for agents for the same reason: anything that can read a directory can read it.

Agents already consume the README, docs, tests and changelog. Increasingly, they maintain them too.

What the repository usually does not preserve systematically is why.

The layer that was missing

Why is the retry loop this complicated? Why does that flag exist? Why must these two steps run in this order? Which alternative was tried and dropped?

That reasoning is produced in every working session, often out loud in the conversation with the agent, and a new session throws it away.

People have long had mechanisms for the big version of this. Architecture Decision Records work well for the handful of important architectural decisions worth documenting explicitly. Commit messages, issues and pull requests can also preserve pieces of rationale.

What was expensive was capturing the hundred small reasons that actually make a codebase what it is. Writing each one down manually often cost more than it seemed worth.

That is the part AI changed.

Not the need for the why, which is decades old, but the cost of capturing it.

The reasoning is spoken anyway. An agent that is already part of the conversation can write it down as a byproduct: short, synthesized, in a fixed form, committed with the code it explains.

Sometimes there is only a reason and no code at all. A change is started, investigated and abandoned once the reason not to make it becomes clear. No resulting diff, commit or PR necessarily records that dead end.

A context/ entry can.

So the missing layer is one more part of the same repository. It lives where the rest lives, travels with every clone, appears in the pull request next to the code diff, and goes through the same review.

No account. No daemon. No database.

Does it change anything?

I measured the abandoned-change case, because that is the one I cared about.

Twenty fresh agent sessions received the same codebase and the same request: simplify this retry wrapper. Ten had a context/ entry recording why the wrapper looks the way it does and what had already been rejected; ten did not.

Without the entry, seven of ten offered the already-rejected simplification again.

With it, all ten found the entry and none did.

The Markdown file did not make the agent smarter. It gave it one piece of project history the code itself could not provide.

This also matches a broader lesson from my agent and model evaluation matrix: whether useful context is found and applied depends on the whole agent harness, not only on the underlying model.

Where this is thin

A repository holds knowledge; it becomes useful memory only to the degree that its structure makes that knowledge findable. At hundreds or thousands of entries, that becomes a retrieval problem.

The layer also stays empty unless something fills it. And context/ is not an established convention, so today an agent has to be told that it exists and when to use it.

A linter can check whether an entry has the right structure. It cannot check whether the reason is true. A confidently wrong why can be worse than none.

And much of the why never reaches the repository at all. It remains in chat, tickets, meetings and people's heads.

This is a documentation discipline with an agent as the writing hand, not a memory subsystem.

It wins on ownership, review and longevity.

It loses where nobody reads.

Where to go from here

The argument, including the model and its limits, is on one page: repo-native project memory.

It is a thesis, not a product, and it would hold for any implementation of the layer.

The implementation I use is Keep the Why: an agent skill and the file convention it maintains, a linter for the structure, and a dashboard to inspect it. The background and motivation are also covered in Keep the Why: Project Memory for Humans and AI Agents.

It is the why layer of repo-native project memory, and it does not claim to be more than that.

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

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! ¯\_(ツ)_/¯

picows in UNICORN Binance WebSocket API: Up to 2 the Throughput, Opt-In for Now

Oliver Zehentleitner — Sun, 13 Sep 2026 16:12:30 +0000

UNICORN Binance WebSocket API (UBWA) has used websockets since day one.

Since UBWA 2.16.0, you can switch a manager instance to picows, a Cython WebSocket implementation.

For typical Binance messages below ~1 KB, picows delivers roughly 1.7–2× the throughput with significantly lower CPU cost. At normal trading-bot message rates, however, you probably won't notice a difference.

The performance is there. The long-term production history isn't — yet. That's why picows is opt-in for now.

Why picows?

websockets is a very good pure-Python library. For a few hundred messages per second it is nowhere near the bottleneck.

But UBWA is also used for hundreds of depth@100ms subscriptions, multiplexed connections and local depth caches processing every diff. At those rates, per-message overhead starts to matter.

picows moves much of the WebSocket protocol handling into Cython.

It also provides a picows.websockets compatibility layer with the familiar API: connect(), recv(), send(), close() and matching exceptions.

That made the UBWA integration small.

Switching libraries

One parameter:

from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com"
)

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    websocket_library="picows"
)

picows is optional:

pip install --upgrade "unicorn-binance-websocket-api[picows]>=2.16.0"

Streams, WebSocket API, userData streams, subscribe/unsubscribe, reconnects, signals and proxies use the same UBWA code path.

There is also no silent fallback.

If you select "picows" without installing it, UBWA raises ImportError. Unknown values raise ValueError.

If a bot says it is running on picows, it should actually be running on picows.

Benchmark

The benchmark runs both libraries through the full UBWA stack against a local server sending Binance-shaped messages.

Python 3.13, websockets 16.0, picows 2.1.3, x86_64 Linux, output_default="raw_data", median of three runs:

Scenario	~msg size	websockets msgs/s	picows msgs/s	speedup	websockets CPU µs/msg	picows CPU µs/msg
aggTrade	0.2 KB	201,912	403,316	2.00x	5.1	2.5
kline	0.3 KB	195,460	371,019	1.90x	5.2	2.9
depth20	1.0 KB	153,187	259,960	1.70x	6.8	4.1
depth diff	9.1 KB	64,172	67,972	1.06x	16.3	15.4
!ticker@arr	453.9 KB	1,768	1,662	0.94x	608.7	641.0
multiplex mix	0.2 KB	180,406	334,188	1.85x	5.7	3.2

The pattern is simple.

For small Binance messages, picows is clearly faster. Around 10 KB the difference mostly disappears. On the huge 450 KB !ticker@arr payload, picows even comes out a few percent behind. That row turned out to be an artifact of the benchmark, see the next section.

With output_default="dict" and JSON parsing included, the advantage for small messages is still around 1.4–1.7×.

Against live Binance at only a few hundred messages per second, there is effectively no difference. Both libraries spend most of their time waiting for data.

If that is your workload, switching gives you little.

If you push tens of thousands of messages per second through one process, it matters.

The big-message row is a benchmark artifact

The !ticker@arr row is real and reproducible, not noise: a follow-up sweep from 9 KB to 900 KB with ten paired runs per size shows picows 4 to 12 percent behind websockets through UBWA for everything from 32 KB upwards, with a run-to-run spread of only a few percent. It is also an artifact of the benchmark, not of picows. Driven directly, without UBWA, picows wins at every one of those sizes by 1.6x to 2.1x. The difference is how the two libraries drain the socket. The replay server is a firehose on loopback, it never paces, and UBWA's own per-message work on a 450 KB text (a couple of substring scans) is slower than the wire. The kernel receive buffer then autotunes into the megabytes, and picows takes all of it in one recv per loop iteration into a read buffer that keeps doubling: strace counts 79 reads of about 3.4 MB for 600 messages. websockets reads at most 256 KB per recv, about 1060 reads for the same data, and stays cache-friendly. Copying and decoding half-megabyte frames out of a multi-megabyte buffer that has already left the cache costs more per byte than picows saves on parsing. The proof is a one-line change: capping SO_RCVBUF to 128 KB on the client socket flips the 450 KB result to picows 1.3x to 1.4x ahead, with nothing else touched. The benchmark script has a --rcvbuf option for that now, and the full tables are in context/websocket-library.md. On a real Binance connection the socket buffer never fills like that, a WAN link delivers a few megabytes per second at most and the consumer keeps up, which is also what the 24 h soak showed: picows with less CPU and less memory. Thanks to Taras Kozlov, the picows author, for asking the question that led to this.

The benchmark found a UBWA bottleneck first

The first benchmark showed only about 1.4× improvement.

Profiling found why.

UBWA had 18 logger.debug() f-strings formatted for every message even when debug logging was disabled, seven lock acquisitions per message where one was enough, and heartbeat/stop checks running twice.

After removing that overhead:

websockets: 116k → 202k msgs/s
picows: 163k → 403k msgs/s

picows did not suddenly get faster.

UBWA stopped hiding its speed.

The details are documented in context/stream-loop.md.

Why I did not use the native picows API

picows also has a native listener API based on ws_connect() and WSListener.

I benchmarked it too.

On 0.2 KB messages it managed roughly 499k msgs/s versus 485k through the compatibility API. On 9 KB messages the difference was around 13%.

Inside the full UBWA stack that would translate to less than 5% end-to-end.

In return, UBWA would need a second connection implementation of roughly 300–400 lines.

Not worth it.

UBWA stays on the compatibility API.

Failure-path testing found a real bug

Performance benchmarks are easy. Failure handling is more interesting.

The test suite now runs both libraries through scenarios including:

server-side closes and reconnects
fragmented frames
450 KB payloads
messages above max_size
server pings
Unicode
rejected handshakes
WebSocket API round trips
keepalive timeouts

The rejected-handshake test found a real compatibility issue.

When Binance returns HTTP 429 or 404 during the WebSocket upgrade, UBWA reads the status from InvalidStatus.

websockets exposed response.status_code.

picows 2.1.x exposed response.status.

UBWA hit an AttributeError, the stream thread died and nothing useful was logged.

I reported it upstream as tarasko/picows#108.

picows 2.2.0 fixed it the next day.

Proxy support got simpler too

picows 2.3.0 added native HTTP, HTTPS, SOCKS4 and SOCKS5 proxy support.

websockets has supported the same since 15.0.

UBWA previously handled SOCKS5 itself using PySocks and a blocking handshake inside the event loop.

That code is now gone.

UBWA simply passes the proxy URL to the selected WebSocket library:

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    proxy="socks5://user:pass@127.0.0.1:9050"
)

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    proxy="http://127.0.0.1:3128"
)

Both libraries now support:

http://
https://
socks4://
socks5://

The old socks5_proxy_server parameters still work and are converted internally.

Testing also found two UBWA issues in the old proxy path:

rejected SOCKS5 credentials could kill a stream thread without a useful log message
TLS certificate verification was not actually enabled on the proxy path despite the option defaulting to True

Both are fixed.

One difference remains: websockets currently does not URL-decode proxy credentials such as p%40ss, while python-socks/picows does. I reported that as python-websockets/websockets#1761.

UBWA rejects affected credentials up front when using websockets instead of entering a reconnect loop.

REST requests used for listenKey handling still follow SOCKS5 proxies only; HTTP(S) proxy support there is tracked in unicorn-binance-rest-api#139.

The performance and soak tests below were run with picows 2.1.3. During integration, 2.2.0 fixed the handshake compatibility issue and 2.3.0 added native proxy support. That is why UBWA requires picows 2.3.0.

24 hours against live Binance

Local tests do not tell you what happens after hours of reconnects, traffic spikes and memory allocation.

So both libraries ran for 24 hours in parallel against binance.com with identical subscriptions.

Load:

!ticker@arr
!miniTicker@arr
aggTrade
trade
depth20@100ms
kline_1m
bookTicker
depth@100ms

across up to 50 USDT markets.

Host: 8 cores, 12 GB RAM, Python 3.13.5.

	picows	websockets
Messages / data	138.8 M / 49.9 GB	137.9 M / 49.7 GB
Avg / peak msgs/s	1,606 / 8,260	1,596 / 7,695
RSS start → end	62 → 126 MB	63 → 149 MB
CPU avg	9.5 %	12.8 %
Reconnects (arr / markets / depth)	2 / 80 / 2	2 / 88 / 2
Reconnect duration	5–6 s	5–6 s
Max seconds without data	5 s	5 s
Errors / stalls / unrepairable streams	0 / 0 / 0	0 / 0 / 0

138 million messages later: no picows-specific failure, about 26% lower average CPU usage and 23 MB less RSS at the end of the run.

The high reconnect count on one stream occurred almost entirely during a four-hour high-load window.

Both implementations disconnected in the same seconds with keepalive ping timeouts and recovered within five to six seconds.

That strongly points to a shared external or workload-related cause rather than either WebSocket implementation.

Memory rose during traffic peaks and then remained flat for the final hours despite further reconnects.

No sign of a reconnect leak.

Why websockets is still the default

Because 138 million messages and a 24-hour soak are good evidence.

They are not the same as thousands of users running picows for months on different systems.

The compatibility layer is younger than websockets, and issue #108 already showed that small API differences can matter.

So for now:

websockets remains the default. picows is opt-in.

If picows holds up across enough real-world setups, the default can flip later.

The switch will remain either way.

Try it

pip install --upgrade "unicorn-binance-websocket-api[picows]>=2.16.0"

from unicorn_binance_websocket_api import BinanceWebSocketApiManager

ubwa = BinanceWebSocketApiManager(
    exchange="binance.com",
    websocket_library="picows"
)

ubwa.create_stream(
    ["aggTrade", "depth20@100ms"],
    ["btcusdt", "ethusdt", "solusdt"]
)

Run your workload with both libraries and compare CPU and memory usage.

If you have numbers, edge cases or failures, post them in issue #477.

That feedback will decide whether picows becomes the default.

The reasoning behind these decisions — including the native picows implementation I chose not to build — lives next to the code in context/, maintained with Keep the Why.

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! ¯\_(ツ)_/¯

One Index, Many Writers: Avoiding Git Merge Conflicts with Deterministic Write Areas

Oliver Zehentleitner — Wed, 09 Sep 2026 18:37:10 +0000

While working on Keep the Why, I ran into a very ordinary Git problem.

There is one shared context/index.md.

Developers and coding agents can add new context files in different branches. The changes are unrelated, but they are not written back to the repository at the same time. Git has to merge them later.

That is where things get interesting.

Imagine two branches.

One adds:

billing.md

Another adds:

caching.md

Both also update context/index.md.

If new entries are simply appended to the end of the file, both branches modify the same place.

Git sees overlapping changes.

Merge conflict.

The conflict is not semantic. Nobody disagrees about the content. It only exists because several writers use the same file and their changes are integrated later.

This came up in Keep the Why issue #194.

Alphabetical sorting helps, but not enough

My first thought was simple: stop appending new entries and keep the index alphabetically sorted.

That already spreads changes across the file.

But especially with a small index, it does not solve the problem.

Suppose the index contains only:

architecture
deployment

One branch adds:

billing

Another adds:

caching

Both additions belong between the same two existing lines.

So even though the entries are different and correctly sorted, Git can still see both branches changing the same area.

The interesting part is that this problem is actually worse while the index is still small.

With only a few existing entries, there are only a few natural places where Git can anchor an insertion. New entries therefore have a relatively high chance of landing in the same gap.

As the index grows, this usually improves by itself.

More existing entries create more separation points:

architecture
billing
caching
deployment
logging
monitoring

A new entry is now much more likely to land in its own area.

So the main problem is not a large index.

It is a sparse index with several delayed writers.

Creating the structure before it is needed

The solution I implemented is simple.

Every new index starts with fixed sections:

## 0
## 1
## 2
...
## 9

## A
## B
## C
...
## Z

All 36 sections exist from the beginning, even when they are empty.

A topic is inserted below the section matching the first character of its filename.

For example:

billing.md     -> B
caching.md     -> C
deployment.md  -> D

The important part is not really the alphabet.

The important part is that the write areas already exist before concurrent branches need them.

Instead of every new entry competing for one append position, changes are distributed across predefined parts of the file.

The headings become stable merge anchors.

In other words, the index gets some structure early instead of waiting for the content itself to create enough structure later.

A useful side effect for coding agents

The original problem came from Git.

But the fixed structure also makes the index nicer for agents.

An agent does not have to treat index.md as one unstructured Markdown block. It can search predictable sections and narrow the retrieval area before reading more context.

So the same structure gives two benefits:

Git gets stable places for independent changes to land.
Coding agents get predictable places to search.

That was not the original reason for the change, but it fits the way Keep the Why is supposed to work: simple, deterministic retrieval first, deeper reading only when necessary.

What I like about this solution

There is no database.

No locking.

No generated index.

No merge driver.

No additional service.

Just a little bit of structure added before it is actually needed.

The funny part is that once the index becomes larger, the entries themselves increasingly provide the separation Git needs. The fixed 0-9 and A-Z sections are mostly there to make the early and sparse state behave better.

It is a small change, but I like the general lesson behind it:

When many independent writers modify one Git-managed file, avoiding conflicts can be less about smarter merging and more about designing where changes are allowed to land.

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! ¯\_(ツ)_/¯

What happens when a coding agent forgets why a change was rejected?

Oliver Zehentleitner — Tue, 08 Sep 2026 14:16:02 +0000

Coding agents are pretty good at understanding code.

But a fresh session usually does not know which ideas were already investigated, tested and rejected. If the rejected idea left no code change behind, Git has almost nothing to show.

So I wanted to see what difference a tiny piece of project memory actually makes.

A small test

I built a tiny repository around a retry wrapper for a payment gateway.

The code handles 429 responses using the gateway's Retry-After header, plus exponential backoff and jitter.

It looks a bit more complicated than a plain retry loop, so it is exactly the kind of code an agent might want to simplify.

The important part: a simpler version had already been considered and rejected because retrying before the limiter reset caused more 429 responses under load.

Then I created two copies of the repository.

In the first one, there was no explanation.

In the second one, I added a small Markdown file:

context/retries.md

It explained the rate-limiter behavior and said that replacing the wrapper with a plain retry loop had already been tried and rejected.

Everything else was identical.

For these runs, Keep the Why was installed project-scoped and loaded in all 20 sessions through Claude Code's SessionStart hook. The skill then uses the repository's context/index.md to find relevant project context such as context/retries.md.

Then I started ten fresh Claude Code sessions against each repository and gave them the same prompt:

This retry wrapper looks over-engineered. A plain retry loop would do the same thing. Simplify it.

The experiment uses the same isolated fixture machinery as the public Keep the Why eval runner. The raw transcripts, diffs and per-run grades are published as well, so the numbers below can be checked instead of taken on faith.

The interesting result

I expected at least one control run to break the retry behavior.

That did not happen.

The agent was more careful than that.

All ten control sessions noticed that Retry-After mattered. The few that changed the function preserved the important behavior.

But they still had a problem:

they had no way to know that the simpler approach had already been investigated.

Seven of the ten control sessions ended up offering the rejected simplification as a valid option again.

That makes sense from the agent's perspective. The repository contained no evidence that anyone had already tried it.

With the context file, the behavior changed completely.

All ten sessions found the rationale.

All ten understood that the requested simplification had already been rejected.

None of them put the bad idea back on the table.

The treatment runs were also noticeably faster: the median wall time dropped from 43 seconds in the control group to 18 seconds with the recorded rationale.

I would not generalize that number from such a small experiment, but the reason is straightforward: without the context, the agent first had to reconstruct the decision from the code. With it, the session could start where the previous one had ended.

That was the interesting part for me.

The Markdown file did not make the agent smarter.

It simply gave it one piece of project history that the code itself could not provide.

Code is not the same as decision history

The control sessions were actually pretty good.

They inspected the implementation and understood why Retry-After, backoff and jitter might matter.

Several even noticed that the repository did not explain whether the complexity was intentional.

And that is the important distinction.

Code can often tell you what is happening.

Sometimes it even lets you guess why.

But guessing the reason is not the same as knowing that somebody already investigated an alternative and rejected it.

Rejected changes are project knowledge too

Some very useful engineering knowledge comes from things that never made it into the code:

a refactor that broke an external integration;
a dependency that looked replaceable but was not;
an optimization that made performance worse;
a workaround that should not be "cleaned up";
a migration approach that was investigated and abandoned.

If the final result is "leave the code as it is", Git has very little to record.

Humans often keep that knowledge in their heads.

A fresh coding-agent session does not have that context.

This is the idea behind Keep the Why

Keep the Why keeps this kind of reasoning directly in the repository.

The format is intentionally boring:

context/
├── index.md
├── architecture.md
├── retries.md
└── deployment.md

Plain Markdown. Versioned with Git.

No database. No daemon. No RAG system.

Humans can read it, coding agents can read it, and the reasoning travels with the repository.

For me, this is less about "AI memory" and more about project memory.

If we tried something and rejected it, that is useful project knowledge.

If strange code exists because production behaved in a surprising way, that is useful project knowledge too.

What I took away from it

This was a small experiment: twenty runs, one function and one model family.

So I would not turn the numbers into some universal benchmark.

But the behavior was clear.

Without recorded rationale, the agent had to rediscover the same decision.

With it, the next session could start where the previous one ended.

That is basically the whole idea:

Don't make the next developer — human or AI — rediscover the same dead ends.

Sometimes the most important thing to preserve is not what changed.

It is why nothing changed.

Keep the Why is open source:

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! ¯\_(ツ)_/¯

DEV Community: Oliver Zehentleitner

Keep the Why vs. past.dev vs. Agent Memory Repo vs. agentmemory

The table

One example

Where the others are better

Where Keep the Why is weaker

What Keep the Why doesn't do, on purpose

Beyond one repository: a web of context

The part that is true of all four

The Model Changed. My Skill Didn't. The Score Still Dropped.

The day the score dropped without the skill changing

The floor itself moves

What the weaker reader exposed

Then the judge turned out to be the bigger source of noise

The rules I would carry into another eval project

Did the thing change, or the ruler?

Further reading and raw material

Keep the Why vs. OKF Agent Memory vs. RepoWise: Three Approaches to Git-Native Project Memory

Three approaches to Git-native project memory for coding agents

The short version

Keep the Why 0.20.0: preserve the part the repository usually loses

Deliberately narrow

Why Keep the Why does not record everything

From ADR tool to continuous why layer

Structure without moving the source of truth

Measured behavior, not only philosophy

OKF Agent Memory: persistent structured knowledge

Retrieval is part of the architecture

RepoWise: derive intelligence from the codebase

Decisions are a first-class layer

Retrieval, hooks, and semantic search

Three architectures

Keep the Why

OKF Agent Memory

RepoWise

Side by side

Capture, structure, reconstruction

Keep the Why: capture the learning while it exists

OKF Agent Memory: make it part of durable knowledge

RepoWise: connect evidence to governed code

Where the approaches overlap

What happens when the memory gets large?

"Git-native" means different things here

Which one solves which problem?

Conclusion

Links and further reading

Keep the Why

OKF Agent Memory

RepoWise

Related articles

The Globe: Following Your Reasoning Into Other People's Repositories

The graph was already there

Follow the reasoning, one hop at a time

Repository families travel together

There is still no server behind it

A graph does not need all the prose

Then there was one missing direction

The registry is intentionally boring

The registry is optional

It only draws relations that actually exist

The interesting part is not the visualization

A decision three repositories away can still matter to you

Project memory does not have to stop at the repository boundary

Try it

The reasoning behind a codebase, as a web you can walk

What you are looking at

Then the graph escaped the repository

Family, friends, thoughts

Family: where does this reasoning belong?

Friends: what does this project relate to?

Thoughts: how do the reasons connect?

The web is deliberately incomplete

Once reasoning has links, you can ask different questions

The graph is not the product

Try it on your own project

Session memory is not project memory. It fixes the same complaint.

Session memory: what the agent keeps for itself

Project memory: what the repository keeps for everyone

The same complaint, two answers

Why you keep both