Episodic Memory

Long-term storage for experiences, conversations, and events. Organized chronologically with rich metadata and hybrid retrieval. Entries are promoted from Working Memory during sleep consolidation.

Schema

Episodic Memory uses an auto-incrementing rowid with a unique text id:

Indexes

• idx_episodic_session on session_id
• idx_episodic_timestamp on timestamp
• idx_episodic_source on source

FTS5

Full-text search via fts_episodes (content synced from episodic_memory), maintained by INSERT/UPDATE/DELETE triggers.

Vector Search

Embeddings stored in vec_episodes (sqlite-vec, int8[384]), generated at recall time.

Hybrid Scoring

Retrieval combines text and vector signals:

score = (vector_similarity * 0.5) + 
      (fts_rank * 0.3) + 
      (temporal_proximity * 0.2)

Consolidation Pipeline

Episodic entries are created during sleep consolidation, not directly by the agent:

flowchart TD
  WM[Working Memory] -->|age > TTL/2| C{Consolidation}
  C -->|group by source| G[Group entries]
  G -->|summarize| S[LLM or AAAK summary]
  S -->|promote| EM[Episodic Memory]
  C -->|evict originals| DEL[Evict from Working]

The summary_of column in the episodic record tracks which Working Memory entries were consolidated to produce it.

Session Grouping

Episodic entries are grouped by session_id for chronological recall:

# Store with session (goes to Working Memory first)
mem.remember(
  content="User approved the design mockup.",
  session_id="design-review-2026-04-25",
)

# Recall with session filter
results = mem.recall("design mockup", session_id="design-review-2026-04-25")

Performance