Hive Memory

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

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

[](https://www.npmjs.com/package/hive-memory) [](LICENSE) [](package.json)

---

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](docs/claude-md-template.md) | | Codex | ~/AGENTS.md or ./AGENTS.md | [codex-md-template.md](docs/codex-md-template.md) |

See the [full setup guide](docs/setup.md) 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= hive-memory

# Or use Docker
docker compose up

API Key Rotation

hive-memory user rotate 

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](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: moonx010
• Source: moonx010/hive-memory
• License: MIT
• Homepage: https://www.npmjs.com/package/hive-memory

Install and usage instructions live in the source repository linked above.