---
name: vault_knowledge_parse
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def vault_knowledge_parse(vault_path: str, rel_path: str, db_path: str | None = None) -> dict"
description: "Parsea un archivo Markdown del vault: extrae YAML frontmatter, título, headings y cuerpo; persiste en knowledge_docs y actualiza files_fts para búsqueda por contenido."
tags: [vault, markdown, knowledge, frontmatter, headings, fts, infra]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [json, re, sqlite3, time, pathlib, yaml]
params:
  - name: vault_path
    desc: "Ruta absoluta a la raiz del vault donde vive el Markdown y vault_index.db."
  - name: rel_path
    desc: "Ruta relativa al archivo .md dentro del vault (ej. 'docs/guia.md')."
  - name: db_path
    desc: "Override opcional de la ruta a vault_index.db. Por defecto <vault_path>/vault_index.db."
output: "Dict con: rel_path (str), title (str), frontmatter (dict), headings (list de {level, text}), content_text (str cuerpo sin frontmatter), persisted (bool)."
tested: true
tests:
  - "test_md_with_frontmatter"
  - "test_md_no_frontmatter"
  - "test_md_title_from_h1"
  - "test_md_title_from_filename"
  - "test_md_headings_levels"
  - "test_md_persists_to_fts"
test_file_path: "python/functions/infra/tests/test_vault_knowledge_parse.py"
file_path: "python/functions/infra/vault_knowledge_parse.py"
---

## Ejemplo

```python
from vault_knowledge_parse import vault_knowledge_parse

result = vault_knowledge_parse("/vaults/mi_vault", "docs/guia_operaciones.md")
# {
#   "rel_path": "docs/guia_operaciones.md",
#   "title": "Guía de Operaciones",
#   "frontmatter": {"author": "Lucas", "tags": ["ops"]},
#   "headings": [{"level": 1, "text": "Guía de Operaciones"}, {"level": 2, "text": "Instalación"}],
#   "content_text": "# Guía de Operaciones\n\n## Instalación\n...",
#   "persisted": True
# }
```

## Notas

- Prioridad de título: frontmatter["title"] > primer H1 en el cuerpo > basename sin extensión.
- Frontmatter YAML delimitado por `---\n` al inicio del archivo. Si no hay frontmatter, se retorna {}.
- content_text es el cuerpo completo sin el bloque frontmatter (incluye los headings H1-H6).
- El rowid de files_fts se ancla al rowid de la tabla files para que vault_search funcione correctamente.
- Si vault_index.db no existe, retorna el dict sin intentar persistir (persisted=False).
- Dependencias: pyyaml (ya instalado en python/.venv).