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.

Layer	Role	Core Components
Transport	Unified ingress / egress	WhatsApp (Baileys), Discord, Telegram, CLI, TUI WebSocket :5001
Orchestration	ReAct loop, IoC, scheduling	BotCore, ServiceContainer, FairnessQueue, BlueprintManager, Planner, PTC VM
Runtime	Safety & cost governance	VIGIL, Ralph, ConstraintManifold, ContextWindowService
Cognitive	Hierarchical memory	Redis L1 <50ms, Supabase pgvector L2, MAPLE, HNSW
Smart Router	Model routing	Layer 1 SmartLayer (quota rotation, circuit breakers), Layer 0 ExecutionLayer (8 adapters)

---

Live Demonstration

Soon.

---

Capabilities

Twenty-six subsystems, each extractable, independently testable and documented with its own Diátaxis page in documentation/.

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

Domain	Subsystems	Responsibility
01 Core & Concurrency	SS-01 → SS-09	ServiceContainer (I=0.00), FairnessQueue DRR, SwarmDispatcher, BlueprintManager, EventBus, Planner DAG, SubAgentEngine, PTC VM, PermissionManager
02 Model Intelligence	SS-10 → SS-14	ExecutionLayer, ParamConverter pivot↔wire, SmartLayer, OAuth PKCE, Voice (Live/STT/TTS)
03 Gateways & IPC	SS-15 → SS-17	Universal TransportInterface, TuiServer WS IPC, CLI Auth Wizard
04 Memory & Cognition	SS-18 → SS-20	Multi-Tier Memory L1/L2, MAPLE Ebbinghaus, Local HNSW Media DB
05 Runtime Safety	SS-21 → SS-26	VIGIL + Ralph, Tiered Context, Hash-Anchored Edit (FNV-1a Myers), AST Tree-Sitter, Plugin Pipeline, SafeFs

---

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.

Step	Harness Action	Key Code
1	Normalize ingress	TransportInterface → NormalizedMessage (src/core/transport/)
2	Schedule fairly	FairnessQueue.ts DRR + VIP sub-queues
3	Hydrate context	tieredContextLoader.ts + ContextWindowService.ts with Ebbinghaus 0.4·e^{-t/τ}
4	Route model	SmartLayer.ts → ExecutionLayer.ts (8 adapters, zero-429)
5	ReAct loop ×10	BotCore.ts + SubAgentEngine.ts (fork/fresh)
6	Execute tools	PTC ProgrammaticExecutor.ts in vm + Acorn validation
7	Guard	VIGIL pre-action + Ralph post-audit + λ=(cost/budget)^4
8	Persist	workingMemory.ts (Redis) + SemanticMemory.ts (pgvector HNSW)
9	Deliver	Transport.sendUniversalResponse() to source channel

---

Providers

The two-layer Smart Router coordinates 8 native adapter families and 22+ dynamic endpoints via a decoupled pivot. Layer 1 executes resilient stateful dispatch (6-window circuit breakers, P50 latency scoring, zero-429 rotation, SSE stream lock); Layer 0 manages stateless wire transformation (ProtocolFamily $\times$ HeaderFamily, reasoning budgets, typed errors).

Provider / Family	Implementation	Wire Protocol	Key Capabilities	Technical Features
OpenAI	Native (openai.ts)	openai-compatible (/v1/chat/completions)	Chat, Tool Calling, Vision, Reasoning Effort	Native max_completion_tokens and reasoning_effort handling, embeddings
Google Gemini	Native (gemini.ts)	gemini-native (generateContent)	Multimodal (Text, Image, Audio), Thinking Budget	Multipart structure, thought_signature preservation, systemInstruction
Anthropic Claude	Native (anthropic.ts)	anthropic-compatible (/v1/messages)	Extended Thinking, Tool Calling, Prompt Caching	Root system extraction, input_schema map, thinking budget bounds check
Groq Cloud	Native (groq.ts)	openai-compatible (/openai/v1)	Ultra-fast LPU, Tool Calling, Server Tools	Groq Compound executed_tools, usage_breakdown, header versioning
Cohere	Native (cohere.ts)	cohere-v2 (/v2/chat)	Structured Content, Tool Calling	Top-level system separation, typed content chunks, usage normalization
Cloudflare AI	Native (cloudflare.ts)	cloudflare-v1 (/ai/v1/chat/completions)	Serverless Inference & Tool Calling	Composite key account_id:api_token, { result } unwrapping, array errors
Hugging Face	Native (huggingface.ts)	openai-compatible (router.huggingface.co)	Open-Source Hub Models	Official SDK routing wrapper, autonomous credentials init, 429 handler
Modal	Native (modal.ts)	openai-compatible ({appUrl}/v1)	Custom GPU Serverless Containers	Dynamic base URL from model ID, 120s extended timeout for cold starts
OAuth Specializations	Headless (codex.ts, antigravity.ts)	Direct SSE / Cloud Code REST API	OAuth2 PKCE / Local OAuth Session	Token refresh (<300s), Clearcut telemetry simulation, TLS impersonation
Dynamic Providers	Generic (GenericProviderAdapter.ts)	openai-compatible / standard-token	22+ Ecosystem Providers (Mistral, NIM, etc.)	Tool ID 9-char sanitization, reasoning_content relay, passthrough options

---

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)

# 77 suites — 834 unit tests
npm run test:unit

# Fast local verification gate (build + fast lint + unit tests)
npm run build && npm run lint:fast && npm run test:unit

# Full local verification gate (build + lints + all tests + audit)
npm run build && npm run lint:fast && npm run lint:arch && npm run test:unit && npm run test:integration && npm audit

---

Project Structure

---

Validation

Command	Purpose	Gate
npm run build	TypeScript 7.0.2 tsc --noEmit	0 errors on 334 files
npm run lint:fast	Oxlint, 96 rules, 4 threads	0 warnings
npm run lint:arch	dependency-cruiser boundaries	0 violations
npm run test:unit	Jest, 77 suites	834 / 834 passing
npm run test:integration	5 suites	34 / 34 passing
npm audit	Known CVE vulnerability audit	0 vulnerabilities

---

Security

See SECURITY.md.