# 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 IRS mileage quickstart, reading as of a day and in force at another, `context()` and `recall()` for prompts, your own rows, syncing with a hosted ledger
- [Timelines and graphs](https://raw.githubusercontent.com/factagora/factblock/main/docs/timelines.md): statements over time as a chart, over a numeric series, in a chat answer, and what one statement rests on
- [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

## Guides

- [Your RAG answers with a rate that changed](https://raw.githubusercontent.com/factagora/factblock/main/docs/guides/stale-policy-in-rag.md): a date filter against as-of reads on the IRS mileage rate
- [Show what an AI answer rested on, and what changed since](https://raw.githubusercontent.com/factagora/factblock/main/docs/guides/answer-evidence-history.md): record an answer, link its evidence, walk it later with `why`
- [Evaluate an agent only on what was known at the time](https://raw.githubusercontent.com/factagora/factblock/main/docs/guides/evaluate-as-of.md): `leak` on an evaluation set

## 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)
