Configuración

Toda la configuración se realiza mediante variables de entorno, pasadas al registrar el servidor MCP.

Requisitos

Hive se degrada de forma elegante — cada dependencia recomendada u opcional añade capacidad sin romper la línea base.

• Requerido

  • Python 3.12+ (funciona en 3.13).
  • Un directorio de archivos markdown. La estructura 00_meta / 10_projects / 50_work / 80_agents es opcional — sin ella, las herramientas de vault siguen funcionando pero el enrutamiento por scope es plano.

• Recomendado

  • git inicializado dentro del vault. Sin él, vault_write / vault_patch siguen escribiendo en disco; simplemente omiten el commit por escritura (y vault_commit reporta el árbol de trabajo como no rastreado).
  • La aplicación de escritorio Obsidian para escribir el vault a mano.
  • El plugin obsidian-git con auto-commit configurado a 5–10 minutos. Combínalo con vault_write(commit=False) / vault_patch(commit=False) para sacar la carga de git de la ruta sincrónica de la herramienta; ver Configuración recomendada abajo.

• Opcional

  • Ollama ejecutando qwen2.5-coder:7b (o compatible) para llamadas locales y gratuitas de delegate_task / capture_lesson.
  • Una API key de OpenRouter (OPENROUTER_API_KEY) como worker de respaldo (tier gratuito y de pago).
  • Un remote git de respaldo (por ejemplo, un repo privado en GitHub) para que el historial del vault sobreviva a una pérdida de disco.

Configuración recomendada

Según ADR-006 (política de commits), el pairing recomendado para flujos con muchas escrituras es:

1. Instala y activa el plugin obsidian-git en tu vault.
2. Configura su intervalo de auto-commit a 5 o 10 minutos.
3. Llama a vault_write(..., commit=False) y vault_patch(..., commit=False) para todas las operaciones masivas.
4. Opcionalmente, llama a vault_commit(message="...") al final de una sesión para forzar un checkpoint antes del siguiente tick de obsidian-git.

vault_health muestra un bloque ## external_committer cuando detecta obsidian-git en el vault. El contrato de durabilidad de commit=False es explícito: los archivos se persisten en disco siempre; solo el commit se difiere. Un crash antes del siguiente flush pierde el commit, no el contenido.

Cuando una llamada a una herramienta se cancela a mitad de ejecución (worker lento, timeout del cliente), el servidor puede haber mutado el disco antes de que el ack de cancelación llegue al wire. vault_health expone un contador ## ghost_responses y emite un WARNING mcp.ghost_response.suppressed_after_cancel_ack por cada evento — verifica el estado vía vault_query en lugar de reintentar, ya que el ack ErrorData no implica rollback (ADR-007).

Variables de Entorno

