Un brain es una arquitectura en markdown. Dylan Engelbrecht ha construido y refinado una para que los agentes puedan guardar mucho contexto y, aun así, elegir solo la información que importa para la tarea.
Actúa como un mapa. El agente no memoriza toda la biblioteca. Toma rumbo y luego abre un camino.
Esa idea tiene un nombre: progressive disclosure (Nielsen Norman Group). Es parecida a cómo piensan los humanos. Empiezas al principio con un mapa. Tomas rumbo. No lees primero cada nombre de calle de la ciudad.
El chat no es ese mapa. El chat es la conversación de ahora. AGENTS.md tampoco es ese mapa. Le dice al agente cómo trabajar en el repo: construir, probar, no romper la casa. El brain es memoria del mundo en el que actúa el agente: personas, servicios, decisiones, vocabulario, lo que pasó la semana pasada.
Los nombres de carpeta no son el protocolo. El protocolo es la forma: un índice, una descripción de una línea junto a cada entrada, y conocimiento que vive en un solo sitio.
Un recorrido (simplificado)
Un ejemplo muy simplificado, pero acompáñame.
La tarea es: «¿Cuál es mi comida favorita?»
El agente no carga todos los archivos. Empieza en el índice. El índice lista rutas de primer nivel. Cada línea es lo bastante corta para que el agente decida «abrir esto» o «saltar esto».
Toma el árbol de abajo con una pizca de sal. Adapta los nombres a tu mundo. Lo que importa es el índice, las descripciones de una línea, y que el conocimiento sea cohesivo.
Un árbol con una pizca de sal — adapta los nombres
AGENTS.md — mentions that the user's name is x
INDEX.md — the map
Wiki/
People/
x.md — a page about the user
y.mdEl agente ya vio en AGENTS.md que el nombre del usuario es x. Mira el índice. Ve Wiki/People/. Ve un archivo llamado x. Eso podría ser relevante, así que abre ese archivo. No abre y.md. No vuelca todo el wiki.
Dentro de x.md podría encontrar una nota: la comida favorita es una lima. La nota está marcada como no verificada. Quizá un agente anterior lo infirió. No está confirmado.
Así que el agente no debería decir: «Tu comida favorita es lima.» Debería decir algo como: «Creo que tu comida favorita es una lima, pero eso no está confirmado. ¿Es correcto?»
Eso es el protocolo en miniatura. Primero el mapa. Un acierto. Un archivo. Los hechos no confirmados reciben una pregunta, no una suposición.
Lo que tiene que hacer el índice
Si el agente tiene que abrir el archivo para saber si el archivo era relevante, el índice falló.
Una buena línea de índice es una pista de enrutado: tema, ruta, cuándo abrir. Los índices anidados (personas, servicios, incidentes) son más mapa, no más archivos de arranque. Un hecho vive en un sitio. Si lo necesitas en otro lugar, apunta. No lo copies. Las copias se desvían.
La misma regla aplica a las instrucciones. Gana el AGENTS.md más cercano a los archivos que se editan. Valores por defecto en la raíz. Excepciones junto al subárbol. Ver The AGENTS.md standard for AI coding agents.
Después del ejemplo de juguete: tres vidas útiles
Cuando ya has visto una búsqueda, las capas son más fáciles.
Algunas notas son para esta semana. Este incidente. Este lanzamiento. Archívalas o bórralas cuando queden obsoletas.
Algunas páginas siguen siendo ciertas a lo largo de semanas: personas, servicios, vocabulario, decisiones de arquitectura. Versiona esas.
Algunos registros ya ocurrieron y no deben reescribirse in situ: actas de incidentes, hitos lanzados, notas de auditoría. Enlaza para hechos de entidad. No dupliques.
Los hechos pueden moverse cuando se estabilizan. Una suposición que se confirma se convierte en una línea verificada en la página de la persona. Una instrucción de chat que aparece dos veces se convierte en una línea de playbook. Un nombre que reaparece se convierte en una entidad wiki. No inventes carpetas extra hasta que los agentes sigan haciendo la misma pregunta o el mismo error.
Anota cómo lo sabes
Markdown es fácil de leer para humanos. Los agentes también necesitan una señal de alto.
En cada hecho o archivo, indica:
status — verified, needs-verification o deprecated.
source — una URL, una persona, un ticket, un documento.
last-verified — una fecha.
Trata needs-verification como en el ejemplo de la lima. Pregunta o cita. No inventes. Lo desconocido sigue desconocido.
Eso es procedencia. Responde: ¿es esto cierto, según quién, desde cuándo?
El control de acceso es otro trabajo. Pregunta quién puede ver el archivo. Algunos brains necesitan etiquetas como interno, restricted o secreto. No pliegues eso en los campos de verificación.
Las reglas viven junto a la capa que gobiernan
Empareja cada capa con su propio AGENTS.md. El archivo raíz fija límites globales y el orden de lectura. El archivo wiki explica cuándo escribir una página de persona o de servicio. El archivo de contexto caliente dice cuándo archivar. Los agentes descubren reglas en el directorio más cercano. El mismo modelo de precedencia que en un repo de código.
El mismo recorrido, contexto de trabajo
Imagina un equipo que entrega una API de facturación. La tarea es: «¿Cuál es el failover de facturación?»
El agente empieza en el índice, no en la homepage pública. El índice dice: para el failover de facturación, abre wiki/runbooks/billing-failover.md. Abre ese runbook. No carga todas las páginas de servicio.
Un boceto de ese mapa:
INDEX.md — un mapa, no un volcado
# INDEX.md — Agent brain
## Read order
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md
## Layers
| Layer | Path | Lifespan |
| Hot context | working-memory/ | This week |
| Wiki | wiki/ | Stays true |
| Incidents | incidents/ | Already happened |
## Open when
| Signal | Path |
| On-call or Sev | working-memory/current.md, then incidents/ |
| What is service X? | wiki/services/INDEX.md |
| Billing failover | wiki/runbooks/billing-failover.md |El contexto caliente podría verse así — fíjate en la fuente y la fecha:
working-memory/current.md — esta semana, con procedencia
---
title: Current focus
status: verified
last-verified: 2026-08-29
source: #inc-1842 retro notes
---
## This week
- Billing retry storm after the card-network timeout change.
- Cut over invoice PDF rendering to the new worker.
## Open threads
- Confirm whether legacy accounts still hit /v1/invoices:finalize.Y la carpeta wiki puede llevar sus propias reglas, descubiertas solo cuando el agente está en esa carpeta:
wiki/AGENTS.md — reglas en el directorio más cercano
# AGENTS.md — Wiki
## Purpose
Durable entities: services, customers, concepts, runbooks.
## When to write here
- Stable facts with a source (ticket, spec, or named owner).
- One file per service or concept.
## Never
- Duplicate SLOs or owner names that live on the service page — link.
- Treat chat summaries as canonical.Sigue siendo un boceto. Un laboratorio podría guardar papers/ y experiments/. Un equipo de ops podría omitir incidents/ hasta la segunda repetición. Los nombres de carpeta no son el protocolo.
Empieza pequeño
Un índice. Un archivo de contexto caliente. Una plantilla de entidad. Una página que dice «si no lo sabes, pregunta».
Añade una capa cuando la repetición demuestra el hueco. Un brain no es un volcado wiki. Es un mapa, más archivos que abres a propósito, más el hábito de no inventar la lima.
Resumen
No vuelques el corpus. Empieza con un mapa y toma rumbo. Sigue una línea del índice. Abre un archivo. Cada almacén una vida útil. Cada afirmación una fuente. Una ubicación canónica. Reglas junto a la capa que gobiernan. Si no está confirmado, pregunta.
Dylan Engelbrecht actualiza este knowledge hub a medida que evoluciona la práctica con agentes. Trata estos artículos como referencia viva — práctica actual, no una instantánea congelada.