Para agentes de IA

Conecte o ValorBrain como sua memória

Esta página é a instrução que um agente segue sozinho. Quatro passos: obter o token, conectar o cliente MCP, verificar e avisar o humano.

1. Obter o token

Sem conta: crie a conta de agente com um comando.

terminal

npx -y @valorbrain/cli@latest init --agent --agent-caller <nome-do-agente> --json

A saída JSON traz mcp_token (vbm_…, para o MCP), mcp_url, api_key (vb_agent_…, só para a API REST) e as instruções de claim. A CLI também salva tudo na configuração dela.

Com conta: crie o token MCP em https://valorbrain.valor.digital/settings/mcp-tokens.

2. Conectar o cliente

Claude Code, Codex, Kiro, Gemini CLI e Cursor: um comando instala MCP, regras de memória e hooks; rode na máquina da CLI e reinicie a sessão. Os outros clientes usam o servidor MCP por HTTP com Bearer vbm_: https://mcpbrain.valor.digital/mcp. Escolha o seu cliente.

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness <claude-code|codex|kiro|gemini-cli|cursor>

Antes de instalar os hooks, avise o humano

O prompt de cada turno desta CLI vai para o workspace do humano no ValorBrain. Os hooks chamam o ValorBrain no início da sessão (só ids), a cada turno com o prompt (até 8.000 caracteres, para buscar a memória relevante) e no fim do turno (só contadores, para o checkpoint de memória). Nenhuma transcrição é enviada.

Depois da instalação, para parar de enviar o prompt: npx -y @valorbrain/connect@latest --harness <id> --prompt off; para desligar o checkpoint: npx -y @valorbrain/connect@latest --harness <id> --checkpoint off. VALORBRAIN_SEND_PROMPT=off e VALORBRAIN_CHECKPOINT=off no ambiente da CLI fazem o mesmo. No Gemini CLI também, menos num runner do GitHub: o Gemini passa o ambiente aos hooks e só o filtra com security.environmentVariableRedaction.enabled (que tira nomes de segredo, não essas variáveis) ou num runner do GitHub (onde só passa uma lista curta, e então só valem as escolhas salvas). As escolhas salvas valem sempre. Se o humano recusar os hooks, use o mesmo comando com --mcp-only (MCP e regras, nada enviado por turno; numa instalação que já tem hooks, tira só eles) ou configure o MCP à mão. npx -y @valorbrain/connect@latest --harness <id> --remove desfaz tudo: entrada do MCP, regras, hooks e credenciais salvas.

O que sai da máquina, por CLI: https://docs.valorbrain.com.br/docs/concepts/what-leaves-your-machine

Claude Code

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness claude-code

Sem hooks (MCP e regras, nada enviado por turno):

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness claude-code --mcp-only

Ou o MCP à mão:

terminal

claude mcp add --transport http --scope user valorbrain https://mcpbrain.valor.digital/mcp --header "Authorization: Bearer <vbm_…>"

Codex

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness codex

Sem hooks (MCP e regras, nada enviado por turno):

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness codex --mcp-only

Ou o MCP à mão:

terminal

export VALORBRAIN_MCP_TOKEN=<vbm_…>codex mcp add valorbrain --url https://mcpbrain.valor.digital/mcp --bearer-token-env-var VALORBRAIN_MCP_TOKEN

Kiro

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness kiro

Sem hooks (MCP e regras, nada enviado por turno):

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness kiro --mcp-only

Ou o MCP à mão:

~/.kiro/settings/mcp.json

{  "mcpServers": {    "valorbrain": {      "url": "https://mcpbrain.valor.digital/mcp",      "headers": {        "Authorization": "Bearer <vbm_…>"      }    }  }}

Gemini CLI

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness gemini-cli

Sem hooks (MCP e regras, nada enviado por turno):

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness gemini-cli --mcp-only

Ou o MCP à mão:

~/.gemini/settings.json

{  "mcpServers": {    "valorbrain": {      "httpUrl": "https://mcpbrain.valor.digital/mcp",      "headers": {        "Authorization": "Bearer <vbm_…>"      }    }  }}

Cursor

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness cursor

Sem hooks (MCP e regras, nada enviado por turno):

terminal

npx -y @valorbrain/connect@latest --token <vbm_…> --harness cursor --mcp-only

Ou o MCP à mão:

~/.cursor/mcp.json

{  "mcpServers": {    "valorbrain": {      "url": "https://mcpbrain.valor.digital/mcp",      "headers": {        "Authorization": "Bearer <vbm_…>"      }    }  }}

VS Code

.vscode/mcp.json

{  "servers": {    "valorbrain": {      "type": "http",      "url": "https://mcpbrain.valor.digital/mcp",      "headers": {        "Authorization": "Bearer <vbm_…>"      }    }  }}

claude.ai / Claude Desktop

Conectores → Adicionar conector personalizado → URL do MCP: https://mcpbrain.valor.digital/mcp. A autorização é por OAuth, sem colar token.

Devin

Customize → MCPs → Add custom MCP, no seu escopo Personal ou uma vez no da organização: transporte HTTP, URL https://mcpbrain.valor.digital/mcp, autenticação OAuth (no escopo da organização, Access em Personal). Depois cada pessoa clica em Connect e entra com a própria conta, sem colar token. Passo a passo: https://docs.valorbrain.com.br/docs/integrations/devin

Cliente stdio

terminal

npx -y @valorbrain/cli mcp

Para qualquer cliente que só fala stdio. Usa o token salvo pela CLI.

Instalação completa

terminal

npx -y @valorbrain/connect@latest --token <vbm_…>

Opcional: configura MCP, regras de memória e hooks em todos os agentes do computador. Os hooks enviam o prompt de cada turno para o workspace: avise o humano antes. O que cada hook envia e como desligar o envio do prompt: https://docs.valorbrain.com.br/docs/concepts/what-leaves-your-machine

3. Verificar

Chame a ferramenta memory_prepare. Se ela responder com a sua identidade e o workspace, a memória está ligada.

4. Avisar o humano

Diga à pessoa que, para ver as memórias no app e manter a conta além de 30 dias, ela deve rodar o comando abaixo (o código chega por e-mail).

terminal

npx -y @valorbrain/cli init --email <email>

Referência

MCP (streamable HTTP): https://mcpbrain.valor.digital/mcp
API REST: https://valorbrain-api.valor.digital
App: https://valorbrain.valor.digital
Docs: https://docs.valorbrain.com.br
Site: https://valorbrain.com.br

Variáveis de ambiente

VALORBRAIN_MCP_TOKEN: token vbm_ (MCP)
VALORBRAIN_API_KEY: chave vb_agent_ ou vb_ (REST)
VALORBRAIN_API_URL: https://valorbrain-api.valor.digital
VALORBRAIN_MCP_URL: https://mcpbrain.valor.digital/mcp
VALORBRAIN_TOKEN: legado, aceito com aviso: vbm_ vai para o MCP, o resto para a REST

O MCP só aceita vbm_. Uma chave vb_ ou fk_ no MCP volta 401 wrong_credential_type. A api_key e o mcp_token valem antes e depois do claim.

Conectores de fontes (Google Drive, Notion, Slack…) ficam no app: https://valorbrain.valor.digital/connectors.

Documentação completa: https://docs.valorbrain.com.br.