README.md
Context infrastructure for AI-assisted development via Obsidian vault access
hive-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 | 6% average per query |
| Knowledge retained between sessions | 0% | 100% (in vault) |
Measured on a real vault with 19 projects, 200+ files. See benchmarks.
Quick Start
# Claude Code
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
Set
VAULT_PATHto your Obsidian vault directory. Default:~/Projects/knowledge.
For Codex CLI, GitHub Copilot, Cursor, Windsurf, and other clients, see Getting Started.
Then ask your assistant: "Use vault_list to see my vault"
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 |
vault_list |
Browse projects and files with glob filtering |
vault_health |
Health metrics, drift detection, usage stats |
vault_write |
Create, append, or replace vault files with auto git commit |
vault_patch |
Surgical find-and-replace with auto git commit |
capture_lesson |
Capture lessons inline or batch-extract from text via worker |
session_briefing |
Tasks + lessons + git log + health in one call |
delegate_task |
Route tasks to cheaper models or summarize vault files |
worker_status |
Budget, connectivity, available models |
Plus 5 resources and 4 prompts for guided workflows.
Architecture
MCP Host (Claude Code, Gemini CLI, Codex CLI, Cursor, ...)
└── hive-vault (MCP server, stdio)
├── Vault Tools (7) ── Obsidian vault (Markdown + YAML frontmatter)
├── Session Tools (1) ── Adaptive context assembly
└── Worker Tools (2) ── Ollama (free) → OpenRouter free → paid ($1/mo cap) → reject
Documentation
Full documentation at mlorentedev.github.io/hive:
- Getting Started — install for all MCP clients
- Configuration — all 16 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
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 (337 tests, 92% coverage)
License
Tools (10)
vault_queryLoad project context, tasks, roadmap, lessons, or any file by path.vault_searchFull-text search with metadata filters, regex, ranked results, and recent changes.vault_listBrowse projects and files with glob filtering.vault_healthCheck health metrics, drift detection, and usage stats.vault_writeCreate, append, or replace vault files with auto git commit.vault_patchSurgical find-and-replace with auto git commit.capture_lessonCapture lessons inline or batch-extract from text via worker.session_briefingGet tasks, lessons, git log, and health in one call.delegate_taskRoute tasks to cheaper models or summarize vault files.worker_statusCheck budget, connectivity, and available models.Environment Variables
VAULT_PATHrequiredThe absolute path to your Obsidian vault directory.Configuration
claude_desktop_config.json
{"mcpServers": {"hive": {"command": "uvx", "args": ["hive-vault"], "env": {"VAULT_PATH": "/path/to/your/vault"}}}}Try it
→Use vault_list to see my vault and identify active projects.
→Search for recent changes in my project roadmap using vault_search.
→Capture a lesson from our current conversation using capture_lesson.
→Provide a session_briefing to get me up to speed on my current tasks and health metrics.
→Use vault_query to load the documentation for my current project.