Prerequisites

Go 1.22 or later (go version to check)
A modern code editor (VS Code, GoLand)
10–15 minutes of focused time

Handler options

Option A — Local Handler (development):

docker pull qosil/brrain-handler:latest
docker run -p 8080:8080 qosil/brrain-handler:latest

Option B — Hosted Handler (free tier): Sign up at app.brrain.io/signup. Handler access is included.

1

Install the SDK

go get github.com/Qosil/bRRAIn/sdk

Verify the install:

go list -u -m github.com/Qosil/bRRAIn/sdk

Expected output: the SDK module name followed by its current version.

2

Get Your API Key

Free tier: sign up at app.brrain.io, then Settings → API Keys → Generate New Key.

Self-hosted: use the internal API key from your bRRAIn Core instance.

Store the key in .env (never commit to source control):

BRRAIN_API_KEY=sk_dev_xxxxxxxxxxxxx

3

Initialize the SDK

Create main.go:

package main

import (
    "fmt"
    "os"

    "github.com/Qosil/bRRAIn/sdk"
)

func main() {
    apiKey := os.Getenv("BRRAIN_API_KEY")

    client := sdk.NewClient(apiKey,
        sdk.WithHandler("http://localhost:8080"),
    )

    ws, err := client.CreateWorkspace("quickstart-demo")
    if err != nil {
        panic(err)
    }

    fmt.Printf("Workspace created: %s\n", ws.ID)
}

Run it:

go run main.go

Expected output: Workspace created: ws_xxxxxxx

4

Store Your First Record

record := map[string]interface{}{
    "type":    "article",
    "title":   "Introduction to bRRAIn",
    "author":  "Jane Developer",
    "content": "bRRAIn is a zero-trust graph memory...",
    "tags":    []string{"ai", "memory", "graph"},
}

id, err := ws.Store(record,
    sdk.WithContext(map[string]string{
        "category":   "tutorial",
        "difficulty": "beginner",
    }),
)
if err != nil {
    panic(err)
}

fmt.Printf("Record stored with ID: %s\n", id)

Expected output: Record stored with ID: rec_xxxxxxx

5

Query with Graph Context

results, err := ws.Retrieve(sdk.Query{
    Search: "getting started with memory systems",
    Limit:  5,
})
if err != nil {
    panic(err)
}

for _, result := range results {
    fmt.Printf("Found: %s (confidence: %.2f%%)\n",
        result.Data["title"], result.Score*100)
}

Expected output: your article with a high confidence score.

6

Build a Graph with Multiple Records

records := []map[string]interface{}{
    {"type": "person",  "name": "Alice", "role": "engineer"},
    {"type": "person",  "name": "Bob",   "role": "designer"},
    {"type": "project", "name": "ProjectX", "team": []string{"Alice", "Bob"}},
}

for _, r := range records {
    if _, err := ws.Store(r); err != nil {
        panic(err)
    }
}

results, _ := ws.Retrieve(sdk.Query{
    Search: "what projects is Alice working on?",
})
// Returns ProjectX with graph context for Alice and Bob.

7

Non-Human Actors (optional)

bRRAIn models robots, IoT sensors, and automation services as first-class participants with their own audit trail.

serviceSession, err := ws.CreateSession(sdk.SessionTypeService,
    sdk.WithMetadata(map[string]string{
        "purpose":  "daily-log-ingestion",
        "schedule": "0 2 * * *", // 2 AM daily
    }),
)
if err != nil {
    panic(err)
}

// This service can now store records autonomously.

What's next?

Troubleshooting

Connection refused: Verify the Handler is running at the URL passed to sdk.WithHandler.
Invalid API key: Confirm BRRAIN_API_KEY is exported in the environment running your Go process.
Workspace already exists: Pick a different workspace name, or load the existing one with client.GetWorkspace(name).

Get Started in 15 Minutes