ai-Memory Four Tiers Explained: Working, Episodic, Semantic, and Procedural

An ai-memory knowledge base organizes every piece of information into four hierarchical tiers—Working, Episodic, Semantic, and Procedural—that mirror human cognitive memory and agent-memory research patterns.

The akitaonrails/ai-memory project implements a sophisticated memory architecture designed for AI agents and long-term knowledge storage. Understanding these four tiers is essential for effectively using the system, as they determine how data flows from raw capture to reusable expertise.

The Four Memory Tiers in ai-memory

Each tier serves a distinct purpose in the knowledge lifecycle, from immediate capture to permanent, callable procedures.

Working Tier: Hot Session State

The Working tier holds raw, unprocessed observations from the current session. It acts as a scratchpad for transient data before any consolidation occurs.

• Typical contents: Raw hook payloads, temporary session state, unprocessed user inputs
• Persistence: In-memory only; ephemeral unless promoted
• Use case: Capturing streaming data during an active conversation or task

In crates/ai-memory-core/src/page.rs, the Tier enum defines this as the base variant. The CLI exposes it via --tier working for direct writes.

Episodic Tier: Time-Bounded Archives

The Episodic tier represents the first consolidation step. It groups recent working-tier observations into logical, timestamped episodes.

• Typical contents: Conversation summaries, task logs, event clusters bound by time
• Organization: Chronological episode groupings with automatic extraction triggers
• Promotion trigger: When raw observations form a coherent, bounded interaction

This tier appears in both docs/research-karpathy-llm-wiki.md#L69 and docs/research-agentmemory.md#L41 as the standard second step in the working → episodic → semantic → procedural flow.

Semantic Tier: Immutable Facts

The Semantic tier stores distilled, long-term factual knowledge extracted from episodic episodes. These are immutable concepts retrievable across any session.

• Typical contents: Named entities, key-value facts, knowledge-graph triples, verified assertions
• Storage: Persistent SQLite records with the tier column set to 'semantic'
• Schema location: The pages table schema in docs/ARCHITECTURE.md#L293 defines this as the primary retrieval tier for factual queries

The ai-memory query --filter-tier semantic command restricts searches to this tier, leveraging the indexed tier column for performance.

Procedural Tier: Reusable Patterns

The Procedural tier sits at the hierarchy's apex, capturing reusable workflows and recipes distilled from frequently-accessed semantic items.

• Typical contents: "How-to" guides, command templates, pattern-matching rules, validated workflows
• Creation: Built automatically when semantic facts demonstrate repeated usage patterns
• Value: Eliminates reasoning from scratch; provides executable, authoritative procedures

How Tiers Are Defined in the Source Code

The Tier enum in crates/ai-memory-core/src/page.rs#L22-L33 provides the canonical implementation:

// From crates/ai-memory-core/src/page.rs
pub enum Tier {
    Working,
    Episodic,
    Semantic,
    Procedural,
}

Each variant serializes to a string stored in the pages.tier database column. The ai-memory-wiki crate's write.rs handles frontmatter parsing to populate this field from markdown sources.

Practical Usage Examples

Writing to a Specific Tier via CLI

# Capture a permanent, searchable fact

ai-memory write \
  --title "Rust-String-Concat-Fact" \
  --tier semantic \
  --body "In Rust, `format!` creates a new `String` without allocating a temporary buffer."

The --tier flag validates against the four allowed strings before persistence.

Storing a Procedural Workflow via API

POST /api/v1/pages
{
  "title": "Git-Commit-Procedure",
  "tier": "procedural",
  "kind": "procedure",
  "tags": ["git", "workflow"],
  "body": "- `git add .`\n- `git commit -m \"msg\"`\n- `git push`"
}

Server-side validation ensures "tier" matches one of the four enum variants.

Filtering Queries by Tier

ai-memory query \
  --query "rust string concat" \
  --filter-tier semantic

This generates SQLite SQL with WHERE tier = 'semantic', optimizing retrieval to authoritative facts rather than ephemeral working notes or lengthy episodes.

Automatic Tier Promotion

The consolidation pipeline automatically migrates data upward through the hierarchy:

1. Working observations accumulate during active sessions
2. Episodic summaries form when sessions conclude or boundaries are detected
3. Semantic facts extract when episodes are analyzed for persistent entities
4. Procedural patterns emerge from semantic clusters showing repeated query+response patterns

This flow—explicitly documented in docs/research-karpathy-llm-wiki.md as the "LLM Wiki v2" architecture—ensures knowledge density increases while noise filters out at each stage.

Summary

• Four tiers structure all ai-memory data: Working, Episodic, Semantic, and Procedural
• Working holds raw, ephemeral session data; Procedural stores reusable expertise
• Source definition: Tier enum in crates/ai-memory-core/src/page.rs#L22
• Schema storage: tier column in the pages table per docs/ARCHITECTURE.md#L293
• CLI/API exposure: --tier flag and JSON tier field accept the four string variants
• Automatic promotion: Consolidation pipeline elevates data through tiers based on usage patterns

Frequently Asked Questions

How do I choose which tier to use when writing data?

Select Working for debugging and temporary capture, Episodic for conversation logs you may revisit soon, Semantic for facts you want permanently searchable, and Procedural only for validated, reusable workflows. The system can promote automatically, so starting with Episodic or Semantic is usually sufficient.

Can I manually promote data between tiers?

Yes. The CLI and API accept explicit --tier or "tier" values on write. The ai-memory-wiki crate's write path in crates/ai-memory-wiki/src/write.rs processes these assignments. Automatic promotion also occurs during consolidation, but manual override ensures immediate placement.

Where is the tier information actually stored?

The tier string persists in the SQLite pages table as defined in docs/ARCHITECTURE.md#L293. The Tier enum in crates/ai-memory-core/src/page.rs handles Rust-side type safety and serialization. Queries filter against this indexed column for performance.

Do all four tiers support the same query features?

All tiers are queryable, but Semantic and Procedural tiers receive priority ranking in retrieval. The --filter-tier flag restricts scope, while unfiltered queries weight higher tiers more heavily according to the M8 policy documented in the architecture overview.

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