hermes-hive 2.0.23

Multi-Agent Orchestration for Hermes Agent. Code constrains AI — not the other way around.

🐝 HIVE

Code constrains AI — not the other way around.

Multi-Agent Orchestration for Hermes.
Architect → Planner → Coder → Reviewer. All driven by a deterministic state machine,
none driven by prompt prayers.

pip install hermes-hive

---

Why HIVE?

Every multi-agent framework tells LLMs "please follow these rules."

HIVE doesn't ask. It enforces.

Framework	How it constrains LLMs	Can LLM break it?
CrewAI	Prompts describe roles	✅ Yes — LLM forgets it's a Coder
AutoGen	Agents negotiate via chat	✅ Yes — two LLMs agree on a mistake
MetaGPT	SOP written in prompts	✅ Yes — LLM skips a step, no one notices
LangGraph	Graphs, but LLM can route edges	✅ Yes — LLM takes wrong path
HIVE	State machine in Python code	❌ No — code is the guard

HIVE's orchestrator is a deterministic state machine (transitions library, 12 states, 23 transitions). LLMs are called only at specific states (Architect, Planner, Reviewer). They cannot skip steps, change the flow, or override constraints.

---

Quick Start

pip install hermes-hive
hive init
hive build "A CLI calculator"

That's it. HIVE orchestrates 4 agents across your project. You watch it build.

Upgrade

pip install --upgrade hermes-hive
# No hive init needed — SKILL.md auto-updates on next startup

Maintenance (tell your Hermes)

• "Upgrade HIVE" → pip install --upgrade hermes-hive
• "Check HIVE health" → hive doctor
• "Clean up HIVE" → hive cleanup

Upgrade

pip install --upgrade hermes-hive
# No need to re-run hive init — SKILL.md auto-updates on next startup

---

The 4-Agent Pipeline

You: "Build a calculator"
  │
  ▼
