# FactBlock

> An open format for claims and their history. Build agent memory that tracks claims, evidence and changes, and lets you query what was known at any point in time. An open file format and Python library (`pip install --pre factblock`) for memory that is read as of a point in time: only what was known then, only what was in force then, with corrections and verdicts attached. Plain files, no server.

Use it when an agent answers from information that changes: prices and policies that get replaced, answers that get corrected, promises and predictions that get settled, backtests that must not see the future. Every read takes `as_of`. A change is never an edit: it is a new block plus a `SUPERSEDES` link, and a verdict is a separate row, each with its own `known_at`. Rows you already have go in with `factblock import file.csv -o brain/` (no model; `factblock sample --policies irs/` writes the IRS business mileage rate, 2022 to 2026, as CSVs to try it on); prose goes through `factblock extract`. `factblock track-record brain/ --as-of <date> --by speaker` counts right, wrong, open and overdue, the hit rate, and how many statements were on record before they were resolved; `--ids` counts only the calls like the one you are weighing. `factblock.timeline(bundle, as_of)` draws what happened to each statement over time, optionally over a numeric series, as a Vega-Lite chart.

## Docs

- [README](https://raw.githubusercontent.com/factagora/factblock/main/README.md): install, the first five minutes, `context()` for prompts, `recall()`, `why()`, analytics, syncing with a hosted ledger
- [SPEC](https://raw.githubusercontent.com/factagora/factblock/main/SPEC.md): the format. Three clocks, six invariants, read semantics, JSONL and Parquet profiles, writing and import rules
- [Agent skill](https://raw.githubusercontent.com/factagora/factblock/main/.claude/skills/factblock/SKILL.md): the API in one page, for coding agents

## Examples

- [Support agent](https://raw.githubusercontent.com/factagora/factblock/main/examples/support-agent/README.md): five dated support questions, a date filter vs FactBlock (0/5 vs 5/5)
- [Analysis](https://raw.githubusercontent.com/factagora/factblock/main/examples/analysis/README.md): DuckDB + Jupyter over a real bundle; three views with an id and source on every mark, then the same data as a model's context with cited ids traced to the recording
- [Promises](https://raw.githubusercontent.com/factagora/factblock/main/examples/promises/README.md): promises and verdicts from one CSV; open, past due, broken, kept as of any date
- [Real sample](https://raw.githubusercontent.com/factagora/factblock/main/samples/cramer/README.md): two years of one public figure's statements, links and settled calls
- [StreamingQA bench](https://raw.githubusercontent.com/factagora/factblock/main/bench/streamingqa/README.md): how often a time-ignorant recall leaks the future (79.7% of questions)

## Optional

- [CHANGELOG](https://raw.githubusercontent.com/factagora/factblock/main/CHANGELOG.md)
- [CONTRIBUTING](https://raw.githubusercontent.com/factagora/factblock/main/CONTRIBUTING.md)
