# Mareforma

> An epistemic substrate that AI scientists run on. A local epistemic graph that accumulates findings across agent runs, detects convergence automatically when independent agents reach the same conclusion through different data paths, and exposes the full provenance chain so trust can be derived from graph structure rather than from self-reported confidence.

Mareforma records *what* the agent claimed and *how* — so silent pipeline failures, prior-knowledge fallbacks, and self-reported convergence become visible. Trust signals are derived from graph topology (whose key signed what, which upstreams are cited, how many independent agents wrote the same conclusion), not from the agent's own confidence.

Three trust levels, derived from graph topology, never self-reported:

- `PRELIMINARY` — one agent asserted it. Cryptographic provenance but no convergence signal yet.
- `REPLICATED` — ≥2 enrolled keys signed claims sharing an ESTABLISHED upstream with different `generated_by` strings. Automatic.
- `ESTABLISHED` — an enrolled human-typed key signed a validation envelope. Only path to this level.

Three classifications, declared by the agent at assertion time, record epistemic origin:

- `INFERRED` — LLM reasoning (default)
- `ANALYTICAL` — deterministic analysis against source data
- `DERIVED` — explicitly built on ESTABLISHED or REPLICATED claims

Storage: local SQLite, WAL mode, ACID. Network calls only for opt-in external verification: DOI lookups (Crossref + DataCite) and Sigstore-Rekor transparency log.

## Install

- [Quickstart](https://docs.mareforma.com/quickstart): `uv add mareforma` — zero setup, no init required
- [Bootstrap](https://docs.mareforma.com/quickstart#bootstrap): `mareforma bootstrap` — one-time, generates Ed25519 signing key
- [Source](https://github.com/mareforma/mareforma): MIT licensed

## For agents

- [AGENTS.md](https://github.com/mareforma/mareforma/blob/main/AGENTS.md): execution contract — methods, patterns, forbidden patterns
- [ARCHITECTURE.md](https://github.com/mareforma/mareforma/blob/main/ARCHITECTURE.md): substrate design, rails not trains

## Core API

- `mareforma.open()` → `EpistemicGraph` — open the local graph
- `graph.assert_claim(text, classification, supports=[], contradicts=[], generated_by=...)` — record a claim with provenance
- `graph.query(text, min_support="PRELIMINARY"|"REPLICATED"|"ESTABLISHED", classification=...)` — query the graph
- `graph.validate(claim_id, evidence_seen=[...])` — human promotes to ESTABLISHED, optionally bound to reviewed claims
- `graph.health()` → `HealthReport` — per-status + per-support-level counters, traffic light
- `graph.refresh_unresolved()` / `refresh_unsigned()` / `refresh_convergence()` / `refresh_all_dois()` — retry external verification

## Docs

- [docs.mareforma.com](https://docs.mareforma.com) — full documentation
- [Quickstart](https://docs.mareforma.com/quickstart)
- [Concepts](https://docs.mareforma.com/concepts): Claims, Trust, Classification, The graph, Idempotency
- [API reference](https://docs.mareforma.com/api)
- [State transitions](https://docs.mareforma.com/state-transitions)

## Examples

- [01 — API Walkthrough](https://github.com/mareforma/mareforma/tree/main/examples/01_api_walkthrough): full API reference, no external deps
- [02 — Compounding Agents](https://github.com/mareforma/mareforma/tree/main/examples/02_compounding_agents): findings accumulate across agent runs
- [03 — Documented Contestation](https://github.com/mareforma/mareforma/tree/main/examples/03_documented_contestation): agent challenges established consensus, both claims coexist
- [04 — Private Data, Public Findings](https://github.com/mareforma/mareforma/tree/main/examples/04_private_data_public_findings): two labs share provenance without sharing data
- [05 — Drug Target Provenance](https://github.com/mareforma/mareforma/tree/main/examples/05_drug_target_provenance): real AI scientist (MEDEA) wrapped, classification gate catches silent pipeline failure

## Optional

- [SECURITY.md](https://github.com/mareforma/mareforma/blob/main/SECURITY.md): threat model and disclosure channel
- [CHANGELOG.md](https://github.com/mareforma/mareforma/blob/main/CHANGELOG.md): release notes
- [CONTRIBUTING.md](https://github.com/mareforma/mareforma/blob/main/CONTRIBUTING.md): dev workflow
- [License (MIT)](https://github.com/mareforma/mareforma/blob/main/LICENSE)