The Half-Life Rule: Agent Memory vs Documentation, From Daily Use

A Hacker News thread with hundreds of comments declared that agents don't need memory plugins, they need documentation. I run a fleet of agents every day, and I have lost real work to missing documentation and to missing memory. Losing work to both sides is why the either/or framing never clicked for me. The split that finally held is simple: route by the half-life of the information.

The rule

Everything a project knows decays, just at different rates. Architecture, setup steps, and interfaces decay slowly. They change through review, on purpose, on a schedule you control. That is documentation: truth slow enough to curate.

Deploy workarounds, environment quirks, preferences that emerged mid-project, and the list of approaches you tried and abandoned decay fast. They are true this week and wrong next month, and nobody schedules a review for them. That is memory: state too volatile to write down, too expensive to re-derive.

Docs hold the slow half. Memory holds the fast half. Most arguments in this debate pick one half and declare the other fake.

What it looks like in practice

One of my agents re-learned the same deploy quirk three times in one week. Each session, it rediscovered that a specific service needs a flag before a restart, and each session it burned twenty minutes getting there. That fact was never going to become documentation. It is boring, it might be obsolete next month, and writing a doc page per quirk would cost more than the quirk does. It belongs in memory, where recall is cheap and local.

The interface contracts those agents code against live somewhere else entirely. They are stable, reviewed, and wrong only when someone deliberately changes them. They live in docs, and nothing in my memory layer is allowed to outrank them.

A new agent joining a project reads the docs on day one and accumulates memory in week one. A new human teammate does the same thing. Nobody calls that confusing.

Where each side is right

The thread's core criticism is fair: memory systems that rank snippets by similarity and replay them as current truth will feed an agent stale facts with full confidence. I want that fixed. But the fix is better memory, such as cheaper recall, clearer validity, and less trust in old state, not deletion.

The pro-docs side is right that documentation is the substrate most agent projects never write. But docs decay the day they are written, and rejected approaches never reach them at all. A README cannot tell an agent which of three refactoring paths the team already tried and hated. Mine knows, because it remembers.

The working split

• Write it in docs if a new teammate must read it on day one and it stays true until someone reviews a change.
• Put it in memory if it is true this week, might be wrong next month, and costs real time to re-derive.
• Keep it in neither if it fails both tests. It was noise.

The next debate about whether agents need memory or documentation is really a debate about which half-life the participants have in mind. Once you start asking "how long does this fact stay true," where to put it stops being a philosophy question. It becomes a routing decision.

This is the personal-ops take. The product-side breakdown of the same HN debate lives on the CodeCora blog.