Engramma

Triggering Consolidation

intermediate

Learn when and how to trigger memory consolidation cycles — scheduling patterns, monitoring, and best practices.

What you'll build

A consolidation strategy for your application — knowing when to trigger sleep cycles, how to monitor their effects, and how to schedule them for optimal memory health.

Prerequisites

RequirementDetails
AccountFree tier or above
API keyFrom your dashboard
SDKPython or JavaScript
KnowledgeFamiliarity with Consolidation concepts
Time~10 minutes

When to trigger consolidation

ScenarioTrigger typeRecommendation
Normal usageAutomaticLet the engine handle it
After bulk importManualTrigger immediately after import completes
High redundancy detectedManualCheck stats, consolidate if redundancy > 0.3
Before a critical demoManualEnsure memory space is optimized
On a scheduleCron/scheduledNightly or weekly for high-volume apps

Steps

1

Check if consolidation is needed

Query stats to see redundancy score, pattern count, and time since last consolidation.
2

Preview the effects

Run a preview to see what would be merged, pruned, and strengthened — without executing.
3

Trigger consolidation

Execute the cycle and observe results.
4

Verify the outcome

Check stats again to confirm improvement.
5

Set up monitoring

Track consolidation metrics over time to understand your memory space's health.

Complete code

import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

# Step 1: Check current health
stats = client.stats()
print(f"Patterns: {stats.patterns_count}")
print(f"Redundancy score: {stats.redundancy_score}")
print(f"Last consolidation: {stats.last_consolidation}")
print(f"Avg importance: {stats.avg_importance}")

# Step 2: Preview what would happen
preview = client.consolidate_preview()
print(f"\nPreview:")
print(f"  Would merge: {preview.merge_candidates} patterns")
print(f"  Would prune: {preview.prune_candidates} patterns")
print(f"  Would strengthen: {preview.strengthen_candidates} patterns")

# Step 3: Decide and execute
if preview.merge_candidates > 5 or preview.prune_candidates > 10:
    print("\nTriggering consolidation...")
    result = client.consolidate()
    print(f"  Before: {result.patterns_before} patterns")
    print(f"  After: {result.patterns_after} patterns")
    print(f"  Merged: {result.merged}")
    print(f"  Pruned: {result.pruned}")
    print(f"  Strengthened: {result.strengthened}")
    print(f"  Duration: {result.duration_ms}ms")
else:
    print("\nNo consolidation needed — memory space is healthy.")

# Step 4: Verify
stats_after = client.stats()
print(f"\nAfter consolidation:")
print(f"  Patterns: {stats_after.patterns_count}")
print(f"  Redundancy: {stats_after.redundancy_score}")

Scheduling patterns

After bulk imports

# Import a batch of documents
for doc in documents:
    client.store(doc.content, metadata={"source": doc.source})

# Always consolidate after bulk operations
result = client.consolidate()
print(f"Post-import consolidation: merged {result.merged}, pruned {result.pruned}")

Nightly scheduled consolidation

# Run nightly via cron job or scheduled task
import os
from engramma_cloud import EngrammaClient

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

# Check if consolidation is worthwhile
stats = client.stats()

if stats.redundancy_score > 0.2:
    result = client.consolidate()
    print(f"Nightly consolidation complete:")
    print(f"  {result.patterns_before} → {result.patterns_after} patterns")
    print(f"  Freed: {result.patterns_before - result.patterns_after} slots")
else:
    print(f"Skipped — redundancy ({stats.redundancy_score}) below threshold")

Threshold-based (in your application)

# Track stores and consolidate every N operations
store_counter = 0

def store_with_auto_consolidation(text, metadata=None, threshold=100):
    global store_counter
    client.store(text, metadata=metadata)
    store_counter += 1
    
    if store_counter >= threshold:
        client.consolidate()
        store_counter = 0

Monitoring consolidation health

Key metrics to track over time:

MetricHealthy rangeAction if outside
redundancy_score< 0.3Consolidate
avg_importance> 0.4Many low-quality memories accumulating — consolidate
patterns_count< 80% of limitApproaching limit — consolidate to free space
causal_links_countGrowing over timeHealthy sign — causal graph is building
Warning

Don't consolidate after every single store operation. Each cycle takes 50-200ms and reorganizes your memory space. Let 50-100 new memories accumulate between cycles for best results.

Tip

Use consolidate_preview() before executing. It's free and lets you decide if the cycle is worth running right now.

Next steps

  • Webhooks Setup — Get notified when consolidation completes
  • Consolidation — Deep dive into what happens during a cycle
  • Regimes — How regime state affects consolidation behavior
Causal QueriesWebhooks Setup