| name | agentdb-causal-link |
| description | Record a causal relationship between two memories in AgentDB — "X caused Y", "A supersedes B", "patch-foo depends-on patch-bar". Use when the user is documenting cause/effect, dependencies, supersessions, or after-action analysis. |
Link Causally
Add a typed edge between two memories so future queries can traverse cause→effect, supersedes, depends-on, etc.
When to use
- User says "X caused Y", "this depends on that", "this supersedes the old one"
- Post-incident analysis — recording what led to what
- Building a knowledge graph from a sequence of episodes
- ADR housekeeping —
supersedes / amends / related-to between architecture decisions
API
agentdb_causal_edge(
fromMemoryId: <id>
fromMemoryType: 'episode' | 'pattern' | 'skill' | 'adr'
toMemoryId: <id>
toMemoryType: <same set>
relation: 'caused' | 'supersedes' | 'depends-on' | 'related-to' | <custom>
similarity?: 0..1
uplift?: -1..1 // signed reward delta
confidence?: 0..1
metadata?: { evidenceCount, sourceTimestamp, ... }
)
uplift is the secret sauce. Positive uplift = the causal link improved outcomes; negative = it hurt. The agentdb-investigator agent (this plugin) walks edges weighted by uplift × confidence to find root causes.
Cascade-aware delete
The agentdb 3.0.0-alpha.13 release added cascade: true semantics:
agentdb_causal_edge_delete(edgeId) — single edgeagentdb_causal_node_delete(nodeId, { cascade: true }) — node + all incident edges; returns deletedEdges countagentdb_edges_by_endpoints(from, to, label?) — bulk delete by tuple
Use cascade when removing an obsolete ADR or decommissioning an agent — leaving dangling edges in the graph poisons future traversals.
Don't
- Don't link memories without confidence < 0.5 unless you mark them as conjectures. Low-confidence edges accumulate and degrade
agentdb_causal_explain quality.
- Don't use
caused for correlation — reserve it for genuinely causal evidence (controlled change, repeated observation, expert confirmation).
- Don't forget the inverse direction. "A supersedes B" implies B is no longer authoritative; tag B's hierarchical entry as deprecated in the same operation.
