for the whitepaper, see: https://github.com/nova-soma/HADES/blob/main/docs/HADES_whitepaper.html
Currently in development. possibly dangerous. not everything is working, but the main parts seem to be.
Use at your own risk. If it blows up your computer, it's not my fault and it probably happened to me too.
Here's the TL;DR: HADES — Hypothesis-Adaptive Distributed Expert System
A self-improving multi-agent reasoning system. You ask it something, an ensemble of domain experts self-selects to answer based on declared domain match and track record, and any claim an agent produces doesn't just get trusted. It gets shoved through a validation pipeline where the rest of the ensemble votes on it, HERO tallies weighted votes, and the thing resolves to confirmed, falsified, or contested. Knowledge isn't asserted; it's adjudicated.
Memory + governance layer that audits itself. Manat watches agent behavior and can retire misbehaving agents, escalating bigger structural changes to you.
Quarantine isolation — adversarial input gets analyzed on a physically separate, locked-down network, and the only way back into trusted memory is through a single audited choke point (Janus). Packets from quarantine !should! not be able to reach the internal net.
AssemblyLine — each expert trains itself over time, gated so a weight update can't make the ensemble dumber than it already was.
Federation — multiple HADES instances can talk, but a peer's identity is verifiable while its reasoning isn't, so every imported claim re-enters local validation. Sensible. Trust the signature, not the conclusion.
You, The human, get registered as the "Forge" expert so the thing is actually useful for your real work instead of being a science-fair project.
"so it's a chatbot?" — no, not really, but thats the part humans interact with mostly. It's an architecture for treating machine-generated claims as hypotheses that have to earn their place, distributed across hosts, with the trust boundary as the load-bearing wall. The grandiose mythology naming is a literally just for mnemonics.
Hypothesis-Adaptive Distributed Expert System
A self-improving ensemble of fine-tuned domain experts that coordinate through persistent shared memory. The ensemble can spawn new specialists, retire underperforming ones, and rewrite its own routing logic. It is governed by an internal validation protocol rather than fixed rules, and it works with a human partner to bootstrap its own toolchain.
Status: Reference implementation. The architecture is fully specified and the code compiles clean, but this is not production-ready software. Treat it as a research substrate.
Version: 0.3 (whitepaper) / Build 1 (reference implementation)
HADES is an attempt to build a small, sovereign AI system that gets better at the things its operator actually cares about — not by retraining a single model, but by maintaining an ensemble that improves itself through a validation process resembling peer review. Every claim the system commits to memory must survive review by agents who didn't make the claim. Every weight update must survive an evaluation against a living test suite. Every conflict triggers a vote among the agents who weren't party to the conflict.
The ensemble currently has eleven specialist agents (memory, governance, orchestration, validation, screening, consolidation, planning, medic, external boundary), six seed domain experts (systems programming, distributed architecture, evaluation methodology, the operator's working domain, research synthesis, security), and two hardened quarantine agents that analyze adversarial input in isolation. Everything routes through a single ZeroMQ message bus called Iris. There is no other communication path.
A short explanation of the key ideas:
Hypothesis-driven memory. Nothing enters the shared knowledge base as fact. Claims enter as hypotheses, get reviewed by agents not involved in producing them, and earn confirmed / falsified / contested status based on weighted voting. Confirmed claims become evidence the ensemble can act on. The validation status is itself a memory layer document.
Self-modifying ensemble. Agents can submit hypotheses about themselves and other agents. A successful self-modification hypothesis can change weights, retire an agent, or spawn a new one. A successful structural hypothesis can change the ensemble's understanding of its own architecture. The architecture document is itself a memory layer document, audited periodically by Athena.
Domain expert ensemble. Six seed experts cover the boostrap path to a self-compilable system. Each maintains its own eval harness, its own training pipeline (AssemblyLine), its own Engram table for low-latency memory retrieval. Experts self-select for queries based on declared domain match and historical success rate.
Human partner as Forge. The operator's working domain is registered as a domain expert called Forge at first launch. The system is built to be immediately useful for the operator's actual work, not just a research curiosity.
Quarantine isolation. Adversarial input that fails screening goes to a hardened pipeline running on its own network with its own model storage. The path back from quarantine to memory passes through exactly one agent (Janus), and every transfer is recorded as a quarantine_handoff document with full audit chain.
Federation. Multiple HADES instances can talk to each other. Federation handshakes (signed instance manifests, capability exchange) run through Janus. Hypotheses imported from a federated peer enter the local validation pipeline as pending claims — the local ensemble decides whether to accept them. Identity is verifiable; reasoning isn't, so every federated claim re-enters validation.
Distributed deployment. A single HADES instance can span multiple hosts. Each host runs one Iris router; Iris instances peer over a separate port and forward messages between hosts transparently. Agents don't change — they connect to their local Iris and address other agents by ID regardless of which host owns them.
The full architectural rationale, including governance protocols, agent specs, message taxonomy, and bring-up sequences, is in HADES_whitepaper.html.
Requires Docker, Python 3.11+, and (recommended) an NVIDIA GPU with at least 16 GB VRAM.
git clone https://github.com/nova-soma/HADES.git
cd hades
bash hades-install.shThe installer picks an installation profile interactively. For an all-in-one install on a single machine:
bash hades-install.sh --profile single-host --yesAfter installation:
cd ~/hades
bash scripts/start.shWhen health checks pass, open http://localhost:8000. The interface will ask you to confirm your role as the human partner and declare your primary working domains, which configures the Forge expert. The system is ready for queries once Forge registers.
See INSTALL.md for profile options, hardware sizing, and distributed deployment patterns.
| Document | What it covers |
|---|---|
HADES_whitepaper.html |
Full architecture, agent specs, governance protocols, message taxonomy. The authoritative reference. |
README.md |
This file — project overview and quick start. |
INSTALL.md |
Installer reference: profiles, hardware sizing, distributed deployment, troubleshooting. |
ARCHITECTURE.md |
Code map: where each subsystem lives, how to navigate the source tree, key abstractions. |
agents/README.md |
Agent inventory with the mythological naming key. Start here if you don't know who Manat or Fukurokuju is. |
docker/README.md |
Container topology, network isolation, the hardened profile. |
CONTRIBUTING.md |
Contributor guide. |
hades/
common/ Shared infrastructure (message bus, types, embedding, screening)
protocols/ Iris ZMQ router (not an agent — pure protocol)
agents/ All agents, one directory each
base.py BaseAgent class every agent inherits from
domain_expert/ Shared base + AssemblyLine for the six seed experts
thoth/ hero/ ... One subdirectory per agent
docker/ Compose file and Dockerfiles
scripts/ init_vault.sh, start.sh, health_check.py, build_engram.py, train_lora.py
static/ Single-page HTML UI served by Hermes
datasets/ Seed training data (per expert)
evals/ Living eval harnesses (per expert)
HADES_whitepaper.html Full architecture specification
hades-install.sh Installer
This is research-stage software. The architecture is specified end-to-end and the reference implementation builds cleanly. Most of the core functionality has been exercised end to end in development; very little has been exercised under real load.
What works as designed:
- Validation pipeline. Hypotheses submitted by any agent get reviewed by the local ensemble; HERO accumulates weighted votes; thresholds resolve to confirmed, falsified, or contested.
- Governance. Manat tracks per-agent participation, drives the correction window, executes structural remediations (retire-agent direct, spawn-agent and refactor escalate to human).
- Consolidation. Inari runs blind peer review, detects contradictions, surfaces them in the merge prompt, and submits persistent contradictions as CROSS_DOMAIN hypotheses.
- Self-improvement. AssemblyLine runs real LoRA training (unsloth or peft+transformers, with a Modelfile fallback when neither framework is installed) and real candidate evaluation via Ollama, with the regression gate applied to actual eval scores.
- Eval scoring. Uses an LLM judge (
qwen3:7bby default) with disk-cached judgments rather than keyword overlap. - Partner adaptation. Hermes learns the human partner's communication preferences from feedback (rating, notes, corrections) and applies them via a transformation pass.
- Distributed coordination. Iris instances peer across hosts. Three target-resolution states (local / remote / unknown), loop prevention via forwarded-from annotation, hub-and-spoke discovery via control plane.
- Federation. Cross-instance handshake with HMAC-signed manifests, peer registry persisted to disk, hypothesis import flows through the local validation pipeline.
Known limitations:
- Bootstrap dependency. The system depends on a working LLM (default: Qwen3 via Ollama). It is not yet self-hosting in the strict sense.
- Distributed deployment is not load-tested. The coordination layer works in code and unit tests but has not been exercised across physical hosts at production traffic.
- LoRA adapter serving requires GGUF conversion. Real PEFT adapters can be trained but Ollama needs them converted to GGUF before it can serve them. The build acknowledges this honestly — for real candidate evaluation, the operator needs to do the conversion and wire up an
ADAPTERModelfile manually. - Federation uses shared-secret HMAC. Sufficient for pairwise trust between known operators; not sufficient for scaled deployment with key rotation, revocation, or non-repudiation. Asymmetric crypto (Ed25519) is the obvious replacement; the interface is designed to make it a local swap.
- No formal eval. The ensemble's overall performance has not been benchmarked against any standardized task suite. This is intentional — the system is meant to be evaluated on the operator's actual work, not on generic benchmarks.
- Pre-1.0. APIs, message types, and storage schemas will change. Migrations are not provided.
If any of those bother you, this is not the right project for you yet. If they don't, the architecture is documented well enough that you can read your way to whatever extension you need.
Dual licensed: AGPL-3.0 and SSPL-1.0, at the user's option.
Both licenses are strong copyleft. If you run a modified version of HADES as a network service, or incorporate any part of it into a service offered to third parties, the modifications and any incorporating software must be released under one of the same two licenses.
Full license text in LICENSE.
The intent is straightforward: build on this freely, including commercially, but the same freedom must propagate. Anything offered as a service that uses this code is itself subject to the same release obligations.
The architecture draws on a long lineage of work:
the ensemble validation protocol was envisioned as peer review in scientific practice,
the Engram retrieval design follows the sparsity-allocation work in arXiv:2601.07372,
the agent topology takes from actor-model systems with explicit message buses,
the self-modification protocol owes a debt to debate-as-alignment literature, specifically karpathy's autoresearch.
The names are mostly from religious and mythological traditions covering knowledge, judgment, healing, and guardianship — anyone wondering why a memory keeper is called Thoth and a medic is called Asclepius can read agents/README.md.
Basically, I had to call them something and these names made it easy for me to remember what they were meant to do in a single word.
Built by Coleman Nickolas Warner, with substantial design conversations on Claude. The fact that I didn't have to hand code all of this is amazing. Claude filled the biggest gap I couldn't: Time. Could I have done it all myself? Yeah, if I had like 8 months to do all the research, program it, troubleshoot, bugfix, and repeat. I didn't have to though. Luckily my family (especially my wife) is amazing and supports me, otherwise I'd never get anything done.
If I used your work and didn't cite you, please inform me and I will make it happen.
If you use HADES in a publication, please cite:
@software{warner2026hades,
author = {Warner, Coleman Nickolas},
title = {HADES: Hypothesis-Adaptive Distributed Expert System},
year = {2026},
url = {https://github.com/nova-soma/hades}
}This document is part of HADES — Hypothesis-Adaptive Distributed Expert System. Copyright (C) 2026 Coleman Nickolas Warner. Dual licensed under AGPL-3.0 and SSPL-1.0, at your option. See LICENSE for full terms. Any modified version of this software, or any software incorporating it as part of a service offered to third parties, must be released under the same terms.