Configuration

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

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

  • Ollama running qwen2.5-coder:7b (or compatible) for local, free delegate_task / capture_lesson worker calls.
  • An OpenRouter API key (OPENROUTER_API_KEY) as a free-tier and paid fallback worker.
  • 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).

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_OLLAMA_ENDPOINT | http://localhost:11434 | Ollama API endpoint | | HIVE_OLLAMA_MODEL | qwen2.5-coder:7b | Default Ollama model | | HIVE_OPENROUTER_API_KEY | — | OpenRouter API key | | HIVE_OPENROUTER_MODEL | qwen/qwen3-coder:free | Default OpenRouter model (free tier) | | HIVE_OPENROUTER_PAID_MODEL | qwen/qwen3-coder | Paid tier model for delegate_task | | HIVE_OPENROUTER_BUDGET | 1.0 | Monthly budget cap in USD | | HIVE_DB_PATH | ~/.local/share/hive/worker.db | SQLite database for budget/usage tracking | | 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 Ollama and OpenRouter | | HIVE_TOOL_TIMEOUT | 60.0 | Tool-level timeout (seconds) for async worker tools (capture_lesson, delegate_task, worker_status) | | 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. |

API Key Resolution

The OpenRouter API key supports two names for convenience:

• HIVE_OPENROUTER_API_KEY (prefixed, standard)
• OPENROUTER_API_KEY (bare, for environments that already export it)

If both are set, the HIVE_ prefixed version takes precedence.

Example: Full Configuration

Claude Code

claude mcp add -s user hive \
  -e VAULT_PATH=$HOME/my-vault \
  -e HIVE_OLLAMA_ENDPOINT=http://minipc.local:11434 \
  -e OPENROUTER_API_KEY=sk-or-v1-abc123 \
  -e HIVE_OPENROUTER_BUDGET=10.0 \
  -- uvx --upgrade hive-vault

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

[mcp_servers.hive-vault.env]
VAULT_PATH = "~/my-vault"
HIVE_OLLAMA_ENDPOINT = "http://minipc.local:11434"
OPENROUTER_API_KEY = "sk-or-v1-abc123"
HIVE_OPENROUTER_BUDGET = "10.0"

Gemini CLI

gemini mcp add -s user \
  -e VAULT_PATH=$HOME/my-vault \
  -e HIVE_OLLAMA_ENDPOINT=http://minipc.local:11434 \
  -e OPENROUTER_API_KEY=sk-or-v1-abc123 \
  -e HIVE_OPENROUTER_BUDGET=10.0 \
  hive-vault uvx -- --upgrade hive-vault

Copilot (VS Code)

Add to .vscode/mcp.json (or VS Code user settings):

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/home/you/my-vault",
        "HIVE_OLLAMA_ENDPOINT": "http://minipc.local:11434",
        "OPENROUTER_API_KEY": "sk-or-v1-abc123",
        "HIVE_OPENROUTER_BUDGET": "10.0"
      }
    }
  }
}

OpenCode

Add to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/home/you/my-vault",
        "HIVE_OLLAMA_ENDPOINT": "http://minipc.local:11434",
        "OPENROUTER_API_KEY": "sk-or-v1-abc123",
        "HIVE_OPENROUTER_BUDGET": "10.0"
      },
      "enabled": true
    }
  }
}

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

Example: Vault Only (No Worker)

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

Claude Code

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

Codex CLI

[mcp_servers.hive-vault]
command = "uvx"
args = ["--upgrade", "hive-vault"]

[mcp_servers.hive-vault.env]
VAULT_PATH = "~/my-vault"

Gemini CLI

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

Copilot (VS Code)

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/home/you/my-vault"
      }
    }
  }
}

OpenCode

{
  "mcp": {
    "hive": {
      "type": "local",
      "command": ["uvx", "--upgrade", "hive-vault"],
      "environment": {
        "VAULT_PATH": "/home/you/my-vault"
      },
      "enabled": true
    }
  }
}

Worker tools will still be available but will return “no providers available” when called.

Setting Up Ollama

Ollama lets you run LLMs locally for free. After installing:

# Pull the default model
ollama pull qwen2.5-coder:7b

# Verify it's running
curl http://localhost:11434/api/tags

If Ollama runs on a different machine (e.g., a homelab), set HIVE_OLLAMA_ENDPOINT to its address.

Setting Up OpenRouter

OpenRouter provides access to many models through a single API. Free tier models are available.

1. Create an account at openrouter.ai
2. Generate an API key at openrouter.ai/keys
3. Pass it as OPENROUTER_API_KEY when registering the MCP server

The default model (qwen/qwen3-coder:free) is free. Paid models are only used when you explicitly set max_cost_per_request > 0 on delegate_task calls, and are capped by HIVE_OPENROUTER_BUDGET.

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.

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

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)

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.

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)

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

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