Hive Mind — Design¶

Upstream Master Issue: rysweet/amplihack-rs#2710 Upstream PR: rysweet/amplihack-rs#2717 Rust port crate: amplihack-hive

Problem Statement¶

Goal-seeking agents generated by the Goal Agent Generator operate with isolated memory. When multiple agents work on related tasks they cannot share discoveries, leading to duplicated effort and missed cross-domain insights. The hive mind gives them a shared substrate while preserving per-agent autonomy.

Solution: Layered Hive Mind¶

Conceptually the hive mind composes four independent mechanisms into a layered architecture where each layer solves a distinct problem:

┌─────────────────────────────────────────────────────┐
│  Layer 4: QUERY                                     │
│  Content-aware retrieval, merged & dedup'd results   │
├─────────────────────────────────────────────────────┤
│  Layer 3: DISCOVERY (Gossip Protocol)               │
│  Periodic top-K fact sharing for "unknown unknowns"  │
├─────────────────────────────────────────────────────┤
│  Layer 2: TRANSPORT (Event Bus)                     │
│  Promotion / learn / query events between peers      │
├─────────────────────────────────────────────────────┤
│  Layer 1: STORAGE (Graph)                           │
│  Per-agent fact graph + promotion policy             │
└─────────────────────────────────────────────────────┘

Layer	Concern	Without It
Storage	Where do shared facts live?	No persistence or access control
Transport	How do promotions propagate?	Agents must poll for changes
Discovery	How do agents find facts they didn't know to look for?	Only query-based retrieval
Query	How are results from all layers merged?	Duplicate facts in results

Rust Port Surface¶

The port keeps the same four-layer model but with a trimmed public API re-exported from amplihack_hive::*. The high-level entry point is [HiveMindOrchestrator].

use amplihack_hive::{HiveMindOrchestrator, DefaultPromotionPolicy, Result};

fn main() -> Result<()> {
    let mut hive = HiveMindOrchestrator::new(Box::new(DefaultPromotionPolicy {
        promote_threshold: 0.7,
        broadcast_threshold: 0.9,
        gossip_threshold: 0.5,
    }))
    .with_agent_id("alice".to_string());

    let outcome = hive.store_and_promote(
        "networking",
        "PostgreSQL listens on TCP 5432",
        0.95,
        "alice",
    )?;
    assert!(outcome.promoted && outcome.broadcast);

    for fact in hive.query_unified("networking")? {
        println!("  [{:.0}%] {}", fact.confidence * 100.0, fact.content);
    }
    Ok(())
}

Federation by Composition¶

There is no tree-shaped federation API on HiveGraph in the current public surface. Federation is built by attaching peer orchestrators:

let mut root = HiveMindOrchestrator::with_default_policy()
    .with_agent_id("root".to_string());
root.add_peer(child_orchestrator);

let merged = root.query_unified("topic")?;   // local + every peer, dedup'd

HiveMindOrchestrator::query_unified aggregates query() across self and every add_peer-attached orchestrator, dedups by content, and sorts by descending confidence.

Experiment Results (Upstream)¶

The upstream Python experiments compared four single-mechanism hives against a unified composition. The Rust port preserves the same four-layer intent.

#	Approach	Tests	Overall Score
1	Shared Blackboard	31	47%
2	Event-Sourced	47	49%
3	Gossip Protocol	42	54%
4	Hierarchical Graph	54	57%
5	Unified (combined)	40	94%

The unified composition outperformed the best single mechanism by +37 percentage points, which motivated the four-layer design above.

Module Reference (re-exports from `crates/amplihack-hive/src/lib.rs`)¶

Only symbols actually re-exported by lib.rs today are listed. Internal modules used by these (e.g. controller, feed, hive_events) are reached through path-qualified imports.

Orchestration & promotion¶

[HiveMindOrchestrator] — composes graph + bus + policy + peers
[PromotionPolicy] (trait) and [DefaultPromotionPolicy]
[PromotionResult]

Storage¶

[HiveGraph] — per-orchestrator fact graph
graph::search::{tokenize, word_overlap, ScoredFact}
controller::{HiveController, InMemoryGraphStore, InMemoryGateway} — desired-state reconcile + lightweight stores

Transport¶

[EventBus] (trait), [LocalEventBus], [MAX_MAILBOX_SIZE]
Topic constants: HIVE_AGENT_READY, HIVE_FEED_COMPLETE, HIVE_LEARN_CONTENT, HIVE_QUERY, HIVE_QUERY_RESPONSE, ALL_HIVE_TOPICS

Discovery¶

[GossipProtocol], convergence_check
[BloomFilter]
DHT primitives: DHTRouter, HashRing, ShardFact, ShardStore
CRDTs: GCounter, GSet, LWWRegister, ORSet, PNCounter

Query / quality¶

Embeddings: cosine_similarity, cosine_similarity_batch, dot_product, normalize
Reranking: ScoredFact, hybrid_score, hybrid_score_weighted, rrf_merge, rrf_merge_scored, trust_weighted_score
Query expansion: expand_query, search_expanded
Quality gate: QualityGate, score_content_quality

Models & lifecycle¶

models::{HiveFact, HiveAgent, HiveEdge, BusEvent, HiveManifest, HiveState, AgentSpec, EventBusConfig, GatewayConfig, GossipConfig, GossipMessage, GraphStats, GraphStoreConfig, MergeResult, make_event} and the DEFAULT_* / MAX_TRUST_SCORE constants
fact_lifecycle::{FactTTL, decay_confidence, gc_expired_facts, refresh_confidence}

Distributed primitives¶

distributed::{AgentNode, HiveCoordinator}
hive_eval::{HiveEvalConfig, HiveEvalResult, QueryResult, EvalResponder, run_eval, run_eval_with_responder}
feed::{FeedConfig, FeedResult, run_feed}
workload::{HiveEvent, HiveWorkloadConfig, WorkloadStatus}

Errors¶

HiveError, Result

What Has Been Built¶

Capability	Status
In-process layered hive (storage / transport / discovery / query)	✅ implemented in `amplihack-hive`
Eval harness driving the bus end-to-end	✅ `run_eval_with_responder`
Learning feed publisher	✅ `feed::run_feed`
Per-agent distributed unit + coordinator	✅ `AgentNode` + `HiveCoordinator`
Bloom / CRDT / DHT / gossip primitives	✅ re-exported
`amplihack hive` subcommand routing	⏳ planned — `hive_haymaker.rs` exists but is not wired
Service Bus / Event Hubs transport	⏳ planned — runner logs a stub warning today
Tree federation API on `HiveGraph` (parent/children)	⏳ planned — federate by composing orchestrators today
`LearningAgent` ↔ hive bridge	⏳ planned — `amplihack-agent-core` has no `hive_store` builder method today

Design Decisions¶

Re-export-driven public surface. lib.rs defines the supported API contract. Anything not re-exported is implementation detail and may change without notice. Documentation must stay aligned with lib.rs.
Composition over hierarchy. Multi-hive federation is built by add_peer() rather than baking parent/child links into HiveGraph. This keeps HiveGraph simple and lets the orchestrator own all cross-hive policy.
Logged failure, never silent. Promotion / hive errors are surfaced via Result<…, HiveError>. Callers that want best-effort fan-out wrap the call and tracing::warn! on Err. The library does not swallow errors.
Cloud transport is opt-in and explicit. Until Service Bus / Event Hubs land, supplying a connection string emits a tracing::warn! and falls back to LocalEventBus. There is no silent degradation.