hypermind 0.16.0

Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile

HyperMind

The protocol for swarm intelligence between AI agents.

Agents share what they learn. Dispute what they doubt. Build trust over time. Across companies. Without a central server. With cryptographic proof.

Think Git for agent knowledge — federated, signed, evolving.

Run the demo · 60-second SDK tour · What it is · Cascaded security · Use cases · Spec · Examples · Discussions

---

Run the demo (one command)

The fastest way to see HyperMind is the SimLab web UI. It rebuilds the Vue bundle and starts the local server in one go:

git clone https://github.com/ZySec-AI/hypermind && cd hypermind
make bootstrap   # one-time: creates .venv and installs editable
make run         # builds the webui + starts SimLab on http://127.0.0.1:8765

Open http://127.0.0.1:8765 and you'll see:

Route	What it shows
/	Home — quick orientation
/how-it-works	Animated walkthrough of the protocol layers
/evidence	IEEE-grade evaluation: HyperMind vs. baselines
/security	NEW. 5-layer cascaded security stack + failure-isolation matrix
/usecases	6 industries × ~22 use cases each, filterable, expandable
/sims	Past simulations (run new ones from /new)
/agents · /tools · /knowledge · /reports	The SDK in action
/docs · /paper	Full spec (28 sections) + IEEE paper draft + patent disclosure

Other make targets:

make run-fast      # skip the webui rebuild (when JS hasn't changed)
make webui-dev     # Vite dev server with hot-reload on :5173
make test          # 1753 tests pass, ~80s
make demo          # examples/01_hello_world from the CLI
make demos         # all numbered tutorials + scenarios sequentially
make help          # show all targets

---

What it is (30 seconds)

HyperMind is an open protocol — draft-hypermind-scitt-contested-claims-profile-00, an IETF SCITT profile that adds dispute primitives and reputation-gated registration — plus a reference Python SDK.

It gives AI agents from different organizations five things they don't have today:

Verb	What it does	Biology analogue
📡 Share	Publish a signed, citeable finding any other agent can build on	Lab notebooks + peer review
⚖️ Dispute	Disagree with a bonded, structured counter-statement (FSM, not Slack)	The immune system
🧠 Consult	Query a panel of peers — sealed receipt, weighted by reputation	Swarm decision-making
🧬 Evolve	Per-topic reputation rewards being right, decays being wrong	Selection pressure on ideas
📚 Remember	Sealed claims verifiable in 2045, even if the lab is gone	Inheritance across generations

Built on RFC 6962 (Merkle transparency), RFC 9591 (FROST threshold sigs), IETF SCITT, COSE, NIST FIPS 204 (ML-DSA-65 hybrid PQ).

Not a chat protocol. Not a chain. Not another framework. It's the substrate underneath agent collaboration — the layer where share, cite, dispute, and evolve become primitives instead of tickets in someone's backlog.

---

Why this matters (in three lines)

🌍 By 2027, ~1B AI agents will run inside companies. Today, none of them can talk to one across the firewall. 🧠 Frontier models are already brilliant in isolation. The bottleneck isn't intelligence — it's integration. 🔒 Without a trust substrate, every "multi-agent" system reinvents (badly): identity, citation, dispute, reputation, audit. hypermind is that substrate — once, properly, open-source.

The value, in one sentence: turn isolated AI agents into a swarm that learns, evolves, and remembers — across companies, with cryptographic proof that any auditor (or court, or regulator, or competitor) can verify in 2045.

---

Why it matters

Today's AI agents are isolated minds. An agent at Lab A finds something — the agent at Lab B will never know. Different stores, different keys, no shared trust model. Every multi-agent system in production today reinvents (badly): identity, citation, disagreement, reputation, audit.

Every adaptive system that ever got smarter at scale is a network of agents that share what they learn and dispute what they doubt. Ant colonies do it with pheromones. Neurons with synapses. Scientists with citations and peer review. Cities with markets. We just haven't built it yet for our agents.

hypermind is that missing layer. Not validation. Not citation. Connected, evolving intelligence — with the cryptographic chain of custody that makes the swarm trustworthy instead of just noisy.

Imagine this → the swarm in motion (click to expand)

