Cabeção

Português | English

Suas notas são arquivos Markdown num repositório git seu, em qualquer provedor. Os agentes de IA (Claude Code, Codex, Cursor e outros) consultam e gravam nelas por MCP, e cada gravação vira um commit que você desfaz com um comando. O nome é uma homenagem ao Cabeção de Malhação.

Como é

$ cabecao init git@github.com:voce/cerebro.git
Pronto. Seu cérebro está em ~/cabecao (máquina notebook) e em git@github.com:voce/cerebro.git.

Repositório vazio: estrutura do cérebro criada na branch main e enviada para git@github.com:voce/cerebro.git.
Índice local: 0 notas indexadas em 2 ms.

Agentes:
  Codex   servidor MCP registrado
  Cursor  servidor MCP registrado
  Reinicie os que estiverem abertos.

Teste agora:
  1. No Codex, peça: "guarde que eu prefiro respostas curtas, em tópicos"
  2. Numa conversa nova, pergunte: "como eu prefiro as respostas?"
  3. Ou confira aqui: cabecao search "respostas curtas"

Opcional:
  cabecao install-skills  skills que ensinam Codex e Cursor a usar o cérebro
  ...

Numa sessão do Claude Code, você pede "guarde que os testes de pagamento só passam com TZ=UTC", e o agente chama a tool remember:

{
  "op": "01M79DRQR9648E1JZ60MF0EBNN",
  "path": "memory/gotchas/testes-de-pagamento-precisam-do-fuso-fixo.md",
  "action": "add",
  "commit": "1af64e1dc48f5627dd086474c571b22326eaa3c0"
}

A nota é um arquivo .md comum. Na próxima sessão, em qualquer máquina, ela volta no recall do agente. E também pelo terminal:

$ cabecao search "testes pagamento"
1 resultado(s) para "testes pagamento", com todos os termos (validade em 2026-11-13):

1. Testes de pagamento precisam do fuso fixo  [gotcha · project:pagamentos]  vigente
   memory/gotchas/testes-de-pagamento-precisam-do-fuso-fixo.md
   Os «testes» do serviço de pagamentos falham perto da meia-noite se o fuso não for fixo. Rode com `TZ=UTC npm test`.

Related MCP server: pulse8-ai-cortex-knowledge-vault

Por quê

• Seus dados, num formato seu. Markdown num repositório git que você controla. Abre no Obsidian, em qualquer editor, e continua seu se você parar de usar o Cabeção.

• Qualquer provedor. GitHub, GitLab, Bitbucket, Gitea, um servidor seu ou só a sua máquina. Só git, sem API de provedor.

• Memória entre sessões e máquinas. O que você ensina numa conversa volta na próxima, em qualquer cliente MCP.

• Tudo reversível. Cada gravação é um commit identificado; cabecao undo desfaz uma operação ou uma sessão inteira de um agente.

• Agentes com limites. Regras e arquivos de instrução só mudam com o seu pedido explícito, confirmado; segredo nunca entra; e todo commit de agente leva a marca dele.

• Manutenção sem você olhando. cabecao consolidate --run chama o Claude Code ou o Codex para consolidar a memória, só com as tools do Cabeção, e desfaz o que ficar pela metade.

Instalação

Requer Node.js 22.16 ou mais novo e git 2.38+. Crie antes um repositório vazio e privado.

npm i -g cabecao
cabecao init git@github.com:voce/cerebro.git
cabecao doctor

O init termina com o que pedir ao agente para testar e os próximos passos opcionais que ele detectou. Ele também adota um vault do Obsidian que está num repositório git (clonado numa pasta nova, sem mover nem renomear notas), e sem URL cria um cérebro só local.

Conectar os agentes

O init já registra o servidor MCP nos clientes que encontrar: Claude Code, Claude Desktop, Codex, Cursor, VS Code, Antigravity e Gemini CLI. Para registrar depois, cabecao install-client --all.

Nos agentes com shell, as skills do Cabeção ensinam o agente a usar o cérebro pela linha de comando, sem o servidor MCP e com as mesmas regras:

cabecao install-skills

No Claude Code, o plugin traz tudo junto (servidor embutido, briefing no início da sessão, sync no fim e as skills): /plugin marketplace add renanloureiroo/cabecao e /plugin install cabecao@cabecao.

Recursos

• init em qualquer remoto git, com adoção de vault do Obsidian, e um fim que leva ao primeiro teste

• sync sem perder nada: cópia de conflito em vez de sobrescrever; sync automático com schedule

• Busca por palavra-chave e, opcional, por significado com um modelo local; validade no tempo (--as-of)

• Grafo: wikilinks, relações tipadas, fatos e menções sem link

• Servidor MCP com 17 tools, plugin do Claude Code, pacote .mcpb do Claude Desktop e skills para os agentes com shell

• Memória com ciclo de vida: handoff, duplicatas resolvidas, lint, consolidate (também com um agente sozinho), forget

• undo por operação ou sessão; scanner de segredos; regras só com o seu pedido explícito

• Obsidian com um comando (obsidian setup); upgrade e uninstall

• Respostas com citações conferidas (ask), opcionais: desligadas por padrão, com o provedor que você ativar no terminal

O que vem depois está em Em breve.

Documentação

Tudo está no site: renanloureiroo.github.io/cabecao, em português e em inglês. Começo rápido, conceitos, guias (Obsidian, conflitos, desfazer, regras), referência da CLI e das tools MCP, segurança e solução de problemas.

Contribuir

Issues e pull requests são bem-vindos. Leia o CONTRIBUTING.md para rodar o projeto e as convenções. Para relatar uma vulnerabilidade, use o relato privado de vulnerabilidades do GitHub.

Licença

MIT © Renan Pereira Loureiro