Skip to main content
Glama
Sign In
hive

hive

by mlorentedev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

hive-vault

CI codecov PyPI Python 3.12+ Docs License: MIT

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 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"

Related MCP server: Obsidian MCP

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_research 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 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:

Project-bound knowledge (docs-as-code) lives in docs/:

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

MIT

Available Tools

13 tools
capture_lessonCapture LessonA

Capture lessons: inline / batch write, or lookup by keyword.

Inline mode (default): provide title, context, problem, solution. Batch mode: provide text to extract lessons automatically via worker. Lookup mode: provide find to surface top-ranked existing lessons whose heading matches the keyword.

Inputs: project (required), find, tags, text, +7 more. Returns: result

delegate_taskDelegate TaskA

Offload 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.

Inputs: path, model, prompt, context, +6 more. Returns: result

session_briefingSession BriefingA
Read-onlyIdempotent

Call at the start of every new session to load project context.

Without a project, returns the available project list with a usage hint — discoverability parity with vault_health() and worker_status(). With a project, assembles active tasks, recent lessons, git activity, and project health into a single response (replaces 3-4 manual calls).

Inputs: project. Returns: result

vault_askVault AskA
Read-onlyIdempotent

Ask a natural-language question; get a source-cited synthesized answer (semantic retrieval / RAG) or relevant vault sections when no synthesis model is configured.

OPTIONAL — disabled by default. Requires the [semantic] extra plus an embeddings backend (HIVE_EMBED_BASE_URL); until then it returns a short how-to-enable message and never errors. Set HIVE_SYNTH_MODEL to enable LLM synthesis on top of retrieval. For keyword / regex lookups use vault_search instead.

Inputs: question. Returns: result

vault_commitVault CommitA

Commit every unstaged and untracked change in the vault, in one commit.

Companion to vault_write(commit=False) and vault_patch(commit=False): callers that opt out of per-write commits batch many writes and then flush with a single vault_commit call.

It also sweeps edits made outside hive. A path that already has a staged change is left out and named in the result: it belongs to whoever staged it, often another session sharing the vault. Commit one deliberately with git commit -- <path>.

Returns the new commit SHA on success, a clean-tree notice when there is nothing to commit, or a human-readable error.

Inputs: message. Returns: result

vault_deleteVault DeleteA

Delete a single file from the vault (destructive; recoverable via git).

Removes one file and, by default, commits the deletion so it stays recoverable from git history (git revert / git show). Files only — directories are rejected. A non-existent path is an error, unless idempotency_key is set (then a retry against an already-gone file is a no-op success).

Inputs: path (required), project (required), commit, idempotency_key. Returns: result

vault_healthVault HealthA
Read-onlyIdempotent

Return vault health metrics, validation, and optional usage analytics.

Always emits the ## server identity block (version, python, vault path, backend presence, started_at) at the top.

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. When include_runtime is True, appends runtime metadata (uptime, tools, budget).

Inputs: checks, project, max_issues, usage_days, +2 more. Returns: result

vault_listVault ListB
Read-onlyIdempotent

List 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.

Inputs: path, pattern, project, subpath. Returns: result

vault_patchVault PatchA

Surgical 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.

Inputs: path (required), project (required), find, commit, +5 more. Returns: result

vault_queryVault QueryB
Read-onlyIdempotent

Read content from a vault project — use instead of direct filesystem access.

Inputs: project (required), path, section, max_lines, +2 more. Returns: result

vault_searchVault SearchB
Read-onlyIdempotent

Search 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. rank_by mode (rank_by != 'bm25'): lessons-only, ranked by usage.

Inputs: limit, query, regex, scope, +10 more. Returns: result

vault_writeVault WriteA

Write 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. Requires path, relative to the project directory. Frontmatter is generated (doc_type defaults to "note") unless content opens with its own block, which is kept as is. Inferred automatically when you pass a path with no section, so operation may be omitted.

Inputs: content (required), project (required), path, commit, +4 more. Returns: result

worker_statusWorker StatusA
Read-onlyIdempotent

Show worker health: configuration, reachability, model, and usage.

HIVE-384 reshaped this tool, and the reshape is the point rather than a side effect. The old output led with a dollar budget and reported two providers by configuration: it said "Ollama: offline / OpenRouter: no API key" for an unknown length of time while every caller treated the worker as a working capability. A status surface that cannot distinguish "configured" from "answers" is how a dead backend stays invisible.

So reachability is probed, not inferred, and reported separately from configuration. The dollar figures are gone: on a flat subscription they would read zero forever, and a gauge that always says the same thing looks like a working gauge.

Inputs: include_models. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.9/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools map to a single verb on a single resource, and the descriptions actively steer callers apart (e.g. vault_ask says to use vault_search for keyword lookups, vault_commit explains its relationship to commit=False writes). A few boundaries blur: delegate_task doubles as a vault-file reader alongside vault_query, capture_lesson's lookup mode overlaps vault_search, and session_briefing aggregates data that vault_health also reports.

    Naming Consistency4/5

    Every name is snake_case verb_noun, which is highly predictable. The only deviation is scope of prefixing: vault_* covers storage operations while session_briefing, capture_lesson, delegate_task, and worker_status are unprefixed — a seemingly deliberate but still visible split.

    Tool Count5/5

    13 tools sits squarely in the well-scoped range, and each earns its place: eight cover vault CRUD/search/git, and the remainder cover session context, lessons, delegation, worker health, and optional RAG. No filler tools and no obviously missing siblings.

    Completeness4/5

    The vault lifecycle is well covered — list, read, write/create, patch, delete, search, and git commit are all present, with recoverability and idempotency handled. Minor gaps remain: no move/rename operation for files, no explicit project creation or deletion, and no directory-level operations (which delete explicitly rejects).

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Obsidian

      clavia-labs
      A
      license
      Not graded
      quality
      Not graded
      maintenance
      This is a connector to allow Claude Desktop (or any MCP client) to read and search any directory containing Markdown notes (such as an Obsidian vault).
      837 npm
      1,352
      AGPL 3.0

    • Obsidian MCP

      newtype-01
      A
      license
      A
      quality
      D
      maintenance
      This project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.
      11
      74 npm
      310
      MIT

    • context-portal

      GreatScottyMac
      A
      license
      Not graded
      quality
      D
      maintenance
      Context Portal (ConPort): A memory bank MCP server building a project-specific knowledge graph to supercharge AI assistants. Enables powerful Retrieval Augmented Generation (RAG) for context-aware development in your IDE.
      38 PyPI
      768
      Apache 2.0

    • Another bloated Obsidian MCP

      diegorv
      A
      license
      A
      quality
      F
      maintenance
      A Model Context Protocol (MCP) server that provides AI assistants with secure access to Obsidian vaults. Enables reading, writing, searching, and managing notes without requiring Obsidian to be running.
      50
      7,721 npm
      Apache 2.0