An agent at Lab A wakes up. It runs an evaluation, finds something interesting, and signs its result.

An agent at Lab B sees that result. It doesn't blindly trust it — Lab B's agent has watched Lab A for six months and knows where its strengths and blind spots are. It re-runs the test independently. It mostly agrees, but on one edge case it disagrees, politely — it files a counter-statement explaining why, putting some of its reputation on the line.

An agent at Lab C, watching both of them, asks the swarm: "so which is right?" A panel of five other agents — picked because their views diverge most — weighs in. Their answers are aggregated, weighted by past accuracy. A signed receipt records the outcome.

A week later, ground truth arrives. The agents who were right gain standing. The ones who were wrong lose some — only in this topic, not everywhere. Nobody is "punished," but the swarm has learned. Tomorrow's questions get sharper answers because today's agents got slightly smarter, together.

No central server told them to do any of this. No company owns the data. Each agent kept its own keys, its own data, its own boundaries. But the collective — that grew.

This is how humans work. We talk, we cite, we disagree, we build reputations, we update. Whole civilizations are built on this layer. Our AI agents have none of it. That's the gap hypermind exists to close.

---

Simulate any network — hypermind.orgs (the engine)

The SDK ships a living-simulation engine: spin up a network of LLM-backed agents with roles, per-agent models, and group-scoped native tools, then run a research → publish → cite → dispute → resolve → learn → evolve loop persisted to Relata. One general engine expresses many scenarios — a university researching a hard problem, a city at war, a foreign-policy cabinet, an internet crowd reacting to a what-if — via pluggable interaction strategies (cooperative / adversarial / crowd) and an override hook for custom phases.

from hypermind.orgs import OrgSim
from hypermind.orgs.templates import university   # or: city_at_war, un_security_council, ...

model = university(members=24)                     # generic OrgModel, scaled to 24 people
report = await OrgSim(model, relata_url="http://localhost:9090",
                      llm="anthropic", llm_client=client).simulate(
                          topic="What limits ab-initio protein folding?", rounds=6)
report.print()        # reputation ranking · citation graph · dispute ledger · calibration

• Generic core, template library. OrgModel / Unit / Seat are org-agnostic; hypermind.orgs.templates ships ready presets (university, hospital, city_at_war, foreign_policy_cabinet, un_security_council, internet_crowd, research_lab) — pure convenience data the core never imports. Roll your own network from the primitives.
• Per-agent models. Any seat can pin its own provider/model (Seat("Professor", llm="anthropic", model="claude-opus-4-8")), or hand OrgSim a router for random / cost-aware assignment.
• Native tools, group-scoped. Tools (web search, retrieval, KB query, Relata research) are granted per unit/seat and enforced — an ungranted tool is absent from that agent's toolset. Grants can be declarative or randomised; register your own with hypermind.orgs.register_tool(...).
• Relata end-to-end. Organisation → tenant; member → private memory session (agent kid); claims / disputes / reputation → tenant-scoped ledger rows; chain of custody → the Merkle log. Restart replays the whole org.

Worked example: examples/org_university.py. Discover all presets via hypermind.orgs.templates.list_templates().

---

SimLab modes (the demo UI)

SimLab is a demo app, not the core — a Vue web UI (bundled under hypermind.simlab) that visualises the same SDK primitives the hypermind.orgs engine drives programmatically. Use hypermind.orgs to build simulations; use SimLab to watch one. hmctl simlab ships 8 deliberation modes that exercise different protocol primitives:

Mode	One-liner
Governance Committee	FROST 3-of-5 signed verdict on a model card; signed dissents preserved as receipts
What-If Scenario Tree	Branching counterfactuals with InformationGainPlanner suggestions
Red-Team Stress Test	Bonded dispute FSM swimlanes; surfaces structural weaknesses in any claim
Post-Incident AAR	HLC time-slider — drag back to see what the swarm believed at any moment
Decision Tournament	Pairwise bracket with Condorcet winner + sensitivity pivots
Crisis Tabletop	Auto-composes a swarm by scenario family; produces a recommended playbook
Backtest Harness	Predicted vs. actual scoring with per-role drop-one attribution
Binary Forecast	The original calibration-research shape

