hive
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hive check shared memory for the current project state and blockers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
hive ๐
A shared brain for Claude Code and its sub-agents (MCP server + CLI).
Agents share state, not conversations: a fresh agent boots with a ~350-token compiled working set instead of re-reading 30k tokens of files and transcripts. Decisions survive across sessions and days, sub-agents inherit each other's results (never their chat logs), and 50 parallel agents can write without clobbering each other.
Golden rule: never make an agent pay tokens to read information it doesn't need โ or pay twice for the same information.
Full design: docs/PLAN.md.
Install (global, like any CLI)
npm install -g hive-mcpOr from source:
git clone https://github.com/HusseinTaha/hive-mcp.git && cd hive-mcp
npm install && npm run build
npm install -g .Now hive works from anywhere. Data lives in one file: ~/.hive/ctx.db (an existing
~/.sharedctx/ctx.db from older versions is adopted automatically).
Related MCP server: obsidiyan
Set up a project (once per repo)
cd your-project
hive initThis does three things:
.mcp.jsonโ registers thehiveMCP server, giving every agent five tools (below)..claude/settings.jsonโ wires three hooks:SessionStartโ injects a <800-token bootstrap, so every session starts already knowing the projectSubagentStopโ commits each sub-agent's final report to shared memory automaticallyPreCompactโ snapshots state before Claude Code compacts, so nothing is lost mid-session
CLAUDE.mdโ adds the one-line norm: bootstrap withctx_get, save results withctx_commit.
Restart Claude Code afterwards so it picks up the config.
Daily use
You mostly don't do anything โ that's the point. The hooks bootstrap every session and capture every sub-agent's results. Your part is telling Claude things worth remembering, in plain language:
"Commit to shared memory: we're using PostgreSQL because we need transactions."
"Save the decision that access tokens expire in 15 minutes."
"Check shared memory before proposing a database."
And when you come back tomorrow, a new session already knows all of it.
What agents get (the 5 MCP tools)
Tool | What it does |
| The working set: objective, current tasks, blockers, hot decisions, recent changes, topic index โ compiled to a budget (~350โ800 tok). Pass |
| BM25 search over everything ever stored, ~40 tok/hit with |
| Save results: what changed, decisions (key/value/reason), facts, open questions, task updates. Hard size caps โ a commit is a telegram, not a memoir. |
| Lease-based task board: |
| A bespoke context pack for one task description โ relevance-ranked, so cold facts matching the task resurface and hot-but-unrelated ones drop. |
What a bootstrap looks like
== acme-api @ a3f9c21 ยท CURSOR: 412 ==
OBJECTIVE: Ship v1 auth
NOW: refresh-token rotation (task#12, owner: backend-2)
BLOCKED: none
DECISIONS: db=PostgreSQL(relational+tx) | auth=JWT(15m access) | api=REST
CHANGED: login endpoint impl (backend-1, 2h ago, ev: tests/auth โ)
OPEN: rate-limit login?
โ VERIFY: 'api routes complete' written @ b2e11f0 (HEAD moved)
TOPICS: auth(9k) db(6k) api-contracts(7k)
MORE: d:cors ยท q:session-invalidation โ pull via topic= or ctx_search~350 tokens replacing a 30k-token history dump. Superseded decisions never appear here, but stay searchable forever โ that's what stops agent #7 from re-proposing MongoDB.
CLI reference
hive init wire up .mcp.json + hooks + CLAUDE.md in cwd, seed DB
hive status [--project P] [--role R] [--budget N] [--topic T] [--since N]
print the compiled working set (what agents see)
hive stats [--project P] context-spend telemetry per tool + est. savings
hive distill [--project P] heat decay + working-set pressure valve (also runs
automatically every ~25 events)
hive compress [--project P] [--model M] [--dry-run]
model-assisted fact compression via the claude CLI;
originals kept in supersede chains
hive dump [--project P] raw append-only event log as JSON lines
hive bootstrap alias of status (used by the SessionStart hook)Environment: HIVE_DB overrides the DB path; HIVE_PROJECT overrides the project key
(default: git-root basename). Legacy SHAREDCTX_* names still work.
Why it saves ~90%+ of context tokens
Naive shared-history | hive | |
Tool schemas | ~2,000 (10 verbose tools) | ~840 (5 terse tools, CI-guarded) |
Bootstrap | 20kโ80k transcript / file re-reads | ~350โ800 (hook-injected) |
Refresh checks | full re-dump each time | ~15โ100 (cursor deltas) |
Handoff | poisons the next agent | ~200-tok structured commit |
Under the hood: append-only SQLite event log (WAL โ 50 parallel writers, zero conflicts),
facts with supersede-chains (nothing is ever deleted), provenance + git-drift โ VERIFY
flags on volatile facts, evidence-gated completion, and a distiller that keeps the hot
working set โค ~1,500 tokens no matter how much knowledge accumulates.
Development
npm test # 39 tests: behavior, eval harness (50k-token seeded project),
# multi-process stress (20 writers / 12-way lease race), schema-token guard
npm run build # tsc โ dist/
npm install -g . # reinstall the global CLI after changesRoadmap M0โM4 from docs/PLAN.md is complete. Remaining work is field
tuning: use it on real projects and let hive stats + the eval harness drive ranking changes.
Available Tools
5 toolsctx_commitC
Save compact results before finishing; caps enforced.
Inputs: agent (required), changed (required), next, facts, +6 more.
ctx_compileD
Context pack for one task.
Inputs: task (required), role, budget, project.
ctx_getB
Shared project context. Call at start; pass since= later for deltas. topic= drills in.
Inputs: role, since, topic, budget, +1 more.
ctx_searchD
Search shared memory.
Inputs: q (required), k, project.
ctx_taskC
Claim|release|complete a task; complete needs evidence.
Inputs: agent (required), action (required), task_id (required), project, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 5 tools
Most tools have clearly distinct purposes: get context, search memory, commit results, manage tasks, compile context pack. However, ctx_get and ctx_search both retrieve shared information, which could cause confusion for an agent unfamiliar with the system.
All tools share the 'ctx_' prefix and mostly follow a verb-noun pattern (get, search, commit, compile). The exception is ctx_task, which uses a noun instead of a verb, creating a minor inconsistency.
Five tools is well-scoped for a shared context and task management server. Each tool has a clear role and the set is neither too thin nor too heavy.
The surface covers retrieving context, searching, committing results, managing task states, and compiling context packs. However, there is no tool to create tasks, list tasks, or update/delete context, which are notable gaps for a collaborative context system.
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Shared, scoped, reviewable team memory for AI coding agents.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
One shared brain for your AI coding agents: team memory, agent Q&A, tasks, and file claims.
Related MCP Servers
- AlicenseAqualityDmaintenancePersistent shared memory for AI coding agents. Stores facts as entity/key/value triples with hybrid semantic search, task checkpoints, and conflict resolution โ shared across Claude Code, Codex CLI, and GitHub Copilot.16235 npm5AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to search a shared, sourced corpus of past Claude Code and Codex sessions and curated notes, retrieve full conversations and timelines, and write or extend memory in either a committed or confidential, git-ignored layer. Confidential material is withheld from results unless explicitly requested.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding assistants to persistently save, search, and restore project context across sessions, including decisions, progress, file caches, checkpoints, and channel-based memory. It supports git-aware organization, batch operations, and shared memory across parallel sessions.243 npmMIT
- AlicenseNot gradedqualityCmaintenancePersistent project memory and task management for AI coding agents through MCP. Lets Claude Code, Cursor, Codex and other MCP clients save decisions and bug fixes, search relevant context, and reuse it across sessions.1MIT