Causalist

The four semantic layers

Causalist inherits Tracey's multi-layer separation, informed by MAGMA's finding that orthogonal graphs for different signal types beat a flat unified memory.

Layer	Source	Examples
Code	Static AST + filesystem	files, functions, classes, imports
Execution	Runtime + tool calls	observations, errors, tool-use events
Knowledge	LLM reasoning	bugs, solutions, patterns, decisions
Project	User messages	tasks, constraints, goals

In the viewer, each layer gets its own color; selecting a node reveals only edges within its layer plus cross-layer "explains" bridges.

Node kinds

Every node has a kind:

file — a source file
module — a logical unit (package, directory with a role)
function / type — AST-level entities
external — npm/cargo/pip dependencies

Edge kinds

Edges are typed. This is the key thing most dependency-graph tools miss — not all "X depends on Y" relationships are the same.

Edge	Semantics
`imports`	`X` statically imports `Y`. From AST. Highest trust.
`calls`	`X` invokes `Y` at runtime. From AST + call-site resolution.
`reads`	`X` reads state from `Y` (DB row, config key, cache). Often inferred.
`writes`	`X` mutates `Y`. Narrower than reads; invariant-critical.
`extends`	`X` inherits / implements / conforms to `Y`.
`caused`	Execution-layer: event $e_1$ directly triggered $e_2$ .
`explains`	Knowledge-layer: learned pattern $p$ accounts for observation $o$ .

Confidence scoring

Each edge carries a confidence score $c \in [0, 1]$ :

c_{\text{edge}} \;=\; c_{\text{source}} \cdot e^{-\lambda (t - t_0)}

$c_{\text{source}}$ depends on provenance: AST-derived edges start at $1.0$ , LLM-inferred at $0.6$ .
The decay $e^{-\lambda (t - t_0)}$ means edges not touched for a long time lose trust. A file refactor that nobody has looked at for six months has a softer claim on the graph than yesterday's lint rule.

Edges below threshold are dimmed in the viewer. Queries with min_confidence filter them out of reasoning context.

Structural invariants

The verifier checks three properties after every update:

Acyclicity on causal edges — cycles indicate incorrectly-directed edges. A cycle $A \to B \to A$ on caused edges is a contradiction by definition.
No contradictions — $X$ cannot both prevent and cause $Y$ at overlapping timestamps.
Typed consistency — a node of kind: "external" cannot appear as the target of an extends edge from a local node in a language without multiple inheritance.

Violations don't halt the agent; they get surfaced as warnings you can investigate.