Consolidation Architecture

ZeroMemory uses two consolidation systems to transform raw episodic memories into durable semantic knowledge.

Overview

Episodic Memories ──► Clustering (daily) ──► Semantic Summaries
                  ──► Reflection (weekly) ──► Entity Profiles + Insights

Clustering (Daily)

Schedule: Daily at 03:30 UTC via Celery beat

Clustering aggregates similar episodic memories into semantic summaries:

1. Groups memories by entity and content similarity
2. Merges clusters into a single semantic memory
3. Marks source memories as state='consolidated'
4. Preserves the highest-importance score from the cluster

Reflection (Weekly)

Schedule: Weekly on Sunday at 04:45 UTC via Celery beat

Reflection uses an LLM to extract structured insights from episodic memories:

1. Finds entities with 10+ unconsolidated episodic memories
2. Sends up to 15 of the 50 most recent episodic/working memories to the LLM
3. LLM extracts: preferences, behavioral patterns, key facts, and a summary
4. Results stored as memory_type='semantic' with importance=0.8
5. Tags: ['reflection', 'insight']
6. Source memories marked state='consolidated'
7. Updates the memory_profiles table with the entity profile

Thresholds

Trigger	Threshold	Scope
Per-entity reflection	10+ episodic memories	Single entity_id
User-wide reflection	50+ episodic memories	User without specific entity

Thresholds are cumulative — once memories are consolidated, they don't count toward future triggers.

Reflection Model

The reflection LLM is resolved in this order:

1. ZEROMEMORY_REFLECTION_MODEL environment variable (highest priority)
2. User's best available model via ModelAccessService
3. Platform default: nemotron-super-49b (NIM-native)

On-Demand Consolidation

Trigger reflection for a specific entity immediately:

POST /api/v1/public/memory/v2/reflect
{
  "entity_id": "user-123",
  "namespace": "global"
}

Response:

{
  "entity_id": "user-123",
  "insights": ["Prefers concise responses", "Works in fintech"],
  "memories_reviewed": 15,
  "new_semantic_memories": 3,
  "profile_updated": true
}

Memory State Machine

raw → consolidated (after clustering/reflection)
raw → archived (after decay threshold)
consolidated → (persists indefinitely)

State	Meaning
raw	Active episodic memory, subject to decay
consolidated	Incorporated into semantic knowledge
archived	Decayed below retention threshold

What Gets Stored After Consolidation

The consolidated semantic memory includes:

• memory_type: 'semantic'
• importance: 0.8 (high, since it survived consolidation)
• tags: ['reflection', 'insight']
• metadata.source_type: 'consolidated'
• metadata.source_count: number of episodic memories merged

The entity profile in memory_profiles includes:

• preferences: array of extracted preferences
• behaviors: array of behavioral patterns
• facts: array of important facts
• summary: natural language summary