Pular para o conteúdo
ReviewRamble

A newsletter semanal

IA, analisada, na sua caixa de entrada.

  • Novas análises de ferramentas, modelos, servidores MCP e repositórios, com o veredicto logo no início
  • Preços e notas reconferidos quando algo muda
  • Novos artigos de análise assim que são publicados

Modelos, agentes, servidores MCP e as ferramentas que realmente valem seu tempo.

Um e-mail por semana. Cancele pelo link em qualquer edição. Como usamos seu e-mail

brain.md

A pequena CLI da MindMux e quatro skills de agente que guardam as decisões e restrições de um projeto como páginas Markdown no repositório.

Análise de ReviewRamble editors · Atualizado

Ver no GitHub Código aberto

Compartilhe esta página:XLinkedInFacebookRedditWhatsAppE-mail

Nossa nota

3.4/5

O brain.md é um jeito organizado de fazer um agente anotar por que uma decisão foi tomada, e faz pouco mais que uma pasta de documentação bem cuidada com regras mais rígidas.

O que é brain.md?

O brain.md é uma convenção mais uma ferramenta para registrar o que um agente de código não deveria esquecer sobre um projeto. brain init adiciona um arquivo de protocolo BRAIN.md, uma pasta brain/ e um bloco marcado no CLAUDE.md e no AGENTS.md que explica a qualquer agente como usá-lo. Cada página tem uma de seis categorias, como decision, concept ou reference, um resumo atual reescrevível e uma linha do tempo de evidências que só recebe acréscimos, e toda gravação passa pela CLI brain para manter o formato válido.

Quatro skills fazem tudo andar: brain-setup prepara e conecta um projeto, brain-bootstrap rascunha as primeiras páginas a partir do código, da documentação e do git log ou entrevistando você, brain-page é o manual de leitura e escrita, e brain-ingest incorpora uma conversa ou documento ao brain. Hooks SessionStart opcionais para Claude Code e Codex entregam ao agente o índice de páginas no início de cada sessão.

A CLI é um script Node.js sem dependências, publicado no npm como @mindmux/brain-md sob a licença Apache 2.0 pela MindMux. O repositório foi criado em junho de 2026; a v0.4.2 saiu em 13 de novembro de 2026.

brain.md vale a pena?

A ideia é sensata e o escopo, honesto. O brain.md não tenta registrar tudo o que um agente faz; pede que ele guarde só o que ainda vai importar daqui a seis meses e não dá para tirar do código, e que deixe rastro quando esse entendimento mudar. update-truth reescreve o resumo de uma página e acrescenta uma entrada na linha do tempo numa única gravação, então uma decisão revertida deixa registro em vez de sumir.

Não há muito código por trás, e isso é ao mesmo tempo o atrativo e o limite. A CLI e o instalador somam cerca de 1.750 linhas de JavaScript sem dependências, mais quatro arquivos de skill e testes. Não há comando de busca: o agente lista as páginas por id, título e categoria e lê as que parecem relevantes, o que funciona com dezenas de páginas e complica com centenas. A captura depende de o agente seguir o BRAIN.md; nada grava uma sessão automaticamente, ao contrário do claude-mem ou do ai-memory, então um agente ocupado pode simplesmente esquecer.

Os hooks são contidos. O hook SessionStart do Codex envia só o índice de páginas, limitado a 8 KiB, tem cinco segundos para rodar e sai em silêncio se a CLI falhar; ele exige Node 18 e um shell POSIX, então o Windows nativo fica de fora. Os hooks contêm um caminho absoluto e precisam ser reinstalados quando um projeto muda de lugar. Como o brain vive no repositório, qualquer pessoa com acesso ao repo pode lê-lo, que é justamente a ideia, e também um motivo para deixar segredos de fora.

A adoção é modesta: 722 estrelas, nove colaboradores e 814 downloads no npm nos 30 dias até 19 de novembro. Para uma equipe que já mantém registros de decisões de arquitetura, o brain.md acrescenta um formato que os agentes são instruídos a manter; para uma que não registra nada, é um primeiro passo barato.

