Brain OS

Memória operacional para agentes de IA que persiste entre sessões e ferramentas.

Documentação

Brain OS - AI remembers conversations but forgets project state

Servidor de memória MCP local-first para estado operacional de projetos: decisões, bloqueios, planos, padrões e próximos passos.

Brain OS

brainos-hq.com

Sua IA lembra de conversas. Ainda assim, ela esquece o estado do projeto.

O Brain OS dá aos agentes estado operacional: decisões, planos, bloqueios e prioridades que sobrevivem entre sessões.

O que é isso?

Agentes de IA são poderosos dentro de uma sessão, mas trabalho de longo prazo tem mais estado do que qualquer chat: o que você decidiu, o que está bloqueado, o que está ativo e o que não deve ser reaberto. O Brain OS dá aos agentes estado operacional, não registros de conversa:

Entidades — acompanhe projetos, negócios, iniciativas com status, momentum, bloqueios e próximos passos
Decisões — registre o que foi decidido, por quê, quais alternativas foram rejeitadas e quando revisitar
Padrões — detecte bloqueios recorrentes, trabalho obsoleto, sinais de evasão e convergência de temas
Foco — priorize no que trabalhar com base em urgência, momentum, alavancagem e obsolescência
Recordação semântica — busque memória por significado, não apenas por ID

O Brain OS é um servidor MCP que funciona com qualquer cliente compatível com MCP: Claude Code, Cursor, Zed, GitHub Copilot, OpenAI Codex, Windsurf ou qualquer agente que fale o protocolo.

Como é na prática

Antes de o agente agir, ele pode verificar se uma ação proposta conflita com uma decisão existente:

> decision_check({ proposal: "switch to Postgres for the new service" })

{
  "verdict": "conflict",
  "conflicting_decision": {
    "id": "dec_2026_03_14_db_choice",
    "decision": "Use SQLite for all local-first projects",
    "reason": "Lower ops burden, no infra to run, fits single-user scope",
    "rejected_alternatives": ["Postgres", "DuckDB"],
    "logged_at": "2026-03-14"
  },
  "guidance": "Re-litigating a settled choice. Surface the prior reasoning to the user before proceeding."
}

Esse é o diferencial: estado estruturado com aplicação de regras, para que os agentes parem de reabrir perguntas que você já respondeu.

Início rápido

Requer Node.js 20 ou mais recente.

# In your project
npx brain-os init

Isso faz três coisas:

Cria um diretório .brain/ com seus repositórios de entidades, decisões e padrões.
Instala comandos de barra em .claude/commands/ para que você possa executar /brain, /brain:focus, /brain:decide, etc. diretamente no Claude Code. Aliases curtos (/focus, /decide, etc.) são instalados junto para agilidade.
Adiciona arquivos de ponteiro de instruções para agentes para que qualquer cliente compatível com MCP se comporte de forma consistente: AGENTS.md (canônico, entre ferramentas) além de arquivos de ponteiro finos para Claude Code (CLAUDE.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursor/rules/brain-os.mdc), Zed (.zed/rules.md) e Windsurf (.windsurfrules).

Flags:

npx brain-os init --minimal — instala apenas AGENTS.md + CLAUDE.md, pula os outros ponteiros de cliente (modo repositório limpo)
npx brain-os init --no-commands — pula comandos de barra (apenas servidor MCP)
npx brain-os init --no-agent-instructions — pula todos os arquivos de ponteiro de instruções para agentes

Conectar ao Claude Code

claude mcp add brain-os -- npx brain-os serve

Conectar ao Cursor / outros clientes MCP

Adicione à sua configuração MCP:

{
  "brain-os": {
    "command": "npx",
    "args": ["-y", "brain-os", "serve"]
  }
}

Configurar busca semântica (opcional)

A ferramenta semantic_recall precisa de um provedor de embeddings. Todo o resto (entity_update, decision_log, plan_*, etc.) funciona sem um.

