Superbrain Documentation

Coordinator Bypass (Metadata Caching)

Establishing a new pointer requires a ROUND TRIP to the Coordinator. However, Superbrain SDKs implement a local **Pointer Map Cache**. Once a 36-byte UUID is resolved to a node's IP:

• ✔ Direct I/O: All future Read/Write calls bypass the Coordinator entirely.
• ✔ 1ms Operations: Eliminates control-plane latency from the data hot-path.
• ✔ P2P Discovery: SDKs listen to Gossip protocol to update node healthy states locally.

Write-Ahead Log (WAL)

To prevent data loss in the async queue during a crash, Superbrain records every write task in a local Write-Ahead Log before acknowledging it to the agent's RAM. On restart, the node automatically replays the WAL to recover any unsaved blocks.

Configuration Example

# Start node with Durable Local Storage
./bin/node --persistence-provider=filestore \
           --persistence-config='{"path": "/var/lib/superbrain", "wal_sync_mode": "always"}'

JSON Configuration Backends

Configure the L3 tier by passing provider-specific JSON via the --persistence-config flag.

./bin/node --persistence-provider=filestore \
           --persistence-config='{"path": "/data", "wal_sync_mode": "always"}'

./bin/node --persistence-provider=redis \
           --persistence-config='{"addr": "localhost:6379", "db": 0}'

./bin/node --persistence-provider=postgres \
           --persistence-config='{"dsn": "postgres://user:pass@host:5432/db"}'

Zero-Trust mTLS

Every node and agent must be enrolled in the cluster's private PKI. The Coordinator acts as a Certificate Authority (CA), issuing short-lived certificates upon successful registration.

End-to-End Encryption (E2EE)

When enabled via SB_ENCRYPTION_KEY, the SDK wraps all memory writes in AES-GCM-256. Infrastructure nodes only see encrypted entropy, ensuring your agent's private reasoning remains private.

client = superbrain.Client(encryption_key=KEY_32_BYTES)

const client = new SuperbrainClient(addr, { encryptionKey: KEY_32_BYTES });

client, _ := sdk.NewClientWithEncryption(key, addr)

Client.Register(agentID)

The first step for any secure agent. This method performs an mTLS handshake, generates a local keypair, and obtains a signed certificate from the Coordinator CA.

# Identity enrollment in the Secure Fabric
client.register("research-agent-01")

// Enrollment is required before any Write/Allocate
await client.register("research-agent-01");

err := client.Register("research-agent-01")

Consistency Guard (Raft)

For distributed agents, Superbrain uses a Raft-based consensus protocol to manage Semantic Locks. This prevents logical race conditions where two agents might attempt to "read-modify-write" a shared reasoning state simultaneously.

Client.Allocate(size)

Reserves chunks of RAM across the distributed fabric. Returns a 36-byte UUID pointer.

# 🔒 Secure Client (mTLS + E2EE)
client = superbrain.Client(
    coordinators=["coord:50050"],
    encryption_key=os.getenv("SB_KEY")
)

# Allocate 50MB
ptr_id = client.allocate(50 * 1024 * 1024)
print(f"Memory ready: {ptr_id}")

// Allocate 50MB
const ptrId = await client.allocate(50 * 1024 * 1024);
console.log(`Memory ready: ${ptrId}`);

// Allocate 50MB
ptr, err := client.Allocate(50 * 1024 * 1024)
fmt.Printf("Memory ready: %s\n", ptr.ID)

Parameters

Common Exceptions

• ERR_QUOTA_EXHAUSTED: Cluster has no free RAM in this tier.
• ERR_COORD_UNREACHABLE: Metadata resolve failed.

Client.WriteCognitive(...)

Enriches raw data writes with semantic metadata. This is the foundation of Superbrain's "Cognitive Architecture".

Parameters

# Write with metadata and 30-day "half-life"
client.write_cognitive(
    ptr_id, offset=0, data=b"...",
    liveliness=0.8,
    intent="Strategic Planning",
    summary="Agent decision to expand search",
    tag="Critical"
)

await client.writeCognitive(ptrId, 0, data, {
    liveliness: 0.8,
    intent: "Strategic Planning",
    summary: "Agent decision to expand search",
    tag: "Critical"
});

client.WriteCognitive(ptr, 0, data, sdk.CognitiveOptions{
    Liveliness: 0.8,
    Intent:     "Strategic Planning",
    Summary:    "Agent decision to expand search",
    Tag:        "Critical",
})

Client.SemanticSubscribe(intent)

Registers a reactive trigger that wakes your agent up when any other agent in the fabric writes with a matching semantic intent.

def on_user_goal(notify):
    print(f"Goal Detected: {notify.summary}")

# Block until a 'User Goal' is written to the fabric
client.semantic_subscribe("User Goal", on_user_goal)

client.semanticSubscribe('User Goal', (notify) => {
    console.log(`Goal Detected: ${notify.summary}`);
});

client.SemanticSubscribe("User Goal", func(n *sdk.Notification) {
    fmt.Printf("Goal Detected: %s\n", n.Summary)
})

Scenario 4: Durable Recovery After Hard Crash

A Memory Node experiences a hardware power failure while holding critical agent context. Because Level 4 (FileStore) was enabled:

• ✔ WAL Replay: Upon restart, the node detects the WAL file and replays all uncommitted writes.
• ✔ Self-Healing: Agents reconnect automatically and find their data intact in RAM (rehydrated from disk).
• ✔ Zero Code Change: This durability is transparent to the SDK.