Storage Lifecycle: Hot State, Cold Evidence

The hot database is for live work

Agentis treats the SQLite database as the hot working set, not an infinite warehouse. Active and waiting runs stay fully hot because the engine may need to resume, inspect, repair, or replay them at any moment. Completed runs, ledger rows, and observability traces are still valuable evidence, but after their retention window they can move out of the critical path.

The default policy keeps completed full run state hot for 7 days, ledger events hot for 30 days, and observability rows hot for 14 days. When the database grows past the hot-size threshold or free disk falls below the safety floor, maintenance tightens those windows temporarily so a test-heavy or automation-heavy workspace does not run away with the machine.

Archiving is lossless before it is destructive

The maintenance worker writes gzip-compressed JSONL archives with checksums first, then removes the archived hot rows only after the archive file lands atomically. If the archive store is disabled or unavailable, the worker skips destructive cleanup rather than deleting evidence it cannot preserve. That is the core rule: reduce hot pressure without hiding or losing what happened.

Archive-aware reads merge hot rows with cold rows for run detail, node history, ledger history, and observability views. A compacted run can therefore load as a small summary in SQLite while still hydrating the original heavy state from the archive when an operator asks for the full story.

Reclaiming space is explicit and observable

New databases enable SQLite incremental vacuum from creation, so deleted pages can be reclaimed gradually instead of waiting for a disruptive full rebuild. The runtime also exposes storage diagnostics under /v1/storage and an authenticated maintenance trigger under /v1/storage/maintenance, giving operators a way to see database bytes, archive bytes, disk free space, largest SQLite objects, and the active retention policy.

Continue