How Hivemind gives a fleet of agents one memory.

What is Hivemind?

Hivemind is a self-hosted, offline server that gives a fleet of AI coding agents one shared episodic memory. When any agent solves a problem, the finding is captured once; every other agent can then recall it — so the fleet stops re-solving the same problem twice.

It runs as a single container on your own hardware and exposes itself over the Model Context Protocol (MCP) — the open standard for connecting AI agents to external tools and data — so it plugs into Claude, Cursor, and other MCP-speaking agents without custom glue. Nothing leaves your machine: there are no model downloads at runtime and no calls home.

The defining design choice is restraint, enforced three ways. Recall would rather return nothing than hand an agent a guess. No memory is served as settled fact until it has earned trust — mechanically or by human sign-off. And a memory about code is re-checked against that code at recall, so drift is flagged instead of silently repeated. The rest of this guide unpacks each mechanism.

How do agents coordinate without messaging each other?

Agents coordinate through stigmergy: instead of talking to one another, each one leaves durable traces in the shared memory, and later work builds on those traces automatically. It is how an ant colony finds a path without any ant giving orders.

Stigmergy is not a Hivemind invention — the term was coined in 1959 by the French biologist Pierre-Paul Grassé to describe how termites build without a blueprint, each acting on the traces left by others. Hivemind applies that same principle to a fleet of coding agents: the shared memory is the environment they read and write.

Direct agent-to-agent chatter doesn’t scale to a fleet — it needs everyone online at once, multiplies token cost, and turns coordination into a scheduling problem. Traces sidestep all of that: an agent writes down what it learned and moves on, the next reads the environment instead of a conversation, and no agent waits on another.

Concretely, one agent captures a finding (say, how authentication is handled on a particular service). Hours or days later a different agent hits the same question, recalls the trace, and continues from there. There is nothing to configure and no message bus to run — the memory is the coordination layer.

How does the abstention gate work?

Every recall is scored by dense cosine similarity, and Hivemind only serves matches at or above an absolute serve floor (written τ, tau — default 0.70). If the best match falls below the floor, the gate abstains and returns nothing — it never lowers the bar to produce an answer.

That single rule is what abstention means in practice. A retrieval system that always returns its closest match will happily hand back something loosely related and let the agent treat it as fact. Hivemind refuses: below the floor there is no answer, and an honest silence is safer than a confident guess. The gate also fails closed — an empty result, a non-finite score, or any internal error resolves to abstention, never to a served guess.

When matches do clear the floor, they come back as reference context — never as instructions — each labelled with its trust state, its recency, its do/dont polarity, and the anchor it is about — so the agent knows exactly how much weight to give it. You can raise τ to demand near-certainty or lower it to surface weaker leads; the homepage has a live gate you can drag, at the same 0.70 default the server ships.

How does a memory earn trust?

Every memory moves through four states — quarantined → provisional → established → retired. Nothing is auto-trusted: promotion to provisional happens only through independent fleet demand, and the established tier is reached only by an explicit human approval. Every transition writes an audit row.

The lifecycle is what keeps a fleet-writable store honest. Agents can capture freely because the blast radius of a bad capture is contained: it is served to no one until demand proves it out, it is labelled unverified until a human vouches for it, and if it is never used it simply expires. On the project’s adversarial trust bench, this lifecycle took the poisoned-memory serve rate from 0.92 to 0.0.

Because retirement is a set-aside rather than a delete, the store keeps a full history — you can always see what a memory used to say and why it changed. And because the serve decision re-checks state at serve time, a retired memory does not keep leaking out of a stale index.

These states are not marketing labels: they and the transitions between them are defined in the project’s source, in the trust-lifecycle module. When a release changes them, that file is the ground truth this page is kept in step with.

How does Hivemind know a memory is still true?

Memories are anchored to the code they describe (file:symbol). The companion hive-edge CLI mints a deterministic AST fingerprint of the anchored code at capture and re-verifies it against the current tree at recall — so drift is detected mechanically, not guessed at by a model.

Silent staleness is the classic failure of agent-memory systems: a memory asserts something about code that changed weeks ago, and nothing ever checks. Hivemind’s answer is to make “is this still true?” a computation:

• Anchors. A memory about code carries the file and symbol it concerns; recall returns that anchor with every hit, so the claim is always attached to a checkable location.
• Fingerprints. At capture, hive-edge derives an AST fingerprint of the anchored code — deterministic, so the same code always yields the same fingerprint. At recall it re-derives the fingerprint from your current tree and compares: a breaking mismatch — the symbol gone, or its call shape changed incompatibly — flags the hit stale; a compatible widening (a new optional parameter, an added overload) leaves it current; a comparison the checker can’t decide comes back unverifiable rather than a guess in either direction.
• The radius advisory. Verification also inspects the anchor’s dependency neighborhood: when the anchored symbol is unchanged but code around it moved, the recall carries an advisory rather than a hard drift flag.
• The evidence ledger. Post-commit and post-merge census hooks feed change outcomes into an append-only evidence ledger keyed by repo and SHA (hive ingest), so what happened to the code is recorded next to what the fleet believes about it.

