Quickstart

Prerequisites

A Brain API key — copy one from the dashboard under API keys
Node.js 18+, Python 3.9+, or Rust 1.75+ (async runtime)

What you'll build

A short script that encodes three memories about a user, then asks Brain what it learned. Total wall-clock time: under a minute.

Install the SDK

npm install @brain-db/sdk

pip install brain-db-sdk

cargo add brain-db-sdk

Create the client

Pass the base URL and your API key — that's it. The key is bound server-side to a (namespace, agent), so you never construct a scope in client code.

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

const brain = new BrainHttpClient({
  baseUrl: 'https://api.arc-labs.ai',
  apiKey: process.env.BRAIN_API_KEY!,
});

import os
from brain_db_sdk import BrainHttpClient

brain = BrainHttpClient(
    os.environ['BRAIN_API_KEY'],
    base_url='https://api.arc-labs.ai',
)

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

let brain = BrainHttpClient::new(
    "https://api.arc-labs.ai",
    std::env::var("BRAIN_API_KEY")?,
);

Each encode call sends one piece of text. Brain runs the synchronous fast path — validate, embed, reserve a slot, persist (the WAL fsync acknowledges the write) — then derives edges and the typed graph asynchronously. The response carries the memory_id and whether the text was deduplicated.

const facts = [
  'Priya moved to Tokyo and works in fintech.',
  'Priya prefers concise answers.',
  'Priya uses Neovim.',
];

for (const text of facts) {
  const res = await brain.encode({ text });
  console.log(res.memory_id, res.was_deduplicated);
}

facts = [
    'Priya moved to Tokyo and works in fintech.',
    'Priya prefers concise answers.',
    'Priya uses Neovim.',
]

for text in facts:
    res = brain.encode(text=text)
    print(res.memory_id, res.was_deduplicated)

let facts = [
    "Priya moved to Tokyo and works in fintech.",
    "Priya prefers concise answers.",
    "Priya uses Neovim.",
];

for text in facts {
    let res = brain
        .encode(&EncodeInput { text: text.into(), ..Default::default() })
        .await?;
    println!("{} {}", res.memory_id, res.was_deduplicated);
}

Recall

recall fans out to the three retrievers — semantic, lexical, and entity-graph — fuses their ranks, reranks, and returns an answer. answer_kind is single (one clear answer), many (several relevant memories), or none (Brain found nothing rather than guessing).

const answer = await brain.recall({ query: 'where does Priya live?' });

console.log(answer.answer_kind);        // 'single'
for (const m of answer.memories) {
  console.log(m.text, m.similarity_score);
}
// Priya moved to Tokyo and works in fintech.

answer = brain.recall(query='where does Priya live?')

print(answer.answer_kind)        # 'single'
for m in answer.memories:
    print(m.text, m.similarity_score)
# Priya moved to Tokyo and works in fintech.

let answer = brain
    .recall(&RecallInput { query: "where does Priya live?".into(), ..Default::default() })
    .await?;

println!("{}", answer.answer_kind); // "single"
for m in &answer.memories {
    println!("{} {}", m.text, m.similarity_score);
}

Call whoami() to see the (namespace, agent) your key is bound to and the permissions it carries — handy when you have several keys in a dev environment.

→ Next

Your first memory

The same flow, field by field — every value in the encode and recall responses.

→ Concepts

Memory types

Fact, preference, event, entity, relation — and how each supersedes.

→ Reference

SDK reference

Every method on the HTTP and wire clients.

Install the SDK

Create the client

Encode some memories

Recall

On this page