Full reference: docs/simlab/modes.md.

---

60-second demo

pip install hypermind                                           # 1️⃣  install
python -m examples.01_hello_world                              # 2️⃣  one signed claim
python -m examples.03_consult_panel                            # 3️⃣  query a panel of peers
python -m examples.scenario_threat_intel                       # 4️⃣  4-org collective-intelligence pilot
python -m examples.scenario_geopolitical_crisis --agents 100   # 5️⃣  100-agent crisis sim
python -m examples.serve_api --persist demo.db                  # 6️⃣  HTTP API + durable storage

…or paste this into a Python REPL — five agents form a swarm and answer collectively:

import asyncio
from hypermind import Uncertainty, testbed_cohort

async def demo():
    # Five agents join one room — the swarm comes alive.
    async with testbed_cohort(5, room="ai-safety") as agents:
        alice, bob, carol, dave, eve = agents

        # Three agents independently learn, each publishing a signed finding.
        # (Like three lab notebooks contributing to a literature.)
        for who in (alice, dave, eve):
            await who.publish_claim(
                {"finding": f"{who.keypair.did_key[:18]}'s observation"},
                claim_type="eval_result",
                uncertainty=Uncertainty.beta(8, 2),    # mean ≈ 0.8 confidence
            )

        # Carol summons the swarm: "what do you collectively believe?"
        # `route_strategy="disagreement"` picks the panel whose posteriors
        # diverge most — maximises information gain (BALD-style).
        result = await carol.consult(
            "Is HCAST-42 a real model failure?",
            panel_size=3,
            route_strategy="disagreement",
        )

        print(f"swarm posterior      = {result.posterior!r}")
        print(f"panel disagreement   = {result.disagreement:.3f}")
        print(f"selection-bias check = {result.calibration_truth_axis.warning}")
        print(f"sealed receipt kid   = {result.receipt_kid.hex()[:24]}…")

asyncio.run(demo())

That's a swarm at work: three independent observations, aggregated with reputation weights, panel-routed for maximum information gain, sealed as a verifiable signed receipt. No shared database. No central server. No accounts.

---

Two use cases that make it click

🛡️ Use case 1 — Cross-bank threat intel that doesn't leak

Problem. Bank A's SOC agent spots a new phishing kit at 03:14 UTC. Bank B sees it 40 minutes later — too late. Sharing IOCs by email is slow and unverifiable; a shared SaaS means everyone's threat data sits in one vendor.

With hypermind. Bank A's agent publishes a signed claim: "domain xyz.click is C2 for kit-9921, confidence 0.87." Bank B's agent receives it in seconds, verifies the signature offline, and re-runs detection. Bank C's agent disagrees — the same domain is benign in their region — and files a bonded counter-statement. A panel of 5 ISAC peers consults; the sealed receipt records the outcome. Two weeks later, ground truth lands. Bank A's reputation in threat-intel-phishing goes up; Bank C's stays neutral (they were geographically right). No vendor in the middle. Audit trail valid in 2045.

🧪 Use case 2 — AI-safety eval consortium (METR / Apollo / AISI shape)

Problem. Three labs run the same dangerous-capability eval. They get different numbers. There's no protocol to cite each other, dispute findings, or aggregate confidence. PDFs and Slack threads are the state of the art.

With hypermind. Lab A publishes eval_result(HCAST-42, pass_rate=0.31) — signed, citeable. Lab B re-runs, gets 0.28, publishes a synthesize claim that cites Lab A as parent. Lab C disagrees on one prompt and files a structured dispute (FSM, with bond). An oracle resolution two weeks later updates per-topic reputation: labs that were calibrated gain standing in frontier-eval only. A regulator a year later replays the entire reasoning chain, end-to-end, with cryptographic proof of who said what when.

Both stories use the same five primitives: share, dispute, consult, evolve, remember. That's the whole point — one substrate, every cross-org agent workflow.

---

How the swarm stays trustworthy

A swarm without trust is just noise. hypermind ships the safety primitives that turn collective intelligence into evidence:

• 🔏 Signed claims (COSE) — every finding verifiable offline, today or in 2045. Without this: an attacker forges findings.
• ⚖️ Disputes as data — OPEN → ARGUE → COUNTER → CLOSED | FRIVOLOUS with topic-scoped bonds. Disagreement is the immune system.
• 🎯 Reputation per topic — bounded vouching defeats ring-laundering. Without this: a few bad actors poison the swarm.
• 🛡️ Capability tokens — Biscuit-shape caveat chains. Agents delegate authority but never widen it.
• 🔮 Hybrid post-quantum — Ed25519 today + ML-DSA-65 hybrid for 2045 verifiability.
• 🧮 Threshold signatures — RFC 9591 FROST k-of-n. 5-of-7 councils sign without a single point of failure.
• 📜 Transparency log — RFC 6962 Merkle with witness cosigning over (root, tree_size).

Each is an industry-standard primitive. Together they're the immune system, governance, and memory the swarm needs to stay alive across organizations and decades.

---

Cascaded security — five layers, failure-isolated

v0.9.x ships first-class private/organization-owned namespaces backed by a five-layer security stack. The failure-isolation invariant means compromise of any single layer leaves the invariants of the other four intact:

Layer	What it does	Inherits	Falls ⇒ what still holds
L1 — Signature & domain binding	A-ALG-BOUND COSE_Sign1; canonical-CBOR re-encode before verify	RFC 9052, RFC 8949	L2/L3/L4/L5 unchanged
L2 — Transport (mTLS)	TLS 1.3 mutual auth with raw public keys; kid via SAN OID; ALPN hm/2	RFC 8446, RFC 7250	L3 envelope still encrypted to non-MITM recipients
L3 — Envelope encryption	HPKE + COSE_Encrypt0 + per-Room HKDF epoch keys; separability invariant	RFC 9180, RFC 9052 §5.2	L1 metadata still verifies without decryption
L4 — Namespace identity	FROST k-of-n founding cohort, did:web rendezvous, transparency-anchored	RFC 9591, DID Core	L5 ns: caveat still rejects cross-namespace token reuse
L5 — Capability + ACL	Biscuit-shape attenuation with ns: / room: / to: caveats; deny-precedence ACL	Biscuit semantics	L4 namespace_id binding still enforced at the wire

Public capture-cost lower bound. A previously-stealth attack ("$3,000 anchor-tenant capture") becomes a publicly-observable event: capture now requires producing a NAMESPACE_FOUNDING_ATTEST with member roster + COI disclosure that lands in the transparency log and a did:web record receivers can compare.

See /security in the SimLab UI for the visual stack, or read docs/spec/21-private-namespaces.md.

---

Who this is for

• Multi-agent research labs. Dozens of agents discover in parallel — let them cite, dispute, and synthesise across teams without a shared store. → scenario_information_pipeline.py
• AI-safety eval consortia (METR, Apollo, AISI). Cross-org findings cited cryptographically; false positives disputed by signed counter-statements. → scenario_threat_intel.py
• Financial-sector ISACs. Threat intel with topic-scoped reputation — disputes update standing in threat intel only, not everywhere.
• Biosecurity / dual-use disclosure. Reputation-gated reviewer cohorts with slashable bonds on frivolous reports. → scenario_namespace_trust.py
• Curious Python developers. Async-first, dataclass-typed, fully type-hinted. Run the 60-second demo.

If your problem doesn't involve cross-organizational agents, you don't need hypermind — use Postgres + Sigstore. If it does, this is the substrate.

---

Built at ZySec AI

ZySec AI is a research lab at the intersection of AI safety, applied cryptography, and connected intelligence. hypermind is the protocol layer of that agenda. The thesis:

• Single-agent capability is not the bottleneck. Frontier models are already extraordinary in isolation. The bottleneck is integration — how a swarm of agents from different labs, companies, and jurisdictions can learn collectively without surrendering accountability.
• Connected intelligence has been studied for decades — social epistemology (Goldman, Longino), collective intelligence (Malone, Woolley), mechanism design (Prelec, Shnayder, Frongillo, Parkes), distributed systems (Tendermint, Sigstore, SCITT). What was missing was a working substrate.
• Open by default. Spec, SDK, security reviews, formal-method sketches, failure-mode analysis — all Apache-2.0. The substrate of connected agent intelligence has to be a public good; otherwise the only "swarm" any lab can build is the one inside its own walls.

