# Hivemind

> The open memory layer for collective agent awareness — a vendor-neutral MCP service for shared AI-agent memory.

- **Type:** MCP server
- **Install:** `agentstack add mcp-lesur-ai-hivemind`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Lesur-ai](https://agentstack.voostack.com/s/lesur-ai)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Lesur-ai](https://github.com/Lesur-ai)
- **Source:** https://github.com/Lesur-ai/hivemind

## Install

```sh
agentstack add mcp-lesur-ai-hivemind
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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*](https://arxiv.org/abs/2501.06322),
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/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.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`](https://docs.astral.sh/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/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.md)
> (FR: [migration guide](docs/MIGRATION_LIVE_GRAPH_TO_HIVEMIND.fr.md)). For
> new or migrated agents, use the vendor-neutral
> [unified agent memory setup](docs/AGENT_MEMORY_SETUP.md), including the
> requirement for one new Hivemind token per agent identity.

### 1. Clone the repository

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

### 2. Create a local development environment

```bash
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)

```bash
# 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).

```bash
# 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

```bash
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-lesur-ai-hivemind
- Seller: https://agentstack.voostack.com/s/lesur-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.