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.

It is a temporal causal knowledge graph: every block keeps when (said, learned, in force, judged) and why (the reasons given, the source, the evidence behind its verdict), so your AI reads it as of any date.

Your data is full of claims: facts, opinions, predictions, promises. FactBlock extracts them, keeps when they were said and when you learned them, links what caused what, and never overwrites what changed. Your agent recalls them as of any moment, so it decides on what was knowable then, not on hindsight.

pip install --pre factblock                           # alpha: --pre until 1.0
factblock sample brain/                               # six dated claims, a reversal, three verdicts
factblock scan brain/ --as-of 2024-05-01              # what was known that day, and what was hidden
factblock recall brain/ "interest rates" --as-of 2024-05-01   # the blocks about something, as of that day
factblock why brain/ c3 --as-of 2024-10-01            # the causal chain behind a block
factblock resolve brain/ belief:fed:direction --as-of 2024-10-01
factblock track-record brain/ --as-of 2025-01-01  # right, wrong, open, hit rate; which were on record before they were resolved
factblock import kb.csv --backfill -o brain/          # rows you already have: id, text, said_at, effective_from, known_at, replaces
factblock import crm.csv --backfill -o brain/ --map Claim=text,Date=said_at   # your own column names
factblock extract transcript.txt --observed-at 2024-03-20 --speaker "Jim Cramer" --backfill -o brain/   # prose, through your model key

$ factblock why brain/ c3 --as-of 2024-10-01
subject: c3  2024-06-20  Housing demand falls as mortgages track yields
    cause (CAUSES): c2  2024-04-10  Bond yields rise after the rate hike
        cause (CAUSES): c1  2024-03-20  The Fed raises interest rates
            successor (SUPERSEDES): c4  2024-09-18  The Fed cuts interest rates
as of 2024-10-01  hidden: nothing  backfilled: 4 rows in 3 batches

Run the same command --as-of 2024-05-01 and the chain stops at c2, because c3 was not known yet. Add --json to any read for the machine form.

import factblock
print(factblock.context("brain/", "interest rates", as_of="2024-10-01"))
# - 2024-09-18: The Fed cuts interest rates
# - 2024-03-20: The Fed raises interest rates (learned 2024-04-15)
#   replaced 2024-09-18 by: The Fed cuts interest rates
#   verdict: true (decided 2024-05-01 by process:tckg-resolver)
# - 2024-04-10: Bond yields rise after the rate hike (learned 2024-04-15)
# (as of 2024-10-01)

That string goes into your agent's prompt. The old claim is still there, marked as replaced, with the verdict it had as of that day; ask as_of="2025-01-01" and the verdict reads false, because it was re-resolved in December. A date filter would show both claims side by side with nothing to say which one stands. examples/support-agent runs five support questions both ways: a date filter puts a stale answer into the prompt on all five, FactBlock on none. factblock.recall(...) returns the same blocks as dicts with a certificate, and factblock.scan(...) returns everything visible as pyarrow tables.

brain/ is a folder of plain files. Commit it to git, query it with DuckDB, hand it to another agent, or sync it with a hosted ledger. Nothing here needs a server.

Backtest it without hindsight. The same files are a table, and they keep what a table of statements loses: when each verdict became known, what replaced what, which reasons were given. examples/analysis backtests two years of one commentator's market calls in DuckDB, then gives a model the same data as of a date and traces every line it cites back to the recording.

What comes out

Two years of one public figure's statements, as files. samples/cramer is Jim Cramer on CNBC, 2024-09 to 2026-09: 2,091 blocks, 1,169 links he drew between them, 779 priced calls scored at their horizon. Every block links to the recording and the timestamp.

$ factblock scan samples/cramer --as-of 2025-01-01 | head -1
as of 2025-01-01  hidden: 1775 nodes, 1025 edges, 753 resolutions  not in force: 15 nodes  backfilled: 471 rows in 52 batches

