Skip to content

Maintaining a Hadron memory

CLIMCPPortalIntermediate~15 min

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.

Start with a check-up

Ask your AI tool, connected to Hadron, for the signals it can find on its own:

Check the memory acme.com:team-notes for notes whose summary may be out of
date, links that point to nothing, and notes with no description, content or
summary. List what you
find; don't change anything yet.

It comes back with a list: notes whose summary may no longer describe them — the content changed after the summary was written, or the summary was never checked against the content — edges to missing nodes, notes with no description, content or summary (they may still hold structured data), notes whose search indexing failed (so vector search can't find them), and records that don't fit the memory's schema. Treat each as a reason to re-read, not a verdict — a flagged summary may still be accurate, and a clean check says nothing about whether the content still matches the world. That part is the practices below.

On an encrypted memory the summary check can't run — the check doesn't decrypt content — and is reported as skipped, so no summary findings there doesn't mean the summaries are fine.

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. Recent versions of each node are kept — the last 10 by default, set per memory — and you can review them on the node's Revisions tab.
Validate against ground truth Manual read of the source. hadron_validate (the check-up above) flags summaries that may be out of date (content changed since, or never checked), broken edges, nodes with no description, content or summary, schema violations and index health (see RAG vector index) — signals to re-read, not a check that 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.