Engramma

Consolidation

intermediate

Memories strengthen over time through sleep cycles. Learn how consolidation works, when it triggers, and what you observe as a user.

Memories that improve with age

In biological brains, sleep isn't idle time — it's when memories consolidate. Important experiences strengthen, irrelevant ones fade, and related patterns merge into coherent knowledge.

Engramma works the same way. Consolidation is the process where your memory space actively improves itself — without you re-indexing, re-embedding, or re-uploading anything.

What consolidation does

During a consolidation cycle, Engramma performs four operations:

OperationWhat it doesEffect you observe
StrengtheningFrequently-accessed memories get higher base confidenceImportant memories surface faster
PruningRarely-accessed, low-importance memories decayStorage stays clean, noise decreases
MergingNear-duplicate memories combine into one stronger memoryLess redundancy, clearer results
Link reinforcementCausal links that proved useful strengthenBetter causal reasoning over time

When consolidation happens

Consolidation can trigger in two ways:

Automatic (background)

Engramma runs lightweight consolidation in the background based on activity patterns. You don't need to do anything — it happens automatically when:

  • A threshold number of new memories have been stored (typically 50-100)
  • A significant time period has passed since the last cycle
  • The engine detects increasing redundancy in stored patterns

Manual (on-demand)

You can trigger consolidation explicitly when you want immediate optimization:

# Trigger a consolidation cycle
result = client.consolidate()

print(f"Patterns before: {result.patterns_before}")
print(f"Patterns after: {result.patterns_after}")
print(f"Merged: {result.merged}")
print(f"Pruned: {result.pruned}")
print(f"Strengthened: {result.strengthened}")
print(f"Duration: {result.duration_ms}ms")

Expected response:

{
  "success": true,
  "patterns_before": 1247,
  "patterns_after": 1183,
  "merged": 42,
  "pruned": 22,
  "strengthened": 389,
  "duration_ms": 156
}

The consolidation lifecycle

Here's what happens to a memory over time:

1

Storage

New memory enters with a base importance score. It's immediately retrievable but hasn't been validated by time.
2

First accesses

Each time the memory is retrieved, its access counter increments. Frequently-accessed memories are marked as important.
3

Causal integration

If the memory participates in causal chains (Level 2/3 queries), its links to other memories strengthen.
4

Consolidation cycle

During the next sleep cycle, the memory's importance is recalculated. High-access, causally-linked memories get boosted. Isolated, never-accessed memories decay.
5

Maturity

After several consolidation cycles, the memory reaches a stable importance level. It's now part of the 'long-term' memory and resistant to pruning.

Protecting memories from pruning

Sometimes you want certain memories to persist regardless of access frequency. You can mark memories as protected:

# Store with protection flag
result = client.store(
    "Company was founded in 2024",
    metadata={"protected": True}
)

# Protected memories are never pruned during consolidation
# They can still be strengthened and merged
Warning

Don't over-protect. If you protect everything, consolidation can't clean up noise. Reserve protection for foundational facts that define your application's core knowledge.

Monitoring consolidation health

Check your memory space health with the stats endpoint:

stats = client.stats()

print(f"Total patterns: {stats.patterns_count}")
print(f"Last consolidation: {stats.last_consolidation}")
print(f"Avg importance: {stats.avg_importance}")
print(f"Redundancy score: {stats.redundancy_score}")
print(f"Causal links: {stats.causal_links_count}")

Key metrics to watch:

  • Redundancy score > 0.3 → consider running consolidation
  • Avg importance dropping → many low-quality memories accumulating
  • Patterns count near limit → consolidation will free up space

Best practices

  1. Let automatic consolidation work — For most applications, the default background cycles are sufficient.

  2. Trigger manual consolidation after bulk imports — If you batch-store hundreds of memories at once, trigger a cycle to let the engine organize them.

  3. Monitor before/after — Track patterns_before vs patterns_after to understand how aggressively consolidation is cleaning up.

  4. Don't consolidate too frequently — Each cycle takes 50-200ms. Running it after every single store operation defeats the purpose. Let memories accumulate between cycles.

  5. Use consolidation previews — Before triggering, you can preview what would happen:

# Preview consolidation without executing
preview = client.consolidate_preview()

print(f"Would merge: {preview.merge_candidates}")
print(f"Would prune: {preview.prune_candidates}")
print(f"Would strengthen: {preview.strengthen_candidates}")

# Decide whether to proceed
if preview.prune_candidates > 10:
    client.consolidate()

Analogy: inbox vs. archive

Think of consolidation like email management:

  • New memories = unread emails (recent, uncertain importance)
  • Consolidation = your weekly inbox cleanup (archive what matters, delete noise, group related threads)
  • Mature memories = your organized archive (searchable, categorized, persistent)

The difference: Engramma does this cleanup automatically, and it gets smarter about what matters based on how you use it.

Next steps

Causal ReasoningExplainability