Skip to content

Home

Jump to bottom
Pedro Gomes Branquinho edited this page Oct 1, 2026 · 7 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.

curl -fsSL https://hive-mcp.com/install.sh | sh
hive setup

Install with curl -fsSL https://hive-mcp.com/install.sh | sh then hive setup. hive setup installs bb-mcp, publishes it at ~/.local/share/hive-mcp/bb-mcp, and registers hive with your MCP clients (Claude Code, Codex) through bb-mcp. Already have bb-mcp checked out somewhere? Run <that checkout>/bb-mcp setup: wherever bb-mcp lives becomes the reference. Verify with bb-mcp setup --check.

For the rest, start Claude Code and say "help me set up the hive-mcp harness locally": the installer leaves the whole procedure behind as a skill, so the assistant drives it. Installation is the same path done by hand, and Verifying-The-Install says exactly what that one line trusts and how to check it before running it.

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
Verifying-The-Install What the one-liner trusts, what it proves, how to check it
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 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, 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: hive setup installs bb-mcp and runs bb-mcp setup
lsp-mcp MIT Clojure-LSP bridge addon
basic-tools-mcp MIT File read/write/glob/grep addon
bb-mcp MIT The standard client entry point: Babashka MCP server every client launches; bb-mcp setup registers it
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