loletranga/Conocimiento-Personal-en-Grafo

Base de Conocimiento Personal × Grafo de Conocimiento (Basado en Archivos, Iterable)

Convierte un conjunto de documentos Markdown en una "red de conocimiento recuperable y trazable": cada documento recibe una capa de metadatos frontmatter, se vincula mediante tres tipos de relaciones para formar un grafo, y un script reconstruye las capas de destilación (registro de decisiones + lista de adyacencia del grafo), permitiendo al agente recuperar pensamientos pasados e historial de antecedentes antes del análisis y la toma de decisiones.

Concepto Central (Leer primero, luego actuar)

1. El documento fuente es la única fuente de verdad. El grafo no es un sistema independiente; el frontmatter y los enlaces dobles viven dentro de los archivos .md del usuario; el directorio graph/ es un artefacto puramente generado que se puede eliminar y reconstruir en cualquier momento. Todas las modificaciones ocurren solo en los documentos fuente.
2. La escritura primero debe confirmarse. El frontmatter lo redactas tú, pero antes de escribir en lote, debes mostrar una muestra al usuario y obtener su confirmación; las relaciones de juicio como supersedes (quién reemplazó a quién) deben enumerarse y confirmarse, sin escritura silenciosa.
3. Mejor degradar que forzar un dado. Los documentos de los que no se puede extraer una conclusión deben marcarse con status: reference, no inventes una conclusion. Una "frase de conclusión" incorrecta puede engañar al usuario durante la toma de decisiones y es más dañina que su ausencia.

Esta habilidad tiene dos archivos acompañantes (ubicados en el mismo directorio que este SKILL.md):

• scripts/gen_kb_graph.py —— Script de generación del grafo (solo biblioteca estándar, utilizable sin conexión)
• references/schema.md —— Especificación completa del frontmatter, semántica de los tres tipos de aristas, plantillas de salida, formato de salida de recuerdo. Léelo primero al construir la base por primera vez o si no estás seguro sobre algún campo.

---

Flujo de Ejecución

Paso 0: Determinar el alcance y explicar al usuario lo que sucederá

• Si el usuario da una carpeta → esa carpeta es el directorio raíz de la base de conocimiento.
• Si el usuario da uno o varios archivos → pregunta: ¿Usar la carpeta que contiene esos archivos como directorio raíz (recomendado, los documentos históricos pueden conectarse entre sí en el grafo) o crear una nueva carpeta de base de conocimiento independiente para ellos?
• Si el usuario no tiene ningún archivo y quiere construir la base primero → ve al Paso 2 "Esqueleto de base vacía".
• Antes de comenzar, confirma con el usuario en dos o tres frases: cuál es el directorio raíz, qué archivos se modificarán (frontmatter del documento fuente + nuevo directorio graph/), que el cuerpo del documento no se tocará.

Paso 1: Detectar el estado de la base de conocimiento

Lee el directorio raíz:

• Si ya existe <raíz>/gen_kb_graph.py o <raíz>/graph/INDEX.md → Modo Iteración (base existente)
• De lo contrario → Modo Construcción (base nueva)

Paso 2 A: Modo Construcción (incluye esqueleto de base vacía)

1. Esqueleto de base vacía (cuando el usuario no tiene archivos históricos): Crea los siguientes archivos y luego salta al Paso 3 para informar:
   • <raíz>/Resumen rápido de la especificación de la base.md: Extrae del references/schema.md la plantilla de frontmatter y las tres reglas principales, para que el usuario las consulte al escribir (viene con status: reference).
   • <raíz>/Plantilla-documento de análisis.md: Plantilla en blanco con frontmatter completo (también viene con su propio frontmatter).
2. Instalar script: Copia scripts/gen_kb_graph.py de este directorio de habilidad como <raíz>/gen_kb_graph.py (omitir si ya existe). Se incluye en la base para que sea autocontenida: el usuario u otros agentes pueden reconstruir el grafo sin depender de esta habilidad.
3. Ejecución de prueba: Ejecuta python3 <raíz>/gen_kb_graph.py <raíz>. Lee la descripción general de <raíz>/graph/report.md e informa al usuario sobre el tamaño (cuántos documentos, cuántos carecen de frontmatter).
4. Redactar metadatos (trabajo principal): Lee primero references/schema.md, luego procesa por subdirectorio o dominio en lotes:
   • Lee cada documento y redacta su frontmatter: date (fecha de la conclusión), domain, status (active/superseded/reference), conclusion (frase de conclusión, solo "qué defiende este documento", no resumen del contenido).
   • Primero muestra una muestra: Elige 2-3 documentos representativos (uno de decisión, uno de referencia) y muestra el frontmatter que escribirás. Una vez que el usuario confirme el formato, procede en lote.
   • Identifica relaciones evolutivas: pares de documentos donde el nombre contenga v2/nueva versión/copia/revisión, o donde el contenido se contradiga. Propón punteros supersedes, enumera en una lista para que el usuario confirme antes de escribir.
   • Informa el progreso después de cada lote; no modifiques ni una palabra del cuerpo, solo añade frontmatter.
