| name | agentdb-causal-explain |
| description | Walk the causal graph in AgentDB to explain why two memories are connected, or trace a root cause. Use when the user asks "why did X happen", "what led to Y", or after an incident. |
Causal Explain
Given a target memory (an episode, a failed test, an outgoing change), traverse the causal graph backwards through edges to surface the chain of preceding events that explain it.
When to use
- "Why did this fail?"
- "What led to the regression?"
- "Trace the dependency chain for X."
- Incident postmortem — surface every step + decision that contributed.
API
agentdb_causal_explain(
targetMemoryId: <id>
maxDepth?: 3
minConfidence?: 0.5
edgeWeights?: 'uplift' | 'confidence' | 'product' // ranking strategy
)
Returns a path or DAG of (node, edge, node) tuples ranked by combined confidence × |uplift|. Each step carries the relation (caused, supersedes, depends-on, etc.) so the explanation reads naturally.
Output shape
Why did "deploy-2026-05-04 failed migration" happen?
┌─ skill[migrate-add-not-null-column] confidence 0.92
│ ─[supersedes]→ skill[v1: migrate-with-default]
│ ─[caused]→ episode[long-running migration on 50M rows]
│ ─[caused]→ episode[deploy-2026-05-04 failed migration]
│
└─ adr[ADR-046: zero-downtime migration policy] confidence 0.78
─[depends-on]→ skill[migrate-add-not-null-column]
Use the investigator agent
For complex traces, dispatch the agentdb-investigator agent (this plugin) — it walks deeper, cross-references with hierarchical memory, and writes a postmortem-shaped report.
Don't
- Don't traverse with
maxDepth > 5 casually — graph fan-out gets exponential and the bandit's confidence weights don't compensate.
- Don't ignore the
confidence column. A high-uplift edge with confidence 0.3 is gossip, not evidence.
