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-mcp

Or 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).

Set up a project (once per repo)

cd your-project
hive init

This does three things:

.mcp.json — registers the hive MCP 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 project
- SubagentStop → commits each sub-agent's final report to shared memory automatically
- PreCompact → snapshots state before Claude Code compacts, so nothing is lost mid-session
CLAUDE.md — adds the one-line norm: bootstrap with ctx_get, save results with ctx_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
`ctx_get`	The working set: objective, current tasks, blockers, hot decisions, recent changes, topic index — compiled to a budget (~350–800 tok). Pass `since=<last CURSOR>` on later calls to get only changes (~15–100 tok). `topic=auth` drills into one topic.
`ctx_search`	BM25 search over everything ever stored, ~40 tok/hit with `[e<id>]` provenance refs. Zero local hits → labeled results from your other projects (`[proj-a/e12] …`).
`ctx_commit`	Save results: what changed, decisions (key/value/reason), facts, open questions, task updates. Hard size caps — a commit is a telegram, not a memoir.
`ctx_task`	Lease-based task board: `claim` / `release` / `complete`. Two agents can never hold the same task; stale leases (30 min) are reclaimable; `complete` requires evidence.
`ctx_compile`	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 changes

Roadmap 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.