hivemind

Local shared memory and coordination for any stdio MCP agent. Guided setup activates HiveMind inside enrolled projects while keeping one shared vault. 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 →

Optional free or cheap model learning: explicitly enable OpenRouter-assisted progress summaries, taste and working-style candidates, and source-linked knowledge drafts. Native adapters for eight clients record supported activity locally; bounded inference suggests learning for review. Free mode has no paid fallback. This feature sends selected activity to an external provider and requires an API key. Core memory needs neither. Set up assisted learning →

Compact handoffs without another model call: hive.py handoff PROJECT brings the last meaningful checkpoint, reported checks, blockers, next actions and new local activity into one bounded packet. The recorder coalesces bursts, skips empty/checkpoint-only inference and reports actual OpenRouter token usage. Handoff commands →

Git-aware continuation: checkpoints record the branch, commit and a fingerprint of staged, unstaged and untracked changes. Resume checks the live worktree before the next harness relies on that handoff. Optional recovery snapshots preserve bounded file copies; Git metadata alone does not save file contents. HiveMind does not automatically commit, push or synchronize code between devices. Git checks and recovery →

Current knowledge for the task at hand: link memory to affected files, mark old decisions replaced, and flag competing current claims. Task briefs include relevant file-linked notes and dependency evidence. Completed work produces reviewable lessons, and consolidation proposals combine related learning while retaining source history. Goal plans connect tasks into bounded dependency graphs with explicit agent execution. Explore core memory and goal workflows →

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 terminal, pick the features and clients you want, and start working. It enrolls the project, configures project connections, and checks the MCP bridge. Each project keeps its own learning/model/budget choices. User-wide client registration is never a fallback. Set up HiveMind →

Related MCP server: io.github.cdnsteve/sugar

Quick start

You need Node.js 20+ for npm/npx, Python 3.11+, Git, and an agent that supports stdio MCP. A manual Git install is also available without Node.js. 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.

Install the HiveMind software once, then opt in from each project's folder. The vault, checkpoints and private API key stay in that shared HiveMind folder; activation files live in the enrolled project. Other folders receive no settings. Project layout, commands and migration →

1 · Install from your project folder

Open a terminal in the project you want to enroll and run:

npx --yes github:raj45681/HiveMind setup

Or add the launcher as a project development dependency:

npm install --save-dev github:raj45681/HiveMind
npx hivemind setup

This is a GitHub package install, not a published npm-registry name. The launcher opens the same guided harness, free-model and hidden OpenRouter-key setup. npm install itself does not run setup or ask for credentials. Python's private environment and pinned dependencies are prepared automatically by the setup command. Activation remains project-only. The shared backend, vault and keys live outside node_modules and npm's cache; removing the npm package does not remove memory.

To reuse an existing HiveMind folder on your first npm run, select it explicitly:

npx --yes github:raj45681/HiveMind setup --hive-home "D:\HiveMind"

Later projects reuse the remembered home. On a fresh device, the shared home is ~/.hivemind/home. Run the same setup command inside each project you want to enroll. See npm setup and storage for requirements, updates and additional options.

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"

For PowerShell and Linux commands, see the project installation guide. Use either the npm method or this manual method; both open the same wizard.

The setup command opens the wizard. 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 terminal; it reuses the local feature choices. A project wizard then asks for clients, learning mode, OpenRouter model and budget, activity capture, and optional project purpose and working preference. Interactive setup always explicitly asks for the OpenRouter API key when learning is enabled, even if one already exists. Input is hidden; Enter keeps the existing key or skips entry when none is set. Pasted keys are saved privately on this device, outside Git and the vault. The All option saves only the working-style answers you actually enter. Setup makes no paid agent call.

Free learning offers six model choices with automatic free fallback routing. Temporary failures retry up to three attempts total, with short backoff and OpenRouter's Retry-After delays. Every HTTP retry respects the shared request budget. See the model pool and retry policy.