O Brain OS não instala um SDK de embeddings por padrão. Isso mantém a instalação principal enxuta e evita puxar dependências nativas de ONNX/Sharp para usuários que não precisam de busca semântica. Instale o provedor OpenAI opcional junto a brain-os e adicione BRAIN_EMBEDDINGS ao ambiente do seu servidor MCP:

npm install brain-os openai

Em seguida, configure o provedor no ambiente do seu servidor MCP:

{
  "brain-os": {
    "command": "npx",
    "args": ["-y", "brain-os", "serve"],
    "env": {
      "BRAIN_EMBEDDINGS": "openai",
      "OPENAI_API_KEY": "${OPENAI_API_KEY}"
    }
  }
}

Modo	O que faz	Configuração
`local`	Temporariamente indisponível enquanto o provedor anterior carrega avisos transitivos de alta severidade não resolvidos.	Use recordação por palavras-chave ou o provedor OpenAI até que um backend local auditado seja lançado.
`openai`	Usa `text-embedding-3-small` via API da OpenAI. Mais rápido que local. Custa ~US$ 0,02 por milhão de tokens.	Instale `openai`, defina `BRAIN_EMBEDDINGS=openai` e referencie `OPENAI_API_KEY` a partir do ambiente do seu shell.

Se BRAIN_EMBEDDINGS não estiver definido, o provedor OpenAI estiver ausente ou o modo local for solicitado, semantic_recall retorna um erro de configuração claro. Nenhuma instalação silenciosa de provedor, download de modelo ou chamada de API ocorre. As ferramentas principais continuam funcionando normalmente.

Nunca cole uma chave sk-... bruta na sua configuração MCP. ~/.claude.json e arquivos de configuração MCP semelhantes são texto puro e fáceis de expor na tela ou em backups. Em vez disso, exporte a chave uma vez no seu shell e referencie-a a partir do ambiente do processo MCP.

Ferramentas

Ferramenta	Descrição
`entity_read`	Lê o estado operacional de uma ou todas as entidades rastreadas
`entity_update`	Atualiza o estado da entidade — status, momentum, bloqueios, próximos passos
`decision_log`	Registra uma decisão estratégica com justificativa e alternativas
`decision_check`	Verifica uma ação proposta contra decisões ativas — retorna claro/cautela/conflito
`decision_refresh`	Atualiza uma decisão existente: altera review_date, adiciona evidências, muda status. Apenas metadados — não altera o conteúdo da decisão.
`decision_review`	Caixa de entrada de dívida de revisão: agrupa decisões atrasadas (ainda-válida / alterada / arquivar / precisa-evidências) e recomenda uma ação para cada. Somente leitura — propõe, você confirma. Detecta automaticamente decisões duplicadas.
`context_resolve`	Resolve a qual entidade o trabalho atual pertence, a partir de menção explícita / alias / arquivos / sinais lexicais. Determinístico e com pontuação de confiança — roteia contexto conhecido, nunca adivinha intenção.
`focus_get`	Obtém recomendações priorizadas sobre no que trabalhar
`project_evidence_scan`	Varredura somente leitura do estado operacional nativo de um repositório (STATE.md, FLAGS, HANDOFF, ROADMAP/PLAN/TODO, atividade git, arquivos sujos) para portões humanos, próximos passos e não-tocar — fundamenta o foco na realidade do repositório.
`pattern_detect`	Analisa padrões em todas as entidades
`memory_check`	Audita a qualidade da memória — sinaliza dados obsoletos, contradições, ruído
`memory_commit`	Commit de fim de sessão — salva todas as alterações de estado
`semantic_recall`	Busca memória por significado usando linguagem natural
`audit_log`	Lê o histórico completo de mutações — o que mudou, quando, por quem
`wrap_check`	Detecta se alterações de estado significativas se acumularam desde o último wrap
`wrap_auto`	Wrap de rede de segurança não interativo: aplica campos de baixo risco e prepara alterações de alto risco para revisão
`plan_set`	Define um plano ordenado para uma entidade — o passo 1 torna-se o próximo passo ativo
`plan_advance`	Conclui ou pula um passo (exige evidência/justificativa) — promove automaticamente o próximo
`plan_add`	Adiciona passos a um plano existente
`plan_read`	Visualiza o progresso do plano e o passo atual
`risk_assess`	Classifica ações arriscadas antes da execução, incluindo riscos de lançamento público e operações destrutivas
`action_guard`	Aplica modelos de proteção integrados a ações comuns de alto risco antes de prosseguir

