Memory Hive

memory-hive-mcp

本地优先的记忆，供你的 AI Agent 通过 MCP 共享。Agent 提议，只有你确认后才会生效。

memory-hive-mcp 是一个轻量的 Model Context Protocol 服务。 它让任何支持 MCP 的宿主（Claude Desktop、Cursor 等）都能读取和写入你的 记忆——这些记忆由你的 Hive 存储在你的电脑上，绝不会上传到任何地方。

此软件包不包含记忆引擎。 它只会将 MCP 协议流量转发到你机器上 已在运行的 Hive 应用（127.0.0.1:8768）。你的数据不会作为存储状态经过此 桥接服务，也不会有任何内容离开你的电脑。

它解决的问题

如今所有主流助手都具备跨会话记忆，因此“我的 AI 没有记忆”已不再是问题。真正的问题是随之而来的情况：记忆被各家供应商割裂存储，格式无法导出，管理政策也不是由你制定的。

	没有 Hive	使用 Hive
记忆存储位置	各家供应商的服务器	你电脑上的文件
切换客户端	从零开始	任何 MCP 客户端都能使用同一份记忆
谁能写入	模型悄悄写入	模型只能 propose；由你确认
导出	一个“删除所有内容”按钮	记忆本来就在你的磁盘上
使用 3 个助手	3 份零碎的记忆，都不属于你	1 份记忆，3 个读取者

适用人群： 认真使用两个或更多 AI 助手，且已经厌倦了反复自我介绍的人。只用一个助手的话，供应商内置的记忆功能可能就够用了。

安装

pip install memory-hive-mcp

需要 Python 3.8+。无第三方依赖。安装后会提供命令 memory-hive-mcp。

（注意：PyPI 上的纯 hive-mcp 名称属于另一个无关项目——并非本项目。）

前置条件：正在运行的 Hive

memory-hive-mcp 会连接到你自己机器上的 Hive。可从 Mac App Store 获取：

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

然后在 Hive 内注册一个 Agent（POST /api/agent/register），以获取 agent_id 和 access_token。

需要 Hive 1.4.5 或更高版本。 更早版本中没有 say 和 board 工具——在 1.4.4 及以下版本中，只有前四个工具可用，调用 say 或 board 会失败。

此软件包无法独立运行。 它不包含记忆引擎、数据库或索引——只负责转发 MCP 流量。如果没有安装并运行 Hive 应用，你连接到的桥接服务后面就没有任何东西。我们特意在这里说明这一限制，而不是把它藏起来，避免有人误以为它是一个独立的记忆服务而安装。

目前 Hive 应用仅支持 macOS。桥接服务本身是纯 Python，可在任何地方运行，但它需要连接 Hive。

Hive 未运行时会发生什么

MCP 方法	Hive 未运行时
initialize	在本地应答——握手完成，协议版本为 2024-11-05。
tools/list	在本地应答——列出下方的工具。
tools/call	明确报错，指出 HIVE_MCP_URL 和 App Store 链接。不会虚构结果。

Hive 正在运行时，initialize 和 tools/list 会由 Hive 本身应答，因此你看到的工具列表、约束条件和协议版本始终是真实信息。

因此，目录爬虫、CI 检查或好奇的 pip install，即使在没有 Hive 的机器上也能看到工具列表——但任何实际的记忆操作都会如实失败，而不会假装成功。捏造一个空结果比报错更糟：调用方会误以为用户的记忆是空的。

配置你的 MCP 宿主

将服务添加到宿主的 MCP 配置中。以 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"
      }
    }
  }
}

环境变量

名称	必需	描述
HIVE_AGENT_ID	是	由你自己的 Hive 颁发的 Agent ID。
HIVE_AGENT_TOKEN	是	注册 Agent 时颁发的访问令牌。请妥善保密。
HIVE_MCP_URL	否	Hive MCP 端点。默认为 http://127.0.0.1:8768/mcp。

六个工具

每个工具都会声明自己的 MCP 注解，让宿主在阅读描述前就了解其安全属性：recall、get_context 和 board 为只读；propose 和 manage 则不是只读工具，且两者都未标记为破坏性操作（manage 中除 discard_pending 外的所有操作均可撤销）。 它们都不会访问开放互联网——桥接层只与本地 Hive 通信。

