# FactBlock

> Agent memory with a track record. Record claims, predictions and commitments, judge them on outcomes, and show which were on record before they were resolved. 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); 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)
