> ## Documentation Index
> Fetch the complete documentation index at: https://astron-bb4261fd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory Types

> Understand Z3rno's four-tier memory model.

# Memory Types

Z3rno implements a biologically-inspired four-tier memory model. Each tier has distinct storage characteristics, access patterns, and retention policies.

## Working Memory

Working memory holds the **ephemeral context for the current task**. It is session-scoped, meaning it is created when a session starts and discarded when the session ends.

* **Storage:** Valkey (in-memory)
* **Latency:** Sub-millisecond
* **Retention:** Auto-expires when the session ends or after a configurable idle timeout
* **Use case:** Tracking the current conversation turn, intermediate reasoning steps, tool call results

```python theme={null}
client.store(
    agent_id="agent-1",
    content="User is asking about pricing for the Pro plan.",
    memory_type="working",
)
```

## Episodic Memory

Episodic memory stores **conversation history and event sequences**. Think of it as the agent's autobiographical memory.

* **Storage:** PostgreSQL with temporal indexing
* **Latency:** Low single-digit milliseconds
* **Retention:** Configurable TTL (default: 30 days). Older episodes decay based on importance score.
* **Use case:** Conversation logs, interaction history, temporal queries

```python theme={null}
client.store(
    agent_id="agent-1",
    content="User asked about upgrading from Free to Pro plan.",
    memory_type="episodic",
)
```

## Semantic Memory

Semantic memory stores **facts, knowledge, and user preferences**. This is the agent's long-term knowledge base.

* **Storage:** PostgreSQL with pgvector (vector similarity search)
* **Latency:** Single-digit milliseconds (vector index lookup)
* **Retention:** Long-lived. No default TTL.
* **Use case:** User preferences, learned facts, domain knowledge, entity attributes

```python theme={null}
client.store(
    agent_id="agent-1",
    content="User is on the Pro plan, based in London, prefers metric units.",
    memory_type="semantic",
)

# Recall via natural language
results = client.recall(
    agent_id="agent-1",
    query="What plan is the user on?",
    memory_type="semantic",
    top_k=3,
)
```

## Procedural Memory

Procedural memory stores **learned behaviours, workflow patterns, and decision rules**. This is the agent's muscle memory.

* **Storage:** PostgreSQL with Apache AGE (graph relationships)
* **Latency:** Low single-digit milliseconds (graph traversal)
* **Retention:** Permanent. Procedural memories are never auto-expired.
* **Use case:** Learned workflows, decision trees, behavioural patterns, tool usage sequences

```python theme={null}
client.store(
    agent_id="agent-1",
    content="When user asks about pricing, always start with the value proposition.",
    memory_type="procedural",
)
```

## Comparison

| Tier           | Scope           | Lifespan         | Storage               | Access Pattern    | Latency |
| -------------- | --------------- | ---------------- | --------------------- | ----------------- | ------- |
| **Working**    | Current session | Session duration | Valkey                | Key lookup        | Sub-ms  |
| **Episodic**   | Past sessions   | Configurable TTL | PostgreSQL            | Temporal query    | 2-5ms   |
| **Semantic**   | All time        | Long-lived       | PostgreSQL + pgvector | Vector similarity | 5-10ms  |
| **Procedural** | All time        | Permanent        | PostgreSQL + AGE      | Graph traversal   | 5-15ms  |

## Memory Transitions

Memories naturally flow between tiers:

1. **Working to Episodic:** When a session ends, relevant working memories are consolidated into episodic memories.
2. **Episodic to Semantic:** Repeated patterns across episodes are summarised and promoted to semantic memory.
3. **Episodic to Procedural:** Learned behaviours extracted from episode sequences are stored as procedural memory.

These transitions can happen automatically (via the memory lifecycle engine) or explicitly (via API calls). See [Memory Lifecycle](/concepts/memory-lifecycle) for details.