HTTP client

Construction

API keybeta

new BrainHttpClient(opts: BrainHttpClientOptions)

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

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

Options

ParameterTypeRequired

apiKeystringrequired

The API key, sent on every request as Authorization: Bearer <apiKey>. The constructor throws a BrainHttpError (code "config") if it is empty.

baseUrlstringoptional

Base URL of the edge. Defaults to http://127.0.0.1:8080 (the self-host default). Any trailing slashes are stripped.

timeoutMsnumberoptional

Per-request timeout in milliseconds. Defaults to 30_000. Enforced with an AbortController; a timeout surfaces as a BrainHttpError with status: 0.

retryPartial<HttpRetryPolicy>optional

Retry policy for the idempotent verbs. Merged over the default ({ maxAttempts: 3, baseDelayMs: 100, maxDelayMs: 2000 }). See Retries.

fetchtypeof fetchoptional

Override the fetch implementation. Defaults to the global fetch. The constructor throws if neither is present.

The HTTP client sends the API key as an Authorization: Bearer header on every request. There is nothing else to configure — the server resolves the caller's identity (namespace, agent, permissions) from the key. Confirm it with whoami():

const me = await brain.whoami();
console.log(me.namespace, me.agent_id, me.permissions);

The nine verbs

BrainHttpClient is a strict subset of the wire client. It supports exactly these verbs — the typed graph, transactions, and subscriptions are wire-only.

Method	Route	Notes
`encode(input)`	`POST /v1/memories`	Store a memory. Idempotent — retried per the policy. See encode.
`recall(input)`	`POST /v1/recall`	Retrieve an answer. See recall.
`forget(input)`	`DELETE /v1/memories`	Soft-tombstone or hard-zero. See forget.
`link(input)`	`POST /v1/links`	Create/overwrite a directed edge between two memories.
`unlink(input)`	`DELETE /v1/links`	Remove a directed edge (idempotent).
`plan(input)`	`POST /v1/plan`	Plan a path from a start state to a goal state.
`reason(input)`	`POST /v1/reason`	Infer over the graph from an observation.
`whoami()`	`GET /v1/whoami`	The identity resolved from the credential. Idempotent — retried.
`capabilities()`	`GET /v1/capabilities`	What the connected shard supports. Idempotent — retried.

Only the idempotent verbs — encode, whoami, capabilities — are retried. Every other verb makes a single attempt. See Retries.

link / unlink

const edge = await brain.link({
  source: "mem_abc",
  target: "mem_def",
  kind: "supports", // caused | followed_by | derived_from | similar_to |
                    // contradicts | supports | references | part_of
  weight: 0.8,
});

await brain.unlink({ source: "mem_abc", target: "mem_def", kind: "supports" });

plan / reason

const plan = await brain.plan({
  start: { text: "empty repo" },
  goal: { text: "green CI" },
  max_steps: 8,
});
for (const step of plan.steps) console.log(step.step_index, step.text);

const inference = await brain.reason({
  observation: { text: "the build is red" },
  depth: 2,
});
for (const step of inference.inferences) console.log(step.claim, step.confidence);

capabilities

const caps = await brain.capabilities();
// { rerank, llm_extractor, classifier_extractor, pattern_extractor,
//   schema_namespaces, vector_dim }

Errors

Every failure throws a BrainHttpError with status, code, and message. Transport failures and timeouts use status: 0. See Errors.