hivemind

Local shared memory and coordination for any stdio MCP agent. Guided setup registers recognized agent CLIs; other compatible clients connect manually. Keep your preferences, project context, and hard-won solutions in one local folder.

Quick start · How it works · Connect an agent · Your memory · Backups · Documentation

The idea

You finish a task with one agent. Later, another agent opens the same project and retrieves what changed, why it changed, and what still needs attention. In your next project, confirmed preferences and relevant solutions are available again.

HiveMind makes that handoff possible through shared files and a local MCP server. It gives each agent a small, relevant brief and a place to save what it learns.

HiveMind is single-device software. One Markdown vault and one SQLite database serve the agents working on that computer. There is no device-sync requirement, sync daemon, hosted memory bill, or cross-device conflict to resolve. Move to a different computer with a backup when needed; do not run two active copies of the same Hive. Existing remote connectors remain optional legacy paths, not the core product.

Now with budgeted briefs and resumable sessions: select a context budget, retrieve complete project-aware excerpts, and carry structured checkpoints between agents. The optional CLI wrapper also captures Git state when an agent exits. Explore context & sessions →

Optional code intelligence: Graphify builds a local map of code relationships. Agents query it through one bounded HiveMind tool, with no indexing model or API key. Explore local code graphs →

Optional semantic recall: a local embedding model can find a past solution even when your new question uses different words. It joins keyword search inside the existing memory tools; the vault remains plain Markdown. Explore semantic memory →

Local memory, normal agent accounts. HiveMind needs no hosting subscription or embedding service. Semantic recall is an optional local model downloaded once. Your AI agents still use their own services and account allowances. Retrieved memory uses normal context tokens.

One-command guided setup: run HiveMind from your project's CMD prompt, pick the features you want, and start working. It enrolls the project, registers the supported installed agent CLIs, and checks the MCP connection. Your feature choice is saved for the next project on this device. Set up HiveMind →

Related MCP server: Memory MCP

Quick start

You need Python 3.11+, Git, and an agent that supports stdio MCP. Guided setup can register recognized installed CLIs; other clients use the manual connection details. The first setup downloads the Python dependencies. This source repository is public, so cloning it needs no GitHub sign-in. Your personal vault and device credentials remain local and are excluded from Git.

1 · Get HiveMind and enroll your project

Open CMD in the project you want to work on and paste this single line:

