mlorentedev/hive

**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.
> Default vault path: ~/Projects/knowledge. Override with VAULT_PATH (or HIVE_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 is optional — without it, vault tools still operate but the scope routing is flat.
- **Recommended**
- 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).
- 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 /v1 endpoint** as the worker for delegate_task / capture_lesson, set with HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY and HIVE_WORKER_MODEL.
- A **backup git remote** (e.g. private GitHub repo) so vault history survives a disk loss.
Recommended configuration
Per ADR-006 (commit policy), the recommended pairing for write-heavy flows is:
1. Install and enable the **obsidian-git** plugin in your vault.
2. Set its **auto-commit interval** to 5 or 10 minutes.
3. Call vault_write(..., commit=False) and vault_patch(..., commit=False) for all bulk operations.
4. 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**