# What Happens When an Episodic Page’s Retention Falls Below the Cold Threshold in ai-memory

> Discover what happens when an episodic page's retention falls below the cold threshold in ai-memory. Learn how the system evicts cold pages, deleting files and writing decay tombstones.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: internals
- Published: 2026-08-22

---

**When an episodic page’s retention score drops below the configured `cold_threshold`, the system flags it as cold and evicts it—permanently deleting the Markdown file and writing a decay tombstone to the store.**

In the `akitaonrails/ai-memory` knowledge consolidation engine, episodic memory pages naturally lose retention over time. When their computed score crosses below the `cold_threshold` defined in `DecayParams`, the system triggers a coordinated workflow involving the curator and sweep modules to identify, report, and ultimately remove stale content from the wiki.

## Understanding the Cold Threshold Detection

The detection process begins in the consolidation layer, where the curator evaluates retention scores against the threshold configuration.

### Curator Scoring and cold_episodic Findings

In [`crates/ai-memory-consolidate/src/curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/curator.rs), the curator builds a comprehensive report by scoring each episodic page using the standard decay formula. When a page’s computed score falls below `params.decay_params.cold_threshold`, the system generates a `cold_episodic` finding [1]. This finding captures the page path, the exact score, the threshold value, age metadata, and access count, creating an audit trail before any deletion occurs.

This detection mechanism serves as the early warning system, identifying candidates for eviction while the content remains accessible.

## The Eviction Sweep Process

Once flagged by the curator, cold pages become candidates for the M8 retention pass—commonly referred to as the "forget sweep."

### Sweep Execution and Dry-Run Modes

The sweep logic resides in [`crates/ai-memory-consolidate/src/sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/sweep.rs). During execution, any candidate with a score below `params.cold_threshold` is added to the internal `evicted` list [2]. The sweep operates in two distinct modes:

- **Dry-run mode**: Pages are cataloged in the report findings but remain physically present in the wiki storage
- **Live mode**: The system proceeds with permanent file deletion and tombstone creation

### Physical File Removal and Tombstone Creation

When executing a live sweep (non-dry-run), the engine invokes `wiki.evict_page_if_latest` from [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs). This function performs two atomic operations [3]:

1. **Deletes the Markdown file** from the wiki filesystem, immediately removing the page from user access
2. **Creates a decay tombstone** entry in the store with `EvictedPage.deleted` set to `true`, marking the page as intentionally evicted

This dual-action approach ensures content disappears from the observable wiki while the database maintains a permanent record of the eviction event.

## Configuring the Cold Threshold

The threshold that triggers eviction is fully configurable through the decay parameter system.

### DecayParams Configuration

The `cold_threshold` value is defined in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) within the `DecayParams` struct. Both the curator and sweep modules reference this shared configuration to ensure consistency in retention evaluation. The default value is provided by `DecayParams::default()`, though deployments can override this based on specific organizational retention policies or compliance requirements.

## Practical Code Examples

The following Rust examples demonstrate how to detect cold pages and execute the eviction workflow.

**Generating a curator report (dry-run):**

```rust
let report = run_curator_report(
    &store.reader,
    workspace_id,
    project_id,
    "default",
    "scratch",
    CuratorParams::default(),
).await?;
println!("{}", render_curator_report_markdown(&report));

```

**Running the forget sweep with actual eviction:**

```rust
let sweep = run_sweep(
    &store.reader,
    &store.writer,
    Some(&wiki),          // provide the Wiki so files are removed
    workspace_id,
    project_id,
    &DecayParams::default(),
    false,                // dry_run = false → perform eviction
).await?;
println!("Evicted {} pages", sweep.evicted.len());

```

**Inspecting cold-episodic findings:**

```rust
for f in report.findings.iter().filter(|f| f.kind == "cold_episodic") {
    println!("Cold page: {}", f.message);
    println!("Score: {}", f.detail.as_ref().unwrap()["score"]);
}

```

## Summary

- **Curator Detection**: In [`crates/ai-memory-consolidate/src/curator.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/curator.rs), pages scoring below `cold_threshold` generate `cold_episodic` findings that capture path, score, age, and access metadata for audit purposes.
- **Sweep Eviction**: The [`crates/ai-memory-consolidate/src/sweep.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-consolidate/src/sweep.rs) engine collects sub-threshold pages into an `evicted` list, differentiating between dry-run reporting and live deletion modes.
- **Physical Removal**: Live sweeps trigger `evict_page_if_latest` in [`crates/ai-memory-wiki/src/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-wiki/src/wiki.rs) to delete Markdown files and write decay tombstones with the `deleted` flag set.
- **Configuration Authority**: The `cold_threshold` parameter lives in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) within `DecayParams`, governing both the curator’s detection logic and the sweep’s eviction criteria.

## Frequently Asked Questions

### What is the difference between a cold_episodic finding and actual eviction?

A `cold_episodic` finding is a diagnostic report generated by the curator indicating a page has fallen below the retention threshold, but the Markdown file remains physically present in the wiki. Actual eviction occurs only during a sweep execution with `dry_run` set to `false`, which permanently deletes the file and creates a database tombstone.

### How can I preview which pages will be evicted without deleting them?

Execute the sweep in dry-run mode by passing `true` for the dry_run parameter in `run_sweep`. This generates the full list of cold pages and findings without invoking `evict_page_if_latest` or performing any filesystem operations, allowing safe inspection of eviction candidates.

### Where is the cold_threshold value defined and how do I change it?

The `cold_threshold` is a configurable field in the `DecayParams` struct located in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs). You can modify the default value in the `DecayParams::default()` implementation or instantiate custom `DecayParams` with your desired threshold when calling `run_sweep` or `run_curator_report`.

### What happens to evicted pages in the database after deletion?

Evicted pages persist as decay tombstones in the store with the `EvictedPage.deleted` boolean set to `true`. This tombstone record prevents the page from being retrieved in future queries while maintaining forensic evidence that the page existed and was intentionally removed due to low retention scores.