Skip to content
Hive

Configuration

All configuration is done through environment variables, passed when registering the MCP server.

Requirements

Section titled “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 00_meta / 10_projects / 50_work / 80_agents layout is optional — without it, vault tools still operate but 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. The git workload is already off the synchronous tool path — writes defer to a reconciler tick by default — but the plugin still earns its place; 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 hosted service and a local runtime are configured the same way; Hive names no provider.
    • The [semantic] extra plus an OpenAI-compatible embeddings endpoint (HIVE_EMBED_BASE_URL) to enable vault_ask, optional semantic Q&A. Disabled until configured.
    • A backup git remote (e.g. private GitHub repo) so vault history survives a disk loss.
Section titled “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. Nothing to do per call. Writes defer to the reconciler tick by default, so bulk operations already pay for one commit instead of N. Step 3 used to be “pass commit=False everywhere” — that flag is now the default and the keyword is redundant.
  4. Optionally call vault_commit(message="...") at the end of a session to force a checkpoint sooner than either tick.
  5. Optionally set HIVE_AUTO_DEFER_TO_EXTERNAL_COMMITTER=true to have the reconciler hand off to the plugin instead of committing, whenever the plugin is present and healthy.

vault_health reports a ## external_committer block when it detects obsidian-git in the vault. The durability contract is explicit and unchanged in substance: files are persisted to disk regardless; only the commit is deferred. A crash before the next flush loses the commit, not the content — and nothing recovers it automatically, so the uncommitted count in the runtime block is where you go looking. See Deferred commits.

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

Environment Variables

