# Understanding the Four Memory Tiers in ai-memory: Lifetimes, Decay Policies, and Implementation

> Explore the four memory tiers in ai-memory: Working, Episodic, Semantic, and Procedural. Learn about their lifetimes and decay policies within the M8 architecture for efficient AI knowledge management.

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

---

**The ai-memory system organizes knowledge into four distinct memory tiers—Working, Episodic, Semantic, and Procedural—each with specific lifetimes ranging from a single session to indefinite persistence, governed by decay policies defined in the M8 architecture specification.**

The `akitaonrails/ai-memory` repository implements a cognitive-inspired storage architecture that mimics human memory retention patterns. Understanding these **memory tiers in ai-memory** is critical for developers building applications that require intelligent context management across varying temporal horizons.

## The Four Memory Tiers Defined

The architecture classifies all stored knowledge into four semantic categories, each mapped to the `tier` enum column in the `pages` table. According to [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md), these tiers balance immediacy against long-term retention through distinct decay policies.

### Working Memory (Session-Bound)

**Working** memory persists only for the duration of the current session. When the session terminates, the system performs a hard-drop on the content, removing it from active storage. However, as implemented in the storage layer, the content is retained in the `observations` table for forensic purposes, ensuring auditability without polluting the active working set.

### Episodic Memory (Time-Decayed Hot Storage)

**Episodic** memory remains hot for 30 days, transitioning to a cold state for up to 180 days before final eviction. The decay behavior combines multiple weighting factors: salience scoring, exponential time-based decay, access-count weighting, and breadth weighting across distinct actors. This complex formula, detailed in the **Memory tiers (M8 policy)** documentation, ensures that frequently accessed, highly relevant contextual memories survive longer than peripheral observations.

### Semantic Memory (Indefinite Until Rewritten)

**Semantic** memory persists indefinitely until explicitly superseded by a later LLM rewrite. Unlike other tiers, **semantic** pages experience no automatic decay; they remain valid until a new version overwrites the old one. This makes the tier ideal for factual knowledge bases and canonical reference material that should remain stable across sessions.

### Procedural Memory (Frequency-Dependent)

**Procedural** memory remains viable as long as the pattern continues to be observed. When the system stops observing the procedural pattern, it applies frequency-based decay. This tier is optimized for scripts, workflows, and reusable automation that should persist only while actively utilized.

## Decay Policies and the M8 Architecture

The **M8 policy** governs how the system evaluates memory retention across tiers. While **Working** memory uses session boundary triggers and **Semantic** memory relies on version replacement, **Episodic** and **Procedural** tiers implement sophisticated decay algorithms that weigh access patterns against temporal distance.

Pages marked `pinned: true` in their front-matter are **exempt from all decay** regardless of tier designation. Additionally, slots located under the `_slots/` directory receive automatic pinning and special handling for mutable ("state") versus immutable ("invariant") data, bypassing standard eviction policies.

## Working with Tiers in Practice

The unified storage model enables tier-specific operations through the API and CLI while maintaining a single `pages` table schema.

Creating a tiered page in Rust requires setting the `tier` field on the `Page` struct as defined in [`crates/ai-memory-core/src/model/page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/model/page.rs):

```rust
// Example: creating a new page with a specific tier
use ai_memory_core::model::Page;
let page = Page {
    title: "Design Decisions".into(),
    body: "...".into(),
    tier: "episodic".into(),   // "working", "episodic", "semantic", or "procedural"
    pinned: false,
    ..Default::default()
};
store.write_page(page).await?;

```

The CLI implementation in [`crates/ai-memory-cli/src/commands/wiki.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-cli/src/commands/wiki.rs) supports direct tier assignment and pinning:

```bash

# CLI: create a pinned procedural page (e.g., a reusable script)

ai-memory wiki write \
  --title "setup.sh" \
  --tier procedural \
  --pinned true \
  --body '#!/usr/bin/env bash\nset -e\n...'

```

For querying specific tiers, the Python client can filter by the `tier` parameter:

```python

# Python client: query only semantic pages

import aiohttp, json

async def fetch_semantic():
    async with aiohttp.ClientSession() as s:
        async with s.get(
            "http://127.0.0.1:49374/api/v1/search",
            params={"query": "authentication", "tier": "semantic"}
        ) as resp:
            data = await resp.json()
            print(json.dumps(data, indent=2))

```

## Database Implementation Details

All tiers coexist in a single `pages` table defined in [`crates/ai-memory-store/src/schema.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/schema.rs), utilizing a unified schema with a `tier` enum column. This design enables cross-tier queries while preserving semantic boundaries. The schema supports time-travel queries (`as_of`) documented in [`docs/temporal.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/temporal.md), allowing historical reconstruction of memory states based on tier validity periods.

The [`crates/ai-memory-core/src/model/page.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/model/page.rs) file handles serialization logic for the tier metadata, ensuring type safety across the Rust core, CLI tooling, and HTTP API boundaries.

## Summary

- **Working** memory lasts only for the current session, with forensic retention in the `observations` table.
- **Episodic** memory survives 30 days hot and 180 days cold using weighted decay formulas.
- **Semantic** memory persists indefinitely until overwritten by new LLM-generated versions.
- **Procedural** memory remains viable while observed and decays based on observation frequency.
- **Pinned** pages and `_slots/` entries bypass all decay policies regardless of tier.
- All tiers share the `pages` table schema with unified query capabilities via the `tier` enum column.

## Frequently Asked Questions

### How long does Working memory persist in ai-memory?

Working memory persists only for the duration of the current session. When the session ends, the system performs a hard-drop on the content, though it retains the data in the `observations` table for forensic audit purposes.

### What determines when Episodic memory expires?

Episodic memory expiration depends on a composite decay formula that weighs salience, exponential time-based decay, access frequency, and actor breadth. The tier remains hot for 30 days, transitions to cold storage for up to 180 days, and then faces eviction unless pinned.

### Can I prevent a page from being decayed?

Yes. Set `pinned: true` in the page's front-matter to exempt it from all decay policies. Additionally, any file placed under the `_slots/` directory is automatically pinned and receives specialized handling for state versus invariant data.

### How are memory tiers stored in the database?

All four tiers reside in a single `pages` table with a `tier` enum column, as defined in [`crates/ai-memory-store/src/schema.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/schema.rs). This unified schema enables efficient queries across tiers while maintaining distinct lifetime semantics through the application-layer logic described in [`docs/ARCHITECTURE.md`](https://github.com/akitaonrails/ai-memory/blob/main/docs/ARCHITECTURE.md).