agentdb-causal-link

# 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 edge - `agentdb_causal_node_delete(nodeId, { cascade: true })` — node + all incident edges; returns deletedEdges count - `agentdb_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.