Regimes

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) vs. easing back onto the highway after a detour (carefully returning to speed). Engramma does the same with memory operations.

The four 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.

curl -s https://api.engramma.dev/v1/memory/regime \
  -H "X-API-Key: $ENGRAMMA_API_KEY" | jq .

# Response:
# {
#   "regime": "normal",
#   "anomaly_active": false,
#   "policy_overrides": {
#     "force_exact": false,
#     "bypass_consolidation": false,
#     "learning_rate_multiplier": 1.0
#   },
#   "modulation_signal": 0.67
# }

high_surprise

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

# After storing many memories about a completely new topic,
# the regime shifts to high_surprise:
curl -s https://api.engramma.dev/v1/memory/regime \
  -H "X-API-Key: $ENGRAMMA_API_KEY" | jq .

# Response:
# {
#   "regime": "high_surprise",
#   "anomaly_active": false,
#   "policy_overrides": {
#     "force_exact": false,
#     "bypass_consolidation": true,
#     "learning_rate_multiplier": 2.5
#   },
#   "modulation_signal": 0.92
# }

What you observe:

• Confidence scores may be lower than usual (the engine is less certain)
• More diverse results returned (wider exploration)
• learning_rate_multiplier increases above 1.0 (faster adaptation)
• The engine exits high_surprise 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.

curl -s https://api.engramma.dev/v1/memory/regime \
  -H "X-API-Key: $ENGRAMMA_API_KEY" | jq .

# Response:
# {
#   "regime": "anomaly",
#   "anomaly_active": true,
#   "policy_overrides": {
#     "force_exact": true,
#     "bypass_consolidation": true,
#     "learning_rate_multiplier": 0.1
#   },
#   "modulation_signal": 0.15
# }

What you observe:

• Fewer results (only high-confidence matches returned)
• force_exact is enabled — fuzzy matching is suppressed
• learning_rate_multiplier drops near zero (the engine resists learning while uncertain)
• Anomaly regime resolves automatically once patterns stabilize, transitioning to recovery

recovery

The cool-down state after an anomaly resolves. The engine has detected that conditions are stabilizing but hasn't fully returned to normal. It gradually loosens constraints — consolidation resumes, plasticity ticks back up, and thresholds relax toward their default values.

curl -s https://api.engramma.dev/v1/memory/regime \
  -H "X-API-Key: $ENGRAMMA_API_KEY" | jq .

# Response:
# {
#   "regime": "recovery",
#   "anomaly_active": false,
#   "policy_overrides": {
#     "force_exact": false,
#     "bypass_consolidation": false,
#     "learning_rate_multiplier": 0.5
#   },
#   "modulation_signal": 0.42
# }

What you observe:

• anomaly_active has returned to false
• learning_rate_multiplier is between the anomaly floor and the normal baseline (ramping up)
• Consolidation resumes to catch up on deferred work
• The engine transitions back to normal once the modulation signal stabilizes

Regime transitions

Regimes shift automatically based on observed behavior:

                novelty detected
    Normal ─────────────────────────→ High Surprise
      ↑                                     │
      │         patterns stabilize          │
      ←─────────────────────────────────────┘

                anomaly detected
    Normal ─────────────────────────→ Anomaly
                                         │
              stabilizing                │
    Recovery ←───────────────────────────┘
      │
      │         full stabilization
      └─────────────────────────────→ Normal

Regime history

You can query the history of regime transitions to understand how your memory space has been behaving:

curl -s https://api.engramma.dev/v1/memory/regime/history \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"last_n": 50}' | jq .

# Response:
# {
#   "history": ["normal", "high_surprise", "anomaly", "recovery", "normal"],
#   "distribution": {
#     "normal": 0.72,
#     "high_surprise": 0.15,
#     "anomaly": 0.08,
#     "recovery": 0.05
#   },
#   "transitions": 12
# }

How regimes affect your application

Building regime-aware applications

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

import requests

response = requests.get(
    "https://api.engramma.dev/v1/memory/regime",
    headers={"X-API-Key": ENGRAMMA_API_KEY}
)
regime_data = response.json()
current = regime_data["regime"]

if current == "high_surprise":
    # The engine is learning — show more results to users
    results = retrieve(query, top_k=10)
    response_text = "I'm still learning about this topic. Here are several relevant memories:"
elif current == "anomaly":
    # Something unusual is happening — be cautious
    results = retrieve(query, top_k=3)
    response_text = "I'm being extra careful with my answers right now."
elif current == "recovery":
    # Engine is stabilizing after an anomaly
    results = retrieve(query, top_k=5)
    response_text = "Returning to normal — results may broaden shortly."
else:
    # Normal operation
    results = retrieve(query, top_k=5)
    response_text = results[0]["text"] if results[0]["confidence"] > 0.7 else "I'm not sure about that."

Testing with inject-anomaly

You can simulate an anomaly to test how your application handles regime transitions. This is useful for verifying your safety circuits and regime-aware logic work correctly:

# Inject a test anomaly
curl -s -X POST https://api.engramma.dev/v1/memory/regime/inject-anomaly \
  -H "X-API-Key: $ENGRAMMA_API_KEY" \
  -H "Content-Type: application/json"

# Now check the regime — it should be "anomaly"
curl -s https://api.engramma.dev/v1/memory/regime \
  -H "X-API-Key: $ENGRAMMA_API_KEY" | jq .regime
# "anomaly"

The modulation signal

The modulation_signal field (0.0 to 1.0) provides a continuous measure of how "activated" the engine currently is. Rather than relying solely on discrete regime labels, you can use this value for fine-grained adaptation:

• 0.0 - 0.3: Low activation (anomaly territory, engine is suppressing activity)
• 0.3 - 0.6: Moderate activation (recovery or calm normal)
• 0.6 - 0.8: Standard activation (typical normal operation)
• 0.8 - 1.0: High activation (high_surprise, engine is actively exploring)

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