memory-hive-mcp

Local-first memory your AI agents share over MCP. Agents propose; only you confirm.

memory-hive-mcp is a thin Model Context Protocol server. It lets any MCP-capable host (Claude Desktop, Cursor, and friends) read and write your memory — stored on your computer, by your Hive, never uploaded anywhere.

This package contains no memory engine. It relays MCP protocol traffic to the Hive app already running on your machine (127.0.0.1:8768). Your data never passes through this bridge as stored state, and nothing leaves your computer.

The problem it solves

Every major assistant now has cross-session memory, so "my AI has no memory" is no longer the problem. The problem is what replaced it: memory is siloed per vendor, in formats you cannot export, governed by policies you did not set.

Who this is for: people who use two or more AI assistants seriously enough to be annoyed by re-introducing themselves. With one assistant, your vendor's built-in memory is probably enough.

Install

pip install memory-hive-mcp

Requires Python 3.8+. No third-party dependencies. This installs the command memory-hive-mcp.

(Note: an unrelated project owns the plain hive-mcp name on PyPI — that is not us.)

Prerequisite: a running Hive

memory-hive-mcp talks to the Hive on your own machine. Get it from the Mac App Store:

https://apps.apple.com/app/id6806992983

Then register an agent inside the Hive (POST /api/agent/register) to obtain an agent_id and access_token.

Hive 1.4.5 or newer is required. The say and board tools do not exist in earlier builds — on 1.4.4 and below, only the first four tools are available, and calling say or board will fail.

This package will not work on its own. It contains no memory engine, no database and no index — it only relays MCP traffic. If the Hive app is not installed and running, you get a connection to a bridge that has nothing behind it. That limitation is stated here on purpose rather than buried, so nobody installs this expecting a standalone memory server.

The Hive app is macOS only at present. The bridge itself is pure Python and runs anywhere, but it needs a Hive to talk to.

What happens without a running Hive

With a Hive running, initialize and tools/list are answered by the Hive itself, so the tool list, its constraints and the protocol version you see are always the real ones.

So a directory crawler, a CI check, or a curious pip install can still see the tool surface on a machine with no Hive — while any real memory operation fails honestly instead of pretending to succeed. A fabricated empty result would be worse than an error: the caller would conclude the user's memory is empty.

Configure your MCP host

Add the server to your host's MCP config. For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "hive-memory": {
      "command": "memory-hive-mcp",
      "env": {
        "HIVE_AGENT_ID": "your-agent-id",
        "HIVE_AGENT_TOKEN": "your-access-token"
      }
    }
  }
}

Environment variables

The six tools

A typical session: get_context on open → recall mid-conversation → when you say "keep this", it proposes → you confirm in your Hive on the Mac.

A shared ledger, not just a shared store

say and board make the Hive something more than a memory table: a place where several agents and one human keep the same ledger.

An agent posts what it just finished (say); another picks it up on its own schedule (board with a cursor) — no push, no waking anyone up, no orchestrator in the middle. Identity comes from the credential, not from a field the caller can set, so one agent cannot speak as another, and the human sees every hand-off in the same thread.

Your agent can propose. It cannot decide.

This is the design point that separates this server from a memory cache.

An agent can propose a memory, but it cannot confirm one. What it writes lands in a pending queue and stays there until you accept it inside your own Hive. There is no self-confirm, no silent background write, no path by which a model quietly decides what is true about you.

Memory is partitioned into vaults, and the boundary is enforced by the Hive — checked server-side, not promised by a prompt:

Agents missing from the registration table are sealed by default. A private vault entry is not readable, deletable, or restorable by an agent that is not allowed to see it.

Why a bridge, not a bundle

Your memory should have exactly one writer: the Hive on your machine. This server therefore speaks protocol and nothing else — no data files are opened, no state is cached, no engine is duplicated. That keeps your memory single-sourced, local, and under your control.

Status

Alpha (0.x). The wire protocol is stable; configuration and tool signatures may still change. See CHANGELOG.md for what changed between versions.

Platforms. The Hive app (the memory engine this bridge talks to) currently ships for macOS — App Store. Windows and Linux builds are in progress; the bridge itself is pure Python and runs anywhere, but it needs a Hive to talk to.

No benchmarks. We deliberately do not publish retrieval benchmarks. On a retrieval leaderboard we would lose to purpose-built vector stores, and we are not making that claim. What we do claim is narrower and checkable: the data stays on your machine, and the write authority stays with you.

Links

• Repository: https://github.com/330899935/memory-hive-mcp
• Project home: https://hello-fengchao.com
• MCP integration docs: https://hello-fengchao.com/mcp.html
• Package: https://pypi.org/project/memory-hive-mcp/
• Security policy: SECURITY.md

License

MIT