Herramientas de Vault

vault_list

Lista proyectos o navega archivos dentro de un proyecto.

# Listar todos los proyectos
vault_list()

# Navegar archivos de un proyecto
vault_list(project="mi-proyecto")

# Navegar un subdirectorio
vault_list(project="mi-proyecto", path="30-architecture")

# Filtrado con patrón glob
vault_list(project="mi-proyecto", pattern="adr-*")

Sin project, lista todos los proyectos del vault con recuento de archivos y atajos. Con project, lista archivos y directorios (directorios primero, luego archivos). Con pattern, busca recursivamente todos los archivos que coincidan.

Resolución de scopes

Los proyectos se organizan en scopes — directorios de nivel superior del vault. Por defecto, Hive incluye tres scopes:

Scope	Directorio	Propósito
`projects`	`10_projects/`	Proyectos personales
`work`	`50_work/`	Trabajo: productos, clientes, tickets, desarrollo
`meta`	`00_meta/`	Patrones y plantillas cross-proyecto

Usa la sintaxis scope:slug para apuntar a un scope específico: vault_list(project="work:hydra3d-plus").

Scopes jerárquicos: El scope work (y cualquier scope) soporta directorios anidados. Si un slug no se encuentra como hijo directo del directorio del scope, Hive busca recursivamente usando búsqueda en amplitud (BFS). Por ejemplo, work:hydra3d-plus resuelve a 50_work/20-products/hydra3d-plus/ automáticamente.

Usa rutas explícitas con / para saltar BFS: work:20-products/hydra3d-plus.

Sin prefijo de scope, Hive escanea todos los scopes en orden — la primera coincidencia gana.

vault_query

Lee secciones o archivos bajo demanda.

vault_query(
    project="mi-proyecto",
    section="context",       # context | tasks | roadmap | lessons
    path="",                 # ruta arbitraria (sobreescribe section)
    max_lines=200,           # 0 = sin límite
    include_metadata=False   # anteponer resumen de frontmatter
)

Los atajos de sección mapean a archivos:

context -> 00-context.md
tasks -> 11-tasks.md
roadmap -> 10-roadmap.md
lessons -> 90-lessons.md

Usa path para archivos arbitrarios: vault_query(project="mi-proyecto", path="30-architecture/adr-001.md")

Usa project="_meta" para acceder a 00_meta/ (patrones cross-proyecto).

vault_search

Búsqueda full-text en el vault con ranking opcional y modo de cambios recientes.

# Búsqueda estándar por palabra clave
vault_search(
    query="autenticación",
    max_lines=100,
    type_filter="",     # filtrar por tipo en frontmatter
    status_filter="",   # filtrar por estado en frontmatter
    tag_filter="",      # filtrar por tag en frontmatter
    use_regex=False     # tratar query como expresión regular
)

# Búsqueda con ranking (puntuación de relevancia)
vault_search(query="deployment", ranked=True, max_results=5)

# Cambios recientes (últimos N días)
vault_search(since_days=7, project="mi-proyecto")

# Restringir búsqueda a un scope
vault_search(query="LVDS", scope="work")

Modo estándar: Devuelve líneas coincidentes agrupadas por archivo, con cabeceras de metadatos. Cuando use_regex=True, la query se compila como expresión regular de Python (case-insensitive).

Modo ranking (ranked=True): Puntúa resultados por peso de estado (active > draft > archived), recencia y densidad de coincidencias. Devuelve los mejores resultados con metadatos y líneas coincidentes.

Modo reciente (since_days > 0): Combina historial de git con fechas created del frontmatter para encontrar archivos modificados en los últimos N días. Filtro opcional por project.

Filtro de scope (scope): Restringe la búsqueda a un solo scope (ej. "work", "projects"). Funciona en los tres modos. Sin scope, busca en todo el vault.

vault_health

Métricas de salud, detección de drift y estadísticas de uso.

# Reporte de salud de todos los proyectos
vault_health()

# Validar un proyecto específico
vault_health(project="mi-proyecto", checks=["frontmatter", "stale", "links"], max_issues=50)

# Incluir estadísticas de uso
vault_health(include_usage=True, usage_days=30)

