Brain Maintenance & Health

A Brain that ages memory instead of hoarding it forever

BrainMaintenanceService runs periodically and does real housekeeping, not just cleanup: 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.

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.

Continue