Hive Vault

hive-vault

你的 AI 编码助手会忘记之前会话中的所有内容。Hive 能解决这个问题。

Hive 是一个 MCP 服务，可将你的 AI 助手连接到 Obsidian 知识库。它不会一开始就加载所有内容，而是按需查询所需内容。

指标	不使用 Hive	使用 Hive
每个会话加载的上下文	~800 行（静态）	~50 行（按需）
上下文的 Token 成本	每个会话 100%	五次项目上下文查询仅需 0.6%（真实知识库，共 493K 个 Token）
会话间保留的知识	0%	100%（保存在知识库中）

只有 Token 成本这一行是测量值（在一个包含 493K 个 Token 的真实知识库上执行 5 次项目上下文查询；方法和数据见基准测试）。行数和知识保留情况描述的是两种设置的工作方式，并非测量结果。

快速开始

Hive 可在没有知识库的情况下运行——在设置 VAULT_PATH 之前，知识库工具会返回友好的错误，因此你可以先安装，之后再配置。

# Minimal — uses default vault path ~/Projects/knowledge
claude mcp add -s user hive -- uvx --upgrade hive-vault

# With a custom vault path
claude mcp add -s user hive -e VAULT_PATH=$HOME/path/to/vault -- uvx --upgrade hive-vault

# Gemini CLI
gemini mcp add -s user -e VAULT_PATH=$HOME/path/to/vault hive-vault uvx -- --upgrade hive-vault

默认知识库路径：~/Projects/knowledge。可按上文所示，通过 VAULT_PATH（或 HIVE_VAULT_PATH）覆盖。

对于 Codex CLI、GitHub Copilot、Cursor、Windsurf 和其他客户端，请参阅入门指南。

然后向助手提问：“使用 vault_list 查看我的知识库”

要求

Hive 可以平稳降级——每个推荐或可选依赖都能带来更多功能，同时不会影响基本功能。

• 必需

  • Python 3.12+（兼容 3.13）。
  • 一个 Markdown 文件目录。00_meta / 10_projects / 50_work / 80_agents 所采用的知识库结构为可选项——没有该结构时，知识库工具仍可运行，但范围路由会采用扁平模式。

• 推荐

  • 在知识库内初始化 git。如果没有，vault_write / vault_patch 仍会写入磁盘，只是跳过每次写入时的提交（而 vault_commit 会将工作区报告为未跟踪状态）。
  • 使用 Obsidian 桌面应用手动编辑知识库。
  • 使用 obsidian-git plugin 插件，并将自动提交间隔设为 5–10 分钟。将其与 vault_write(commit=False) / vault_patch(commit=False) 配合使用，可将 git 工作负载移出同步工具调用路径；详见下文的推荐配置。

• 可选

  • 将任意 OpenAI 兼容的 /v1 端点用作 delegate_task / capture_lesson 的工作器，并通过 HIVE_WORKER_BASE_URL、HIVE_WORKER_API_KEY 和 HIVE_WORKER_MODEL 设置。
  • 一个备份 git 远程仓库（例如私有 GitHub 仓库），让知识库历史记录在磁盘丢失后依然留存。

推荐配置

根据 ADR-006（提交策略），对于写入密集型流程，建议采用以下组合：

1. 在你的库中安装并启用 obsidian-git 插件。
2. 将其自动提交间隔设为 5 或 10 分钟。
3. 所有批量操作都调用 vault_write(..., commit=False) 和 vault_patch(..., commit=False)。
4. 可选：在会话结束时调用 vault_commit(message="...")，以便在 obsidian-git 定时触发前强制创建检查点。

当检测到库中存在 obsidian-git 时，vault_health 会报告一个 ## external_committer 区块。commit=False 的持久性约定十分明确：无论如何，文件都会写入磁盘；延后的只有提交。如果在下一次刷新前发生崩溃，丢失的是提交，而不是内容。

工具调用在执行过程中被取消时（工作进程缓慢、客户端超时），取消确认到达传输线路前，服务可能已经修改了磁盘。对于每个此类事件，vault_health 都会显示 ## ghost_responses 计数器，并发出 mcp.ghost_response.suppressed_after_cancel_ack WARNING——请通过 vault_query 核实状态，而不要重试，因为 ErrorData 确认并不表示已回滚（ADR-007）。

守护进程模式（可选）

默认情况下，uvx hive-vault 会在每个会话启动一个新的服务。守护进程模式则会运行一个长期存续的 hive serve 来管理库，每个仅使用 stdio 的会话通过 hive client 连接。适配器启动时不会导入 Hive 服务或 FastMCP，而是将 JSON-RPC 转发到守护进程稳定的环回端点。如果守护进程或凭据不可用，它会明确报错，而不会启动另一个进程内管理者。

默认端点是为每位用户确定性分配的 49152..65535 范围内的端口，因此普通的守护进程重启不会使客户端配置失效。如果计算出的端口与其他本地服务冲突，可在守护进程和每个客户端环境中通过 HIVE_DAEMON_PORT 覆盖。hive serve --port 只会更改守护进程的绑定端口；它不会重新配置 hive client 或 hive delegate。Hive 会直接失败关闭，不会静默切换到其他端口。仅限所有者使用的 bearer token 会在守护进程状态目录中持久保存，普通重启不会使其失效。daemon.port 仍是用于迁移诊断的元数据，而不是客户端发现状态。请参阅 ADR-022。

