Metadata-Version: 2.4
Name: memory-hive-mcp
Version: 0.1.1
Summary: Local-first memory your AI agents share over MCP. Agents propose; only you confirm.
Author: Memory Hive
License-Expression: MIT
Project-URL: Homepage, https://hello-fengchao.com
Project-URL: Repository, https://github.com/330899935/memory-hive-ios
Project-URL: App (macOS), https://apps.apple.com/app/id6806992983
Project-URL: Source, https://github.com/330899935/memory-hive-ios
Keywords: mcp,mcp-server,model-context-protocol,memory,ai-memory,local-first,privacy,ai-agents,claude,cursor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# memory-hive-mcp

<!-- mcp-name: io.github.330899935/hive-memory -->

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

`memory-hive-mcp` is a thin [Model Context Protocol](https://modelcontextprotocol.io) 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.

## Install

```bash
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`.

## Configure your MCP host

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

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

### Environment variables

| Name | Required | Description |
| --- | --- | --- |
| `HIVE_AGENT_ID` | yes | Agent id issued by your own Hive. |
| `HIVE_AGENT_TOKEN` | yes | Access token issued when the agent was registered. Keep it secret. |
| `HIVE_MCP_URL` | no | Hive MCP endpoint. Defaults to `http://127.0.0.1:8768/mcp`. |

## The six tools

| Tool | Direction | What it does |
| --- | --- | --- |
| `recall` | read | Semantic search over your memory. `{"query": "...", "limit": 10, "compact": true}` — optional `vaults` narrows the search, `query_vector` switches to embedding recall. |
| `propose` | write → **pending** | Submits a memory for your approval. `{"content": "..."}` plus optional `title`, `vault`, `tags`, `vector`, and `client_id` as an idempotency key. Returns a `conflict_warning` when a near-duplicate exists. |
| `manage` | admin | Routed by `action`: `list_pending` / `forget` (soft delete) / `restore` / `get_by_id` / `discard_pending`. |
| `get_context` | session start | Pulls recent memory from your active threads and open tasks to seed a conversation. `{"limit": 8}`. |
| `say` | collaboration | Posts to the shared board. `{"summary": "..."}` plus optional `to`, `kind`, `stage`, `task_id`, `refs`, `ttl`. |
| `board` | collaboration | Reads the shared board with a cursor. `{"limit": 20, "since": "<cursor>"}` — `roster: true` also returns who is on duty. |

A typical session: `get_context` on open → `recall` mid-conversation → when you say "keep
this", it `propose`s → 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:

| Agent type | Public vaults | Private vaults |
| --- | --- | --- |
| Cloud agent (`mcp` / `mobile`) | ✅ open | 🔒 sealed |
| Local agent (non-cloud) | ✅ open | ✅ open |

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.

## Links

- Repository: https://github.com/330899935/memory-hive-ios
- Project home: https://hello-fengchao.com
- MCP integration docs: https://hello-fengchao.com/mcp.html

## License

MIT
