brain-db-sdk (Rust)

The Rust client for the Brain memory database. Speaks Brain's BRN0 wire protocol directly; no dependency on Brain's internal code.

Status: multiplexed client (Phase 3 wired in). The wire codec (Phase 1) is verified byte-for-byte against the shared conformance corpus (all 86 .bin/.json cases re-encode to identical bytes). On top of it: an async transport, a MuxConnection that splits the socket and runs a background reader task demultiplexing responses by stream_id, and a high-level BrainClient built on it — so every verb takes &self and many requests run in flight at once over one connection (share a client across tasks behind an Arc). The full v1 + typed-graph API is present: encode(), recall() (streaming to EOS / recall_frames()), forget(), create_entity(), create_statement(), create_relation(), upload_schema(), materialize_procedural(), and the space/session registry verbs (create_space() / list_spaces() / delete_space(), create_session() / list_sessions() / delete_session()) — each with an ergonomic builder, plus a retry layer (RetryPolicy + the free with_retry combinator). The connection pool and transparent reconnect are later work; the serial one-at-a-time Connection remains for callers who want it.

The connection is async (tokio); the wire codec stays runtime-agnostic. The full build plan is in the repo-root ../PLAN.md; the layered architecture is in ../ARCHITECTURE.md.

use brain_db_sdk::{BrainClient, EncodeBuilder, RecallBuilder, ForgetBuilder};

let client = BrainClient::connect(addr).await?;
let stored = client.encode(&EncodeBuilder::new("the user prefers dark mode").build()).await?;
// Recall answers like a real memory: a grounded value, a set, or episodic hits.
let answer = client.recall(&RecallBuilder::new("ui preferences").max_results(5).build()).await?;
for hit in answer.episodic() {
    println!("{}", hit.text);
}
client.forget(&ForgetBuilder::new(stored.memory_id).build()).await?;
client.close().await?;

Verbs take &self, so a shared client serves concurrent requests and the free with_retry combinator wraps a verb directly — the stable request_id each builder mints makes the resend idempotent; the backoff honors a server retry_after_ms:

use brain_db_sdk::{with_retry, RetryPolicy};

let req = ForgetBuilder::new(stored.memory_id).build();
let resp = with_retry(&RetryPolicy::default(), || client.forget(&req)).await?;

cargo test          # unit + conformance + handshake + verbs + retry (mock-server round-trips)
cargo clippy --all-targets

The integration suites run against a real server when BRAIN_SDK_IT_DATA is set, and skip otherwise; scripts/it-server.sh up boots one and prints the vars. Set BRAIN_SDK_IT_REQUIRED=1 wherever a server is meant to be reachable so a misconfigured one fails instead of reading as green.

HTTP tier

For hosted Brain (the Arc cloud gateway) or a self-hosted brain-edge edge, the crate also ships BrainHttpClient — a JSON-over-HTTP client with the same verb surface, field names, and error shape as the Python and TypeScript SDKs (the canonical contract is ../HTTP_CONTRACT.md). Use it when you talk to Brain through an HTTP edge and authenticate with an API key; use the wire BrainClient above for a direct socket, streaming, transactions, and typed-graph management.

use brain_db_sdk::http::{BrainHttpClient, EncodeInput, RecallInput};

let brain = BrainHttpClient::new("https://api.arc-labs.ai", api_key);
let stored = brain.encode(&EncodeInput { text: "the kettle whistled".into(), ..Default::default() }).await?;
let answer = brain.recall(&RecallInput { query: "what whistled?".into(), max_results: Some(3), ..Default::default() }).await?;

Run the live smoke example (reads BRAIN_API_URL + BRAIN_API_KEY):

BRAIN_API_URL=http://127.0.0.1:8080 BRAIN_API_KEY=brain_… cargo run --example http_smoke

The live HTTP edge smoke tests cover identity, capabilities, and a memory encode/recall/list/forget lifecycle across all SDKs. Run them from the repo root with BRAIN_SDK_IT_HTTP=https://edge.example BRAIN_SDK_IT_HTTP_KEY=brain_… scripts/edge-it.sh.

License: Apache-2.0.

The verb builders live in src/verbs.rs.