hive-memory

<p align="center">

 ██╗  ██╗██╗██╗   ██╗███████╗
 ██║  ██║██║██║   ██║██╔════╝
 ███████║██║██║   ██║█████╗
 ██╔══██║██║╚██╗ ██╔╝██╔══╝
 ██║  ██║██║ ╚████╔╝ ███████╗
 ╚═╝  ╚═╝╚═╝  ╚═══╝  ╚══════╝
 ███╗   ███╗███████╗███╗   ███╗ ██████╗ ██████╗ ██╗   ██╗
 ████╗ ████║██╔════╝████╗ ████║██╔═══██╗██╔══██╗╚██╗ ██╔╝
 ██╔████╔██║█████╗  ██╔████╔██║██║   ██║██████╔╝ ╚████╔╝
 ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██║   ██║██╔══██╗  ╚██╔╝
 ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║╚██████╔╝██║  ██║   ██║
 ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝   ╚═╝

Cross-project memory layer for AI coding agents — with graph memory

</p>

---

Hive Memory is an MCP server that gives AI coding agents persistent, graph-connected memory across projects. It stores decisions, learnings, and session progress in a local knowledge base with brain-inspired synaptic connections — so your agent can discover related context through topology-based traversal, not just keyword search.

Features

• 33 MCP tools — project management, memory storage/recall, graph traversal, browsing, connectors, team sync, meetings, stewardship, and admin
• SQLite-backed — FTS5 full-text search, WAL mode, zero external services
• Graph memory (synapses) — 15 axon types, Hebbian learning, spreading activation
• Hybrid search — BM25 + optional vector similarity with RRF fusion
• 4 connectors — GitHub, Slack, Notion, Google Calendar
• Team sync — Git-based shared cortex for teams
• Meeting pipeline — transcript → structured notes → enrichment
• HTTP mode — Deploy on Railway/Render with per-user API keys and rate limiting
• Docker support — Ready-to-run container with health check
• Schema versioning — Tracked migration history in schema_meta table
• Audit logging — In-memory audit trail for all tool calls
• Backup CLI — hive-memory backup [--output path] for database snapshots

Architecture

┌──────────────────────────────────────────────────────────┐
│                    Hive Memory (cortex)                   │
│                                                          │
│  ┌────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ MCP Server │  │  HTTP Server │  │   CLI Interface  │  │
│  │  (stdio)   │  │  (port 3179) │  │   (hive-memory)  │  │
│  └─────┬──────┘  └──────┬───────┘  └────────┬────────┘  │
│        └────────────────┼────────────────────┘           │
│                         │                                │
│  ┌──────────────────────▼────────────────────────────┐  │
│  │                   CortexStore                      │  │
│  │  ┌────────────┐  ┌──────────┐  ┌──────────────┐  │  │
│  │  │HiveDatabase│  │ Synapse  │  │ Enrichment   │  │  │
│  │  │ (SQLite)   │  │  Graph   │  │   Engine     │  │  │
│  │  └─────┬──────┘  └──────────┘  └──────────────┘  │  │
│  │        │                                           │  │
│  │  ┌─────▼──────────────────────────────────────┐  │  │
│  │  │         SQLite Database (cortex.db)          │  │  │
│  │  │  entities · synapses · sessions · projects  │  │  │
│  │  │  connectors · users · labels · schema_meta  │  │  │
│  │  └─────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
         ▲              ▲              ▲
   ┌─────┴─────┐  ┌─────┴─────┐  ┌───┴──────┐
   │  GitHub   │  │   Slack   │  │  Notion  │
   │ Connector │  │ Connector │  │ Connector│
   └───────────┘  └───────────┘  └──────────┘

Quick Start

Install

npm install -g hive-memory

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hive-memory": {
      "command": "hive-memory"
    }
  },
  "permissions": {
    "allow": [
      "mcp__hive-memory__*"
    ]
  }
}

The permissions.allow entry auto-approves all Hive Memory tools so Claude won't prompt for permission every session.

Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "hive-memory": {
      "command": "hive-memory"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "hive-memory": {
      "command": "hive-memory"
    }
  }
}

HTTP Mode (Remote Deployment)

CORTEX_HTTP=true CORTEX_AUTH_TOKEN=secret hive-memory --http

Or with Docker:

docker compose up

Agent Instructions

Hive Memory works best when your AI agent knows when to call the tools. Copy the provided instruction templates into your agent's instruction file:

Agent	Instruction file	Template
Claude Code	~/.claude/CLAUDE.md	claude-md-template.md
Codex	~/AGENTS.md or ./AGENTS.md	codex-md-template.md

See the full setup guide for step-by-step instructions.

Tools Reference (33 tools)

Project Tools (4)

Tool	Description
project_register	Register or update a project (upsert)
project_search	Search projects by name/tags, or list all (empty query)
project_status	Get project context (full mode includes cross-project insights)
project_onboard	Auto-discover projects in a directory + scan for agent memory files

Memory Tools (5)

Tool	Description
memory_store	Store a decision, learning, or note. Auto-creates synapses to related memories
memory_recall	Search using keyword matching + graph traversal (spreading activation)
memory_link	Form an explicit synapse between two memory entries
memory_traverse	Deep graph traversal — find memories connected through synaptic pathways
memory_connections	View the synaptic connections of a specific memory entry

Session Tools (1)

Tool	Description
session_save	Save session progress — what was done, what's next

Browse Tools (5)

Tool	Description
memory_ls	List entities with filters (project, type, status, domain)
memory_tree	Tree view of entities grouped by project and type
memory_grep	Regex/substring search across entity content
memory_inspect	Detailed view of a specific entity including synapses
memory_timeline	Chronological view of entities in a time range

Trail Tools (3)

Tool	Description
memory_trail	View the access trail of recently used memories
memory_who	See which agents have contributed to a project
memory_decay	Apply synapse weight decay and prune weak connections

Connector Tools (2)

Tool	Description
connector_sync	Trigger a connector sync (GitHub, Slack, Notion, Calendar)
connector_status	View sync status and entry counts for all connectors

Team Tools (4)

Tool	Description
team_init	Initialize a Git-based shared team cortex
team_push	Push local entries to the team cortex
team_pull	Pull team entries into local database
team_status	View pending push/pull and conflict count

Context Tools (2)

Tool	Description
context_enrich	Run enrichment on an entity (classification, topics, decisions)
entity_resolve	Find and deduplicate person entities across sources

Meeting Tools (2)

Tool	Description
meeting_process	Process a meeting transcript into structured notes and decisions
meeting_briefing	Generate a meeting briefing from recent meetings

Steward Tools (2)

Tool	Description
memory_audit	Run data quality audit on stored memories
memory_briefing	Generate daily or weekly memory briefing

Advisor Tools (1)

Tool	Description
workflow_analyze	Analyze workflow patterns and generate insights

User / Admin Tools (2)

Tool	Description
user_manage	Manage users — add, list, revoke, rotate API keys
memory_audit_log	Retrieve recent MCP tool call audit log (admin only)

Connectors

Connector	Env Variable	What it syncs
GitHub	GITHUB_TOKEN	PRs, Issues, ADRs, CODEOWNERS
Slack	SLACK_TOKEN	Signal-filtered messages, threads
Notion	NOTION_TOKEN	Pages, databases, block content
Google Calendar	GOOGLE_CALENDAR_CREDENTIALS	Events, attendees (OAuth2/service account)
Outlook	OUTLOOK_TOKEN	Calendar events

How It Works

┌──────────┐     ┌──────────┐     ┌──────────┐
│ Claude   │     │ Cursor   │     │ Codex    │
│ Code     │     │          │     │          │
│ (Proj A) │     │ (Proj B) │     │ (Proj C) │
└────┬─────┘     └────┬─────┘     └────┬─────┘
     │                │                │
     └────────────────┼────────────────┘
                      │ MCP (stdio)
               ┌─────────────┐
               │ Hive Memory │
               │  MCP Server │
               └──────┬──────┘
                      │
     ┌────────────────┼────────────────┐
     ▼                ▼                ▼
┌─────────┐    ┌───────────┐    ┌───────────┐
│ Hive    │    │ Synapse   │    │ Spreading │
│ Cell    │    │ Graph     │    │ Activation│
│ Tree    │    │ (LTP/LTD) │    │           │
└─────────┘    └───────────┘    └───────────┘

No cloud. No accounts. No embeddings required. Everything stays on your machine.

Graph Memory (Synapses)

Every memory can be connected to other memories through synapses — directed, weighted edges inspired by neuroscience:

"Use JWT for auth" ──[causal:0.8]──→ "Add token refresh logic"
        │                                      │
        │──[semantic:0.5]──→ "OAuth2 decision"  │
                                               │
"Rate limit API" ←──[dependency:0.6]───────────┘

