Module lifecycle 

F3 Flagship 3: Lifecycle & forgetting — Stories 3.1–3.4. F3 Lifecycle & forgetting — Stories 3.1–3.4.

Story 3.1 — Active forgetting / compaction policy

forget_brain identifies memories that are simultaneously:

1. Low-usefulness (usefulness_score / use_count <= floor, OR usefulness_score <= floor when use_count == 0).
2. Stale: last_useful_at (or created_at when never cited) is older than min_age_days.
3. NOT evergreen: use_count < protect_use_count (high-traffic memories are protected even if the per-turn ratio is noisy).

Forgetting is archival, not destructive: it calls the existing invalidate_memory path with reason "forgotten/archived", emitting a memory.invalidated event into the event log. A full rebuild_in_place will replay the invalidation and arrive at the same state — rebuild-safe.

The policy is opt-in via [lifecycle] forget_enabled = true in project.toml. The default is false, so existing installs are entirely unaffected until the operator explicitly enables it.

Story 3.2 — Regret-driven review

flagged_for_review returns memories whose retrieval.regret event count (a memory was cited despite having been dropped from the context bundle) exceeds a threshold. These memories are surfaced in brain status and the review list — they are NOT auto-deleted.

Story 3.3 — Proposal-queue hygiene

gc_proposals expires pending proposals older than proposal_expiry_days (via the existing reject_proposal path, reason "expired") and optionally auto-accepts proposals whose proposed_confidence is above proposal_auto_accept_confidence.

Story 3.4 — Structured invalidation taxonomy

InvalidationReason is a serde-tagged enum whose canonical snake_case string is what gets written to invalidated_reason. Back-compat: the column has always been free-text; rows written before this story parse as InvalidationReason::Manual. Analytics groups invalidations by reason.

Structs

ForgetCandidate

One candidate identified by the forgetting pass.

ForgetOptions

Options for the forget_brain policy run.

ForgetSummary

Result of a forget_brain call.

InvalidationByReason

Count of invalidations grouped by structured reason.

ProposalGcOptions

Options for the proposal GC pass.

ProposalGcSummary

Summary of a proposal GC pass.

RegretFlaggedMemory

A memory flagged for review due to repeated retrieval regrets.

Enums

InvalidationReason

Canonical invalidation reason enum.

Functions

forget_brain

Run the active-forgetting policy.

gc_proposals

Run the proposal-queue hygiene pass.

invalidations_by_reason

Return a summary of all invalidated memories grouped by their structured reason (normalised via InvalidationReason::from_db).

list_archived

Explicit archival status; invalidated/corrected/superseded claims are excluded.

regret_flagged_memories

Query memories that have accumulated ≥ threshold retrieval.regret events. These are surfaced for review but NOT auto-deleted.

restore_memory

Restore archival state only; never reopen expiry or resurrect superseded claims.