SDK Quick Start — bRRAIn Docs

Install the SDK, create a workspace, store a record, and run a graph-aware query in under 15 minutes.

SDK Quick Start

This guide gets you from zero to a working query in under 15 minutes.

Prerequisites

  • Go 1.22+
  • A modern editor
  • 10 minutes of focused time

Handler options:

  • Local (recommended for development): docker run -p 8080:8080 qosil/brrain-handler:latest
  • Hosted (free tier): sign up at app.brrain.io

1. Install

go get github.com/Qosil/bRRAIn/sdk

2. Get an API key

Sign up at app.brrain.io and generate a key under Settings → API Keys. Store it in .env:

BRRAIN_API_KEY=sk_dev_xxxxxxxxxxxxx

3. Initialize

package main

import (
    "fmt"
    "os"

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

func main() {
    client := sdk.NewClient(os.Getenv("BRRAIN_API_KEY"),
        sdk.WithHandler("http://localhost:8080"),
    )

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

    fmt.Println("Workspace created:", ws.ID)
}

4. Store a record

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

id, _ := ws.Store(record, sdk.WithContext(map[string]string{
    "category":   "tutorial",
    "difficulty": "beginner",
}))

fmt.Println("Record ID:", id)

5. Query with graph context

results, _ := ws.Retrieve(sdk.Query{
    Search: "getting started with memory systems",
    Limit:  5,
})

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

6. Build a graph

Store multiple related records and query the graph directly:

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 {
    ws.Store(r)
}

results, _ := ws.Retrieve(sdk.Query{
    Search: "what projects is Alice working on?",
})

7. Non-human actors (optional)

svc, _ := ws.CreateSession(sdk.SessionTypeService,
    sdk.WithMetadata(map[string]string{
        "purpose":  "daily-log-ingestion",
        "schedule": "0 2 * * *",
    }),
)

Troubleshooting

  • connection refused — the Handler isn't running at the URL passed to sdk.WithHandler.
  • invalid API key — verify BRRAIN_API_KEY is exported in the calling process.
  • workspace already exists — use client.GetWorkspace(name) to fetch the existing one instead.

What's next