TypeScript SDK overview

Two clients, one package

Brain exposes two transports, and the SDK gives you a client for each. They share verb names and field names — only the reach differs.

Client	Transport	Use it for
`BrainHttpClient`	JSON over HTTP (hosted `brain-edge` or the Arc cloud gateway)	The common case: store and recall memories from a serverless function, a backend service, or an edge runtime.
`BrainClient`	BRN0 binary frames + CBOR over TCP	Everything the HTTP edge does plus the typed-graph management surface (entities, statements, relations, schema), transactions, live subscriptions, and multiplexed concurrent requests over one socket.

BrainHttpClient is a strict subset. It supports exactly nine verbs: encode, recall, forget, link, unlink, plan, reason, whoami, and capabilities. The typed graph, transactions, and subscriptions are wire-only — they have no HTTP route, so they live on BrainClient.

Both clients are flat: you call client.encode(...), client.recall(...), client.forget(...) directly. There are no namespaced resource objects and no separate query verb — the write verb is encode and the read verb is recall.

When to reach for which

Start with BrainHttpClient. Move to BrainClient when you need any of:

Typed-graph management — creating entities, statements, or relations by hand, uploading a schema, resolving or traversing the graph.
Transactions — grouping several writes under one TXN_BEGIN / TXN_COMMIT.
Subscriptions — a live change-feed of write events.
Connection multiplexing — many in-flight requests over a single socket.
Self-hosting against the raw TCP port without an HTTP edge in front.

Install

npm install @brain-db/sdk

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

See Installation for versioning and runtime notes.

Quickstart

Store a memory and recall it, over the hosted HTTP edge:

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

const brain = new BrainHttpClient({ apiKey: process.env.BRAIN_API_KEY! });

await brain.encode({ text: "I prefer dark mode and live in Berlin." });

const answer = await brain.recall({ query: "where does the user live?" });
console.log(answer.answer_kind, answer.memories[0]?.text);

recall never fabricates: answer_kind is "single", "many", or "none", and memories is empty when Brain has nothing to say. See recall.

Section map

Page	What it covers
Installation	`npm install`, imports, versioning, runtime notes
HTTP client	`BrainHttpClient` construction, options, auth, the nine verbs
Wire client	`BrainClient.connect`, `ClientConfig`, `Auth`, the session getters
encode	Store a memory — both clients
recall	Retrieve an answer — the Single / Many / None membership shape
forget	Soft-tombstone or hard-zero a memory
Typed graph	Wire-only: entities, statements, relations, schema, transactions, subscriptions
Errors	The error taxonomy both clients throw
Retries	Retry policies and cancellation
Pagination	Cursor-based enumeration on the wire client