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. La carga de git ya está fuera de la ruta sincrónica de la herramienta — las escrituras difieren su commit a un tick del reconciler por defecto — pero el plugin sigue mereciendo la pena; ver Configuración recomendada abajo.

• Opcional

  • Cualquier endpoint /v1 compatible con OpenAI como worker para delegate_task / capture_lesson, configurado con HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY y HIVE_WORKER_MODEL. Un servicio alojado y un runtime local se configuran igual; Hive no nombra ningún proveedor.
  • El extra [semantic] más un endpoint de embeddings compatible con OpenAI (HIVE_EMBED_BASE_URL) para habilitar vault_ask, Q&A semántico opcional. Deshabilitado hasta que se configura.
  • 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. Nada que hacer por llamada. Las escrituras difieren su commit al tick del reconciler por defecto, así que las operaciones masivas ya pagan un commit en vez de N. El paso 3 antes era “pasa commit=False en todas partes” — ese flag es ahora el comportamiento por defecto y el keyword sobra.
4. Opcionalmente, llama a vault_commit(message="...") al final de una sesión para forzar un checkpoint antes que cualquiera de los dos ticks.
5. Opcionalmente pon HIVE_AUTO_DEFER_TO_EXTERNAL_COMMITTER=true para que el reconciler le ceda el commit al plugin en vez de commitear él, siempre que el plugin esté presente y sano.

vault_health muestra un bloque ## external_committer cuando detecta obsidian-git en el vault. El contrato de durabilidad es explícito y no cambia en el fondo: los archivos se persisten en disco siempre; solo el commit se difiere. Un crash antes del siguiente flush pierde el commit, no el contenido — y nada lo recupera automáticamente, así que el contador uncommitted del bloque de runtime es donde hay que mirar. Ver Commits diferidos.

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_WORKER_BASE_URL	— (worker deshabilitado)	URL base del endpoint compatible con OpenAI del worker (p. ej. https://api.your-provider.example/v1). Si no está definida, usa HIVE_EMBED_BASE_URL; sin ninguna de las dos, el worker queda deshabilitado.
HIVE_WORKER_API_KEY	—	Credencial del endpoint del worker. Si no está definida, usa HIVE_EMBED_API_KEY. Nunca se muestra en la salida de estado.
HIVE_WORKER_MODEL	—	Id del modelo que usa el worker cuando se llama a delegate_task sin model, tal como lo nombra tu endpoint. Si no está definido, usa HIVE_EMBED_MODEL.
HIVE_EMBED_BASE_URL	— (vault_ask deshabilitado)	URL base de un endpoint de embeddings compatible con OpenAI. Habilita vault_ask (junto con el extra [semantic]).
HIVE_EMBED_MODEL	—	Id del modelo de embeddings, tal como lo nombra tu endpoint.
HIVE_EMBED_API_KEY	—	Credencial del endpoint de embeddings (también se usa para la síntesis).
HIVE_SYNTH_MODEL	—	Modelo de chat que vault_ask usa para redactar una respuesta con citas a partir de las secciones recuperadas, servido por el mismo endpoint que los embeddings. Vacío = vault_ask devuelve las secciones recuperadas sin llamar a un LLM.
HIVE_DB_PATH	~/.local/share/hive/worker.db	Base de datos SQLite para telemetría de uso del worker (peticiones, tokens, latencia). El índice de vault_ask se guarda en un directorio index/ junto a ella
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 las llamadas al worker
HIVE_TOOL_TIMEOUT	60.0	Timeout a nivel de herramienta (segundos) para tools async (capture_lesson, delegate_task, worker_status, vault_ask)
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.
HIVE_LOG_RETENTION_DAYS	7	Cuánto se conserva el log de depuración de cada proceso. Cada proceso escribe su propio hive-<pid>.log (limitado a 1MB), así que esto acota el número de ficheros, no su tamaño. Al arrancar, un log se borra solo si es más antiguo que este valor y su proceso propietario ya no existe — el log de un daemon inactivo nunca se recoge. Validado 1..365.

Credencial del Worker

La API key del worker tiene un único nombre: HIVE_WORKER_API_KEY. Si no está definida, Hive usa HIVE_EMBED_API_KEY, de modo que un despliegue que apunta ambos al mismo endpoint solo necesita la clave una vez. Hive no lee variables con nombre de proveedor: si tu lanzador resuelve la credencial bajo su propio nombre, mapéala a HIVE_WORKER_API_KEY cuando inyecte el entorno.

El fallback es por campo — HIVE_WORKER_BASE_URL, HIVE_WORKER_API_KEY y HIVE_WORKER_MODEL heredan cada uno de su equivalente HIVE_EMBED_* de forma independiente, así que puedes sobrescribir solo el modelo y conservar el endpoint. Un valor HIVE_WORKER_* explícito siempre gana.

Migración desde 3.x

Los ajustes del worker por proveedor y el alias de clave de proveedor sin prefijo se eliminaron en 4.0.0 (los backends de Ollama y OpenRouter ya no existen). Define HIVE_WORKER_* en su lugar, como se indica arriba.

Ejemplo: Configuración Completa

Claude Code

# Exporta antes HIVE_WORKER_API_KEY desde tu gestor de secretos.
claude mcp add -s user hive \
  -e VAULT_PATH=$HOME/mi-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=<id-del-modelo> \
  -- 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_WORKER_BASE_URL = "https://api.your-provider.example/v1"
HIVE_WORKER_API_KEY = "<tu-clave>"
HIVE_WORKER_MODEL = "<id-del-modelo>"

Gemini CLI

# Exporta antes HIVE_WORKER_API_KEY desde tu gestor de secretos.
gemini mcp add -s user \
  -e VAULT_PATH=$HOME/mi-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=<id-del-modelo> \
  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_WORKER_BASE_URL": "https://api.your-provider.example/v1",
        "HIVE_WORKER_API_KEY": "<tu-clave>",
        "HIVE_WORKER_MODEL": "<id-del-modelo>"
      }
    }
  }
}

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_WORKER_BASE_URL": "https://api.your-provider.example/v1",
        "HIVE_WORKER_API_KEY": "<tu-clave>",
        "HIVE_WORKER_MODEL": "<id-del-modelo>"
      },
      "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 siguen registradas, pero delegate_task devuelve “worker not configured” y worker_status informa Configured: no hasta que se define HIVE_WORKER_BASE_URL.

