{"slug": "a-stale-proof-shared-memory-for-coding-agents", "title": "A stale-proof shared memory for coding agents", "summary": "Hivemind, a self-hosted MCP server, provides a stale-proof episodic memory for coding agents, allowing them to share learned insights across a single codebase. The system uses a conservative recall mechanism with an abstention gate and a tiered trust system where memories must be promoted through quarantine, provisional, and established stages, with only human-approved writes reaching the highest trust level. Designed for solo developers and small teams, it runs as a single Docker container with an offline embedder and offers eight tools for memory management.", "body_md": "A stale-proof, stigmergic **episodic memory** for a fleet of coding agents working one codebase. Hivemind\nruns as a single self-hosted **MCP server** that every agent connects to; what one agent\nlearns, the others can recall. It is built for **solo devs and small teams** — single-tenant,\nsingle-host, one SQLite store.\n\nRecall is deliberately conservative: a query is embedded, matched by dense cosine similarity,\nand passed through an **absolute-relevance abstention gate** — when the top match does not\nclear an absolute similarity floor, Hivemind returns nothing rather than guess. Memories enter **quarantined**\nvia `hive_capture`\n\nand become servable only once independent fleet demand or a verified change outcome promotes them\n(`provisional`\n\n); the trusted `established`\n\ntier is reached **only** by an explicit\nhuman-approved `hive_write`\n\n. Unused memories decay on a TTL. Nothing is auto-trusted, and the\nstore never silently migrates across schema generations.\n\nA connected agent gets exactly eight tools:\n\n| Tool | Purpose |\n|---|---|\n`hive_recall(query)` |\nDense recall behind the abstention gate. Returns reference context (or abstains) with each hit's `trust` , `ts` , `polarity` , `kind` , and `anchor` . |\n`hive_capture(text)` |\nRecord a durable insight. Lands quarantined; served only after fleet demand or a verified change outcome promotes it. |\n`hive_write(text, approved_by=…)` |\nHuman-vouched memory served immediately as `established` . `replaces=<id>` supersedes an existing one. |\n`hive_supersede(loser, winner, approved_by=…)` |\nHuman-vouched: retire one memory in favor of another. Nothing new is written. |\n`hive_prune(episode_id, approved_by=…)` |\nHuman-vouched: retire an incorrect or misleading memory with no replacement (it stays in the audit ledger). |\n`hive_flag(a, b, kind)` |\nAdvisory only: record that two memories conflict or one supersedes the other, for a human to resolve. Retires nothing. |\n`hive_outcome(helped=[…], hurt=[…])` |\nLog which recalled memories helped or hurt the task; records evidence only — changes no trust. |\n`hive_health(...)` |\nLiveness/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). |\n\n**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`\n\n)).**Python 3.11+** on the host — to run the`hive`\n\noperator CLI (it drives`docker compose`\n\n).\n\n```\ngit clone https://github.com/Hivemind-OSS/Hivemind.git hivemind && cd hivemind\npip install -e .          # installs the `hive` command (venv on PEP-668 systems; uninstalled: python3 -m hive.tools.cli)\ncp .env.example .env      # persist the store across restarts (sets HIVE_STORE__DB_PATH)\nhive up                   # build + start; blocks until the daemon is healthy\n```\n\n`hive up`\n\nis zero-config to boot, but **the store defaults to /data/shared.db in the hive-data volume — persistent;\nonly an explicit HIVE_STORE__DB_PATH=:memory: boots ephemeral, losing all memory on restart.** Copy\n\n`.env.example`\n\nto `.env`\n\n(above) to persist into the\n`hive-data`\n\nvolume via `HIVE_STORE__DB_PATH=/data/shared.db`\n\n; an ephemeral boot WARNs loudly and\n`hive_health`\n\nreports `store_ephemeral`\n\n. **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;\n\n[skill](/Hivemind-OSS/Hivemind/blob/master/skills/hive-bringup/SKILL.md)`hive-bringup`\n\n**then registers agents & teammates.**\n\n`hive-connect-team`\n\nThe daemon serves MCP over **two\ndoors**: a tokenless **loopback** door on **127.0.0.1:8765** for local agents, and a\ntoken-required **tunnel** door for remote teammates (compose-internal, never host-published).\nIdentity is per-agent-session — every connection gets its own identity automatically (the\nserver-minted `Mcp-Session-Id`\n\n, or an explicit `X-Hive-Agent-Id`\n\nfor readable provenance), so a\nfleet of K agents behaves the same whether 1 or N engineers run it. The token only\nauthenticates the tunnel door — it is never the identity.\n\nConnect a **local** agent (no token needed — the loopback door is tokenless):\n\n```\nhive connect              # prints the ready-made tokenless `claude mcp add …` line\nclaude mcp add --transport http hive http://localhost:8765/mcp\n```\n\nFor a **remote** teammate, mint a seat token (the tunnel door authenticates with it):\n\n```\nhive token alice-laptop   # prints the token ONCE — hand it over via a secret manager\nclaude mcp add --transport http hive https://<your-domain>/mcp \\\n  --header \"Authorization: Bearer <seat-token>\"   # replace <seat-token> with the seat's token\n```\n\nFrom there onboarding is automatic and server-side: at connect the server delivers its usage\ncontract through the MCP `initialize`\n\ninstructions (every client surfaces them) — recall-first,\ncapture-by-default, and the per-agent-session identity model. **Nothing is\nautomatically written into a rules file at connect** — installing the optional persistence block\ninto your project's rules file is an agent-driven step via `hive_health(include_onboarding=true)`\n\n. On **Claude Code only**, `hive_health(include_onboarding=true)`\n\nadditionally\nserves optional lifecycle-hook nudges you can merge into `.claude/settings.json`\n\n.\n\nRead for the complete, self-contained explanation of how\nagents use the memory;\n\n`llms-full.txt`\n\n**is the short link index to every project doc.**\n\n`llms.txt`\n\nAll config has safe code defaults in `hive/app/config.py`\n\nand is applied **only at boot** (a\nrestart — there is no live reload). To override a knob, copy `.env.example`\n\nto `.env`\n\n, set the\n`HIVE_<GROUP>__<FIELD>`\n\nkey, and run `hive up`\n\n. Out-of-range values fail boot loudly rather than\nsilently clamping.\n\n**Two doors** (auth is a property of the listening socket, not a config knob):\n\n**Loopback door**(`127.0.0.1:8765`\n\n, host-published) —**tokenless**, for local agents on the host. Identity is the per-session`X-Hive-Agent-Id`\n\n(or the server-minted`Mcp-Session-Id`\n\n), else the`local`\n\nbucket.**Tunnel door**(compose-internal`8766`\n\n, ngrok-forwarded) —**token-required**; the only remote-reachable door. The bearer token authenticates; it is never the identity.\n\nThere is no `HIVE_AUTH__MODE`\n\nswitch — delete any leftover one from `.env`\n\n(it is ignored).\n\n**Automatic census feed (optional).** Set `HIVE_SYNC__REPO_URL`\n\n(plus `HIVE_SYNC__TOKEN`\n\nfor a\nprivate remote) and the server itself mirrors the repo and feeds every landing on the tracked\nbranch into the change-outcome evidence ledger — detect-only, fail-open, byte-inert when unset;\nnothing is wired per repo or per device. Arm and test it with the runnable\nskill; knob table + details:\n\n`hive-connect-repo`\n\n**.**\n\n[HIVE-ADMIN.md §4](/Hivemind-OSS/Hivemind/blob/master/HIVE-ADMIN.md)Loopback never leaves the host, so open exactly one door:\n\n**Tunnel**— a free ngrok account: set`NGROK_AUTHTOKEN`\n\n+`NGROK_DOMAIN`\n\nin`.env`\n\n, then`hive up --tunnel`\n\n. TLS terminates at the ngrok edge, so the seat token is encrypted in transit.**SSH**—`ssh -NL 8765:localhost:8765 you@host`\n\n, then the localhost registration line works as-is.\n\nNever publish `0.0.0.0:8765`\n\n— a bearer token over plain LAN HTTP is cleartext.\n\n`hive ui`\n\n(loopback operator dashboard in the browser — live status, seat mint/revoke, backup,\nnon-blocking start/stop, tunnel activate/deactivate, restore from an in-volume backup behind a\ntyped confirm, log tail; no reset) / `hive status`\n\n/ `logs`\n\n/ `tokens`\n\n/ `revoke <seat>`\n\n/\n`backup`\n\n(manual snapshot) / `ingest <receipt.json>`\n\n(manually feed an unsigned census receipt's change outcome into the evidence\nledger — the escape hatch; with `HIVE_SYNC__REPO_URL`\n\nset the server feeds itself) / `down`\n\n(stop, keep data) / `reset`\n\n(snapshot the store out of the volume, then destroy + recreate it\nempty — recoverable; typed confirm) / `restore`\n\n(replace the live store from a snapshot) / `upgrade [--ref release]`\n\n(move the server to a vetted release ref — backup-gated, auto-rollback on failure).\nA compatible release moves with `hive upgrade`\n\n; crossing a schema generation is a single `hive reset`\n\n— it saves the prior store to the host, then recreates empty; no in-place migration ships.\n\nSee ** HIVE-ADMIN.md** for the full admin & operator guide (setup, tunneling, tuning,\nKPIs).\n\nAnchor mint/verify (recall freshness, including the dependency-neighborhood `radius`\n\nadvisory) and\na persistent per-repo code graph (`hive-edge graph`\n\n) ride a companion, per-workstation CLI,\n— 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\nverify simply no-op; nothing else is affected), but the trust-lifecycle verify step depends on it.\nCensus change evidence does\n\n`hive-edge`\n\n**not**: it is computed and fed server-side (\n\n`HIVE_SYNC__REPO_URL`\n\n,\nabove), 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):\n\n```\nuv tool install git+https://github.com/Hivemind-OSS/Hive-edge@release\nuv tool update-shell   # once, so uv's tool directory is on your PATH\n```\n\nPer-device edge state (worktree-delta baselines, the per-checkout code-graph cache) lives under\n`~/.hive-edge/`\n\n(`HIVE_EDGE_HOME`\n\noverrides); it is safe to delete and regenerates. See\n** HIVE-ADMIN.md §8** for the full install/update/rollback flow.\n\nRecall is powered by [ Qwen3-Embedding-0.6B](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)\n(© Alibaba Cloud / the Qwen Team), used unmodified and baked into the image at build time. Its\nnative 1024-dim output is used directly, L2-normalized (no weight modification). The\nmodel is licensed under the\n\n[Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0); the full text and attribution travel with this repository in\n\n[and](/Hivemind-OSS/Hivemind/blob/master/THIRD_PARTY_NOTICES.md)\n\n`THIRD_PARTY_NOTICES.md`\n\n[.](/Hivemind-OSS/Hivemind/blob/master/LICENSES/Qwen3-Embedding-0.6B-Apache-2.0.txt)\n\n`LICENSES/`\n\n```\nhive/                 the server: domain core, adapters (SQLite store, embedder), MCP app, CLI\ntests/                the test suite\ncompose.yaml          the single-service stack (+ opt-in ngrok tunnel profile)\nDockerfile            the hermetically-offline server image (embedder baked at build)\nllms.txt              link index to the project docs (llmstxt.org convention)\nllms-full.txt         the complete, self-contained operating guide for agents & integrators\nHIVE-ADMIN.md         admin & operator guide\nOPERATIONS.md         long-form operations reference & the tuning evidence behind the knobs\nskills/               operator runbook-skills (bringup, connect-team, connect-repo, backup/restore, operate)\nCONTRIBUTING.md       how to contribute: the development-first branch flow and running the tests\nLICENSE               this project's license (Apache-2.0)\nTHIRD_PARTY_NOTICES.md / LICENSES/   embedding-model attribution + license (the embedder)\n```\n\nContributions are welcome. All work lands on the `development`\n\nbranch; `master`\n\nis updated\nonly through a `development → master`\n\npull request — a required check enforces that source,\nand direct pushes to `master`\n\nare rejected. See ** CONTRIBUTING.md** for the\nfull workflow and how to run the tests.", "url": "https://wpnews.pro/news/a-stale-proof-shared-memory-for-coding-agents", "canonical_source": "https://github.com/Hivemind-OSS/Hivemind", "published_at": "2026-07-18 05:36:28+00:00", "updated_at": "2026-07-18 05:51:20.478514+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-infrastructure"], "entities": ["Hivemind", "MCP", "SQLite", "Docker", "Python"], "alternates": {"html": "https://wpnews.pro/news/a-stale-proof-shared-memory-for-coding-agents", "markdown": "https://wpnews.pro/news/a-stale-proof-shared-memory-for-coding-agents.md", "text": "https://wpnews.pro/news/a-stale-proof-shared-memory-for-coding-agents.txt", "jsonld": "https://wpnews.pro/news/a-stale-proof-shared-memory-for-coding-agents.jsonld"}}