hypermind 1.9.4

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

HyperMind

The trust layer for AI-agent collaboration.

Agents share what they learn, dispute what they doubt, and build reputation over time — across organizations, without a central server, with cryptographic proof.

Quickstart · MCP tools · What it is · Docs · Examples · Discussions

---

Quickstart (30 seconds)

pip install 'hypermind[mcp]'   # Python 3.11–3.13  (blake3 + quantcrypt need cp313 wheels; 3.14 pending)
hmctl quickstart               # in-process swarm → publishes, asks the network,
                               # returns trust-scored answers. No server, no API key.

Ask the HyperMind network from your code — one object, no server:

from hypermind.integrations import HyperMindClient

hm = HyperMindClient.sandbox(swarm=3)
await hm.publish("Ed25519 public keys are 32 bytes.", topic="crypto")
ans  = await hm.ask("How big is an Ed25519 key?", topic="crypto")   # → NetworkAnswer(text, stance, confidence)
hits = await hm.retrieve("key size", min_trust=0.6)                 # → trust-scored results

Use it inside Claude Desktop / Cursor (MCP) — one command:

hmctl mcp install          # auto-wires the host (read-only by default; --write to publish)
hmctl mcp install --local  # fully offline: Ollama auto-detect + SQLite ledger, no API key

Then just talk naturally — "What does the swarm know about CRISPR off-target effects?", "Ingest my research notes into the swarm", "Export the verified corpus as a DPO dataset."

Drop into any agent framework — point an OpenAI-compatible client at the network:

hmctl serve-endpoint       # OpenAI-compatible endpoint on :8899, backed by the swarm + verified corpus

Native adapters: LangChain · CrewAI · AutoGen · LlamaIndex · OpenAI Agents → docs/integrations.md

---

MCP tools (59 tools)

Every tool below is available when you run hmctl mcp install. Read-only by default; hm_publish_claim requires --write (53 tools total in write mode).

Knowledge & retrieval

Tool	What it does
hm_retrieve	Verifiable RAG — trust-scored BM25 hybrid search over the signed ledger (Relata or lexical fallback)
hm_justify	Full evidence chain for any claim: author, confidence, dispute history, citations
hm_recall	Memory search — "what does the swarm believe about X?" with bi-temporal time-travel
hm_related	Graph traversal: find connected claims via CITES / CORROBORATES links
hm_publish_claim	Publish a signed, attributed claim to the ledger with optional ttl_days for knowledge decay (requires --write)

Ask the network

Tool	What it does
hm_ask	Reputation-weighted panel deliberation — returns one answer with provenance
hm_simulate	Counterfactual what-if: ask original vs. counterfactual-prepended, report confidence delta
hm_debate	Adversarial pro/con panel debate over a proposition for N rounds
hm_cross_check	Multi-source cross-validation: does the swarm support, refute, or is uncertain about a claim?
hm_hypothesis	Register a falsifiable hypothesis (publishes to ledger if --write, else local file)
hm_goal	Goal-directed swarm planning: decompose a goal into concrete actionable steps

Ingest, export & domain packs

Tool	What it does
hm_ingest	Ingest .md / .txt files or directories into the swarm as signed claims
hm_dataset_export	Export the verified corpus as JSONL / Parquet / HuggingFace dataset with SHA-256 digest, Merkle proofs, and --exclude-contested filter (supports --push-to-hub)
hm_stale	List claims past their TTL with effective confidence after knowledge-decay scoring

Domain packs: hypermind.domains.medical, .defense, .legal — pre-configured populations + prompts for verticals.

Research engine

Tool	What it does
hm_research_start	Kick off a deep-research OrgSim run (research → publish → cite → dispute → resolve → learn)
hm_research_status	Poll progress of a research job (status, round, findings count)
hm_research_result	Fetch findings of a finished research job (summary, top members/claims, disputes)

Swarm management & reputation

Tool	What it does
hm_agents	Query agents — no args: full roster; kid=<hex>: one agent detail; topic=<str>: topic experts
hm_reputation	Read the primary agent's earned reputation score (0..1)
hm_disputes	Count disputes by FSM state (OPEN / ARGUE / COUNTER / CLOSED / FRIVOLOUS / UNRESOLVED_PARTITION)
hm_audit	Tamper-evident audit log summary (recent claims, disputes, totals)

Persistent populations

Tool	What it does
hm_population	Manage named populations — action: list | get | create | load | checkpoint

Autonomous agent pool (v1.5)

