¿Qué es brain.md?
brain.md es una convención más una herramienta para dejar por escrito lo que un agente de programación no debería olvidar de un proyecto. brain init añade un archivo de protocolo BRAIN.md, una carpeta brain/ y un bloque marcado en CLAUDE.md y AGENTS.md que indica a cualquier agente cómo usarlo. Cada página tiene una de seis categorías, como decision, concept o reference, un resumen actual reescribible y una cronología de evidencias a la que solo se añade, y toda escritura pasa por la CLI brain para que el formato siga siendo válido.
Cuatro skills lo mueven: brain-setup prepara y conecta un proyecto, brain-bootstrap redacta las primeras páginas a partir del código, la documentación y el git log o entrevistándote, brain-page es el manual para leer y escribir, y brain-ingest incorpora una conversación o un documento al brain. Hooks SessionStart opcionales para Claude Code y Codex entregan al agente el índice de páginas al empezar cada sesión.
La CLI es un script de Node.js sin dependencias, publicado en npm como @mindmux/brain-md con licencia Apache 2.0 por MindMux. El repositorio se creó en junio de 2026; la v0.4.2 salió el 13 de noviembre de 2026.
¿Merece la pena brain.md?
La idea es sensata y el alcance, honesto. brain.md no intenta registrar todo lo que hace un agente; le pide que capture solo lo que seguirá importando dentro de seis meses y no se puede deducir del código, y que deje rastro cuando esa comprensión cambie. update-truth reescribe el resumen de una página y añade una entrada a la cronología en una sola escritura, así que una decisión revertida deja constancia en lugar de desaparecer.
No hay mucho código detrás, y eso es a la vez su atractivo y su límite. La CLI y el instalador suman unas 1.750 líneas de JavaScript sin dependencias, más cuatro archivos de skill y pruebas. No hay comando de búsqueda: el agente lista las páginas por id, título y categoría y lee las que parecen relevantes, lo que funciona con decenas de páginas y se complica con cientos. La captura depende de que el agente siga BRAIN.md; nada registra una sesión automáticamente, a diferencia de claude-mem o ai-memory, así que un agente ocupado puede olvidarlo sin más.
Los hooks son comedidos. El hook SessionStart de Codex envía solo el índice de páginas, con un tope de 8 KiB, tiene cinco segundos para ejecutarse y sale sin ruido si la CLI falla; necesita Node 18 y un shell POSIX, así que Windows nativo queda fuera. Los hooks contienen una ruta absoluta y hay que reinstalarlos cuando se mueve un proyecto. Como el brain vive en el repositorio, cualquiera con acceso al repo puede leerlo, que es justo la idea, y también un motivo para no meter secretos.
La adopción es modesta: 722 estrellas, nueve colaboradores y 814 descargas en npm en los 30 días hasta el 19 de noviembre. Para un equipo que ya lleva registros de decisiones de arquitectura, brain.md añade un formato que se ordena mantener a los agentes; para uno que no lleva nada, es un primer paso barato.
Dónde se gana su sitio
Un equipo de tres personas cuyos agentes reabren una y otra vez decisiones de diseño ya cerradas
Que el agente lea las decisiones pasadas antes de proponer otro enfoque
Ejecuta brain init y luego la skill brain-bootstrap para redactar páginas de decisión a partir del git log; el bloque de CLAUDE.md indica al agente que cargue las páginas relevantes al empezar cada tarea. Gratis, y las páginas aparecen en la revisión de código.
Un desarrollador que alterna entre Claude Code y Codex en un mismo repositorio
Dar a ambos agentes el mismo conocimiento del proyecto al iniciar sesión
Instala los hooks SessionStart de ambos con brain install-hooks y brain install-hooks --agent codex; cada sesión recibe el índice de páginas, hasta 8 KiB, y lee las páginas completas cuando las necesita.
Antes de decidirte
- Puesta en marcha
- npm install -g @mindmux/brain-md, después brain setup -y para copiar las skills en cada agente detectado y, por último, brain init en el proyecto. Necesita Node 18 o posterior.
- Integraciones
- Skills de agente para Claude Code, Codex, Cursor y Pi; hooks SessionStart para Claude Code y Codex; cualquier agente que lea AGENTS.md o CLAUDE.md puede seguir el protocolo. Sin servidor MCP.
- Datos y privacidad
- Las páginas son Markdown en la carpeta brain/ del repositorio, o en una ruta fijada con brainRoot; la CLI no envía nada a ninguna parte. Todo lo que escribe el agente es visible para cualquiera con acceso al repositorio.
- Límites
- Sin búsqueda ni embeddings; la instantánea del hook de Codex tiene un tope de 8 KiB y cinco segundos; los hooks guardan una ruta absoluta y hay que reinstalarlos tras mover el proyecto; no admite shells nativos de Windows.
Lo bueno
- Markdown plano en el repo, versionado con el código
- La cronología de solo añadir conserva el motivo de cada cambio de decisión
- CLI sin dependencias; nada que alojar
- La skill de arranque redacta las primeras páginas a partir del código y el git log
Lo malo
- Sin búsqueda; los agentes recorren una lista de páginas
- La captura depende de que el agente se acuerde de escribir
- Los hooks necesitan un shell POSIX; sin soporte para Windows nativo
- Proyecto pequeño: 9 colaboradores, 814 descargas al mes en npm
Ideal para
Equipos pequeños que quieren que Claude Code o Codex guarden las decisiones y restricciones de arquitectura en el repositorio, en un formato que una persona pueda revisar en un pull request.
Alternativas a brain.md
brain.md: preguntas frecuentes
- ¿Merece la pena brain.md?
- brain.md es una forma ordenada de que un agente apunte por qué se tomó una decisión, y hace poco más que una carpeta de documentación bien llevada con reglas más estrictas. Le damos un 3.4 sobre 5.
- ¿Cuánto cuesta brain.md?
- Gratis con licencia Apache 2.0; sin servicio ni cuenta.
- ¿Qué inconvenientes tiene brain.md?
- Sin búsqueda; los agentes recorren una lista de páginas; la captura depende de que el agente se acuerde de escribir; los hooks necesitan un shell POSIX; sin soporte para Windows nativo; proyecto pequeño: 9 colaboradores, 814 descargas al mes en npm.
- ¿Para quién es brain.md?
- Equipos pequeños que quieren que Claude Code o Codex guarden las decisiones y restricciones de arquitectura en el repositorio, en un formato que una persona pueda revisar en un pull request.
- ¿Es brain.md seguro para los datos de la empresa?
- Las páginas son Markdown en la carpeta brain/ del repositorio, o en una ruta fijada con brainRoot; la CLI no envía nada a ninguna parte. Todo lo que escribe el agente es visible para cualquiera con acceso al repositorio.
- ¿Cuáles son las mejores alternativas a brain.md?
- Las alternativas más cercanas que hemos analizado son ai-memory, claude-obsidian y OpenWiki.
Respuestas comprobadas el 20 nov 2026.