(if not exist "%USERPROFILE%\HiveMind\hivemind.cmd" call git clone https://github.com/raj45681/HiveMind.git "%USERPROFILE%\HiveMind") & call "%USERPROFILE%\HiveMind\hivemind.cmd"

Already have HiveMind installed? From any project's CMD prompt:

"%USERPROFILE%\HiveMind\hivemind.cmd"

On the first interactive run, choose what to include:

Semantic recall downloads a local model; Graphify downloads an isolated dependency. HiveMind saves your semantic and Graphify choices on this device. For the next project, run the same command from that project's CMD prompt; it reuses those choices without asking again. The All option saves only the working-style answers you actually enter. Setup makes no paid agent call.

Both commands are safe to rerun. Setup enrolls the project, registers each installed CLI independently, then opens the local MCP bridge and calls hive_context without starting an AI session. The final report shows each agent as ready, skipped, or needs-action, plus the bridge check and next step. A CLI marked ready has its HiveMind entry registered and listed; restart an active agent session to load it. A skipped CLI can be installed later, then the same setup command will register it. If one CLI fails, the others are still attempted. Setup succeeds with no recognized CLI when the local bridge passes its probe; it prints the command and project-instruction path for another stdio MCP client. Choose 5 on a fresh interactive setup, or add --other-client to an explicit command. You can combine --other-client with --with-semantic and --with-graphify.

To reopen the menu and change the defaults for future projects, run this from the project you are setting up:

"%USERPROFILE%\HiveMind\hivemind.cmd" --configure

If you installed HiveMind before the guided menu was added, use --configure once to set your defaults.

Recognized CLIs need no separate skill or manual MCP configuration. Other clients need the printed stdio command in their own MCP settings. Restart any agent session that was open during setup so it can load the new bridge.

Setup checks installed bridge package versions against requirements.txt on every run and repairs missing or mismatched pins. hive.py doctor reports the required and installed versions without installing anything.

For scripts or unattended setup, add --no-prompt to use saved defaults (core only on a fresh install). --with-semantic and --with-graphify add a feature for one run without opening the menu. Add --personalize when you only want the working-style questions. Changing defaults does not uninstall an already installed model or disable Graphify in existing projects.

Or specify the project explicitly:

"%USERPROFILE%\HiveMind\hivemind.cmd" "D:\Projects\My App"

To include local Graphify code indexing (Python 3.12+, first setup downloads dependencies):

"%USERPROFILE%\HiveMind\hivemind.cmd" "D:\Projects\My App" --with-graphify

To include local semantic memory (first setup downloads an isolated model):

"%USERPROFILE%\HiveMind\hivemind.cmd" "D:\Projects\My App" --with-semantic

Once installed on the coordinator device, semantic recall works for every enrolled project through the existing memory_search and hive_context tools. No agent skill or extra MCP tool is needed. Combine both flags if you want Graphify as well. Setup, privacy and limits →

Use --tool-profile memory to expose only eight memory and session MCP tools on this device. The default full profile exposes 16 core tools, including task claims and messages, plus optional Graphify. The memory profile reduces the serialized tool schemas by about 45% in the included synthetic benchmark; exact prompt-token savings depend on the client. Override one generic client's profile with hive.py client-info PROJECT --profile memory, or run the bridge with hive.py serve --profile memory. Restart clients after changing the profile.

Run the same command for each new project on this device. Source-only graphs are rebuilt locally; preferences and handoffs stay in the same vault. Memory-only setup still works without Graphify. Supported files, limits and recovery →

PowerShell, after cloning to your home folder:

& "$HOME\HiveMind\hivemind.cmd"

Linux, from your project's folder:

git clone https://github.com/raj45681/HiveMind.git "$HOME/HiveMind" && python3 "$HOME/HiveMind/bootstrap.py"

Subsequent projects:

python3 "$HOME/HiveMind/bootstrap.py"

Linux may need its distribution's Python venv package. Windows has been tested locally; the portable code has not yet been exercised on a physical Linux device.

2 · Restart your agent session

Setup registers the hivemind MCP bridge with installed CLI adapters it recognizes. It adds a managed workflow to AGENTS.md, handles an existing AGENTS.override.md, and adds a pointer to an existing GEMINI.md.

Existing instructions are preserved and backed up. Reruns update the managed section without duplicating it. Accept normal project-trust and MCP prompts from your client. Missing CLIs are skipped. The bridge probe verifies the server itself; it cannot verify that an already-open client session has reloaded its MCP configuration.

Any stdio MCP client can join the same memory and task state. Run hive.py client-info PROJECT for their local connection command, then load the project’s AGENTS.md workflow in that client. Context and session tools accept a stable lowercase client ID; automatic registration and queued headless execution are limited to verified CLI adapters. Connect another agent →

3 · Work as usual

Agents are instructed to retrieve context before substantial work, save verified learning at milestones, and leave a handoff. You do not need to repeat “use HiveMind” for every task in an enrolled project.

This is an instruction-based workflow. Agents must follow the rules and have access to the tools. HiveMind does not silently capture every chat, guarantee model compliance, or automatically launch another agent.

Verify the handoff path

From the HiveMind folder, run this after setup or an update:

.venv\Scripts\python.exe hive.py verify

verify creates a disposable vault and Git project. It starts two separate MCP server processes, saves memory and a session checkpoint in the first, then checks that a fresh context retrieves the right project note and handoff within a 1,000 estimated-token budget. It also checks safe memory retry, project isolation, and Git drift detection. The command returns a nonzero exit code on failure and uses no paid agent/model calls. Your real vault and projects are untouched. On Linux use .venv/bin/python.

This proves the local protocol path, not that a vendor client has loaded its registration or will follow the project instructions. The onboarding report checks registration; restart the client and ask it to call hive_context to check its live session.

For a repeatable retrieval check, run .venv\Scripts\python.exe hive.py benchmark from the HiveMind folder (.venv/bin/python hive.py benchmark on Linux). It uses a disposable synthetic vault to report exact and paraphrase recall, unrelated and wrong-project results, 512/1000/1800-token context inclusion, latency, response bytes, and full versus memory tool-schema bytes. --distractors 500 increases vault size. --semantic reuses an installed local model cache without a download or paid agent call. The fixture does not measure your private vault or guarantee a vendor client's behavior.

How it works

flowchart TB
    A1[Agent A] --> M
    A2[Agent B] --> M
    A3[Any stdio MCP agent] --> M
    M[Local HiveMind MCP bridge]
    M <--> V["Markdown vault<br/>Style · preferences · project memory"]
    M <--> D["SQLite<br/>Tasks · claims · events · messages"]
    M --> Q["Optional Graphify<br/>Local source relationships"]
    O[Obsidian or your editor] <--> V
    V --> B[Portable backup]
    D --> B
    classDef agent fill:#182b2c,stroke:#8ef0cc,color:#edfff8
    classDef core fill:#23213d,stroke:#a59fff,color:#f0edff
    classDef data fill:#172338,stroke:#92b9ff,color:#e8f0ff
    class A1,A2,A3 agent
    class M core
    class V,D,O,B,Q data

Small context by design: configurable briefs (default 1800 estimated tokens), query-matched notes packed before the remaining standing context, complete excerpts ranked by project, relevance and freshness, revision-checked writes, and no model-driven queue polling. Optional semantic search runs local embedding inference only; it makes no paid agent or hosted API calls. Other search and coordination remain deterministic; reading the returned text still consumes context. Inferred tastes stay separate from confirmed preferences. Current instructions always take precedence over memory.

Candidate review, checkpoint review, procedure maintenance, history, audit and older handoff search are on demand. They do not expand the default brief or add MCP tools. Agents can save verified procedures through the existing memory_learn tool; inferred preferences need explicit local approval before they enter the profile. Use local memory operations →

One server, up to 17 tools

HiveMind registers one MCP server with each agent. That server exposes 16 core tools, plus code_query on devices with Graphify-enabled projects:

The MCP tools/list response distinguishes reads from writes with explicit readOnlyHint annotations. New sessions, tasks and messages are marked additive; checkpoints, memory updates and task-state changes are marked as mutations. code_query can refresh its disposable local index, so it is marked as a non-destructive write even though it does not edit source files. These are client hints, not an access-control boundary; the server still validates every write.

The local authority's tools/list response explicitly classifies retries for every write:

Read-only tools leave idempotentHint unset because the hint only applies to environment-changing tools. An idempotency hint describes repeated effects, not an identical response or a guarantee that the first call succeeded. A forwarding bridge conservatively marks writes non-idempotent because it cannot verify an older authority's behavior; legacy cloud-memory writes are treated the same way.

Task and messaging tools support explicit coordination; their presence does not launch other agents. All 16 core tools are currently exposed. A smaller tool profile is a proposed optimization, not an available setting yet.

When Graphify runs: selecting it in setup or using --with-graphify builds the initial index. Subsequent code_query calls check for source changes and refresh as needed. It does not run continuously or after every message. Agents are instructed to use it for code relationships; preferences and handoffs use the memory/session tools. Invocation details →

Token overhead: semantic indexing uses your CPU, not agent tokens. Tool definitions, project instructions and returned text still add context to the agent. The 1,800-token memory brief and 1,000-token code-query defaults are approximate response ceilings, not fixed per-task charges or limits on the entire conversation. Actual usage depends on the harness, tokenizer, caching and number of calls. Net savings from fewer file reads have not yet been measured in a paid-agent task.

Your memory

HiveMind/
├── hivemind.cmd          Windows project installer
├── bootstrap.py          Portable first-run setup
├── hive.py               CLI + MCP entry point
├── hivemind/             Memory, coordination, and execution
├── templates/vault/      Generic starter notes tracked in Git
├── vault/                Your private local notes — ignored by Git
│   ├── 00-System/        Personality and working style
│   ├── 01-Memory/        Preferences and reusable solutions
│   ├── 02-Decisions/     Decisions and reasons
│   ├── 03-Projects/      Project state and handoffs
│   ├── 04-Tasks/         Generated task views
│   └── 05-Agents/        Agent roles
├── runtime/              Private SQLite database, note versions, logs, and config backups
└── tests/                Automated tests without paid inference

Open vault/ as an Obsidian vault, then open START. No community plugin is required, and Obsidian does not need to be running. Edit 00-System/Personality.md and 00-System/Working-Style.md to define how your agents should work.

Session checkpoints retain completed work, reported checks, blockers and next steps in SQLite, with a Markdown view under each project's Sessions/ directory. Concurrent updates require revision checks, and a CLI exit alone is never treated as verified completion. Resume compares each saved Git/worktree fingerprint with the live state and flags changed or unverifiable handoffs for inspection. Session behavior and limitations.

Opt-in worktree recovery saves bounded private file snapshots at session milestones. Preview a changed file, restore it only while its current hash matches the preview, and undo that restore if needed. Setup and limits →

Saved Markdown revisions can be inspected, diffed and restored with a current-revision check. A read-only audit flags mechanical issues; an opt-in search finds older task, session and message handoffs. These local operations make no model calls. Commands and limits →

The repository ships generic templates. First setup creates missing local notes without replacing your edits. Your real vault, credentials, databases, device configuration, and backup ZIPs are excluded from Git. Cloning this repository installs the software; it does not restore your personal memory.

Back up & move devices

From your HiveMind folder, after stopping active agent sessions and task workers:

.venv\Scripts\python.exe hive.py backup "D:\Backups\HiveMind-2026-09-25.zip"

Choose a new filename each time. Existing backups are never overwritten.

Extract the ZIP's HiveMind folder onto the next device. Install Python and your agent CLIs, then run its installer in each project. Keep the project's tracked .hivemind/project.json to preserve its identity. Restart agent sessions.

Use one active copy. Moving devices is migration, not live synchronization. Move a fresh backup when switching devices; do not sync a live SQLite database with a generic folder-sync tool. Personal backups contain private data—keep them out of GitHub releases and repository commits.

Useful commands

Run these from your HiveMind folder. On Linux substitute .venv/bin/python.

.venv\Scripts\python.exe hive.py doctor
.venv\Scripts\python.exe hive.py status
.venv\Scripts\python.exe hive.py search "authentication"
.venv\Scripts\python.exe hive.py offline
.venv\Scripts\python.exe hive.py context myapp --query "login" --budget 1000
.venv\Scripts\python.exe hive.py resume myapp
.venv\Scripts\python.exe hive.py history "01-Memory/Solutions/my-fix.md"
.venv\Scripts\python.exe hive.py memory-audit --project myapp
.venv\Scripts\python.exe hive.py handoff-search "authentication" --project myapp

The installer also supports --dry-run, --name myapp, --skip-register, --configure, and --no-prompt.

For an explicitly launched interactive session with automatic exit capture:

.venv\Scripts\python.exe hive.py session-run myapp AGENT-CLI

Replace AGENT-CLI with an installed CLI name or a locally configured adapter. This uses that agent's normal account usage. Normal agent launches still work; their handoff capture depends on following the installed instructions. The context budget is an estimate for the returned brief, not a hard limit on the agent's full conversation or account usage.

.venv\Scripts\python.exe hive.py create examples\inspect-project.json
.venv\Scripts\python.exe hive.py run TASK-ID --dry-run

Replace TASK-ID with the returned ID. Remove --dry-run only when you intend to execute the task using the assigned agent's account. Creating tasks or sending messages does not wake a model.

Tasks use claims and leases to prevent duplicate ownership. Write tasks require a clean Git repository with a committed HEAD and run in an isolated worktree. Expired tasks block for inspection and explicit requeue. Reported evidence needs review; nothing automatically merges, pushes, or deploys code.

Development

.venv\Scripts\python.exe -m unittest discover -s tests -v

Tests cover memory conflicts, ownership and leases, worker result handling, MCP interoperability, project-rule preservation, offline routing, backup restoration, private-vault separation, and a two-process handoff acceptance check. They use temporary fixtures and no paid model calls.

The protocol suite verifies tool behavior, not a model's instruction compliance. Real vendor inference and physical Linux behavior need separate smoke tests.

Documentation

License

HiveMind is licensed under the MIT License. Keep the copyright and license notice when redistributing it. Installed third-party dependencies retain their own licenses.

Keep the context. Carry the learning. Choose the agent.

Markdown you can read · SQLite you can back up · A folder you control