# A stale-proof shared memory for coding agents

> Source: <https://github.com/Hivemind-OSS/Hivemind>
> Published: 2026-07-18 05:36:28+00:00

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:

| Tool | Purpose |
|---|---|
`hive_recall(query)` |
Dense recall behind the abstention gate. Returns reference context (or abstains) with each hit's `trust` , `ts` , `polarity` , `kind` , and `anchor` . |
`hive_capture(text)` |
Record a durable insight. Lands quarantined; served only after fleet demand or a verified change outcome promotes it. |
`hive_write(text, approved_by=…)` |
Human-vouched memory served immediately as `established` . `replaces=<id>` supersedes an existing one. |
`hive_supersede(loser, winner, approved_by=…)` |
Human-vouched: retire one memory in favor of another. Nothing new is written. |
`hive_prune(episode_id, approved_by=…)` |
Human-vouched: retire an incorrect or misleading memory with no replacement (it stays in the audit ledger). |
`hive_flag(a, b, kind)` |
Advisory only: record that two memories conflict or one supersedes the other, for a human to resolve. Retires nothing. |
`hive_outcome(helped=[…], hurt=[…])` |
Log which recalled memories helped or hurt the task; records evidence only — changes no trust. |
`hive_health(...)` |
Liveness/identity snapshot; `include_trends=true` adds convergence KPIs, `include_gaps=true` the demand-gap report, `include_conflicts=true` the contested-memory worklist; further flags: `suspect_consensus` , `stale_suspects` , `census_health` , `meta_versions` , `onboarding` (the full install payload). |

**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** rather than the raw commands above — it carries the bounded health-wait, the boot failure modes, and the schema-refusal recovery;

[skill](/Hivemind-OSS/Hivemind/blob/master/skills/hive-bringup/SKILL.md)`hive-bringup`

**then registers agents & teammates.**

`hive-connect-team`

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 for the complete, self-contained explanation of how
agents use the memory;

`llms-full.txt`

**is the short link index to every project doc.**

`llms.txt`

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
skill; knob table + details:

`hive-connect-repo`

**.**

[HIVE-ADMIN.md §4](/Hivemind-OSS/Hivemind/blob/master/HIVE-ADMIN.md)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,
— 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

`hive-edge`

**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](https://huggingface.co/Qwen/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](https://www.apache.org/licenses/LICENSE-2.0); the full text and attribution travel with this repository in

[and](/Hivemind-OSS/Hivemind/blob/master/THIRD_PARTY_NOTICES.md)

`THIRD_PARTY_NOTICES.md`

[.](/Hivemind-OSS/Hivemind/blob/master/LICENSES/Qwen3-Embedding-0.6B-Apache-2.0.txt)

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