5. Reconstruir y entregar: Vuelve a ejecutar el script (genera automáticamente graph/kb-graph.html como página de visualización), muestra al usuario las primeras líneas de INDEX.md y las brechas restantes de report.md, e informa que puede abrir kb-graph.html en un navegador para ver el grafo interactivo.

Paso 2 B: Modo Iteración (base existente)

1. Ejecuta el <raíz>/gen_kb_graph.py existente (si no existe, cópialo de nuevo del directorio de la habilidad).
2. Lee graph/report.md, procesa solo los incrementos: documentos nuevos sin frontmatter, documentos que carecen de date/conclusion, enlaces rotos. Redacta → confirma → escribe.
3. Complemento de aristas semánticas: Para los documentos nuevos, después de leerlos, propón relaciones related ("dos facetas del mismo tema") y supersedes ("este documento corrige aquel") con documentos existentes, adjuntando una frase de justificación. Escribe después de la confirmación.
4. Reconstruye (incluyendo la actualización de kb-graph.html para la visualización), e informa al usuario de los cambios (número de nodos/aristas añadidos, brechas restantes).

Paso 3: Informar al usuario cómo usar

Al final de cada construcción/iteración, sugiere al usuario que en el futuro use esto (las palabras originales son referencia):

En el futuro, antes de hacer un análisis o tomar una decisión, solo dime directamente: "Recuérdame mis pensamientos y conclusiones anteriores sobre XX". Yo consultaré el grafo, seguiré las cadenas evolutivas, verificaré la vigencia y te daré un informe de referencia. Si quieres ver el grafo visualmente, abre graph/kb-graph.html en tu navegador (puedes buscar, filtrar, hacer clic en nodos para ver detalles). Sigue escribiendo documentos como siempre; cuando termines, solo di "Actualiza la base de conocimiento" y yo añadiré automáticamente los metadatos y las relaciones a los nuevos documentos.

---

Modo Recuerdo (Recuperación antes de decisiones)

Cuando el usuario solicite recordar pensamientos pasados y el directorio de destino ya tenga artefactos graph/, sigue este proceso, solo lectura:

1. Lee graph/INDEX.md, empareja los títulos de documentos y conclusiones con palabras clave del tema, cribando elementos relevantes (más vale que sobren a que falten).
2. Si necesita expandir, lee graph/GRAPH.md: sigue las cadenas evolutivas de supersedes y los vecinos related de los documentos cribados para completar el contexto.
3. Lee en detalle el frontmatter y la sección de conclusiones de los documentos relevantes (no es necesario leer todo el documento).
4. Produce la salida en un formato fijo (ver ejemplo completo en references/schema.md):
   • Lista de líneas de pensamiento relevantes: cada línea = Fecha | Frase de conclusión | Estado | Enlace al documento
   • Cadena evolutiva: La trayectoria de cambio de pensamiento sobre el tema, indicando cuándo y por qué algo fue reemplazado/corregido.
   • Puntos de referencia para el problema actual: qué conclusiones se pueden reutilizar directamente, cuáles están desactualizadas y se debe tener cuidado.
   • Declaración de falta de precedente: Si no se encuentra un historial de decisión para el problema en el grafo, di explícitamente "Esta es una decisión completamente nueva, no hay precedentes pasados en los que basarse" — esto también es una salida valiosa.

---

Puntos de Confirmación con el Usuario (Debe Detenerse)

1. Antes de construir la base: alcance del directorio raíz, reglas de ignorar (se puede usar <raíz>/.kbignore para excluir directorios, una línea por patrón).
2. Antes de escribir frontmatter en lote: muestra de 2-3 documentos para confirmar.
3. Antes de escribir relaciones supersedes: confirmar la lista de pares.
4. Cualquier modificación del contenido del cuerpo: prohibida por defecto, solo con solicitud explícita del usuario.

Uso del Script

python3 gen_kb_graph.py <directorio_raíz_base_conocimiento> [--output graph] [--ignore "books,old,*_old"] [--no-html]

Ignorados por defecto: directorios ocultos, .venv, venv, node_modules, pycache, .git, el directorio de salida en sí. Idempotente, se puede volver a ejecutar en cualquier momento; produce 5 archivos (INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html), con formatos especificados en references/schema.md. kb-graph.html es una página de visualización de un solo archivo sin dependencias (grafo de diseño dirigido por fuerzas + tabla de lista de decisiones, con soporte para búsqueda/filtro/clic en detalles/doble clic para abrir el archivo fuente), que se puede abrir directamente en un navegador para mostrar al usuario si el entorno lo permite.

Límite de Escalado

Cuando los documentos superan aproximadamente 500, GRAPH.md no se puede leer de una vez, o se necesita razonamiento con múltiples saltos frecuentes, el grafo basado en archivos alcanza su límite. Se sugiere al usuario migrar a LightRAG (recuperación híbrida grafo + vectorial) — el frontmatter y los enlaces dobles son el mejor corpus de migración, la migración es sin pérdida. Antes de eso, no introduzcas bases de datos ni servicios externos.