---
title: Herramientas de Vault
description: 7 herramientas para consultar, buscar y gestionar tu vault de Obsidian.
---

## vault_list

Lista proyectos o navega archivos dentro de un proyecto.

```python
# 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

Lee secciones o archivos bajo demanda.

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

```python
# 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

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

```python
# 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

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

```python
# 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

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

```python
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

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

```python
# 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.
