Seven layers
The brain is presented to clients as seven substrate layers. Each layer maps to concrete infrastructure in the brain repo on ArcHelm.
Components
ArcRouter
The API gateway for all brain calls. Every LLM request - from Surface, Trebek, ArcCycle, or tenant apps - routes through ArcRouter. It resolves effort aliases to catalog descriptors, enforces tenant entitlements and provider class restrictions, meters usage to the ledger, and handles multi-model failover.
Runs in a Docker container on ArcHelm at port 4000. API key prefix sk-. Keys provisioned through ArcHub admin API.
Tenancy kernel
Postgres service that owns the tenant registry, entitlement grants, and usage ledger. ArcRouter calls it on every gated request. The tenancy service runs at port 8083.
User memory layer
Per-user profile state stored in the tenancy Postgres. The SDK exposes it via brain.memory.*. Shape of the profile JSON is tenant-defined - the brain stores and returns it without interpreting it. The user_id is always an opaque token, never PII.
The memory layer (schema 002 + tenancy/src/memory.ts) is built and typechecked, but the PR has not merged. Apply after review.
Compliance kernel
Consent records, deletion attestations, and retention policies. Enforced at write time by upsertProfile() - you cannot write BIOMETRIC data without a valid, unexpired consent record. The brain.consent.* SDK namespace is the entry point.
Covers BIPA (Illinois) §15(b) written consent requirement, CPRA (California) right-to-deletion, and HIPAA-adjacent HEALTH data retention defaults.
Schema 003 + tenancy/src/compliance.ts - built and typechecked. Not yet deployed.
Training pipeline (L6)
SLRP.1 - Supervised Learning and Reward Pipeline. Converts ArcRouter completion logs to HuggingFace SFT dataset format. Domain classifier tags each example. Multi-turn windowing preserves conversation structure. HAG (Human Approval Gate) requires approved_by to be set on every training manifest before the training runner will consume it - fails closed on null.
Feeds Noema model training. Output: our own distilled models that replace Claude over time for common Grid workloads.
Provider tiers
ArcRouter routes to three provider classes. The routing table maps effort aliases to candidate descriptors - each descriptor carries a providerClass that controls which tenant tiers can use it.
| Class | Where it runs | Current models | Tenant access |
|---|---|---|---|
local |
ArcRig fleet on-prem (10.20.10.x) | qwen3-fast, qwen2.5-coder:32b, llama3.1:8b, claude-code-3b fine-tunes | T0 + T1 + T2 |
cloud |
Our cloud infra (Runpod / Modal) | Same models, our infra (provisioning pending) | T0 + T1 + T2 + T3 |
frontier |
External APIs (Anthropic, Groq, Together) | Claude Sonnet/Opus (live), Groq/Together (D.3 unblocked) | T0 + T1 only (T2/T3 blocked) |
Provider class enforcement is built (brain PR #37). Cloud descriptors come when cloud infra is provisioned. Groq/Together/Gemini frontier descriptors come when D.3 keys arrive.
Tenant tiers
| Tier | Who | Enforcement | Provider access |
|---|---|---|---|
T0 | Grid-internal (grid, team keys) | None - no entitlement gates, no provider limits | All |
T1 | Wholly owned properties | None | All |
T2 | Co-owned portfolio clients | Module entitlements enforced. Research_only blocked. Frontier APIs blocked. | local + cloud |
T3 | External paying clients (Avalon, Beyond-Sleep, Aris, AgX) | Full enforcement. Cloud only by default. | cloud only (override: key.allowedProviderClasses) |
Wiring guide
Two team-facing surfaces need to be wired to the brain. Neither requires changes to how they work - only where they direct LLM calls.
Surface backend
Add @arcgrid/brain-client as a dependency. Replace direct Anthropic calls with brain.chat(). Use the T0 grid API key - no entitlement gates apply.
See Brain SDK - Internal wiring for the exact pattern.
Trebek
Replace Trebek's hardcoded model reference with brain.chat(). Neo4j MCP wiring stays unchanged - only the language layer changes. Result: all Trebek calls are metered, logged, and can be rerouted to local models for client privacy sessions.
ArcCycle
Every turn in a Cycle calls brain.chat() with module_id set per capability and attribution.flow_id set to the Cycle id. This gives per-turn metering and per-turn routing decisions.
Surface and Trebek currently call Anthropic directly. Brain PRs #35 and #36 need to merge first, then Surface and Trebek get SDK-wired as separate PRs.
Activation checklist
Everything below is built. What is not yet done is activating it on ArcHelm.