Connects AI coding assistants to Obsidian vaults to provide on-demand context and persistent knowledge between sessions.
Also known as mlorentedev/hive, hive, hive-vault
- Stars
- 10
- Tools
- 10
- Downloads, 30 days
- 1,721
- Latest version
- 1.12.2
- Last commit
- Nov 15, 2026
- License
- MIT
What is Hive Vault MCP?
Hive Vault connects AI coding assistants to Obsidian vaults to provide on-demand context and persistent knowledge between sessions. It exposes 10 tools, such as vault_list, vault_query, vault_search.
Summary generated from the project's README
About Hive Vault MCP server
Hive Vault connects AI coding assistants to Obsidian vaults to provide persistent knowledge across different sessions. Instead of loading an entire codebase into the context window, it uses on-demand querying to retrieve only the necessary information. This approach significantly reduces token consumption and prevents the assistant from forgetting project details once a session ends.
Developers can use this server with clients like Claude, Gemini CLI, Cursor, and Windsurf. It requires a local directory of markdown files, which can be configured via the VAULT_PATH environment variable. The server supports various operations through tools like vault_query for loading context, vault_search for full-text searches, and vault_write for creating or updating files. For advanced workflows, it can connect to an OpenAI-compatible endpoint to delegate tasks to other models.
Users can also run the server in a long-lived daemon mode to maintain a stable connection. This setup works well with the obsidian-git plugin to manage version control and file history automatically. The system includes specialized tools like capture_lesson to extract and reinforce important project insights over time.
Written from the project's README. Every use case is checked against a quote from it.
How to install Hive Vault MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Hive Vault MCP in Claude Code
$ claude mcp add --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' hive -- uvx hive-vaultInstall Hive Vault MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hive": {
"command": "uvx",
"args": [
"hive-vault"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Install Hive Vault MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hive": {
"type": "stdio",
"command": "uvx",
"args": [
"hive-vault"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Install Hive Vault MCP in VS Code CLI
$ code --add-mcp '{"name":"hive","type":"stdio","command":"uvx","args":["hive-vault"],"env":{"OPENROUTER_API_KEY":"<YOUR_OPENROUTER_API_KEY>"}}'Install Hive Vault MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hive": {
"command": "uvx",
"args": [
"hive-vault"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Install Hive Vault MCP in Codex
$ codex mcp add hive --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' -- uvx hive-vaultInstall Hive Vault MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hive] command = "uvx" args = ["hive-vault"] [mcp_servers.hive.env] OPENROUTER_API_KEY = "<YOUR_OPENROUTER_API_KEY>"
Install Hive Vault MCP in Gemini CLI
$ gemini mcp add -s user -e 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' hive uvx -- hive-vaultInstall Hive Vault MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hive": {
"command": "uvx",
"args": [
"hive-vault"
],
"env": {
"OPENROUTER_API_KEY": "<YOUR_OPENROUTER_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for hive-vault 1.12.2 in an isolated container with no network and no keys. It answered and listed 10 tools.
Hive Vault MCP tools 10
Read from the server with tools/listvault_listRead-onlyList vault projects, or files within a project. When called without arguments, lists all available projects. When called with a project, lists files in that project directory.
vault_queryRead-onlyRead content from a vault project — use instead of direct filesystem access.
vault_searchRead-onlySearch the vault: full-text, ranked, or recent changes. Default mode: flat full-text search across all vault files. Ranked mode (ranked=True): results scored by relevance. Recent mode (since_days>0): files changed in the last N days.
session_briefingRead-onlyCall at the start of every new session to load project context. Assembles active tasks, recent lessons, git activity, and project health into a single response — replaces 3-4 manual tool calls.
vault_writeActionWrite to the vault: append, replace a section, or create a new file. Modes: - append/replace: Update a project section. Requires section. - create: Create a new file with auto-generated frontmatter. Requires path and doc_type.
vault_patchActionSurgical find-and-replace in a vault file with auto git commit. Supports single or multi-replacement. For a single replacement, provide ``find`` and ``replace``. For multiple replacements, provide ``patches`` — a list of ``{"find": "...", "replace": "..."}`` dicts applied in sequence. Do not mix both modes. Each ``find`` value must appear exactly once in the file (after prior patches in the list have been applied). If any patch fails validation, no changes are written. Uses 3-pass cascading match: exact → body-only → whitespace-normalized.
vault_healthRead-onlyReturn vault health metrics, validation, and optional usage analytics. Without parameters, returns a health summary for all projects. When checks are specified, runs drift detection (frontmatter, stale, links). When include_usage is True, appends tool usage analytics.
capture_lessonActionCapture lessons: inline (structured fields) or batch (raw text via worker). Inline mode (default): provide title, context, problem, solution. Batch mode: provide text to extract lessons automatically via worker.
delegate_taskActionOffload work to a cheaper model or summarize vault files. When project is provided, reads a vault file. Small files (≤50 lines) are returned directly. Large files are auto-delegated to a worker for summarization — falls back to raw content if workers are unavailable.
worker_statusRead-onlyShow worker health: budget, connectivity, available models, and usage stats.
Configuration
OPENROUTER_API_KEYSecretOpenRouter API key for cloud worker delegation
HIVE_OLLAMA_ENDPOINTOllama API endpoint for local worker delegation
HIVE_VAULT_SCOPESJSON mapping of scope names to vault subdirectories
VAULT_PATHAbsolute path to your Obsidian vault (or any Markdown directory)
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemlorentedev/hive is public and reachablegithub.com/mlorentedev/hive ↗Pass
- Package names this repository as its sourcehive-vault names mlorentedev/hive as sourcepypi.org/project/hive-vault/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for hive-vaultpypi.org/project/hive-vault/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-15github.com/mlorentedev/hive ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from hive-vaultPass
- No critical advisory in the package or its dependencies65 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model10 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubhive-vault
Your AI coding assistant forgets everything between sessions. Hive fixes that.
Hive is an MCP server that connects your AI assistant to an Obsidian vault. Instead of loading everything upfront, it queries only what's needed — on demand.
| Metric | Without Hive | With Hive |
|---|---|---|
| Context loaded per session | ~800 lines (static) | ~50 lines (on demand) |
| Token cost for context | 100% every session | 0.6% for five project-context queries (real vault, 493K tokens) |
| Knowledge retained between sessions | 0% | 100% (in vault) |
Only the token-cost row is a measurement (5 project-context queries on a real 493K-token vault; method and numbers in the benchmarks). The line counts and the retention row describe how the two setups work; they are not measured.
Quick Start
Hive runs without a vault — vault tools return a friendly error until VAULT_PATH is set, so you can install first and configure later.
# 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
Default vault path:
~/Projects/knowledge. Override withVAULT_PATH(orHIVE_VAULT_PATH) as shown above.
For Codex CLI, GitHub Copilot, Cursor, Windsurf, and other clients, see Getting Started.
Then ask your assistant: "Use vault_list to see my vault"
Requirements
Hive degrades gracefully — every recommended or optional dependency reveals more capability without breaking the baseline.
-
Required
- Python 3.12+ (works on 3.13).
- A directory of markdown files. The vault structure used by
00_meta/10_projects/50_work/80_agents/05_researchis optional — without it, vault tools still operate but the scope routing is flat.
-
Recommended
gitinitialised inside the vault. Without it,vault_write/vault_patchstill write to disk; they just skip the per-write commit (andvault_commitreports the working tree as untracked).- The Obsidian desktop app to author the vault by hand.
- The obsidian-git plugin with auto-commit set to 5–10 minutes. Pair it with
vault_write(commit=False)/vault_patch(commit=False)to push the git workload off the synchronous tool path; see Recommended configuration below.
-
Optional
- Any OpenAI-compatible
/v1endpoint as the worker fordelegate_task/capture_lesson, set withHIVE_WORKER_BASE_URL,HIVE_WORKER_API_KEYandHIVE_WORKER_MODEL. - A backup git remote (e.g. private GitHub repo) so vault history survives a disk loss.
- Any OpenAI-compatible
Recommended configuration
Per ADR-006 (commit policy), the recommended pairing for write-heavy flows is:
- Install and enable the obsidian-git plugin in your vault.
- Set its auto-commit interval to 5 or 10 minutes.
- Call
vault_write(..., commit=False)andvault_patch(..., commit=False)for all bulk operations. - Optionally call
vault_commit(message="...")at the end of a session to force a checkpoint sooner than the obsidian-git tick.
vault_health reports a ## external_committer block when it detects obsidian-git in the vault. The commit=False durability contract is explicit: files are persisted to disk regardless; only the commit is deferred. A crash before the next flush loses the commit, not the content.
When a tool call is cancelled mid-flight (slow worker, client timeout), the server may have already mutated the disk before the cancel ack reaches the wire. vault_health surfaces a ## ghost_responses counter and emits a mcp.ghost_response.suppressed_after_cancel_ack WARNING for each event — verify state via vault_query rather than retrying, since the ErrorData ack does not imply rollback (ADR-007).
Daemon mode (optional)
The default uvx hive-vault runs a fresh server per session. Daemon mode
instead runs one long-lived hive serve that owns the vault, with each
stdio-only session connecting through hive client. The adapter starts without
importing the Hive server or FastMCP, then relays JSON-RPC to the daemon's stable
loopback endpoint. If the daemon or credential is unavailable, it fails
explicitly rather than starting a competing in-process owner.
The default endpoint is a deterministic per-user port in 49152..65535, so an
ordinary daemon restart does not invalidate client configuration. Override it
with HIVE_DAEMON_PORT in both the daemon and every client environment when
the derived port conflicts with another local service. hive serve --port
changes only the daemon's bind port; it does not reconfigure hive client or
hive delegate. Hive fails closed rather than silently moving to a different
port. The owner-only bearer token persists across ordinary restarts in the daemon state
directory. daemon.port remains diagnostic migration metadata, not client
discovery state. See ADR-022.
Security hold: Until #456 is resolved, do not deploy daemon mode on untrusted multi-user hosts. The endpoint serves TLS with a per-user certificate that Hive's clients pin, so an impostor on the fixed port fails the handshake before any bearer is sent; the hold stays until the Linux and Windows evidence, including the cross-user check, is recorded.
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
Run hive client from your MCP host. A host that can verify the daemon's
certificate may connect directly to
https://127.0.0.1:<derived-or-overridden-port>/mcp (for Node-based hosts,
NODE_EXTRA_CA_CERTS pointing at daemon.crt in the state directory); never
disable verification, and note that http:// no longer works. Never print or
copy the token into logs or shell history.
To install a newer release, use the platform-specific command:
# Linux / macOS
uv tool upgrade hive-vault
# Windows (the version is optional; omitted selects the latest PyPI release)
hive self-upgrade [version]
On Windows, self-upgrade builds the release beside the running files and atomically switches
the managed runtime, avoiding in-use-file conflicts. Open a new terminal after the first managed
upgrade so its PATH change is available. Once supervised, the daemon detects the new installed
version, exits 75, and the supervisor restarts it into the new code. See the
daemon mode guide and the
activation runbook.
Tools
| Tool | What it does |
|---|---|
vault_query |
Load project context, tasks, roadmap, lessons — or any file by path |
vault_search |
Full-text search with metadata filters, regex, ranked results, recent changes, lesson-usage ranking (rank_by) |
vault_list |
Browse projects and files with glob filtering |
vault_ask |
Optional semantic Q&A with source citations; disabled until an embeddings backend is configured ([semantic] extra) |
vault_health |
Server identity (version, vault path, backends), health metrics, drift detection, usage stats, opt-in runtime block |
vault_write |
Create, append, or replace vault files. commit=False defers the git commit for batching |
vault_patch |
Surgical find-and-replace. commit=False defers the git commit for batching |
vault_commit |
Flush pending commit=False writes into one git commit |
vault_delete |
Delete one file, committed synchronously so it stays recoverable from git history |
capture_lesson |
Capture lessons inline / batch-extract from text / look up existing lessons by keyword (find=) |
session_briefing |
Tasks + lessons + git log + health in one call |
delegate_task |
Route tasks to cheaper models or summarize vault files |
worker_status |
Whether the worker is configured and reachable, its model, and usage |
Plus 5 resources and 4 prompts for guided workflows.
Lesson reinforcement
Every read of a lesson via vault_query, vault_search, or capture_lesson(find=…) increments a counter and grows that lesson's confidence asymptotically toward 1.0. Validated lessons rank higher than one-shot captures over time.
# 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
Storage: SQLite side-table at HIVE_LESSON_DB_PATH (default ~/.local/share/hive/lesson_reinforcement.db). WAL mode + busy_timeout make it cross-process safe.
Architecture
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
Documentation
Full documentation at mlorentedev.github.io/hive:
- Getting Started — install for all MCP clients
- Configuration — all 19 environment variables
- Vault Structure — how to organize your vault
- Use Cases — real-world workflows
- Architecture — module map and design decisions
- Troubleshooting — common issues and fixes
Project-bound knowledge (docs-as-code) lives in docs/:
docs/adr/— Architecture Decision Recordsdocs/runbooks/— operational proceduresdocs/troubleshooting/— known issues and root-cause write-upsdocs/lessons.md— accumulated gotchas and post-mortems
Contributing
See CONTRIBUTING.md for setup and PR workflow.
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)
License
Hive Vault MCP questions
How do I add Hive Vault MCP to Claude Code?
Run claude mcp add --env 'OPENROUTER_API_KEY=<YOUR_OPENROUTER_API_KEY>' hive -- uvx hive-vault in your terminal. Add --scope user to make it available in every project.
How do I add Hive Vault MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Hive Vault MCP provide?
It exposes 10 tools, including vault_list, vault_query, vault_search, session_briefing, vault_write.
How does Hive Vault handle context loading?
Instead of loading the entire vault upfront, it queries only the specific information needed on demand, significantly reducing token costs.
What is the default vault path?
The default directory for your vault is ~/Projects/knowledge.
Can I use Hive Vault with Git?
Yes, it is recommended to initialize git inside the vault to allow tools to perform commits, though writing to disk works without it.
Does Hive Vault support semantic search?
Semantic Q&A is available via the vault_ask tool, but it requires an embeddings backend to be configured.