# hive-agi/hive-mcp architecture

> Architecture diagram of the GitHub repository hive-agi/hive-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hive-agi/hive-mcp
- Repository: https://github.com/hive-agi/hive-mcp

## Overview

hive-mcp is an MCP backend for AI coding agents, centered on persistent, project-scoped memory and session continuity. The documented user workflow is to catch up on project context, work with memory, knowledge-graph and Kanban tools, then wrap up by crystallizing learnings; `multi` can batch wrap-up actions. The architecture also includes agent execution, workflow automation, multi-agent coordination, extensions and optional integrations. Several relationships below are documented in the README; where sampled source did not establish wiring, edges are marked dashed with no evidence path.

Main entry points: [`src/hive_mcp/server/routes.clj`](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/server/routes.clj) (Tool routes), [`src/hive_mcp/tools/memory/crud/query.clj`](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/tools/memory/crud/query.clj) (Memory tools), [`src/hive_mcp/agent/budget_router.clj`](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/budget_router.clj) (Agent execution), [`src/hive_mcp/events/handlers.clj`](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/events/handlers.clj) (Event handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_routes["Tool routes<br/>[routes.clj]"]
  node_async["Async tasks<br/>[async_tasks.clj]"]
  node_multi["Batch tools<br/>[batch.clj]"]
end

subgraph group_continuity["Session continuity"]
  node_memory["Memory tools<br/>[query.clj]"]
  node_embedding["Embedding service<br/>[service.clj]"]
  node_crystal["Session wrap<br/>[pipeline.clj]"]
  node_catchup["Catch-up workflow"]
  node_kg[("Knowledge graph<br/>[connection.clj]")]
  node_kanban["Kanban tools<br/>[query.clj]"]
end

subgraph group_agents["Agent runtime"]
  node_agent["Agent execution<br/>[budget_router.clj]"]
  node_provider["Model providers<br/>[openrouter.clj]"]
  node_saa["SAA orchestration<br/>[orchestrator.clj]"]
  node_workflow["Workflow engine<br/>[fsm_engine.clj]"]
  node_saa_handlers["SAA handlers<br/>[handlers.clj]"]
end

subgraph group_coordination["Coordination"]
  node_swarm["Ling coordination<br/>[coordinator.clj]"]
  node_hivemind["Hivemind messaging<br/>[messaging.clj]"]
end

subgraph group_platform["Platform services"]
  node_events["Event handlers<br/>[handlers.clj]"]
  node_nats["NATS messaging<br/>[client.clj]"]
  node_emacs["Emacs bridge<br/>[client.clj]"]
  node_extensions["Addon extensions<br/>[loader.clj]"]
end

node_user(("AI client"))

node_user -->|"calls tools"| node_routes
node_routes -.->|"dispatches"| node_memory
node_routes -.->|"dispatches"| node_kanban
node_routes -->|"queues calls"| node_async
node_user -->|"requests catch-up"| node_catchup
node_catchup -->|"reconstructs context"| node_memory
node_user -->|"requests wrap-up"| node_crystal
node_crystal -->|"crystallizes learnings"| node_memory
node_user -->|"connects knowledge"| node_kg
node_user -->|"syncs tasks"| node_kanban
node_user -->|"batches actions"| node_multi
node_memory -.->|"embeds and searches"| node_embedding
node_agent -.->|"routes requests"| node_provider
node_saa -.->|"runs workflows"| node_workflow
node_saa_handlers -.->|"handles workflow actions"| node_saa
node_swarm -.->|"coordinates agents"| node_hivemind
node_events -.->|"dispatches lifecycle"| node_swarm
node_events -.->|"notifies agents"| node_nats
node_agent -.->|"uses editor"| node_emacs
node_routes -.->|"advertises tools"| node_extensions

click node_routes "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/server/routes.clj"
click node_async "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/server/routes/async_tasks.clj"
click node_memory "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/tools/memory/crud/query.clj"
click node_embedding "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/embeddings/service.clj"
click node_crystal "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/crystal/pipeline.clj"
click node_catchup "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/workflows/catchup_session.clj"
click node_kg "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/knowledge_graph/connection.clj"
click node_kanban "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/tools/memory_kanban/query.clj"
click node_multi "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/batch.clj"
click node_agent "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/budget_router.clj"
click node_provider "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/openrouter.clj"
click node_saa "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/saa/orchestrator.clj"
click node_workflow "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/workflows/fsm_engine.clj"
click node_saa_handlers "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/workflows/saa/handlers.clj"
click node_swarm "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/swarm/coordinator.clj"
click node_hivemind "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/hivemind/messaging.clj"
click node_events "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/events/handlers.clj"
click node_nats "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/nats/client.clj"
click node_emacs "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/emacs/client.clj"
click node_extensions "https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/extensions/loader.clj"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_routes,node_async,node_multi,node_user toneBlue
class node_memory,node_embedding,node_crystal,node_catchup,node_kg,node_kanban toneAmber
class node_agent,node_provider,node_saa,node_workflow,node_saa_handlers toneMint
class node_swarm,node_hivemind toneRose
class node_events,node_nats,node_emacs,node_extensions toneIndigo
```

## Components

### MCP entry

- [Tool routes](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/server/routes.clj): `src/hive_mcp/server/routes.clj`
- [Async tasks](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/server/routes/async_tasks.clj): `src/hive_mcp/server/routes/async_tasks.clj`
- [Batch tools](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/batch.clj): `src/hive_mcp/batch.clj`

### Session continuity

- [Memory tools](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/tools/memory/crud/query.clj): `src/hive_mcp/tools/memory/crud/query.clj`
- [Embedding service](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/embeddings/service.clj): `src/hive_mcp/embeddings/service.clj`
- [Session wrap](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/crystal/pipeline.clj): `src/hive_mcp/crystal/pipeline.clj`
- [Catch-up workflow](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/workflows/catchup_session.clj): `src/hive_mcp/workflows/catchup_session.clj`
- [Knowledge graph](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/knowledge_graph/connection.clj): `src/hive_mcp/knowledge_graph/connection.clj`
- [Kanban tools](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/tools/memory_kanban/query.clj): `src/hive_mcp/tools/memory_kanban/query.clj`

### Agent runtime

- [Agent execution](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/budget_router.clj): `src/hive_mcp/agent/budget_router.clj`
- [Model providers](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/openrouter.clj): `src/hive_mcp/agent/openrouter.clj`
- [SAA orchestration](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/agent/saa/orchestrator.clj): `src/hive_mcp/agent/saa/orchestrator.clj`
- [Workflow engine](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/workflows/fsm_engine.clj): `src/hive_mcp/workflows/fsm_engine.clj`
- [SAA handlers](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/workflows/saa/handlers.clj): `src/hive_mcp/workflows/saa/handlers.clj`

### Coordination

- [Ling coordination](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/swarm/coordinator.clj): `src/hive_mcp/swarm/coordinator.clj`
- [Hivemind messaging](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/hivemind/messaging.clj): `src/hive_mcp/hivemind/messaging.clj`

### Platform services

- [Event handlers](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/events/handlers.clj): `src/hive_mcp/events/handlers.clj`
- [NATS messaging](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/nats/client.clj): `src/hive_mcp/nats/client.clj`
- [Emacs bridge](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/emacs/client.clj): `src/hive_mcp/emacs/client.clj`
- [Addon extensions](https://github.com/hive-agi/hive-mcp/blob/main/src/hive_mcp/extensions/loader.clj): `src/hive_mcp/extensions/loader.clj`

### Other components

- **AI client**

## Connections

- AI client → Tool routes: calls tools (evidence: `README.md`)
- Tool routes → Memory tools: dispatches
- Tool routes → Kanban tools: dispatches
- Tool routes → Async tasks: queues calls (evidence: `src/hive_mcp/server/routes.clj`)
- AI client → Catch-up workflow: requests catch-up (evidence: `README.md`)
- Catch-up workflow → Memory tools: reconstructs context (evidence: `README.md`)
- AI client → Session wrap: requests wrap-up (evidence: `README.md`)
- Session wrap → Memory tools: crystallizes learnings (evidence: `README.md`)
- AI client → Knowledge graph: connects knowledge (evidence: `README.md`)
- AI client → Kanban tools: syncs tasks (evidence: `README.md`)
- AI client → Batch tools: batches actions (evidence: `README.md`)
- Memory tools → Embedding service: embeds and searches
- Agent execution → Model providers: routes requests
- SAA orchestration → Workflow engine: runs workflows
- SAA handlers → SAA orchestration: handles workflow actions
- Ling coordination → Hivemind messaging: coordinates agents
- Event handlers → Ling coordination: dispatches lifecycle
- Event handlers → NATS messaging: notifies agents
- Agent execution → Emacs bridge: uses editor
- Tool routes → Addon extensions: advertises tools
