Cómo sigue mejorando BrainAI: menos kernel, menos scripts y una métrica que no se cree sola

El problema no era que faltara IA. Era que el sistema no sabía si estaba mejorando.

BrainAI es un vault de conocimiento en Markdown para agentes: las fuentes crudas viven en raw/, el agente compila notas atómicas en wiki/, y el humano protege lo que refinó a mano en curated/. La idea viene del patrón LLM Wiki de Andrej Karpathy: en vez de recuperar fragmentos en cada consulta, el modelo mantiene una wiki persistente, enlazada y citable.

Después de la primera versión funcionando, el sistema tenía tres síntomas:

Síntoma Qué pasaba
Kernel monolítico AGENTS.md pesaba 569 líneas / 51,6 KB. Todo agente lo leía en cada sesión, aunque solo fuera a hacer /query.
Demasiados scripts Linter, merge y hook propios. Cada uno era código que mantener, probar y explicar.
Una métrica sola /compose optimizaba DEUDA (estructura del grafo), pero nadie medía si las respuestas mejoraban.

Estos son los ajustes que hicimos, y el loop que usamos para seguir mejorando.

Ajuste 1 — El kernel dejó de ser un manual

Antes, AGENTS.md mezclaba el contrato (reglas, ownership) con el procedimiento de cada operación. El agente leía los pasos de /ingest incluso cuando iba a hacer /status.

Ahora es contrato + router:

ANTES AHORA AGENTS.md (569 líneas) AGENTS.md (~322 líneas) ├─ reglas ├─ reglas críticas ├─ /ingest paso a paso ├─ ownership ├─ /query paso a paso └─ router: ├─ /lint paso a paso operación → Done → SKILL └─ ... │ ├─ SKILLS/ingest.md ├─ SKILLS/query.md └─ SKILLS/lint.md

El router tiene una fila por operación con disparador, criterio de cierre (Done) y archivo. Los pasos completos viven en SKILLS/, que se leen solo cuando esa operación se ejecuta.

Resultado: ~45% menos de contexto fijo y una sola fuente de verdad por procedimiento. Si cambia un paso, se edita el SKILL; si cambia una regla, se edita el kernel.

Ajuste 2 — Menos scripts, más herramientas nativas

No era una cruzada anti-tooling. Era notar que varios scripts reimplementaban cosas que el LLM ya hace bien:

Antes Ahora
Linter propio en Python verify_wikilinks.sh, verify_citations.sh, graph_health.sh
Script de merge para curated/ diff + sha256sum/shasum + confirmación humana
Hook para "proteger" archivos El límite real es el sandbox del agente o los permisos del SO

El caso de /accept-proposal es el más claro: el humano aprueba una propuesta, el agente muestra el diff exacto, verifica el hash de la nota curada y aplica solo ese delta. Sin parser propio. Menos código, más juicio.

Ajuste 3 — El índice dejó de ser un inventario

El índice listaba notas sueltas por tipo. Con 1.000 notas, eso es una lista que hay que releer y reordenar.

Ahora es MOC-only: el índice es un catálogo de dominios, y cada MOC es la puerta de entrada a sus átomos.

index.md └─ moc:infraestructura ├─ entity:prometheus ├─ concept:alerting └─ incident:caida-2026-03

El agente entra por el MOC del dominio y navega enlaces hasta el átomo exacto. El índice crece con los dominios, no con las notas.

Ajuste 4 — La métrica ahora tiene un guardrail

DEUDA mide estructura: notas-cubo, huérfanas, sub-enlazadas, dominios sin MOC. Es útil, pero puede bajar mientras las respuestas empeoran. Es el clásico problema de optimizar la métrica en vez del objetivo.

El protocolo ahora exige dos cosas:

  • Tope de costo en el protocolo de /compose: ciclos, tiempo y --max-tokens estimado. Sin tope, no se deja corriendo horas.
  • Un protocolo de evaluación en EVALUACION.md: 20–30 preguntas con respuesta conocida, baselines grep/MOC, y métricas de correctitud, citas válidas, tokens y latencia.

La regla es simple:

Si no hay benchmark, no se afirma mejora semántica; solo mejora estructural.

Cómo se sigue mejorando

El loop no es "agregar features". Es reducir una fricción y probar que el cambio fue mejor:

1. MEDIR graph_health.sh --score + 3–5 preguntas del benchmark 2. ELEGIR un solo cuello de botella (kernel, SKILL, índice, retrieval) 3. CAMBIAR una sola cosa 4. VERIFICAR citas + DEUDA + benchmark 5. REGISTRAR commit + issue + próxima hipótesis └────────── repetir ──────────┘

Si DEUDA sube, se revierte. Si DEUDA baja pero las respuestas empeoran, también se revierte. El número no decide solo.

Tres señales de que no estás mejorando

Señal Pregunta incómoda
DEUDA baja, respuestas peores ¿Mediste retrieval o solo estructura?
Aparecen más scripts ¿El LLM no podía hacerlo de forma fiable?
Los docs crecen ¿Esto es contrato, procedimiento o reference?

Lo que decidimos NO hacer (todavía)

  • RAG/embeddings: antes de agregar infraestructura, hay que medir si el retrieval dirigido por MOC alcanza.
  • Bajar a 100 líneas de golpe: es un objetivo abierto (#3), pero se hace por fases para no esconder reglas que el agente necesita ver. 322 líneas es el equilibrio actual.
  • chmod + hooks sobre curated/: el vault está en .gitignore; un hook no ve las notas. La protección real es el sandbox.
  • Declarar victoria: el benchmark está definido, pero todavía no hay resultados. La evidencia es el próximo paso.

Lo que viene

El repo tiene tres issues abiertos que muestran el siguiente tramo:

Cierre

Un sistema que mejora no es el que tiene más piezas. Es el que puede mostrar qué cambió, por qué y con qué evidencia.

El commit de esta iteración está en 60c4aa9. El siguiente paso no es más IA: es medir si la IA que ya está hace mejores preguntas y mejores respuestas.