Hypergraph

A protocol for keeping research projects legible to fresh agents. Hypergraph maintains two graphs per project on top of a graph store (v0.0.1: Flywheel):

• Record graph — the append-only log of everything that happened: decisions, experiments, evidence, dead ends. Optimized for audit, not orientation.
• State graph — a small, single-writer, distilled projection of what is true now: architecture, what works, what's broken or open (the frontier), and accumulated negative knowledge. Every state node cites the record nodes it derives from — that many-to-one cross-graph provenance is the "hypergraph".

The problem it solves: on a mature project, cold-start orientation over an append-only DAG means traversing thousands of nodes. With Hypergraph, a fresh agent reads the frontier in ≤ ~6 tool calls and follows provenance slugs into the record graph only where the task demands history.

How it stays coherent with many parallel agents: knowledge lands record-first — every record node declares its ## State Impact (or none: <reason>), and a separate single-writer reconcile pass folds declared impacts into the state graph behind an append-only high-water mark. Nobody edits state inline. Forward work follows the same rule: new directions (including Operator directives) enter as decision record nodes whose impacts open Status: open state nodes — the frontier carries intent as claims about gaps, never as task lists.

v0.0.1 = protocol + skills + checker

Deliberately not a package. Flywheel (MCP) is the load-bearing graph store; the protocol is written against a thin abstract backend interface so an open, git-native backend can be a drop-in second adapter later.

• SPEC.md — the protocol: invariants I1–I8 + conventions.
• skills/ — four Claude skills: hypergraph-init, hypergraph-record, hypergraph-reconcile, hypergraph-orient.
• tools/hypergraph.py — single-file uv script: check validates the mechanical invariants over JSON graph exports (CI-ready, nonzero exit on violations); render generates STATE.md (frontier first, architecture tree below); viz emits a self-contained interactive HTML visualization — record view, state view, and the combined hypergraph view with cross-graph provenance/impact links (zero JS dependencies, no network; opens straight from file://).
• templates/ — the exact markdown shapes the checker parses.

Quickstart

./install.sh                       # symlink the skills into ~/.claude/skills

# in a Claude session inside your project repo (Flywheel MCP connected):
#   run hypergraph-init            → roots + state skeleton + .hypergraph/config.yml + STATE.md
#   ... do work; run hypergraph-record after each unit of work
#   run hypergraph-reconcile       → fold impacts into state, regenerate STATE.md
#   (fresh session) hypergraph-orient → frontier brief in ≤ ~6 tool calls

Checker/renderer/visualizer, standalone:

uv run tools/hypergraph.py check  --record .hypergraph/cache/record.json --state .hypergraph/cache/state.json
uv run tools/hypergraph.py render --state .hypergraph/cache/state.json --config .hypergraph/config.yml -o STATE.md
uv run tools/hypergraph.py viz    --record .hypergraph/cache/record.json --state .hypergraph/cache/state.json \
                                  --config .hypergraph/config.yml -o .hypergraph/viz.html
open .hypergraph/viz.html          # interactive: pan/zoom, click nodes, search; SVG/PDF export
uv run pytest tests/               # checker + viz test suite over committed fixtures

The viz page is one unified view driven by a Display section in the sidebar: graph visibility (record / state / both), node style (cards / circles), layout (layered / force — independent of node style), and per-species edge toggles (parent edges, impact links, provenance links, hyperedge blobs — each state node's contributing record set drawn as a convex-hull blob; deterministic layout, no randomness). Preset chips — Record, State, Columns (record log and state projection side by side with cross-graph links), Force (force-directed circles with blobs) — reproduce the classic arrangements, and any custom mix in between is fair game. The sidebar is resizable (drag the divider) and collapsible (click it); exports live in the header's download menu. Deep links still work: viz.html#record, #state, #combo, #hyper, or #<any-slug> to jump straight to a node.

Repo map

SPEC.md                     the protocol (invariants + conventions)
backend/INTERFACE.md        ~10 abstract backend operations
backend/flywheel-adapter.md op → Flywheel MCP call recipes
skills/hypergraph-*/        the four skills (install.sh symlinks these)
templates/                  record-node / state-node / config shapes
tools/hypergraph.py         checker + STATE.md renderer + interactive visualizer (uv script)
tools/fixtures/             checker test fixtures (clean + per-invariant violations)
tests/                      pytest suites (checker + viz)

This repo dogfoods itself: see .hypergraph/config.yml and STATE.md.