causal-memory MCP
causal-memory keeps decision-to-outcome links outside agent context, so reasons for past choices survive compaction.
- 107 ★ on the repository
- Last commit
- Apache-2.0
Extended access
Why this level
- Memory stores decision records on disk in plain form.
- In HTTP mode the service endpoints expose stored content unless a token is set.
Install
- Works in
Manual install
git clone https://github.com/JingxuanC/causal-memory.git
cd causal-memory
cargo build --releaseThe first Quick start option in the README builds from source. Without Rust use `pip install causal-memory`; ready installers live in `integrations/claude-code/` and `integrations/codex/`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Memory stores decision records on disk in plain form.
- In HTTP mode the service endpoints expose stored content unless a token is set.
This is third-party code. Review the repository files before installing.
What it does
causal-memory is an agent memory MCP server that keeps facts, temporal state and decision-to-outcome causal edges in one SQLite store. Recall walks a graph with excitatory and inhibitory links, so an agent can recover what happened, when it was true and why it worked. Tools include `record_decision` for writing, `search_causal` for experience lookup, `counterfactual_query` for comparing options and `intervention_query`, which warns about a risky step based on a recorded lesson. The server runs over stdio or as MCP over HTTP, and a bundled skill teaches the agent to call the memory unprompted.
Who it is for. People running long coding-agent sessions who are tired of agents repeating old mistakes after context compaction.
Good fit when
- An agent fixes the same bug the same wrong way for the third time.
- A team wants the agent to recall a past failure before a risky command.
- Several agents must share one decision memory over HTTP.
- Two options need comparing against recorded outcomes of earlier attempts.
Not a fit when
- Memory of user facts is the goal; the author admits mem0 is stronger there.
- A decision log cannot be stored on disk in plain form.
- A notes file in `CLAUDE.md` is enough.
Example request
Before pushing with `--no-verify`, check through intervention_query whether we recorded a lesson about this step and show the chain.MCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
CAUSAL_MEMORY_DB- Path to the SQLite memory database file
CAUSAL_MEMORY_HTTP_AUTH_TOKENsecret- Token for service endpoints in HTTP mode
Limitations
Status v0.10.0, alpha. On fact-recall suites it trails mem0 (79.1% against 91.6% on LoCoMo in the author's table). Agents do not call the memory on their own until the skill is installed or an instruction is added. The `/metrics` and `/debug/*` endpoints expose stored content, so set a token through `CAUSAL_MEMORY_HTTP_AUTH_TOKEN`. Quality numbers come from the author. Last commit: November 2026.
How to disable. Remove the `causal-memory` entry from the client MCP config and the skill from the skills directory (`./install.sh --uninstall` does both). Delete the database file at the `CAUSAL_MEMORY_DB` path separately if the memory is no longer needed.
FAQ
How does it differ from ordinary fact memory?
Besides facts it stores decision-to-outcome links and inhibitory links, so it can warn about a risky step and compare options.
Is Rust required?
No. A `cargo build --release` build is documented, but `pip install causal-memory` installs the same executable.
How do I share memory between agents?
Start HTTP mode with `causal-memory http --port 9938`. Protect the service endpoints with the `CAUSAL_MEMORY_HTTP_AUTH_TOKEN` token.
Why is the skill needed?
Without it the agent does not call the memory tools unprompted. The skill in `skills/causal-memory/SKILL.md` explains when to use them.
Where is the data stored?
In one SQLite file at the `CAUSAL_MEMORY_DB` path, on your own machine with no cloud required.
Discussion
No questions or reviews yet.
Related
MCP serversMCP server with a memory of the agent's own: it decides what to keep and wakes with it each session, stored in one SQLite file
A long-term memory system for AI agents: the agent stores experience and facts, then retrieves them through a built-in MCP server
Long-term memory layer for AI agents: decisions and facts are stored as JSON next to the code and found again in a later session.
An MCP server for long-term agent memory: compresses dialogues into atomic facts, resolves pronouns and anchors relative time to absolute dates
ContextKeep gives agents persistent memory on SQLite with full-text search, categories and a web interface.
A long-term memory MCP server for AI agents: facts fade along a forgetting curve and related records are compressed into a summary
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| causal-memory (this card) | no | not required | 107 | |
| ai-memory | no | API key | 15,717 | stores notes and facts; causal-memory records decision-to-outcome links and warns about a risky step |
| SuperLocalMemory | no | not required | 275 | local memory for searching the past; causal-memory compares options by outcomes of earlier attempts |
README in short
The README opens with the problem of losing causes under context compaction, then demos, the CausalEval benchmark with an honest table where the project trails mem0 on facts, and install steps.