Skip to main content
Glama

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

Related MCP server: obsidiyan

Set up a project (once per repo)

cd your-project
hive init

This does three things:

  1. .mcp.json โ€” registers the hive MCP server, giving every agent five tools (below).

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

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

Available Tools

5 tools
ctx_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_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

    C2.5/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Persistent 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.
      16
      235 npm
      5
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Persistent 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.
      1
      MIT