Ir al contenido
Hive

Herramientas de Vault

vault_list

Sección titulada «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.

vault_query

Sección titulada «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).

Sección titulada «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")

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.

vault_health

Sección titulada «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.

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

Sección titulada «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

Sección titulada «vault_patch»

Reemplazo quirúrgico de texto en un archivo del vault.

vault_patch(
    project="mi-proyecto",
    path="30-architecture/adr-001.md",
    old_text="status: draft",
    new_text="status: accepted"
)

Reemplaza exactamente una ocurrencia de old_text con new_text. Rechaza coincidencias ambiguas — si old_text aparece más de una vez, la operación falla con un error pidiendo más contexto. Auto-commit a git.

capture_lesson

Sección titulada «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.