---
title: "Consolidation Architecture"
description: "How ZeroMemory consolidates episodic memories into semantic knowledge — triggers, thresholds, and schedules."
canonical: "https://docs.ainative.studio/docs/zeromemory/consolidation"
last-updated: "2026-10-03T21:47:10.764Z"
---

# Consolidation Architecture

Source: https://docs.ainative.studio/docs/zeromemory/consolidation

> How ZeroMemory consolidates episodic memories into semantic knowledge — triggers, thresholds, and schedules.

# 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:

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

**Response:**
```json
{
  "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