Regimes — Docs

Engramma adapts its behavior based on what it observes. Learn about Normal, Exploration, and Anomaly regimes and what they mean for your application.

An engine that adapts

Most memory systems behave identically regardless of context. Engramma is different — it detects regimes (behavioral states) and adapts its strategy accordingly.

Think of it like driving: you behave differently on a familiar highway (cruise control) vs. an unfamiliar city (alert, slower, checking maps) vs. icy roads (maximum caution). Engramma does the same with memory operations.

The three regimes

Normal

The default state. The engine processes queries efficiently using learned patterns. Retrieval is fast, confidence thresholds are stable, and consolidation follows its regular schedule.

Characteristic	Value
When active	Most of the time (80-90% typical)
Behavior	Standard routing, stable thresholds
Plasticity	Moderate — new memories are encoded normally
Consolidation	Regular schedule
Latency	Lowest (2-5ms retrieve)

stats = client.stats()
print(stats.regime)  # "normal"

# In normal regime, everything works as expected
results = client.retrieve("team meeting schedule")
# Fast, confident results from known patterns

Exploration

Activated when the engine encounters novelty. When queries or stored memories don't match existing patterns well, the engine enters Exploration mode. It widens its search, lowers confidence thresholds, and increases plasticity to learn faster.

Characteristic	Value
When active	New topic areas, unfamiliar query patterns
Behavior	Wider search, lower thresholds, more results returned
Plasticity	High — the engine is learning actively
Consolidation	Deferred (let new patterns stabilize first)
Latency	Slightly higher (5-10ms retrieve)

# After storing many memories about a completely new topic...
client.store("Quantum computing uses qubits instead of bits")
client.store("Shor's algorithm can factor large numbers")
client.store("Quantum decoherence is a major challenge")

stats = client.stats()
print(stats.regime)  # "exploration"

# In exploration regime, the engine casts a wider net
results = client.retrieve("quantum computing applications")
# May return more results with lower confidence
# (the engine is still learning this topic)

What you observe:

Confidence scores may be lower than usual (the engine is less certain)
More diverse results returned (wider exploration)
The engine exits Exploration once it has enough patterns to work with (typically after 10-20 stores in the new domain)

Anomaly

Activated when something unexpected occurs. This could be unusual access patterns, sudden spikes in queries about a dormant topic, or internal consistency issues. The engine becomes cautious.

Characteristic	Value
When active	Unusual patterns, sudden shifts, internal inconsistencies
Behavior	Conservative routing, higher confidence thresholds
Plasticity	Reduced — the engine is cautious about accepting new information
Consolidation	Paused (don't merge when state is uncertain)
Latency	Normal (2-5ms) but fewer results pass threshold

stats = client.stats()
print(stats.regime)  # "anomaly"

# In anomaly regime, the engine is conservative
results = client.retrieve("financial projections")
# Fewer results returned (higher threshold)
# Only high-confidence matches pass

# Check what triggered the anomaly
print(stats.anomaly_reason)
# "Sudden access pattern shift: 50x increase in queries
#  about 'financial' topic in last 5 minutes"

What you observe:

Fewer results (only high-confidence matches returned)
The engine may take longer to accept new memories at full weight
Anomaly regime resolves automatically once patterns stabilize

Info

Anomaly detection is a safety feature, not an error state. It protects your memory space from being corrupted by sudden, unusual inputs (e.g., a bug that stores garbage data in a loop).

Regime transitions

Regimes shift automatically based on observed behavior:

Normal ──── novelty detected ────→ Exploration
  ↑                                      │
  │                                      │
  └──── patterns stabilize ──────────────┘

Normal ──── anomaly detected ───→ Anomaly
  ↑                                      │
  │                                      │
  └──── patterns normalize ──────────────┘

You can also observe regime history:

stats = client.stats()

print(f"Current regime: {stats.regime}")
print(f"Time in regime: {stats.regime_duration_s}s")
print(f"Regime history (last 24h):")
for entry in stats.regime_history:
    print(f"  {entry.timestamp}: {entry.from_regime} → {entry.to_regime}")
    print(f"    Reason: {entry.reason}")

How regimes affect your application

Scenario	Regime	What to expect
Steady usage, known topics	Normal	Fast, confident results
Onboarding new knowledge domain	Exploration	Lower confidence, wider search
Bulk import of new data	Exploration → Normal	Temporary exploration, then stabilization
Sudden spike in unusual queries	Anomaly	Conservative, fewer results
After consolidation cycle	Normal	Refreshed, often improved confidence

Building regime-aware applications

You can check the current regime and adapt your application behavior:

stats = client.stats()

if stats.regime == "exploration":
    # The engine is learning — show more results to users
    results = client.retrieve(query, top_k=10)
    response = "I'm still learning about this topic. Here are several relevant memories:"
elif stats.regime == "anomaly":
    # Something unusual is happening — be cautious
    results = client.retrieve(query, top_k=3)
    response = "I'm being extra careful with my answers right now."
else:
    # Normal operation
    results = client.retrieve(query, top_k=5)
    response = results[0].text if results[0].confidence > 0.7 else "I'm not sure about that."

Regime detection webhooks

You can receive notifications when regimes change:

# Configure webhook for regime changes
client.webhooks.create(
    url="https://your-app.com/hooks/engramma",
    events=["regime.changed"]
)

# Your webhook receives:
# {
#   "event": "regime.changed",
#   "data": {
#     "from": "normal",
#     "to": "exploration",
#     "reason": "12 queries about unfamiliar topic 'quantum computing'",
#     "timestamp": "2026-01-15T14:22:00Z"
#   }
# }

Tip

Monitoring regime changes is one of the best ways to understand how your memory space evolves. Set up a webhook to Slack or your monitoring system to get notified when the engine shifts behavior.

Next steps

How It Works — The full 10-phase cycle including regime detection
Consolidation — How regimes affect consolidation behavior
Webhooks Setup — Configure regime change notifications