Data Flow

How information moves through Mnemosyne's memory tiers.

Write Path

flowchart LR
  A[Agent Input] -->|remember| WM[Working Memory]
  WM -->|index| FI[FTS5 Index]
  WM -->|sleep| SC[Sleep Consolidator]
  SC -->|promote| EM[Episodic Memory]
  EM -->|index| VI[Vector Index + FTS5]
  SC -->|evict| DEL[Deleted]

1. Agent calls remember() with content, source, importance, and optional metadata
2. Working Memory stores the raw entry with metadata in SQLite
3. FTS5 index is updated for full-text search
4. Sleep consolidation (triggered by calling sleep()) processes older entries
5. Promotion summarizes and moves entries to Episodic Memory
6. Vector + FTS5 indexing occurs on the new Episodic entries
7. Eviction removes the original Working Memory entries

Read Path

flowchart LR
  Q[Query] -->|recall| RE[Retrieval Engine]
  RE -->|vector search| VI[sqlite-vec Index]
  RE -->|text search| FI[FTS5 Index]
  VI -->|scores| RF[Rank Fusion]
  FI -->|scores| RF
  RF -->|ranked results| A[Agent]

1. Agent calls recall(query, top_k=5)
2. Query is embedded using BAAI/bge-small-en-v1.5 (384 dims) for vector search
3. Parallel dispatch to vector (sqlite-vec) and text (FTS5) indices
4. Rank Fusion combines scores: vec×0.5 + fts×0.3 + importance×0.2, then applies recency decay: score × (0.7 + 0.3 × recency_decay)
5. Agent receives ranked results

Consolidation Flow

flowchart TD
  START[sleep called] --> SELECT[Select entries older than TTL/2]
  SELECT --> GROUP[Group by source]
  GROUP --> SUMMARIZE[Summarize via LLM or AAAK]
  SUMMARIZE --> PROMOTE[Store summary in Episodic Memory]
  PROMOTE --> INDEX[Index new episodic entry]
  INDEX --> EVICT[Evict originals from Working Memory]

Consolidation is triggered explicitly by calling mem.sleep():

1. Select Working Memory entries older than TTL/2 (default 12 hours)
2. Group candidates by their source field
3. Summarize each group via LLM (if enabled) or AAAK text substitution
4. Promote the summary as a new Episodic Memory entry (with summary_of tracking)
5. Index the new entry in vector and FTS5 indices
6. Evict the original entries from Working Memory

Event Lifecycle