How to Customize Decay and Retention Policies for ai-memory Episodic Memory

You customize ai-memory's episodic retention behavior by providing a custom DecayParams struct to the store builder or CLI configuration, which tunes six parameters governing exponential decay rates, access reinforcement, and eviction thresholds.

The ai-memory system manages episodic memory tiers by calculating a retention score for each stored page, determining whether content remains hot in the cache or becomes a candidate for eviction. According to the akitaonrails/ai-memory source code, this scoring logic is implemented as pure functions in crates/ai-memory-store/src/decay.rs and exposes tunable parameters through the DecayParams struct. By adjusting these values, you control how quickly unused memories fade, how much access patterns reinforce retention, and when the system permanently deletes cold content.

Understanding the DecayParams Configuration Structure

The DecayParams struct defined in crates/ai-memory-store/src/decay.rs contains six fields that govern the complete lifecycle of episodic memory pages:

• lambda: Controls the per-day exponential decay for page age (default 0.02, yielding approximately a 35-day half-life)
• sigma: Determines the magnitude of reinforcement boost granted by access patterns (default 0.6)
• mu: Applies exponential decay to "days since last access" separately from creation age (default 0.04)
• salience_default: Baseline salience multiplier for pages without explicit feedback (default 1.0)
• cold_threshold: The retention score threshold below which pages are flagged for eviction (default 0.20)
• hard_delete_after_days: Tombstone retention period before permanent deletion (default 180)

These parameters feed into the retention_score function, which returns an f64 value that the forget-sweep job compares against cold_threshold during cleanup cycles.

Implementing Custom Decay Parameters in Rust

To programmatically customize decay and retention policies, you instantiate a DecayParams struct and pass it to the store builder via the with_decay_params method implemented in crates/ai-memory-mcp/src/server.rs:

use ai_memory_store::{Store, DecayParams};

let custom_decay = DecayParams {
    lambda: 0.015,               // Slower decay extends content half-life
    sigma: 0.8,                  // Stronger access reinforcement
    mu: 0.02,                    // Recent accesses retain influence longer
    salience_default: 1.0,
    cold_threshold: 0.10,        // More aggressive eviction
    hard_delete_after_days: 365, // Extended tombstone period
};

let store = Store::builder()
    .with_decay_params(custom_decay)
    .build()?;

The builder pattern ensures that your custom DecayParams propagates to all internal storage operations, including the background forget-sweep job that evaluates retention_score against your specified cold_threshold.

How the Retention Score Algorithm Works

The retention_score function signature in crates/ai-memory-store/src/decay.rs accepts the decay parameters alongside page metadata and calculates relevance through two primary components:

pub fn retention_score(
    params: &DecayParams,
    age_days: f64,
    access_count: u32,
    days_since_access: Option<f64>,
    salience: Option<f64>,
) -> f64

Time Decay Component

The algorithm applies exponential decay to page age, moderated by salience. The calculation follows salience * exp(-lambda * age_days), meaning older pages lose score exponentially unless elevated by user-provided salience feedback. Higher lambda values accelerate this decay, while lower values (e.g., 0.015 vs. 0.02) create longer-lived memories.

Access Reinforcement Component

The access term rewards recent, frequent reads using the formula sigma * ln(1 + access_count) * exp(-mu * days_since_access). This creates a logarithmic growth pattern for total accesses that decays exponentially based on recency. The mu parameter specifically governs how quickly the "freshness" of an access fades, distinct from the creation-age decay controlled by lambda.

Eviction Thresholds

When the forget-sweep job iterates through stored rows, any page scoring below cold_threshold becomes an eviction candidate. The system then applies hard_delete_after_days to tombstoned entries, ensuring that removed content persists for audit or recovery purposes before permanent deletion.

Configuration via CLI and TOML Files

If you run ai-memory through the command-line interface, you can override decay parameters without modifying source code. The CLI configuration system in crates/ai-memory-cli/src/config.rs maps configuration keys prefixed with decay_ directly to DecayParams fields in your .ai-memory.toml file:

[decay]
lambda = 0.01
sigma = 0.9
mu = 0.03
cold_threshold = 0.15
hard_delete_after_days = 90

Command-line flags also expose these parameters, forwarding values to the same builder pattern used in programmatic initialization.

Practical Tuning Strategies for Different Workflows

Long-Lived Personal Notes

For personal knowledge bases where content remains relevant months after creation, increase lambda to slow decay (e.g., 0.01 for ~70-day half-life) and lower cold_threshold (e.g., 0.10) to prevent premature eviction of rarely accessed but valuable references.

Team-Wide Knowledge Bases

When operating in collaborative environments, enable the breadth bonus by populating the distinct_actors column via the accesses table, then increase the breadth_weight parameter to reward pages accessed by multiple team members. This elevates content with cross-functional relevance above individually useful but narrow entries.

Rapidly Evolving Documentation

For rapidly changing specifications or ephemeral context, lower sigma to reduce the influence of historical accesses and raise mu to accelerate the decay of access freshness. This configuration keeps the episodic cache focused on recent hits while quickly forgetting outdated iterations.

Summary

• DecayParams in crates/ai-memory-store/src/decay.rs provides six tunable fields controlling exponential decay rates (lambda, mu), access reinforcement (sigma), and eviction thresholds (cold_threshold).
• Use the with_decay_params builder method when constructing the Store programmatically, or set decay_* keys in .ai-memory.toml for CLI usage.
• The retention score combines time-based decay with logarithmic access reinforcement; pages scoring below cold_threshold enter the eviction queue.
• Tombstoned pages persist for hard_delete_after_days (default 180) before permanent deletion.
• Unit tests in crates/ai-memory-store/tests/access_breadth.rs validate the effects of custom parameter combinations.

Frequently Asked Questions

What are the default decay parameters in ai-memory?

The default DecayParams configuration sets lambda to 0.02 (35-day half-life), sigma to 0.6, mu to 0.04, salience_default to 1.0, cold_threshold to 0.20, and hard_delete_after_days to 180. These values balance retention for moderately active knowledge bases without requiring manual tuning.

How does the cold_threshold parameter affect eviction?

The cold_threshold value acts as a gatekeeper for the forget-sweep job; any page with a calculated retention score below this threshold becomes a candidate for eviction during cleanup cycles. Lowering this value (e.g., from 0.20 to 0.10) makes the system more aggressive about removing content, while raising it preserves marginal entries in the episodic cache.

Can I adjust retention policies without recompiling the code?

Yes. When running the ai-memory CLI, you can modify decay and retention policies through the .ai-memory.toml configuration file or via command-line flags that map to DecayParams fields. The CLI constructs the Store using the same builder pattern, passing your external configuration values to the internal with_decay_params method without requiring source changes.

What is the difference between lambda and mu in the decay formula?

The lambda parameter controls exponential decay based on page creation age, affecting how quickly content fades regardless of access patterns, while mu governs the decay of access recency, determining how long ago a read occurred before its influence on the retention score diminishes. You might lower lambda to keep old but unaccessed content alive while raising mu to ensure only recent reads provide significant score boosts.

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