Five Memory Stores

Overview

Cerememory implements five specialized memory stores, each modeled after a distinct region of the human brain. Every store implements the same Store trait, but each has unique characteristics for what it stores, how fast memories decay, and how they interact with other stores.

Store Comparison

Episodic Store (Hippocampus)

The episodic store holds personal experiences and events -- what happened, when, and in what context. This is the default destination for new memories when no store is explicitly specified.

Key characteristics:

• Medium decay rate -- Episodic memories fade at a moderate pace unless reinforced through recall
• Rich context -- Stores temporal, spatial, and session context alongside content
• Consolidation source -- During consolidation, episodic memories that meet age and access thresholds are migrated to the semantic store as distilled knowledge
• Association-rich -- Temporal and sequential associations are automatically created between episodic memories stored in the same session

// Episodic memories capture experiences
let record = MemoryRecord::new_text(
    StoreType::Episodic,
    "User asked about Rust async patterns and I explained tokio::spawn",
);

Semantic Store (Neocortex)

The semantic store holds facts, knowledge, and conceptual understanding -- the "what" rather than the "when." Semantic memories are distilled from repeated episodic experiences or stored directly as factual knowledge.

Key characteristics:

• Slow decay rate -- Knowledge persists much longer than episodic memories
• Consolidation target -- Receives distilled memories from the episodic store during consolidation
• Compression -- Over time, related semantic memories are compressed and summarized
• Relation extraction -- When an LLM provider is configured, semantic memories undergo relation extraction to build a knowledge graph

Procedural Store (Basal Ganglia)

The procedural store holds skills, workflows, and habitual patterns -- the "how." These memories represent learned behaviors that become more stable with repetition.

Key characteristics:

• Very slow decay -- Procedural memories are among the most persistent
• Repetition reinforcement -- Each time a procedural memory is accessed, its stability increases significantly
• Structured content -- Often stores structured data (JSON) representing workflows or step-by-step procedures

Emotional Store (Amygdala)

The emotional store holds emotionally significant memories. The emotional dimension uses Plutchik's 8-dimensional model to represent affective state.

Key characteristics:

• Emotion-anchored decay -- Higher emotional intensity leads to slower decay via the emotional modulation factor
• Cross-store influence -- Emotional tags on any memory (in any store) modulate that memory's decay rate
• Valence tracking -- Each emotion has a valence from -1.0 (negative) to +1.0 (positive)

The eight primary emotions and their valences:

Working Store (Prefrontal Cortex)

The working store holds active context and short-term information -- the current "mental workspace." Unlike all other stores, working memory is entirely in-memory and does not persist across restarts.

Key characteristics:

• Fast decay -- Working memory items have the highest decay rate
• Capacity-limited -- Has a configurable maximum capacity (default: 7 slots, inspired by Miller's Law); when capacity is exceeded, the least recently used (LRU) record is silently evicted
• Promotion -- Important working memory items can be promoted to the episodic store for long-term retention
• Volatile -- Data is lost on server restart

Raw Journal Store

The raw journal is a separate preservation plane that operates alongside the five curated stores. It holds verbatim conversation content exactly as received, without any curation, decay, or noise processing.

Key characteristics:

• No decay -- Raw journal entries are preserved indefinitely with full fidelity
• Forensic recall -- Full-text search over preserved content via a dedicated Tantivy index
• Session-indexed -- Entries are grouped by session and can be filtered by speaker, source, and topic
• Dream processing -- The lifecycle.dream_tick operation summarizes raw entries into curated episodic/semantic memories, with backlinks to the source entries
• Secrecy-aware -- Entries marked as secret are redacted during dream summarization; sensitive entries receive partial redaction
• Suppression -- Individual entries can be suppressed to exclude them from future dream processing

// Raw journal entries preserve exact conversation content
let raw = RawJournalRecord {
    session_id: "sess_001".into(),
    source: RawSource::Conversation,
    speaker: RawSpeaker::User,
    secrecy_level: SecrecyLevel::Public,
    content: MemoryContent::text("I prefer using Neovim for everything"),
    ..Default::default()
};

Meta-Memory Plane

Meta-memory is a cross-cutting plane attached to both curated memories and raw journal records. It preserves the why around every memory rather than storing another content item.

Key characteristics:

• Typed rationale -- MetaMemory stores intent, rationale, trigger, goals, assumptions, alternatives, decisions, confidence, and evidence references
• Explicit absence -- new records without a supplied rationale receive an unavailable capture status instead of fabricated reasoning
• Lifecycle traceability -- engine-generated records, such as dream summaries, receive inferred meta-memory explaining why they were created
• Context graph -- MetaEdge relations such as derived_from, motivated_by, supports, and chose_over connect rationale across memories
• Opt-in graph exposure -- recall.graph returns meta and meta_edges only when include_meta is true

The Store Trait

All five curated stores implement the same Store trait, providing a uniform interface:

pub trait Store: Send + Sync {
    fn store(&self, record: MemoryRecord) -> impl Future<Output = Result<Uuid>>;
    fn get(&self, id: &Uuid) -> impl Future<Output = Result<Option<MemoryRecord>>>;
    fn delete(&self, id: &Uuid) -> impl Future<Output = Result<bool>>;
    fn update_fidelity(&self, id: &Uuid, fidelity: FidelityState) -> impl Future<Output = Result<()>>;
    fn query_text(&self, query: &str, limit: usize) -> impl Future<Output = Result<Vec<MemoryRecord>>>;
    fn list_ids(&self) -> impl Future<Output = Result<Vec<Uuid>>>;
    fn count(&self) -> impl Future<Output = Result<usize>>;
    fn update_record(&self, id: &Uuid, ...) -> impl Future<Output = Result<()>>;
    fn update_access(&self, id: &Uuid, ...) -> impl Future<Output = Result<()>>;
}

Next Steps