HiveMind

Peer-to-peer shared memory for AI agents. When one agent learns something, every other agent on every machine can use it too. Local-first, no cloud, no central server.

Website: hivemind.projectmentor.org · Docs: docs/ · For developers: hivemind.projectmentor.org/dev

The HiveMind dashboard, hv dash. Watch the intro video on the site.

HiveMind is a shared, append-only memory that your AI agents read and write as they work. Facts, decisions, and outcomes accumulate over time and earn trust through independent corroboration, not by an agent asserting it. Each machine holds the full memory and syncs directly with its peers over your private Tailscale network. There is no server to operate and nothing leaves your hardware.

It is not a vector database or a RAG framework. It is the memory-and-trust layer your agents share so they work together, instead of each starting from a blank slate. That is what sets it apart from Pinecone, Weaviate, LlamaIndex, LangGraph, and friends.

---

What you get

• Syncs automatically — when one agent learns something, every other agent on every machine gets it, over Tailscale, with only the differences transferred (a Merkle delta).
• Trust earned, not assumed — confidence in a fact rises only when distinct, independent agents agree. A single agent cannot inflate its own credibility, agents on one machine count for less than agents on separate machines, and only devices you have admitted count at all, so no one can mint a crowd of keys to fake agreement. Conflicts are surfaced, not silently overwritten.
• Coordinate without a coordinator — no leader, no Raft, no lock server. A conflict-free set (G-Set CRDT) over an append-only journal, so every device is equal and converges.
• Works offline — agents keep working with no connection; entries merge cleanly on reconnect.
• Fast local search — full-text search runs on your machine in milliseconds, ranked by corroboration. No round trips, no data leaving your network.
• Nothing to operate — no servers to provision, no database to manage, no cloud accounts. Any single device's journal is the complete memory; a backup is just files.
• Auditable — every fact records who wrote it and when; nothing is silently overwritten.
• Works with your agents today — Claude Code, Hermes, Claude Desktop (via MCP), and any agent that can run a shell command.

---

Install

On Android (Termux), Linux, macOS, or a WSL terminal on Windows 11, run:

curl -fsSL https://raw.githubusercontent.com/projectmentor/hive-mind/main/scripts/installer/install.sh | bash
hive-mind install

The installer will:

1. Install Tailscale (used for syncing between machines) and authenticate it
2. Install Python dependencies
3. Clone this repo to ~/projects/hive-mind
4. Ask for one input: your peer's Tailscale IP. First machine with no peers yet? Just press Enter — you can add peers later by editing .peers.json.
5. Initialise the local database
6. Install and start the sync daemon under your OS's service manager (systemd on Linux/WSL, launchd on macOS, termux-services/runit on Android)
7. Wire the Hermes memory plugin (if Hermes is installed)

Requirements

• Android (Termux), Linux (native), macOS, or Windows 11 with WSL2 (with systemd enabled). The daemon runs under each platform's supervisor: systemd on Linux/WSL, launchd on macOS, termux-services/runit on Android (plus Termux:Boot for start-on-reboot).
• Internet access (for the install and git clone)
• Tailscale only if you want multiple machines to sync. The installer sets it up for you (inside WSL on Windows; on macOS install the app or brew install tailscale). On Android Tailscale is the VPN app — install and connect it from the Play Store/F-Droid; the installer can't manage it from Termux. It is not needed on the Windows host. A single-machine setup needs no Tailscale at all — there are no peers to reach.

Android (Termux) setup notes

# In Termux (install it from F-Droid, not the Play Store build):
pkg install python git
curl -fsSL https://raw.githubusercontent.com/projectmentor/hive-mind/main/scripts/installer/install.sh | bash
hive-mind install

The installer adds termux-services (runit) to keep the daemon alive while Termux runs. For start-on-reboot, install the Termux:Boot app from F-Droid, open it once, and disable battery optimisation for Termux + Termux:Boot so Android Doze doesn't freeze the daemon. Connect the Tailscale Android app before syncing. A phone behind Tailscale's userspace VPN can't accept inbound connections, but it doesn't need to: it converges by syncing outbound every 5 minutes.

