Understanding the Four Memory Tiers in ai-memory: Working, Episodic, Semantic, and Procedural

The ai-memory system classifies every markdown page into one of four memory tiers—Working, Episodic, Semantic, and Procedural—that determine retention policies, search ranking weights, and lifecycle management based on the content's purpose and longevity.

The ai-memory Rust crate implements a biologically-inspired memory architecture where each stored page receives a tier classification that drives how the system treats it for persistence and retrieval. These ai-memory tiers are stored in front-matter metadata and influence everything from TTL calculations to ranking multipliers during vector searches.

The Four Memory Tiers

Every page within the system must belong to one of four distinct tiers, defined in crates/ai-memory-core/src/page.rs (lines 22-31) and serialized using #[serde(rename_all = "snake_case")] to produce lowercase front-matter values.

Working Memory

Working memory holds transient observations and temporary files from the current active session. Pages in this tier represent scratch notes or intermediate data that should disappear when the session terminates. The retention sweep in crates/ai-memory-store/src/decay.rs assigns these pages the shortest TTL, treating them as ephemeral session state.

Episodic Memory

Episodic memory summarizes a single completed session, capturing concepts, tags, and files that were touched during a specific run. Unlike Working pages, Episodic entries persist beyond the immediate session but remain tied to specific temporal contexts. These pages serve as structured session logs that bridge immediate working state and long-term knowledge.

Semantic Memory

Semantic memory contains long-term distilled facts, user preferences, and architectural notes that should persist indefinitely. When the wiki layer in crates/ai-memory-wiki/src/wiki.rs encounters front-matter without an explicit tier (lines 2050-2070), it defaults to Semantic. According to the decay logic, Semantic pages may never expire unless explicitly configured with an expiration date.

Procedural Memory

Procedural memory stores patterns extracted from clusters of Episodic entries, representing reusable workflows, code snippets, and automated procedures. The system generates or updates Procedural pages by analyzing patterns across multiple Episodic summaries, creating canonical recipes that auto-populate during similar future sessions.

How Tiers Influence System Architecture

The tier classification cascades through multiple subsystems, affecting storage, retrieval, and maintenance behaviors.

Retention and Decay Policies

The retention engine in crates/ai-memory-store/src/decay.rs uses tier classification to compute time-to-live (TTL) values during periodic sweeps. Working pages receive aggressive expiration schedules, while Semantic and Procedural pages enjoy extended or permanent retention. This tier-based decay prevents storage bloat while preserving critical long-term knowledge.

Search Ranking Multipliers

When ranking vector search results, the reader implementation in crates/ai-memory-store/src/reader.rs (lines 225-235) applies tier-based multiplicative boosts:

• Semantic and Procedural pages receive the highest ranking factors
• Episodic pages receive moderate weighting
• Working pages receive minimal or neutral weighting

This ensures that canonical knowledge surfaces above transient session notes during retrieval, even when semantic similarity scores are comparable.

Practical Implementation Examples

Creating Pages with Specific Tiers

When programmatically creating pages via the core crate, specify the tier using the Tier enum:

use ai_memory_core::page::{Tier, NewPage};
use ai_memory_core::ids::{WorkspaceId, ProjectId, PagePath};

let page = NewPage {
    workspace_id: WorkspaceId::new("default"),
    project_id: ProjectId::new("demo"),
    path: PagePath::new("notes/summary.md").unwrap(),
    title: "Session Summary".into(),
    body: "Captured key architectural decisions...".into(),
    tier: Tier::Episodic,               // ← Explicit tier assignment
    frontmatter_json: serde_json::json!({ "title": "Session Summary" }),
    pinned: false,
    links: vec![],
    author_id: None,
    expires_at: None,
    entities: vec![],
};

Front-Matter Configuration

In markdown files, declare the tier in YAML front-matter using snake_case values:

---
title: "Project Architecture"
tier: semantic        # ← working, episodic, semantic, or procedural

pinned: true
---

# Architecture Overview

This document contains canonical architectural decisions...

The wiki parser in crates/ai-memory-wiki/src/wiki.rs validates this field during ingestion, rejecting invalid tier values to prevent silent fallback errors.

Filtering Queries by Tier

Target specific memory layers during retrieval by filtering on the tier column:

let results = store.search_pages(
    "authentication patterns",
    SearchOptions {
        required_tier: Some("procedural".into()),
        ..Default::default()
    },
);

The store reader extracts the pages.tier column and applies the filter before ranking, allowing fine-grained control over which memory layers participate in context construction.

Summary

• Four distinct tiers govern the ai-memory lifecycle: Working (transient), Episodic (session summaries), Semantic (permanent facts), and Procedural (extracted patterns).
• Source definition resides in crates/ai-memory-core/src/page.rs with snake_case serialization for front-matter compatibility.
• Default behavior assigns Semantic tier when front-matter omits the field entirely.
• Retention policies in crates/ai-memory-store/src/decay.rs tier by TTL, while ranking logic in crates/ai-memory-store/src/reader.rs boosts higher-value tiers during retrieval.

Frequently Asked Questions

What happens if I don't specify a tier in the front-matter?

The wiki parser in crates/ai-memory-wiki/src/wiki.rs automatically defaults the page to the Semantic tier. This ensures that unclassified content receives long-term retention by default rather than expiring as transient Working memory.

How does the system choose between Episodic and Procedural tiers?

Episodic pages are created automatically to summarize individual completed sessions, while Procedural pages emerge from pattern extraction across multiple Episodic clusters. The system promotes frequently-observed patterns from Episodic summaries into reusable Procedural entries through background analysis processes.

Can I change a page's tier after creation?

Yes, though the specific mutation logic depends on the store implementation. Because the tier is stored as a column in the underlying database and serialized in front-matter, updating the field requires modifying both the markdown source and the store index via the writer interfaces in crates/ai-memory-store/src/writer.rs.

Why does Working memory have a short TTL?

Working memory is designed for active session state—temporary notes, scratch files, and intermediate computations that lose relevance once the session concludes. The short TTL in crates/ai-memory-store/src/decay.rs implements automatic garbage collection for this transient data, preventing storage pollution while preserving the most recent context during active use.

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