Brain Maintenance & Health

A Brain that ages memory instead of hoarding it forever

BrainMaintenanceService runs immediately at startup when maintenance is overdue, then every day. It marks stale atoms, archives what's past its useful life, prunes broken links, expires session-local atoms whose window has closed, and — critically — promotes staged traces that proved themselves useful before they could expire. A frequently restarted server therefore cannot postpone maintenance indefinitely.

Quality hygiene: remove residue without erasing ownership

The hygiene pass detects obvious managed residue such as truncated fragments, unbalanced or incomplete captures, code-heavy implementation debris, and legacy harness-import artifacts. Detection is explainable: GET /v1/brain/hygiene/preview returns a score, reasons, and either review or archive for every candidate.

Automatic archival is intentionally narrower than detection. An atom must be managed platform output, old enough to clear the grace period, unpinned, never retrieved, and high-confidence garbage before maintenance archives it. Operator-authored memory, pinned atoms, and anything previously used in dispatch are protected. Operators can apply an explicit reviewed set through POST /v1/brain/hygiene/apply.

Graduation is earned by reuse

A staged, unconsolidated trace graduates to durable, consolidated memory once it's been retrieved into a real dispatch context at least twice, or reinforced once — the practical form of "lazy summarization": something is worth remembering permanently because it kept being useful, not merely because it was said once. Everything the maintenance pass touches is reported back as a concrete count — staleMarked, archived, linksPruned, stagedGraduated, stagedExpired — so this isn't an invisible background process; its effects are auditable per run.

Reclaiming disk, not just marking rows dead

Beyond soft archival, a reclamation pass hard-deletes episodes, links, queue entries, and events that have genuinely aged out — reporting exactly how many rows of each it removed. A Brain that only ever grows would eventually become its own liability; this is the part of the system that keeps that from happening.

Finding contradictions — a daily sweep, plus an immediate check for the highest-stakes case

The same maintenance pass runs a deterministic contradiction sweep over durable atoms: two topically similar memories carrying opposing directives ("always X" vs. "never X") get flagged as a dispute rather than silently coexisting, both retrievable, both confidently contradicting each other. This sweep is thorough but not instant — it walks a bounded batch of recently-updated atoms on the periodic maintenance schedule, so a contradiction can sit undetected for a stretch between passes.

That's an acceptable trade for most memory — but not for a rule. An operator-authored correction is constitutional-tier the moment it's written: it gets injected into every relevant dispatch regardless of query relevance, which means two silently-opposing rules both active is the single most damaging thing that can happen to a workspace's memory. Rather than wait for the sweep, a governing atom is checked against this scope's other constitutional-tier atoms immediately, using the same polarity-and-similarity logic — narrowed to one new atom instead of a full batch, so it's cheap enough to run on every write. The broad daily sweep remains the safety net for everything else.

Continue