What Hive is

After this page you'll know what Hive is, why bees consult it, and what kind of knowledge lives in it. You don't need to touch Hive to run a bee (every run uses it automatically), but understanding it explains why a bee already knows your project's conventions.

Why it exists

Without shared memory, every bee would start cold: no idea what the project is, how the repos fit together, or which decisions the team already made. Hive fixes that. It's the per-project knowledge layer that a bee reads before it plans, so run #50 on a project starts smarter than run #1. Runs compound instead of resetting.

The division of labour is simple: Swarm executes, Hive remembers. Swarm owns triggers, identity checks, planning, and the code/PR work. Hive owns the project registry, the ingested context library, and the sink for what runs learn.

What lives in it

Hive organises everything around Spaces, one Space per project. A Space holds:

• Membership: who's on the project. Swarm checks the requester against this before any run starts; if you're not a member of the Space, the run is rejected.
• AI policy: which model provider the project uses, or NO_AI if the client has opted out of automation entirely. NO_AI is a hard gate: Swarm rejects the run rather than falling back to a default.
• Sources: the project's connected repos and channels, each GitHub source tagged with a role (BACKEND, WEB, IOS, ...) so a bee can work out which repo your request belongs to.
• Context pages: structured project docs, namely OVERVIEW, ARCHITECTURE, DEV_WORKFLOW, DECISION_LOG, and friends. These seed the swarm agent's planning phase on every trigger.
• Decisions and patterns: the append-only record of what was decided and what recurring approaches emerged, written back after runs that produced durable signal.

How bees talk to it

Hive exposes this over MCP. The tool names are hive_<verb>:

hive_resolve_source     which Space does this Slack channel / repo belong to?
hive_check_membership   is this requester on the project?
hive_resolve_policy     which model provider, or NO_AI?
hive_list_sources       which repos does this Space have, and what role is each?
hive_get_page           fetch one context page (OVERVIEW, ARCHITECTURE, ...)
hive_search             hybrid retrieval across the Space's ingested context
hive_list_decisions     the project's decision log
hive_append             write a new section back to a page (append-only) *
hive_propose_pattern    propose a reusable pattern from a decision *

* The two write tools are what Swarm's client calls, but the Hive server doesn't implement them yet; those calls currently soft-fail (see below).

All of this goes through one Swarm-side client (triggers/lib/hive-client.js), authenticated with a space-scoped token, so a bee can only read the project it's working on. The step-by-step of where each call happens in a run is on How a run uses Hive.

Reading is guaranteed, writing is best-effort

The read path is load-bearing: if Hive can't resolve your channel or membership, the run doesn't start. The write path is deliberately not: a failed write-back never fails a run, and most runs write nothing at all. A bee only feeds Hive when the run produced something durable: a decision, a workflow change, a pattern.

Write-back is also append-only. A bee never edits human-authored content; it adds a new section or a new decision entry, which a human can review like anything else. One caveat: the Hive server does not yet implement hive_append or hive_propose_pattern, so today every write-back soft-fails. The design above describes the contract, not yet the end-to-end behaviour.

What good Hive content looks like, and who keeps it that way, is covered in Keeping Hive healthy.