Knowledge Graph

El Knowledge Graph es la columna vertebral del sistema de contexto de RaiSE. Fusiona todo — patrones de memoria, documentos de gobernanza, metadatos de skills, seguimiento de trabajo y componentes descubiertos — en un solo grafo de conceptos conectados.

Qué Es¶

Un grafo dirigido donde: - Nodos son conceptos — patrones, principios, requisitos, skills, stories, componentes, módulos - Edges son relaciones — "aprendido de", "gobernado por", "depende de", "restringido por"

Cuando ejecutas rai graph build, el CLI recorre todas las fuentes del proyecto y ensambla este grafo. Cuando consultas con rai graph query o rai graph context, estás buscando en este grafo.

Tipos de Nodos¶

Tipo	Patrón de ID	Fuente	Ejemplo
Pattern	`PAT-`, `BASE-`	Archivos JSONL de memoria	"Usar fixtures para tests de BD"
Calibration	`CAL-*`	Registros de calibración	Story S3.5: talla M, 45 min reales
Session	`SES-*`	Historial de sesiones	"Implementé módulo de auth"
Principle	`§N`	Constitución	"Heurísticas simples sobre ML complejo"
Requirement	`RF-*`	PRD	"Website de marketing con voz de artesano"
Guardrail	`GR-*`	Guardrails	"MUST: No vanity metrics como goals"
Skill	`/name`	Archivos SKILL.md	`/rai-story-plan` — descomponer en tareas
Story	`S.`	Seguimiento de trabajo	S8.6: Docs Getting Started
Epic	`E*`	Scope de epics	E8: Website v1 + Docs
Component	`comp-*`	Discovery scan	Clase `SessionManager`
Module	`mod-*`	Discovery analysis	`mod-memory` — subsistema de memoria
Decision	`ADR-*`	Decisiones de arquitectura	ADR-019: Grafo de contexto unificado

Tipos de Edges¶

Los edges expresan cómo se relacionan los conceptos:

Edge	Significado	Ejemplo
`learned_from`	El patrón vino de esta sesión	PAT-042 → SES-015
`governed_by`	El requisito implementa un principio	RF-01 → §2
`implements`	La story implementa un requisito	S8.6 → RF-05
`part_of`	La story pertenece a un epic	S8.6 → E8
`depends_on`	El módulo depende de otro	mod-session → mod-memory
`belongs_to`	El módulo pertenece a un dominio	mod-memory → bc-core
`constrained_by`	El dominio está restringido por un guardrail	bc-core → GR-015
`applies_to`	El patrón aplica a un skill	PAT-001 → /rai-story-implement

Construir el Grafo¶

rai graph build

Esto fusiona todas las fuentes: 1. Gobernanza: principios, requisitos, guardrails de governance/ 2. Memoria: patrones, calibración, sesiones de .raise/rai/memory/ 3. Trabajo: scopes de epics y stories de work/epics/ 4. Skills: metadatos de .claude/skills/*/SKILL.md 5. Componentes: código descubierto de work/discovery/ 6. Documentos: markdown libre que tú declares — ver abajo

La salida es .raise/rai/memory/index.json.

Indexar Documentos¶

Las fuentes 1–5 se descubren por convención. Tu prosa no: los SOPs, ADRs, RFCs, notas de investigación y scopes de trabajo viven donde tu equipo los puso, así que el grafo indexa solo los globs que declares en graph.document_sources.

Es opt-in y está vacío por defecto. Un proyecto que nunca lo configura obtiene cero nodos document — rai graph query encontrará tu código y tus patrones, pero nada de lo que escribiste en markdown. rai graph build imprime un aviso cuando eso ocurre:

hint: No documents indexed: 'graph.document_sources' is unset in .raise/manifest.yaml.

Configuración¶

Agrega una sección graph a .raise/manifest.yaml. Los patrones son globs relativos a la raíz del proyecto; ** es recursivo.

graph:
  document_sources:
  - dev/sops/*.md            # procedimientos operativos
  - dev/decisions/**/*.md    # ADRs
  - dev/rfcs/**/*.md
  - work/epics/*/scope.md    # qué se propuso cada epic
  - work/epics/*/design.md   # y cómo se diseñó
  - docs/concepts/*.md

Luego reconstruye:

rai graph build

Empieza angosto. Cada archivo se parte en un nodo por sección ##, así que un patrón amplio como work/**/*.md sobre un repo maduro puede agregar decenas de miles de nodos — builds más lentos y recuperación más ruidosa. Apunta a los documentos que de verdad querrías que un agente te cite.