安全暂停： 在#456解决之前，请勿在不可信的多用户主机上部署守护进程模式。该端点使用 TLS，并提供 Hive 客户端会固定验证的每用户证书，因此固定端口上的冒名者会在发送任何 bearer 之前于握手阶段失败；在记录 Linux 和 Windows 证据（包括跨用户检查）之前，此暂停措施将继续有效。

uv tool install --upgrade hive-vault   # >= 1.32.0
hive service install                   # supervise hive serve (systemd --user / Task Scheduler)
hive service status                    # exit 0 only if the listener proves the daemon's certificate

在 MCP 宿主中运行 hive client。能够验证守护进程证书的宿主可以直接连接到 https://127.0.0.1:<derived-or-overridden-port>/mcp（对于基于 Node 的宿主，可将 NODE_EXTRA_CA_CERTS 指向状态目录中的 daemon.crt）；绝不要禁用验证，并请注意，http:// 已不再可用。绝不要将 token 打印或复制到日志或 Shell 历史记录中。

若要安装较新的版本，请使用对应平台的命令：

# Linux / macOS
uv tool upgrade hive-vault

# Windows (the version is optional; omitted selects the latest PyPI release)
hive self-upgrade [version]

在 Windows 上，self-upgrade 会在运行中的文件旁构建发行版，并以原子方式切换受管理的运行时，从而避免文件正在使用时发生冲突。首次执行受管理的升级后，请打开新的终端，以便使用 PATH 中的更改。由监督程序管理后，守护进程会检测到新安装的版本，以状态码 75 退出，然后由监督程序重启并运行新代码。请参阅守护进程模式指南和激活操作手册。

工具

工具	功能
vault_query	加载项目上下文、任务、路线图、经验教训，或按路径加载任意文件
vault_search	全文搜索，支持元数据筛选、正则表达式、结果排序、最近更改以及经验教训使用情况排序（rank_by）
vault_list	浏览项目和文件，支持 glob 筛选
vault_ask	可选的语义问答，附带来源引用；配置嵌入后端前处于禁用状态（[semantic] extra）
vault_health	服务身份信息（版本、知识库路径、后端）、运行状况指标、偏差检测、使用统计，以及可选启用的运行时区块
vault_write	创建、追加或替换知识库文件。commit=False 会延迟 git 提交，以便批量处理
vault_patch	精准查找并替换。commit=False 会延迟 git 提交，以便批量处理
vault_commit	将待处理的 commit=False 写入合并为一次 git 提交
vault_delete	删除单个文件，并同步提交，使其可从 git 历史中恢复
capture_lesson	直接记录经验教训／从文本中批量提取／按关键词查找现有经验教训（find=）
session_briefing	一次调用即可获取任务、经验教训、git 日志和运行状况
delegate_task	将任务分配给成本更低的模型，或总结知识库文件
worker_status	预算、连接状态、可用模型

此外，还提供 5 个资源和 4 个提示词，用于引导工作流。

经验教训强化

每次通过 vault_query、vault_search 或 capture_lesson(find=…) 读取经验教训，都会增加计数器，并使该经验教训的置信度渐近提升至 1.0。随着时间推移，经过验证的经验教训会比一次性记录的内容排名更高。

# Surface the top-ranked lessons matching a keyword
capture_lesson(project="hive", find="multi-process")

# Search lessons ranked by usage signal (not BM25)
vault_search(query="timeout", rank_by="reinforcements")    # most-reinforced first
vault_search(query="timeout", rank_by="confidence")        # highest decayed confidence
vault_search(query="timeout", rank_by="hybrid")            # α=0.7 BM25 + 0.3 confidence

存储：位于 HIVE_LESSON_DB_PATH 的 SQLite 旁表（默认值为 ~/.local/share/hive/lesson_reinforcement.db）。WAL 模式和 busy_timeout 可确保跨进程安全。

架构

MCP Host (Claude Code, Gemini CLI, Codex CLI, Cursor, ...)
    └── hive-vault (MCP server, stdio)
            ├── Vault Tools (9) ── Obsidian vault (Markdown + YAML frontmatter)
            ├── Session Tools (1) ── Adaptive context assembly
            └── Worker Tools (3) ── one OpenAI-compatible endpoint, no internal fallback

文档

完整文档请访问 mlorentedev.github.io/hive：

• 入门指南 — 为所有 MCP 客户端安装
• 配置 — 全部 19 个环境变量
• 知识库结构 — 如何组织知识库
• 使用案例 — 实际工作流
• 架构 — 模块图和设计决策
• 故障排除 — 常见问题及解决方法

项目相关知识（文档即代码）位于 docs/：

• docs/adr/ — 架构决策记录
• docs/runbooks/ — 操作流程
• docs/troubleshooting/ — 已知问题和根因分析
• docs/lessons.md — 累积的问题记录和事后复盘

贡献

设置和 PR 工作流请参阅 CONTRIBUTING.md。

git clone https://github.com/mlorentedev/hive.git && cd hive
make install   # create venv + install deps
make check     # lint + typecheck + test (478 tests, 90% coverage)

许可证

MIT