Onde ele se destaca

  • Uma equipe de três pessoas cujos agentes vivem reabrindo escolhas de design já resolvidas

    Fazer o agente ler as decisões passadas antes de propor outra abordagem

    Rode brain init e depois a skill brain-bootstrap para rascunhar páginas de decisão a partir do git log; o bloco no CLAUDE.md diz ao agente para carregar as páginas relevantes no início de cada tarefa. Gratuito, e as páginas aparecem no code review.

  • Um desenvolvedor que alterna entre Claude Code e Codex no mesmo repositório

    Dar aos dois agentes o mesmo conhecimento do projeto no início da sessão

    Instale os hooks SessionStart dos dois com brain install-hooks e brain install-hooks --agent codex; cada sessão recebe o índice de páginas, até 8 KiB, e lê as páginas completas quando precisa.

Antes de decidir

Configuração
npm install -g @mindmux/brain-md, depois brain setup -y para copiar as skills para cada agente detectado e, por fim, brain init no projeto. Exige Node 18 ou mais novo.
Integrações
Skills de agente para Claude Code, Codex, Cursor e Pi; hooks SessionStart para Claude Code e Codex; qualquer agente que leia AGENTS.md ou CLAUDE.md pode seguir o protocolo. Sem servidor MCP.
Dados e privacidade
As páginas são Markdown na pasta brain/ do repositório, ou num caminho definido por brainRoot; a CLI não envia nada para lugar nenhum. Tudo o que o agente escreve fica visível para quem tem acesso ao repositório.
Limites
Sem busca nem embeddings; o snapshot do hook do Codex é limitado a 8 KiB e cinco segundos; os hooks guardam um caminho absoluto e precisam ser reinstalados após uma mudança de lugar; shells nativos do Windows não são suportados.

O que é bom

  • Markdown simples no repositório, versionado com o código
  • A linha do tempo só de acréscimos guarda o motivo de cada decisão alterada
  • CLI sem dependências; nada para hospedar
  • A skill de bootstrap rascunha as primeiras páginas a partir do código e do git log

O que não é

  • Sem busca; os agentes percorrem uma lista de páginas
  • A captura depende de o agente lembrar de escrever
  • Os hooks exigem um shell POSIX; sem suporte a Windows nativo
  • Projeto pequeno: 9 colaboradores, 814 downloads no npm por mês

Ideal para

Equipes pequenas que querem que o Claude Code ou o Codex guardem decisões e restrições de arquitetura no repositório, num formato que uma pessoa possa revisar num pull request.

Alternativas ao brain.md

brain.md: perguntas frequentes

brain.md vale a pena?
O brain.md é um jeito organizado de fazer um agente anotar por que uma decisão foi tomada, e faz pouco mais que uma pasta de documentação bem cuidada com regras mais rígidas. Damos nota 3.4 de 5.
Quanto custa brain.md?
Gratuito sob a licença Apache 2.0; sem serviço nem conta.
Quais são as desvantagens de brain.md?
Sem busca; os agentes percorrem uma lista de páginas; a captura depende de o agente lembrar de escrever; os hooks exigem um shell POSIX; sem suporte a Windows nativo; projeto pequeno: 9 colaboradores, 814 downloads no npm por mês.
Para quem brain.md é indicado?
Equipes pequenas que querem que o Claude Code ou o Codex guardem decisões e restrições de arquitetura no repositório, num formato que uma pessoa possa revisar num pull request.
brain.md é seguro para dados da empresa?
As páginas são Markdown na pasta brain/ do repositório, ou num caminho definido por brainRoot; a CLI não envia nada para lugar nenhum. Tudo o que o agente escreve fica visível para quem tem acesso ao repositório.
Quais são as melhores alternativas ao brain.md?
As alternativas mais próximas que analisamos são ai-memory, claude-obsidian e OpenWiki.

Respostas verificadas em 20 de nov. de 2026.