# 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`](../PLAN.md); the layered
architecture is in [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
```rust
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`:
```rust
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?;
```
```bash
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`](../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.
```rust
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`):
```bash
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.
[`BrainHttpClient`]: src/http/client.rs
[`transport`]: src/transport.rs
[`Connection`]: src/connection.rs
[`BrainClient`]: src/client.rs
[`MuxConnection`]: src/mux.rs
The verb builders live in [`src/verbs.rs`](src/verbs.rs).