$ factblock why samples/cramer 1b77a1a885470207 --as-of 2026-09-10
subject: 1b77a1a885470207  2025-07-17  The current data center buildout is the largest construction boom since World War II.
    effect (CAUSES): c43aac6a842836bf  2025-07-17  Lead contractors such as ABB and Legrand are receiving strong data center orders.
        effect (CAUSES): 041ef1dfd5dbb6df  2025-07-17  Companies involved in the data center buildout, such as Eaton and Parker-Hannifin, are receiving a large number of new orders.
            effect (CAUSES): 2751ba237ecd5415  2025-07-17  Parker-Hannifin is a good stock to own.
            effect (CAUSES): 7d3af08ba4f4f027  2025-07-17  Eaton is a good stock to own.

A call and its verdict carry separate clocks, so the same read gives different answers on different days:

66027d5985bf9605  prediction  2024-09-11  Nvidia's business is currently growing, not slowing down.   NVDA, up
  verdict: came_true   decided 2024-12-10   NVDA +23.3% over 90 days   known 2024-12-10

As of 2024-11-01 the call is open. As of 2024-12-10 it came true. As of 2024-09-10 it does not exist yet. to-claimreview samples/cramer --as-of 2025-06-01 writes the 197 verdicts known by then as schema.org JSON-LD.

Every block carries two clocks: asserted_at, when it was said (--observed-at for extract), and known_at, when your system learned it. By default that is now, so a 2024 transcript extracted today is hidden from a 2024 read; --backfill declares it known when it was said, which is what you want for material from the past. --provider fake splits sentences without a model, enough to see the files; gemini and openai do the real extraction with your key. Every edge carries a type with a family (causal, argumentative, temporal) and the speaker's own confidence. Nothing is a chunk, nothing is a bare triple; the unit is a dated statement someone made.

When

Memory that cannot answer "what did I know on that date" leaks the future into every evaluation and every backtest. FactBlock reads are always as of an instant:

import factblock
r = factblock.scan("brain/", as_of="2024-05-01")
r.nodes                 # pyarrow.Table: only blocks known by 2024-05-01
r.certificate           # {'as_of': ..., 'masked': {'node': 4, 'edge': 2}, 'backfill': {'batches': 1, 'rows': 3}}

The certificate says how many rows were hidden because they were learned later, and which rows were backfilled from the past under a declared batch. An answer with masking is a correct answer for that instant, and it says so.

A statement that gets corrected or reversed is not overwritten. The new block points at the old one with SUPERSEDES, both keep their intervals, and a read as of a date in between still sees the old one. That is how "when did they change their mind" stays answerable.

Why

Edges are the speaker's reasoning, not co-occurrence: CAUSES, CONTRIBUTING_FACTOR, TRIGGERS, PREVENTS, SUPPORTS, CONTRADICTS, CONCURRENT_SIGNAL, SUPERSEDES. why walks them from a block to the given depth, as of an instant, and names the role at every hop (cause, effect, successor, contradiction), so the chain never includes a reason that was not yet known.

Declared facts make conflicts explicit. Declare belief:fed:direction with a policy (latest_valid, latest_observed, source_priority, strict) and resolve returns one value or the reason there is none: no_data, not_yet, no_value_at, unresolved_conflict. It never guesses.

Timelines

Once your data is a bundle, one call draws what happened to each statement over time, as known on a day you pick.

t = factblock.timeline("examples/promises/brain", as_of="2026-05-10", group_by="customer")
t                                                  # in Jupyter, the chart; hover for the history and block id, click for the source
t.save("promises.html")                            # .html needs nothing; .png and .svg need factblock[viz]

One bar per statement, from the day it was said to the day it was replaced, judged or due, coloured by what became of it. The rest of its story (took effect, learned late, replaced by what, every verdict with its date) is in the tooltip and in t.claims and t.events. Read as of an earlier day and the verdicts, replacements and statements learned after it are not drawn.

Add a numeric series (prices, rates, any CSV with a date and a value) and the same statements sit on it where they were said:

