# How the Episodic Memory Decay Formula Works in ai-memory

> Understand the episodic memory decay formula in ai-memory. Learn how age and access frequency combine to manage content salience and eviction.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: deep-dive
- Published: 2026-09-09

---

**The episodic memory decay formula in ai-memory combines age-based exponential decay with access-frequency logarithmic decay to calculate evolving page salience, automatically evicting content whose scores fall below configurable retention thresholds.**

The akitaonrails/ai-memory repository implements an intelligent forgetting mechanism that mimics human episodic memory by mathematically degrading wiki page importance over time. This system ensures that outdated or irrelevant content naturally fades while frequently accessed knowledge persists, balancing storage efficiency with information retrieval quality. The implementation spans [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) for calculations, [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) for eviction logic, and [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) for architectural rationale.

## The Two-Component Decay Model

The formula operates on two distinct temporal signals: how long ago the page was last updated and how often it has been accessed. This dual approach prevents the premature loss of valuable reference material while allowing stale content to fade from active memory according to configurable decay rates.

### Age-Based Decay

The first component applies exponential decay to the base salience score based on the time elapsed since the last update. As implemented in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs), this calculation uses the parameter **lambda (λ)**—approximately 0.01 by default—to control the daily decay rate of the original salience value.

### Access-Based Decay

The second component rewards engagement by incorporating a logarithmically scaled access count that undergoes its own exponential decay based on days since last access. This ensures that popular pages decay more slowly than forgotten ones, utilizing the **mu (μ)** and **sigma (σ)** parameters to fine-tune the access influence.

## Mathematical Implementation

The complete formula implemented in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) follows this structure:

```rust
salience · exp(-λ · age_days) + σ · log(1 + access_count) · exp(-μ · days_since_access)

```

Where the variables represent:

- **salience** — The base importance score assigned to the page at creation or last update.
- **age_days** — Days elapsed since the page's `updated_at` timestamp.
- **access_count** — Total number of times the page has been read.
- **days_since_access** — Days elapsed since the `last_accessed_at` timestamp.
- **λ (lambda)** — Per-day exponential decay rate for the age component (default ~0.01).
- **μ (mu)** — Per-day exponential decay rate for the access component (default ~0.001).
- **σ (sigma)** — Scaling factor determining access frequency influence (default ~1.0).

## Calculating Salience After Feedback

The `salience_after_feedback` function in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) applies this formula following user interactions. It accepts the current salience, optional previous salience, and a `FeedbackKind` enum (`Helpful` or `NotHelpful`) to compute the updated score that persists until the next decay sweep.

```rust
use ai_memory_store::decay::{DecayParams, salience_after_feedback, FeedbackKind};

let params = DecayParams::default();
let new_salience = salience_after_feedback(&params, None, FeedbackKind::Helpful);

```

## The Decay Sweep Lifecycle

### Identifying Decay Candidates

The system periodically queries for pages requiring evaluation through methods in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs). The `decay_candidates` function retrieves pages within a workspace and project where the calculated salience may have fallen below the retention threshold.

### Tombstone Creation and Hard Deletion

When salience drops below the configured threshold, [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs) executes `soft_delete_for_decay_if_latest` to convert the page into a **decay tombstone**—a lightweight placeholder preserving historical metadata while removing content. Eventually, `hard_delete_decayed_page_chain` performs permanent deletion once the retention window expires.

```rust
let candidates = store.reader.decay_candidates(ws, proj).await?;
for cand in candidates {
    if cand.salience < params.threshold {
        store.writer.soft_delete_for_decay_if_latest(
            ws, 
            proj, 
            cand.page_id, 
            &params
        ).await?;
    }
}

```

## Configuration and Parameters

Decay behavior is controlled through the `[decay]` section in [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml). The `DecayParams` struct in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) exposes builder methods like `with_decay_params`, allowing per-project customization of lambda, mu, sigma, and threshold values without recompiling the source.

## Pinning Pages to Prevent Decay

Users can exempt critical content from the decay formula entirely by pinning pages, which sets a flag bypassing all salience calculations regardless of age or access patterns.

```rust
store.writer.pin_page(ws, proj, page_id).await?;

```

## Summary

- The episodic memory decay formula combines **age-based exponential decay** with **access-frequency logarithmic decay** to calculate evolving page salience in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs).
- Key parameters **λ**, **μ**, and **σ** control decay rates and are configurable via [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml) and the `DecayParams` builder in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs).
- The `salience_after_feedback` function applies the mathematical model after user feedback events.
- Decay sweeps utilize `decay_candidates` from [`reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/reader.rs) to identify content for eviction.
- Pages below threshold become tombstones via `soft_delete_for_decay_if_latest` and are later purged by `hard_delete_decayed_page_chain` in [`ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/ops.rs).
- Critical pages can be permanently retained using the `pin_page` method, bypassing all decay calculations.

## Frequently Asked Questions

### What determines how fast a page decays in ai-memory?

The decay velocity depends on the **lambda** parameter controlling age-based fading and the **mu** parameter governing access-pattern decay. Pages with high `access_count` values decay more slowly due to the logarithmic scaling factor **sigma**, while rarely accessed or outdated pages fade quickly as their `age_days` and `days_since_access` values increase.

### How can I prevent important pages from being deleted?

Call the `pin_page` method on the store writer, which exempts the content from decay sweeps entirely. Pinned pages maintain full salience regardless of age or access patterns until explicitly unpinned, effectively removing them from the `decay_candidates` query results.

### Where is the decay formula configured in the codebase?

The mathematical constants and default rates reside in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs), while runtime configuration is handled through `DecayParams` in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) and the `[decay]` table in [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml). The architectural rationale is documented in [`docs/design-decisions.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/design-decisions.md) under the "Episodic" section.

### What happens to decayed pages before they are permanently deleted?

Decayed pages transition into tombstones via `soft_delete_for_decay_if_latest` in [`crates/ai-memory-store/src/ops.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/ops.rs), preserving metadata while removing content. These tombstones remain in storage until `hard_delete_decayed_page_chain` permanently removes them after the configured retention window expires, ensuring a grace period for potential recovery.