Do I need to change my coding agent to use this?

No. causal-memory is an MCP server, so it mounts into Claude Code, Cursor, DSH or any MCP client. The write discipline is the only new behaviour: the agent has to call record_decision after an outcome is observed, which is what the bundled skill teaches.

Will it slow the agent down?

Two extra tool calls per non-trivial change: one recall before, one record after. Both are local SQLite queries by default, so the latency is far below a model round trip. The intervention check is one more call and only on risky actions.

What if the recorded lesson is wrong later?

Supersede it rather than delete it. Soft supersession (C7) keeps the falsified edge readable for counterfactuals while making the correction visible to the answer model. A deleted lesson cannot explain why an old decision looked correct at the time.

Does this replace code review or tests?

No. It records the reasoning that review and tests cannot reconstruct: which alternative was rejected and what happened when it was tried. Tests tell you whether the code works; causal edges tell you why this approach and not the other one.

Where does the data live?

In one SQLite file (causal.db) on the machine running the server, or in a hosted tenant database if you use cloud memory. Nothing is sent anywhere unless you configure HTTP embeddings or the cloud endpoint.

USE CASE

Causal memory for a coding agent

A coding agent already remembers the diff. Causal memory makes it remember why the diff was wrong the first time.

Updated 2026-10-21 · English

Who this is for

For teams running a coding agent across many sessions in one repository, where context compaction is routine and the same mistake keeps coming back.

The failure mode it fixes

These are not hypothetical; each one is a direct consequence of storing text instead of causal structure.

The diff survives, the reasoning does not
After two or three context compactions the agent still knows what the code looks like, but not why the retry loop was rewritten, which approach was tried first, or what broke when it was tried. The repository is a record of what exists, not of what was rejected.
The same bug gets fixed the same wrong way
A new session starts clean, rediscovers the symptom, and reaches for the first plausible fix — the one that already failed last month. Nothing in the loop marks that approach as known-bad, so the agent has no reason to avoid it.
Architecture debates restart from zero
A choice about queueing, locking or caching was settled with evidence. Six sessions later the agent reopens it with no memory of the evidence, and a human has to re-argue the same trade-off.
The risky command looks routine
A force-push, a migration without a lock, a release during a freeze. The agent has done it before and it went fine — except the time it did not, and that incident is not stored anywhere the agent looks.

How causal memory is used

The loop is always the same three fields — decision, context, outcome — plus one rule: record after the outcome, not before.

Record the decision, not the diff

After a change is merged or reverted, record one edge: the decision, the context it was made in, the observed outcome, and the relation between them. The diff is already in git; what git cannot reconstruct is which alternative was considered and why it was rejected. Keep the payload short enough that an agent will actually call the tool.

relation: caused when the decision produced the outcome, enabled when it contributed, prevented when it stopped something worse.
task_tag: route recall later — backend-performance, migration, release, debugging.
context: language version, scale, constraints. Two decisions with the same task_tag and context become a comparable branch for counterfactual queries.

Recall before editing

Before a non-trivial change, search by task_tag and a short description of the current problem. The result is a ranked list of past decisions with their outcomes, not a pile of similar text. Read the failures first: they are the part a normal context window loses earliest.

Use task_tag alone for a domain sweep, or add query text for a broader semantic match.
Ask for detail_level l0 when you only need to know whether a lesson exists.
Treat a returned edge as evidence to check, not an instruction to follow — the code may have moved on.

Warn before the risky command

Intervention prediction is the difference between a memory and a guardrail. Before a destructive or hard-to-reverse action, ask what happened last time an action like this was taken. A prevented edge returns a DANGER chain instead of silence, because the outcome that was avoided is stored as a typed edge with negative activation.

Run it before force-push, --no-verify, schema migrations, and dependency major bumps.
A DANGER chain is a stop-and-read signal, not an automatic block; the agent still decides.
The chain cites the original decision, so the warning is auditable rather than a vibe.

Retire the belief when it is falsified