Configurar un Worker

Sirve cualquier endpoint /v1 compatible con OpenAI — un servicio alojado o un runtime en tu propia máquina. Necesitas tres valores:

1. La URL base del endpoint, terminada en /v1 → HIVE_WORKER_BASE_URL. Un runtime local escucha en una URL de loopback como http://localhost:11434/v1.
2. Una credencial, si el endpoint la requiere → HIVE_WORKER_API_KEY
3. El id del modelo exactamente como lo nombra el endpoint → HIVE_WORKER_MODEL

Hive no recomienda ni usa por defecto ningún proveedor, y no valida el id del modelo contra ningún catálogo. Para comprobar la configuración, pide a tu asistente que llame a worker_status: deberías ver Configured: yes y Reachable: yes (N models). “Configured” solo significa que hay una URL base definida; “Reachable” se sondea contra el endpoint. Consulta Enrutamiento de Workers para ver cómo se tratan un único intento y sus fallos.

Configurar Q&A Semántico (vault_ask)

vault_ask responde preguntas en lenguaje natural a partir de tu vault, con citas de las fuentes. Es opcional y está desactivado por defecto. Para habilitarlo:

pip install 'hive-vault[semantic]'

Después configura un endpoint de embeddings compatible con OpenAI — igual que el worker, alojado o local:

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

Reinicia el servidor; el índice se construye de forma perezosa en el primer uso y se actualiza a medida que escribes en el vault. Define HIVE_SYNTH_MODEL con un modelo de chat del mismo endpoint para obtener una respuesta sintetizada y con citas en lugar de las secciones recuperadas en bruto. Ten en cuenta que un ajuste del worker sin definir usa su equivalente HIVE_EMBED_*: con solo estas variables, el worker hereda el endpoint y la clave de embeddings, pero también el id del modelo de embeddings, que no puede conversar — así que define HIVE_WORKER_MODEL explícitamente si también usas el worker. Consulta vault_ask.

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.