HIVE-MIND

🌐 English | Français

The Philosophy: Why HIVE-MIND?

Modern LLM deployments look strong in demos yet fail in the wild — not because models lack capability, but because the harness around them is thin. A stateless prompt loop cannot remember, cannot budget, cannot coordinate, and cannot recover from a tool error without human help. The model is naked without the harness; a harness without a model is dead.

HIVE-MIND was engineered to invert that hierarchy. It treats the harness itself as the primary artifact — a research testbed where every seam is measurable. Five strict layers, twenty-six extractable subsystems, eight provider families and five channels are not features but instruments for asking: what scaffolding actually makes a model better at tasks it was never trained to do?

The mechanism is selective wiring, not context stuffing. A sandboxed PTC VM that saves 80–95% of tokens, a hash-anchored Myers reconciler that eliminates drift, an AST skeleton that cuts 90% of code context, a two-tier memory with Ebbinghaus forgetting, and a Smart Router that rotates quotas with zero 429s. HIVE-MIND exists to prove, instrument and iterate on that hypothesis in public, as an experimental harness.

Architecture

HIVE-MIND is a strict five-layer harness with one-way dependency: each layer talks only to its immediate neighbours, no skips. The decomposition into 26 subsystems is formally audited in ARCHITECTURE.md with Martin instability metrics.

Capabilities

Twenty-six subsystems, each extractable, independently testable and documented with its own Diátaxis page in documentation/. The board below is editorial — amber on #0D1117, 12px radius, balanced 16:9 geometry.

Domain map — expand for SS-01 to SS-26

How It Works

From a normalized NormalizedMessage to a delivered answer, the harness executes a closed loop: queue fairly, hydrate selectively, route intelligently, think with tools, validate both pre- and post-action, then persist only what matters. The diagram below is a compact landscape (1280×520) exported from hand-crafted SVG — zero raw Mermaid in markdown.

Providers

The two-layer Smart Router speaks 8 provider families through a unified pivot. Layer 1 rotates keys and tiers with sliding-window circuit breakers; Layer 0 adapts GenerationParams to each wire protocol.

Channels & Transports

Channel	Status	Transport File	Notes
WhatsApp		baileys.ts	Multi-device, media, stickers, voice
Discord		discord.ts	Guilds, DMs
Telegram		telegram.ts	Groups, inline bots
CLI		cli.ts	Full interactive UX
TUI Server		TuiServerTransport.ts	Loopback WS :5001 (default, auto-increments if busy; see tui-connection.json)

Quick Start

Note — HIVE-MIND is an experimental research harness, not a product. Interfaces are unstable and may change without notice.

1 — Clone & Install (Node 22+ required)

# Clone the harness
git clone https://github.com/leandre755/HIVE-MIND.git
cd HIVE-MIND

# Install dependencies
npm install

2 — Configure Environment

# Copy the template and fill at least one LLM key + Supabase + Redis
cp .env.example .env
nano .env

3 — Launch the Harness

# Interactive startup menu — channel auth + provider selection
npm start

# Watch mode — auto-restart on source change
npm run dev

4 — Verify (build + lint + tests)

# 73 suites — 595 unit tests
npm run test:unit

# Full local gate
npm run build && npm run lint:fast && npm run test:unit

Project Structure

hive-mind/
├── src/
│   ├── bin/              # daemon entry — hive-mind.ts
│   ├── cli/              # startupMenu, whatsappAuthHelper, authSessionManager
│   ├── config/           # Zod schemas, pricing, keyResolver, blueprints
│   ├── core/             # BotCore, ServiceContainer, FairnessQueue, transports
│   ├── persona/          # system prompts + lessons_learned.md
│   ├── plugins/          # modular tools (manifest Zod-validated)
│   ├── providers/        # Layer0 ExecutionLayer + Layer1 SmartLayer + families
│   ├── scheduler/        # node-cron + dbMonitoring
│   ├── services/         # memory L1/L2, agentic Planner/SubAgent, PTC VM, runtime
│   ├── supabase/         # SQL migrations, pgvector match_* functions
│   └── utils/            # safeFs.ts, pidLock, TlsImpersonator, toolExecution
├── documentation/        # 97 Diátaxis docs (core/providers/transport/memory/runtime/plugins)
├── src/tests/
│   ├── unit/             # 73 suites — core/providers/runtime/services
│   ├── integration/      # 5 suites, 34 tests
│   └── e2e/              # harness + WebSocket cross-process
├── .GCC/                 # Git-Context-Controller session state
└── .gouvernance/         # review-policy, accompanied-agent, governance

Validation

Live Demonstration

Animated media is reserved for concrete proof of execution. Below is the editorial teaser (GIF, 1280×480, 24 frames) — the static hero stays static by design.

Teaser loop: npm start → harness boots → transports connect → ReAct ×10 → memory persists → WS streams to TUI. Replace with your own screen capture for proof of work.

Contributing

All non-trivial work ships through Pull Requests only. An agent never approves its own code.

• Read AGENTS.md — mandatory rules for every agent and human
• Read ARCHITECTURE.md — layer blueprint and 26 SS boundaries
• Read .gouvernance/review-policy.md — Strict Review, dual-layer defense, acceptance gates

# Branch naming — Conventional Commits enforced at pre-commit
git checkout -b feat/my-feature
git checkout -b fix/issue-description

# PR budget: ≤1000 lines warning, 2500 hard limit (docs/assets excluded)

Security

Private disclosure only — never via public issues. See SECURITY.md.

• Every filesystem access goes through src/utils/safeFs.ts (resolveWithinRoot traversal-safe)
• Secrets are scanned on every commit and push via gitleaks (staged + full history), ALLOW_CONFIG_EDIT=1 for protected files
• ALLOW_CONFIG_EDIT=1 git commit is the only authorized path for package.json, .githooks/ etc. — --no-verify stays forbidden

_{HIVE-MIND is an experimental research harness — the scaffolding is the artifact.
Editorial premium — amber #F59E0B · orange #F97316 on #0D1117 · Fluent 3D icons
Apache-2.0  ·  leandre755  ·  2026}