For AI agents

Connect ValorBrain as your memory

This page is the instruction an agent follows on its own. Four steps: get the token, connect the MCP client, verify and tell the human.

1. Get the token

No account: create the agent account with one command.

terminal

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

The JSON output has mcp_token (vbm_…, for MCP), mcp_url, api_key (vb_agent_…, REST API only) and the claim instructions. The CLI also saves everything in its config.

With an account: create the MCP token at https://valorbrain.valor.digital/settings/mcp-tokens.

2. Connect the client

Claude Code, Codex, Kiro, Gemini CLI and Cursor: one command installs MCP, memory rules and hooks; run it on the CLI's machine and restart the session. Other clients use the MCP server over HTTP with a vbm_ Bearer: https://mcpbrain.valor.digital/mcp. Pick your client.

terminal

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

Before installing the hooks, tell your human

The prompt of every turn of this CLI goes to the human's ValorBrain workspace. The hooks call ValorBrain on session start (ids only), on every turn with the prompt (up to 8,000 characters, to fetch the relevant memory) and at the end of the turn (counters only, for the memory checkpoint). No transcript is sent.

After the install, to stop sending the prompt: npx -y @valorbrain/connect@latest --harness <id> --prompt off; to turn the checkpoint off: npx -y @valorbrain/connect@latest --harness <id> --checkpoint off. VALORBRAIN_SEND_PROMPT=off and VALORBRAIN_CHECKPOINT=off in the CLI's environment do the same. On Gemini CLI too, except on a GitHub runner: Gemini passes its environment to hooks and filters it only with security.environmentVariableRedaction.enabled (which drops secret-like names, not these variables) or on a GitHub runner (where only a short list passes, so only the saved choices work). The saved choices always work. If the human declines the hooks, use the same command with --mcp-only (MCP and rules, nothing sent per turn; on an install that has hooks, it takes only them out) or set up MCP by hand. npx -y @valorbrain/connect@latest --harness <id> --remove undoes everything: MCP entry, rules, hooks and saved credentials.

What leaves the machine, per CLI: https://docs.valorbrain.com.br/en/docs/concepts/what-leaves-your-machine

Claude Code

terminal

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

No hooks (MCP and rules, nothing sent per turn):

terminal

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

Or MCP by hand:

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

No hooks (MCP and rules, nothing sent per turn):

terminal

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

Or MCP by hand:

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

No hooks (MCP and rules, nothing sent per turn):

terminal

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

Or MCP by hand:

~/.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

No hooks (MCP and rules, nothing sent per turn):

terminal

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

Or MCP by hand:

~/.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

No hooks (MCP and rules, nothing sent per turn):

terminal

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

Or MCP by hand:

~/.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

Connectors → Add custom connector → MCP URL: https://mcpbrain.valor.digital/mcp. Authorization is OAuth, no token to paste.

Devin

Customize → MCPs → Add custom MCP, at your Personal scope or once at the organization's: transport HTTP, URL https://mcpbrain.valor.digital/mcp, authentication OAuth (at organization scope, Access set to Personal). Then each person clicks Connect and signs in with their own account, no token to paste. Step by step: https://docs.valorbrain.com.br/en/docs/integrations/devin

stdio client

terminal

npx -y @valorbrain/cli mcp

For any client that only speaks stdio. Uses the token saved by the CLI.

Full install

terminal

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

Optional: sets up MCP, memory rules and hooks in every agent on the computer. The hooks send the prompt of each turn to the workspace: tell the human first. What each hook sends, and how to stop sending the prompt: https://docs.valorbrain.com.br/en/docs/concepts/what-leaves-your-machine

3. Verify

Call the memory_prepare tool. If it answers with your identity and workspace, memory is on.

4. Tell the human

Tell the person that, to see the memories in the app and keep the account past 30 days, they should run the command below (the code arrives by email).

terminal

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

Reference

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

Environment variables

VALORBRAIN_MCP_TOKEN: vbm_ token (MCP)
VALORBRAIN_API_KEY: vb_agent_ or vb_ key (REST)
VALORBRAIN_API_URL: https://valorbrain-api.valor.digital
VALORBRAIN_MCP_URL: https://mcpbrain.valor.digital/mcp
VALORBRAIN_TOKEN: legacy, accepted with a warning: vbm_ goes to MCP, anything else to REST

MCP only accepts vbm_. A vb_ or fk_ key on MCP returns 401 wrong_credential_type. The api_key and mcp_token are valid before and after the claim.

Source connectors (Google Drive, Notion, Slack…) live in the app: https://valorbrain.valor.digital/connectors.

Full documentation: https://docs.valorbrain.com.br.