Section titled “Environment Variables”
Variable Default Description
HIVE_VAULT_PATH ~/Projects/knowledge Path to your Obsidian vault (canonical name; the bare VAULT_PATH is also accepted). For config-file MCP clients (Hermes, Cursor, Windsurf, …), set it in the server’s env block rather than via a CLI flag.
HIVE_WORKER_BASE_URL — (worker disabled) Base URL of the worker’s OpenAI-compatible endpoint (e.g. https://api.your-provider.example/v1). Falls back to HIVE_EMBED_BASE_URL when unset; with neither set, the worker is disabled.
HIVE_WORKER_API_KEY — Credential for the worker endpoint. Falls back to HIVE_EMBED_API_KEY when unset. Never echoed in status output.
HIVE_WORKER_MODEL — Model id the worker uses when delegate_task is called without model, as your endpoint names it. Falls back to HIVE_EMBED_MODEL when unset.
HIVE_EMBED_BASE_URL — (vault_ask disabled) Base URL of an OpenAI-compatible embeddings endpoint. Enables vault_ask (together with the [semantic] extra).
HIVE_EMBED_MODEL — Embedding model id, as your endpoint names it.
HIVE_EMBED_API_KEY — Credential for the embeddings endpoint (also used for synthesis).
HIVE_SYNTH_MODEL — Chat model vault_ask uses to write a cited answer from the retrieved sections, served by the same endpoint as the embeddings. Empty = vault_ask returns the retrieved sections without an LLM call.
HIVE_DB_PATH ~/.local/share/hive/worker.db SQLite database for worker usage telemetry (requests, tokens, latency). The vault_ask index is stored in an index/ directory next to it
HIVE_RELEVANCE_DB_PATH ~/.local/share/hive/relevance.db SQLite database for adaptive context scoring
HIVE_LESSON_DB_PATH ~/.local/share/hive/lesson_reinforcement.db SQLite database for lesson reinforcement counters + decayed confidence
HIVE_STALE_THRESHOLD_DAYS 180 Days before a vault file is flagged as stale
HIVE_HTTP_TIMEOUT 60.0 HTTP timeout (seconds) for worker calls
HIVE_TOOL_TIMEOUT 60.0 Tool-level timeout (seconds) for async tools (capture_lesson, delegate_task, worker_status, vault_ask)
HIVE_LOCK_TIMEOUT_S 30 Git filelock acquire timeout (seconds). Raise to 60-90 on large vaults or under heavy obsidian-git contention. Validated 1..600.
HIVE_WAL_CHECKPOINT_INTERVAL_S 30.0 Interval between PRAGMA wal_checkpoint(PASSIVE) ticks per hive process. Lower = more aggressive WAL drain. Validated >0..3600.
HIVE_OUTBOX_TICK_S 5.0 Interval (seconds) between reconciler ticks that drain the in-process lesson-reinforcement outbox into SQLite. Lower = faster cross-process visibility, higher SQLite contention.
HIVE_UPGRADE_POLL_S 30.0 Daemon mode only (hive serve): seconds between version-drift checks. On drift the daemon exits 75 so the supervisor restarts it into the new version. Lower = adopts a new version sooner; validated >0..3600. See the daemon mode guide.
HIVE_AUTO_DEFER_TO_EXTERNAL_COMMITTER false Opt-in cooperation with obsidian-git: when true AND obsidian-git is installed AND healthy, hive’s vault_write / vault_patch writes are silently treated as commit=False so obsidian-git’s auto-commit picks them up on its next tick. See the obsidian-git integration guide for the full predicate and fallback semantics.
HIVE_RELEVANCE_ALPHA 0.3 EMA learning rate for adaptive context scoring
HIVE_RELEVANCE_DECAY 0.9 Session decay factor for relevance scores
HIVE_RELEVANCE_EPSILON 0.15 Exploration ratio for session_briefing (epsilon-greedy)
HIVE_VAULT_SCOPES {"projects": "10_projects", "meta": "00_meta", "work": "50_work", "agents": "80_agents"} JSON mapping of scope names to vault subdirectories. Scopes support hierarchical resolution (BFS). The agents scope holds AI-agent inboxes; auto-scan tries scopes in insertion order, so agents is listed last to avoid shadowing existing project names. Each directory must be a unique relative path inside the vault — duplicate, absolute, or escaping (..) values are rejected at startup.
HIVE_LOG_PATH ~/.local/share/hive/hive.log File path for persistent debug log (1MB rotating)
HIVE_LOG_LEVEL INFO Log level for the persistent log file. Captures hive, fastmcp and mcp loggers. Set to DEBUG for transport-level diagnostics, WARNING to suppress lifecycle events.
HIVE_LOG_RETENTION_DAYS 7 How long a per-process debug log is kept. Each process writes its own hive-<pid>.log (size-capped at 1MB), so this bounds the number of files rather than their size. On startup, a log is deleted only when it is older than this and its owning process is gone — an idle daemon’s log is never collected. Validated 1..365.

Worker Credential

Section titled “Worker Credential”

The worker’s API key has one name: HIVE_WORKER_API_KEY. When it is unset, Hive falls back to HIVE_EMBED_API_KEY, so a deployment that points both at one endpoint needs the key only once. Hive does not read provider-named variables: if your launcher resolves the credential under its own name, map it onto HIVE_WORKER_API_KEY when it injects the environment.

The fallback is per field — HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY and HIVE_WORKER_MODEL each inherit from their HIVE_EMBED_* counterpart independently, so you can override the model alone and keep the endpoint. An explicit HIVE_WORKER_* value always wins.

Example: Full Configuration

Section titled “Example: Full Configuration”
Terminal window
# Export HIVE_WORKER_API_KEY from your secret store first.
claude mcp add -s user hive \
  -e VAULT_PATH=$HOME/my-vault \
  -e HIVE_WORKER_BASE_URL=https://api.your-provider.example/v1 \
  -e HIVE_WORKER_API_KEY="$HIVE_WORKER_API_KEY" \
  -e HIVE_WORKER_MODEL=<model-id> \
  -- uvx --upgrade hive-vault

The --upgrade flag ensures you always get the latest version from PyPI on each session start.

Example: Vault Only (No Worker)

Section titled “Example: Vault Only (No Worker)”

If you only need vault access and don’t want worker delegation:

Terminal window
claude mcp add -s user hive -e VAULT_PATH=$HOME/my-vault -- uvx --upgrade hive-vault

Worker tools stay registered, but delegate_task returns “worker not configured” and worker_status reports Configured: no until HIVE_WORKER_BASE_URL is set.

Setting Up a Worker

Section titled “Setting Up a Worker”

Any OpenAI-compatible /v1 endpoint works — a hosted service or a runtime on your own machine. You need three values:

  1. The endpoint’s base URL, ending in /v1 → HIVE_WORKER_BASE_URL. A local runtime listens on a loopback URL such as http://localhost:11434/v1.
  2. A credential, if the endpoint requires one → HIVE_WORKER_API_KEY
  3. The model id exactly as the endpoint names it → HIVE_WORKER_MODEL

Hive does not recommend or default to a provider, and does not validate the model id against any catalog. To check the setup, ask your assistant to call worker_status: you should see Configured: yes and Reachable: yes (N models). “Configured” only means a base URL is set; “Reachable” is probed against the endpoint. See Worker Routing for how a single attempt and its failures are handled.

Setting Up Semantic Q&A (vault_ask)

Section titled “Setting Up Semantic Q&A (vault_ask)”

vault_ask answers natural-language questions from your vault with source citations. It is optional and off by default. To enable it:

Terminal window
pip install 'hive-vault[semantic]'

Then configure an OpenAI-compatible embeddings endpoint — the same way as the worker, hosted or local:

Terminal window
HIVE_EMBED_BASE_URL=https://api.your-provider.example/v1
HIVE_EMBED_MODEL=<an embedding model the endpoint serves>
HIVE_EMBED_API_KEY=<your-key>

Restart the server; the index builds lazily on first use and is updated as you write to the vault. Set HIVE_SYNTH_MODEL to a chat model on the same endpoint to get a synthesized, cited answer instead of the raw retrieved sections. Note that an unset worker setting falls back to its HIVE_EMBED_* counterpart: with only these variables set, the worker inherits the embeddings endpoint and key, but also the embedding model id, which cannot chat — so set HIVE_WORKER_MODEL explicitly if you also use the worker. See vault_ask.

Activating Hive in Your Workflow

Section titled “Activating Hive in Your Workflow”

Installing and registering Hive makes the tools available, but your AI assistant needs guidance on when to use them. Your project instructions file (CLAUDE.md, GEMINI.md, or equivalent in your MCP client) is the key.

Without explicit instructions, your assistant might use Hive tools, but inconsistently. With clear instructions, it uses them predictably for every relevant query.

Section titled “Recommended Instructions Snippet”

Add this to your project instructions file (CLAUDE.md, GEMINI.md, or equivalent):

## Vault & Knowledge (Hive MCP)


When hive-vault MCP is available, use it for on-demand context:
- `vault_query(project="myproject", section="context")` — project overview
- `vault_query(project="myproject", section="tasks")` — active backlog
- `vault_search(query="...")` — cross-vault search
- `session_briefing(project="myproject")` — full context in one call


When writing to the vault: lessons → `90-lessons.md`, decisions → `30-architecture/`.

Replace myproject with your actual project slug (the directory name under 10_projects/).

How MCP Tool Selection Works

Section titled “How MCP Tool Selection Works”
  1. Registration — MCP servers are loaded at session start. Your client sees all tools from all servers.
  2. Discovery — The assistant reads tool names and descriptions to understand capabilities.
  3. Routing — Your CLAUDE.md instructions tell the assistant which tools to prefer for which situations. Multiple MCP servers coexist without conflict — each serves its domain.
  4. Adaptation — Hive’s session_briefing learns from your usage patterns. Sections you query often get prioritized automatically in future briefings.

Automating Session Briefing (Claude Code Hooks)

Section titled “Automating Session Briefing (Claude Code Hooks)”

Claude Code supports hooks — shell commands that run in response to lifecycle events. You can use a SessionStart hook to automatically remind your assistant to load context from Hive at the beginning of every session.

Section titled “Option 1: Context Injection (Recommended)”

Add a SessionStart hook that outputs a system reminder. The text is injected into the conversation automatically:

In ~/.claude/settings.json (or .claude/settings.json per-project):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Call session_briefing(project=\"myproject\") to load context before starting work.'"
          }
        ]
      }
    ]
  }
}

Replace myproject with your vault project slug. The assistant will see the reminder and call session_briefing at the start of every session.

Option 2: Agent Hook (Autonomous)

Section titled “Option 2: Agent Hook (Autonomous)”

For fully automatic context loading without any manual invocation, use an agent hook. This spawns a lightweight subagent that calls the tool directly:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Call session_briefing(project=\"myproject\") and present the results to the user.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

This is more autonomous but spawns a subagent (consuming extra tokens). Option 1 is usually sufficient since the assistant follows the injected reminder reliably.

Notes

Section titled “Notes”
  • Hooks are a Claude Code feature, not part of Hive itself. Other MCP clients may have their own automation mechanisms.
  • You can also use UserPromptSubmit hooks for per-message context injection, but SessionStart is the natural fit for briefings.
  • See claude /hooks within Claude Code to manage hooks interactively.