v1.3 to v1.3

---

name: causal-memory

description: Causal memory for agents — install/setup the causal-memory MCP server, then record decisions/outcomes and recall them before acting. Trigger when the user asks to install or set up causal-memory/agent memory, when causal-memory MCP tools are available and the agent faces a non-trivial decision (architecture, debugging approach, library/deployment choice), when something fails unexpectedly, or when the user asks to "remember" something.

version: v1.3

---

# Causal Memory

Causal memory records your past decisions and their outcomes as causal edges,

so you learn from experience across sessions and survive context compaction.

This skill has two parts:

- **§1 Setup** — when the `record_decision` / `search_causal` MCP tools are

NOT available yet: install and configure them yourself.

- **§2 Usage** — once the tools exist: the proactive recall/record loop.

## 1. Setup (do this yourself, then tell the user to restart the client)

The bundled `install.sh` (next to this SKILL.md, shipped with the skill) does

steps 1–2 below automatically — installs the server, symlinks the skill, and

registers the MCP server in every detected client (Claude Code / Cursor /

Opencode / Claude Desktop / Kimi Code). Prefer it over hand-editing:

```bash

bash <skill_dir>/install.sh # 交互式引导; --yes 全自动; --uninstall 卸载

```

Then jump to step 3 (restart). The numbered steps below are the manual

fallback.

1. **Install the package** (ships the full CLI as `causal-memory` on PATH):

```bash

pip install causal-memory # or: pipx install causal-memory

causal-memory --help | head -5 # verify the console script works

```

2. **Register it as an MCP server** in the user's client. Bare

`causal-memory` runs the stdio MCP server; the only env worth setting is

`CAUSAL_MEMORY_DB` (SQLite location, default `~/.causal-memory/causal.db`).

- **Claude Code** (CLI does the config for you):

```bash

claude mcp add causal-memory -- causal-memory

```

- **Cursor** — edit `~/.cursor/mcp.json` (merge into `mcpServers`):

```json

{ "mcpServers": { "causal-memory": { "command": "causal-memory" } } }

```

- **Opencode** — edit `~/.config/opencode/opencode.jsonc` (or opencode.json):

```json

{ "mcp": { "causal-memory": {"type":"local", "command": "causal-memory", "enabled":true, "environment":{

"CAUSAL_MEMORY_DB": ".local/share/causal-memory/causal.db"

} } } }

```

- **Claude Desktop** — edit

`~/Library/Application Support/Claude/claude_desktop_config.json`

(same `mcpServers` shape as above).

- **Kimi Code** — add to `config.toml`:

```toml

[mcp.servers.causal-memory]

command = "causal-memory"

```

When editing JSON configs, merge — never overwrite the whole file.

3. **Tell the user to restart the client** (MCP servers load at startup).

After restart, verify by calling `causal_directory` — an empty directory

is fine, an error means the server didn't come up.

4. Optional shared/remote mode: `causal-memory http --port 9938` serves MCP

over Streamable HTTP at `/mcp` (multi-agent shared memory; bind

`--host 0.0.0.0` for non-localhost access, and set

`CAUSAL_MEMORY_HTTP_AUTH_TOKEN` to protect the observability routes

`/metrics` and `/debug/*` when the port is reachable beyond loopback).

## 2. Usage (once the tools are available)

**Do NOT ask the user before searching or recording — do it proactively.**

The core loop (five tools cover 90% of usage):

- **Before any non-trivial decision** (architecture, debugging approach,

library selection, deployment strategy): call `search_memory` (facts +

causal lessons, RRF-fused). For risky or irreversible actions, also call

`intervention_query` — it forward-simulates what similar past actions

caused (safe / warning / **danger**).

- **When choosing between two concrete options**: `counterfactual_query`

with both option texts — recorded-outcome comparison, same-context

branches (natural experiments) when they exist, and a logged falsifiable

prediction that auto-resolves when either option is later recorded.

- **After acting on a decision and observing the result**: call