┌─────────────────────────────────────┐
│ 🏗️  Architect (v4-pro)              │
│ Multi-turn requirements dialogue    │
│          │ User confirms            │
│          ▼                          │
│       project_brief.json            │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ 📋  Planner (v4-flash)             │
│ Splits into DAG tasks:             │
│   T1: Core engine (reasonix)       │
│   T2: Deploy verify (toolman)      │
│   T3: Cleanup (toolman)            │
│          │                         │
│          ▼                         │
│       tasks/*.json                  │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ ⌨️  Coder (Reasonix / LLM fallback) │
│ Writes code + pytest self-verify   │
│   T1 → calculator.py               │
│          │                         │
│          ▼                         │
│       src/*.py                      │
└─────────────────────────────────────┘
  │
  ▼
┌─────────────────────────────────────┐
│ 🔍  Reviewer (v4-flash)            │
│ Audits every output:               │
│   ✅ pass → next layer             │
│   🟡 minor → retry                 │
│   🔴 fatal → replan                │
│          │                         │
│          ▼                         │
│       ✅ DONE → projects/           │
└─────────────────────────────────────┘

Every transition between boxes? Python code, not an LLM decision.

---

HIVE is a Hermes plugin. No extra desktop app needed.

~/.hermes/
├── config.yaml          ← HIVE reads your model/API config
├── .env                 ← HIVE reads your API keys
├── skills/hive/         ← SKILL.md teaches Hermes when to invoke hive
└── hive/
    ├── hive.json        ← 🌐 Global config
    ├── projects/        ← Built projects
    ├── chroma_db/       ← L3 vector memory
    └── skill_registry.json

From Hermes CLI or Desktop: "Build me a web scraper" → Hermes loads the hive skill → runs hive build.

---

What HIVE Manages

Capability	Description
Project lifecycle	Versioned briefs, changelogs, task progress
Skill evolution	DONE triggers skill extraction; review → approve/reject/merge
L3 Memory (ChromaDB)	3-domain vector memory, BGE embeddings (optional)
Crash recovery	Atomic file-system checkpoints; resume skips done tasks
Parallel execution	ThreadPoolExecutor, max 3 concurrent agents
Entropy control	Stale workspace cleanup, dormant skill archival
Full audit trail	Every action → JSON file. Debuggable, replayable
LLM fallback	Coder: Reasonix (Go) preferred, LLM auto-fallback
Multi-Provider	DeepSeek / OpenAI / Anthropic / OpenRouter
Bilingual CLI	lang zh / lang en instant switch
Open framework	Add custom agents via config files — no code changes needed

---

Customize & Extend

HIVE is an open framework. Every agent is defined by configuration files, not hardcoded logic. You — or your Hermes agent — can add new agent roles, tune behavior, and manage the ecosystem without touching Python code.

Agent Configuration (3 files per role)

profiles/{role}/
└── config.yaml      ← model, tools, memory settings

agents/{role}/
├── soul.md          ← agent identity & behavior rules
├── skills.md        ← domain knowledge & patterns
└── model.yaml       ← model parameters

Constitution (agents/constitution.md)

Global rules injected into every agent. All agents share this — define cross-cutting constraints here.

Ecosystem Management (governance/)

File	Purpose
skill_governor.py	Skill registry — conflict detection, lifecycle
hive_memory.py	ChromaDB L3 memory — three-domain vector store
entropy.py	Cleanup — stale workspaces, dormant skills
profile_manager.py	Profile validation on startup

Global Configuration (hive.json)

All HIVE behavior is controlled by a single file at ~/.hermes/hive/hive.json. Deployed automatically by hive init.

🔒 Safety guarantee: If you delete this file, corrupt the JSON, or set invalid values — HIVE runs with code defaults. Each field falls back independently. You cannot break HIVE by misconfiguring it.

{
  "orchestrator":    // max_children, max_retries, parallel_workers …
  "provider_defaults": // deepseek / openai / anthropic / openrouter
  "coder":           // engine: auto | reasonix | llm
  "memory":          // ChromaDB enabled, embedding model, top_k
  "language":        // default: zh | en
  "skills":          // auto_approve, merge_threshold
  "entropy":         // workspace TTL, skill lifecycle days
  "agent_overrides": // per-role temperature / max_tokens
}

Full reference: see hive.json in the repository.

Adding a New Agent

1. Create profiles/{my-agent}/config.yaml
2. Create agents/{my-agent}/soul.md
3. Add to constitution.md if global rules apply
4. Register in orchestrator/protocol.py if new task types needed

No Python code changes required for basic agents. The state machine discovers profiles from the filesystem.

---

Architecture

┌──────────────────────────────────────────┐
│              HIVE Orchestrator            │
│          (Pure Python State Machine)      │
│                                          │
│  IDLE → ARCHITECTING → PLANNING →        │
│  DISPATCH → EXECUTING → REVIEWING →      │
│  DONE / REPLAN / RETRY                   │
│                                          │
│  🔒 LLMs cannot cross state boundaries   │
└──────────────────────────────────────────┘
         │          │          │
    ┌────▼───┐ ┌───▼────┐ ┌──▼──────┐
    │Architect│ │Planner │ │Reviewer │
    │(v4-pro) │ │(v4-flash)│(v4-flash)│
    └────────┘ └────────┘ └─────────┘
                    │
              ┌─────▼─────┐
              │  Reasonix  │
              │ (Go binary)│
              └───────────┘

Communication: File system + JSON
Concurrency:   Atomic file renames
Auditability:  Every action = one JSON file

---

Design Philosophy

1. Code Constrains LLMs. If the rule can be expressed in code, it's in code. Prompts are for creative work, not enforcement.

2. File System as Protocol. Agents communicate via JSON files in agreed directories. cat any file to see exactly what happened.

3. No Trust. LLMs fill fields → code validates and may override. Reviewer misses a task? Code fills in default pass. LLM misjudges? Code override corrects it.

4. Local-First. Everything runs locally. Orchestration, memory, and state stay on your machine.

---

Requirements

• Hermes Agent — github.com/NousResearch/hermes-agent
• Python 3.12+
• API key in ~/.hermes/.env (DeepSeek / OpenAI / Anthropic / OpenRouter)
• Reasonix (optional — LLM Coder auto-fallback)

---

vs. The Competition

Feature	HIVE	CrewAI	AutoGen	LangGraph
Constraint	Code state machine	Prompt roles	Prompt negotiation	Graph + LLM routing
LLM breaks flow?	❌ No	✅ Yes	✅ Yes	✅ Yes
Crash recovery	✅ Checkpoint	❌	❌	❌
Parallel execution	✅ ThreadPool	❌ sequential	✅ conversation	✅ graph
Auditability	Every action = file	Logs	Logs	Traces
Memory	3-domain ChromaDB	Single vector DB	History	Checkpoints
Skill evolution	✅ Auto-extract	❌	❌	❌
Hermes native	✅ Plugin	❌	❌	❌
Install size	<300KB	pip + deps	pip + deps	pip + deps

---

FAQ

Q: Do I need to know multi-agent systems? No. Type hive build "your idea" and watch.

Q: What if the LLM makes a mistake? Reviewer catches it. Minor → retry. Fatal → replan. Code override prevents LLM misjudgments from derailing builds.

Q: Can I use OpenAI instead of DeepSeek? Yes. HIVE reads Hermes's provider config. Set provider in profile configs.

Q: What if my computer crashes mid-build? hive resume picks up from the last checkpoint.

Q: Is this just a fancy prompt chain? No. The orchestrator is a Python state machine. LLMs are called at 4 specific points. Everything between is deterministic code.

Q: Do I need Hermes? Yes — HIVE is a Hermes plugin. It uses Hermes's AIAgent engine and provider management.

---

_{Built for the Hermes ecosystem. v2.0.2}