Axon Types:

Type	Meaning	Example
temporal	A occurred before B	Decision A was made before Decision B
causal	A caused/led to B	"Use PostgreSQL" → "Add pgvector extension"
semantic	Topically related	Both about authentication
refinement	B refines/updates A	"Use JWT" → "Use JWT with 15min expiry"
conflict	A contradicts B	"Use SQL" vs "Use NoSQL"
dependency	B depends on A	Feature B requires Feature A
derived	B was derived from A	Learning extracted from a decision

Spreading Activation

When you search with memory_recall or memory_traverse, the system propagates signal through the synapse graph:

Query: "auth token handling"
  │
  ▼ keyword match
  Seed: "Use JWT for auth" (activation: 1.0)
  │
  ├─[causal:0.8]──→ "Add token refresh" (activation: 0.4)
  │                        │
  │                  ├─[dependency:0.6]──→ "Rate limit API" (activation: 0.12)
  │
  └─[semantic:0.5]──→ "OAuth2 decision" (activation: 0.25)

Hebbian Learning

"Neurons that fire together, wire together":

• LTP (Long-Term Potentiation): When two memories are recalled together repeatedly, their synapse weight increases (+0.1 per co-activation)
• LTD (Long-Term Depression): Unused synapses decay over time (×0.995 per flush cycle)
• Pruning: Synapses below 0.05 weight are automatically removed
• Auto-formation: When two memories are co-activated 5+ times, a Hebbian synapse is created automatically

HTTP Mode & Multi-User Setup

Deploy as an HTTP server for shared team access:

# Create an admin user
hive-memory user create admin-name

# Start HTTP server
CORTEX_HTTP=true CORTEX_AUTH_TOKEN=<token> hive-memory

# Or use Docker
docker compose up

API Key Rotation

hive-memory user rotate <user-id>

The new key is active immediately. The graceUntil timestamp is stored for audit purposes.

Rate Limiting

The HTTP server enforces a limit of 100 requests per minute per user (in-memory, per instance).

Auto Session Capture

Hive Memory can automatically save sessions when Claude Code exits. Add to ~/.claude/settings.json:

{
  "hooks": {
    "SessionEnd": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "hive-memory hook session-end"
      }]
    }]
  }
}

This parses the Claude Code transcript and auto-saves a session summary. It skips if session_save was already called during the session.

Backup

# Create a backup
hive-memory backup

# Specify output path
hive-memory backup --output /path/to/backup.db

Configuration

Environment Variables

Variable	Default	Description
CORTEX_DATA_DIR	~/.cortex	Data storage directory
CORTEX_LOCAL_SYNC	true	Set to "false" to disable writing .cortex.md into project directories
CORTEX_LOCAL_FILENAME	.cortex.md	Custom filename for local context files
CORTEX_HTTP	false	Set to "true" to enable HTTP server mode
CORTEX_AUTH_TOKEN	—	Admin API token for HTTP mode
PORT / CORTEX_PORT	3179	HTTP server port
CORTEX_SYNC_INTERVAL_MIN	30	Connector auto-sync interval in minutes

Example with custom config:

{
  "mcpServers": {
    "hive-memory": {
      "command": "hive-memory",
      "env": {
        "CORTEX_DATA_DIR": "/custom/path",
        "CORTEX_LOCAL_SYNC": "false"
      }
    }
  }
}

Local Context File (.cortex.md)

Hive Memory writes a .cortex.md file in each registered project directory. This file contains a snapshot of the project's current context — summary, recent session, next tasks, and cross-project insights. It's auto-generated and should be added to .gitignore.

To disable this feature, set CORTEX_LOCAL_SYNC=false.

Migration from v1/v2

Hive Memory v3 automatically migrates existing data:

• Legacy knowledge/ files are migrated to hive direct entries on first startup, then renamed to knowledge.bak/
• Existing project registrations (index.json, summary.json, sessions) are unchanged
• Embedding data (vectors.json, embedding model cache) is no longer used and can be safely deleted
• The @huggingface/transformers dependency has been removed — no more model downloads
• Schema version is now tracked in the schema_meta table

No manual action needed — just update and restart.

Development

npm install          # Install dependencies
npm run build        # Build TypeScript
npm run dev          # Dev mode with auto-reload
npm run lint         # Lint with ESLint
npm run typecheck    # Type check
npm test             # Run tests
npm run test:coverage # Run tests with coverage report

License

MIT