Skip to content

Maintaining a Hadron memory

Adding nodes is the easy half. The hard half is keeping them true after the reality they describe starts to move. A memory that silently goes stale is worse than no memory: agents read the wrong thing with full confidence. This guide is about upkeep — catching drift, correcting in place, and pruning what nothing reads.

If you're still populating a memory, start with Adding nodes to a memory. Come back here once it's in use and the underlying reality is changing under it.

The three ways a node goes bad

Maintenance is easier once you can name the failure you're looking for. There are three, and they need different detection.

Failure mode What it looks like How you find it
Stale-but-used A frequently-read node that no longer matches reality. Validate high-usage nodes against ground truth. Usage tells you frequency, not correctness — a popular node can be quietly wrong.
Should-have-fired-but-didn't A node whose trigger drifted, so it no longer matches the task it governs. Downstream symptoms. It logs zero usage — indistinguishable from "correctly irrelevant", so usage data is blind to it. A check or review catching something a node should have prevented is the signal.
Dead/unused Nodes nothing reads. Low/zero usage over time — prune candidates.

The middle one is the trap. Because a node that never fires and a node that's correctly irrelevant look identical in usage data, you can't detect a drifted trigger by watching the graph — only by noticing that something the node should have caught slipped through.

The practices

Maintain at the moment of work

The highest-quality correction happens while you're doing a real change, grounded in concrete before/after — not in a separate cold-review shift. When you touch code (or whatever the memory describes) and notice a node that no longer matches, fix it then. You have the ground truth in front of you and you know exactly what changed. A scheduled "review the memory" pass weeks later has neither.

Validate against an independent ground truth

The question is always "does this node still match what the thing it describes actually does?" — checked against that thing (the code, the API, the recent diffs), not against what you remember being true. Validating a node against your own memory just re-certifies your own blind spots. If the node claims a function returns X, read the function.

Triage by usage to keep cost bounded

You can't re-read everything on every change, and you don't need to. Use node and edge usage to decide what to validate (the frequently-read nodes, where a mistake does the most damage) and what to prune (the nodes nothing reads). This keeps maintenance proportional instead of open-ended.

Tooling status

Usage-based triage depends on node/edge usage recording, which is evolving — see Tooling status below. Where the signal isn't available yet, fall back to validating the nodes you happen to touch during real work.

Feed conformance failures back to triggers

When a check catches a violation whose governing node never fired, don't just fix the code — that's the should-have-fired-but-didn't mode, and the real defect is the node's trigger. Fix the trigger so the node matches the task next time. Every such near-miss is free information about where a trigger has drifted.

Prefer checkable conventions

A convention expressed as a runnable check drifts loudly: the check starts disagreeing with the code and someone notices. A convention written as pure prose drifts silently: nothing objects until an agent acts on stale guidance. For anything you need to stay true, bias toward nodes that can be checked — or that point at a check — over prose alone.

The caretaker role

Someone should own stewardship of a shared memory. But the caretaker is a backstop and structural editor — catching slips, keeping the graph coherent, pruning the dead — not the sole author.

If one person is the only one feeding and validating the graph, the memory re-encodes their mental model, and you've re-centralized the very knowledge you were trying to distribute. The people doing the work are the ones with the ground truth; they should be the ones capturing and correcting it. The caretaker curates against the source of truth, not against their own head, for the same reason everyone else should.

Be honest about the cost: maintenance is recurring human work. It's worth measuring — hours spent versus drift prevented — because that ratio is what tells you whether the practice is sustainable, or whether a convention should be turned into a check instead.

Tooling status

Some of this is manual today; some is tooling-assisted and evolving. Treat the split as a moving line, not a fixed contract:

Practice Today
Maintain at the moment of work Manual — a discipline, not a feature.
Validate against ground truth Manual read of the source. hadron_validate / h-validate checks structural and index health (see RAG vector index), not whether content still matches reality.
Triage by usage Node/edge usage recording is evolving; where present it feeds usage analytics.
Feed failures back to triggers Manual — driven by checks/reviews catching near-misses.
Scheduled validation Planned as a step in the Spec Kit integration; not a general feature yet.

As tooling lands, more of the left column moves from "manual" to "assisted." Write your maintenance habits so they survive that shift — lean on the discipline, and let the tools reduce the toil as they arrive.