Joining an existing hive from the phone. Android has no tailscale CLI (Tailscale is the app), so the installer can't auto-discover hives on the tailnet. Instead, on a device that's already in the hive run hive-mind invite — it prints one line (that device's Tailscale address). Paste it when the phone's hive-mind install asks for a hive address. You only need one node to join; everything else syncs from there. Then admit the phone from the owner: hv group admit <phone-device-id> --principal <you>.

Enable systemd in WSL (if it isn't already)

sudo bash -c 'echo -e "[boot]\nsystemd=true" >> /etc/wsl.conf'
# Then, from a Windows terminal:
wsl --shutdown
# Reopen WSL and proceed

---

Usage

./hv remember "The payments API rate-limits at 100 req/s" --tags api,payments
./hv search "payments"
./hv decide "Use AGPL for the core" --rationale "keeps the dual-license option open" --tags licensing
./hv stats
./hv dash            # open the read-only web dashboard (facts, decisions, peers) in your browser
./hv doctor          # health check: integrity, DB, sync, hygiene, agent hooks (--fix self-heals)
./hv sync now        # manual sync to all peers

The dashboard (hv dash) is a read-only web view of your hive — searchable facts and decisions (filterable by tag) plus a live peers/health tab. It's served by the sync daemon itself, so it's reachable on localhost and across your private tailnet (open it from your phone or laptop) with nothing exposed to the public internet.

Most of the time your agents call hv for you. Full reference: docs/CLI_REFERENCE.md.

The hive-mind command

Command	Description
hive-mind install	Full device setup from scratch
hive-mind status	Show device health and peer sync state
hive-mind uninstall	Remove HiveMind from this device (--keep-hive preserves your journal + keys; --yes skips the confirmation prompt)
hive-mind update	Pull latest and restart the daemon (auto-heals after a force-push / history rewrite)
hive-mind reset	Recover a wedged install: force-align code to origin + rebuild + restart + verify. Keeps your Hive data (journal, keys, identity). -y skips the prompt.

---

How it works

• Journal (journal/YYYY-MM-DD.jsonl) — an append-only event log. This is the source of truth. Each entry carries a device id, per-node sequence, type, payload, a hash chain, and a signature. A node identifies by an Ed25519 device key (not a hostname), and entries are signed and verified on sync, so a peer cannot forge another node's identity to inflate confidence.
• SQLite (store.db) — a derived index (WAL + FTS5) rebuilt from the journal on any node.
• Merkle index — per-node chunk hashes for efficient delta sync: only missing entries move.
• Sync daemon — a stdlib HTTP server on :9876 that syncs with peers (every 5 minutes, or on demand). No leader, no central broker. The tailnet is the trust perimeter, but the daemon also caps request bodies, times out slow reads, bounds concurrent requests, and rate-limits per peer, so a single misbehaving peer can't exhaust a node.
• Capsules — share secrets (API keys, tokens) as encrypt-to-device capsules: a secret sealed so only the devices you've admitted can open it. Each recipient's key is derived from that device's signed identity, so a capsule can never be sealed to a key a device hasn't proven it holds. See hv capsule.
• Confidence model — a fact's confidence is derived from independent corroboration, never declared by the agent that wrote it. It's a governed projection: agreement across distinct devices counts most, multiple agents on one device are discounted, only owner-admitted devices count, and agreement among one principal's own machines is capped. Governance (owner, admitted devices, tunable parameters) lives in owner-signed journal entries, so every device computes the same confidence. The owner runs the membership lifecycle with hv group (admit, revoke, deny, change, purge, list). The owner key is recoverable, not a dead end: back it up off-device or escrow it in the hive (hv owner export/escrow), and hand it off to a new key by nomination or transfer (hv owner nominate/claim/transfer). If it is lost outright with no backup, admitted devices can elect a successor by quorum once the owner goes dark (hv config quorum set, then hv owner propose-election/vote); a live owner is never unseated, since any owner act (including hv owner heartbeat) resets the dead-man timer. See hv owner and docs/INTERNALS.md.

Deeper reading: docs/INTERNALS.md, docs/P2P_DESIGN.md, docs/SYNC_API.md, docs/THREAT_MODEL.md — what HiveMind defends against, and what it assumes.

Integrating an agent? See docs/AGENT_INTEGRATION.md — a runtime-agnostic spec each agent uses to wire itself to the hive (and keep itself current). One brain (hv), one spec, no hand-maintained per-agent adapters.

---

Works with your agents

• Claude Code — a skill (integrations/claude-code/) lets Claude Code read and write the hive directly.
• Hermes — if Hermes Agent is installed, the installer wires the memory plugin so every memory() call is mirrored to the hive and synced. Manual setup: hermes config set memory.provider hive-mind.
• Claude Desktop (MCP) — a local stdio MCP server (integrations/mcp/) exposes the hive to Claude Desktop, so it reads and writes your shared memory with no copy-paste.
• Any CLI agent — if it can run a shell command, it can use hv.

---

Multi-node sync

Run the installer on each machine. When prompted for peer IPs, enter the WSL Tailscale IP of the other machine (run tailscale ip -4 in WSL on that machine). Each WSL instance is its own machine on the tailnet, so use that IP, not the Windows host IP.

cd ~/projects/hive-mind
./hv sync now    # pull from all peers
./hv stats       # confirm the journals converged

Sync runs over HTTP on port 9876 and needs no SSH. If you also want to administer one node from another (run git, systemctl, or hv on a peer), that uses Tailscale SSH, which needs an accept rule in your tailnet SSH ACL. See Remote administration for the policy and the common failure modes.

---

Roadmap

• Federated hives (a colony) — separate hives (personal, team, project) that selectively share what matters, so groups pool knowledge without merging into one pool. Multiple hives form a colony.
• More platforms — iOS / thin-client nodes (Android, Linux, macOS, and WSL2 are supported today).
• Hosted relay — an optional managed tier for nodes that can't reach each other directly.

---

Contributing

The source is open to read, audit, fork, and self-host. Contributions are welcome on a best-effort, solo-maintainer basis. Please read CONTRIBUTING.md first. Code contributions require a one-time CLA, automated on your pull request.

Questions or ideas? Start a Discussion.

License

HiveMind is licensed under the GNU Affero General Public License v3.0 (see LICENSE). You are free to use, modify, and self-host it; if you run a modified version as a network service, you must make your source available under the same terms. The copyright holder (Certified Project Management, LLC, d/b/a ProjectMentor) also reserves the right to offer a separate commercial license.

Support the project

HiveMind is free and open source. If it helps you, you can help keep it alive:

• ❤️ GitHub Sponsors
• ☕ Ko-fi
• 🥤 Buy Me a Coffee

Project

Built by ProjectMentor. HiveMind by ProjectMentor, a project of Certified Project Management, LLC. Need custom development or consulting on multi-agent systems? Reach out at hello@projectmentor.org.