t = factblock.timeline("samples/cramer", as_of="2025-06-30", query="SPY").with_series("sp500.csv", "S&P 500")

Values after the as-of day are dropped too. On the command line: factblock timeline brain/ --as-of 2025-06-30 -q SPY --series sp500.csv -o spy.html. The chart is a Vega-Lite spec (t.spec()), so it renders the same in a notebook, a web page (react-vega, vega-embed), or as an image in a chat answer. t.to_html(inline=True) is one self-contained page that renders with no network; t.to_markdown() is the same timeline as text for clients that cannot draw; t.to_dict() is the data for any other renderer, versioned as schemas/timeline.v1.schema.json. samples/fed-funds-rate.csv (FRED DFF, public domain) goes with samples/rates; the S&P 500 is licensed, so download it from FRED (SP500) yourself.

In a chat answer. An MCP server returns t.to_mcp() from its tool and serves factblock.mcp_app_html() as the resource ui://factblock/timeline (mime type and _meta in factblock.timeline.MCP_APP_MIME and MCP_APP_META; the tool's _meta is MCP_APP_TOOL_META). Hosts that support MCP Apps (Claude, ChatGPT, VS Code) then draw the chart inside the answer, in the host's theme; the rest show the markdown. The tckg timeline tool does exactly this. The same question asked as of two days:

On 30 April the last call ("bigger forces are going to crush the entire market") is open; on 30 June it has been judged wrong and five later calls have appeared. The April answer cannot use what was learned in May.

What one statement rests on. factblock.graph(bundle, block_id, as_of) draws the links around one statement: what it rests on above it, what came of it below, each row written in full, each dot coloured by what became of the statement. It walks why(), so a link or a verdict learned after as_of is not drawn.

g = factblock.graph("samples/cramer", "fdc79a63b9b44a7f", as_of="2025-06-30", depth=2)
g.nodes, g.edges     # {id, label, type, when, resolution} and {id, from, to, label}: a graph renderer takes them as they are

Claims it is good at

The common thread: a claim has a speaker, a time, a reason, and a later verdict. RAG keeps chunks, entity graphs keep triples, chat memories keep summaries. None of them keep that.

Use it with your AI

Recall as context. recall ranks the visible blocks about a query and context turns them into prompt lines. Matching is by keyword over the statement and the payload's text (speaker, quote, imported columns): a shared four-letter stem counts, so cost finds "costs" but price does not; an empty query lists everything, newest first. verdict="did_not" (or "broken" for a commitment, "open", "resolved", "overdue") narrows to settled, unsettled or past-due blocks, kinds= to kinds of your own such as commitment. A change that was announced but is not in force yet is shown as changes <date> to: ..., so the agent can say "$30, rising to $36 on 15 March". Read with as_of set to the decision time (now, or a past instant for a backtest). scan returns everything visible as Arrow tables when you want to build your own.

Analytics. to-parquet writes the Parquet profile. DuckDB reads it with no Python through duckdb/factblock.sql: factblock_nodes(bundle, as_of), factblock_edges, factblock_certificate. Spark and Databricks read the same files.

From an existing graph. factblock/adapters/graphiti.py turns a Graphiti graph into a bundle; the store's own timestamps become declared backfill batches, because a store that stamped time itself is a witness.

