readproof

Website · Docs · Install · Quickstart · Example agent · MCP · DeepSeek Harness · Roadmap

Readproof gives every document an AI agent reads a stable identity, a freshness policy, and a content-addressed snapshot — and records every run as a manifest you can diff, replay byte for byte without touching the live source, and hand over as evidence.

Models are probabilistic, but many context failures are infrastructural. Agent reliability is bounded by context reliability.

It is not a vector database, not an observability tool, not a prompt registry, not a memory system. It sits underneath those and makes their inputs reproducible. Install-time lockfiles (Microsoft APM, skills-lock.json) pin an agent's static configuration; Readproof pins the runtime documents, per run.

Sixty seconds, end to end

1. Give a document an identity and a freshness policy, then record a run.

readproof resource add readproof://demo/policies/refunds \
  --source-type filesystem --path policies/refunds.md --policy require_fresh
readproof run --id run-a readproof://demo/policies/refunds

Committed manifest manifest_01M0GQH8K8… for run run-a (1 entry)

2. The source changes. A later run picks it up — and the diff says exactly why.

printf 'Products can be refunded within 14 days.\n' > policies/refunds.md
readproof run --id run-b readproof://demo/policies/refunds
readproof diff run-a run-b

~ readproof://demo/policies/refunds
  why: source revision sha256:c8b0bb212e93 → sha256:8f4b00474456
  -Products can be refunded within 30 days.
  +Products can be refunded within 14 days.

3. Replay the first run from the store — the file is gone or changed, the bytes are not — and prove it.

readproof replay run-a
readproof evidence export run-a --with-content --out bundle.json
readproof evidence verify bundle.json

Products can be refunded within 30 days.
Replay verified: SHA256 match for 1/1 entries.
evidence verified: 1 entry, merkle root a9b73469f1a6…, replay match 1/1

SHA256(original) == SHA256(replay) is a test, not a slogan: the reference demo asserts it over SQLite, over Postgres + MinIO, and over a real HTTP round trip (examples/refund-agent).

Why

How it works

• Identity — readproof://<namespace>/<path>, independent of where the bytes live.
• Policy — require_fresh (re-verify every resolve), allow_stale --max-age (reuse within a TTL), or pin a reviewed snapshot by tag: …@prod delivers exactly that snapshot, no fetch, policy not consulted. Promotion is one pointer move; it is recorded and revertible.
• Snapshot — immutable, content-addressed; identical bytes dedupe to one blob.
• Manifest — the ordered list of what a run was delivered, by hash; entries record the ref they were mounted by, so moving a tag later can never change what a committed manifest replays.
• Evidence — derived from a manifest on demand; the Go CLI and the TypeScript SDK produce byte-identical bundles, and the same Merkle root appears on the run's OpenTelemetry span.

Deep dive: docs/architecture.md.

Quickstart

Install

# Go 1.26+ — lands in $(go env GOPATH)/bin
go install github.com/fbzz/readproof/cmd/readproof@latest
go install github.com/fbzz/readproof/cmd/readproofd@latest   # only if you run the server

# macOS — the cask installs both binaries
brew install fbzz/tap/readproof

Or download a prebuilt archive for your platform from GitHub Releases: readproof_<version>_<os>_<arch>.tar.gz (.zip on Windows) contains readproof, readproofd, LICENSE, NOTICE, and this README.

Plainly: all three work once this repository is public and the first release is cut. Until then, build from source — which is what the embedded walkthrough below does anyway.

Embedded mode

One binary, a local .readproof/ directory, no services:

git clone https://github.com/fbzz/readproof.git
cd readproof
go build -o readproof ./cmd/readproof        # Go 1.26+

# identity + source + freshness policy
./readproof resource add readproof://demo/policies/refunds \
  --source-type filesystem \
  --path examples/refund-agent/policies/refunds.md \
  --policy require_fresh

./readproof run --id run-a readproof://demo/policies/refunds
./readproof replay run-a

Client/server mode

Postgres + S3-compatible store, one HTTP API for every client:

# Postgres, MinIO, an OTel collector and readproofd, from a clean clone
cp .env.example .env
docker compose up -d --build

# every command now talks to the server
export READPROOF_SERVER_URL=http://localhost:8080
./readproof get readproof://demo/policies/refunds

A containerized readproofd cannot see your host filesystem; use GitHub/HTTP sources there, or run readproofd --data-dir ~/.readproof on the host.

What you get

Examples

Documentation

Status

v0.3.1 — Apache-2.0. Stable core (identity, policies, tags, snapshots, manifests, provenance-aware diff, strict replay, evidence), MCP server, OpenTelemetry, TypeScript SDK, SQLite or Postgres + S3, DeepSeek Harness plugin, three runnable examples. CI runs Go build/vet/test, the SDK and example suites, the DSH plugin suite, and a Docker Compose integration job that replays the demo against the built readproofd image on every push.

Next, in order (docs/roadmap.md): public release and packages (binaries, npm), Python SDK, trace-context propagation over the HTTP API, MCP HTTP transport, a source policy file (allow-lists), signed and OCI-distributed evidence bundles, tag promote, more adapters.

Security

No plaintext credentials at rest (env references resolved at fetch time; redaction everywhere), optional API-key auth on readproofd, labeled dev-only Compose credentials, dependency scanning. Not yet: SSRF allow-list for the HTTP adapter, signed bundles. Report vulnerabilities privately — see SECURITY.md.

Contributing

go build ./... && go vet ./... && gofmt -l . && go test ./... must be green with no external services; the SDK, examples, and plugin each have npm test. Conventions, the live-infra test block, and the pre-PR checklist are in CONTRIBUTING.md.

Community — questions and ideas in Discussions, bugs and feature requests in Issues, vulnerabilities privately via SECURITY.md. Everyone taking part is held to the Code of Conduct.

License

Apache-2.0 · NOTICE

_{Built for teams who have to answer for what their agents read.}