hive-mind
Provides tools for recording and recalling decisions in a Neo4j graph database, enabling temporal memory with versioning and supersession chains.
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-mind record decision to use Redis for caching with rationale"
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 Mind
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.
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
Decisionrecord 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 |
| When the ruling became effective |
| When Hive Mind learned about it |
| When a replacement ended its effective interval |
| 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.yamlrepos.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: acmeAn 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-mcpRun the local web app:
./run_viewer.shThen open http://localhost:3000.
Configuration
The defaults match the development stack in compose.yaml. Every setting can
be overridden:
Variable | Default | Purpose |
|
| Python Neo4j connection |
|
| Python Neo4j user |
|
| Python Neo4j password |
|
| Web server Neo4j endpoint |
|
| Web server Neo4j user |
|
| Web server Neo4j password |
| auto-detected | Explicit scope-map path |
| unset | Checkout path used by the bundled Claude command |
|
| Shared practice-memory group |
|
| Attribution on confirmed decisions |
| 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 providerThe 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 toolscurrent_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
Scored across 8 tools
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 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.
With 8 tools, the set is well-scoped for the domain of decision management and context recall, covering all essential operations without being bloated.
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
Append-only decisions with provenance, supersession, retrieval, and audited MCP actions.
Memory for coding agents: the decisions, the dead ends, and where the last session stopped.
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI coding agents to record auditable work ledgers with evidence chains, from contract to proof packet, via MCP tools for file scanning, code review, and issue triage.7MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityAmaintenanceEnables 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.-