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

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

// 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 supports direct tier assignment and pinning:

# 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 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, 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, allowing historical reconstruction of memory states based on tier validity periods.

The 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. This unified schema enables efficient queries across tiers while maintaining distinct lifetime semantics through the application-layer logic described in docs/ARCHITECTURE.md.

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