Tool	What it does
hm_loop	Start / stop / inspect an always-on autonomous learning loop per topic — adaptive scheduling, topic clustering, automatic sub-loop spawning
hm_loop_ingest	Push current session's published claims into a running loop so they inform the next cycle
hm_pool_status	Live state of all running loop agents: role, topic, strategy, questions asked, findings published, reputation
hm_agent_memory	Read or write per-agent working memory — steer a running loop agent's question focus
hm_evolve_now	Trigger an immediate evolution tick — retire weak agents, clone strong ones, mutate one gene
hm_session_summary	Summarise this session: claim count, topics covered, loops updated

Self-directed learning

Tool	What it does
hm_next_question	Self-directed question generation: picks the highest-value open question via uncertainty, contradiction, or frontier strategy over the HypothesisBook
hm_scan_contradictions	Lexical contradiction detection (Jaccard + negation-asymmetry) across the knowledge base; optional auto_dispute=true to raise disputes automatically
hm_calibration	Per-agent Brier / ECE calibration report — shows how well each agent's stated confidence predicts outcomes, with a calibration_weight applied to future reputation updates
hm_federate	Connect to a peer namespace over TCP (connect / disconnect / pull / status); syncs claims via anti-entropy Bloom reconciliation; foreign reputation is display-only

Evaluation & org templates

Tool	What it does
hm_eval	Run the proper-score calibration suite (Brier, ECE, log-score, WoC-Δ, EIG/Q, skill score)
hm_swarm_iq	Full swarm IQ scorecard: Brier, ECE, log-score, diversity, composite IQ 0–100
hm_list_templates	List available org-simulation template names
hm_org_roster	Describe a template's structure — units, seats, concrete roster
hm_run_org	Server-free alias of hm_org_roster

Observability

Tool	What it does
hm_status	Feature-by-feature health check with stats snapshot — OK / degraded / unconfigured with fix instructions
hm_doctor	Deep connectivity + readiness probe: LLM key, Relata, SQLite, PQ signing, clock drift

Meta

Tool	What it does
hm_version	Report server version, wire version, read-only/read-write mode, registered tool list
hm_tools	List tool providers, configured MCP servers, and recommended good-to-have MCP servers

---

What it is

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

Five protocol primitives that AI agents from different organizations lack today:

Verb	What it does
📡 Share	Publish a signed, citeable finding any other agent can build on
⚖️ Dispute	Disagree with a bonded, structured counter-statement (an FSM, not a chat thread)
🧠 Consult	Query a panel of peers — sealed receipt, weighted by earned reputation
🧬 Evolve	Per-topic reputation rewards being right, decays being wrong
📚 Remember	Sealed claims verifiable in 2045, even if the lab that made them is gone

Built on COSE (RFC 9052), Merkle transparency (RFC 6962), FROST threshold sigs (RFC 9591), IETF SCITT, and hybrid post-quantum signing (Ed25519 + ML-DSA-65, FIPS 204).

Three capability layers on top of the protocol:

Layer	Package	What it gives you
Deep research engine	hypermind.orgs	PI decomposition + self-refine, 12 reasoning strategies, hypothesis lifecycle, architecture-native metrics, streaming learn-large/serve-small query, full-run replay → emits a trust-scored verified corpus
Eval suite	hypermind.eval	Proper scoring rules (Brier, ECE, EIG/Q, skill score, Murphy-Winkler decomposition), self-contained HTML reports, hmctl eval CLI
Adoption layer	hypermind.integrations	One-object facade, OpenAI-compatible endpoint, 52-tool MCP server, framework adapters (LangChain / CrewAI / AutoGen / LlamaIndex / OpenAI Agents), knowledge ingestion, fine-tuning dataset export, autonomous agent pool (hm_loop, hm_pool_status, hm_agent_memory, hm_evolve_now) + learning engine (hm_next_question, hm_scan_contradictions, hm_calibration, hm_federate), domain packs

The learn-large / serve-small loop: feed a small model high-trust, contested-and-survived knowledge from the verified corpus and it outperforms a larger model trained on raw web text.

Works fully offline: hmctl mcp install --local auto-detects Ollama, wires a persistent SQLite ledger, and loads a default population — no API key, no internet.

---

Documentation

Start here

You want to…	Read
Install and run your first signed claim	getting-started · quickstart
Understand the core concepts	concepts
Drop HyperMind into your agent stack (facade, MCP, endpoint, adapters)	integrations
Feed a small model a trust-scored corpus	verified-corpus
Run a multi-agent domain simulation	simulations · SimLab
Browse runnable examples	examples/README.md

Go deep