Speak the standards. to-claimreview writes the verdicts visible as of an instant as schema.org ClaimReview JSON-LD; to-okf writes the blocks as an Open Knowledge Format bundle (markdown with frontmatter) that catalogs and agents read; from-factcheck brings published fact-checks in (Google's Fact Check Tools API shape) as dated claims with dated verdicts, every row under a batch declared at its review date. None of them is the storage format; they are doors.

Check your evals. leak takes a question set with dates ({asked_at, evidence: [block ids]} per line) and reports how many answers depend on blocks learned after the question's date, naming each block and when it became known. A date-only asked_at means the start of that day, so news ingested later that day counts as a leak; give a timestamp to be exact. It exits non-zero on a leak, so it fits in CI. On StreamingQA (36,378 dated questions about dated news), a recall that ignores time rests on a block learned after the question for 80% of questions; the same recall as of the question date leaks nothing and says how much it hid. If your memory benchmark never reports this number, it is measuring hindsight.

Backtests with ingest lag. When each item has a publication time and the time your system ingested it, publication is said_at and ingestion is known_at. Do not pass --backfill: it would date every item to its publication and erase exactly the lag you are testing.

# news.jsonl: {"id": "n2", "text": "Acme cuts Q1 guidance to $1.0B.", "said_at": "2025-03-20T21:00:00Z", "known_at": "2025-03-21T02:00:00Z", "replaces": "n1"}
factblock import news.jsonl -o news/
factblock leak news/ questions.jsonl      # {"id": "q2", "asked_at": "2025-03-21T00:00:00Z", "evidence": ["n2"]} per line; --evidence-key for another name

A date-only as_of means the end of that day for reads and the start of that day for leak, so build each question's context with its full timestamp and give leak the same one. leak checks knowledge time and validity. Evidence that was knowable but already replaced when the question was asked is not a leak; recall marks it superseded_by if you need to catch that too.

For coding agents

The whole API in one block. It runs as is; tests/test_readme_agents.py keeps it that way.

pip install --pre factblock
factblock sample brain/          # or: factblock extract notes.txt --observed-at 2024-03-20 -o brain/ --provider gemini

import factblock
print(factblock.context("brain/", "interest rates", as_of="2024-10-01"))   # prompt lines, as known that day
r = factblock.recall("brain/", "interest rates", as_of="2024-10-01")       # same, as dicts
c1 = next(i for i in r["items"] if i["id"] == "c1")
print(c1["superseded_by"]["statement"], c1["verdict"]["outcome"])          # what replaced it, how it was settled

Words are matched as written. To match by meaning too, pass embed=factblock.embedder("gemini") (or "openai", or your own function) to recall, context or timeline, or --embed gemini on the command line: "price" then finds a block that says "costs". The vectors are an index cached in brain/.factblock-cache/, not part of the bundle.

Three rules: every read takes as_of (no default); a change is a new block plus SUPERSEDES, never an edit; known_at is when you learned a row: give it honestly (default now; --backfill means when it was said) and let import, extract or write_bundle declare the batch that attests it. Never claim a ledger stamp you did not get. Claude Code users can copy .claude/skills/factblock into their project; other agents read llms.txt.

Write rows you already have

Most memory starts as rows, not prose: a pricing table, a policy log, a CRM export. import takes them as they are, no model, and every date comes from your columns.

id,said_at,effective_from,known_at,text,replaces
p1,2026-01-10,,,The Team plan costs $30 per user per month.,
p2,2026-02-20,2026-03-15,,The Team plan costs $36 per user per month.,p1

said_at (or asserted_at) is when it was said, effective_from (or valid_from, default said_at) when it takes effect, known_at when you learned it, replaces the id it supersedes. A row with target, outcome and decided_at is a verdict. Any other column goes into the payload. In Python, any dicts with the format's own names will do:

factblock.write_bundle({"nodes": [{"id": "r1", "kind": "claim", "statement": "Annual plans refund within 30 days.",
                                   "asserted_at": "2026-01-10", "known_at": "2026-01-10"}]}, "brain/", append=True)

write_bundle fills the manifest, declares one batch per known_at, and validates the whole folder before it writes; a bundle that would fail validate raises and is not written.

Words for verdicts

Same files, hosted

A folder is one writer's memory. factagora.ai is where a brain/ meets other people's. Upload it and it comes back with more rows, never changed rows: verdicts on predictions whose horizon has passed (mechanical ones from prices and published figures, judgment calls from the community, each with evidence), links to what other people claimed about the same thing (SUPPORTS, CONTRADICTS), entities resolved across worldviews. Every added row carries its own known_at, stamped by the server rather than by you, so a verdict is as replayable as the claim it judges: as of last June, the prediction was still open.

It also gives what a folder cannot: one ledger shared by many agents and users, natural-language writes at scale, and an MCP address per worldview, so a user plugs one into Claude or Cursor and reaches nothing else. Browse public worldviews there, or ask one a question as of a date. GET /v1/export hands the folder back at any instant. The format is the contract; you can leave with your files.

factblock sync brain/ <url> --space <space> moves rows both ways by identity: what only the folder has goes up, what only the ledger has comes down, nothing is changed in place. A row's known_at travels as the batch that attests it, so the ledger learns a 2024 transcript as known in 2024, not today, and the folder learns a verdict at the instant the ledger stamped it. Run it again and it is a no-op. --pull-only into a folder that does not exist yet clones a space. The token is $TCKG_TOKEN or --token.

Bring your own store. sync talks to a store through two methods, pull(as_of) and push(manifest, nodes, edges) (factblock/sync.py, the Store protocol). TckgStore is the one for tckg over HTTP; tests/test_sync.py has a forty-line in-memory one that shows the single rule a store has to keep: declare the bundle's batches as your own backfill batches, never adopt an imported row as learned now. A SQLite, Neo4j, or warehouse store is the same two methods.

The same ledger runs closed for companies at app.factagora.com: your support logs, your sales promises, your own assistant's assertions, as claims with verdicts, inside your tenant.

The format

SPEC.md is short. Six invariants (present, attested, unique, typed, declared, verdicts on statements that were made), a JSONL profile and a Parquet profile, read semantics, and the conformance checks validate runs (thirteen of them). Projections to OKF and ClaimReview are described, and to-claimreview writes the verdicts visible as of an instant as schema.org JSON-LD, so a bundle can feed systems that speak those.

Format, not platform. Apache-2.0. tckg is one writer of this format; nothing here requires it. Contributions are welcome under the DCO: see CONTRIBUTING.md.

Status

1.0-draft.1. Works today: import (CSV or JSONL rows, no model), extract (providers gemini, openai, and fake for offline runs; the claims profile is three files under factblock/profiles/claims that any language can run), validate, scan, recall, why, leak, resolve, track-record, timeline, graph, to-parquet, sync with a tckg ledger or a store of your own, to-claimreview, to-okf, from-factcheck, the DuckDB macros, the Graphiti adapter, and the tckg export. Extraction quality on real transcripts is being measured separately; the rules are the ones a dated-claims pipeline has run on hundreds of videos. On PyPI as 1.0.0a9 (pip install --pre factblock). The format reaches 1.0.0 when a reader or writer maintained outside this repository exists; until then minor versions may change fields and the manifest's factblock_version says which one a bundle speaks.

uv sync --extra gemini                                 # or --extra openai; the fake provider needs nothing
export GEMINI_API_KEY=...                              # or GOOGLE_GENAI_USE_VERTEXAI=1 GOOGLE_CLOUD_PROJECT=... for Vertex
echo "The Fed will keep raising rates this year. That means bond yields keep climbing." \
  | uv run python -m factblock extract - --observed-at 2024-03-20 --speaker "Jim Cramer" --backfill -o brain/
uv run python -m factblock scan brain/ --as-of 2024-05-01

uv sync
uv run python -m factblock validate samples/rates
uv run python -m factblock scan samples/rates --as-of 2024-08-01
uv run python -m factblock why samples/rates c3 --as-of 2024-10-01 --json
uv run python -m factblock leak samples/rates samples/rates-questions.jsonl
uv run python -m factblock resolve samples/rates belief:fed:direction --as-of 2024-10-01
uv run python tests/test_rates.py && uv run python tests/test_why.py && uv run python tests/test_recall.py && uv run python tests/test_leak.py && uv run python tests/test_sync.py && uv run python tests/test_claimreview.py && uv run python tests/test_okf.py && uv run python tests/test_factcheck.py && uv run python tests/test_graphiti_adapter.py && uv run python tests/test_duckdb.py