Open Source to Cloud Upgrade Guide

The Problem: Outgrowing Open Source

Brain open-source is great for development and early production, but at scale you hit:

• Operational overhead: You manage upgrades, backups, scaling
• Availability SLAs: No guarantees; downtime = your agent downtime
• Multi-tenant isolation: If running multiple agents, they share compute
• Compliance: You handle GDPR, SOC 2, data residency

Brain Managed Cloud is a drop-in replacement:

• Zero downtime: Automatic failover, geo-redundancy
• Compliance included: GDPR-ready, SOC 2, data residency options
• Auto-scaling: Handles traffic spikes without config
• Expert operations: Let us manage upgrades, backups, performance tuning

Best part: Your code doesn't change. Same API, same behavior, same queries—just point to the cloud.

The 3 Steps

Step 1: Set Environment Variables

Open source uses a local endpoint. Cloud uses an API key.

# Before (open source)
export BRAIN_ENDPOINT="http://localhost:8000"

# After (cloud)
export BRAIN_API_KEY="rec_...your_api_key..."
export BRAIN_ENDPOINT="https://api.brain.cloud"

Get your BRAIN_API_KEY from the Brain Cloud dashboard.

Step 2: Update Initialization

Python:

Before (open source):

from brain_sdk import Brain

brain = Brain(endpoint="http://localhost:8000")

After (cloud):

from brain_sdk import Brain

brain = Brain(api_key="rec_...your_api_key...")
# Endpoint defaults to https://api.brain.cloud

Or use environment variables (simpler):

# Set BRAIN_API_KEY env var, then:
from brain_sdk import Brain

brain = Brain()  # Reads from env

TypeScript:

Before (open source):

import { Brain } from "brain-sdk";

const brain = new Brain({
  endpoint: "http://localhost:8000",
});

After (cloud):

import { Brain } from "brain-sdk";

const brain = new Brain({
  apiKey: process.env.BRAIN_API_KEY,
  // endpoint defaults to https://api.brain.cloud
});

Or:

// Use environment variables
const brain = new Brain();

Step 3: Deploy & Test

Your store(), retrieve(), list(), and all other APIs stay identical.

# This code works on both open-source and cloud—no changes
await brain.store(
    agentId="agent_1",
    content="User prefers coffee at 8am",
    metadata={"type": "preference"}
)

results = await brain.retrieve(
    agentId="agent_1",
    query="What does the user like?",
    topK=5
)

Deploy your updated config and it just works.

Environment Variables

Backward Compatibility Guarantee

✓ All APIs stay the same. store(), retrieve(), list(), delete(), update() signatures don't change.

✓ Same response format. Brain Cloud returns identical JSON to open-source.

✓ Same error codes. ApiError, ValidationError, NotFoundError are the same.

✓ Rollback is safe. If you need to revert, point BRAIN_ENDPOINT back to localhost.

Performance Expectations

Cloud adds network round-trip time but gains reliability and scale. For agent loops, 50–100ms is acceptable (agents don't require <10ms).

Cost Comparison: OSS vs Cloud

Example for 100 agents with 5K memories each = 500K vectors:

• OSS on EC2 (t3.medium): $20/month infra + your ops time
• Cloud: $500/month for 500K vectors +$100/month retrievals (1K/day)

Cloud wins if you have multiple agents or need compliance/availability.

Implementation Checklist

• Create Brain Cloud account (or request API key if provided)
• Copy your BRAIN_API_KEY from the dashboard
• Set environment variables: BRAIN_API_KEY and BRAIN_ENDPOINT
• Update SDK initialization to use api_key parameter
• Test: store a memory, retrieve it, verify content matches
• Deploy to staging; run agent for 1 hour, monitor latency
• Verify: latency is acceptable (P99 <200ms), error rates are <0.1%
• Deploy to production

Troubleshooting

Authentication error ("401 Unauthorized")

• Verify BRAIN_API_KEY is correct and not expired
• Confirm it starts with rec_ prefix
• Check dashboard: key might be revoked

Connection timeout

• Confirm BRAIN_ENDPOINT is https://api.brain.cloud (not http://)
• Check firewall: outbound HTTPS to api.brain.cloud should be allowed
• Test: curl https://api.brain.cloud/health

Latency spike

• Cloud P99 is 150–200ms; if you see >300ms, contact support
• Check network conditions; local ISP issues can add 100ms+

Migration rollback

• Set BRAIN_ENDPOINT="http://localhost:8000" to revert to open-source
• Data is not synced; export from cloud if needed

Data Migration (Optional)

If you want to export memories from open-source before switching:

from brain_sdk import Brain
import json

# Open-source instance
brain_oss = Brain(endpoint="http://localhost:8000")

# Export all
all_memories = []
for agent_id in ["agent_1", "agent_2"]:  # Your agent IDs
    memories = await brain_oss.list(agentId=agent_id)
    all_memories.extend(memories)

# Save
with open("memories_export.json", "w") as f:
    json.dump(all_memories, f)

# Then import to Cloud
brain_cloud = Brain(api_key="rec_...")

for memory in all_memories:
    await brain_cloud.store(
        agentId=memory["agentId"],
        content=memory["content"],
        metadata=memory.get("metadata")
    )

Next Steps

• Learn pricing: Check Cost Optimization for Agent Memory
• Multi-team setup: See Embedded vs Cloud Decision for deployment patterns
• Scale your agents: Read Production Checklist for monitoring and observability