causal-memory — architecture

Facts, temporal state and decision→outcome causal edges on one store — typed spreading activation (excitatory + inhibitory), Hebbian co-occurrence, Q-value dynamics, immutable SWR consolidation.

Agent / clients

Claude CodeCursorgrok-buildremote agents (HTTP)

stdio / streamable-HTTP transport

MCP server — 14 tools

record_decisionremembersearch_causal record_factsearch_factssearch_memory trace_causetrace_cause_chaininvalidate_decision search_patternscausal_directoryintervention_query counterfactual_queryreconstruct_lesson

CLI · PyO3 · benches

sleep (consolidate)resolve-updates (C7)ingest / distill python bindings

CausalEval · LoCoMo · LongMemEval · Memora · AMC

Memory facade — 15+ ops (sync → tokio bridge)

search_memorysearch_memory_multi_passsearch_causalsearch_facts trace_cause(_chain)intervention_querycounterfactual_query reconstruct_lessonsearch_patternscausal_directoryrecord_*invalidate_decision

query_router (D4) dispatches display intent · block_on bridges runtime

Store — SQLite schema v11

chunkscausal_edgesagent_facts meta_causal_edgescooccurrence_edgessessionsbm25_index

WAL · connection pool · never compacted (lives outside the context window)

write gatekeeping: record_decision / distill / supersede / invalidation

Hippocampus — CausalGraph

spreading activationinhibition (GABA)Hebbian co-occurrenceQ-value Bellman

caused +1.0 · enabled +0.5 · prevented −0.3 · fact +0.8 · meta +0.6

intervention / counterfactual · cross-task transfer (REM)

Retrieval — unified + multi-pass

BM25 (inverted)semantic cosinehop expansionRRF fusion multi-pass: entities + time anchor + session expansion + verify loop

type-agnostic evidence topology (docs/design/multi-session-retrieval-2026-08.md)

Consolidation — sleep stages

0 novelty gate→ 1 reactivation→ 1.5 Q-value→ 1.7 C7 supersession (LLM judge)→ 2 generalization→ 3 downscale (half-life tiers + GC)→ 4 REM transfer

dry-run · --immutable (VACUUM INTO new store) · --restore with backup

LLM judges

polaritycausalitysupersession (C7)narrative reconstruction

Distill

session → facts / preferences / lessons / events

Embed

HTTP / fastembed (local)LRU cacheshared embedder

Support

patterns minerchain_linkerrefutetokenizer (CJK)

Data flow

raw turns → session_logs→ distill → facts + causal edges→ hippocampus graph (lazy rebuild)→ SQLite (never compacted)→ sleep: merge / retire / decay / transfer

query→ search_memory fusion (facts + causal + hop, RRF)→ multi-pass retrieval (cross-session)→ answer (LLM) · judge (LLM)

causal-memory v0.9.0 · agent memory with a causal core · rust + sqlite