# mlorentedev/hive [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/mlorentedev/hive  
**GitHub Stars:** 10  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mlorentedev-hive

## Description
On-demand Obsidian vault access via MCP. Adaptive context loading (67-82% token savings), full-text and ranked search, health checks, auto git commit, and worker delegation to cheaper models. 10 tools, works with any MCP client.

## Tools
Capabilities this server exposes over MCP:

- **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_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
- **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** — Budget, connectivity, available models

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "hive": {
    "command": "uvx",
    "args": ["--upgrade"]
  }
}
```

## Documentation

## What mlorentedev/hive MCP server does

The mlorentedev/hive MCP server gives an MCP client access to an Obsidian vault stored as a directory of Markdown files. It supports targeted reads rather than loading the entire vault into every session. Agents can retrieve project context, tasks, roadmaps, lessons, or a specific file with `vault_query`; search content with metadata filters, regular expressions, ranked results, recent-change ordering, or lesson-reinforcement ranking; and browse files with glob filters.

The server also provides write operations. `vault_write` creates, appends to, or replaces files, while `vault_patch` performs a focused find-and-replace. Both can defer the git commit, allowing several changes to be grouped before `vault_commit` creates one commit. `capture_lesson` records lessons, extracts multiple lessons from text, or finds existing lessons by keyword. `session_briefing` combines tasks, lessons, git history, and health information in one request.

## How it works

The server runs over MCP using stdio and reads the configured vault directly from disk. The default vault location is `~/Projects/knowledge`; `VAULT_PATH` or `HIVE_VAULT_PATH` can select another directory. A structured layout using directories such as `00_meta`, `10_projects`, `50_work`, and `80_agents` is supported but not required. Without that structure, vault operations continue with flat scope routing.

Lesson reads through `vault_query`, `vault_search`, or `capture_lesson(find=...)` update reinforcement data. This data is stored in a SQLite side-table, with the default path at `~/.local/share/hive/lesson_reinforcement.db`. Search can use reinforcement, confidence, or a hybrid ranking mode.

Optional worker features route tasks or vault-file summarization through Ollama first, then OpenRouter according to available connectivity and budget. `worker_status` reports budget, connectivity, and available models. Ollama can provide a local worker, while OpenRouter requires an API key.

## Setup and configuration

Install the mlorentedev/hive MCP server with Python 3.12 or newer and the `hive-vault` package through `uvx`. The server can start before a vault is configured; vault tools return an explanatory error until a path is available. A git repository inside the vault is recommended for commit support, but writing still works without git and skips per-write commits.

Obsidian is optional for authoring the files manually. The obsidian-git plugin can perform periodic commits, while calls using `commit=False` keep file persistence separate from commit timing. A backup git remote can protect vault history from disk loss. Daemon mode is also available through the `hive` command for long-lived ownership of the vault and concurrent sessions, but the standard `uvx --upgrade hive-vault` process is the basic setup.

## Tools and capabilities

- Query project context or individual files.
- Search Markdown content with filters, regex, and ranking options.
- List projects and files with glob matching.
- Inspect identity, health metrics, drift, usage, and worker information.
- Create, append, replace, patch, and commit vault content.
- Capture, extract, and reinforce reusable lessons.
- Delegate tasks or summarize vault files with optional workers.

## Limitations and notes

The mlorentedev/hive MCP server requires Python 3.12 or later and a Markdown-file directory for useful vault operations. Git commits depend on git being initialized in the vault. Deferred commits persist file changes immediately, but a crash before the next commit can lose the commit itself. A cancelled tool call may have changed the disk before the cancellation acknowledgement arrives, so state should be checked with `vault_query` before retrying.

Ollama and OpenRouter workers are optional rather than prerequisites. OpenRouter use requires the user's `OPENROUTER_API_KEY`; the baseline vault tools do not require an external service. The server reports health and worker details through its MCP tools, and it includes five resources and four prompts for guided workflows according to the project documentation.

_Full upstream README: https://allmcps.com/mcp/mlorentedev-hive/readme_