Topic	Read
Protocol spec — 30 numbered sections (§01–§30, §21 split)	docs/spec/ · index
Verified corpus / ground-truth anchoring	spec §29 · spec §30
Architecture & storage	architecture
Architecture Decision Records	docs/adr/
Feature matrix · standards inheritance	feature-matrix · standards-map
5-layer cascaded security	spec §21 · docs/security/
Decide if it fits · operate a deployment	docs/decide/ · docs/operate/

Project

Roadmap · Changelog	ROADMAP.md · CHANGELOG.md
Contributing · Security policy	CONTRIBUTING.md · SECURITY.md
Governance · maintainers · charter	GOVERNANCE.md · MAINTAINERS.md · CHARTER.md

---

CLI

hmctl quickstart                       # zero-to-verifiable swarm, no config
hmctl init my-app                      # scaffold a starter project
hmctl mcp install                      # wire into Claude Desktop / Cursor (59 tools)
hmctl mcp install --local              # fully offline (Ollama + SQLite, no API key)
hmctl serve-endpoint                   # OpenAI-compatible endpoint on :8899
hmctl ingest notes.md --topic research # ingest documents into the swarm
hmctl dataset export --format dpo --out dpo.jsonl   # export fine-tuning dataset
hmctl population create my-lab --template research_lab --size 5
hmctl eval                             # run the calibration metric suite
hmctl orgs simulate --template university --topic "…" --rounds 6 --live
hmctl doctor                           # smoke-test the install

Every hmctl <cmd> --help lists its flags. Full engine reference: docs/simulations.md.

---

Configuration

All configuration is via environment variables. Set them in ~/.hypermind/env (one KEY=VALUE per line) — the CLI and MCP server load this file automatically.

OPENAI_API_KEY=sk-…           # LLM key (OpenAI / OpenRouter / Ollama / …)
OPENAI_BASE_URL=              # gateway URL — blank = OpenAI direct; http://localhost:11434/v1 for Ollama
HYPERMIND_LLM_MODEL=AUTO      # AUTO probes /v1/models and picks best available; or set e.g. gpt-4o
RELATA_URL=http://localhost:9090  # durable knowledge ledger (optional — SQLite fallback without it)
RELATA_BEARER_TOKEN=…         # auth token for managed RelataDB instances
HYPERMIND_DB=~/.hypermind/cache.db  # local SQLite fallback

# Web search — DuckDuckGo works keyless. Add any for richer results:
SERPER_API_KEY=               # Google Search via Serper (2,500 free/mo → serper.dev)
SEARCHAPI_KEY=                # Multi-engine search (100 free/mo → searchapi.io)

Copy .env.example to .env for a full annotated template.

See docs/configuration.md for the full reference of every HYPERMIND_* variable, its default, and what it controls. Quick commands:

hmctl env-vars    # live table of all tuning knobs
hmctl doctor      # health-check (reports SSE port, webhook, secret status)
hmctl config      # interactive wizard
hmctl status      # shows LLM, Relata, search backend, MCP servers — and what to fix
hmctl mcp install # wires Claude Desktop/Cursor + auto-adds fetch/Serper/SearchAPI MCP tools

---

Status

Engineering GA (1.0.0, 2026-07-09; SemVer binding). Current release: 1.9.0. Remaining gates are ecosystem, not code (see ROADMAP.md §External).

• Protocol — 30 numbered spec sections (§01–§30, §21 split) + independent reference_verifier/ proving two-impl interop
• SDK — async-first, fully type-hinted, 3197 tests; hybrid PQ signing, FROST k-of-n, dispute FSM (incl. SUSPENDED), capability tokens, RFC 6962 transparency
• 59 MCP tools — knowledge & retrieval, what-if simulation, adversarial debate, goal planning, hypothesis tracking, ingest, dataset export, population management, eval suite
• Federation — real multi-node TCP gossip (TCPGossipBus); libp2p is an optional external Rust binding
• SimLab web UI at make run

make test        # 3197 tests, ~90s
make lint        # ruff check + format
make run         # SimLab web UI on http://127.0.0.1:8765

---

Built at ZySec AI

ZySec AI is a research lab at the intersection of AI safety, applied cryptography, and connected intelligence. hypermind is open by default — spec, SDK, and security reviews are Apache-2.0, because the substrate of connected agent intelligence has to be a public good. Open research questions live in Discussions.

License

Apache-2.0 — see LICENSE. Builds on the IETF SCITT architecture, LAMPS composite signatures, RFC 9591 FROST, and RFC 6962.

HyperMind — many minds, learning together, with cryptographic chain of custody.

github.com/ZySec-AI/hypermind