causal-memory
CloudGitHub

INTEGRATION

causal-memory with Claude Code

Claude Code already reads your repository. Give it the one thing a repository cannot store: why a decision was made, and what it prevented.

Updated · English

Before you start

Claude Code with MCP support, and the causal-memory binary available on your PATH. The easiest install is pip; a source build works too.

Three steps

Each step is idempotent; re-running it updates the registration instead of duplicating it.

  1. 01

    Install the server

    The Python package puts the same causal-memory console script on your PATH; running it with no arguments starts the stdio MCP server. If you prefer a source build, build the release binary and use its path instead.

    pip install causal-memory
  2. 02

    Register it with Claude Code

    Add the server to the project's .mcp.json so the registration travels with the repository, or register it once for your user. The command and the JSON below are equivalent — pick one.

    claude mcp add causal-memory -- causal-memory
  3. 03

    Teach the agent when to use it

    The tools work as soon as the server is registered, but agents do not call memory proactively without instruction. Install the bundled skill, which tells the agent when to record a decision and when to recall before acting.

    npx skills add JingxuanC/causal-memory@causal-memory
  4. 04

    Verify

    Ask Claude Code to run a causal search. An empty result is the correct first answer; the point is that the tool call succeeds and the store path is writable.

    search_causal with no query returns the most recent edges, or an empty list on a fresh store.

Configuration

Copy the block, replace nothing if the binary is on PATH, and restart the client once.

.mcp.json in the repository rootjson
{
  "mcpServers": {
    "causal-memory": {
      "command": "causal-memory",
      "env": {
        "CAUSAL_MEMORY_DB": "~/.local/share/causal-memory/causal.db"
      }
    }
  }
}

The five tools to learn first

Seventeen tools are mounted. These five cover the loop: recall, record, warn, attribute, compare.

search_causal

Rank past decisions and outcomes for the task in front of you. Call it before a non-trivial change.

record_decision

Write the decision, the context and the observed outcome as one typed edge. Call it after the outcome exists.

intervention_query

Forward-check an action you are about to take and get the chains it would trigger, including DANGER chains.

trace_cause

Walk backwards from a bad outcome to the decision that caused it. Use it for postmortems.

counterfactual_query

Compare a decision with the alternative you rejected, using recorded evidence rather than recollection.

Gotchas worth knowing

  • The server speaks stdio by default; there is no port to open and no service to keep running.
  • CAUSAL_MEMORY_DB selects the SQLite file. Point different repositories at different files if you want separate memory.
  • The bundled skill is the difference between a mounted tool and a used one — install it before judging the results.
  • Everything stays local unless you configure HTTP embeddings or point the client at the hosted endpoint.

Claude Code setup questions

Do I need a Rust toolchain?
No. pip install causal-memory ships the same CLI and stdio server. A source build is only necessary if you want a specific commit or a feature flag such as local ONNX embeddings.
Where is the memory stored?
In the SQLite file named by CAUSAL_MEMORY_DB, by default ~/.local/share/causal-memory/causal.db. It is a normal SQLite database, so you can inspect it with the sqlite3 CLI.
Why is the first search empty?
A new store has no edges. Memory only becomes useful after record_decision has been called a few times; the skill exists to make the agent do that without being asked each session.
Can I share one memory across a team?
Locally, the file can be shared like any other file, but there is no locking story for concurrent writers. For teams, run the HTTP transport with a token file, which keeps one database per tenant.
Does this change how Claude Code edits files?
No. It adds tools the agent can call. The only behavioural change comes from the skill, which asks the agent to recall before a non-trivial change and record the outcome after.

Related

Comparison

Use case

Integration

Wire it into Claude Code in about three minutes

No account, no API key and no service to operate for local use — one binary and one SQLite file.

GitHubInstall guideCloud memory