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

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

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

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

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 for details.