工具	方向	功能
recall	读取	对已确认的记忆进行语义搜索。{"query": "...", "limit": 10, "compact": true}——可选的 vaults 用于缩小搜索范围，query_vector 则切换为嵌入向量检索。用于回答具体问题；会话开始时应改用 get_context，并使用 manage list_pending 查看尚未获批的内容。
propose	写入 → 待处理	提交一条记忆供你审批。{"content": "..."}，还可选填 title、vault、tags、vector 和作为幂等键的 client_id。存在近似重复项时会返回 conflict_warning。成功响应表示已加入队列，而非已存储——内容会一直处于待处理状态，直到你接受。
manage	管理	按 action 路由：list_pending / forget（软删除，可用 restore 撤销）/ restore / get_by_id / discard_pending（唯一不可逆的操作）。通过 ID 或队列状态指定目标——要按主题搜索，请使用 recall。
get_context	会话开始	从当前活跃的线程和未完成任务中提取近期记忆，为对话提供背景。{"limit": 8}。基于时间新近程度，而非查询内容；要回答具体问题，请使用 recall。
say	协作	向共享看板发布消息。{"summary": "..."}，还可选填 to、kind（data/handoff/result）、stage（start/handoff/done/blocked）、task_id、refs、ttl。需要 Hive 1.4.5+。要读取看板，请使用 board。
board	协作	使用游标读取共享看板。{"limit": 20, "since": "<cursor>"}——设置 roster: true 还会返回当前值班人员。消息会过期，因此结果为空可能表示消息已过期。需要 Hive 1.4.5+。

典型会话流程：打开时调用 get_context → 对话过程中调用 recall → 当你说“保留这个”时，调用 propose → 你在 Mac 上的 Hive 中确认。

共享账本，而不只是共享存储

say 和 board 让 Hive 不再只是一个记忆表：它成为多个 Agent 和一位用户共同维护同一本账本的地方。

一个 Agent 发布刚完成的内容（say）；另一个 Agent 按自己的安排查看（使用游标调用 board）——没有推送，不会唤醒任何人，中间也没有编排器。 身份由凭证决定，而不是由调用方可设置的字段决定，因此一个 Agent 不能冒充另一个 Agent 发言，用户也能在同一线程中看到每次交接。

你的 Agent 可以提议，但不能决定

这是本服务与记忆缓存的关键区别。

**Agent 可以 propose 一条记忆，但不能确认它。**写入的内容会进入待处理队列，并一直留在那里，直到你在自己的 Hive 中接受。没有 self-confirm，没有静默的后台写入，也没有任何途径让模型悄悄决定关于你的哪些内容属实。

记忆按知识库划分，边界由 Hive 强制执行——在服务端进行检查，而不是依赖提示词中的承诺：

Agent 类型	公共知识库	私有知识库
云端 Agent（mcp / mobile）	✅ 开放	🔒 封闭
本地 Agent（非云端）	✅ 开放	✅ 开放

注册表中不存在的 Agent 默认无法访问。未经授权查看某条私有知识库记录的 Agent，无法读取、删除或恢复该记录。

为什么是桥接层，而不是捆绑包

你的记忆应该只有一个写入方：你机器上的 Hive。因此，此服务只负责协议，不做其他事情——不会打开数据文件，不会缓存状态，也不会重复实现引擎。这样可以确保你的记忆数据来源单一、保存在本地，并由你掌控。

状态

Alpha（0.x）。线协议已稳定；配置和工具签名仍可能变更。版本间的变更请参阅 CHANGELOG.md。

平台。 Hive 应用（此桥接层连接的记忆引擎）目前仅提供 macOS 版本——App Store。Windows 和 Linux 版本正在开发中；桥接层本身是纯 Python，可在任何平台运行，但需要连接到 Hive。

没有基准测试。 我们有意不发布检索基准测试。在检索排行榜上，我们会输给专门构建的向量存储，而且我们也没有声称自己能胜过它们。我们所做的承诺范围更窄，也可以验证：数据保存在你的机器上，写入权限由你掌控。

链接

• 代码仓库：https://github.com/330899935/memory-hive-mcp
• 项目主页：https://hello-fengchao.com
• MCP 集成文档：https://hello-fengchao.com/mcp.html
• 软件包：https://pypi.org/project/memory-hive-mcp/
• 安全策略：SECURITY.md

许可证

MIT