# 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](https://github.com/hive-agi/hive-mcp) | AGPL-3.0 | The host — memory, KG, swarm, MCP surface |
| [hive-mcp-cli](https://github.com/hive-agi/hive-mcp-cli) | MIT | Guided installer and setup |
| [lsp-mcp](https://github.com/hive-agi/lsp-mcp) | MIT | Clojure-LSP bridge addon |
| [basic-tools-mcp](https://github.com/hive-agi/basic-tools-mcp) | MIT | File read/write/glob/grep addon |
| [bb-mcp](https://github.com/hive-agi/bb-mcp) | MIT | Lightweight Babashka MCP wrapper |
| [hive-dsl](https://github.com/hive-agi/hive-dsl) | MIT | Result monad + DSL verb compiler |
| [hive-test](https://github.com/hive-agi/hive-test) | MIT | Test utilities for addons |
| [hive-connectors](https://github.com/hive-agi/hive-connectors) | MIT | GitHub, Slack, Linear integrations |
| [olympus-web-ui](https://github.com/hive-agi/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.