Skillget

hive-memory

mcp
SUMMARY

Cross-project memory for AI coding agents. MCP server that maintains context, decisions, and knowledge across workspaces. Fully local.

README.md 

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

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

npm
license
node

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

Reviews (0)

No results found