Python SDK overview | Brain Docs

Brain ships no client library of its own — its contract is the wire protocol (a 32-byte BRN0 frame header plus CBOR payloads over TCP). This package re-implements that protocol independently and is verified byte-for-byte against Brain's conformance corpus. The distribution is brain-db-sdk; the importable module is brain_db_sdk.

Two clients

OptionTypeDefault / Env

BrainHttpClientHTTP / JSON

Talks JSON to the Brain HTTP edge (brain-edge self-hosted, or the Arc cloud gateway). A deliberate subset of the verb surface: encode, recall, forget, link, unlink, plan, reason, whoami, capabilities. Built on urllib.request — no third-party runtime dependency. Use it for application reads and writes over the hosted API.

BrainClientWire / BRN0 TCP

Talks the native binary protocol directly to a Brain shard. The full verb surface: everything in the HTTP client plus the typed graph (entities, statements, relations, schema), transactions, subscriptions, memory enumeration, and graph export. Use it when you need those capabilities or the lowest-latency path.

Both clients are synchronous. There is no async client — see Sync vs async.

When to use which

Reach for BrainHttpClient when you talk to a hosted Brain deployment (brain-edge or the Arc gateway), when JSON over HTTP is the natural fit for your stack, or when you only need the core verbs. Reach for BrainClient when you self-host and connect straight to a shard, when you need the typed graph, transactions, or live subscriptions, or when you want to stream large result sets frame by frame.

The verb names are identical across both clients — encode, recall, forget — so moving from one to the other is a change of transport, not of vocabulary.

Install

pip install brain-db-sdk

import brain_db_sdk
print(brain_db_sdk.__version__)  # '0.1.0'

See Installation for version support and verification.

Quickstart

from brain_db_sdk import BrainHttpClient

# api_key is positional and first; base_url defaults to
# http://127.0.0.1:8080.
client = BrainHttpClient("sk-...", base_url="https://api.arc-labs.ai")

written = client.encode("Ada prefers dark mode.")
print(written.memory_id, written.was_deduplicated)

answer = client.recall("What UI theme does Ada like?")
print(answer.answer_kind)          # "Single" | "Many" | "None"
for hit in answer.memories:
    print(hit.text, hit.similarity_score)

from brain_db_sdk import BrainClient, Auth
from brain_db_sdk import EncodeBuilder, RecallBuilder

# Auth is mandatory: the credential is the connection's identity.
with BrainClient.connect("127.0.0.1", 9090, Auth.token(b"my-token")) as client:
    written = client.encode(EncodeBuilder("Ada prefers dark mode.").build())
    print(written.memory_id)

    answer = client.recall(RecallBuilder("What UI theme does Ada like?").build())
    print(answer.answer_kind, answer.is_empty)
    for hit in answer.memories:
        print(hit.text, hit.similarity_score)

Authentication

OptionTypeDefault / Env

HTTPBearer

The api_key you pass to BrainHttpClient is sent as Authorization: Bearer <key> on every request.

Wiretoken / mTLS

BrainClient authenticates after the WELCOME handshake with an Auth credential — Auth.token(bytes) for a shared bearer token, or Auth.mtls(claim) for an mTLS subject claim. Auth is mandatory; there is no anonymous mode.

The server resolves the connection's (namespace, agent, permissions) from the credential and refuses any connection it cannot resolve.

What's in this section

Installation — pip install, version support, verification.
HTTP client — BrainHttpClient construction, verbs, and the subset it covers.
Wire client — BrainClient.connect, ClientConfig, Auth, and the session it exposes.
Sync vs async — the SDK is synchronous; how to run it under concurrency.
Encode — writing memories on both clients.
Recall — cue-driven reads and the Single/Many/None answer shape.
Forget — soft and hard deletes.
Typed graph — entities, statements, relations, schema, transactions, and subscriptions (wire only).
Errors — the exception hierarchy for both clients.
Retries — HttpRetryPolicy and the with_retry helper.
Pagination — streamed frames and keyset cursors.