Proofpress

Typed knowledge infrastructure for continuous learning.

Build on every discovery. Proofpress turns agent-produced findings into typed, evidence-bound knowledge that teams and agents can inspect, review, and reuse. Each finding carries its evidence, dependencies, and conditions for reuse.

Verifiable. Traceable. Auditable.

Spend less time reconstructing past work. Carry forward what the team learned, recognize what needs rechecking, and give the next experiment a better starting point.

Website · Quick start · Localhost guide · Product thesis · Remote MCP

Quick start

New here? Choose a path, then complete one finding → human review → reuse loop.

What you want	Start here
Try the product with synthetic data	Local demo — no account or credential.
Use your own files with Claude Code on localhost	Your own local workspace — an empty database, full review UI, file-to-finding instructions and agent setup.
Join an existing team workspace	Connect to Hosted — use your team's assigned URL and Agent credential.
Deploy on your own server	Self-hosting — persistent storage, credentials and backups.
Develop Proofpress	Contributing.

Try the local demo

You need Python 3.11+, Git, and uv. Use a macOS/Linux terminal, or Windows WSL2:

uv tool install --with "mcp>=2,<3" "git+https://github.com/chenmingtang830/proofpress.git"
uv tool update-shell

Open a new terminal if proofpress is not found, then run:

proofpress quickstart --ui

This creates ./proofpress-demo with synthetic evidence and candidates, starts the local review UI and opens your browser. Inspect a candidate and make a human review decision. Stop with Ctrl-C; the workspace remains on disk. Choose another empty destination with --workspace PATH; use --no-browser for a headless demo. The generated proofpress-mcp.json targets this demo's Git-backed ledger, not the SQLite workspace below.

Use your own files on localhost

For real work, start an empty workspace. After installing above, run the bootstrap command yourself in a private terminal:

umask 077
mkdir -p "$HOME/.local/share/proofpress"
proofpress hosted --database "$HOME/.local/share/proofpress/workspace.db" \
  bootstrap --workspace-id workspace:research --owner-principal human:owner

Save the returned Owner token and recovery_secret in your password manager; keep them out of agents, chat and Git. Bootstrap runs once. Then start the server:

proofpress hosted --database "$HOME/.local/share/proofpress/workspace.db" \
  serve --host 127.0.0.1 --port 7334

Open http://127.0.0.1:7334 and sign in with the Owner token. Despite the command name hosted, this server stays on your machine. Keep the terminal running; restart with the same database to keep your history. You do not need Docker or a frontend build.

Continue in Localhost: files → Claude Code → review → reuse:

1. Save review criteria in Admin → Verification settings. Human review works without a model key.
2. Issue a separate Agent key and connect Claude Code to this workspace's http://127.0.0.1:7334/mcp endpoint with the maintained plugin/skill.
3. Let Claude read selected local files and submit bounded evidence plus candidate findings. There is no generic bulk-upload or folder-crawling UI.
4. Review a finding yourself, then retrieve it in a fresh Claude conversation.

For capture format errors, update the plugin/skill and follow the capture input guide: read proofpress_get_capture_schema before writing and use the bundled helper to prepare exact excerpts and real hashes for selected files or slides.

Proofpress stores submitted excerpts and governance records locally. Claude Code still processes the material it reads under your Claude configuration; localhost does not make the model offline. Optional Proofpress AI checks have a separate provider/processing opt-in.

Use your own AI-assisted review (BYOK)

Provider API keys are encrypted before being stored in SQLite. To enable the API key input, configure the server's PROOFPRESS_SECRET_ENCRYPTION_KEY first. This encryption key is separate from your provider API key and Owner/Agent credentials. The localhost UI offers Copy setup commands using the current database and port, then Check storage again after restarting. Existing saved credentials get original-key recovery instructions. Manual commands follow.

For an instance that has never saved a provider key, stop the server with Ctrl-C, then initialize a persistent encryption key in your private Terminal:

umask 077
mkdir -p "$HOME/.local/share/proofpress"
python3 - <<'PYTHON'
import base64
import os
from pathlib import Path

key_file = Path.home() / ".local/share/proofpress/provider-key-encryption.key"
try:
    with key_file.open("x", encoding="ascii") as output:
        output.write(base64.urlsafe_b64encode(os.urandom(32)).decode("ascii") + "\n")
except FileExistsError:
    pass
PYTHON

The file is created with owner-only permissions and is not overwritten on repeat runs. If you have already stored provider credentials, reuse the original encryption key; generating another key cannot decrypt them.

Load the key and restart your existing database. Run this entire block in the same Terminal tab every time you start the server; change the database path if your workspace uses a different one:

export PROOFPRESS_SECRET_ENCRYPTION_KEY="$(cat "$HOME/.local/share/proofpress/provider-key-encryption.key")"
proofpress hosted --database "$HOME/.local/share/proofpress/workspace.db" \
  serve --host 127.0.0.1 --port 7334

