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

> Customize ai-memory episodic memory decay and retention policies by configuring DecayParams. Tune exponential decay, access reinforcement, and eviction thresholds for optimal performance.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs):

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) accepts the decay parameters alongside page metadata and calculates relevance through two primary components:

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) maps configuration keys prefixed with `decay_` directly to `DecayParams` fields in your [`.ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/.ai-memory.toml) file:

```toml
[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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/.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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/.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.