Install & configure | Brain Docs

Install the SDK

Every SDK ships two clients: BrainHttpClient (JSON over the hosted HTTP edge — the common path, shown here) and BrainClient (Brain's native binary wire protocol, for streaming, transactions, and typed-graph management). See the SDK references for the wire client.

npm install @brain-db/sdk
# or: pnpm add @brain-db/sdk   /   yarn add @brain-db/sdk

import { BrainHttpClient } from '@brain-db/sdk';

const brain = new BrainHttpClient({
  baseUrl: process.env.BRAIN_URL ?? 'https://api.arc-labs.ai',
  apiKey: process.env.BRAIN_API_KEY!,
});

The package exports both the HTTP client and the wire BrainClient from the same entry point. BrainHttpClient runs anywhere fetch is available — Node, edge runtimes, or the browser — and takes an optional fetch override.

pip install brain-db-sdk

import os
from brain_db_sdk import BrainHttpClient

brain = BrainHttpClient(
    os.environ['BRAIN_API_KEY'],
    base_url=os.environ.get('BRAIN_URL', 'https://api.arc-labs.ai'),
)

BrainHttpClient is synchronous and depends only on the standard library. The API key is the first positional argument.

cargo add brain-db-sdk

use brain_db_sdk::BrainHttpClient;

let brain = BrainHttpClient::new(
    std::env::var("BRAIN_URL").unwrap_or_else(|_| "https://api.arc-labs.ai".into()),
    std::env::var("BRAIN_API_KEY").expect("BRAIN_API_KEY"),
);

BrainHttpClient is async and runs on Tokio. new(base_url, api_key) takes the base URL first; BrainHttpClient::localhost(api_key) is a shorthand for a local self-hosted edge. Tune it with .with_timeout(..) and .with_retry_policy(..).

Configuration

BRAIN_URLrequired

optional

The base URL of the Brain HTTP edge. Managed cloud is https://api.arc-labs.ai. Self-hosted, point at your own deployment (the default is http://127.0.0.1:8080). The SDKs default to the self-host address when you pass no base URL.

BRAIN_API_KEYrequired

required

Your API key, sent as Authorization: Bearer <key> (the SDKs do this for you; the edge also accepts X-API-Key: <key>). Mint and rotate keys from the dashboard under API keys. A key is bound server-side to a (namespace, agent) pair at creation — clients never construct that scope. There is no key prefix to match on.

Confirm the connection

whoami returns the identity the edge resolved from your key — the namespace, the agent, and the resolved permissions.

const me = await brain.whoami();
console.log(me.namespace, me.agent_id);
console.log(me.permissions); // { can_encode, can_recall, can_forget, ... }

me = brain.whoami()
print(me.namespace, me.agent_id)
print(me.permissions)  # can_encode, can_recall, can_forget, ...

let me = brain.whoami().await?;
println!("{} {}", me.namespace, me.agent_id);
println!("{:?}", me.permissions);

curl -s "$BRAIN_URL/v1/whoami" \
  -H "Authorization: Bearer $BRAIN_API_KEY"
# {"namespace":"…","agent_id":"…","permissions":{"can_encode":true,…}}

A missing or blank key returns 401 unauthorized. If whoami succeeds but a write is rejected, check permissions on the result — the key may lack can_encode for the bound (namespace, agent).

Install the SDK

Configuration

Confirm the connection

On this page