Comandos de barra

brain-os init instala comandos de barra em .claude/commands/ para que o agente tenha um vocabulário claro para trabalhar com estado operacional. Cada comando é instalado em duas formas: /brain:* (forma canônica, documentada) e um alias curto (/decide, /focus, etc.) para agilidade de usuários avançados. /brain é a raiz do namespace e é instalado uma vez.

Também instala:

BRAIN_OS_PROTOCOL.md em .claude/brain-os/PROTOCOL.md (projeto) e ~/.claude/brain-os/PROTOCOL.md (usuário). O protocolo governa o roteamento de ferramentas: quando um agente executa um comando de barra do Brain OS, ele lê o protocolo primeiro e depois chama entity_read/plan_read/focus_get/etc. como principal. Arquivos pulse tornam-se apenas fallback.
Subagente brain-os-mode em .claude/agents/brain-os-mode.md. Quando o agente principal delega trabalho do Brain OS a um subagente (ex.: ferramenta Task do Claude Code), ele assume sob o mesmo protocolo — sem risco de subagentes recorrerem à busca genérica de arquivos.
Hook opcional de guarda de roteamento em templates/hooks/brain-os-routing-guard.py. Hook PreToolUse opt-in que alerta se arquivos pulse forem lidos enquanto um workspace .brain/ existir. Instruções de instalação são impressas por brain-os init.

Comando	Alias	O que faz
`/brain`	—	Scanner de projeto: visão geral de todas as entidades, atualidade, decisões, alertas
`/brain:focus`	`/focus`	"No que devo trabalhar hoje, e por quê?" com evidências
`/brain:decide`	`/decide`	Captura uma decisão estratégica (com verificação de conflito antes de registrar)
`/brain:strategy`	`/strategy`	Parceiro de pensamento estratégico: pense em uma decisão antes de construir
`/brain:wrap`	`/wrap`	Wrap de sessão: atualiza estado da entidade, captura decisões, detecta mudanças de momentum
`/brain:patterns`	`/patterns`	Detecta padrões entre entidades: bloqueios recorrentes, evasão, temas
`/brain:retro`	`/retro`	Retrospectiva semanal ou mensal: o que foi entregue, o que estagnou, o que está oculto
`/brain:graph`	`/graph`	Mostra como as entidades se conectam, oportunidades de alavancagem, decisões compartilhadas

Instalação idempotente

Reexecutar init é seguro e ciente de reparos: comandos existentes do Brain OS são preservados e qualquer forma ausente é instalada. Se um caminho de comando estiver ocupado por outra ferramenta, esse caminho é ignorado e relatado — seu arquivo nunca é sobrescrito. Você pode instalar o Brain OS em um projeto com comandos /decide ou /focus existentes e as formas com namespace /brain:* ainda serão instaladas.

Como funciona

O Brain OS armazena tudo como arquivos JSON locais em um diretório .brain/:

.brain/
  entities/     — one file per tracked entity
  decisions/    — decision log
  patterns/     — detected patterns
  config.json   — workspace settings

Sem nuvem. Sem banco de dados. Sem conta. Seus dados permanecem na sua máquina.

Por que sem interface?

A interface é o agente. O Brain OS é lido e escrito por meio de chamadas de ferramentas MCP — /brain, /focus, /decide, decision_check, etc. — exibidas inline pelo cliente que você usar (Claude Code, Cursor, etc.). Não há painel separado para manter aberto, nenhuma segunda aba para alternar contexto, nenhum estado de interface que possa divergir dos arquivos subjacentes.

