Engramma

Causal Reasoning

intermediate

Ask 'what if?' and 'why?' to your memories. Engramma builds causal relationships between facts and lets you query them.

Beyond correlation

Most memory systems tell you what is similar. Engramma tells you why things are connected and what would happen if something changed.

This is the difference between "these two facts are related" and "this fact caused that outcome." Engramma builds and maintains a causal graph across your memories.

Three levels of causal queries

Engramma supports three levels of causal reasoning, inspired by Judea Pearl's causal ladder:

Level 1: Association

"What is related to X?"

This is what vector databases do — find similar items. Engramma does this too, but it's just the starting point.

# Level 1: Association (what's related?)
results = client.retrieve("deployment issues")

# Returns memories associated with deployments:
# - "Last deploy failed due to memory limits"
# - "Deployment window is Tuesday 2-4pm"
# - "The staging environment mirrors production"

Level 2: Intervention

"What happens if I do X?"

This goes beyond correlation. The engine can reason about the effects of an action based on stored causal relationships.

# Level 2: Intervention (what if?)
# First, store facts that form a causal chain
client.store("Increasing memory limits fixes OOM crashes")
client.store("OOM crashes cause deployment rollbacks")
client.store("Deployment rollbacks trigger PagerDuty alerts")

# Ask a causal intervention question
results = client.retrieve(
    "What happens if we increase memory limits?",
    causal=True
)

# The engine traces the causal chain:
# increase memory → fewer OOM crashes → fewer rollbacks → fewer alerts
print(results[0].text)         # "Increasing memory limits fixes OOM crashes"
print(results[0].causal_chain) # ["OOM crashes cause deployment rollbacks",
                               #  "Deployment rollbacks trigger PagerDuty alerts"]

Level 3: Counterfactual

"Would Y have happened if X hadn't occurred?"

The most powerful level. The engine reasons about alternative histories using the causal graph.

# Level 3: Counterfactual (what would have happened?)
results = client.retrieve(
    "Would we have had alerts if memory was already increased?",
    causal=True
)

# The engine reasons backwards through the causal chain:
# more memory → no OOM → no rollback → no alerts
print(results[0].text)
# "Deployment rollbacks trigger PagerDuty alerts"
print(results[0].counterfactual)
# "If memory limits were increased, the causal chain to alerts would be broken"

You don't need to explicitly tell Engramma which facts are causally related. The engine discovers causal relationships automatically:

  1. Temporal co-occurrence — Facts stored close in time are candidates for causal links
  2. Semantic direction — "X causes Y" patterns are detected in stored text
  3. Retrieval patterns — If querying A frequently leads to accessing B, a link strengthens
  4. Consolidation — During sleep cycles, weak causal links are pruned and strong ones are reinforced
Info

Causal discovery improves over time. The more memories you store and retrieve, the better the causal graph becomes. This is one reason consolidation cycles matter.

Querying the causal graph

You can explicitly ask about causal relationships using the engine's advanced endpoints:

# Get causal neighbors of a fact
neighbors = client.causal_neighbors(
    query="deployment failures",
    direction="both",  # upstream | downstream | both
    depth=2
)

for n in neighbors:
    print(f"{n.direction}: {n.text} (strength: {n.strength})")

# Output:
# upstream: "Code changes without tests" (strength: 0.82)
# upstream: "Memory limits too low" (strength: 0.76)
# downstream: "Deployment rollbacks" (strength: 0.91)
# downstream: "Team on-call fatigue" (strength: 0.64)

Real-world use cases

Use caseHow causal reasoning helps
Incident response"What caused this outage?" — trace back through causal chain
User preferences"Why does the user prefer dark mode?" — connect to past interactions
Knowledge base"What's affected if we deprecate this API?" — trace downstream effects
Decision support"What's the impact of hiring 3 more engineers?" — project causal outcomes

Causal strength

Each causal link has a strength score (0-1) that indicates how reliably A leads to B:

  • Strong (> 0.8): Near-certain causal relationship. "Memory exhaustion causes OOM crashes."
  • Moderate (0.5-0.8): Likely causal but with exceptions. "Late deployments correlate with incidents."
  • Weak (< 0.5): Possible relationship, needs more evidence. May be pruned during consolidation.
Tip

Causal links strengthen every time the relationship is observed and weaken when evidence contradicts them. Store contradicting facts to update the causal graph — Engramma handles belief revision automatically.

Limitations

Causal reasoning is powerful but has boundaries:

  • Not a knowledge graph — Engramma doesn't store explicit RDF triples. Causal links are learned, not declared.
  • Requires evidence — At least 2-3 related facts are needed before causal links form reliably.
  • Temporal scope — Very old causal links may weaken if never reinforced (by design — the world changes).
  • Correlation ≠ causation — The engine uses heuristics. Strong correlations may be flagged as causal links that aren't truly causal. Use the explain() endpoint to inspect link quality.

Next steps

Memory TypesConsolidation