# ai‑memory M8 Retention Policy: The 4 Memory Tiers Explained

> Explore ai-memory's M8 retention policy and its four memory tiers: Working, Episodic, Semantic, and Procedural. Understand page eviction and preservation rules.

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

---

**ai‑memory's M8 retention policy uses four memory tiers—Working, Episodic, Semantic, and Procedural—each with defined lifetimes and decay rules that govern when pages are evicted or preserved indefinitely.**

The M8 retention policy is the core garbage‑collection mechanism in the ai‑memory open‑source project. It organizes wiki pages into distinct memory tiers based on how long information remains relevant and how it should decay over time. According to the project architecture documentation in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md), these tiers directly control the behavior of the `memory_forget_sweep` tool that cleans stale data from the store.

## The Four ai‑memory M8 Memory Tiers

The tier definitions are located at [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) lines 93–101. Each tier maps to a different cognitive analogy: immediate workspace, recent events, long‑term facts, and learned skills.

### Working Tier: Session‑Bound Volatility

Pages in the **Working** tier exist only for the current session. They face **hard‑drop on session end**, meaning the primary content is deleted when the session closes. A forensic copy is retained in `observations` for debugging or audit purposes, but the page itself does not survive.

Use this tier for scratchpads, temporary calculations, or draft content that has no value once the immediate task completes.

### Episodic Tier: Time‑Decaying Event Memory

The **Episodic** tier mimics human short‑to‑medium term memory. Pages follow a temperature curve:

- **30 days hot**: full retention with active decay calculation
- **180 days cold**: reduced priority, eligible for eviction
- **Eviction**: permanent removal after cold phase expires

#### Episodic Decay Formula

The decay calculation implemented in [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) combines four signals:

```

salience·exp(−λΔt) + σ·log(1+access_count)·exp(−μ·days_since_access)·(1 + breadth_weight·ln(1 + max(distinct_actors−1, 0)))

```

| Signal | Meaning |
|--------|---------|
| **salience** | Initial importance score from front‑matter or LLM rating |
| **λΔt** | Exponential time decay since creation |
| **access_count** | How often the page has been read |
| **days_since_access** | Recency penalty for idle pages |
| **distinct_actors** | Social breadth bonus—pages accessed by many users decay slower |

The **breadth weight** term rewards collective relevance. A page touched by five different actors decays slower than a page with equal access count from a single user.

### Semantic Tier: Indefinite Factual Storage

**Semantic** pages are retained **indefinitely with no decay**. These store facts, concepts, and reference material that do not expire. The only way a Semantic page changes is through **M7 LLM rewrite**—a deliberate update where the model generates a new version superseding the old.

Set `tier = "semantic"` in front‑matter for canonical documentation, entity definitions, or any content that should remain stable until explicitly revised.

### Procedural Tier: Skill Memory With Frequency Decay

**Procedural** pages also live indefinitely, but they implement **frequency‑decay**: if a skill or procedure is not re‑observed (accessed or reinforced) over time, its priority drops. Unlike Episodic pages, Procedural items are never hard‑deleted—they simply become less likely to surface in relevance queries.

This tier suits encoded workflows, prompt templates, and learned strategies that should persist but may fade from active recommendation if unused.

## Special Exemptions From M8 Decay

Two mechanisms override the standard tier rules, defined at [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) lines 102–108.

### Pinned Pages

Any page with `pinned: true` in its front‑matter is **exempt from all decay paths**. Pinning is the explicit user signal that content must survive regardless of tier rules.

### Automatic Slot Pinning

Pages stored under the `_slots/` directory are **automatically pinned**. This convention protects template slots and system‑critical files without requiring manual front‑matter edits.

## Enforcing M8 Policy: The memory_forget_sweep Tool

The `memory_forget_sweep` tool—exposed in [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs)—executes the M8 retention policy across the store. According to [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) lines 91–93, the sweep performs three operations:

