# Understanding the Memory Tiers in ai-memory: The M8 Policy Explained

> Explore the four memory tiers in ai-memory Working Episodic Semantic and Procedural. Understand how the M8 policy dictates retention rules for efficient AI knowledge management.

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

---

**ai-memory organizes all knowledge into four distinct memory tiers—Working, Episodic, Semantic, and Procedural—each with unique retention rules defined by the M8 policy.**

The M8 policy governs how the ai-memory system retains and decays information over time. Implemented in the akitaonrails/ai-memory repository, this policy assigns every page in the SQLite-backed wiki to a specific tier that determines its lifecycle, from session-bound working memory to indefinitely persistent semantic knowledge.

## The Four Memory Tiers of the M8 Policy

The M8 policy defines four memory tiers with distinct retention behaviors. These tiers are documented in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) at lines 80-88 and implemented across the core storage crates.

### Working Memory

**Working** memory exists only for the current session and receives no decay processing.

- **Lifetime**: Current session only
- **Decay behavior**: Hard-drop when the session ends
- **Raw observations**: Preserved only for forensics

Working memory holds transient, context-specific information that doesn't need to persist beyond the immediate interaction.

### Episodic Memory

**Episodic** memory follows a graduated decay pattern based on salience, access patterns, and time.

- **Lifetime**: 30 days hot → 180 days cold → eviction
- **Decay formula**: `salience·exp(−λ·Δt) + σ·log(1+access_count)·exp(−μ·days_since_access)·(1 + breadth_weight·ln(1 + max(distinct_actors−1, 0)))`

The episodic tier uses the most complex decay logic in the M8 policy. The formula combines:

- **Base salience decay**: Exponential time decay with rate `λ`
- **Access count boost**: Log-scaled access frequency with decay rate `μ`
- **Breadth weight**: Social signal based on distinct actors interacting with the page

These parameters (`λ`, `μ`, `σ`, `breadth_weight`) are configurable via the `[decay]` table in [`ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory.toml).

### Semantic Memory

**Semantic** memory persists indefinitely and is only modified through explicit supersession.

- **Lifetime**: Indefinite
- **Decay behavior**: None automatic; removed only by M7 LLM rewrite

Semantic pages contain distilled, factual knowledge that shouldn't fade over time. The M7 policy handles supersession—when new information replaces old, the outdated page becomes a tombstone.

### Procedural Memory

**Procedural** memory also persists indefinitely but includes frequency-based decay for unused entries.

- **Lifetime**: Indefinite
- **Decay behavior**: Decays only if not re-observed

This tier stores operational knowledge like "how to" procedures, which remain valid until explicitly contradicted or forgotten through disuse.

## Protected Pages: Pinned and Reserved Namespaces

Certain pages bypass all decay mechanisms regardless of tier assignment.

- **Pinned pages**: Marked with `pinned: true` in front-matter; immune to all decay
- **`_slots/` namespace**: Reserved directory where pages are permanently retained

These protections ensure critical reference material survives routine maintenance sweeps.

## The Forget-Sweep Tool: Enforcing M8 Policy at Runtime

The M8 policy is enforced by the `memory_forget_sweep` tool, exposed through the MCP server in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) (lines 299-306).

During a sweep:

1. Episodic pages below the cold threshold become tombstones (`superseded_at` timestamp)
2. Tombstones older than the configured period are permanently removed
3. Pinned and `_slots/` pages are skipped regardless of scores

The decay implementation lives in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs), while candidate selection for sweeps occurs in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) at `decay_candidates` (lines 3132-3156).

## Querying Memory Tiers Programmatically

You can inspect tier assignments through the CLI or Rust client.

### CLI Usage

```bash
ai-memory memory_query "how to initialize a Rust project" --explain

```

Output includes `tier: "episodic"` with the decay-adjusted relevance score.

### Rust Client Example

```rust
use ai_memory_mcp::client::MemoryClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = MemoryClient::new("http://127.0.0.1:49374")?;

    let resp = client
        .memory_query(
            "git branch list".into(),
            None,
            false,
            None,
            Some(true),
            None,
        )
        .await?;

    for hit in resp.hits {
        println!("{} (tier: {})", hit.title, hit.tier);
    }
    Ok(())
}

```

Each query automatically increments the access counter, feeding into the episodic decay formula.

### Running a Forget Sweep in Rust

```rust
use ai_memory_store::writer::WriterHandle;
use ai_memory_store::decay::DecayParams;

async fn run_forget_sweep(writer: WriterHandle) {
    let params = DecayParams::default();
    writer.memory_forget_sweep(params, dry_run = false).await.unwrap();
}

```

## Integration with M9 and M10 Enhancements

The M8 policy operates alongside newer M9 and M10 columns that add:

- **Embedding metadata** for vector search
- **Salience-derived scoring** for improved ranking

These enhancements supplement but don't replace the core tier logic—all four memory tiers function identically regardless of which metadata columns are present.

## Summary

- **Working**: Session-only, hard-dropped on exit
- **Episodic**: 30-day hot window, 180-day cold retention, complex salience-based decay formula
- **Semantic**: Indefinite, only removed by M7 LLM supersession
- **Procedural**: Indefinite, frequency-based decay if unobserved
- **Pinned pages** and **`_slots/` namespace** are immune to all decay
- Configuration lives in [`ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory.toml) under `[decay]`
- Core implementation spans [`decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/decay.rs), [`reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/reader.rs), and [`server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/server.rs)

## Frequently Asked Questions

### How do I configure decay parameters for episodic memory?

Edit the `[decay]` table in your [`ai-memory.toml`](https://github.com/akitaonrails/ai-memory/blob/main/ai-memory.toml) file. The parameters `λ` (time decay rate), `μ` (access decay rate), `σ` (access boost coefficient), and `breadth_weight` (social signal multiplier) all control the behavior of the decay formula defined in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs).

### What happens when an episodic page becomes "cold"?

Pages that fall below the cold threshold receive a `superseded_at` timestamp and become tombstones. If they remain cold for the configured eviction period (default 180 days), the forget-sweep tool permanently removes them. This process is handled in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) through the `memory_forget_sweep` MCP tool.

### Can I prevent a page from ever being deleted?

Set `pinned: true` in the page's front-matter, or store it under the `_slots/` namespace. Both mechanisms bypass all decay logic in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) during sweep candidate selection.

### What's the difference between semantic and procedural memory tiers?

Semantic memory contains factual knowledge that never decays automatically—it only changes through explicit M7 LLM rewrites. Procedural memory stores operational knowledge that persists indefinitely but can decay if the page is never re-observed, making it sensitive to usage patterns rather than calendar time.