causal-memory
Causal memory layer for AI agents — MCP server that records decision→outcome relationships. Survives compaction.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/jingxuanc--causal-memory)HTML
<a href="/listings/jingxuanc--causal-memory"><img src="/api/listings/jingxuanc--causal-memory/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
git clone https://github.com/JingxuanC/causal-memory.git cd causal-memory cargo build --release
MCP integration (Claude Code, Cursor, grok-build, etc.)
First-class installers: **Claude Code** (`integrations/claude-code/`) and **Codex CLI** (`integrations/codex/`) — MCP registration + activation prompt/skill in one idempotent script each.
{
"mcpServers": {
"causal-memory": {
"command": "/path/to/causal-memory/target/release/causal-memory",
"env": {
"CAUSAL_MEMORY_DB": "~/.local/share/causal-memory/causal.db"
}
}
}
}No Rust toolchain? `pip install causal-memory` puts the same `causal-memory` console script on your PATH (the full CLI — bare invocation is the stdio MCP server), so `"command": "causal-memory"` works as the MCP entry too.
To teach the agent *when* to use the memory tools (agents don't call them proactively without instruction), install the bundled agent skill [skills/causal-memory/SKILL.md](skills/causal-memory/SKILL.md):
**Guided installer (recommended)** — one command installs the skill, the `causal-memory` server, and the MCP registration across every detected client (Claude Code / Cursor / Opencode / Claude Desktop / Kimi Code):
./install.sh # interactive, walks you through each step ./install.sh --yes # non-interactive, accept all defaults ./install.sh --uninstall # remove the skill (+ optional MCP)
Or via the Skills CLI, or by hand:
# Skills CLI (skills.sh ecosystem) — works with Claude Code, Cursor, # Kimi Code CLI, Codex, Copilot and more: npx skills add JingxuanC/causal-memory@causal-memory
…or copy `skills/causal-memory/` into your agent's skills directory (e.g. `~/.agents/skills/causal-memory/`), or paste [CLAUDE.md](CLAUDE.md) into your system prompt / `AGENTS.md`.
HTTP transport (remote agents, multi-agent shared memory)
./target/release/causal-memory http --port 9938 # MCP Streamable HTTP
Observability endpoints on the same port:
GET /metrics Prometheus text (RED + recall metrics)
GET /healthz / /readyz liveness / readiness (readiness probes the store)
GET /debug/recall?query=... run a recall now, return the full JSON trace
(seeds, hop summary, per-result provenance)
GET /debug/recalls newest-first recall audit rows (persisted,
schema v13 recall_audit table; survives restarts)`/metrics` and `/debug/*` expose the recall corpus, so they accept opt-in bearer auth: set `CAUSAL_MEMORY_HTTP_AUTH_TOKEN` (env or `causal-memory setconfig`) and they require `Authorization: Bearer <token>` (unset = open, the previous behavior). `/healthz` / `/readyz` stay open on purpose — kubelet probes cannot send bearer headers and leak nothing. `/mcp` client auth is a separate mechanism: per-tenant bearer tokens (see *Multi-tenant HTTP* below). Without the token, do not expose the port to the public internet.
Structured JSON logs on stderr: `CAUSAL_MEMORY_LOG_FORMAT=json`.
Multi-tenant HTTP (per-tenant databases)
Point `CAUSAL_MEMORY_TOKENS_FILE` (env or `causal-memory setconfig`) at a JSON file mapping bearer tokens to tenant names:
{ "token-for-alice": "alice", "token-for-bob": "bob" }With the file configured and non-empty, `/mcp` requires `Authorization: Bearer <token>`, and each tenant reads and writes its own SQLite store at `<db-dir>/tenants/<tenant>.<fnv1a-hash>.db` — one database per tenant, opened lazily on first request, so one tenant can never see another's facts or causal edges (covered by an end-to-end isolation test). Missing or unknown tokens get `401` and never create a database file. The file is reloaded when its mtime changes, so tenants can be added or revoked without a restart; if the file turns unreadable at runtime the last-good map stays in force (fail closed).
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 20 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "causal-memory",
- "description": "Persistent causal memory for coding agents — decisions, outcomes, lessons, same-context counterfactuals, and a falsifiable prediction ledger. Shared across Claude Code, Codex, kimi, Hermes, and Python.",
- "owner": {
- "name": "JingxuanC"
- },
- "plugins": [
- {
- "name": "causal-memory",
- "description": "Persistent causal memory for Claude Code — decisions, outcomes, and lessons that survive compaction. Same-context counterfactuals (natural experiments), a falsifiable prediction ledger, and an activation skill that teaches when to recall and record.",
- "author": {
- "name": "JingxuanC"
- },
- "category": "memory",
- "source": "./plugins/claude-code",
- "homepage": "https://github.com/JingxuanC/causal-memory"
- }
- ]
- }
README.md · README · 582 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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.
- [](LICENSE)
- [](#status)
- [](#build--test)
- [](https://github.com/JingxuanC/causal-memory/releases)
- [](hermes-plugin/)
- [](dsh-plugin/)
- **English** · [简体中文](README.zh-CN.md)
- ---
- ## 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):
- | Compactions (k) | Textual recall | Causal-table recall |
- |---|---|---|
- | 1 | 100% | 100% |
- | 2 | 85% | 100% |
- | 3 | 55% | 100% |
- | 5 | **45%** | **100%** |
- The causal table survives because it lives **outside the agent's context window** —
- compaction cannot touch it.
- ---
- ## Demo
- **30-second single scene** — the agent is about to `git push --no-verify`;
- `intervention_query` fires a DANGER chain citing the lesson it recorded last
- time ("production login failed for 40 minutes; emergency rollback"):
- <!-- GitHub's CSP (media-src) only allows GitHub-hosted media, so an
- external <video> never plays on the repo page. An animated GIF goes
- through the camo image proxy and plays inline. Click for the mp4. -->
- [](docs/demo/causal-memory-danger-30s.mp4)
- [Download video](docs/demo/causal-memory-danger-30s.mp4) ·
- [DANGER-scene screenshot](docs/demo/demo30_danger.png) ·
- Regenerate: `scripts/capture_demo30.py` → `scripts/render_demo30.py`
- A 21-second hands-on demo (real memory store, no mocks): pre-action warning
- (`intervention_query` → DANGER chain) → experience recall (`search_causal`)
- → counterfactual comparison (`counterfactual_query`) → write loop
- (`record_decision` → immediately searchable).
- [](docs/demo/causal-memory-demo.mp4)
- [Download video](docs/demo/causal-memory-demo.mp4) ·
- [Warning-scene screenshot](docs/demo/demo_intervention.png) ·
- [Brand card](docs/demo/demo_card.png) ·
- Regenerate: `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):
- | Capability | causal-memory | v12 (70q) | mem0 (70q) | What it tests |
- |---|---|---|---|---|
- | **C7 Update** | **100%** | 50% | 80% | Supersede old belief after falsification (soft `superseded_by` annotation) |
- | C3 Counterfactual | **95%** | 90% | 80% | Choosing between alternatives with known outcomes |
- | C2 Intervention | **75%** | 70% | 40% | Forward prediction: "if X again, what happens?" |
- | C4 Inhibition | **80%** | 90% | 50% | Distinguishing root-cause fix vs blast-radius limiter (`prevented` edges) |
- | C1 Attribution | 85% | 90% | 90% | Backward causal chain → root cause |
- | C5 Temporal-causal | 90% | 100% | 90% | Ordering on a causal chain |
- | C6 Lesson transfer | 20% | 20% | 30% | Cross-task analogy via meta edges (open limitation) |
- | **Overall** | **78%** | 81% | 65% | |
- **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.
- | Benchmark | causal-memory | mem0 | Note |
- |---|---|---|---|
- | LoCoMo (strict judge) | 79.1% | 91.6% | mem0's home turf |
- | LongMemEval-S (full pipeline, deepseek-chat) | **76.4%** @ 11.5K tok/q | 94.4% @ 6.8K tok/q (official) · 73.8% (ind. repro) | single-model stack vs platform stack; see docs/benchmarks/longmemeval.md |
- | Memora MPA | 67.4% | 71.8% | −4.4pp |
- | Compaction survival | 100% | 45% | External table = immune to compaction |
- | Agent repeat-mistake | 33% | 67% | −34pp on trap-world |
- ### Capability tests (322 across the workspace)
- These test capabilities that **no fact store (mem0, Zep, Letta) can offer**.
- | Capability | What it proves | Tests |
- |---|---|---|
- | **Prevented-edge warning** | `prevented` edge spreads −0.3 activation (GABA analogue) | 2 |
- | **Trace-cause attribution** | Backward CSR traversal finds root cause | 2 |
- | **Multi-hop causal chain** | Forward K-hop spreading reaches 2-3 hop outcomes | 2 |
- | **Inhibitory filtering** | Prevented outcomes appear as negative, not false positives | 1 |
- | **Intervention comparison** | Same outcome has +0.9 for "skip tests" and −0.3 for "add tests" | 4 |
- | **SWR consolidation** | LTP strengthens replayed edges, LTD weakens unvisited, GC forgets dormant | 5 |
- | **Q-value dynamics** | Good decisions rank higher; Bellman propagates to parents | 3 |
- | **Novelty entropy** | Diverse experience triggers consolidation; uniform does not | 3 |
- | **Meta-edge mining** | Cross-session pattern discovery (similar_to / repeated) | 3 |
- | **Hebbian co-occurrence** | Repeated co-activation strengthens connection | 3 |
- ---
- ## What makes it different
- | Capability | causal-memory | mem0 | Zep | Letta | HeLa-Mem |
- |---|---|---|---|---|---|
- | Typed causal semantics (caused/enabled/prevented) | ✅ | ❌ | ❌ | ❌ | ❌ |
- | **prevented negative spread (inhibitory)** | ✅ | ❌ | ❌ | ❌ | ❌ |
- | Hebbian co-occurrence edges (excitatory) | ✅ | ❌ | ❌ | ❌ | ✅ |
- | Immutable consolidation (delta + clone) | ✅ | ❌ | ❌ | ❌ | ❌ |
- | Q-value dynamic utility | ✅ | ❌ | ❌ | ❌ | ❌ |
- | Forward simulation (intervention_query) | ✅ | ❌ | ❌ | ❌ | ❌ |
- | SWR offline consolidation (LTP/LTD/GC) | ✅ | ❌ | ❌ | ❌ | ❌ |
- | Novelty-entropy consolidation trigger | ✅ | ❌ | ❌ | ❌ | ❌ |
- | Meta-edge cross-session pattern mining | ✅ | ❌ | ❌ | ❌ | ❌ |
- | Compaction survival evidence | ✅ +20.8pp | ❌ | ❌ | ❌ | ❌ |
- | One graph unifying all memory types | ✅ | ❌ | ⚠️ | ❌ | ⚠️ |
- | Write-time gatekeeping (raw → session_logs) | ✅ | ✅ | ❌ | ❌ | ❌ |
- | Local ONNX embedding (offline) | ✅ | ✅ | ❌ | ❌ | ❌ |
- **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](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
- | Edge type | Spread coeff | Biological analogue | Meaning |
- |---|---|---|---|
- | `caused` | +1.0 | Glutamate (strong excitatory) | "Doing X caused Y" |
- | `fact` | +0.8 | Semantic association | "User is/has Z" |
- | `meta` | +0.6 | Cortical top-down | Cross-task pattern link |
- | `enabled` | +0.5 | Weak excitatory | "Doing X enabled Y" |
- | `co_occurrence` | dynamic | Hebbian LTP | "X and Y frequently co-occur" |
- | **`prevented`** | **−0.3** | **GABA (inhibitory)** | **"Doing X prevented Y"** |
- | `no_effect` | 0.0 | — | No causal relationship |
- ---
- ## Quick start
- ```bash
- git clone https://github.com/JingxuanC/causal-memory.git
- cd causal-memory
- cargo build --release
- ```
- ### MCP integration (Claude Code, Cursor, grok-build, etc.)
- First-class installers: **Claude Code** (`integrations/claude-code/`) and
- **Codex CLI** (`integrations/codex/`) — MCP registration + activation
- prompt/skill in one idempotent script each.
- ```json
- {
- "mcpServers": {
- "causal-memory": {
- "command": "/path/to/causal-memory/target/release/causal-memory",
- "env": {
- "CAUSAL_MEMORY_DB": "~/.local/share/causal-memory/causal.db"
- }
- }
- }
- }
- ```
- No Rust toolchain? `pip install causal-memory` puts the same `causal-memory`
- console script on your PATH (the full CLI — bare invocation is the stdio MCP
- server), so `"command": "causal-memory"` works as the MCP entry too.
- To teach the agent *when* to use the memory tools (agents don't call them
- proactively without instruction), install the bundled agent skill
- [skills/causal-memory/SKILL.md](skills/causal-memory/SKILL.md):
- **Guided installer (recommended)** — one command installs the skill, the
- `causal-memory` server, and the MCP registration across every detected client
- (Claude Code / Cursor / Opencode / Claude Desktop / Kimi Code):
- ```bash
- ./install.sh # interactive, walks you through each step
- ./install.sh --yes # non-interactive, accept all defaults
- ./install.sh --uninstall # remove the skill (+ optional MCP)
- ```
- Or via the Skills CLI, or by hand:
- ```bash
- # Skills CLI (skills.sh ecosystem) — works with Claude Code, Cursor,
- # Kimi Code CLI, Codex, Copilot and more:
- npx skills add JingxuanC/causal-memory@causal-memory
- ```
- …or copy `skills/causal-memory/` into your agent's skills directory
- (e.g. `~/.agents/skills/causal-memory/`), or paste [CLAUDE.md](CLAUDE.md)
- into your system prompt / `AGENTS.md`.
- ### HTTP transport (remote agents, multi-agent shared memory)
- ```bash
- ./target/release/causal-memory http --port 9938 # MCP Streamable HTTP
- ```
- Observability endpoints on the same port:
- ```
- GET /metrics Prometheus text (RED + recall metrics)
- GET /healthz / /readyz liveness / readiness (readiness probes the store)
- GET /debug/recall?query=... run a recall now, return the full JSON trace
- (seeds, hop summary, per-result provenance)
- GET /debug/recalls newest-first recall audit rows (persisted,
- schema v13 recall_audit table; survives restarts)
- ```
- `/metrics` and `/debug/*` expose the recall corpus, so they accept opt-in
- bearer auth: set `CAUSAL_MEMORY_HTTP_AUTH_TOKEN` (env or
- `causal-memory setconfig`) and they require
- `Authorization: Bearer <token>` (unset = open, the previous behavior).
- `/healthz` / `/readyz` stay open on purpose — kubelet probes cannot send
- bearer headers and leak nothing. `/mcp` client auth is a separate
- mechanism: per-tenant bearer tokens (see *Multi-tenant HTTP* below).
- Without the token, do not expose
- the port to the public internet.
- Structured JSON logs on stderr: `CAUSAL_MEMORY_LOG_FORMAT=json`.
- #### Multi-tenant HTTP (per-tenant databases)
- Point `CAUSAL_MEMORY_TOKENS_FILE` (env or `causal-memory setconfig`) at a
- JSON file mapping bearer tokens to tenant names:
- ```json
- { "token-for-alice": "alice", "token-for-bob": "bob" }
- ```
- With the file configured and non-empty, `/mcp` requires
- `Authorization: Bearer <token>`, and each tenant reads and writes its own
- SQLite store at `<db-dir>/tenants/<tenant>.<fnv1a-hash>.db` — one database
- per tenant, opened lazily on first request, so one tenant can never see
- another's facts or causal edges (covered by an end-to-end isolation test).
- Missing or unknown tokens get `401` and never create a database file. The
- file is reloaded when its mtime changes, so tenants can be added or revoked
- without a restart; if the file turns unreadable at runtime the last-good
- map stays in force (fail closed).
- Unset (or an empty/unreadable file) keeps the previous behavior: no `/mcp`
- auth, one shared store — local and stdio usage are unaffected. The startup
- log states the mode: `auth=multi-tenant (N tokens)` vs `auth=open`.
- Memory residency: every active tenant holds its own `CausalStore` and
- in-memory graph, so RSS grows with the tenant count — see
- [docs/design/enterprise-scaling.md](docs/design/enterprise-scaling.md)
- before packing many tenants into one process. The observability endpoints
- (`/metrics`, `/debug/*`) keep reporting on the default store and are still
- gated by `CAUSAL_MEMORY_HTTP_AUTH_TOKEN`, independently of tenant auth.
- ### With local embeddings (no API key needed)
- ```bash
- 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.)
- ```bash
- 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:
- ```bash
- cd crates/causal-memory-py
- pip install maturin
- maturin develop # builds and installs into the active venv
- ```
- ```python
- 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",
- context="go 1.22, single redis, 5k rps")
- print(mem.search_causal(query="cache stampede protection"))
- print(mem.intervention_query("skip the test suite before shipping"))
- ```
- Methods mirror the 17 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`).
- ---
- ## Integrations
- ### Hermes memory provider
- [hermes-plugin/](hermes-plugin/) turns causal-memory into a drop-in Hermes
- `MemoryProvider` — flat facts + decision→outcome causal lessons on one local
- SQLite store, per-profile by construction
- (`<hermes_home>/causal-memory/causal.db`). Wired hooks: system-prompt causal
- directory, budgeted prefetch recall, non-blocking `sync_turn` write-behind,
- and a `hermes causal-memory stats` CLI. Because the store lives outside the
- context window, Hermes compaction can't touch it. Install and configuration:
- [hermes-plugin/README.md](hermes-plugin/README.md).
- ### DeepSeek Harness (DSH) native plugin
- [dsh-plugin/](dsh-plugin/) mounts all 16 causal-memory tools onto DSH's
- `ctx.tools` with clean names (no `mcp__` prefix) and injects a system-prompt
- block telling the model when to consult the causal store. Zero runtime
- dependencies — JSON-RPC over stdio straight to the causal-memory binary.
- One-line install: `dsh plugin --profile web add "$PWD/dsh-plugin"` (needs the
- `causal-memory` binary — `pip install causal-memory`, or a repo
- `cargo build --release`).
- Details: [dsh-plugin/README.md](dsh-plugin/README.md).
- ---
- ## Seventeen MCP tools
- | Tool | When to call | What it does |
- |---|---|---|
- | `record_decision` | After acting on a decision | Logs `decision → outcome` as a causal edge with relation type; optional `context` records the world state — same task_tag + context becomes a comparable branch (fork) |
- | `remember` | After any meaningful exchange | Zero-friction alternative: paste conversation text, LLM auto-extracts facts/lessons/causal edges |
- | `search_causal` | Before a non-trivial decision | BM25 + semantic retrieval of past causal episodes |
- | `record_fact` | When learning a stable fact | Records flat facts with scope + confidence; idempotent |
- | `search_facts` | When you need "what is" info | BM25 + semantic retrieval over the fact layer |
- | `search_memory` | When unsure which type | Unified: facts + causal lessons fused by RRF |
- | `trace_cause` | When something fails | Single-hop reverse: which decision caused this outcome |
- | `trace_cause_chain` | Deep failure analysis | Multi-hop backward traversal through the causal graph |
- | `invalidate_decision` | When a lesson is wrong | Soft-invalidate (hidden from search, kept for audit) |
- | `invalidate_pattern` | When a mined pattern is wrong | Soft-invalidate a meta edge (the #N handle from search_patterns) |
- | `resolve_updates` | After contradicting outcomes | LLM-judged supersession pass over diverged repeated decisions |
- | `search_patterns` | To recall cross-task lessons | Mined meta edges: similar_to / repeated / contradicts / refines |
- | `causal_directory` | Pinned in system prompt | L0 compact pointer list of what the agent knows |
- | `intervention_query` | **Before taking an action** | Forward simulation: predicts outcomes (safe/warning/danger) |
- | `counterfactual_query` | When choosing between options | Contrastive: compares recorded outcomes of two alternatives; renders same-context branches (natural experiments) when they exist; every verdict logs a falsifiable prediction |
- | `prediction_report` | Periodic calibration check | Prediction-ledger accuracy overall / per method / per task_tag + pending list |
- | `reconstruct_lesson` | When you want the distilled lesson | Reconstructive retrieval: Markov-blanket subgraph → coherent narrative, with optional N-way calibration |
- ---
- ## Sleep consolidation
- ```bash
- 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):
- | Layer | Benchmark | Tests |
- |---|---|---|
- | Fact layer | Memora / LoCoMo | — |
- | Causal edges (caused/enabled/prevented) | Capability | 12 |
- | Hippocampus spreading activation | Capability | — |
- | SWR consolidation (LTP/LTD/GC) | Longitudinal | 5 |
- | Q-value dynamics | Longitudinal | 3 |
- | Novelty entropy trigger | Longitudinal | 3 |
- | Sleep-wake cycle | Longitudinal | 1 |
- | Meta-edge pattern mining | Advanced | 3 |
- | Co-occurrence Hebbian | Advanced | 3 |
- | Intervention query (forward sim) | Advanced | 4 |
- | Trace cause chain | Capability | 2 |
- | Inhibitory ablation | Inhibition | 2 |
- | Distill / retrieval / facts | Memora / LoCoMo / LME | — |
- | Compaction survival | Compact | — |
- | Agent trap-world | Agent | — |
- | Pipeline e2e | Migration / Pipeline | 2 |
- ---
- ## Build & test
- ```bash
- 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](https://agentmemories.ai/competition/)
- 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`):
- ```bash
- 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`](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`](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](https://github.com/JingxuanC/agent-teardown/tree/main/insights)),
- 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.10.0 — alpha.**
- What works (16/16 layers with end-to-end validation):
- - ✅ 17 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, extraction calibration, adversarial injection
- - ✅ 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)
- - ✅ Hermes memory-provider plugin (hermes-plugin/)
- - ✅ 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](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.