Why markdown rot breaks agent memory
Putting agent instructions in the repo is the cheapest way to start. It also fails in the same three ways once the pile grows. Here is what breaks, and what Stele’s record does about each one.
The setup everyone reaches for
You add a CLAUDE.md, an AGENTS.md, or a docs/ folder the agent is supposed to read. Zero new infrastructure. Any harness that can open a file can use it. For a small set of notes owned by one person, that is often enough.
The trouble is not that markdown is bad. It is that a growing set of agent-facing files quietly recreates three failure modes that show up at scale.
Three ways the pile goes wrong
Stale content with no signal
Nothing on the file tells the next agent (or you) whether it is still true. You reverse a decision in code. The old rule stays in the folder. Weeks later an agent reads it, believes it, and rebuilds the thing you tore out. A file has no opinion about what is current.
Exact-match recall
Finding the right note means already knowing what to grep for, or knowing which filename holds it. Miss the keyword and you miss the knowledge. A search subagent makes navigation faster. It does not turn a library organized by filename into meaning-addressable memory.
All-or-nothing loading
When the agent cannot find the right slice, it loads whole files. That is slow to parse and expensive in context. The alternative is hoping the right paragraph was already in the prompt.
What Stele’s record does instead
Stele keeps project knowledge as typed nodes (decisions, lessons, risks, and related kinds) with a lifecycle you choose when you write them. The point is not “more text.” It is a record that can age, retire, and be checked.
On the automatic side, shipped behavior includes:
- Flagging knowledge that has not been verified in a long stretch, so it is not treated as certain by default.
- Expiry dates for facts that were only ever true for a while.
- Retiring a risk or note bound to a task when that task closes.
- Supersession: when a decision replaces an earlier one, the old fact stops being served as truth, stays readable, and ranks below the replacement.
On the deliberate side, agents run a verification sweep (/stele:review) against the code, and a health check (/stele:doctor) that surfaces stale claims, duplicates, and broken links. Freshness (when content last changed) and verification (when someone last confirmed it still holds) are tracked as separate clocks, because “recently edited” is not the same as “still true.”
The honest trade-off
In-repo markdown needs no hosted backend. Stele does. If one person can keep a small folder honest by hand, stay with the file. Reach for a maintained record when agents (and teammates) need the same facts, when reversed decisions must stop being followed, and when “grep harder” is no longer a retrieval strategy.
One more boundary: today the deliberate sweeps run when your agent runs them. Automatic flagging and retirement happen on their own. A fully autonomous background gardener that runs with no one prompting it is on the roadmap, not something this post pretends already ships.