HTTP client

Construction

Bearerstable

BrainHttpClient(
    api_key: str,
    base_url: str = "http://127.0.0.1:8080",
    timeout: float = 30.0,
    retry: HttpRetryPolicy | None = None,
)

ParameterTypeRequired

api_keystrrequired

The bearer key. Positional and first. Sent as Authorization: Bearer <key> on every request. An empty key raises BrainHttpError at construction time.

base_urlstroptional

The edge base URL. Defaults to http://127.0.0.1:8080 (the self-host default). A trailing slash is stripped. Point it at your gateway for hosted deployments (e.g. https://api.arc-labs.ai).

timeoutfloatoptional

Per-request timeout in seconds. Defaults to 30.0.

retryHttpRetryPolicy | Noneoptional

Retry policy for idempotent verbs. Defaults to a fresh HttpRetryPolicy() (3 attempts, exponential backoff) when omitted. See Retries.

from brain_db_sdk import BrainHttpClient
from brain_db_sdk.http import HttpRetryPolicy

client = BrainHttpClient(
    "sk-...",
    base_url="https://api.arc-labs.ai",
    timeout=15.0,
    retry=HttpRetryPolicy(max_attempts=5),
)

The nine verbs

BrainHttpClient exposes exactly these methods:

OptionTypeDefault / Env

encode(text, context=None, occurred_at=None) → EncodeResult

Store a memory. POST /v1/memories. Idempotent — retried per the policy.

recall(query, max_results=None, subject=None) → RecallResult

Cue-driven read. POST /v1/recall.

forget(memory_id, hard=False) → ForgetResult

Delete a memory. DELETE /v1/memories.

link(source, target, kind, weight=None) → LinkResult

Create or reweight a directed edge between two memories. POST /v1/links.

unlink(source, target, kind) → UnlinkResult

Remove a directed edge (idempotent). DELETE /v1/links.

plan(start, goal, ...) → PlanResult

Plan a path from a start state to a goal state. POST /v1/plan. start / goal are {"text": ...} or {"memory_id": ...}.

reason(observation, ...) → ReasonResult

Infer over the graph from an observation. POST /v1/reason. observation is {"text": ...} or {"memory_id": ...}.

whoami() → Whoami

The identity Brain resolves from the credential. GET /v1/whoami.

capabilities() → Capabilities

What the connected shard supports. GET /v1/capabilities.

client.encode("Ada moved to Berlin in March.", occurred_at=1710000000000000000)
answer = client.recall("Where does Ada live?", max_results=5, subject="Ada")
client.forget("mem_01H...", hard=True)
client.link("mem_a", "mem_b", "SimilarTo", weight=0.8)

me = client.whoami()
print(me.namespace, me.agent_id, me.permissions.can_encode)

caps = client.capabilities()
print(caps.rerank, caps.vector_dim, caps.schema_namespaces)

The HTTP client covers the core memory verbs plus plan / reason and the two introspection GETs. It deliberately does not expose the typed graph (entities, statements, relations, schema), transactions, subscriptions, memory enumeration, or graph export. Those live only on the wire client — see Typed graph and the Wire client.

plan, reason, and capabilities are brain-edge-only routes. A hosted gateway deployment may omit them; the core encode / recall / forget / link / unlink / whoami verbs are always present.

Authentication

Every request carries Authorization: Bearer <api_key>. The server derives the bound (namespace, agent_id, permissions) from the key — the client never sends a namespace or agent. Inspect the resolved identity with whoami():

me = client.whoami()
# Whoami(namespace=..., agent_id=..., permissions=Permissions(...))

Idempotency and retries

encode, whoami, and capabilities are treated as idempotent and are retried per the policy on 503 and transport/timeout failures. recall, forget, link, unlink, plan, and reason run exactly once. See Retries for the full policy.

Construction

The nine verbs

It is a subset

Authentication

Idempotency and retries

On this page