`record_decision` with `decision`, `outcome`, `relation`

(caused / enabled / prevented / no_effect), `task_tag`,

`confidence_source`, and **`context`** — a short description of the

situation (environment, constraints, key parameters). Same task_tag +

context ⇒ comparable branch: this is the abduction substrate that makes

counterfactuals same-world. If you weighed multiple options at this

especially — those are the most valuable lessons.**

- **Stable facts** (preferences, tech stack, config): `record_fact` with

`key` / `value` / `scope`; `replace_same_key: true` when superseding.

- **Failure postmortem**: `trace_cause` (single hop) /

`trace_cause_chain` (multi-hop root cause).

- **Corrections**: `invalidate_decision` / `invalidate_pattern` (soft-delete,

kept for audit).

- **Calibration check** (periodic): `prediction_report` — accuracy of past

counterfactual verdicts per method / per task_tag, plus pending

predictions.

Keep `task_tag` consistent within a domain (e.g. `deployment`,

`git-workflow`) — stratified pattern mining depends on it.

## 3. Context recovery & sync (CLI git-sync)

The store snapshots like git — but the git semantics are **self-implemented**

(no git binary or wire protocol involved): content-addressed sha256 objects

under `<db>.cm/objects/`, plain-text refs, hand-rolled fast-forward checks.

A "remote" is one of exactly two things: a **shared directory** (file

remote, zero infrastructure) or a **sync server** (`https` object store —

`GET/PUT {base}/objects/{hash}` + `/refs/heads/main`, bearer auth; see

contrib/docker for the server image). GitHub/GitLab repos do NOT work as

remotes.

**Primary purpose: context recovery.** Memory is the agent's *private*

context, snapshotted under its `agent_id` namespace. `commit && push` keeps

the cloud copy current; on a new machine `clone <agent_id>` restores the

full context in one shot; `checkout <hash>` rolls back to any snapshot.

Single-writer assumption → no merge algorithm; "merge" is just the

idempotent import.

- **`commit -m <msg>`** — snapshot the whole store (full truth incl.

invalidated edges, no redaction). On a fresh clone with no local changes

it correctly reports "nothing to commit".

- **`push [<remote|path>]` / `pull`** — upload / import commits

(fast-forward checked, idempotent; pull propagates forget/supersede).

- **`clone <path|remote>`** — build a fresh DB from a remote + set origin.

This is the context-restore entry point: new machine → `clone` → back to

work with full memory.

- **`checkout <hash|HEAD|HEAD~N>`** — hard-reset the DB to a snapshot

(rollback; auto-backup first); **`log --oneline`** walks the chain

without opening the DB.

- **`remote add|list|remove`** — named remotes; **`cloud register

<agent_id> <server-url>`** — per-agent tokens against a sync server.

- **`session-commit [<session>] [--push R]`** — snapshot a session's

lessons and optionally push; designed for host auto-commit hooks

(skips empty stores). Keeps the cloud copy from ever going stale.

Team pattern (a natural extension, not the primary goal): point several

agents at one shared remote (a shared directory is enough to start), each

`clone`s once, then `commit && push` after meaningful work and `pull` at

session start.

## 4. Offline session extraction (CLI — backfill memory from past sessions)

All four commands need an LLM: `CAUSAL_MEMORY_LLM_API` +

`CAUSAL_MEMORY_LLM_KEY` (or `DEEPSEEK_API_KEY`). They write into the same

`CAUSAL_MEMORY_DB` store the MCP server reads.

Agent-native session files (`--agent grok|claude|kimi|codex`; kimi = OpenClaw

format — kimi-code wire protocol 1.5 is NOT supported yet):

- **`extract <session-file|dir>`** — the default choice. Batches 15 assistant

messages per LLM call; one call yields facts/preferences (→ fact layer)

AND lessons/causal edges in all layers. Cheapest full-coverage path.

- **`judge <session-file|dir>`** — rule-based: pairs tool calls with their

results into decision→outcome edges, then LLM re-judges only the top-20

