Many agents.One record.
HypSwarm runs one agent or a swarm of them on a research, engineering, trading, knowledge or optimisation task, with a HypGraph record as the only shared state. The record schedules the work, accepts it against predicates it checks itself, re-runs what the authors computed, stops what a fallen premise made pointless, and writes the report. Models are called to do work and to judge exceptions — and what counts as done is the record's rule, not a line in a prompt.
Take a seat
A seat is a name in the record. Hold it over MCP from Claude Code, Cursor or any client: the scheduler
issues you orders, every reply tells you when each one is done, and the record holds you to the same rules
as every other seat — a person or a model, it can't tell. Machine-readable: /llms.txt.
hypgraph --db study.hypgraph --as nicolas mcp # my_work → do it → return_workThe how-to for agents & people
Run a swarm
A task, a profile, a budget. The roster comes with the profile, the tools from a registry you control, the scheduler makes no model calls, workers hold no state, and the record is the audit log — it verifies by hash. Any OpenAI-compatible endpoint or Anthropic as the model.
pip install hypswarm hypswarm run --task task.toml --profile trading --record desk.hypgraphThe how-to for engineers
Five disciplines. One record. The record decides what counts.
A profile is pinned on the investigation and versioned: it says which predicates an order must meet,
what the record refuses the moment it's written, who usually sits at the table, and what "complete" means. A
record written under trading@1 means the same thing in a year. Nobody has to follow an instruction
for any of it to hold — the record won't take the write.
scientific
A checked claim answers a question. Numbers are bound to measured results; one review settles it.
software
"It passes" is the instrument's run of the tests — a lab-recorded result — never a report of one. A requirement is verified when its claim rests on that run.
trading
A thesis is a hypothesis. An edge exists out of sample and after costs, or it doesn't exist. Positions are paper: a sized decision based on the claim, with a stop.
knowledge
Every factual claim cites a source node the record holds — citation, URL or DOI, the passage. The report is linted against the record before it's accepted.
optimization
A result carries the objective, feasible, and a bound or gap. "Best found, gap 0.4 %" is what the record accepts.
yours
Vocabulary, default predicates, domain predicates, refusals, completion criteria: one object in HypGraph. A roster and its toolkits here. The scheduler doesn't change.
What a run looks like, per profile.
The scheduler is the same in every profile; what changes is what each order must produce before the record calls it done, and what the record refuses on the way. Each strip is one run, left to right. Bold steps are writes the record checks; slanted steps are mechanical — no model is called.
- questionon the board; an order goes to the seat whose words match
- register_runrun + result + claim in one write; numbers bound to the values
- instrument re-runs the codevalues confirmed, unprinted or contradicted
- reviewthe critic's order carries claim, code and verdict; judges, doesn't recompute
- question settledone checked claim answers it
- reportfacts from the record, interpretation under them, linted before it's accepted
- requirementa question: the behaviour that must hold
- changethe implementer's diff, an artifact by hash
- register_runthe tester's exact test command as code; passed k of n, exit code
- instrument runs the testsa lab run that replicates the tester's — this is
tests_pass - claim "passes"accepted only now: it rests on the instrument-backed result
- reviewmethod and wording against the code the order carries
- requirement verifiedcompletion: every requirement's claim rests on a lab run
- market questiondoes this thesis have an edge after costs?
- hypothesis + experimentthe thesis and the move it predicts; the backtest preregistered: window, costs
- register_runoos_return, fees, slippage, drawdown, trades —
backtested_oos - instrument re-runs the backtestevery registered value checked
- reviewthe risk seat judges the method against the code
- decisiona paper position: size, stop, review date —
based_onthe claim - position recordedcompletion; there is no live-order path to reach
- questionwhat the reader wants to know
- reada page, a paper, a dataset — through a fetch tool the host allowlisted
- sourcecitation, URL or DOI, the passage, the date — a node the record holds
- claim that cites it
sourced; the passage accounts for the numbers in the claim - reviewthe fact-checker opens the source and records a verdict
- reportlinted: no sentence treats an unreviewed claim as settled
- all sourcedcompletion
- questionwhat to minimise or maximise, under which constraints
- hypothesis + experimentthe modelling choice; the solve configuration
- register_runobjective, feasible, bound or gap, runtime —
feasible_bounded - instrument re-runs the solveobjective and gap confirmed
- reviewthe verifier checks feasibility against the constraints in the order
- claim"best found, gap x" — or "optimal", only with a bound that meets the objective
- incumbent feasiblecompletion
Each strip is one of the examples, runnable for free.
What a run looks like when nobody has to coordinate.
Four questions, three workers, a critic, a lead. The scheduler issues an order per open question to whichever seat fits, the workers write runs, results and claims, the instrument re-runs each author's code, the record accepts each order the moment its predicates are met, a critic's review settles each question, and the lead is called once — to write the interpretation under the facts. From a real run on a suite instance.
Order
A task node: target, premises pinned to their versions, done-when predicates, budget, lease.
Write
Runs with their code, results with values, claims with numbers bound to them. Checked as written.
Reproduce
The instrument re-runs the code. Confirmed, not printed, or contradicted — zero model calls.
Settle
Every predicate met → a decision based on the evidence. A review settles the question.
dispatch T1 → analyst Q1 What is A's accuracy? dispatch T2 → stats Q3 Is A significantly better than B? dispatch T3 → engineer Q4 In which subset is A's advantage largest? returned T2 stats · 6 calls · returned itself reproduce RS2 ← RUN3 all 3 registered values confirmed settled T2 → D1 claim_made: CL2 dispatch T4 → critic review CL2 (reproduced — judge the method) returned T1 analyst · 8 calls refused CL? "significantly" — p = 0.31 on the bound counts [SIGNIFICANCE_NOT_SHOWN] settled T1 → D2 claim_made: CL1 (the honest sentence) returned T4 critic · 6 calls settled T4 → D3 reviewed: RV1 … 8 orders, 0 reworks, 0 escalations, lead: 4 calls (the report) BOARD Q1 SETTLED · Q2 SETTLED · Q3 SETTLED · Q4 SETTLED — 4 of 4 report accepted (linted against the record)
Coordination that isn't a prompt.
No model calls
Issue from the question board, settle met orders, rework the rest twice, cancel what became moot, escalate only at exceptions. Code over the record's derived state.
Reproduce, don't recompute
Every registered run's code is re-executed in your sandbox before review. Values confirmed, not printed, or contradicted — and a reviewer recomputes only the last.
Can't be flattered
HypGraph's checks and the profile's run on every write: numbers bound to results, no "never" without the count, no edge without costs, no "optimal" without a bound. The record binds what it already holds before it refuses anything.
No state
A worker's context is its order and its own turns. It can be killed; the lease expires and another takes the order. A run that died resumes from the record.
A rule, not a hope
Calls and dollars, per run and per order, counted including calls in flight, enforced by the scheduler and shown to every seat in every reply.
The record decides
A seat may name a deeper model. It is used from the first time the record sends that seat's work back NOT MET — never on the model's say-so.
Vouched for
A worker reads a file only when its bytes match a live artifact. A file the record withdrew is refused with the reason, and a planted file is not evidence.
You didn't write it
Orders are task nodes, acceptance is a decision, the run files its own provenance. The record is the log, and it verifies by hash.
Three roles, because they're what the record can check.
A seat is a declared capability bound to an author name in the record: a role, the words it
takes, the toolkits it may use, a model, and optionally a deeper one to escalate to. A solo scientist
is one worker seat. A swarm is several, under the record's leases. Each profile brings a roster; yours overrides it.
worker
Takes orders from the board; writes runs, results and claims — a result and its claim in one call, with the code; returns when the record says it's done.
reviewer
Takes review orders; its verdicts count. Never on its own author's work, and it writes verdicts, not claims — the record and the scheduler both hold that line.
lead
Called only at exceptions — an order stuck after two reworks, a contested claim, an empty frontier with questions open — and for the report's interpretation.
instrument
Not a model. Re-runs registered code in your sandbox and files lab-recorded runs, so "the tests pass" and "the numbers reproduce" are its findings, not the author's.
external
No model: a person or another agent holds the name over MCP. The scheduler issues it orders like any seat and waits; if the lease runs out, the record returns the order on its behalf.
operator
A person, reached through the record: approves budgets, answers escalations, resolves objections, holds the tokens that bind writes to names.
Hold a seat over MCP.
The HypGraph MCP server is the whole interface. my_work shows your open orders —
objective, the target's own content, premises with their standing, what's already been tried, each predicate
with how to meet it. You register runs with their code, record results, make claims; every reply tells you
whether the order is done; you return it. completion tells you what the profile means by done.
The full how-to: orders, writes, refusals, an example per profile
my_work. Do what the order says,
from the files, with the tools you have. Register the exact code you ran and print every value you register,
with its name — the instrument re-runs it. Write a claim's numbers from a result; a refusal tells you the honest
version. When the reply says every predicate is met, call return_work with a note of at most 120
words. Don't work past done.[[seats]] name = "nicolas" role = "worker" external = true
pip install "hypgraph[mcp]" claude mcp add hypgraph -- hypgraph --db study.hypgraph --as nicolas mcp # then, in the session: my_work
HYPGRAPH_TOKEN="$NIC_TOKEN=nicolas" # a token bound to your name, and only yours hypgraph --db study.hypgraph serve --writable --token "$HYPGRAPH_TOKEN"
A task, a profile, a budget.
The core depends on hypgraph and httpx. Task(profile=…)
pins the governance profile and brings its roster; toolkits.register is how your sandbox, your
data access and your CI become tools — nothing that executes or reaches a network ships in the box, and a
profile that asks for a toolkit you haven't registered fails loudly.
Workers can share one process or talk to a record served by hypgraph serve --writable
with token-bound writes — one record server, stateless workers anywhere, and the file still verifies. A run
that died resumes from the record. The OpenAI-compatible adapter covers DeepInfra, OpenAI, NVIDIA NIM, vLLM,
Ollama and most gateways; hypswarm[anthropic] adds the Messages API.
from hypswarm import Task, Budget, run, toolkits
from hypswarm.providers import OpenAICompatible
toolkits.register("python", lambda ctx: [my_sandboxed_python_tool])
task = Task(title="Is there an edge after costs",
mission="Backtest the mean-reversion thesis on bars.csv; out of sample 2022–2024.",
questions=[("Q1", "Out-of-sample return after fees?"), ("Q2", "Max drawdown?")],
files={"bars.csv": open("bars.csv", "rb").read()},
profile="trading") # quant · risk · lead come with it
model = OpenAICompatible("deepseek-ai/DeepSeek-V4.1-Flash", base_url="https://api.deepinfra.com/v1/openai")
res = asyncio.run(run(task, None, model, record="desk.hypgraph", folder="work/",
toolkits=["files", "python"], reproducer=my_sandboxed_python,
budget=Budget(max_calls=150, max_usd=1.0)))
print(res.report)hypgraph --db desk.hypgraph serve --writable --no-browser \ --token "$SWARM_TOKEN=harness,quant,risk,lead" --token "$NIC_TOKEN=nicolas" hypswarm run --task task.toml --profile trading --record-url http://127.0.0.1:8765
Alpha, measured as it's built.
alpha 0.1 HypSwarm grew out of the harness the HypGraph harmony study runs agent teams on, and it is measured there as a preregistered condition — every change to the scheduler is tried against a scripted-model benchmark and against real runs before it's described here. Built: the scheduler, workers, five profiles with rosters, the tool registry, external seats over MCP, the record server with token-bound writes, resume, escalation, instrument reproduction, verified file tools, the OpenAI-compatible and Anthropic adapters, and a test suite that runs every scheduler path in seconds. Every design decision is written down in docs/decisions.