Reporte de salud (por defecto): Recuento de archivos por proyecto, total de líneas, archivos obsoletos (>180 días, configurable vía HIVE_STALE_THRESHOLD_DAYS), cobertura de secciones. También detecta nombres de directorio duplicados en scopes jerárquicos y advierte qué ruta resolverá BFS.

Validación (parámetro checks): Detector de drift para problemas comunes:

frontmatter: Frontmatter YAML faltante o malformado, campos requeridos ausentes (id, type, status), fechas no parseables
stale: Archivos activos no modificados en HIVE_STALE_THRESHOLD_DAYS (por defecto 180)
links: [[wikilinks]] rotos apuntando a archivos inexistentes

Los problemas se categorizan como [error] o [warning] con ruta del archivo y descripción.

Estadísticas de uso (include_usage=True): Recuento de llamadas a herramientas por herramienta y proyecto, con ahorro estimado de tokens.

vault_write

Crea, agrega o reemplaza archivos del vault con validación y auto-commit a git.

# Agregar a un archivo existente
vault_write(
    project="mi-proyecto",
    section="lessons",
    content="Nueva lección aprendida...",
    operation="append"      # por defecto
)

# Reemplazar un archivo completo (requiere frontmatter válido)
vault_write(
    project="mi-proyecto",
    section="context",
    content="---\nid: mi-proyecto\ntype: project\nstatus: active\n---\n\nContenido nuevo.",
    operation="replace"
)

# Crear un nuevo archivo con frontmatter auto-generado
vault_write(
    project="mi-proyecto",
    path="30-architecture/adr-005.md",
    content="# ADR-005: PostgreSQL\n\n## Contexto\n...",
    operation="create",
    doc_type="adr"          # usado en frontmatter generado
)

append: Agrega contenido al final de un archivo existente
replace: Reemplaza el archivo completo. Requiere frontmatter YAML válido con id, type, status
create: Crea un nuevo archivo. Auto-genera frontmatter con id, type, status: draft, created: hoy

Todas las operaciones hacen auto-commit a git.

vault_patch

Buscar y reemplazar quirúrgico en un archivo del vault.

# Reemplazo simple
vault_patch(
    project="mi-proyecto",
    path="30-architecture/adr-001.md",
    find="status: draft",
    replace="status: accepted"
)

# Múltiples reemplazos (aplicados en secuencia)
vault_patch(
    project="mi-proyecto",
    path="11-tasks.md",
    patches=[
        {"find": "- [ ] Tarea uno", "replace": "- [x] Tarea uno"},
        {"find": "- [ ] Tarea dos", "replace": "- [x] Tarea dos"},
    ]
)

Reemplaza exactamente una ocurrencia de find con replace. Rechaza coincidencias ambiguas — si find aparece más de una vez, la operación falla con un error pidiendo más contexto. Usa coincidencia en cascada de 3 pasadas: exacta → solo cuerpo → normalizada por espacios. Auto-commit a git.

capture_lesson

Captura lecciones inline o extracción por lotes desde texto usando un worker.

# Captura inline (estructurada, una lección)
capture_lesson(
    project="mi-proyecto",
    title="La causa raíz era caché obsoleta",
    context="Depurando fallo de deploy",
    problem="El servicio devolvió 500 después del deploy",
    solution="Limpiar caché de Redis después de cambios de configuración",
    tags=["deploy", "cache"]    # opcional
)

# Extracción por lotes (con worker, múltiples lecciones)
capture_lesson(
    project="mi-proyecto",
    text="Descubrimos que la caché estaba obsoleta después del deploy...",
    min_confidence=0.7,
    max_lessons=5
)

Modo inline (sin text): Agrega una entrada estructurada a 90-lessons.md con fecha, contexto, problema y solución. Crea el archivo con frontmatter si no existe. Deduplicación por título. Auto-commit a git.

Modo por lotes (text proporcionado): Envía el texto a un modelo worker (Ollama/OpenRouter) que extrae lecciones estructuradas (título, contexto, problema, solución, tags, confianza). Las lecciones por encima del umbral de confianza se escriben en 90-lessons.md con deduplicación.

Cuándo usar: Inmediatamente después de descubrir la causa raíz de un bug, un insight arquitectónico o un truco de depuración — no esperes al final de la sesión.