Provenance

Provenance is on every row in Relata, not bolted on top. The provenance layer (relata-prov) mints PROV-O assertions, links them into hash-chained commit manifests, content-addresses blobs, and supports byte-identical replay of any logged exhibit.

WITH PROVENANCE

A trailing SQL modifier (must come after LIMIT) — adds three lineage columns to every row:


SELECT * FROM Event
LIMIT 10
WITH PROVENANCE

Column	Meaning
`prov_source`	The source system that produced the row
`prov_agent`	The agent (human or machine) that authored it
`prov_hash`	Content-addressed hash tying the row to its blob

EXPLAIN REPLAY

EXPLAIN REPLAY('<exhibit-id>', SEQ => n) re-derives a logged exhibit link’s seal byte-identically — so an auditor can reproduce any conclusion in court:


EXPLAIN REPLAY('exhibit-7', SEQ => 5)

Commit manifests

Every commit produces a manifest with:

The rows in the commit (content-addressed by hash)
The principal that authored the commit
The purpose declared at commit time
The timestamp (i64 ns UTC)
A hash that chains to the previous manifest

The chain is tamper-evident — any retroactive edit breaks the chain and is detectable by relata doctor or /audit/count (chain_valid: false).

Content-addressed blobs

Media and large bodies are content-addressed (SHA-256) into a separate blob store, so the same bytes are stored once and deduplicated. The blob store is wired to:

The S3 door (objects ≥ RELATA_S3_BLOB_THRESHOLD_MB, default 4 MiB, are stored out-of-row)
The media worker (ingest_media MCP tool, base64 payloads)
The IVF cold tier for vectors (PagedAnnIndex)

Audit log replay

The audit log records every query, every write, every tool invocation — with principal, timestamp, purpose, cost units, and a hash chain entry. The audit replay path:

Reads the manifest chain head-to-tail.
Re-derives each row from its blob hash.
Confirms the chain is intact.

Use the Python SDK’s AuditClient:


from relata import RelataClient, AuditClient
 
with RelataClient(url, bearer_token=token, purpose="compliance_review") as client:
    audit = AuditClient.from_client(client)
    entries = audit.entries(filter={"principal": "api-user",
                                    "since": "2026-01-01T00:00:00Z"})
    receipt = audit.signed_receipt(exhibit_id="exhibit-7")
    pdf     = audit.export_pdf(filter={"case_id": "case-42"})

Provenance + agent memory

When an agent uses the cognitive verbs (remember, consolidate, justify, …) each memory item carries:

The session id that produced it
The principal that authored it
The purpose declared
The confidence score
The provenance chain back to the source rows

justify returns the full provenance + audit trail for a memory item.