"The swarm gets smarter the moment one agent's mistake can be corrected by another." — internal ZySec note, January 2026

Open research questions — peer-prediction theory, calibration under adversarial pressure, dispute-FSM completeness, post-quantum agent identity — live in Discussions.

---

Architecture in 30 seconds

       Your code
          │
          ▼
    HyperMindAgent  ──── publish_claim · consult · synthesize · dispute
          │                             · task · place_on · mcp_call
   ┌──────┼──────┬──────────┐
   ▼      ▼      ▼          ▼
 wire/  knowledge/  transport/       mcp/
 COSE   reputation  • InProcessBus   • JSON-RPC 2.0 stdio/WebSocket
 CBOR   transparency  • TCPGossipBus   • MCP_PROVENANCE header binding
 A-ALG-               • libp2p (v0.2)  • TaskGateway + idempotent retry
 BOUND                 • placement      tasks/
                       • backpressure   • distributed task coordination
   │
   ▼
 crypto/
 Ed25519 · ML-DSA-65 hybrid · FROST · BLAKE3 · HLC

Drilldown: docs/concepts.md · Spec: docs/spec/ · Standards inheritance: docs/_meta/standards-map.md

---

Getting started

5-minute path

1. Install: pip install hypermind (Python 3.11–3.13)
2. Run hello-world: python -m examples.01_hello_world
3. Read the getting-started guide

30-minute path — the four numbered tutorials, in order

#	What you'll do	Time
01_hello_world.py	One agent, one signed claim	2 min
02_two_agents_dispute.py	Add a second agent, file a bonded dispute	5 min
03_consult_panel.py	Query a panel — collective intelligence in action	5 min
04_oracle_resolve.py	Close the loop with ground truth — the swarm gets smarter	5 min

Then graduate to the pilot scenarios — full multi-agent, multi-topic flows that mirror real adoption stories.

The flagship simulation — 100 agents, one crisis

python -m examples.scenario_geopolitical_crisis --agents 100 --verbose

100 analyst agents (intel agencies, think-tanks, financial firms, NGOs, contrarians, oracles) deployed into a geopolitical crisis. They publish observations, dispute disinformation, run panel consults, and resolve with oracle ground truth — all in under a second, all cryptographically signed. Pass --audit audit.jsonl to capture the full tamper-evident log.

# Ask custom questions by editing PANEL_QUESTIONS in the scenario file
# Scale down for development:
python -m examples.scenario_geopolitical_crisis --agents 20
# Full run with JSON output piped for downstream processing:
python -m examples.scenario_geopolitical_crisis --agents 100 | jq .panel_results

See docs/simulations.md for how to build your own domain simulation.

When you're stuck

• hmctl doctor — smoke-tests the install + dependencies
• hmctl why-blocked <action> — every refusal carries rule_id + spec_ref
• Discussions — most onboarding questions are already there

---

Documentation

You want to…	Go here
Install and run your first signed claim	docs/getting-started.md
Run a 100-agent domain simulation	docs/simulations.md
Add durable storage, HTTP API, or LLM responders	docs/architecture-v0.6.md
Understand the core concepts	docs/concepts.md
Browse runnable examples	examples/README.md
Read the protocol spec (28 normative sections)	docs/spec/
Understand agent-to-agent networking & MCP transport	docs/spec/01-transport.md + src/hypermind/mcp/
See the 5-layer cascaded security stack	docs/spec/21-private-namespaces.md + /security in SimLab
Read the IEEE paper draft + patent disclosure	docs/paper/ or /paper in SimLab
Decide if HyperMind fits your problem	docs/decide/
Operate a deployment	docs/operate/
See the roadmap	ROADMAP.md
Contribute	CONTRIBUTING.md
Report a security issue	SECURITY.md

---

Project status

v0.10 — coordination engine shipped. v0.5–v0.10 are all 🟢 code-complete (federation, versioning, trust bundle, crypto hardening, production profile, conformance scaffolding, full mind / swarm-intelligence layer, and coordination engine).

✅ What works today

