Hive Mind

Hive-Mind Consensus

Ruflo supports queen-led Byzantine fault-tolerant consensus across agent swarms.

---

Topologies

Hierarchical

• Queen (central coordinator) assigns tasks and collects results
• Workers execute tasks and report back to Queen
• Anti-drift control: Queen maintains authoritative state
• Best for: Small teams (6–8 agents), tight coordination needed

        Queen
        /  |  \
    W1  W2  W3  W4

npx ruflo@latest hive-mind init --topology hierarchical --queen-id coordinator

Mesh

• Fully connected: Every agent talks to every other agent
• Peer-to-peer: No central authority
• Consensus via gossip: Eventual consistency
• Best for: Decentralized teams, high autonomy

    W1 ↔ W2
    ↕   ↕
    W3 ↔ W4

npx ruflo@latest hive-mind init --topology mesh

Hierarchical-Mesh (Hybrid)

• Queen coordinates specialist clusters
• Clusters are mesh-connected internally
• Best for: Large teams (10–15 agents), mixed coordination needs

         Queen
        /      \
    Cluster1  Cluster2
    /  |  \    / |  \
   W1 W2 W3  W4 W5 W6

Ring

• Linear chain: W1 → W2 → W3 → W4 → W1
• Low latency for sequential operations
• Best for: Pipeline-style workflows

Star

• Central hub (not a Queen)
• All workers connect to hub
• Less strict than hierarchical (hub doesn't command)

Adaptive

• Topology switches based on load
• Hierarchical when coordinating
• Mesh when parallelizing
• Best for: Unknown workloads

---

Consensus Strategies

Byzantine Fault-Tolerant (BFT)

Tolerates f < n/3 faulty nodes (traditional Byzantine assumption):

npx ruflo@latest hive-mind init \
  --topology hierarchical-mesh \
  --consensus byzantine \
  --max-agents 9

With 9 agents: tolerates up to 2 malicious/crashed agents.

Algorithm: PBFT (Practical Byzantine Fault Tolerance)

• Multiple rounds of voting
• Quorum requirement: 2/3 + 1
• Latency: O(n) message rounds

Raft

Leader-based consensus, tolerates f < n/2 faulty nodes:

npx ruflo@latest hive-mind init \
  --topology hierarchical \
  --consensus raft \
  --max-agents 5

Algorithm: Raft (Diego Ongaro, Mendus Housley)

• Single leader elected via majority vote
• Followers replicate leader's state
• Re-election on leader failure

Better for: Synchronous, reliable networks

Gossip (Epidemic)

Asynchronous, eventual consistency:

npx ruflo@latest hive-mind init \
  --topology mesh \
  --consensus gossip

Algorithm: Anti-entropy + push/pull

• Agents periodically exchange state
• State propagates exponentially
• No strong consistency guarantee (but fast)

Better for: Unreliable networks, high latency tolerance

CRDT (Conflict-Free Replicated Data Type)

No coordination needed; conflicts resolved by merge semantics:

npx ruflo@latest hive-mind init \
  --consensus crdt

Examples: Last-write-wins, OR-sets, LWW-registers

• Every agent has a local copy
• Updates are locally visible immediately
• Automatic conflict resolution
• No quorum required

Better for: Offline-first, high availability

Quorum

Configurable voting threshold (flexible):

npx ruflo@latest hive-mind init \
  --consensus quorum \
  --quorum-preset majority  # 50% + 1

Presets:

• unanimous — All agents must agree
• majority — > 50% must agree (default)
• supermajority — > 66% must agree

---

Hive-Mind Operations

Initialize

npx ruflo@latest hive-mind init \
  --topology hierarchical-mesh \
  --max-agents 10 \
  --queen-id queen-agent \
  --consensus raft

Join the Collective

npx ruflo@latest hive-mind join \
  --agent-id worker-1 \
  --role worker  # "worker" | "specialist" | "scout"

Spawn Workers Directly

npx ruflo@latest hive-mind spawn \
  --count 4 \
  --role worker \
  --prefix hive-worker

Broadcast Message

Send message to all workers:

npx ruflo@latest hive-mind broadcast \
  --message "Run security audit" \
  --priority critical

Consensus Proposal

Propose a decision for the collective to vote on:

npx ruflo@latest hive-mind consensus propose \
  --type "upgrade-dependency" \
  --value '{"package":"express","version":"4.18.2"}' \
  --strategy raft

Workers vote:

npx ruflo@latest hive-mind consensus vote \
  --proposal-id "prop-123" \
  --voter worker-1 \
  --vote true  # or false

Check status:

npx ruflo@latest hive-mind consensus status --proposal-id "prop-123"

Memory (Shared State)

All agents can read/write shared memory:

# Write to shared state
npx ruflo@latest hive-mind memory set \
  --key "deployment-status" \
  --value "in-progress"

# Read from shared state
npx ruflo@latest hive-mind memory get \
  --key "deployment-status"

# List all shared state
npx ruflo@latest hive-mind memory list

Status & Health

npx ruflo@latest hive-mind status

npx ruflo@latest hive-mind health \
  --swarm-id hive-1

Shutdown Gracefully

npx ruflo@latest hive-mind shutdown \
  --graceful true  # Wait for pending tasks

---

Example: Code Review Swarm

Spawn a queen + 4 reviewer agents:

// Initialize hive
await hiveMind.init({
  topology: "hierarchical",
  consensus: "raft",
  maxAgents: 5
})

// Spawn queen
Task({
  prompt: "You are the code review queen. Coordinate PRs among reviewers.",
  subagent_type: "pr-manager",
  name: "queen",
  run_in_background: true
})

// Spawn 4 reviewers
for (let i = 0; i < 4; i++) {
  Task({
    prompt: "Review the PR assigned by the queen. SendMessage results to queen when done.",
    subagent_type: "reviewer",
    name: `reviewer-${i}`,
    run_in_background: true
  })
}

// Broadcast PR to review
SendMessage({
  to: "queen",
  summary: "PR #123 ready for review",
  message: "[PR details]"
})

The queen:

1. Receives PR assignment
2. Broadcasts to all reviewers (via gossip/mesh)
3. Collects votes (via consensus proposal)
4. Reports final decision

---

Trade-offs

Strategy	Latency	Consistency	Fault Tolerance	Messaging	Best For
BFT	High	Strong	f < n/3	O(n²)	Security-critical
Raft	Medium	Strong	f < n/2	O(n)	Production
Gossip	Low	Eventual	f < n	O(n log n)	Large, unreliable nets
CRDT	Low	Eventual	f = n	O(1)	Offline-first, high-availability

---

Performance Metrics

Check consensus health:

npx ruflo@latest hive-mind consensus engine-stats

Output:

Consensus Strategy: raft
Total Proposals: 127
Approved: 124 (97.6%)
Rejected: 2
Timed Out: 1

Average Consensus Time: 45ms
P95 Consensus Time: 120ms
P99 Consensus Time: 250ms

Network Messages: 1,847
Replication Lag: 0ms (followers)
Leader Uptime: 99.94%

---

Ruflo v3.10.1 · GitHub