Hivemind

hivemind

The open memory layer for collective agent awareness.

Vendor-neutral, open-source MCP service for three-tier agent memory: short · mid · long.

Agents from any MCP-capable runtime notice what others are doing, inherit what others have learned, and understand complex projects together.

[](#-concept) [](#-license) [](https://github.com/Lesur-ai/hivemind/actions/workflows/ci.yml) [](#-license) [](#-prerequisites)

Français · [README.fr.md](README.fr.md)

---

📋 Table of Contents

• [Concept](#-concept)
• [Project Mesh](#project-mesh)
• [What Hivemind does NOT claim (V1)](#-what-hivemind-does-not-claim-v1)
• [Architecture](#-architecture)
• [Prerequisites](#-prerequisites)
• [Installation](#-installation)
• [Configuration](#-configuration)
• [Getting Started](#-getting-started)
• [MCP Tools](#-mcp-tools)
• [Long Tier — Ontology / Knowledge Graph](#-long-tier--ontology--knowledge-graph)
• [Web Interface](#-web-interface)
• [MCP Integration](#-mcp-integration)
• [CLI and Shell](#-cli-and-shell)
• [Tests](#-tests)
• [Security](#-security)
• [Project Structure](#-project-structure)
• [Troubleshooting](#-troubleshooting)
• [Contributing](#-contributing)
• [Documentation map](#-documentation-map)

---

🎯 Concept

Hivemind is the open-source MCP (Model Context Protocol) service that gives AI agents a vendor-neutral shared memory across three horizons — short, mid, and long — plus Project Mesh, its project-level synchronization feature: several agents and teams can share one logical project memory space, and administrators can opt into the implemented Mesh Sync V1 federation flow through the capability-gated admin console — see [Project Mesh](#project-mesh) for its exact full-mesh all-ACK boundary.

Hivemind turns isolated agent context into a shared space where agents notice what others are doing, inherit what others have learned, and understand complex projects together.

Markdown memory files are a good primitive, but by themselves they become islands: one agent writes a .md bank, another agent or vendor starts from a different context, and the project owner becomes the integration layer. Hivemind makes the space the owner of memory instead of any one assistant, IDE, model provider, or prompt history. If you move from one MCP-capable agent to another, the accumulated project context remains in your Hivemind storage and governance boundary.

Three memory horizons

| Horizon | Was | What it holds | Aha moment | | --- | --- | --- | --- | | short | live_* | Append-only live notes: observations, decisions, todos — immediate working context, visible across the space. | Notice — an agent changes course because it sees another agent's current work. | | mid | bank_* | The consolidated Markdown memory bank: rules, synthesis, project context. The structured working memory other agents inherit. | Inherit — an agent recovers a rule or method left by another agent, no manual prompt. | | long | graph_* | The ontology / knowledge-graph tier: derived associative recall, conceptual links built by the collective process. | Understand — an agent retrieves logical links across the collective knowledge. |

The historical live_* / bank_* / graph_* tool names map one-to-one onto short_* / mid_* / long_* and remain callable as compatibility aliases. See [Compatibility aliases](#compatibility-aliases).

Project Mesh

Beyond a single server, Project Mesh is Hivemind's project-level synchronization feature. In V1 it ships in two clearly separated stages:

• Available today — agent-level sharing. Multiple teams, open-source

contributors, and agent fleets connect their own MCP-capable runtimes to one unified space_id on a Hivemind deployment — one space owns its short notes, mid bank, long projection, and Project Mesh coordination state.

• Available as opt-in instance federation. Two administrators pair a blank

target in three actions: create one opaque, one-time invitation (valid for 3,600 seconds), paste and accept it on the target, then verify and approve it at the source. The signed peer exchange performs the pending membership transition, bounded bootstrap import, final ACK, and activation; post-mutation faults remain in explicit recovery rather than rolling back. This V1 pairing flow provisions exactly a two-node mesh from a source whose space has one active member. It refuses a source that already has more than one active member; adding a third node through this workflow is not supported in V1. After bootstrap, the two peers operate symmetrically. Operators use the capability-gated /admin #/mesh routes. Mesh remains an admin/peer HTTP surface: the 24-tool maximum agent discovery and the complete registered MCP surface expose no mesh_* MCP tool.

The use case is software-development acceleration: several contributors can work in parallel with their own agents while shared memory, provenance, and mutation ordering stay inside the project boundary. See [docs/PROJECT_MESH.md](docs/PROJECT_MESH.md) for the canonical vocabulary.

> Project Mesh's Mesh Sync V1 protocol is conservative by design: > full-mesh all-ACK, not quorum. See [What Hivemind does NOT claim (V1)](#-what-hivemind-does-not-claim-v1) > for the exact boundary between what runs today and what is later work.

Vendor-neutral ownership

Hivemind's multi-agent promise is also a multi-vendor promise:

| Without Hivemind | With Hivemind | | --- | --- | | Markdown memories live as isolated files beside each agent or tool. | short, mid, and long memory live in one governed Hivemind space. | | Switching agents often means re-prompting, copying context, or trusting vendor history. | Any MCP-capable agent can read and write through scoped tokens. | | Project knowledge drifts into vendor-specific sessions. | Memory persists in operator-controlled storage, protecting continuity, ownership, and project IP. |

Why three horizons?

One level is never enough:

• short alone is ephemeral — it scrolls away as the project moves.
• long alone is too heavy for quick daily notes.
• mid is the structured bridge: agents write fast (short),

consolidate into a durable bank (mid), and capitalize knowledge into an ontology-backed graph (long).

This shared-memory architecture follows the multi-agent framework in Tran et al., 2025 — Multi-Agent Collaboration Mechanisms: A Survey of LLMs, which identifies a shared environment and shared memory as fundamental components for LLM agents to coordinate, rather than operate as isolated algorithms.

---

🚫 What Hivemind does NOT claim (V1)

Hivemind is positioned honestly. The following are not current behavior. A later phase may revisit each, but until then they are not implemented and must not be assumed. This section is the public mirror of [docs/POSITIONING.md](docs/POSITIONING.md), the canonical non-claims guardrail, and is fenced with HTML-comment sentinels so an automated release-doc lint can detect it deterministically.

Hivemind V1 does NOT claim:

• quorum consensus — Project Mesh V1 / Mesh Sync V1 is full-mesh all-ACK,

not a quorum runtime.

• hub topology — there is no central hub; all peers are equivalent under

Mesh Sync V1.

• permanent master / leader runtime — no node holds permanent leadership,

and there is no leader-election path.

• offline-first CRDT merge — Hivemind V1 is not a CRDT system and does not

attempt offline-first conflict-free merge.

• merging two already-populated spaces — V1 does not merge two spaces that

each already carry state; there is no two-populated-space reconciliation path.

• parallel collective consolidation — mid-tier consolidation is

serialized per space; there is no parallel collective consolidation across agents.

• multi-tenant behavior — the per-token space_ids allowlist is the

only isolation primitive. There is no tenant object, no row-level security, and no per-tenant bucket isolation in the open-source edition. space_ids is an allowlist, not tenancy; for tenancy, see the [downstream extension seams](docs/EXTENSION_POINTS.md) (ADR-0003).

Additionally:

• long memory is never authoritative. The long ontology /

knowledge-graph tier is a derived projection only. It is never the source of commit validity, rollback, audit, tombstones, watermarks, or recovery, and no long state sits in the commit path (ADR-0010).

• **backup_restore over a shared Project Mesh space is refused by default,

forward-forcing only with explicit operator confirmation. Restoring over a shared / unsafe / corrupted Hivemind space (read-only detection via hive_status_label, ADR-0008) is refused by default; corrupted critical state, a missing local NodeIdentity (orphan node), or a backup whose bank_version is strictly greater than the live pointer are all refused fail-closed with zero mutation. With operator-confirmed unsafe_recovery=True, the restore runs the field-by-field forward-forcing choreography of ADR-0014 (Accepted)**: it stages the backup bank via CommitRuntime, forces membership_epoch and term strictly forward to max(live, backup)+1, unions live and backup tombstones, drops the pending queue, purges acks/, prunes watermarks/ to the post-bump MembershipView, publishes a forward BankCommit through assert_commit_allowed() (single authorisation point, ADR-0011) at pointer+1, emits UNSAFE_RECOVERY_RESTORED + RESYNC_REQUIRED audit events under {space}/_hivemind/events/, and marks the node HiveNodeStatus.RESYNC_REQUIRED until re-bootstrap. See the public [migration and recovery guide](docs/MIGRATIONLIVEGRAPHTOHIVEMIND.md#6-shared-space-restore-caveat) (ADR-0014). For the single-instance, non-shared (local_only / not_a_space) case backup_restore is unchanged — byte-for-byte passthrough.

"Collective awareness" and "collective consciousness" are positioning language, not literal claims — Hivemind makes no claim of AGI, sentience, or consciousness.

---

🏗️ Architecture

     Agent Cline        Agent Claude        Agent X
          │                   │                │
          └────────┬──────────┘                │
                   │                           │
                   ▼  MCP Protocol (Streamable HTTP)  ▼
          ┌────────────────────────────────────────┐
          │   WAF (Caddy + Coraza CRS)             │
          │   Rate Limiting • TLS • OWASP CRS      │
          └────────────┬───────────────────────────┘
                       │
          ┌────────────┴───────────────────┐
          │   Hivemind MCP service         │
          │   short · mid · long           │
          │   Project Mesh sync state      │
          │   Auth Bearer • consolidation  │
          └──────┬──────────┬──────┬───────┘
                 │          │      │
          ┌──────┴──┐  ┌────┴───┐  │
          │   S3    │  │  LLM   │  │  MCP Streamable HTTP
          │ durable │  │ (mid   │  │  (internal long-engine binding)
          │  store  │  │ consol)│  │
          └─────────┘  └────────┘  │
                       ┌───────────┴────────────┐
                       │  long-tier engine      │
                       │  ontology / knowledge  │
                       │  graph (derived only)  │
                       └────────────────────────┘

Protocol stack: S3 + LLM for authoritative short/mid and Project Mesh state. Complete Hivemind product: includes the mandatory long ontology / knowledge-graph engine bound internally to the space. It is a derived projection, outside the commit path — see [Long Tier](#-long-tier--ontology--knowledge-graph).

> The WAF profile and the embedded long runtime ship in the default compose > stack ([docker-compose.yml](docker-compose.yml)); the S3 backend and the LLM > provider are operator-supplied via .env. Concrete endpoints shown in > examples are examples, not defaults.

---

📦 Prerequisites

• Docker >= 24.0 + Docker Compose >= 2.17.0 (up --wait is used)
• Python 3.11+ and uv (for local CLI/tests)
• A compatible S3 storage (Dell ECS, AWS, MinIO)
• An OpenAI-API-compatible LLM (for mid consolidation and long

extraction, embeddings, and semantic queries)

• No separate graph backend or graph token: Graph Memory + Neo4j + Qdrant are

embedded in the default compose stack (ADR-0019). The embedded runtime still uses the configured LLM API for long ingestion and queries.

---

🚀 Installation

> The default docker compose up -d brings up the complete Hivemind > product: WAF, the Hivemind MCP service, and the embedded long runtime > (Graph Memory + Neo4j + Qdrant) on the internal Docker network (ADR-0019). > A networkless one-shot initializer prepares the local secret volume, then > Hivemind durably creates/registers its scoped internal credential before > readiness; persistence or revocation failures stop startup. > Each product space binds to the embedded long engine automatically on its > first long write (long_push) — there is no separate backend to provision > and no manual bind step.

> Migrating from separate Live Memory + Graph Memory services to a single > Hivemind deployment? Follow the English > [space-by-space migration playbook](docs/MIGRATIONLIVEGRAPHTOHIVEMIND.md) > (FR: [migration guide](docs/MIGRATIONLIVEGRAPHTOHIVEMIND.fr.md)). For > new or migrated agents, use the vendor-neutral > [unified agent memory setup](docs/AGENTMEMORYSETUP.md), including the > requirement for one new Hivemind token per agent identity.

1. Clone the repository

git clone https://github.com/Lesur-ai/hivemind.git
cd hivemind

2. Create a local development environment

python scripts/configure_dev_env.py

The helper creates .env with mode 0600, random bootstrap/MinIO/Neo4j credentials, sigv4, and Mesh disabled for a deliberate single-node local evaluation. It refuses to overwrite an existing file and never prints the generated secrets. Before testing mid or long, configure LLMAAS_API_URL, LLMAAS_API_KEY, LLMAAS_MODEL, LLMAAS_EMBEDDING_MODEL, and the embedding model's exact LLMAAS_EMBEDDING_DIMENSIONS. The provider must expose compatible /chat/completions and /embeddings endpoints; the model names shipped in the template are examples, not portable defaults. Production operators must instead copy .env.example, provide their own S3 and secrets, and configure a complete Mesh identity when enabling Mesh.

3a. Docker Start (recommended)

# Build images, including local MinIO from the dev profile
docker compose --profile dev build

# Start the full default stack
# (WAF + secret initializer + Hivemind + embedded Graph Memory + Neo4j + Qdrant)
docker compose --profile dev up -d --wait

# Check status
docker compose ps

# Health check
curl -s http://localhost:8080/health

3b. Local Start (development)

Direct host starts do not run the Compose volume initializer. Set a stable, non-empty LONG_EMBEDDED_TOKEN in .env, especially on macOS, or configure a Linux-local secret path that satisfies the 0700/0600 contract documented in [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md#embedded-credential-lifecycle-and-repair).

# Create the project environment and install locked development dependencies
uv sync --locked --dev

# Run server
uv run python -m live_mem

> Note: the source package is still live_mem (the imported engine). The > public short/mid/long MCP grammar is an additive naming layer over the > same code; renaming the Python package is later work, not a behavior > change.

4. Use the bundled CLI

uv run

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Lesur-ai](https://github.com/Lesur-ai)
- **Source:** [Lesur-ai/hivemind](https://github.com/Lesur-ai/hivemind)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.