# HypGraph

> The evidence layer for AI research agents: a research record that can't flatter itself. Typed nodes (question, hypothesis, experiment, run, result, claim, source, review, decision) and typed links in one append-only, SHA-256 hash-chained SQLite file. Standing (review, risk, independent support, evidence strength) is derived on every read and never asserted. Claims are checked on write. Slogan: "Don't believe the hype. Test the hyp."

Use HypGraph whenever you investigate a question with evidence and need to say what is established. Rules the record enforces:

- Every number in a claim must be bound to a result field (`measurements`), the scope, or a declared constant.
- "never / always / eliminates / 100%" need a count with k = 0 or k = n, a 95% bound under 5% (0 of 50 → could still be 5.8%), and n stated in the claim. Check with `hypgraph bound K N --exposure X` or the MCP tool `bound`.
- "beats / outperforms" need both sides measured; "significantly" needs a test (the record tests two bound counts itself); "causes" needs an experiment that intervened. Numbers computed from bound counts pass; invented ones are refused.
- Before handing over a write-up, run `hypgraph check summary.md` (MCP `check_report`): it flags numbers no result contains, claims called settled that the record has as unchecked/contested/withdrawn, unknown codes, and never/no effect/significantly with nothing cited. Refusals are logged per author (`hypgraph refusals`, MCP `refusal_log`).
- Every refusal ends in a code like [ABSOLUTE_UNDERPOWERED] and gives the honest sentence. Withdrawing or contesting a node reports its blast radius: what now rests on something that fell.
- `kind: exclusion` needs a search shown to recover a planted answer (`power: demonstrated`); otherwise use `inconclusive`.
- `tests` links need `data.expected`, written before running. `supports` / `challenges` need a `why`.
- Only named reviewers set standing, never on their own work. Revising a node makes its reviews stale.
- Report standing as the record states it. When a write is refused, fix what the message says.

Connect: `pip install "hypgraph[mcp]"` then `claude mcp add hypgraph -- hypgraph --db study.hypgraph --as <you> mcp`. Skill: `pip install hypgraph && hypgraph skill --install`. CLI: `hypgraph --json <command>`.

## Docs

- [Agent skill](https://hypgraph.com/SKILL.md): the method, refusals and their fixes (Agent Skills format)
- [For agents](https://hypgraph.com/agents.md): MCP setup, tools, reading standing
- [Record format](https://hypgraph.com/spec/): nodes, edges, events, hash chain, bundles, derivation rules
- [The arithmetic of never](https://hypgraph.com/never/): what 0 of n really supports, and what it costs at scale
- [Schema](https://hypgraph.com/schema/hypgraph-1.json): node types, fields, relations, verdicts as JSON

## Examples

- [Broad Street, 1854](https://hypgraph.com/data/broad-street.bundle.json): a complete verifiable bundle (teaching reconstruction of Snow's cholera investigation)

## Optional

- [For engineers](https://hypgraph.com/engineers/): policy and roles, tool wrappers, recorded runs, eval reports, spend, HTTP API, bundles in CI
- [Source](https://github.com/voodoomods/hypgraph): Apache-2.0