Setup is safe to rerun. Saved project choices avoid repeated option questions; the OpenRouter key step remains explicit during interactive learning setup. --configure reopens the other options; --no-prompt skips all questions. Setup configures each selected client independently, then opens the local MCP bridge and calls hive_context without starting an AI session. The report separates MCP configuration, native capture and headless task execution. Configured means settings are installed; actual client callbacks still need a restart and normal trust. If one adapter fails, the others are attempted. Codex and Grok use project-local MCP configuration and hooks. Cline CLI uses a project launcher; Antigravity and Windsurf use the local CLI fallback because their current adapters do not provide native project-only MCP activation. 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:

npx --yes github:raj45681/HiveMind setup --configure

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

After enrollment, use the helper inside your project:

.hivemind\hive.cmd handoff
.hivemind\hive.cmd context --query "current task"
.hivemind\hive.cmd setup --configure

The helper supplies the project ID and follows the ignored local pointer to the same shared vault. On Linux use python3 .hivemind/hive.py or bash .hivemind/hive. Existing global registrations from older releases require the explicit one-time migration.

Supported adapters cover Codex, Grok Build, Antigravity, Claude Code, OpenCode, Command Code, Gemini CLI, Cursor, Copilot CLI, VS Code, Cline, Roo Code, Continue and Windsurf. Capabilities, scope and configuration paths →

For explicit project setup without questions (using an existing key):

"%USERPROFILE%\HiveMind\hivemind.cmd" "D:\Projects\My App" --no-prompt --harness claude --harness opencode --learning free --daily-limit 100 --capture

You can also run .venv\Scripts\python.exe hive.py setup PROJECT from the HiveMind folder. Free learning is the default model when enabled; cheap mode requires an explicit model, daily dollar ceiling and provider price ceilings. Native capture can be off independently of explicit MCP checkpoint learning.

Recognized adapters need no separate skill. 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 eleven memory, review, and session MCP tools on this device. The default full profile exposes 22 core tools, including task claims, goals, and messages, plus optional Graphify. The memory profile reduces serialized tool schemas; hive.py benchmark reports the current sizes, while 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 writes project-local connections for supported clients and reports launcher or CLI fallbacks for the others. It never silently edits user-wide client settings. 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.

The benchmark includes 17 labelled cases: exact queries, paraphrases, ambiguous terms, conflicting archived advice, pending preferences, review drafts, unrelated queries, and literal project boundaries. It reports rank and incremental indexing work as well as retrieval results. Add --check to return a nonzero exit code on required retrieval, isolation, indexing, or context-budget regressions. Core mode reports paraphrase misses without failing; --semantic --check requires those paraphrases to be found too.

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. Core memory relationships and learning proposals have dedicated MCP tools. Agents can save verified procedures through memory_learn; inferred preferences need explicit local approval before they enter the profile. Use local memory operations →

One server, up to 23 tools

HiveMind registers one MCP server with each agent. That server exposes 22 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. The full profile exposes coordination tools; the memory profile exposes only recall and memory tools. Select it during setup with --tool-profile memory.

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 handoff myapp
.venv\Scripts\python.exe hive.py assist-status --project 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 leases display as blocked even on read-only task views; the next coordinator write records the expiry event. Inspect before explicitly requeuing. 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, client setup, recorder batching and crash recovery, token accounting, and model-free handoffs. They use temporary fixtures, simulated provider responses and local child processes, with 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.

GitHub Actions runs the unit suite, doctor, the MCP acceptance check, and the retrieval regression benchmark on Windows and Linux with Python 3.11, 3.12, and 3.13. Each job uploads its benchmark JSON. A manual workflow run can also enable the real semantic-model tests and benchmark; this downloads or reuses the local model cache and makes no paid inference calls.

hive.py doctor keeps its JSON output for scripts and exits nonzero when a required dependency or coordinator check fails. Use hive.py doctor --human for a readable summary with repair commands. Missing optional features do not fail core health checks; degraded optional features appear as warnings.

Search checks file metadata each time and reads changed notes. Full content reconciliation occurs on the next scan after five minutes, or immediately with hive.py index. This preserves direct Obsidian edits, deletions, and note history without rereading an unchanged vault on every query. Filesystem metadata is a change signal, not proof of identical content; run index after tools that preserve every timestamp and file identity.

Open Review in the Obsidian vault for pending preference approvals, checkpoint drafts, and procedures to check. Refresh it with hive.py review-dashboard or hive.py export. Review workflow and project filters →

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