Qué obtienes¶

Comportamiento	Detalle
Tipo de nodo	`document`, id `doc-<ruta-slug>-<n>` donde `n` es el ordinal de sección (base 0) — los ids son opacos, no los construyas desde un encabezado
Granularidad	Un nodo por sección `##`, para que la recuperación aterrice en la parte relevante de un documento largo, no en el archivo entero
Título	`title` del frontmatter YAML, si no el primer `# H1`, si no el nombre del archivo
`doc_type`	`doc_type` del frontmatter, si no se infiere de la ruta (`sops/` → `sop`, `rfcs/` → `rfc`, `research/` → `research`, `proposals/` → `proposal`)
Tags	`tags` del frontmatter (lista o cadena separada por comas)

Consúltalos como cualquier otro nodo:

rai graph query "procedimiento de rollback" --types document

Si un patrón no encuentra nada, rai graph build lo dice en vez de indexar en silencio menos de lo que pediste — un glob con typo no es un cero silencioso.

Antigüedad del Grafo¶

El grafo es una foto, no una vista en vivo. Una vez construido, no se entera de los commits que llegan después — rai session open corre un check advisorio de frescura en cada sesión para mostrar cuándo esa foto se alejó demasiado del checkout que describe.

La frescura se evalúa con dos señales independientes, cada una con un nivel warn y uno critical:

Señal	`warn` (default)	`critical` (default)
Antigüedad desde el último build	7 días	14 días
Commits llegados desde el último build	50 commits	100 commits

Basta con que cualquiera de las dos señales cruce su umbral — el grafo no necesita estar viejo y atrasado a la vez. El check nunca bloquea rai session open: ambos niveles se muestran como un warn advisorio, con el nombre del nivel y una sugerencia de rebuild en los datos del check, para que el developer decida si conviene correr rai graph build antes de apoyarse en reviews o patterns basados en el grafo esa sesión.

Configuración¶

Ajusta los umbrales por proyecto bajo graph.staleness en .raise/manifest.yaml. Cualquier clave que omitas cae al default — overrides parciales son seguros:

graph:
  staleness:
    warn_days: 5
    warn_commits: 20
    critical_days: 10
    critical_commits: 50

Un equipo de alta velocidad puede ajustar estos valores para detectar drift más pronto; un proyecto más pausado puede relajarlos para reducir ruido. Los mismos umbrales también alimentan los checks de rai doctor project-graph-age / project-graph-commits — una sola configuración, ambas superficies.

Consultar el Grafo¶

Búsqueda por Palabras Clave¶

Encontrar conceptos por contenido:

rai graph query "testing patterns"

Búsqueda por Concepto¶

Encontrar un concepto específico por ID:

rai graph query "PAT-001" --strategy concept_lookup

Contexto de Módulo¶

Obtener el contexto arquitectónico completo de un módulo — su dominio, capa, restricciones y dependencias:

rai graph context mod-memory

Esto retorna: - Bounded context: a qué dominio pertenece el módulo - Layer: su posición en la arquitectura (leaf, domain, integration, orchestration) - Constraints: guardrails aplicables (MUST y SHOULD) - Dependencies: de qué depende y qué depende de él

Validación¶

Verificar el grafo por problemas estructurales:

rai graph validate

Esto detecta ciclos en relaciones de dependencia, tipos de edge inválidos y referencias colgantes.

Por Qué un Grafo¶

La estructura de grafo habilita consultas contextuales — no solo "buscar esta palabra clave" sino "muéstrame todo lo relacionado con este módulo, incluyendo las reglas que lo restringen y los patrones aprendidos al construirlo."

Cuando tu partner de IA ejecuta rai session start --context, el CLI ensambla un bundle de contexto recorriendo este grafo. El resultado es una vista comprimida de todo lo relevante a tu trabajo actual — no un dump de todos los archivos, sino una selección curada de los nodos más importantes y sus relaciones.