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

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, 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. 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. 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 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):

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:

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:

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, 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 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 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}