When a lesson turns out to be wrong, supersede the edge instead of deleting it. The falsification reaches the answer model, and the old edge stays readable for counterfactual questions. This is the C7 capability: 100% on CausalEval v13, up from 50% in v12 when superseded edges were hidden instead of annotated.

Delete nothing: a wrong lesson is still the evidence that a choice was once reasonable.
Supersession is what keeps the graph from becoming a museum of stale advice.

What the calls look like

The same JSON shape works over stdio MCP, the HTTP transport and the DSH plugin.

1 · Record why the change was made, after it landsjson

{
  "name": "record_decision",
  "arguments": {
    "decision": "replaced the unbounded retry loop with a bounded queue",
    "outcome": "replay stopped dropping events; retries no longer amplify load",
    "relation": "caused",
    "task_tag": "backend-performance",
    "context": "Go 1.22, 4 workers, replay of the ingest backlog"
  }
}

2 · Recall before starting a similar changejson

{
  "name": "search_causal",
  "arguments": {
    "task_tag": "backend-performance",
    "query": "retry amplification under replay",
    "limit": 5,
    "detail_level": "l1"
  }
}

3 · Warn before the command that already went wrong oncejson

{
  "name": "intervention_query",
  "arguments": {
    "action": "push directly to main with --no-verify",
    "task_tag": "release",
    "max_depth": 3
  }
}

What to watch over three months

Track these on your own data. The published numbers are benchmark baselines, not a promise about your repository or your incidents.

Metrics to watch after adopting causal memory
Metric	Reference	How to read it
Repeat-mistake rate	33% vs 67%	Agent repeat-mistake on the trap-world benchmark: causal-memory vs the fact-store baseline. Track the same thing on your own repo by tagging reverted changes that re-apply an already-failed approach.
Causal recall after compaction	100% vs 45%	At 5x context compaction in our harness. This is the metric that decides whether memory survives a long session at all.
Belief revision accuracy	100%	CausalEval C7 after soft supersession was introduced (v12: 50%). Watch for stale advice resurfacing after a lesson is corrected.
Decision coverage	Track weekly	Share of merged changes that have a recorded decision edge. Low coverage means the agent is not calling record_decision — install the skill so it knows when to.
Time to first correct fix	Track per repo	We publish no customer number for this. Measure it from the first failing CI run to the commit that stays merged, and compare before and after adoption.

Benchmark figures come from the causal-memory README and CausalEval v13; see the CausalEval page for protocol and limitations.

Coding agent questions

Do I need to change my coding agent to use this?: No. causal-memory is an MCP server, so it mounts into Claude Code, Cursor, DSH or any MCP client. The write discipline is the only new behaviour: the agent has to call record_decision after an outcome is observed, which is what the bundled skill teaches.
Will it slow the agent down?: Two extra tool calls per non-trivial change: one recall before, one record after. Both are local SQLite queries by default, so the latency is far below a model round trip. The intervention check is one more call and only on risky actions.
What if the recorded lesson is wrong later?: Supersede it rather than delete it. Soft supersession (C7) keeps the falsified edge readable for counterfactuals while making the correction visible to the answer model. A deleted lesson cannot explain why an old decision looked correct at the time.
Does this replace code review or tests?: No. It records the reasoning that review and tests cannot reconstruct: which alternative was rejected and what happened when it was tried. Tests tell you whether the code works; causal edges tell you why this approach and not the other one.
Where does the data live?: In one SQLite file (causal.db) on the machine running the server, or in a hosted tenant database if you use cloud memory. Nothing is sent anywhere unless you configure HTTP embeddings or the cloud endpoint.

Comparison

causal-memory vs mem0mem0 is the better fact store. causal-memory answers the next question: why did that decision work, and what did it prevent?

Use case

Integration

Run it on one real decision

Record a decision you already made, add the outcome when you know it, and ask for it back a week later. That single loop is the whole evaluation.

GitHub Install guide Cloud memory