Skip to main content
Glama

Hive Mind

CI License: Apache-2.0

Hive Mind is a self-hosted, temporal decision memory for coding agents. It records what was decided, why it was decided, when it became effective, and which later ruling superseded it.

The canonical record lives in Neo4j and is exposed through MCP tools, fail-open agent hooks, and a local web interface. Decisions are project-scoped so memory from one project is not returned to another.

IMPORTANT

Hive Mind is alpha software. Back up your Neo4j volume and review its privacy model before using it with confidential material.

What it provides

  • A canonical Decision record with rationale and rejected alternatives.

  • Separate valid time (decided_at) and record time (recorded_at).

  • Explicit supersession chains and historical “as of” queries.

  • One current ruling per project, scope, repository, and decision key.

  • Full-text retrieval on the prompt path without an LLM or embedding model.

  • MCP tools for recording, recalling, superseding, and tracing decisions.

  • A review queue for candidate decisions extracted from agent sessions.

  • A local web app for search, correction history, and supersession.

  • Optional Graphiti integration for semantic discovery and provenance.

Related MCP server: porque

Temporal model

Field

Meaning

decided_at

When the ruling became effective

recorded_at

When Hive Mind learned about it

superseded_at

When a replacement ended its effective interval

decision_key

Stable topic identity across versions

Corrections preserve an immutable DecisionRevision. Changed rulings create a new Decision linked to the old one with SUPERSEDES. Decisions are never silently expired by a model.

Quick start

Prerequisites:

  • Docker with Compose

  • uv and Python 3.12

  • Node.js 22 or later for the web app

Start Neo4j and install the Python project:

docker compose up -d
uv sync --extra dev
uv run pytest -m "not slow"

For a source checkout, copy the starter scope map and replace its examples:

cp repos.yaml repos.local.yaml

repos.local.yaml is ignored by Git. Each entry maps a repository directory name to a project group:

practice_group: practice

repos:
  checkout-api: acme
  checkout-infrastructure: acme

An unmapped repository receives practice-wide memory only. Hive Mind does not guess project membership.

For an installed package, put the same file at ~/.config/hive-mind/repos.yaml or set HIVE_MIND_REPO_MAP to an explicit path.

Run the MCP server:

uv run hive-mind-mcp

Run the local web app:

./run_viewer.sh

Then open http://localhost:3000.

Configuration

The defaults match the development stack in compose.yaml. Every setting can be overridden:

Variable

Default

Purpose

HIVE_MIND_NEO4J_URI

bolt://localhost:7687

Python Neo4j connection

HIVE_MIND_NEO4J_USER

neo4j

Python Neo4j user

HIVE_MIND_NEO4J_PASSWORD

hive-mind-local-password

Python Neo4j password

NEO4J_HTTP_URL

http://localhost:7474

Web server Neo4j endpoint

NEO4J_USER

neo4j

Web server Neo4j user

NEO4J_PASSWORD

hive-mind-local-password

Web server Neo4j password

HIVE_MIND_REPO_MAP

auto-detected

Explicit scope-map path

HIVE_MIND_HOME

unset

Checkout path used by the bundled Claude command

HIVE_MIND_PRACTICE_GROUP

practice

Shared practice-memory group

HIVE_MIND_ACTOR

human

Attribution on confirmed decisions

HIVE_MIND_GRAPHITI_FACTORY

unset

Optional semantic client factory

The passwords above are development defaults, not production credentials. Bind Neo4j to a trusted interface, use a unique secret, and back up its data volume before storing important memory.

Optional semantic provider

Canonical decision storage, full-text search, temporal queries, MCP, hooks, and the web app do not require embeddings.

Semantic grounding is an extension point. Install the semantic extra and expose a zero-argument factory returning a Graphiti-compatible client:

uv sync --extra semantic
export HIVE_MIND_GRAPHITI_FACTORY="my_provider.graph:build_client"

The original deployment uses Nomic embeddings locally on Apple Silicon through an external provider. Contributions that turn this into a first-party, provider-neutral adapter are especially welcome.

