Skip to content

Home

Jump to bottom
Pedro Gomes Branquinho edited this page Aug 5, 2026 · 3 revisions

hive-mcp Wiki

Your AI finally remembers. Persistent, project-scoped memory with semantic search, multi-agent orchestration, and an addon architecture that never asks the core to change.

Start here

Guide Description
FOSS-Quickstart Batteries-included open-source stack — one command
Core-Engine What hive-mcp is: host, harness, and the OCP boundary
Agents-and-Skills Drop-in agent definitions and presets
Creating-Addons Scaffold and publish your own addon

All guides

Guide Description
Installation Step-by-step setup for new users
Infrastructure-Setup Docker, Ollama, OpenRouter, Chroma
Ecosystem Architecture, open source strategy, contributing
Interfaces-and-Protocols All ~49 Clojure protocols with method signatures
ADR-0007-hive-addons-architecture Why the addon architecture looks like this
Addon-Classpath-Discovery How manifests are found and loaded
Emacs-Configuration Doom Emacs and vanilla Emacs configs
Tools-Reference Tool surface and DSL verbs
Presets System prompts for ling/drone specialization
Session-Continuity catchup and wrap for session memory
Kanban Task tracking for agent sessions
Seed-Memories Bootstrap projects with pre-built knowledge
Troubleshooting Common issues and solutions

Architecture

hive-mcp is a host: a runtime that addons mount into. Your MCP client is the harness you type into; hive-mcp is the substrate it talks to — and itself a harness for the agents it spawns. Core-Engine unpacks the distinction.

┌─────────────────────────────────────────────────────────────┐
│         Claude Code / any MCP client  (your harness)        │
└──────────────────────────┬──────────────────────────────────┘
                           │  MCP protocol
┌──────────────────────────▼──────────────────────────────────┐
│  hive-mcp — THE HOST (AGPL-3.0)                             │
│                                                             │
│   Memory   ──►  Chroma (semantic) + JSON (fallback)         │
│   KG       ──►  structural edges over memory                │
│   Swarm    ──►  lings + drones, file claims, hivemind       │
│   Session  ──►  catchup / wrap rituals                      │
│                                                             │
│   protocols · registries · orchestrators · noop defaults    │
└──────────────────────────┬──────────────────────────────────┘
                           │  IAddon  (addon → core, never the reverse)
      ┌────────────────────┼────────────────────┐
      ▼                    ▼                    ▼
  :addon               :library             :addon
  (contributes         (backend: vector     (contributes
   user-facing tools)   store, terminal)     user-facing tools)

The Emacs surface is one such addon, not a requirement — hive-mcp runs headless just as well.

The tool surface

Tools are grouped into domain roots rather than a flat list. Core ships roots for memory, project, code, swarm, fs, git, emacs, preset, web, events, multi and migrate-kanban; multi routes to 21 consolidated domains in one call.

Anything an addon registers that doesn't collide with a domain name becomes a new top-level tool root automatically — no core edit, no allowlist entry, no release. A config-driven visibility gate can shrink the advertised surface without breaking callers: hidden tools stay dispatchable by name, they just leave tools/list.

See Tools-Reference.

Key features

  • Persistent memory — notes, conventions, decisions, snippets, stored locally
  • Semantic search — by meaning, via Ollama embeddings + Chroma
  • Knowledge graph — structural edges (refines, depends-on, supersedes) over memory
  • Session continuity — catchup reconstructs, wrap crystallizes
  • Multi-agent swarm — parallel workers with file claims and hivemind coordination
  • Open by extension — addons add capabilities without core changing a line

Getting started

  1. FOSS-Quickstart — one command, fully open-source stack
  2. Emacs-Configuration — optional, if you want the Emacs surface
  3. Agents-and-Skills — drop in the roles and disciplines you want
  4. Creating-Addons — extend it

Ecosystem

Repository Licence Description
hive-mcp AGPL-3.0 The host — memory, KG, swarm, MCP surface
hive-mcp-cli MIT Guided installer and setup
lsp-mcp MIT Clojure-LSP bridge addon
basic-tools-mcp MIT File read/write/glob/grep addon
bb-mcp MIT Lightweight Babashka MCP wrapper
hive-dsl MIT Result monad + DSL verb compiler
hive-test MIT Test utilities for addons
hive-connectors MIT GitHub, Slack, Linear integrations
olympus-web-ui MIT Web dashboard for swarm monitoring

Licence follows hosting: GitHub repos are MIT, hive-mcp itself is AGPL-3.0 so derivative works stay open while SaaS use remains possible. See Ecosystem for the full strategy.

Clone this wiki locally