Module optical_forgetting 

ScrapMem optical forgetting — progressive content-fidelity decay (issue #3713).

Transitions old messages through resolution levels by compressing their content via LLM:

1. Full — original message content, unchanged.
2. Compressed — LLM-generated summary preserving key facts (stored in compressed_content).
3. SummaryOnly — one-line distilled fact (replaces original content, most compact).

The sweep is orthogonal to SleepGate (which decays importance scores):

• SleepGate prunes by importance score below a floor.
• Optical forgetting compresses by age (turns since creation).

Both can run concurrently; optical forgetting skips messages below the SleepGate prune threshold to avoid compressing content that will be pruned shortly anyway.

Invariants

• Messages below the SleepGate forgetting_floor are skipped.
• The episodic_events table (EM-Graph) references messages by FK; events survive optical forgetting because messages are never deleted — only their content is replaced.
• focus_pinned is a runtime-only MessageMetadata field and is not stored in the messages table, so it cannot be filtered at the SQL level. The agent loop is responsible for not triggering optical forgetting on pinned sessions.

Structs

OpticalForgettingConfig

ScrapMem optical forgetting configuration.

OpticalForgettingResult

Outcome of a single optical forgetting sweep.

Enums

ContentFidelity

Content-fidelity level for optical forgetting.

Functions

run_optical_forgetting_sweep

Execute one full optical forgetting sweep.

start_optical_forgetting_loop

Start the background optical forgetting loop.