Module native_memory_retention 

Retention/GC for db_agent_native_memory_versions — closes §7.1 of docs/specs/SPEC_MEMORY_VERSION_CONTROL_AND_ARMORY_AUDIT_2026_08_19.md, left open in v1 (“no pruning is proposed… flag if unbounded growth is a concern”). Operator-confirmed policy (2026-08-22): hybrid age + min-count floor — a version is pruned only once it is BOTH older than MAX_AGE_MS AND ranked beyond the MIN_KEEP most-recent versions for its (agent_id, filename). The floor exists so an agent that rarely touches a given memory file never loses its entire history just because every version happens to be old; the age bound exists so a hyperactive agent’s frequently-rewritten file doesn’t grow unbounded just because every version happens to be recent. See agent_native_memory_versions.rs::agent_native_memory_version_prune for the actual query.

Runs as its own periodic background sweep, started once at server startup alongside native_memory_drift’s detection sweeps (a sibling concern, not the same one — drift detects out-of-band writes, retention prunes old versions regardless of source). Deliberately a much slower cadence than drift detection’s 30s: pruning is housekeeping, not latency-sensitive — nothing is waiting on a stale version’s removal the way a reviewer is waiting to see a drifted write show up.

Constants

MAX_AGE_MS 🔒

Beyond MIN_KEEP, prune versions older than this.

MIN_KEEP 🔒

Keep at least this many most-recent versions per (agent_id, filename), regardless of age.

SWEEP_INTERVAL 🔒

Pruning is housekeeping, not latency-sensitive — once a day is generous enough that growth stays bounded without adding meaningful DB load.

Functions

prune_once 🔒

One pass: prune every (agent_id, filename) pair that has any recorded version history. Returns the number of version rows deleted (for logging; tests assert on it directly). A failure listing targets or pruning one file is logged and does not stop the sweep from covering everything else — matches native_memory_drift’s own per-item error handling.

spawn

Start the periodic sweep. Call once at server startup with the store version history is recorded in. Returns immediately — runs as a spawned background task for the process lifetime (no shutdown handle; srv itself owns the process lifetime, same as native_memory_drift::spawn).