1. **Evicts cold episodic pages** that have passed their 180‑day cold threshold
2. **Hard‑deletes tombstone ancestry** for pages with explicit deletion markers
3. **Removes TTL‑expired pages** that exceeded time‑to‑live constraints

Always run with `dry_run(true)` first to preview deletions:

```rust
// Preview what the M8 sweep would remove without deleting anything
let resp = client
    .memory_forget_sweep()
    .dry_run(true)
    .send()
    .await?;
println!("{:#?}", resp);

```

Execute the live sweep once you verify the candidate list:

```rust
// Execute the M8 retention policy enforcement
client.memory_forget_sweep().dry_run(false).send().await?;

```

## Code Examples: Working With M8 Tiers

### Creating an Episodic Page

```rust
let frontmatter = r#"
title = "Sprint planning notes"
tier = "episodic"
pinned = false
"#;

ai_memory_wiki::write_page("meetings/sprint_42.md", frontmatter, "Discussion content…")
    .await?;

```

This page enters the 30‑day hot phase and begins accumulating decay signals based on access patterns.

### Creating a Semantic Page

```rust
let frontmatter = r#"
title = "API Authentication Schema"
tier = "semantic"
"#;

ai_memory_wiki::write_page("reference/auth_schema.md", frontmatter, "OAuth2 flow details…")
    .await?;

```

No decay calculation runs. This page survives until an explicit M7 rewrite supersedes it.

### Pinning a Page to Bypass Decay

```rust
let frontmatter = r#"
title = "Critical incident runbook"
pinned = true
"#;

ai_memory_wiki::write_page("runbooks/critical_incident.md", frontmatter, "Escalation steps…")
    .await?;

```

The `pinned` flag overrides tier behavior. Even if declared Episodic, this page never enters decay evaluation.

## Key Implementation Files

| File | Role in M8 Retention |
|------|----------------------|
| [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md) | Canonical tier definitions and decay formulas (lines 91–108) |
| [`crates/ai-memory-store/src/decay.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/decay.rs) | Episodic decay mathematics implementation |
| [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) | `decay_candidates` query for sweep evaluation |
| [`crates/ai-memory-mcp/src/server.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/server.rs) | `memory_forget_sweep` MCP tool server |

## Summary

- **ai‑memory M8 retention policy** organizes pages into four tiers with distinct lifetime rules.
- **Working** pages die with the session; **Episodic** pages decay over 30–180 days using a multi‑factor formula.
- **Semantic** pages last forever until rewritten; **Procedural** pages fade by frequency but never delete.
- **Pinned pages** and **`_slots/`** contents bypass all decay via explicit or automatic exemption.
- The **`memory_forget_sweep`** tool enforces policy, with `dry_run` available for safe preview.

## Frequently Asked Questions

### What triggers removal of a page in the Episodic tier?

A page exits the Episodic tier after 180 days in cold storage without sufficient access signals to offset decay. The `memory_forget_sweep` evaluates candidates via `decay_candidates` in [`crates/ai-memory-store/src/reader.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/reader.rs) and evicts those whose calculated priority falls below threshold.

### Can I change a page's tier after creation?

Yes. Rewrite the page with updated front‑matter—`tier = "semantic"` to stop decay, or `tier = "episodic"` to begin the 30‑day hot phase. The new tier applies on next write; previous decay history does not carry over.

### How does the breadth weight in Episodic decay work?

The term `ln(1 + max(distinct_actors−1, 0))` scales decay resistance based on how many unique users or agents have accessed the page. A page accessed by one actor gets no bonus; five actors add `ln(4) ≈ 1.39` to the multiplier, slowing decay proportionally.

### What is the difference between Semantic and Procedural indefinite retention?

Semantic pages have **zero decay**—they persist unchanged until an M7 LLM rewrite generates a new version. Procedural pages use **frequency‑decay**: priority drops if not accessed, though the page itself remains stored. Semantic suits facts; Procedural suits skills that may fall out of practice.