causal-memory

An agent memory system with a causal core — and the only one that models inhibition.

Facts, temporal state, and decision → outcome causal edges on one SQLite store, powered by a hippocampus-style engine: typed spreading activation (excitatory and inhibitory), Hebbian co-occurrence reinforcement, Q-value dynamics, and immutable SWR consolidation. Agents recall what happened, when it was true, why it worked — and what would happen if they acted differently.

Why

Every agent forgets why it made past decisions after a few context compactions. It re-fixes the same bug the same wrong way, re-debates the same architecture choice, relearns the same lesson.

This happens because causal information is the most fragile type under text compaction. Real-LLM benchmark (grok-build's production compaction prompt):

The causal table survives because it lives outside the agent's context window — compaction cannot touch it.

Demo

21 秒实操演示（真实记忆库，非 mock）：行动前预警（intervention_query → DANGER 链） → 经验检索（search_causal）→ 反事实对比（counterfactual_query）→ 写入闭环（record_decision → 立即可检索）。

下载视频 · 预警场景截图 · 品牌卡 · 重新生成：scripts/render_demo.py

Benchmarks

CausalEval — the causal memory benchmark (primary)

Most agent-memory benchmarks (LoCoMo, LongMemEval, Memora) test fact recall ("what is the user's preference"). causal-memory's differentiators — typed causal edges, inhibition, intervention prediction, cross-task transfer — are invisible on those suites. CausalEval measures them.

Design: the causal graph is the answer key. Typed DAGs are generated deterministically; conversations are narrated from the graph; gold answers are derived from graph structure — zero hand annotation, zero ambiguity.

CausalEval v13 (soft supersession) — 140 questions, 20 graphs (same LLM, same judge; v12 baseline was 70q/10 graphs; mem0 comparison ran on the 70q protocol):

Key result: C7 update 50% → 100% (+50pp, 20/20 questions) and it holds at doubled sample size. Soft supersession annotates superseded edges (superseded_by) instead of hiding them — the falsification signal reaches the answer model while the old lesson stays retrievable for counterfactuals (C3 unharmed at 95%). The C6 gap (20% vs mem0 30%) is the remaining open limitation; C1/C4/C5 dips vs v12 are within re-distillation variance and new-graph difficulty (v12 and v13 do not share a distilled corpus).

Fact-recall benchmarks (not our strong suit)

On traditional fact-recall suites, causal-memory performs competitively but does not beat mem0 — this is expected, because fact recall is mem0's specialty and not where causal-memory adds value.

Capability tests (322 across the workspace)

These test capabilities that no fact store (mem0, Zep, Letta) can offer.

What makes it different

Core innovation: the excitatory/inhibitory duality. HeLa-Mem (ACL 2026) builds the excitatory side (Hebbian co-activation, positive spread). causal-memory adds the inhibitory side (prevented edges spread negative activation — a GABA analogue). A complete memory needs both: "what caused this" and "what prevents this from happening again."

Architecture

Interactive version: docs/architecture.html

  ┌───────────────────────────────────────────────┐
  │           causal-memory (Rust, MCP)            │
  │                                                │
  │  14 tools ← Agent (stdio / HTTP)                 │
  │    ↓                                           │
  │  Write-time gatekeeping                        │
  │    raw turns → session_logs (audit only)       │
  │    distill → facts + causal edges (searchable) │
  │    ↓                                           │
  │  Unified retrieval (RRF fusion)                │
  │    BM25 + semantic cosine → RRF merge          │
  │    Fact layer (BM25 + embeddings)              │
  │    ↓                                           │
  │  ┌──── Hippocampus engine ──────────────────┐  │
  │  │ CSR graph + spreading activation          │  │
  │  │  caused (+1.0)   enabled (+0.5)           │  │
  │  │  prevented (−0.3) ← GABA inhibitory       │  │
  │  │  fact (+0.8)     meta (+0.6)              │  │
  │  │  co_occurrence (Hebbian, dynamic)         │  │
  │  │                                            │  │
  │  │ DG: SimHash pattern separation             │  │
  │  │ CA3: K-hop spreading (forward + reverse)   │  │
  │  │ CA1: Novelty entropy trigger               │  │
  │  │ SWR: LTP/LTD/GC (immutable delta + clone)  │  │
  │  │ Q-value: Bellman dynamics (MemRL-style)    │  │
  │  └────────────────────────────────────────────┘  │
  │    ↓                                           │
  │  SQLite (causal.db) — never compacted          │
  └───────────────────────────────────────────────┘

The causal_edges table is never compacted — it lives outside the agent's context window. That's the entire point.

Edge types

Quick start

git clone https://github.com/JingxuanC/causal-memory.git
cd causal-memory
cargo build --release

MCP integration (Claude Code, Cursor, grok-build, etc.)

{
  "mcpServers": {
    "causal-memory": {
      "command": "/path/to/causal-memory/target/release/causal-memory",
      "env": {
        "CAUSAL_MEMORY_DB": "~/.local/share/causal-memory/causal.db"
      }
    }
  }
}

HTTP transport (remote agents, multi-agent shared memory)

./target/release/causal-memory http --port 9938   # MCP Streamable HTTP

With local embeddings (no API key needed)

cargo build --release --features local-embed
# Uses BAAI/bge-small-en-v1.5 (384 dims, ~130MB, downloads once then offline)

With HTTP embeddings (OpenAI/ZhiPu/etc.)

export CAUSAL_MEMORY_EMBED_API=https://open.bigmodel.cn/api/paas/v4
export CAUSAL_MEMORY_EMBED_KEY=your-key
export CAUSAL_MEMORY_EMBED_MODEL=embedding-3

Python bindings (PyO3)

All 14 memory operations are also available as a Python package, built on the same causal_memory::memory::Memory facade the MCP server uses:

cd crates/causal-memory-py
pip install maturin
maturin develop          # builds and installs into the active venv

from causal_memory import CausalMemory

mem = CausalMemory("~/.local/share/causal-memory/causal.db")  # or CausalMemory.in_memory()
mem.record_decision("used Redis mutex for cache stampede protection",
                    "deadlock under load", "caused", "concurrency")
print(mem.search_causal(query="cache stampede protection"))
print(mem.intervention_query("skip the test suite before shipping"))

Methods mirror the 14 MCP tools one-to-one and return the same text. Embedding and LLM features use the same CAUSAL_MEMORY_EMBED_* / CAUSAL_MEMORY_LLM_* environment variables; without them the bindings degrade gracefully to BM25-only retrieval. Smoke tests: maturin develop && pytest tests/.

macOS note: always build the bindings through maturin. Plain cargo build -p causal-memory-py --release fails to link — the Xcode CLT Python ships no libpython3.9 dylib (this is why the py crate sits outside the workspace default-members).

Fourteen MCP tools

Sleep consolidation

causal-memory sleep --dry-run   # preview what would change
causal-memory sleep             # run consolidation cycle

Immutable SWR 2.0: produces a delta + clone (original graph untouched), with full audit log. Triple-criterion GC (weak AND dormant AND zero-access). Triggers automatically when novelty entropy exceeds threshold.

Causal distill pipeline

The distiller extracts structured memories from raw conversations:

Raw conversation → V3 extraction prompt (130 lines, 6 rules, 5 few-shot)
                   ↓
  Fact/Preference → agent_facts table (BM25 + embedding searchable)
  Lesson/Event    → causal edges (self-referential, searchable)
  Causal          → proper directed edge: decision → outcome
                    with relation type (caused/enabled/prevented)

Raw turns go to session_logs (audit/replay only) — they never enter the retrieval pool. This write-time gatekeeping keeps BM25 precision high.

System layer coverage

All 16 designed layers have end-to-end validation (322 workspace tests):

Build & test

cargo build --release                    # Build binary
cargo test --workspace --no-fail-fast  # Run 322 tests
cargo test --features local-embed     # Run with ONNX embedding tests
cargo clippy --workspace -- -D warnings # Lint

Agent Memory Challenge (AMC/01)

causal-memory enters the Agent Memory Leaderboard first evaluation cycle via an Add/Search integration server — a thin HTTP frontend over the same Memory facade the MCP server runs (BM25 + semantic + entity retrieval, RRF-fused; one store per user_id):

cargo build --release --bin causal-memory-amc
./target/release/causal-memory-amc --db-dir amc_data --port 8787 --write-mode raw
# --write-mode raw (no LLM, platform default) | distill (write-time LLM extraction)
# POST /add (store memory, user_id-isolated) · POST /search (ordered evidence) · GET /health

Docker route: docker build -t causal-memory-amc . && docker run -p 8787:8787 -v amc-data:/data causal-memory-amc. Submission details, method description, and the participation checklist live in docs/benchmarks/amc-2026.md.

Test suite breakdown:

• 186 library unit tests (types, store, distill, patterns, hippocampus)
• 45 library integration tests (capability, longitudinal, advanced, pipeline)
• 91 CLI, benchmark-harness & MCP e2e tests

Research background

Full documentation map: docs/README.md — design docs, benchmark protocols, evaluation reports, paper drafts, and the literature survey.

This project is the engineering output of 17 research notes on agent memory architecture (insights/01-17), a teardown of 7 production agent frameworks, and deep analysis of 10+ memory research papers. Key references:

• HeLa-Mem (ACL 2026) — Hebbian spreading activation (our closest competitor; we add the inhibitory side)
• Anthropic Dreams API — immutable consolidation pattern (aligned in SWR 2.0)
• mem0 — write-time gatekeeping architecture (adopted: session_logs separation)
• MemRL (arXiv:2601.03192) — Q-value memory dynamics (implemented)
• Graph World Models — causal-memory maps to "Graph as Reasoner"

Status

v0.9.0 — alpha.

What works (16/16 layers with end-to-end validation):

• ✅ 14 MCP tools (stdio + HTTP transport)
• ✅ Write-time gatekeeping (session_logs separation, V3 distill prompt)
• ✅ BM25 + semantic RRF unified retrieval
• ✅ Hippocampus engine: CSR spreading activation, DG SimHash, CA1 novelty, SWR 2.0
• ✅ 7 edge types: caused/enabled/prevented/fact/meta/co_occurrence/no_effect
• ✅ Causal distill: extracts typed causal edges (caused/enabled/prevented) from conversations
• ✅ Hebbian co-occurrence reinforcement
• ✅ Q-value Bellman dynamics
• ✅ Novelty-entropy consolidation trigger + sleep-wake cycle
• ✅ Meta-edge cross-session pattern mining
• ✅ Forward simulation (intervention_query) with prevented-edge warnings
• ✅ Benchmark harnesses: LoCoMo, LongMemEval, Memora, CausalEval, compaction, agent ablation, capability, longitudinal, advanced
• ✅ C7 LLM update-resolver (resolve-updates CLI + sleep stage 1.7 supersession)
• ✅ Vela-style half-life decay tiers (90d / 7d / legacy 0.99-per-day)
• ✅ Multi-session multi-pass retrieval (LongMemEval multi-session 42.9% → 57.9%, same-codebase)
• ✅ PyO3 Python bindings (crates/causal-memory-py)
• ✅ DSH native plugin (dsh-plugin/) + architecture visualization (docs/architecture.html)
• ✅ 368/368 tests passing + clippy clean

What's not done yet:

• ❌ TS bindings
• ❌ Forward-simulation prediction-accuracy benchmark (designed, not yet run)
• ❌ 7×24 production deployment validation

License

Apache-2.0. See LICENSE.