factgraph: facts that carry their own proof#
This morning an analyst flags a transaction. In the moment it feels obvious: the amount, the customer, the rule. Months later an auditor sits across the table and asks a harder question. Not is this still flagged, but show me exactly why you flagged it, on the day you did.
In most systems, that is where the floor gives way. The value that triggered the alert has been overwritten. “We flagged it” survives; the why does not.
Software is good at knowing what is true right now. It is poor at remembering why. factgraph closes that gap by keeping the receipts as it works, so a decision and its justification are one record, not two systems to reconcile.
What problem it solves#
Most software state is mutable: a value changes and the previous one quietly disappears, unless someone bolted on an audit log in advance. In regulated work like anti-money-laundering, finance, and risk, that is not enough. You have to reproduce a past decision and its reasoning on demand. factgraph keeps that proof by construction.
How it works#
factgraph is a Python library for append-only facts and auditable reasoning. Facts are written as entries into a ledger that is never updated or erased in place. It behaves like an accountant’s journal: you don’t scrub a wrong entry, you post a correcting one, and both stay visible. Taking a fact back is a revocation that points at the original, so “was this ever true, and when did it stop being true?” has an answer on the record.
On top of the ledger, you write rules and evaluate them. Each result row comes back with a deterministic proof that shows, condition by condition, exactly which facts it rests on, and replays the same way every time. Auditability is not a logging mode you switch on. It is built into the store. You read the history; you don’t reconstruct it.
It explains itself#
A derived fact justifies itself, condition by condition, in plain language, and replays the same proof every time. Write one rule: flag any single transfer at or over the $10,000 reporting threshold (a Currency Transaction Report). Given Alice’s $12,000 transfer and Bob’s $5,000, factgraph flags exactly Alice’s and shows its work:
Txn T1 flagged · single transfer at or over the reporting threshold · customer Alice · holds
- Txn T1 amount is 12000 ✓
- 12000 ≥ 10000 ✓
- Txn T1 is by Customer C-ALICE ✓
- Customer C-ALICE name is Alice ✓
Each line names the exact fact it rests on. Everything runs locally: no services, no network. A saved ledger is guarded by its schema, so last month’s data can never be reopened under the wrong one.