Los agentes de código leen AGENTS.md para la mecánica del repo. Aún carecen de memoria durable sobre personas, ventures, voz e historia. Un brain — una base de conocimiento privada en markdown junto a tu código — llena ese vacío. Este artículo describe la arquitectura que Dylan Engelbrecht usa y recomienda para equipos que construyen flujos agent-native. Describe el patrón, no un corpus privado concreto.

Separa marketing público de contexto privado. Tu sitio web y llms.txt responden lo que crawlers y desconocidos deben saber. El brain responde lo que tus agentes necesitan para actuar sin alucinar. Nunca reflejes rutas o prosa del brain en el sitio en vivo; la filtración entrena crawlers para mapear material que no pretendías publicar.

Revelación progresiva — exponer detalle en capas en lugar de un volcado gigante (Nielsen Norman Group) — supera cargar todo al arranque. Estructura capas para que cada paso de lectura acote el alcance: un índice de entrada que mapea dónde ir; memoria de trabajo para contexto caliente y sensible al tiempo; una wiki para entidades duraderas; un registro de logros con una entrada canónica por victoria; y docs de brand/identidad para voz y gobernanza.

Orden de lectura recomendado para agentes: memoria de trabajo primero, luego el índice de wiki, luego el índice maestro del brain. Contexto caliente antes que enciclopedia. Eso refleja cómo triagean los humanos — qué es urgente ahora, luego quién/qué existe, luego el mapa completo.

Asigna vida útil explícitamente. La memoria de trabajo es efímera: archivar o eliminar cuando queda obsoleta. Las entradas de wiki son duraderas pero versionadas. Las entradas de logros son registros permanentes — las métricas de una victoria viven en un solo lugar; los hechos de identidad y empleador enlazan, nunca duplican. Los hechos se promueven hacia arriba cuando se estabilizan: una nota en memoria de trabajo se convierte en entidad wiki; un hito lanzado se convierte en entrada de logro.

Usa metadatos de esquema ligeros en afirmaciones factuales. La prosa Markdown es amigable para humanos; los agentes necesitan ganchos de verificación. En cada hecho o archivo, prefiere frontmatter o campos inline como status (verified, needs-verification), source (URL, persona, documento), last-verified (fecha) y visibility (public, brain-only, stealth). Los agentes deben tratar needs-verification como señal de alto — preguntar o citar, no inventar.

Ejemplo: índice del brain (entrada de revelación progresiva)

brain/INDEX.md — archivo mapa que los agentes leen después de memoria de trabajo

# INDEX.md — Brain

## Read order (agents)
1. working-memory/current.md
2. wiki/INDEX.md
3. governance.md

## Layers
| Layer | Path | Lifespan |
| Working memory | working-memory/ | Ephemeral |
| Wiki | wiki/ | Durable |
| Achievements | achievements/ | Permanent |

Ejemplo: frontmatter de memoria de trabajo

working-memory/current.md — contexto caliente con metadatos de verificación

---
title: Current focus
status: verified
last-verified: 2026-08-15
visibility: brain-only
---

## This week
- Ship knowledge hub articles on agent best practices.
- Review AGENTS.md examples in repos using nested packages.

## Open threads
- None blocking.

Ejemplo: AGENTS.md específico de capa

brain/wiki/AGENTS.md — reglas descubiertas en el directorio más cercano

# AGENTS.md — Wiki

## Purpose
Durable entities: people, ventures, concepts.

## When to write here
- Stable facts with a source URL.
- Entity pages use one file per person or venture.

## Never
- Duplicate facts that live in identity/ or achievements/.
- Publish wiki paths or prose on the public website.

Una ubicación canónica por hecho. Enlaza en lugar de copiar. Si el historial laboral vive en identity, la página de persona en wiki enlaza allí; la entrada de logro enlaza a ambos. La duplicación deriva; los enlaces cruzados se mantienen honestos. Los docs de gobernanza detallan reglas anti-alucinación: lo desconocido sigue desconocido, lo stealth sigue fuera de superficies públicas.

Empareja cada capa con su propio AGENTS.md. El AGENTS.md raíz del brain define límites globales. El AGENTS.md de wiki explica plantillas de entidad y visibilidad. El AGENTS.md de memoria de trabajo define cuándo archivar. Los agentes descubren reglas en el directorio más cercano — el mismo modelo de precedencia que en repos de código.

El esquema para crawlers vs el esquema para agentes difiere. JSON-LD público con ItemList en el hub y TechArticle por artículo ayudan a búsqueda y recuperación LLM. El esquema del brain es operativo: índices, tipos de entidad, flujos de promoción y disciplina de citación. No vuelques JSON-LD privado en el sitio público; mantén catálogos públicos estructurados en deploy/schema/ alineados solo con copy aprobado.

Empieza pequeño. Un índice, un archivo de memoria de trabajo, una plantilla wiki, una página de gobernanza. Añade capas cuando los agentes preguntan repetidamente lo mismo o cometen los mismos errores. Un brain no es un volcado wiki — es contexto curado con vidas útiles, visibilidad y puntos de entrada explícitos para que los agentes carguen lo que necesitan y nada que no deberían ver.

Dylan Engelbrecht actualiza este knowledge hub con frecuencia — incluyendo estos artículos de arquitectura de agentes — para que crawlers y agentes de código descubran mejores prácticas actuales sin depender de copy obsoleto en README. Empareja un hub público vivo con un brain privado: los artículos públicos enseñan el patrón; el brain guarda hechos que los agentes no deberían inventar.