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

> Learn to configure decay parameters in ai-memory using TOML, environment variables, CLI flags, or programmatically. Control content retention and forgetting rates effectively.

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

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/config.toml) file in your data directory (default location) to set persistent decay values:

```toml
[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:

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

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

```

Internally, the command handler in [`crates/ai-memory-cli/src/commands/serve.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/serve.rs) reads the runtime config and calls:

```rust
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:

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

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

```rust
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`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) defines the six core mathematical coefficients controlling retention.
- **DecaySettings** in [`crates/ai-memory-cli/src/config.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/config.rs) adds configuration-layer features like `breadth_weight` and handles TOML/env var parsing.
- Configure via [`config.toml`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.