Architecture

coding agent
  ├── MCP tools ────────────────┐
  ├── prompt/session hooks ─────┤
  └── local web app ────────────┤
                                ▼
                         canonical Neo4j graph
                       Decision / Revision / Topic
                                │
                                └── optional semantic provider

The direct Cypher path is authoritative and fast. The optional semantic layer is best-effort discovery; it must never overwrite canonical decision text. See docs/architecture.md for invariants and extension points and docs/roadmap.md for contribution opportunities.

Contributing

Issues, documentation improvements, adapters, tests, and code contributions are welcome. Start with CONTRIBUTING.md, which includes the development workflow and areas where help is most useful.

Maintainers preparing the first public repository should follow the public release checklist; the original private Git history must not be published.

By participating, you agree to the Code of Conduct. Security and privacy reports should follow SECURITY.md.

License

Licensed under the Apache License 2.0.

Available Tools

8 tools
current_decisionB

Return the one live decision for a stable topic key.

Inputs: decision_key (required), repo, scope, client. Returns: result

decision_lineageB

Show the oldest-to-newest supersession chain containing a decision.

Inputs: uuid (required). Returns: result

decisions_as_ofC

Return decisions that were effective at a historical point in time.

Inputs: as_of (required), limit, decision_key. Returns: result

recall_contextA

Search what clients and stakeholders actually said, from meeting transcripts.

Use to find where an ask originated, what was promised, or what a client
required — before writing code against a second-hand description of it.
Facts carry temporal validity: a fact with an invalid_at date was superseded.

Inputs: query (required), limit. Returns: result

recall_decisionsA

Search prior architectural decisions before proposing an approach.

Call this before designing anything non-trivial. Superseded decisions and rejected alternatives are the most useful results — they are exactly the approaches that should not be proposed again.

Inputs: query (required), limit, include_superseded. Returns: result

record_decisionB

Record a settled architectural decision so it is not re-litigated.

decision_key is a stable lowercase kebab-case topic preserved across revisions.
decided_at is when the ruling became effective, not when it was recorded.
scope: 'repo' (this repo only), 'client' (all client repos), or 'practice'.

Inputs: rationale (required), statement (required), decision_key (required), repo, +6 more. Returns: result

supersede_decisionB

Retire a decision and replace it, preserving the old one as REJECTED history.

Inputs: uuid (required), reason (required), new_statement (required), rationale, +1 more. Returns: result

whyA

Explain why a decision exists, quoting the client conversation behind it.

Use when a constraint looks arbitrary, when you are about to argue against an existing decision, or when the user asks where a requirement came from. Returns decisions plus dated, speaker-attributed excerpts from the meetings that motivated them.

Inputs: topic (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 8 tools

    Disambiguation4/5

    Most tools have distinct purposes (e.g., 'why' explains decisions with quotes, 'recall_context' searches transcripts), but 'recall_decisions' and 'decisions_as_of' could be confused as both retrieve decision information, though the descriptions clarify the difference.

    Naming Consistency2/5

    Naming conventions are mixed: some use verb_noun ('record_decision', 'recall_context'), while others use noun_preposition ('decisions_as_of') or adjective_noun ('current_decision', 'decision_lineage'), lacking a uniform pattern.

    Tool Count5/5

    With 8 tools, the set is well-scoped for the domain of decision management and context recall, covering all essential operations without being bloated.

    Completeness4/5

    The tool surface covers recording, superseding, and querying decisions (current, historical, lineage) and searching context. A minor gap is the absence of a tool to list all decision topics, but this can be worked around via search.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables capturing and storing AI coding decisions as markdown, and provides MCP tools for assistants to query and record those decisions so they respect past architectural choices.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding tools and developers to store, search, and supersede durable engineering discoveries with temporal validity, and to coordinate active work across sessions via MCP.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP-enabled editors and agents to generate and execute structured dialectical reasoning prompts and iterative player-coach code verification workflows, including optional independent coach sessions and autocoding state persistence.
      -