by confidence. Fewest LLM calls; causal edges only.

- **`reasoning <session-file|dir> [max_messages]`** — one LLM call PER

assistant message, extracting decisions that never became tool calls

(rejected designs, debated trade-offs). Most thorough, most expensive

(calls = messages; default cap 30).

Normalized conversation JSON (`{"date": "YYYY-MM-DD", "turns": [[speaker,

message], ...]}` — hand-curated corpora, benchmark ingest):

- **`distill <session.json|dir> [--dry-run]`** — same Distiller as

`extract`, for non-agent-native input. `--mode recurrence` switches to

the RecMem flow (embeddings + recurrence gate).

Rule of thumb: backfilling an agent's history → `extract`; tight LLM budget

→ `judge`; hunting "decisions that never became actions" → `reasoning`;

own-format corpora → `distill`.

**Unsupported session format? Convert it yourself.** The turns JSON is the

universal interchange format — any agent can emit it and run `distill`, no

Rust parser needed. The bundled `scripts/session_to_turns.py` is the

reference converter (kimi-code wire v1.5 → turns JSON, ~60 lines) and its

docstring IS the format spec: ordered `["speaker", message]` pairs, stitch

streaming deltas, keep the assistant's reasoning prefixed `[think] `,

inline outcome-bearing tool results. Adapt the `convert_*` function to your

own session format (~1 hour of work), then `distill --dry-run` to verify.

## 5. Bundled scripts (ops & integration helpers)

Shipped in the `scripts/` directory **next to this SKILL.md** — resolve

`<skill_dir>` from the skill listing path (e.g.

`~/.agents/skills/causal-memory/scripts/…` once installed, or

`scripts/…` at the source repo root). Repo source of truth:

`scripts/` in github.com/JingxuanC/causal-memory.

- **`session_to_turns.py`** — CLI converter, agent session log → turns JSON

(the §4 interchange format). Use when the user's session format has no

Rust parser and they want history backfilled:

```bash

python3 <skill_dir>/scripts/session_to_turns.py <session-file> /tmp/turns.json

causal-memory distill /tmp/turns.json --dry-run # verify, then drop --dry-run

```

Input is kimi-code wire.jsonl; for other agents copy the `convert_*`

function and adapt (docstring is the format spec). stdlib only.

- **`audit_fact_links.py`** — read-only store audit: fact↔chunk entity

links, replicating the Rust linker policy; reports orphaned / mis-linked

facts. Run after large imports, migrations, or when `search_facts`

surfaces stale entries:

```bash

python3 <skill_dir>/scripts/audit_fact_links.py # default db

python3 <skill_dir>/scripts/audit_fact_links.py --db /path/to/causal.db --sample 5

```

Options: `--db` (default `~/.local/share/causal-memory/causal.db`),

`--min-tokens N`, `--df-limit N` (0 disables), `--no-compare`,

`--sample N`. stdlib only; never writes.

- **`causal_memory_client.py`** — importable Python client (NOT a CLI) for

scripting against the MCP server over **both** transports. Requires

`pip install requests`. Use for bulk reads/writes, deployment probes, or

automation beyond single MCP tool calls:

```python

import sys; sys.path.insert(0, "<skill_dir>/scripts")

from causal_memory_client import CausalMemoryClient

cm = CausalMemoryClient.http("http://localhost:9938/mcp") # remote deployment

assert cm.health()

print(cm.search_memory("deploy rollback"))

cm = CausalMemoryClient.stdio("causal-memory") # local, spawns the binary

cm.record_decision("chose HRP over equal-weight", "sharpe 1.8 vs 1.1",

"caused", "portfolio", context="120d lookback, 10 names")

cm.close()

```

Wraps all 17 tools (`record_decision` / `search_*` / `trace_*` /

`intervention_query` / `counterfactual_query` / `reconstruct_lesson` …).

Full reference (17 tools): repo README "MCP tools" —

github.com/JingxuanC/causal-memory.