Hive Vault Skill 技能

Hive Vault — 让 AI 编程助手永久记住你的项目上下文

hive-vault 是一个把 AI 编码助手与 Obsidian 知识库打通的 MCP 服务器。它的命题很直接：现在的 AI 助手每次开会话都把上下文清零，于是你不得不反复粘贴项目背景。Hive Vault 走"按需检索"路线——不一次性灌入 800 行项目背景，而是按 Agent 的真实问题去 Obsidian vault 拉相关条目，把单次查询的 token 成本压到传统方案的 6% 左右，同时保留 100% 的项目记忆。它用 Obsidian 兼容的 markdown 仓库作为存储层，原生支持 git 版本回溯、Obsidian Git 插件自动提交、可选 Ollama / OpenRouter 后端跑本地或免费的 worker 委派。

核心能力

• MCP 标准接入：一行 claude mcp add -s user hive -- uvx --upgrade hive-vault 把它接入 Claude Code，Gemini CLI、Codex、Cursor、Windsurf 等也都有对应命令。
• 按需上下文加载：默认每次会话从约 800 行静态上下文降到 50 行"按需检索"，token 成本降为传统方式的 6%（项目实测：19 个项目、200+ 文件的 vault）。
• 完整的 Vault 操作工具集：vault_list / vault_query / vault_write / vault_patch / vault_read / vault_commit 等工具覆盖读取、改写、版本控制全流程。
• 可选本地 worker：delegate_task / capture_lesson 可调用本地 Ollama（如 qwen2.5-coder:7b）做免费委派，OpenRouter 作为付费 / 免费 fallback。
• Git 自动提交：与 obsidian-git 插件搭配，vault_write(commit=False) 把写盘与提交解耦，主路径写盘、副路径异步 git commit。
• 守护进程模式：hive serve 启动一个常驻守护进程管理 vault，stdio-only 客户端通过 hive client 连入，端口按用户确定性派生（49152..65535），可被 HIVE_DAEMON_PORT 覆盖。
• 健康与安全可观测：vault_health 暴露 ## external_committer 与 ## ghost_responses 计数，工具被取消时也会发出 mcp.ghost_response.suppressed_after_cancel_ack 警告，避免重复写盘。
• 优雅降级：没有 vault 也能启动——VAULT_PATH 未配置时所有 vault 工具返回友好错误，配置好之前不会阻塞其它功能。
• 跨客户端支持：详细配置覆盖 Claude Code、Codex CLI、GitHub Copilot、Cursor、Windsurf、Gemini CLI。

安装配置

1. Python 环境：需要 Python 3.12 或更新版本（同时支持 3.13）；通过 uvx --upgrade hive-vault 自动管理虚拟环境。
2. 准备 Vault：任选一个 markdown 目录作为 vault；可选结构 00_meta / 10_projects / 50_work / 80_agents 让 Hive 自动识别作用域。
3. 接入 MCP 客户端：Claude Code 跑 claude mcp add -s user hive -- uvx --upgrade hive-vault；要换 vault 路径，加 -e VAULT_PATH=$HOME/path/to/vault。
4. （推荐）初始化 git：在 vault 目录运行 git init 并安装 obsidian-git 插件，把 auto-commit 间隔设为 5–10 分钟。
5. （可选）配置本地 worker：装 Ollama 并下载 qwen2.5-coder:7b；OpenRouter 用户配 OPENROUTER_API_KEY 环境变量。
6. （可选）守护进程模式：长期使用可启动 hive serve 守护进程，stdio-only 客户端用 hive client 连接，避免每次 session 重建。

使用步骤

1. 完成配置：按上文配置好 MCP 客户端与 VAULT_PATH，运行 claude mcp list 确认 hive 已注册。
2. 触发首次读取：在 Claude Code / Cursor 里对 Agent 说"用 vault_list 看看我的 vault"，确认 vault 已可访问。
3. 写入新条目：用 vault_write(path="10_projects/alpha.md", content="...") 写入新内容，建议传 commit=False 让 obsidian-git 异步提交。
4. 按需查询：让 Agent 跑 vault_query("alpha 项目架构")，Hive 会 BM25F 检索相关条目并返回带出处的内容块。
5. 批量改写：批量修改走 vault_patch(commit=False)，避免主路径被 git 卡住；批次结束手动调 vault_commit(message="checkpoint")。
6. 健康巡检：定期跑 vault_health，观察 external_committer 与 ghost_responses 计数，发现异常先 vault_query 校验再决定是否重试。
7. 升级：uvx 安装方式只需 uvx --upgrade hive-vault；守护进程模式需要重启 hive serve 让新版本生效。
8. 跨设备同步：（推荐）把 vault 推到私有 GitHub remote，避免本机磁盘故障丢失历史。

适用场景

• 跨会话的编程助手：让 Claude Code / Cursor 持续记住你的项目架构、命名约定、未完成 TODO。
• 个人 / 团队知识库：把 Obsidian vault 直接喂给 AI，写笔记即沉淀为可被 Agent 引用的知识。
• 研究与写作：用 Hive 把论文笔记、研究日志喂给 Agent，自动回答"上周我在 X 项目上解决了什么"这类问题。
• 本地优先的 AI 工作流：不想把笔记传到云端？Hive + 本地 Ollama 跑通纯本地的"记住 + 检索"。
• 多代理协作：Hive 在 Claude Code / Codex / Cursor / Gemini CLI 之间共享同一个 vault，Agent 切换不丢上下文。
• 长周期项目：超过一周以上、需要多轮会话接力的项目，Hive 替代"反复粘贴背景"的人工操作。

适用人群

• 用 Claude Code / Cursor / Codex 做开发的工程师与架构师；
• 已经在用 Obsidian 做笔记的知识工作者、研究员、作家；
• 想让 AI 助手"记住"项目背景但又不愿意把笔记传到云端的隐私敏感用户；
• 维护长周期项目、需要跨会话衔接工作的技术负责人；
• 折腾本地 LLM（Ollama）+ 知识库组合的 AI 爱好者。

工作原理

Hive Vault 是一个 stdio/HTTP MCP 服务器，背后挂一个本地 Obsidian vault。它不做"启动时全量加载"，而是把 vault 当成检索库：每次 Agent 调 vault_query / vault_read 时，用 BM25F + 链接遍历定位相关 markdown，再把原文片段以 MCP 内容块的形式返回。写路径走 vault_write / vault_patch，先把变更落盘，再用 obsidian-git 插件的 5–10 分钟自动 commit 把 git 操作挪出主调用路径，因此即使 commit 慢也不阻塞 MCP 响应。worker 委派走 delegate_task，默认调本地 Ollama 上的 qwen2.5-coder:7b 做免费 worker，没有本地模型时回落到 OpenRouter 免费档。守护进程模式进一步把"vault 拥有者"拆成常驻 hive serve（管理文件系统 / git / vault state）与短生命周期的 hive client（每个 MCP session 一个），端口在 49152–65535 区间按用户哈希派生，token 持久化避免频繁认证。所有错误都"fail closed"——遇到端口冲突、credential 缺失、vault 损坏等场景，绝不静默换端口或假装成功，而是明确报错让用户处理。

官方链接

• PyPI 包：https://pypi.org/project/hive-vault/
• 文档：https://mlorentedev.github.io/hive/
• GitHub 仓库：https://github.com/mlorentedev/hive
• 安装命令：uvx --upgrade hive-vault
• MCP 接入：claude mcp add -s user hive -- uvx --upgrade hive-vault