Isso é uma escolha de design, não um recurso ausente. O estado do Brain OS vive no mesmo nível do seu código; o agente já está lá, já está na conversa, já é a superfície certa para perguntar "qual é a prioridade agora?". Adicionar um painel humano dividiria a atenção entre duas interfaces para os mesmos dados.

Se você quiser uma visualização rápida, .brain/ é JSON puro — renderize como quiser. O servidor MCP público permanece nativo de agente por design.

Equipes e sincronização

O Brain OS é de usuário único por design hoje. Mas como .brain/ são apenas arquivos JSON locais, equipes podem compartilhar um cérebro por qualquer sistema de arquivos sincronizado — sem mudanças no produto:

Abordagem	Prós	Contras
Git — faça commit de `.brain/` no repositório	Ferramentas de diff/merge, histórico de versões, pontos de sincronização intencionais	`git pull` manual; conflitos de merge em edições simultâneas
Pasta compartilhada Dropbox / Drive	Quase em tempo real, sem passos manuais	Gravações concorrentes podem criar arquivos de conflito; `embeddings.json` reescreve com frequência
Montagem NFS / SMB / S3	Verdadeiramente em tempo real	Exige configuração de infraestrutura

Isso funciona sem sincronização integrada porque cada chamada de ferramenta do Brain OS lê direto do disco — não há cache em memória para invalidar. O que seu sistema de arquivos sincronizar, a próxima chamada de ferramenta verá. O mesmo vale entre ferramentas: registre uma decisão no Claude Code na segunda-feira, abra o Cursor na terça — mesmo cérebro, ambos os agentes.

Sincronização nativa criptografada para equipes com semântica de merge adequada está no roadmap. A fundação local-first de hoje é o que torna essa federação aditiva, não um retrofit.

Status carregado automaticamente

Quando um cliente MCP se conecta, o Brain OS expõe um recurso brain://status com uma visão geral operacional — entidades ativas, alertas, prioridade máxima e decisões recentes. O agente inicia cada sessão com contexto, não com amnésia.

Testes

O Brain OS inclui um conjunto de testes de fumaça em tests/smoke.mjs, conectado ao npm test e executado a cada push pelo .github/workflows/audit.yml. Execute localmente:

npm test

Cobertura atual (regressão + caminho feliz):

decision_log — colisão de tipo sem substituição, supersedes explícito funciona, substituição entre entidades rejeitada
decision_check — flag somente por palavra-chave permanece como cautela sem embeddings (sem STOPs falsos), comparação semântica assimétrica (faceta rejeitada vs. escolhida)
decision_refresh — limpa superseded_by pendente quando o status transita para fora de superseded
plan_advance — sem promoção excessiva quando uma etapa ativa já existe
entity_update — aplica diff e registra alterações, cria entidade ausente, mode_reason obrigatório ao estacionar, atualizações somente de status são aplicadas, saltos de ranqueamento protegidos são visíveis
semantic_recall — lança EmbeddingsNotConfiguredError (não Error genérico) quando BRAIN_EMBEDDINGS não está definido
Resolução de armazenamento — falha de forma fechada em um cwd sem armazenamento, em vez de criar silenciosamente um .brain/ vazio

Lacunas conhecidas (sem cobertura direta ainda): pontuação focus_get, heurísticas pattern_detect, memory_*, plan_set/add/read e o recurso brain://status. Expandir o conjunto está no roadmap.

Se você encontrar um bug, abra uma issue com a ferramenta, a entrada e a saída — esse é o caminho mais rápido para uma correção.

Comunidade

Discord: discord.gg/9VBUGstjY — perguntas, feedback, o que quebrou para você, o que você está lançando com o Brain OS
Site: brainos-hq.com
Issues: github.com/brainOS-HQ/brain-os/issues

Licença

MIT