Quickstart — bRRAIn Docs

Get up and running with bRRAIn in five minutes. Obtain an API key, store your first memory, and retrieve it.

Quickstart

This guide walks you through storing and retrieving your first memory object using the bRRAIn API. By the end, you will have a working integration in under five minutes.

Prerequisites

  • A bRRAIn account (sign up at app.brrain.io)
  • An API key (generated from Settings > API Keys in the dashboard)
  • A terminal with cURL, or a development environment with Go or Python installed

Step 1: Get Your API Key

Log in to the bRRAIn dashboard at app.brrain.io. Navigate to Settings > API Keys and click Create New Key. Give your key a descriptive name (e.g., "quickstart-demo") and select the read-write scope. Copy the key immediately; it will not be shown again.

Your API key looks like this:

brr_live_k1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6

Store this key securely. Never commit it to version control or expose it in client-side code.

Step 2: Store Your First Memory

The memory store endpoint accepts a JSON payload containing the content you want to remember, along with optional metadata for categorization.

Using cURL

curl -X POST https://api.brrain.io/v1/memory/store \
  -H "Authorization: Bearer brr_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The quarterly board meeting is held on the first Tuesday of each quarter. The CFO presents the financial summary first, followed by department heads in alphabetical order.",
    "metadata": {
      "category": "procedures",
      "department": "executive",
      "tags": ["meetings", "board", "quarterly"]
    }
  }'

Expected Response:

{
  "id": "mem_7f3a2b1c4d5e6f8g",
  "status": "stored",
  "vault_id": "vlt_default",
  "workspace_id": "ws_default",
  "created_at": "2026-04-15T10:30:00Z",
  "content_hash": "sha256:9f86d081884c7d659a2feaa0c55ad015...",
  "metadata": {
    "category": "procedures",
    "department": "executive",
    "tags": ["meetings", "board", "quarterly"]
  }
}

Using Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

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

    payload := map[string]interface{}{
        "content": "The quarterly board meeting is held on the first Tuesday of each quarter. The CFO presents the financial summary first, followed by department heads in alphabetical order.",
        "metadata": map[string]interface{}{
            "category":   "procedures",
            "department": "executive",
            "tags":       []string{"meetings", "board", "quarterly"},
        },
    }

    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.brrain.io/v1/memory/store", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        fmt.Fprintf(os.Stderr, "request failed: %v\n", err)
        os.Exit(1)
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("Memory stored: %s\n", result["id"])
}

Using Python

import os
import requests

api_key = os.environ["BRRAIN_API_KEY"]

response = requests.post(
    "https://api.brrain.io/v1/memory/store",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "content": "The quarterly board meeting is held on the first Tuesday "
                   "of each quarter. The CFO presents the financial summary "
                   "first, followed by department heads in alphabetical order.",
        "metadata": {
            "category": "procedures",
            "department": "executive",
            "tags": ["meetings", "board", "quarterly"],
        },
    },
)

result = response.json()
print(f"Memory stored: {result['id']}")

Step 3: Retrieve a Memory

Now query your stored memory using a natural language question. bRRAIn uses semantic search to find the most relevant memory objects.

Using cURL

curl -X GET "https://api.brrain.io/v1/memory/retrieve?q=when+is+the+board+meeting&limit=3" \
  -H "Authorization: Bearer brr_live_YOUR_API_KEY"

Expected Response:

{
  "query": "when is the board meeting",
  "results": [
    {
      "id": "mem_7f3a2b1c4d5e6f8g",
      "content": "The quarterly board meeting is held on the first Tuesday of each quarter. The CFO presents the financial summary first, followed by department heads in alphabetical order.",
      "relevance_score": 0.94,
      "metadata": {
        "category": "procedures",
        "department": "executive",
        "tags": ["meetings", "board", "quarterly"]
      },
      "created_at": "2026-04-15T10:30:00Z"
    }
  ],
  "total": 1,
  "took_ms": 23
}

Using Go

req, _ := http.NewRequest("GET", "https://api.brrain.io/v1/memory/retrieve?q=when+is+the+board+meeting&limit=3", nil)
req.Header.Set("Authorization", "Bearer "+apiKey)

resp, err := http.DefaultClient.Do(req)
if err != nil {
    fmt.Fprintf(os.Stderr, "request failed: %v\n", err)
    os.Exit(1)
}
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)

results := result["results"].([]interface{})
for _, r := range results {
    mem := r.(map[string]interface{})
    fmt.Printf("Found: %s (score: %v)\n", mem["id"], mem["relevance_score"])
}

Using Python

response = requests.get(
    "https://api.brrain.io/v1/memory/retrieve",
    headers={"Authorization": f"Bearer {api_key}"},
    params={"q": "when is the board meeting", "limit": 3},
)

data = response.json()
for result in data["results"]:
    print(f"Found: {result['id']} (score: {result['relevance_score']})")

Step 4: Explore Further

Now that you have stored and retrieved your first memory, explore these next steps:

  • Bulk import: Use the /v1/memory/batch endpoint to import existing documents
  • Vault management: Create dedicated vaults for different teams or data classifications
  • Webhooks: Subscribe to memory events for real-time integrations
  • SDKs: Install the official Go, Python, or JavaScript SDK for a more ergonomic developer experience

Troubleshooting

| Issue | Solution | |-------|----------| | 401 Unauthorized | Verify your API key is correct and has not been revoked | | 403 Forbidden | Ensure your key has the required scope (read-write for store operations) | | 429 Too Many Requests | You have exceeded the rate limit; wait and retry with exponential backoff | | Empty results on retrieve | Your query may not semantically match stored content; try rephrasing |

For additional help, visit the Support page or join our community on Discord.