Começo rápido

O onboarding que importa é o caminho do agente. O humano manda uma frase; o agente faz o resto. Depois, o humano assume a conta com o email e as mesmas credenciais continuam funcionando.

A instrução

Mande isto para o seu agente:

Conecte o ValorBrain como sua memória: leia https://valorbrain.com.br/connect.md e siga as instruções.

O connect.md é a fonte única dos passos. Esta página repete os mesmos quatro passos.

Duas credenciais, dois hosts

O host MCP aceita só vbm_. Uma chave vb_/vb_agent_/fk_ como bearer no MCP volta 401 com error: "wrong_credential_type" e uma dica de qual token usar. As duas credenciais continuam funcionando antes e depois do claim.

1. Pegue um token MCP (vbm_…)

Sem conta:

npx -y @valorbrain/cli@latest init --agent --agent-caller <agent-name> --json

Devolve mcp_token (vbm_…, MCP e REST), mcp_url, api_key (vb_agent_…, só REST) e as instruções de claim. Tudo fica salvo na config da CLI (~/.valorbrain/config.json, modo 0600). O mcp_token aparece só nessa resposta; guarde-o.

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

2. Conecte o cliente MCP

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:

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

Antes, avise o humano: os hooks enviam o prompt de cada turno da CLI (até 8.000 caracteres) para o workspace dele no ValorBrain, para buscar a 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, menos no Gemini CLI num runner do GitHub, que não passa essas variáveis aos hooks; ali só valem as escolhas salvas. Para tirar só os hooks, rode a instalação de novo com --mcp-only; npx -y @valorbrain/connect@latest --harness <id> --remove desfaz tudo (entrada do MCP, regras, hooks e credenciais salvas). Detalhes por CLI: O que sai da sua máquina.

Sem hooks (o humano recusou): o mesmo comando com --mcp-only instala o servidor MCP e as regras, sem hooks; nada é enviado por turno. No Hermes, que não tem hooks, o plugin de memória continua enviando o prompt (use --prompt off).

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

Outros clientes, ou o MCP à mão: só o servidor MCP. HTTP com Authorization: Bearer <vbm_…> em https://mcpbrain.valor.digital/mcp.

Claude Code

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

Codex

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

Gemini CLI — ~/.gemini/settings.json

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

Cursor — ~/.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 — Settings → Connectors → Add custom connector → URL https://mcpbrain.valor.digital/mcp. O login é por OAuth; não há token para colar.

Qualquer cliente stdio — use como comando do servidor (usa o token salvo pelo init):

npx -y @valorbrain/cli mcp

Instalação completa com regras e hooks (opcional):

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

Detalhes por cliente: MCP e Integrações.

3. Verifique

Chame a ferramenta MCP memory_prepare. Ela devolve quem você é neste workspace e a memória relevante para a tarefa.

4. Avise o humano

Para manter a conta além de 30 dias, o humano vincula o email dele (código de uso único por email, válido por 10 minutos, 5 tentativas):

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

As duas credenciais continuam funcionando depois do claim. Sem claim, as duas expiram em 30 dias. O claim ainda não cria um login no app. Passo a passo: Assumir uma conta de agente.

A saída do init --json traz um notice (o message da resposta do signup) escrito como instrução para o agente, com esse mesmo aviso. Mostre-o ao humano no seu próximo turno voltado para o usuário. Não pule.

Identidade autodeclarada

--agent-caller nunca é inferido do ambiente. A CLI pode sugerir um caller a partir do env (CLAUDECODE, CURSOR, …) e imprimir uma dica; ela não registra nada a menos que você passe a flag. Se esqueceu:

npx -y @valorbrain/cli identify claude-code

Caller ids que a CLI entende como dicas: claude-code, cursor, codex, cline, continue, aider, goose, windsurf, kiro, opencode, hermes, zcode, grok. Qualquer outro é armazenado como você digitou.

Memória direto do shell (REST)

A CLI fala REST com valorbrain-api.valor.digital usando a credencial que o init salvou. A api_key (vb_agent_) não serve para o MCP; o vbm_ serve nos dois.

npx -y @valorbrain/cli add "the deploy key lives in the ops vault"
npx -y @valorbrain/cli search "deploy key"
npx -y @valorbrain/cli status

O tenant é resolvido a partir do token — você não envia X-Tenant-ID.

Chamando o REST sem a CLI, POST /documents exige os quatro campos: content, title, collection e path — faltou campo, o erro diz qual ({"error": "path is required"}). O contrato completo e vivo (incluindo o próprio signup, que não precisa de chave) está em GET /openapi.json do engine. Veja REST.

--json em qualquer comando imprime um único objeto JSON. help --json despeja a superfície inteira. Referência completa: Referência da CLI.

Tempo medido

Medido em 2026-08-30 contra o pacote publicado @valorbrain/cli, versão 0.1.0, não contra um checkout local:

Alvo: menos de 15 segundos. Referência (mem0, no mesmo dia): ~13s, dos quais 4.66s são pip install. O npx pula essa instalação.

Sem npm no PATH

Num runtime que só tem o binário do Node 18+ (containers enxutos, harnesses Windows), o pacote não tem dependências — baixe o tarball do registry e rode direto:

TARBALL=$(curl -sS https://registry.npmjs.org/@valorbrain/cli/latest | node -pe 'JSON.parse(require("fs").readFileSync(0)).dist.tarball')
curl -sSL "$TARBALL" | tar -xz    # extrai package/ com bin/valorbrain.js
node package/bin/valorbrain.js init --agent --agent-caller <agent-name> --json

Daí em diante, troque npx -y @valorbrain/cli por node package/bin/valorbrain.js — inclusive no comando stdio (node package/bin/valorbrain.js mcp). Um agente de terceiros validou esse caminho num runtime sem npm (batch #1 do DSH, §11.4): ~4 minutos, incluindo entender o entry point.

Caminho humano (app)

Se você não é um agente:

1. Abra valorbrain.valor.digital.
2. Ative o email.
3. Crie um token MCP (vbm_…) em Settings → MCP tokens. A chave de ingest (fk_….sk_…) é outra coisa: só para o ingest do app, servidor a servidor.
4. Siga o passo 2 acima, ou REST.

Comandos fantasma

Estes aparecem em READMEs antigos e não existem na CLI publicada. help --json é a fonte da verdade.

• valorbrain setup harness …
• valorbrain setup status
• valorbrain setup openclaw
• valorbrain setup harness --detect