Reload Admin → Verification settings, turn on AI-assisted checks, choose your provider and model, enter its API key privately, review the processing notice, and save. Keep automatic approval off unless you separately choose it. Saving AI settings can process pending findings and incur provider charges.

The key field should now be enabled; after saving, only the provider key's last four characters are shown. A saved key does not prove a successful provider call: verify a review receipt. Keep the encryption file outside Git, retain a protected backup, and reuse it across restarts. Never paste either key into chat. See the complete BYOK guide and troubleshooting.

Connect an agent to a Hosted workspace

From the repository whose agent work you want Proofpress to govern:

1. Install the proofpress Agent Plugin for Codex, Claude Code, or Cursor. It bundles the governed-context skill and policy assets; a separate skill download is unnecessary on the normal path.
2. Add the /mcp URL assigned to your team. The generic plugin intentionally contains no customer endpoint, so it cannot silently connect to another workspace.
3. Complete OAuth with the separate agent credential issued for that client. Never use an owner or recovery credential in an agent client.
4. Start a fresh agent session. If you want repository-specific proposal selection, ask: “Initialize a Proofpress policy for this repository.” Review and commit the generated .proofpress/context-policy.yaml.
5. Give the agent a real task. It will retrieve eligible context when available, submit bounded proposals when warranted, and stop for Human Approval.

For example, Codex users can install from this repository and connect an assigned Hosted workspace as follows:

codex plugin marketplace add chenmingtang830/proofpress --ref main
codex plugin add proofpress@proofpress-plugins
codex mcp add proofpress --url https://YOUR-PROOFPRESS-HOST/mcp
codex mcp login proofpress

Installing the plugin does not create a Hosted workspace, MCP connection, or ledger. Each team needs a separately provisioned Hosted workspace or a self-hosted deployment. See Remote MCP for Claude Code, Cursor, manual fallback, and the full authorization boundary.

Want a managed Hosted Proofpress session and to work with us as a design partner? Tell us about your workflow.

Building Proofpress itself? Use the contribution guide.

Agents generate outputs faster than teams can trust them

The result is saved. The reasoning is scattered. Experiments, evaluations, analyses, and failed attempts leave findings across files, chats, traces, and repositories. The next person or agent has to reconstruct what supports a conclusion, where it applies, and whether it is still current.

Memory helps preserve and retrieve context. Files, embeddings, and knowledge graphs are useful representations. Some memory systems also extract facts, update relationships, and track time. The remaining question is concrete: which finding may the next workflow rely on, under which conditions?

Compression alone won't close the trust gap. Scattered evidence, silent drift, memory laundering, and repeated reconstruction can survive a shorter context.

_{Illustrative model, not measured data. The curve describes the trust gap; it is not a universal mathematical growth law.}

A typed knowledge system

A finding is more than a text record with extra fields. Its type and lifecycle make its role, supporting evidence, dependencies, and reuse conditions explicit. Proofpress applies checks and review decisions to those objects before they enter downstream context.

• Verifiable: inspect the submitted evidence and recorded checks behind a finding.
• Traceable: follow its sources, dependencies, versions, and declared downstream use.
• Auditable: retain review decisions, revisions, withdrawals, and outcome observations.

These properties make reliance inspectable; they do not guarantee that every finding is true or that every relevant event was captured.

Knowledge should be managed like software

Software reuse depends on more than storing and finding source code. The analogy for knowledge is an explicit lifecycle around a usable object:

Software concept	Knowledge counterpart
Compiler	Turn submitted findings into structured, evidence-bound objects.
Type checker	Check evidence, scope, and the rules for reuse.
Dependency manager	Track what a conclusion depends on and what needs reassessment.
Runtime	Return eligible knowledge and record its use in a workflow.

This is an architectural analogy, not a claim of formal proof or a literal compiler implementation.

Capture → Verify → Reuse → Learn → Review

1. Capture findings and evidence. Preserve the source version and intended scope through MCP, CLI, Python, or HTTP.
2. Verify and review. Apply deterministic checks and optional model advice. Human review is the default admission path; agents cannot approve their own claims.
3. Reuse within conditions. Retrieve current, admitted, in-scope knowledge for the requesting actor. Record the exact versions supplied and relied on.
4. Connect outcomes. Attach outputs, tests, and later observations to the work that used a finding.
5. Maintain the lifecycle. Reassess, revise, supersede, or withdraw findings as evidence and dependencies change. Retain prior decisions and history.

The learning loop serves continuous organizational learning. Outcome-based retrieval weighting is a product direction, not a shipped or validated automatic learning engine. Reuse utility is separate from evidence confidence and never grants authority.

Across agents and tools

Existing memory, observability, skills, and workflow tools can supply inputs or consume eligible findings. Proofpress maintains the knowledge lifecycle across them. The Owner workspace lets reviewers inspect support and lineage before admitting, rejecting, or requesting revision.

