Apiary Memory

Apiary Memory MCP

也称为： Apiary Memory · 记忆蜂巢 · Memory Hive · 蜂巢 · PyPI 上的 apiary-memory，以及 MCP Registry 上的 io.github.330899935/apiary-memory（从 v0.2.0 开始）· 旧名称 memory-hive-mcp / hive-memory（v0.1.9 及更早版本）仍可安装，也仍能正常使用。 与 hive.com（团队协作）或 hive-mcp Claude Code 插件无关联。

通过 MCP 为 AI Agent 提供本地优先的个人记忆。 你的 Agent 可以搜索你已确认的内容，也可以提议它们认为你应该保留的内容；只有你能确认。 所有内容都存储在你自己磁盘上的一个文件中，不会发送到任何地方。

它可独立运行。此软件包内置了可用的 SQLite 记忆存储——无需账户、云服务、守护进程或依赖项。

pip install apiary-memory

无需终端的桌面应用： 下载 apiary-memory-0.2.0.mcpb，然后双击打开。

数据测量于 2026-10-27，使用一台本地运行 Hive 的 MacBook——脚本和原始输出见 bench/：

指标	结果
搜索延迟	p95 111 ms，p50 76 ms（预热后，包含 HTTP）
检索	在 40 次试验中，有 97.5% 的正确条目位于前 5 条
语料	1,303 个条目 · 2.39 M 字符 · 45 天，仅纯文本

检索时使用了每个条目自身的标题作为查询——这是一个简单的数据集。它表明索引完整，且能按精确词条正确排序，并不能说明它用你自己的话提问时回答得有多好。可以在自己的 Hive 上运行 bench/bench_search.py。

---

不使用应用时，你能获得什么

一个完整但功能朴素的记忆服务。在没有安装其他软件的机器上：

调用	执行内容
initialize	在本地处理，协议版本为 2024-11-05
tools/list	在本地处理，提供六种工具
propose	写入磁盘上的真实数据库
recall	搜索该数据库并返回排序后的条目
get_context	汇总你最近确认的内容
manage	读取一个条目、列出待处理内容、遗忘、恢复
say / board	用于协调多个 Agent 的共享留言板

默认使用 SQLite 存储于 ~/.memory-hive/hive.db。搜索采用词法匹配——中文使用字符二元组，拉丁字母使用单词——因此词语重合时排序效果好，不重合时则无法找到。没有嵌入，也没有向量索引。每个响应都包含 "mode": "local"，因此你始终能知道是哪个引擎给出了响应。

不使用应用时，数据库是普通 SQLite 数据库：未加密。 我们在这里明确说明，避免你之后才发现——参见诚实说明的限制。

应用提供的功能

适用于 macOS 的 Apiary Memory 采用相同的设计，并实现了成本较高的部分：八个保险库，其中四个由 PIN 码保护（使用 Argon2id 封装密钥，静态数据采用 AES-256 加密）、每日演进日志、多 Agent 身份管理，以及用于阅读和确认内容的 UI。它也能直接响应 MCP 请求，并提供更丰富的排序功能。

如果应用正在运行，此软件包会使用它，并保持本地文件不变。如果应用未运行，则由本地存储响应。你不必预先做出选择：

HIVE_MODE	行为
auto（默认）	请求应用。仅当应用无法连接时才使用本地存储。
local	绝不连接网络。始终使用本地存储。
remote	仅使用应用。连接失败会报错，不会切换目标。

所有模式都遵循一条规则：如果应用正在运行并返回错误，该错误将原样返回。 如果应用拒绝请求时改为回退，客户端会以为自己访问的是应用，记忆却被写入第二个数据库。无提示地分叉数据比报错更糟，因此应用一旦回复，该回复就是最终结果。只有连接失败时才会触发回退，其他情况一概不会。

安装

pip install apiary-memory        # the server: apiary-memory (was apiary-memory)
                                 # the human's CLI: apiary-memory-cli (was apiary-memory-cli)

需要 Python 3.8 或更高版本。无需安装其他内容——此软件包仅使用标准库，sqlite3 也包含在其中。

从代码检出目录安装：

git clone https://github.com/330899935/apiary-memory
cd apiary-memory
PYTHONPATH=src python -m hive_mcp.stdio

连接客户端

任何能够运行 stdio 命令的 MCP 主机都可以使用。最低要求是命令；其他内容均为可选。

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "apiary-memory": {
      "command": "apiary-memory",
      "env": { "HIVE_MODE": "local" }
    }
  }
}

Cursor — ~/.cursor/mcp.json，使用相同的 mcpServers 结构。

仅支持 HTTP 的主机 — 启动应用，并将其指向 http://127.0.0.1:8768/mcp，同时设置请求头 X-Hive-Agent 和 X-Hive-Token。此软件包提供 stdio 接入方式；HTTP 端点属于应用。

前置条件

