# Agentdb Causal Link

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

- Skill: `ruvnet-agentdb/agentdb-causal-link` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ruvnet-agentdb/agentdb-causal-link`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruvnet-agentdb/agentdb-causal-link/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ruvnet (https://skillmd.com/u/ruvnet-agentdb)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ruvnet-agentdb/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.