Hive 是一个 MCP 服务器，用于把 AI 编程助手连接到 Obsidian 知识库（vault），解决 AI 助手在会话之间遗忘上下文的问题。它不预先加载全部内容，而是按需查询所需信息。
用途与定位 Hive 定位为“AI 辅助开发的上下文基础设施”。它让 AI 助手能够访问 Obsidian 知识库中的 Markdown 文件，按需检索项目知识、文档和经验教训，而不是把整个知识库塞进上下文。
主要能力
- 按需访问 Obsidian 知识库，自适应加载上下文。
- 全文搜索与排序搜索。
- 知识库健康检查（vault_health），可报告外部提交者、幽灵响应计数等状态。
- 自动 git 提交：vault_write / vault_patch 可写入磁盘并提交，也支持 commit=False 延迟提交。
- 任务委派：delegate_task / capture_lesson 可调用兼容 OpenAI 的 /v1 端点作为 worker，将任务交给更便宜的模型。
- 课程强化：每次通过 vault_query、vault_search 或 capture_lesson(find=…) 读取课程，都会增加计数并使其置信度渐近趋向 1.0，经过验证的课程排序更高。
- 提供 5 个资源和 4 个提示词用于引导工作流。
使用方式 Hive 通过 MCP 协议与 AI 助手集成。默认使用 uvx hive-vault 为每个会话启动新服务器；也可选守护进程模式，运行一个长期存活的 hive serve 拥有知识库，各 stdio 会话通过 hive client 连接。默认知识库路径为 ~/Projects/knowledge，可通过 VAULT_PATH 或 HIVE_VAULT_PATH 覆盖。未设置 VAULT_PATH 时，知识库工具会返回友好错误，因此可以先安装后配置。安装后可以向助手发出指令，例如“Use vault_list to see my vault”。
依赖与配置 必需：Python 3.12+（兼容 3.13）；一个包含 Markdown 文件的目录。知识库结构（00_meta / 10_projects / 50_work / 80_agents）是可选的，没有该结构时知识库工具仍可运行，但范围路由是扁平的。 推荐：在知识库内初始化 git；使用 Obsidian 桌面应用手动编写知识库；使用 obsidian-git 插件并将自动提交间隔设为 5–10 分钟，配合 vault_write(commit=False) / vault_patch(commit=False) 将 git 工作负载移出同步工具路径。 可选：任何兼容 OpenAI 的 /v1 端点作为 delegate_task / capture_lesson 的 worker，通过 HIVE_WORKER_BASE_URL、HIVE_WORKER_API_KEY、HIVE_WORKER_MODEL 设置；备份 git 远程仓库（如私有 GitHub 仓库）以便磁盘丢失后保留历史。
适用场景 适用于希望 AI 编程助手跨会话记住项目知识、文档、架构决策记录（ADR）、运行手册、故障排查记录和经验教训的开发者。项目相关知识以 docs-as-code 形式存放在 docs/ 目录中，包括 docs/adr/、docs/runbooks/、docs/troubleshooting/、docs/lessons.md。
限制与注意事项
- 守护进程模式存在安全保留：在 #456 解决之前，不要在不受信任的多用户主机上部署守护进程模式。
- 工具调用中途取消时，服务器可能已在取消确认到达前修改磁盘；vault_health 会显示 ghost_responses 计数并发出警告，应通过 vault_query 验证状态而非重试，因为 ErrorData 确认不意味着回滚。
- 守护进程模式默认端点使用 49152..65535 范围内的确定性每用户端口，可通过 HIVE_DAEMON_PORT 覆盖；hive serve --port 只改变守护进程绑定端口，不会重新配置 hive client 或 hive delegate。
- 不要禁用证书验证，http:// 不再可用；不要将令牌打印或复制到日志或 shell 历史中。
- 课程强化数据存储在 SQLite 侧表，默认路径 ~/.local/share/hive/lesson_reinforcement.db，使用 WAL 模式和 busy_timeout 保证跨进程安全。
更多文档见 mlorentedev.github.io/hive，包括 Getting Started、Configuration（全部 19 个环境变量）、Vault Structure、Use Cases、Architecture、Troubleshooting。
