ProofOfContext

The memory that stops AI agents — and engineers in fresh sessions — from silently contradicting decisions your team already made: the wrong database, a banned dependency, an architecture call quietly reversed.

brain.md and the decision log are the source of truth. ProofOfContext records a project's decisions once, feeds them to a fresh agent before it writes, and enforces them when code lands.

Not a security scanner. A scanner asks "is this code insecure?" from a shared rule library. ProofOfContext asks "does this contradict a decision we made?" — Postgres-not-Mongo, one billing source of truth, stdlib-only core. Those aren't vulnerabilities and aren't in anyone's library; they live in your team's head. Security is a library problem; architectural intent is a memory problem.

Trust

Nothing is taken on faith: the package ships as readable source, makes no network calls, and sends no telemetry — and every one of those claims comes with a command you can run against your installed copy to verify it. See TRUST.md.

Install

The CLI is pure standard library — no runtime dependencies — and runs on Python 3.8+, tested through 3.14. End-of-life interpreters are supported deliberately: the stdlib-only core makes them nearly free to keep, and the repos that most need a decision gate are often pinned to older Pythons.

pipx install proofofcontext   # recommended: puts `poc` on your PATH everywhere
# or: pip install proofofcontext

For development, install from source instead:

git clone https://github.com/prove-ai/proof-of-context.git
cd proof-of-context
pip install -e .

Uninstall leaves zero trace:

rm -f .git/hooks/pre-commit && rm -rf .context/ && pip uninstall proofofcontext

(Details and what each piece is in TRUST.md.)

Commands

poc init              scaffold .context/ + a pre-commit hook (with human approval)
poc decide [flags]    record one human-approved decision (appended to the log)
poc context "<task>"  emit a paste-ready context package for a fresh agent session
poc why "<question>"  answer "why did we decide X?" from the decision log
poc check <path>...   fail if a file contradicts a recorded decision (deterministic, offline)
poc evaluate "<rule>" advisory KEEP / REVISIT / RETIRE verdict on a rule (never blocks)
poc skill [refresh]   keep the generated Claude skills in sync with .context/
poc stats             summarize the decision-collision ledger

# operational assumptions — beliefs about the codebase, recomputed from real git history
poc assume scan <repo>     compute the assumption portfolio (coupling, stability, debt)
poc assume show "<pair>"   render one belief's claim card (trend, sparkline, real-SHA evidence)
poc assume update <repo>   recompute the assumptions new commits touched; report the move
poc assume verify "<pair>" re-derive a belief's confidence from git a second way to prove it

Try it

Follow docs/GETTING-STARTED.md — a 5-minute first run. You install poc, open the governed example in examples/billing-service/, and watch an AI-written MongoDB change get blocked at git commit because it contradicts the team's recorded PostgreSQL decision — then fix it and watch the commit pass. It's the real workflow, not a script.

How it works

Team memory lives in .context/ (brain.md, decisions.md, ledger.jsonl, graph.md). poc check runs deterministically and offline — token matching with comments and strings ignored, no LLM, no network, no per-commit cost — so it runs identically in a pre-commit hook, in CI (GitHub Action), and by hand. Nothing is written to .context/ without a human accept / edit / reject step.

Docs

• docs/GETTING-STARTED.md — 5-minute first run
• TRUST.md — verify the no-network / no-telemetry claims yourself
• docs/FAQ.md — trust and verification, false positives, monorepos, --no-verify, other hooks, pricing
• docs/WRITING-RULES.md — writing Forbids: lines that catch what you mean
• docs/TROUBLESHOOTING.md — hook not firing, PATH, merge conflicts, local-vs-CI
• docs/ASSUMPTIONS-LIMITS.md — honest limits of the assumptions engine
• CHANGELOG.md — release history (semver)

Repo layout

The repo root is the product: the proofofcontext/ package, the poc CLI, .context/ (this repo's own decision memory — the tool dogfoods itself), demo-sample/, docs/, and the web pitch (app.py, deployed to Render via render.yaml / Dockerfile — pip install .[web]).