{
  "markdown": "# hive-vault\n\n[![CI](https://github.com/mlorentedev/hive/actions/workflows/ci.yml/badge.svg)](https://github.com/mlorentedev/hive/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/mlorentedev/hive/graph/badge.svg)](https://codecov.io/gh/mlorentedev/hive)\n[![PyPI](https://img.shields.io/pypi/v/hive-vault)](https://pypi.org/project/hive-vault/)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://python.org)\n[![Docs](https://img.shields.io/badge/docs-hive-blue)](https://mlorentedev.github.io/hive/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n<a href=\"https://glama.ai/mcp/servers/mlorentedev/hive\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/mlorentedev/hive/badge\" />\n</a>\n\n<!-- mcp-name: io.github.mlorentedev/hive-vault -->\n\n**Your AI coding assistant forgets everything between sessions. Hive fixes that.**\n\nHive is an [MCP](https://modelcontextprotocol.io/) server that connects your AI assistant to an [Obsidian](https://obsidian.md/) vault. Instead of loading everything upfront, it queries only what's needed — on demand.\n\n| Metric | Without Hive | With Hive |\n|---|---|---|\n| Context loaded per session | ~800 lines (static) | ~50 lines (on demand) |\n| Token cost for context | 100% every session | 6% average per query |\n| Knowledge retained between sessions | 0% | 100% (in vault) |\n\n> Measured on a real vault with 19 projects, 200+ files. See [benchmarks](https://mlorentedev.github.io/hive/guides/benchmarks/).\n\n## Quick Start\n\nHive runs without a vault — vault tools return a friendly error until `VAULT_PATH` is set, so you can install first and configure later.\n\n```bash\n# Minimal — uses default vault path ~/Projects/knowledge\nclaude mcp add -s user hive -- uvx --upgrade hive-vault\n\n# With a custom vault path\nclaude mcp add -s user hive -e VAULT_PATH=$HOME/path/to/vault -- uvx --upgrade hive-vault\n\n# Gemini CLI\ngemini mcp add -s user -e VAULT_PATH=$HOME/path/to/vault hive-vault uvx -- --upgrade hive-vault\n```\n\n> Default vault path: `~/Projects/knowledge`. Override with `VAULT_PATH` (or `HIVE_VAULT_PATH`) as shown above.\n\nFor Codex CLI, GitHub Copilot, Cursor, Windsurf, and other clients, see [Getting Started](https://mlorentedev.github.io/hive/getting-started/).\n\nThen ask your assistant: *\"Use vault_list to see my vault\"*\n\n## Requirements\n\nHive degrades gracefully — every recommended or optional dependency reveals more capability without breaking the baseline.\n\n- **Required**\n  - Python **3.12+** (works on 3.13).\n  - A directory of markdown files. The vault structure used by `00_meta` / `10_projects` / `50_work` / `80_agents` is optional — without it, vault tools still operate but the scope routing is flat.\n\n- **Recommended**\n  - `git` initialised inside the vault. Without it, `vault_write` / `vault_patch` still write to disk; they just skip the per-write commit (and `vault_commit` reports the working tree as untracked).\n  - The **[Obsidian](https://obsidian.md)** desktop app to author the vault by hand.\n  - The **[obsidian-git plugin](https://github.com/Vinzent03/obsidian-git)** 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.\n\n- **Optional**\n  - **[Ollama](https://ollama.com/)** running `qwen2.5-coder:7b` (or compatible) for local, free `delegate_task` / `capture_lesson` worker calls.\n  - An **OpenRouter** API key (`OPENROUTER_API_KEY`) as a free-tier and paid fallback worker.\n  - A **backup git remote** (e.g. private GitHub repo) so vault history survives a disk loss.\n\n### Recommended configuration\n\nPer [ADR-006 (commit policy)](docs/adr/adr-006-commit-policy.md), the recommended pairing for write-heavy flows is:\n\n1. Install and enable the **obsidian-git** plugin in your vault.\n2. Set its **auto-commit interval** to 5 or 10 minutes.\n3. Call `vault_write(..., commit=False)` and `vault_patch(..., commit=False)` for all bulk operations.\n4. Optionally call `vault_commit(message=\"...\")` at the end of a session to force a checkpoint sooner than the obsidian-git tick.\n\n`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.\n\nWhen 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](docs/adr/adr-007-mcp-cancellation-response.md)).\n\n## Daemon mode (optional)\n\nThe 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 session connecting through a thin `hive client` shim — useful for concurrent sessions, single-owner guarantees ([ADR-011](docs/adr/adr-011-phase-c-daemon-model.md)), and automatic version adoption. It always degrades to an in-process server if the daemon is down, so it never breaks a session.\n\n```bash\nuv tool install --upgrade hive-vault   # >= 1.32.0\nhive service install                   # supervise hive serve (systemd --user / Task Scheduler)\n```\n\nTo install a newer release, use the platform-specific command:\n\n```bash\n# Linux / macOS\nuv tool upgrade hive-vault\n\n# Windows (the version is optional; omitted selects the latest PyPI release)\nhive self-upgrade [version]\n```\n\nOn Windows, `self-upgrade` builds the release beside the running files and atomically switches\nthe managed runtime, avoiding in-use-file conflicts. Open a new terminal after the first managed\nupgrade so its `PATH` change is available. Once supervised, the daemon detects the new installed\nversion, exits `75`, and the supervisor restarts it into the new code. See the\n[daemon mode guide](https://mlorentedev.github.io/hive/guides/daemon-mode/) and the\n[activation runbook](docs/runbooks/daemon-activation.md).\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `vault_query` | Load project context, tasks, roadmap, lessons — or any file by path |\n| `vault_search` | Full-text search with metadata filters, regex, ranked results, recent changes, lesson-usage ranking (`rank_by`) |\n| `vault_list` | Browse projects and files with glob filtering |\n| `vault_health` | Server identity (version, vault path, backends), health metrics, drift detection, usage stats, opt-in runtime block |\n| `vault_write` | Create, append, or replace vault files. `commit=False` defers the git commit for batching |\n| `vault_patch` | Surgical find-and-replace. `commit=False` defers the git commit for batching |\n| `vault_commit` | Flush pending `commit=False` writes into one git commit |\n| `capture_lesson` | Capture lessons inline / batch-extract from text / look up existing lessons by keyword (`find=`) |\n| `session_briefing` | Tasks + lessons + git log + health in one call |\n| `delegate_task` | Route tasks to cheaper models or summarize vault files |\n| `worker_status` | Budget, connectivity, available models |\n\nPlus 5 [resources](https://mlorentedev.github.io/hive/reference/resources/) and 4 [prompts](https://mlorentedev.github.io/hive/guides/prompts/) for guided workflows.\n\n### Lesson reinforcement\n\nEvery 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.\n\n```bash\n# Surface the top-ranked lessons matching a keyword\ncapture_lesson(project=\"hive\", find=\"multi-process\")\n\n# Search lessons ranked by usage signal (not BM25)\nvault_search(query=\"timeout\", rank_by=\"reinforcements\")    # most-reinforced first\nvault_search(query=\"timeout\", rank_by=\"confidence\")        # highest decayed confidence\nvault_search(query=\"timeout\", rank_by=\"hybrid\")            # α=0.7 BM25 + 0.3 confidence\n```\n\nStorage: SQLite side-table at `HIVE_LESSON_DB_PATH` (default `~/.local/share/hive/lesson_reinforcement.db`). WAL mode + busy_timeout make it cross-process safe.\n\n## Architecture\n\n```\nMCP Host (Claude Code, Gemini CLI, Codex CLI, Cursor, ...)\n    └── hive-vault (MCP server, stdio)\n            ├── Vault Tools (7) ── Obsidian vault (Markdown + YAML frontmatter)\n            ├── Session Tools (1) ── Adaptive context assembly\n            └── Worker Tools (2) ── Ollama (free) → OpenRouter free → paid ($1/mo cap) → reject\n```\n\n## Documentation\n\nFull documentation at **[mlorentedev.github.io/hive](https://mlorentedev.github.io/hive/)**:\n\n- [Getting Started](https://mlorentedev.github.io/hive/getting-started/) — install for all MCP clients\n- [Configuration](https://mlorentedev.github.io/hive/configuration/) — all 19 environment variables\n- [Vault Structure](https://mlorentedev.github.io/hive/guides/vault-structure/) — how to organize your vault\n- [Use Cases](https://mlorentedev.github.io/hive/guides/use-cases/) — real-world workflows\n- [Architecture](https://mlorentedev.github.io/hive/reference/architecture/) — module map and design decisions\n- [Troubleshooting](https://mlorentedev.github.io/hive/guides/troubleshooting/) — common issues and fixes\n\nProject-bound knowledge (docs-as-code) lives in [`docs/`](docs/):\n\n- [`docs/adr/`](docs/adr/) — Architecture Decision Records\n- [`docs/runbooks/`](docs/runbooks/) — operational procedures\n- [`docs/troubleshooting/`](docs/troubleshooting/) — known issues and root-cause write-ups\n- [`docs/lessons.md`](docs/lessons.md) — accumulated gotchas and post-mortems\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for setup and PR workflow.\n\n```bash\ngit clone https://github.com/mlorentedev/hive.git && cd hive\nmake install   # create venv + install deps\nmake check     # lint + typecheck + test (478 tests, 90% coverage)\n```\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 10183,
  "sha": "07333787ebfc14af829551f558371adf30b4a4f0b1bd4e0ee9513ab3fba3218f",
  "repo_slug": "mlorentedev/hive",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mlorentedev_hive_vault_2b835d65/readme"
}