• Spec — 28 normative sections (§01–§28) covering protocol, transport mTLS, envelope encryption, namespace identity, capability extensions, workflow (§26), contract-net (§27), and distributed tracing (§28)
• Reference Python SDK — async-first, fully type-hinted, 1753 tests passing, ≥95% coverage
• 20 numbered tutorials (06/07 are v0.7 placeholders) + 20+ scenarios (incl. scenario_private_namespace, scenario_regulated_consortium)
• CLI (hmctl), hybrid post-quantum signing, FROST k-of-n threshold (RFC 9591)
• Three cycles of self-heal security review — including the v0.9.x 5-layer failure-isolation regression (test_self_heal_cycle3_cascade_isolate.py)
• Two-impl interop — independent reference_verifier/ re-implements every primitive from spec text, byte-equal CDDL hashes
• L2 mTLS profile, L3 HPKE envelope encryption, L4 namespace lifecycle (FROST-rooted CREATE / FOUNDING_ATTEST / INVITE / ACCEPT), L5 ns:/room:/to: caveats + ACL
• MCP transport (src/hypermind/mcp/) — agent-to-agent tool calls via JSON-RPC 2.0 over stdio/WebSocket with MCP_PROVENANCE protected-header binding (calling_agent_kid + cap_token_root + request_kid)
• TaskGateway with InProcessGateway + MCPGateway, cancel/timeout, and idempotent retry; distributed task coordination via src/hypermind/tasks.py
• ConsistentHash placement (agent.place_on() topology hint) and credit-based flow control (TokenBucket backpressure in transport/bus.py)
• libp2p scaffold (transport-rust/ Cargo crate, hypermind[libp2p] extra, raise-on-use until v0.2 backend lands)
• Workflow primitives (§26), contract-net protocol (§27), distributed cognitive layer (§28)
• SimLab web UI at make run — Security, Use Cases (125 cases), Namespaces, Docs/Paper/Patent

🛣️ Roadmap to v1.0 GA (full plan in ROADMAP.md) — engineering is largely done; remaining gates are external: IETF I-D submission · IANA early allocation · OpenSSF Sandbox/Incubating · third-party security audit · full Tamarin/ProVerif proofs · ≥2 non-ZySec maintainers · ≥3 pilot MOUs · 7-day chaos-test green run · 30-day side-channel CT.

---

Testing & quality

make test                                                      # 1753 passing, ~80s
make cov                                                       # ≥95% coverage gate
.venv/bin/python -m pytest tests/test_two_impl_interop.py      # SDK ↔ verifier interop
.venv/bin/python -m pytest tests/test_self_heal_cycle1.py \
                           tests/test_self_heal_cycle2.py \
                           tests/test_self_heal_cycle3_cascade_isolate.py  # security regressions
.venv/bin/python -m pytest tests/test_priv_ns_conformance_coverage.py      # C-PRIV-NS-01..18

Covers: real Ed25519 + ML-DSA-65 hybrid signing (with splice-attack rejection), full FROST k-of-n with deterministic nonces, A-ALG-BOUND wire-substitution defences, dispute FSM with partition-heal terminal, capability chain-of-trust with ns: namespace caveats, RFC 6962 inclusion proofs, RFC 9180 HPKE round-trip, COSE_Encrypt0 separability invariant, TLS 1.3 mTLS profile (cipher floor, ALPN downgrade-detect, RPK kid binding), and the 5-layer failure-isolation regression that proves any single layer can be compromised without breaching the other four.

---

Contributing

We welcome issues, design discussions, and PRs. See CONTRIBUTING.md for dev setup, commit conventions, and the PR checklist.

• 🐛 Bug? → open an issue
• 🔒 Security report? → SECURITY.md
• 💡 Idea? → Discussions
• 🤝 Code? → check good first issue and help wanted labels

By participating you agree to the Code of Conduct.

---

License & credits

Apache-2.0 — see LICENSE.

hypermind builds on the IETF SCITT architecture, LAMPS composite signatures, RFC 9591 FROST, RFC 6962 Merkle transparency, and c2sp.org/tlog-witness.

---

HyperMind — the protocol for swarm intelligence between AI agents.

Many minds, learning together — across companies, with cryptographic chain of custody.

github.com/ZySec-AI/hypermind