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

> Explore the four memory tiers in ai-memory: Working, Episodic, Semantic, and Procedural. Understand how they mimic human cognition for advanced AI.

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

---

**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`](https://github.com/akitaonrails/ai-memory/blob/main/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:

```rust
// 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`](https://github.com/akitaonrails/ai-memory/blob/main/write.rs) handles frontmatter parsing to populate this field from markdown sources.

## Practical Usage Examples

### Writing to a Specific Tier via CLI

```bash

# 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

```json
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

```bash
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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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`](https://github.com/akitaonrails/ai-memory/blob/main/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.