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

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, 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 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 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 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—executes the M8 retention policy across the store. According to 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:

// 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:

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

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

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

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	Canonical tier definitions and decay formulas (lines 91–108)
crates/ai-memory-store/src/decay.rs	Episodic decay mathematics implementation
crates/ai-memory-store/src/reader.rs	decay_candidates query for sweep evaluation
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 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.

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