Task run tracking documents the Run, ContextReceipt, Reliance, Output, and Observation contracts.

Evaluation evidence

• 89.3% → 93.4% rubric completion in the seven-model Harvey LAB-derived controlled evaluation, across 126 paired runs.
• The website evidence section reports the separate 5.5× fewer numeric errors result (11 → 2 incorrect final values, 20 paired chains, 1,600 numeric slots per arm).
• 38.3% fewer executor tokens in the separate Muse Spark 1.1 two-task APEX pilot. This excludes upstream treatment preparation.

These are bounded controlled studies with different protocols and denominators. They do not establish customer ROI, universal error prevention, or the complete autonomous learning loop. See the study catalog.

Use the Python client

Run the same lifecycle in-process or over HTTP:

from proofpress import ProofpressClient, ProofpressError

client = ProofpressClient.in_process(".")
evidence = client.import_evidence("run.otlp.json", idempotency_key="run-001")
candidate = client.propose_claim(
    "The bounded result is ready for review.",
    evidence["evidence"],
    scope="experiment:demo",
    proposer="agent:runner",
    idempotency_key="proposal-001",
)

# A human authorizer reviews through the owner surface. A successor agent reads:
context = client.context(scope="experiment:demo", actor="agent:successor")

Other MCP clients and advanced local use

Use Remote MCP for client-specific plugin/skill installation and OAuth. For a real localhost workspace, follow the local guide; for the synthetic Git-backed demo, use its generated proofpress-mcp.json. These are separate storage backends.

Choose a deployment

• One local repository: use the in-process client or localhost HTTP for a Git-backed ledger, local review, and governed-context reads.
• One private workspace across people, devices, and agents: use proofpress hosted for durable storage, distinct human Reviewer credentials, scoped agent credentials, review, and HTTP/MCP access.
• Workflow-specific evidence: use a profile or integration for typed validation without changing the authority model.
• Owner UI preview: run npm run preview:local from web/owner; it reuses one ignored, mode-0600 local credential and synthetic workspace.
• Hosted boundary: the reference deployment is private and single-instance, not a multi-tenant Proofpress cloud. See Self-hosting.

Self-host in three steps

1. Deploy this repository with render.yaml, or use the provider-neutral examples in deploy/self-hosted/.

2. In a private server shell, bootstrap one owner workspace:

   proofpress hosted --database /var/data/proofpress.db \
     bootstrap --workspace-id workspace:personal \
     --owner-principal human:owner

3. Store the one-time owner credential and recovery secret outside Git, then issue a distinct credential for each human Reviewer and agent or device. Configure backups before relying on the instance.

• The Blueprint contains no Proofpress credentials or customer data.
• A fork uses the operator's own account, storage, domain, and billing.

• Submitting evidence or proposing a claim never admits it.
• Agent credentials identify and constrain callers; they do not carry owner authority.
• Governed-context reads return only admitted, current, in-scope, actor-eligible claims.

Integrations and deployment

• proofpress.profiles.experiment validates bounded metric, table-cell, and derivation evidence.
• proofpress.integrations.repository binds one repository change to Git and check receipts for self-dogfood.
• proofpress.integrations.matter_catalog and proofpress.integrations.document_extraction are optional evidence-entry integrations. Their output remains candidate evidence.
• proofpress hosted runs the private hosted control plane and web review surface. See Self-hosting.
• AFF is the separate Apache-2.0 format and CLI for portable agent Findings. Its collaborator trial works with a Git collection; Proofpress is an optional open-source governance runtime for authenticated review and reuse.
• Proofpress's OAFF v0.1 integration can export bounded claims and receive foreign candidate packages without granting receiver-local authority.

Read this next

• Work on the repository: repository structure and ownership.
• Understand the product: Thesis → claims and governed context → FAQ.
• Connect an agent: trace integration → content-addressed receipt adapter → external experiment evidence → Baseten training evidence → spreadsheet cell evidence → MCP and WebMCP → repository dogfood.
• Run it privately: self-hosting guide → render.yaml → deployment examples.
• Explore prior experiments: study catalog. Research evidence is separately scoped; it is not a blanket product-efficacy claim.

• Python-first and one private workspace per deployment today.
• Human Reviewers may inspect and decide claims. Credential and policy administration stays with the bootstrap Owner; invitations and customer VPC packaging are not available.
• No Notion or multi-repository knowledge ingestion.
• Not a universal OCR, RAG, memory, or search platform.

Compatibility

Python is the supported SDK and CLI installation path. Older Python imports, console aliases, and portable top-level commands remain deprecated forwarding shims; new integrations should use ProofpressClient, proofpress, and proofpress legacy ... for the portable artifact ledger. Browser tooling builds the Owner workspace. The public website is maintained separately in continuara-lab/proofpress-website; this product repository does not deploy proofpress.dev.

See the documentation index, study catalog, and GitHub Releases.