None of this asks an LLM for its opinion. Verification is deterministic end to end: same code, same verdict, every time — and it costs no tokens.

Why doesn’t the store bloat?

Because usefulness is treated as a flow, not a stock: unused quarantined memories expire in 14 days and unused provisional ones in 45 (defaults), serving is gated on live demand, and a bigger store is treated as a worse store — and the hygiene that enforces all of this is mechanical, with no autonomous maintenance LLM.

Agent-memory systems tend to die of hoarding — an ever-growing graph in which recall drowns, kept “tidy” by LLM compression jobs that stall and bill. Hivemind inverts the assumption. Dilution and staleness outrun recall bandwidth as a store grows, so the design goal is a lean, high-value working set:

• TTL decay does real work. Anything unestablished that the fleet stops asking for expires on its own. Lengthening TTLs to hoard is an anti-pattern, not a feature request.
• Demand decides what serves. A memory is served because agents keep independently needing it — not because it exists. The store converges on what your fleet actually asks.
• Established is the one tier that never decays — it is deliberately human-paced. Superseding a stale established memory is the operator’s highest-leverage move, and re-verification tells you exactly which ones drifted.
• No autonomous maintenance LLM. The automated hygiene — decay, promotion, dedup at serve time, conflict detection — is all mechanical: no summarizer on a stop hook, no token bill for keeping memory current. The semantic curation on top — storing, superseding, tagging, pruning — is the agents’ deliberate work through gated tools, so upkeep is hybrid rather than a background job.

The result is one small SQLite file, and a weekly hive_health read — trends, gaps, conflicts — is enough cadence for a small team to keep it sharp.

What are the eight Hivemind tools?

Hivemind exposes eight MCP tools — not fifty. Five are open to any agent — read, contribute, and flag — and three are approver-only, reserved for the human who decides what becomes established.

The split maps directly onto the trust lifecycle: agents can propose and report all day, but promotion to established, replacement, and removal stay in human hands.

The when-to-use contract for these tools is delivered once, at connect, through the MCP initialize instructions — static and versioned, with a contract_version beacon on every result. Recall is pull-based. Nothing rewrites your agent’s system prompt per turn, so prompt caching stays intact.

The tool names, their access levels, and their input schemas live in the repository’s tool-definitions module — the same definitions your MCP client sees when it connects.

How do I install and self-host Hivemind?

Clone the repository, run pip install -e . to get the hive CLI, copy .env.example to .env to make your store config explicit, then hive up to build and start the container. When it reports healthy, run hive connect to register an agent.

Everything runs locally in one container. The open-source core has no hosted service to sign up for and no account — you own the whole stack.

After hive up reports healthy, the MCP endpoint lives at http://localhost:8765/mcp. Point your agent there with the line that hive connect prints, and it can immediately recall from and contribute to the shared memory. For remote teammates, the operator mints per-seat tokens; the tunnel door is the only remotely reachable one.

How does Hivemind stay private and offline?

Hivemind is offline by build, not by configuration: the embedding model is baked into the image, so there are no model downloads and nothing phones home. Your fleet’s entire memory is a single store file that never leaves your machine unless you move it.

Several design choices reinforce that boundary:

• One store, one truth. The whole shared memory is a single SQLite file — persisted in a Docker volume by default, with .env able to set an explicit path (see install). Back it up like any file — Hivemind takes atomic snapshots — and upgrades never touch your data without telling you.
• Two doors, set by the socket. Working solo, the server is available only on your own machine, tokenless. Bring in remote teammates and every connection is token-gated; nothing else about your host is exposed.
• Secret-scanned by default. Every memory is checked for stray API keys and passwords before it is saved. Findings log the rule that fired — never the matched bytes.
• Single-tenant by architecture. One Hivemind serves one project’s fleet, and identity is per-agent-session, minted by the server — never inferred from a directory name. Another project’s memory cannot surface here, because it is never in the same store.
• Offboarding is one command. Remove a remote seat’s access at any time; the tunnel token authenticates the connection, it is never an identity.

Because the model and the store both live inside your container, Hivemind works the same on a laptop with no network as it does on a shared box — offline is the only mode.

Which AI coding agents work with Hivemind?

Hivemind works with any agent that speaks the Model Context Protocol, including Claude and Cursor. Because it is a standard MCP server at http://localhost:8765/mcp, there is no Hivemind-specific SDK to adopt — if your agent can add an MCP server, it can use Hivemind.

That is deliberate: MCP is the shared language, so the same eight tools show up in every compatible agent, and a memory captured by one agent is instantly recallable by another running in a completely different client. At connect, the server delivers its usage contract through the standard MCP initialize instructions, so an agent learns recall-first, capture-by-default behaviour with no rules-file edit required.

Ready to try it? Get Hivemind on GitHub, see how it differs from a vector database or a typical agent-memory layer, or read the honest, direct answers on the FAQ.