| Variable | Valor por defecto | Descripción | |---|---|---| | HIVE_VAULT_PATH | ~/Projects/knowledge | Ruta a tu vault de Obsidian (nombre canónico; también se acepta el VAULT_PATH sin prefijo). Para clientes MCP basados en fichero de configuración (Hermes, Cursor, Windsurf, …), defínelo en el bloque env del servidor en lugar de con un flag de CLI. | | HIVE_OLLAMA_ENDPOINT | http://localhost:11434 | Endpoint de la API de Ollama | | HIVE_OLLAMA_MODEL | qwen2.5-coder:7b | Modelo de Ollama por defecto | | HIVE_OPENROUTER_API_KEY | — | API key de OpenRouter | | HIVE_OPENROUTER_MODEL | qwen/qwen3-coder:free | Modelo de OpenRouter por defecto (tier gratuito) | | HIVE_OPENROUTER_PAID_MODEL | qwen/qwen3-coder | Modelo de pago para delegate_task | | HIVE_OPENROUTER_BUDGET | 1.0 | Presupuesto mensual máximo en USD | | HIVE_DB_PATH | ~/.local/share/hive/worker.db | Base de datos SQLite para tracking de presupuesto/uso | | HIVE_RELEVANCE_DB_PATH | ~/.local/share/hive/relevance.db | Base de datos SQLite para puntuación adaptativa de contexto | | HIVE_LESSON_DB_PATH | ~/.local/share/hive/lesson_reinforcement.db | Base de datos SQLite para contadores de refuerzo de lecciones + confianza decaída | | HIVE_STALE_THRESHOLD_DAYS | 180 | Días antes de que un archivo se marque como obsoleto | | HIVE_HTTP_TIMEOUT | 60.0 | Timeout HTTP (segundos) para Ollama y OpenRouter | | HIVE_TOOL_TIMEOUT | 60.0 | Timeout a nivel de herramienta (segundos) para tools async de worker (capture_lesson, delegate_task, worker_status) | | HIVE_LOCK_TIMEOUT_S | 30 | Timeout de adquisición del filelock de git (segundos). Sube a 60-90 en vaults grandes o bajo fuerte contención con obsidian-git. Validado 1..600. | | HIVE_WAL_CHECKPOINT_INTERVAL_S | 30.0 | Intervalo entre ticks de PRAGMA wal_checkpoint(PASSIVE) por proceso hive. Menor = drenaje del WAL más agresivo. Validado >0..3600. | | HIVE_OUTBOX_TICK_S | 5.0 | Intervalo (segundos) entre ticks del reconciliador que drena el outbox de refuerzo de lecciones hacia SQLite. Menor = visibilidad cross-process más rápida, mayor contención SQLite. | | HIVE_UPGRADE_POLL_S | 30.0 | Solo modo daemon (hive serve): segundos entre comprobaciones de drift de versión. Ante drift el daemon sale con 75 para que el supervisor lo reinicie con la nueva versión. Menor = adopta una versión nueva antes; validado >0..3600. Ver la guía de modo daemon. | | HIVE_AUTO_DEFER_TO_EXTERNAL_COMMITTER | false | Cooperación opt-in con obsidian-git: cuando es true Y obsidian-git está instalado Y sano, los vault_write / vault_patch de hive se tratan silenciosamente como commit=False para que obsidian-git los recoja en su siguiente tick. Ver la guía de integración con obsidian-git para el predicado completo y la semántica de fallback. | | HIVE_RELEVANCE_ALPHA | 0.3 | Tasa de aprendizaje EMA para puntuación adaptativa | | HIVE_RELEVANCE_DECAY | 0.9 | Factor de decaimiento por sesión para puntuaciones de relevancia | | HIVE_RELEVANCE_EPSILON | 0.15 | Ratio de exploración para session_briefing (epsilon-greedy) | | HIVE_VAULT_SCOPES | {"projects": "10_projects", "meta": "00_meta", "work": "50_work", "agents": "80_agents"} | Mapeo JSON de nombres de scope a subdirectorios del vault. Los scopes soportan resolución jerárquica (BFS). El scope agents contiene buzones de agentes de IA; el auto-scan prueba los scopes en orden de inserción, por lo que agents va al final para no eclipsar nombres de proyectos existentes. Cada directorio debe ser una ruta relativa única dentro del vault — los valores duplicados, absolutos o que escapan (..) se rechazan al iniciar. | | HIVE_LOG_PATH | ~/.local/share/hive/hive.log | Ruta del log persistente de depuración (rotación 1MB) | | HIVE_LOG_LEVEL | INFO | Nivel del log persistente. Captura los loggers hive, fastmcp y mcp. DEBUG para diagnóstico a nivel de transporte; WARNING para silenciar eventos de ciclo de vida. |

Resolución de API Key

La API key de OpenRouter soporta dos nombres por conveniencia:

• HIVE_OPENROUTER_API_KEY (con prefijo, estándar)
• OPENROUTER_API_KEY (sin prefijo, para entornos que ya la exportan)

Si ambas están definidas, la versión con prefijo HIVE_ tiene prioridad.

Ejemplo: Configuración Completa

Claude Code

claude mcp add -s user hive \
  -e VAULT_PATH=$HOME/mi-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

Agrega a ~/.codex/config.toml:

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

[mcp_servers.hive-vault.env]
VAULT_PATH = "~/mi-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/mi-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)

Agrega a .vscode/mcp.json (o a las settings de usuario de VS Code):

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

OpenCode

Agrega a ~/.config/opencode/opencode.jsonc:

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

El flag --upgrade asegura que siempre obtengas la última versión de PyPI al iniciar cada sesión.

Ejemplo: Solo Vault (Sin Worker)

Si solo necesitas acceso al vault sin delegación de tareas:

Claude Code

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

Codex CLI

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

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

Gemini CLI

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

Copilot (VS Code)

{
  "servers": {
    "hive-vault": {
      "command": "uvx",
      "args": ["--upgrade", "hive-vault"],
      "env": {
        "VAULT_PATH": "/home/tu-usuario/mi-vault"
      }
    }
  }
}

OpenCode

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

Las herramientas de worker seguirán disponibles pero devolverán “no hay proveedores disponibles” cuando se invoquen.

Configurar Ollama

Ollama te permite ejecutar LLMs localmente de forma gratuita. Después de instalar:

# Descargar el modelo por defecto
ollama pull qwen2.5-coder:7b

# Verificar que está ejecutándose
curl http://localhost:11434/api/tags

Si Ollama se ejecuta en otra máquina (ej. un homelab), configura HIVE_OLLAMA_ENDPOINT con su dirección.

Configurar OpenRouter

OpenRouter proporciona acceso a muchos modelos a través de una única API. Hay modelos de tier gratuito disponibles.

1. Crea una cuenta en openrouter.ai
2. Genera una API key en openrouter.ai/keys
3. Pásala como OPENROUTER_API_KEY al registrar el servidor MCP

El modelo por defecto (qwen/qwen3-coder:free) es gratuito. Los modelos de pago solo se usan cuando estableces explícitamente max_cost_per_request > 0 en las llamadas a delegate_task, y están limitados por HIVE_OPENROUTER_BUDGET.

Activar Hive en tu Flujo de Trabajo

Instalar y registrar Hive hace que las herramientas estén disponibles, pero tu asistente de IA necesita guía sobre cuándo usarlas. Tu archivo de instrucciones de proyecto (CLAUDE.md, GEMINI.md, o equivalente en tu cliente MCP) es la clave.

Sin instrucciones explícitas, tu asistente podría usar las herramientas de Hive, pero de forma inconsistente. Con instrucciones claras, las usa de forma predecible para cada consulta relevante.

Fragmento de Instrucciones Recomendado

Agrega esto a tu archivo de instrucciones de proyecto (CLAUDE.md, GEMINI.md, o equivalente):

## Vault y Conocimiento (Hive MCP)

Cuando hive-vault MCP esté disponible, úsalo para contexto on-demand:
- `vault_query(project="miproyecto", section="context")` — resumen del proyecto
- `vault_query(project="miproyecto", section="tasks")` — backlog activo
- `vault_search(query="...")` — búsqueda cross-vault
- `session_briefing(project="miproyecto")` — contexto completo en una llamada

Al escribir en el vault: lecciones -> `90-lessons.md`, decisiones -> `30-architecture/`.

Reemplaza miproyecto con el slug real de tu proyecto (el nombre del directorio bajo 10_projects/).

Cómo Funciona la Selección de Herramientas MCP

1. Registro — Los servidores MCP se cargan al inicio de sesión. Tu cliente ve todas las herramientas de todos los servidores.
2. Descubrimiento — El asistente lee los nombres y descripciones de las herramientas para entender las capacidades.
3. Enrutamiento — Tus instrucciones en CLAUDE.md le dicen al asistente qué herramientas preferir en cada situación. Múltiples servidores MCP coexisten sin conflicto — cada uno sirve su dominio.
4. Adaptación — El session_briefing de Hive aprende de tus patrones de uso. Las secciones que consultas frecuentemente se priorizan automáticamente en futuros briefings.

Automatizar Session Briefing (Claude Code Hooks)

Claude Code soporta hooks — comandos shell que se ejecutan en respuesta a eventos del ciclo de vida. Puedes usar un hook SessionStart para recordar automáticamente a tu asistente que cargue contexto de Hive al inicio de cada sesión.

Opción 1: Inyección de Contexto (Recomendado)

Agrega un hook SessionStart que emite un recordatorio del sistema. El texto se inyecta en la conversación automáticamente:

En ~/.claude/settings.json (o .claude/settings.json por proyecto):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Llama a session_briefing(project=\"miproyecto\") para cargar contexto antes de empezar.'"
          }
        ]
      }
    ]
  }
}

Reemplaza miproyecto con el slug de tu proyecto en el vault. El asistente verá el recordatorio y llamará a session_briefing al inicio de cada sesión.

Opción 2: Hook de Agente (Autónomo)

Para carga de contexto completamente automática sin invocación manual, usa un hook de agente. Esto lanza un subagente ligero que llama a la herramienta directamente:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "agent",
            "prompt": "Llama a session_briefing(project=\"miproyecto\") y presenta los resultados al usuario.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Esto es más autónomo pero lanza un subagente (consumiendo tokens extra). La Opción 1 suele ser suficiente ya que el asistente sigue el recordatorio inyectado de forma fiable.

Notas

• Los hooks son una funcionalidad de Claude Code, no de Hive. Otros clientes MCP pueden tener sus propios mecanismos de automatización.
• También puedes usar hooks UserPromptSubmit para inyección de contexto por mensaje, pero SessionStart es el ajuste natural para briefings.
• Consulta claude /hooks dentro de Claude Code para gestionar hooks interactivamente.