causal-memory
CloudGitHub

INTEGRATION

causal-memory with Cursor

The same repository, the same compaction problem. Cursor gets a causal record that survives the context window.

Updated · English

Before you start

Cursor with MCP enabled, and the causal-memory server on your PATH (pip install causal-memory, or a release binary).

Three steps

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

  1. 01

    Install the server

    Install the CLI so the command resolves on PATH. Cursor launches MCP servers with your shell environment, so a binary in ~/.local/bin or /usr/local/bin is enough.

    pip install causal-memory
  2. 02

    Add the MCP server

    Create or edit ~/.cursor/mcp.json for a user-wide registration, or .cursor/mcp.json inside the repository to scope memory to that project. Restart Cursor after saving.

    cursor → Settings → MCP → add a server, or edit the JSON directly
  3. 03

    Install the skill

    Cursor reads agent skills; the same skill that works with Claude Code works here. Without it the tools are available but rarely called.

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

    Verify

    Open a chat, ask for a causal search, and confirm the tool call appears in the MCP panel. A fresh store returns an empty list — that is a successful call, not a failure.

Configuration

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

~/.cursor/mcp.json (or .cursor/mcp.json in the repo)json
{
  "mcpServers": {
    "causal-memory": {
      "command": "causal-memory",
      "args": [],
      "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

  • A repository-scoped .cursor/mcp.json keeps a client project's memory separate from your other work.
  • If the server does not appear, check that the command resolves from a non-login shell — Cursor may not load your full profile.
  • Multiple Cursor windows share the same SQLite file unless you override CAUSAL_MEMORY_DB.
  • The HTTP transport is available if you would rather run one server for several clients.

Cursor setup questions

Does Cursor support MCP servers?
Yes. Cursor reads mcpServers from ~/.cursor/mcp.json or a project-level .cursor/mcp.json, which is the same shape used by Claude Code and most MCP clients.
Why does the server not start?
The usual cause is PATH: a GUI-launched editor may not see a shell alias or a virtualenv-only install. Use an absolute path in the command field, or install the binary somewhere on the system PATH.
Can I use the hosted endpoint instead of a local file?
Yes, if you have a cloud memory token. Point the client at the hosted MCP endpoint with the token in the environment instead of launching a local command. The tool surface is the same 17 tools.
Will Cursor call the tools on its own?
Sometimes, but not reliably. The skill exists because proactive memory use is a behaviour, not a capability; install it and the agent gets explicit instructions for when to recall and when to record.
Does this work with Cursor's agent mode?
Yes. MCP tools are available to the agent in chat and in agent mode; the difference is that agent mode can chain a recall, an edit and a record in one turn.

Related

Comparison

Use case

Integration

Wire it into Cursor 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