How to Configure Decay Parameters in ai-memory: A Complete Guide

Configure decay parameters in ai-memory by modifying the TOML configuration file, setting AI_MEMORY_* environment variables, passing CLI flags to the serve command, or programmatically constructing a DecayParams struct to control content retention and forgetting rates.

The ai-memory system (akitaonrails/ai-memory) uses a retention-score formula to determine how long pages remain in the knowledge store. These calculations rely on tunable coefficients defined in the DecayParams struct, which you can override at runtime to adjust how aggressively the system forgets or reinforces content.

Core Decay Components

The ai-memory architecture separates the core decay logic from configuration handling. Understanding these two primary structures is essential before adjusting settings.

DecayParams Struct

The DecayParams struct in crates/ai-memory-store/src/decay.rs contains the mathematical coefficients used by the retention engine:

• lambda: Per-day exponential decay rate
• sigma: Magnitude of access-reinforcement boost
• mu: Decay rate of the reinforcement term
• salience_default: Baseline salience for new entries
• cold_threshold: Score threshold for marking content as cold
• hard_delete_after_days: Maximum retention period before forced deletion

DecaySettings Wrapper

The CLI and server use DecaySettings from crates/ai-memory-cli/src/config.rs, which wraps DecayParams and adds an extra breadth_weight field for distinct-actor weighting. This wrapper handles deserialization from TOML and environment variables, converting to DecayParams via the decay_params() method.

Configuration Methods

You can configure decay parameters through four primary interfaces, listed in order of precedence from lowest to highest priority.

TOML Configuration File

Create or edit the config.toml file in your data directory (default location) to set persistent decay values:

[decay]
lambda = 0.015               # per-day exponential decay (≈48-day half-life)

sigma = 0.7                  # magnitude of access-reinforcement boost

mu = 0.03                    # decay of the reinforcement term

salience_default = 1.0
cold_threshold = 0.25
hard_delete_after_days = 365
breadth_weight = 0.1        # optional weight for distinct actors

The system loads this file via Config::load(), which uses the figment library to merge settings. The Config::decay field exposes these as DecaySettings, which are converted to DecayParams when initializing the store.

Environment Variables

For containerized deployments or temporary overrides, use the AI_MEMORY_ prefix with uppercase field names:

export AI_MEMORY_DECAY_LAMBDA=0.015
export AI_MEMORY_DECAY_SIGMA=0.7
export AI_MEMORY_DECAY_MU=0.03
export AI_MEMORY_DECAY_SALIENCE_DEFAULT=1.0
export AI_MEMORY_DECAY_COLD_THRESHOLD=0.25
export AI_MEMORY_DECAY_HARD_DELETE_AFTER_DAYS=365
export AI_MEMORY_DECAY_BREADTH_WEIGHT=0.1

The figment loader in crates/ai-memory-cli/src/config.rs automatically merges these environment variables into the final Config struct, allowing you to configure decay parameters without modifying files.

CLI Launch Flags

When running the serve subcommand, pass a --decay flag pointing to a TOML snippet or JSON file for ad-hoc adjustments:

ai-memory serve --decay /path/to/decay-config.toml

Internally, the command handler in crates/ai-memory-cli/src/commands/serve.rs reads the runtime config and calls:

let decay_params = config.decay.decay_params();
server = server.with_decay_params(decay_params);

This pattern allows you to configure decay parameters at launch time without rebuilding the application.

Programmatic Configuration

When embedding ai-memory as a library, construct DecayParams directly and pass it to the store constructor:

use ai_memory_store::DecayParams;

let custom = DecayParams {
    lambda: 0.015,
    sigma: 0.7,
    mu: 0.03,
    salience_default: 1.0,
    cold_threshold: 0.25,
    hard_delete_after_days: 365,
};
let store = Store::new(..., custom);

The store's writer and reader use these coefficients when computing retention_score_with_breadth in crates/ai-memory-store/src/decay.rs.

Integrating Decay Parameters with the Server

The HTTP server accepts custom decay configuration through the with_decay_params method defined in crates/ai-memory-mcp/src/server.rs:

let cfg = Config::load()?;
let decay = cfg.decay.decay_params();

let server = ai_memory_mcp::Server::new(cfg)
    .with_decay_params(decay);
server.run()?;

This method injects the DecayParams instance into the server's consolidation engine, ensuring all retention calculations use your specified coefficients. The admin routes in crates/ai-memory-mcp/src/admin.rs expose the current decay configuration for runtime inspection.

Debugging Retention Scores

To verify how your decay parameters affect content longevity, use the retention_score function directly:

use ai_memory_store::{DecayParams, retention_score};

let params = DecayParams::default();
let score = retention_score(&params, 30.0, 5, Some(2.0), None);
println!("Score after 30 days: {}", score);

This helps tune lambda and sigma values before deploying to production.

Summary

• DecayParams in crates/ai-memory-store/src/decay.rs defines the six core mathematical coefficients controlling retention.
• DecaySettings in crates/ai-memory-cli/src/config.rs adds configuration-layer features like breadth_weight and handles TOML/env var parsing.
• Configure via config.toml, AI_MEMORY_* environment variables, CLI --decay flags, or direct struct instantiation.
• Pass finalized parameters to the server using with_decay_params() in crates/ai-memory-mcp/src/server.rs.
• Changes take effect immediately on server restart or CLI reload, affecting all subsequent retention_score_with_breadth calculations.

Frequently Asked Questions

What is the difference between DecayParams and DecaySettings?

DecayParams is the core mathematical struct used by the storage engine in crates/ai-memory-store/src/decay.rs, containing six fields like lambda and sigma. DecaySettings is a configuration-layer wrapper in crates/ai-memory-cli/src/config.rs that adds deserialization support and extra fields like breadth_weight, converting to DecayParams via the decay_params() method.

How do I calculate the half-life from the lambda parameter?

The lambda value represents the per-day exponential decay rate. To calculate half-life in days, use the formula ln(2) / lambda. For example, lambda = 0.015 yields approximately 46 days (ln(2)/0.015 ≈ 46.2), meaning content loses half its retention score every 46 days without reinforcement.

Can I change decay parameters without restarting the server?

Currently, ai-memory requires a server restart to apply new decay parameters. The with_decay_params method initializes the server with immutable coefficients, and the consolidation engine reads these values at startup. However, you can inspect current values through the admin routes in crates/ai-memory-mcp/src/admin.rs without restarting.

What happens when content drops below the cold_threshold?

When a page's retention score falls below the cold_threshold value (default 0.25), ai-memory marks it as "cold" content. While not immediately deleted, cold content becomes a candidate for archival or background cleanup. If the score remains low for hard_delete_after_days, the system permanently removes the entry from the knowledge store.

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