How the Episodic Memory Decay Formula Works in ai-memory

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 for calculations, crates/ai-memory-store/src/ops.rs for eviction logic, and 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, 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 follows this structure:

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

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

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. The DecayParams struct in 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.

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.
• Key parameters λ, μ, and σ control decay rates and are configurable via config.toml and the DecayParams builder in 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 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.
• 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, while runtime configuration is handled through DecayParams in crates/ai-memory-mcp/src/server.rs and the [decay] table in config.toml. The architectural rationale is documented in 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, 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.

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