本地存储无需任何前置条件——安装软件包即可使用。只有在使用应用自身的功能时，才需要先运行应用：加密保险库、演进日志和多 Agent 身份。如果需要这些功能，请安装 the Hive app（macOS，版本 1.4.5 或更高），并让 HIVE_MODE 保持为 auto。

六种工具

全部功能就由这六种工具构成。无论由应用还是本地存储响应，都是相同的六种工具；不同之处仅在于其背后的排序方式，以及对于两种输入，这些工具是否存在。应用接受预先计算的嵌入向量（recall.query_vector、propose.vector）；本地存储没有嵌入器，因此在本地存储能够响应的所有情况下，tools/list 都不会列出这两种工具，包括应用可能在会话中途停止响应的 auto 模式。某个字段如果会被接受后悄然忽略，就根本不会被公开。

同一规则也适用于描述。在本地存储能够响应的情况下，recall.query 会被描述为词法排序器——基于词语和字符二元组，不使用嵌入向量；在只有应用能够响应的情况下，则会被描述为基于应用索引的排序，并使用 query_vector 理解语义。描述是在说明输入会如何处理，因此会随可用输入而调整。

默认值不会调整，而是共用的。省略 limit 时，recall 会返回 10 条，get_context 会返回 8 条；省略 compact 时，返回的正文会经过精简；调用 say 时省略 ttl，卡片有效期为 24 小时。两个引擎对这些数字的处理完全一致，因为默认值是架构中的一个数字，而不是某个引擎不具备的能力。store.py 将每个默认值都定义为一个命名常量，测试会将响应与公开的数字进行比较，而不是与另一份手写副本比较。

工具	类型	用途
recall	读取	按主题搜索已确认的记忆。使用 {"query": "..."}，以及可选的 limit、vaults、compact。
propose	写入	提交一条记忆，等待人工批准。内容会进入队列，不会更改任何已确认的记忆。
manage	读取/写入	管理单条记录：list_pending、get_by_id、forget、restore、discard_pending。
get_context	读取	获取近期已确认记忆的简短摘要，为对话提供上下文。
say	写入	发布到共享公告板，让其他 Agent 看到已完成或已移交的事项。
board	读取	读取公告板，也可以只读取上次游标之后收到的内容。

有两点值得明确说明，因为它们体现了产品的设计：

• propose 成功表示“已加入队列”，而非“已存储”。 只有人工确认后，recall 才会返回这条记忆。
• manage 没有 approve 操作。 Agent 没有任何途径可以创建已确认的记忆。这不是遗漏，而是设计如此。

响应结构

tools/list 是两个引擎共用的接口，回答也应如此：如果模型必须根据哪个引擎给出了响应来分支处理，最终总会分错。因此，board 会逐字段匹配应用的结构——items、unread、count、cursor、reader——而 cursor 是最新卡片的 ID，与应用返回的值类型相同。

游标是在切换引擎时轮询所携带的值，这就是为什么它要占用空间。在 auto 模式下，一次调用可能由应用响应，下一次则由本地存储响应。在 0.1.9 之前，本地引擎会响应一个浮点纪元时间戳，并用 float() 读取应用的卡片 ID，因此从应用获取的游标会导致重新读取整个看板，而且不会有任何提示；反过来，发送浮点数时也无法匹配任何卡片 ID，应用会同样悄无声息地返回最新的 limit 条卡片。

游标仍可能无法解析：它对应的卡片已过期（默认卡片保留 24 小时），或者它由另一个引擎发出，应用中的 ID 为 CB…，而本地的 ID 为 msg_…。两个引擎都无法从此处继续，因此都会返回最新窗口——但这时还会设置 since_unknown，并通过 note 说明发生了哪种情况。unread 统计游标之后所有仍有效的卡片，count 统计本次响应包含的卡片，因此 unread > count 表示这一页未涵盖所有待处理内容，note 会用文字说明这一点。

以下三种结构不会统一，因为两个引擎实际持有的数据不同：

• recall 条目在本地存储中使用 vault 表示其知识库，在应用中则使用 wh；
• get_context 在本地返回一个扁平的 digest，在应用中则按每个仓库返回一个分组（context，以仓库名称为键）；
• roster 条目都包含 agent_id；本地条目还包含 messages 和 last_seen，而应用会添加其注册卡片——显示名称、席位、租约和当前任务——这些信息 SQLite 文件无从得知。

确认 Agent 提出的内容

Agent 提出建议。你来确认。确认操作在终端中，通过你必须输入的命令完成——这是有意设计的，不能让 Agent 调用工具来执行。

apiary-memory-cli list                 # what is waiting
apiary-memory-cli show <id>            # read one in full
apiary-memory-cli approve <id>         # confirm it, or --all
apiary-memory-cli reject <id>          # drop it for good
apiary-memory-cli search "deploy key"  # search confirmed memory
apiary-memory-cli forget <id>          # soft delete, reversible
apiary-memory-cli restore <id>         # undo forget
apiary-memory-cli stats                # counts and the database path
apiary-memory-cli export --out dump.json
apiary-memory-cli path

