A stale-proof, stigmergic episodic memory for a fleet of coding agents working one codebase. Hivemind runs as a single self-hosted MCP server that every agent connects to; what one agent learns, the others can recall. It is built for solo devs and small teams — single-tenant, single-host, one SQLite store.

Recall is deliberately conservative: a query is embedded, matched by dense cosine similarity, and passed through an absolute-relevance abstention gate — when the top match does not clear an absolute similarity floor, Hivemind returns nothing rather than guess. Memories enter quarantined via hive_capture and become servable only once independent fleet demand or a verified change outcome promotes them (provisional); the trusted established tier is reached only by an explicit human-approved hive_write. Unused memories decay on a TTL. Nothing is auto-trusted, and the store never silently migrates across schema generations.

A connected agent gets exactly eight tools:

• Docker + Docker Compose v2 — the server, its store, and a baked offline embedder run in one container (the image is hermetically offline; no network at runtime beyond the opt-in census sync's git fetches (HIVE_SYNC__REPO_URL)).
• Python 3.11+ on the host — to run the hive operator CLI (it drives docker compose).

git clone https://github.com/Hivemind-OSS/Hivemind.git hivemind && cd hivemind
pip install -e .          # installs the `hive` command (venv on PEP-668 systems; uninstalled: python3 -m hive.tools.cli)
cp .env.example .env      # persist the store across restarts (sets HIVE_STORE__DB_PATH)
hive up                   # build + start; blocks until the daemon is healthy

hive up is zero-config to boot, but the store defaults to /data/shared.db in the hive-data volume — persistent; only an explicit HIVE_STORE__DB_PATH=:memory: boots ephemeral, losing all memory on restart. Copy .env.example to .env (above) to persist into the hive-data volume via HIVE_STORE__DB_PATH=/data/shared.db; an ephemeral boot WARNs loudly and hive_health reports store_ephemeral. Agents should bring the server up with the runnable hive-bringup skill rather than the raw commands above — it carries the bounded health-wait, the boot failure modes, and the schema-refusal recovery; hive-connect-team then registers agents & teammates.

The daemon serves MCP over two doors: a tokenless loopback door on 127.0.0.1:8765 for local agents, and a token-required tunnel door for remote teammates (compose-internal, never host-published). Identity is per-agent-session — every connection gets its own identity automatically (the server-minted Mcp-Session-Id, or an explicit X-Hive-Agent-Id for readable provenance), so a fleet of K agents behaves the same whether 1 or N engineers run it. The token only authenticates the tunnel door — it is never the identity.

Connect a local agent (no token needed — the loopback door is tokenless):

hive connect              # prints the ready-made tokenless `claude mcp add …` line
claude mcp add --transport http hive http://localhost:8765/mcp

For a remote teammate, mint a seat token (the tunnel door authenticates with it):

hive token alice-laptop   # prints the token ONCE — hand it over via a secret manager
claude mcp add --transport http hive https://<your-domain>/mcp \
  --header "Authorization: Bearer <seat-token>"   # replace <seat-token> with the seat's token

From there onboarding is automatic and server-side: at connect the server delivers its usage contract through the MCP initialize instructions (every client surfaces them) — recall-first, capture-by-default, and the per-agent-session identity model. Nothing is automatically written into a rules file at connect — installing the optional persistence block into your project's rules file is an agent-driven step via hive_health(include_onboarding=true). On Claude Code only, hive_health(include_onboarding=true) additionally serves optional lifecycle-hook nudges you can merge into .claude/settings.json.

Read llms-full.txt for the complete, self-contained explanation of how agents use the memory; llms.txt is the short link index to every project doc.

All config has safe code defaults in hive/app/config.py and is applied only at boot (a restart — there is no live reload). To override a knob, copy .env.example to .env, set the HIVE_<GROUP>__<FIELD> key, and run hive up. Out-of-range values fail boot loudly rather than silently clamping.

Two doors (auth is a property of the listening socket, not a config knob):

• Loopback door (127.0.0.1:8765, host-published) — tokenless, for local agents on the host. Identity is the per-session X-Hive-Agent-Id (or the server-minted Mcp-Session-Id), else the local bucket.
• Tunnel door (compose-internal 8766, ngrok-forwarded) — token-required; the only remote-reachable door. The bearer token authenticates; it is never the identity.

There is no HIVE_AUTH__MODE switch — delete any leftover one from .env (it is ignored).

Automatic census feed (optional). Set HIVE_SYNC__REPO_URL (plus HIVE_SYNC__TOKEN for a private remote) and the server itself mirrors the repo and feeds every landing on the tracked branch into the change-outcome evidence ledger — detect-only, fail-open, byte-inert when unset; nothing is wired per repo or per device. Arm and test it with the runnable hive-connect-repo skill; knob table + details: HIVE-ADMIN.md §4.

Loopback never leaves the host, so open exactly one door:

• Tunnel — a free ngrok account: set NGROK_AUTHTOKEN + NGROK_DOMAIN in .env, then hive up --tunnel. TLS terminates at the ngrok edge, so the seat token is encrypted in transit.
• SSH — ssh -NL 8765:localhost:8765 you@host, then the localhost registration line works as-is.

Never publish 0.0.0.0:8765 — a bearer token over plain LAN HTTP is cleartext.

hive ui (loopback operator dashboard in the browser — live status, seat mint/revoke, backup, non-blocking start/stop, tunnel activate/deactivate, restore from an in-volume backup behind a typed confirm, log tail; no reset) / hive status / logs / tokens / revoke <seat> / backup (manual snapshot) / ingest <receipt.json> (manually feed an unsigned census receipt's change outcome into the evidence ledger — the escape hatch; with HIVE_SYNC__REPO_URL set the server feeds itself) / down (stop, keep data) / reset (snapshot the store out of the volume, then destroy + recreate it empty — recoverable; typed confirm) / restore (replace the live store from a snapshot) / upgrade [--ref release] (move the server to a vetted release ref — backup-gated, auto-rollback on failure). A compatible release moves with hive upgrade; crossing a schema generation is a single hive reset — it saves the prior store to the host, then recreates empty; no in-place migration ships.

See HIVE-ADMIN.md for the full admin & operator guide (setup, tunneling, tuning, KPIs).

Anchor mint/verify (recall freshness, including the dependency-neighborhood radius advisory) and a persistent per-repo code graph (hive-edge graph) ride a companion, per-workstation CLI, hive-edge — the server image bakes its own copy for the server-side census leg; each workstation installs its own. It is not required for the core recall/capture/write loop (absent, mint and verify simply no-op; nothing else is affected), but the trust-lifecycle verify step depends on it. Census change evidence does not: it is computed and fed server-side (HIVE_SYNC__REPO_URL, above), so there is nothing to wire per repo or per device.

You don't need to install it yourself: a connected agent checks for it during onboarding and installs or updates it automatically. To install it manually instead — uv required (the CLI's workspace engines resolve from git subdirectories via uv sources, which pip/pipx cannot read):

uv tool install git+https://github.com/Hivemind-OSS/Hive-edge@release
uv tool update-shell   # once, so uv's tool directory is on your PATH

Per-device edge state (worktree-delta baselines, the per-checkout code-graph cache) lives under ~/.hive-edge/ (HIVE_EDGE_HOME overrides); it is safe to delete and regenerates. See HIVE-ADMIN.md §8 for the full install/update/rollback flow.

Recall is powered by Qwen3-Embedding-0.6B (© Alibaba Cloud / the Qwen Team), used unmodified and baked into the image at build time. Its native 1024-dim output is used directly, L2-normalized (no weight modification). The model is licensed under the Apache License 2.0; the full text and attribution travel with this repository in THIRD_PARTY_NOTICES.md and LICENSES/.

hive/                 the server: domain core, adapters (SQLite store, embedder), MCP app, CLI
tests/                the test suite
compose.yaml          the single-service stack (+ opt-in ngrok tunnel profile)
Dockerfile            the hermetically-offline server image (embedder baked at build)
llms.txt              link index to the project docs (llmstxt.org convention)
llms-full.txt         the complete, self-contained operating guide for agents & integrators
HIVE-ADMIN.md         admin & operator guide
OPERATIONS.md         long-form operations reference & the tuning evidence behind the knobs
skills/               operator runbook-skills (bringup, connect-team, connect-repo, backup/restore, operate)
CONTRIBUTING.md       how to contribute: the development-first branch flow and running the tests
LICENSE               this project's license (Apache-2.0)
THIRD_PARTY_NOTICES.md / LICENSES/   embedding-model attribution + license (the embedder)

Contributions are welcome. All work lands on the development branch; master is updated only through a development → master pull request — a required check enforces that source, and direct pushes to master are rejected. See CONTRIBUTING.md for the full workflow and how to run the tests.