Wire client | Brain Docs

Connect

Token or mTLSbeta

static BrainClient.connect(
  host: string,
  port: number,
  config: ClientConfig,
): Promise<BrainClient>

connect opens the TCP connection, runs the HELLO → WELCOME → AUTH → AUTH_OK handshake, and resolves to a client bound to the session the server granted.

import { BrainClient } from "@brain-db/sdk";

const client = await BrainClient.connect("127.0.0.1", 9090, {
  auth: { kind: "token", token: new TextEncoder().encode(process.env.BRAIN_TOKEN!) },
});

console.log(client.namespace);           // the bound tenant ("" = system)
console.log(client.session.chosenVersion);

Close it cleanly when done — this sends BYE and closes the socket:

await client.close();

ClientConfig

ParameterTypeRequired

authAuthrequired

How to authenticate after WELCOME. Mandatory — there is no anonymous mode; the credential is the connection's whole identity. See Authentication.

clientIdstringoptional

Client identifier advertised in HELLO. Defaults to "brain-db-sdk-typescript".

supportedVersionsnumber[]optional

Wire versions the client offers. Defaults to [1].

capabilitiesHelloCapabilitiesoptional

Client capabilities advertised in HELLO. Defaults to { streaming: true, compressionZstd: false, serverPush: false }.

connectTimeoutMsnumberoptional

Deadline for the TCP connect. Defaults to 10_000.

requestTimeoutMsnumberoptional

Per-response read deadline. Defaults to 30_000.

Authentication

Auth is mandatory and is applied after the server sends WELCOME. The Auth value is a discriminated union — a token or an mTLS assertion:

type Auth =
  | { kind: "token"; token: Uint8Array }
  | { kind: "mtls"; certFingerprint: Uint8Array; assertedSubject: string };

const client = await BrainClient.connect("127.0.0.1", 9090, {
  auth: {
    kind: "token",
    token: new TextEncoder().encode(process.env.BRAIN_TOKEN!),
  },
});

const client = await BrainClient.connect("127.0.0.1", 9090, {
  auth: {
    kind: "mtls",
    certFingerprint: fingerprintBytes,
    assertedSubject: "svc-ingest",
  },
});

The server resolves (namespace, agent, permissions) from the credential and refuses any connection it cannot resolve. The client never sends a namespace — it is server-derived.

The session

BrainClient.connect resolves once the handshake completes. The granted session is on client.session, with two convenience getters:

ParameterTypeRequired

client.agentIdUint8Arrayoptional

The agent id this connection acts as, as the server assigned it.

client.namespacestringoptional

The owning tenant the server bound this connection to. An empty string means the reserved brain system namespace. Read-only.

client.sessionSessionInfooptional

The full session: agentId, serverId, chosenVersion, sessionId, boundShardId, permissions, namespace, and serverFeatures.

Full verb surface

BrainClient covers every verb. Beyond encode / recall / forget (see the encode, recall, and forget pages), it adds:

Typed graph — createEntity, createStatement, createRelation, resolveEntity, getEntity, uploadSchema, traversal, and the list* / *Frames enumerations. See Typed graph.
Transactions — txnBegin, txnCommit, txnAbort.
Subscriptions — subscribe, returning a Subscription you drain.
Introspection — capabilities, extractorList, memoryInspect, queryExplain, queryTrace.
Links, plan, reason — link, unlink, plan, reason.

Requests run concurrently: the connection is multiplexed, so many verb calls can be in flight at once over the one socket.

Retry

Verb calls aren't retried automatically. Wrap a call in withRetry; each request builder mints a stable requestId, so a resend is idempotent server-side. See Retries.