任何命令中的 --db <path> 都可以指定其他数据库。环境变量 HIVE_DB 也能达到相同效果。

记忆存储位置

默认位于 ~/.memory-hive/hive.db，除非 HIVE_DB 另有指定。它是一个 SQLite 文件；复制即可备份，删除即可重新开始。

看板会将消息保存在同一个文件中，因此始终只需备份一个文件。卡片会过期：默认保留 24 小时，除非另行设置 ttl；其值会限制在 60 秒至 30 天之间，与应用的行为一致——看板要是无限增长，就不再是看板了。

搜索的工作方式及其局限

中文文本按单字和重叠的双字字符组建立索引；拉丁文本则按单词建立索引。查询结果会根据条目覆盖查询内容的程度评分，再按新近程度微调——乘以 10%，足以打破平局，但不足以颠覆相关性排序。

这是排序器，不是理解器。

• 分数是相对的。 0.8 表示“对这次查询而言比 0.4 更接近”，而不是“有 80% 的把握”。不同查询之间的分数不可比较。
• 不支持语义召回。 查询“money”时，只提到“invoice”的条目不会被找到。覆盖相关词需要嵌入模型；这个软件包没有依赖项，也不会假装有。
• 排序方式就是描述中所述的方式。 此处的 tools/list 表明使用“单词和双字字符组……不使用嵌入”，这句话对该引擎而言属实。它会针对每个引擎分别说明，就像嵌入输入也会因引擎而异一样，因为应用对同一个问题会给出不同的回答。
• 未命中就会如实报告未命中。 没有匹配项时，recall 会明确说明，并指出有多少条目正等待确认，而不会返回一个看似合理的相近结果。

配置

变量	默认值	用途
HIVE_MODE	auto	auto、local 或 remote — 参见上表
HIVE_DB	~/.memory-hive/hive.db	本地数据库的存储位置
HIVE_MCP_URL	http://127.0.0.1:8768/mcp	应用的端点
HIVE_AGENT_ID	—	应用中的 Agent ID；仅用于由应用提供服务的调用
HIVE_AGENT_TOKEN	—	应用提供的访问令牌；仅用于由应用提供服务的调用

使用本地存储不需要 HIVE_AGENT_ID 和 HIVE_AGENT_TOKEN。本软件包会直接从环境中读取它们，绝不会将其写入磁盘。

诚实说明局限

把这些写清楚，因为夸大自身能力的记忆工具，比能力有限的工具更糟糕。

1. 本地存储未经加密。 使用纯 SQLite。任何能读取你的主目录的人都能读取其中内容。应用的保险库是加密选项，而 stats 会报告 "encrypted": false，不会让你自己去发现这一点。
2. 不支持语义搜索，如上所述。
3. 同一时间只能有一个写入者。 WAL 模式允许 CLI 在服务连接时确认内容，但这是个人记忆文件，不是多主机服务。不要让两台机器通过网络共享指向同一个数据库。
4. 看板用于协调，而非记忆。 消息用于 Agent 之间交接；无法通过 recall 搜索。
5. 该应用仅支持 macOS。 本地存储则不受此限——它是纯 Python 实现。

故障排除

有待处理条目时提示“no confirmed memory matched this query”。 这是正常行为。请确认这些条目：运行 apiary-memory-cli list，然后运行 approve。

调用失败并提示 HIVE_AGENT_ID 相关信息。 应用已响应，但拒绝了凭据。调用不会回退到本地存储，这是有意设计的。请在应用中注册 Agent 并设置两个变量；如果你想使用本地文件，则设置 HIVE_MODE=local。

提示“Hive app not reachable ... and HIVE_MODE=remote forbids the local fallback”。 你要求仅使用应用，但应用并未运行。请启动应用，或移除 HIVE_MODE=remote。

我的记忆去哪儿了？ apiary-memory-cli stats 会打印数据库路径。如果 HIVE_MODE 为 auto 且应用正在运行，则由应用处理请求——按照设计，本地文件不会被触及。

开发

PYTHONPATH=src python -m unittest discover -s tests -v

测试套件无需运行中的应用，也无需网络：需要真实响应时，它会启动自己的模拟后端，并将 HIVE_DB 指向临时文件，因此测试绝不会触及真实的记忆数据库。

目录结构：

src/hive_mcp/store.py   the memory engine (SQLite, stdlib only)
src/hive_mcp/stdio.py   the MCP server: routing, envelopes, the app bridge
src/hive_mcp/cli.py     the human's half: review and confirm
src/hive_mcp/tools.json the tool surface snapshot for the offline path

许可证

MIT。你的记忆文件归你所有；此处没有任何内容会偷偷向外发送数据。