Namespace lifecycle
Plan, create, populate, and decommission a namespace — the tenant boundary. Tenancy is managed in the dashboard; per-namespace schema is declared over the wire.
- Dashboard access to your Arc Labs org (tenancy is a control-plane concern).
- Familiarity with the namespaces concept and identity.
A repeatable checklist for standing up a new tenant: one namespace, its agents, keys, and schema — plus how to verify and tear it down.
A namespace is a tenant boundary, not a folder
A namespace is the top-level isolation boundary — it owns its memories, entities, statements, and relations, and no key outside it can read across. Create a namespace for a product, a customer tier, or an environment — never per end-user. The right heuristic and the anti-patterns are in Namespaces.
Namespaces, agents, keys, members, and plan are all control-plane — managed in the Arc Labs dashboard, not through the data-plane /v1/* API. The data plane only ever scopes each request to the (namespace, agent) its key resolves to. See Org.
Step-by-step
Decide what the namespace represents before you create it. One namespace per product or per enterprise customer; environments (dev, staging, production) as separate namespaces of the same code. End-users are not namespaces — they share a namespace, isolated by the agent their key is bound to.
In the dashboard: create and name the namespace (tenant), then create the agents (apps / personas) inside it. A namespace can hold many agents; each is a distinct reader/writer.
Still in the dashboard, mint an API key bound to each (namespace, agent) with the permission flags that agent needs. The plaintext secret is shown once — store it in your secret manager immediately. Give each agent its own key so you can rotate or revoke one without touching the others. See API keys.
Schema is always on — the seeded brain: system namespace is active from byte zero — and user declarations merge into it additively. To constrain which typed entities, statements, and relations your namespace accepts, upload a schema with the wire client's uploadSchema. Typed-graph writes then check per-type against it.
const up = await client.uploadSchema({
schemaDocument: schemaText,
dryRun: false, // dryRun: true validates without applying
allowBreaking: false,
requestId: newId(),
});
// up: { namespace, schemaVersion, validationErrors, backwardCompatible, ... }Uploading is wire-only; see Typed graph → Schema. Recall, extraction, and indexing run regardless of what you declare — schema narrows explicit typed-graph writes and which extracted candidates persist, it does not gate reads.
Before pointing production traffic at the new key, confirm it resolves where you expect:
const me = await new BrainHttpClient({ apiKey: NEW_KEY }).whoami();
if (me.namespace !== "acme-prod") throw new Error(`key resolves to ${me.namespace}`);me = BrainHttpClient(NEW_KEY).whoami()
assert me.namespace == "acme-prod", f"key resolves to {me.namespace}"let me = BrainHttpClient::new("https://api.arc-labs.ai", NEW_KEY).whoami().await?;
if me.namespace.as_deref() != Some("acme-prod") {
return Err(format!("key resolves to {:?}", me.namespace).into());
}To retire a tenant, revoke its keys and delete the namespace from the dashboard. Revoked keys return 401 unauthorized immediately; a deleted namespace stops accepting reads and writes. Because keys are the entry point, revoking them is the fast kill switch even before deletion completes.
Migration and re-embedding
Brain is a single binary — there is no external database to attach and no pgvector to re-dimension. Brain owns its embedding model (BGE-small, 384-dim); clients send text, not vectors. There is no data-plane "reembed job" verb in the API. Operational migration and admin tooling (brainctl) is future work; for now, tenant lifecycle is dashboard creation plus schema declaration.
Set the tenant's schema before its first production write. Extraction persists typed-graph rows only for declared types, so declaring the schema after data has flowed leaves earlier writes without the typed structure you expected.
Was this page helpful?
Multi-tenant patterns
Serve many tenants correctly — namespace-per-tenant isolation, one key per agent, and a pooled service key with per-request act_as. No user axis, no scope juggling.
Graph queries
When to reach past recall into the typed graph — resolve an entity, read its relations, traverse from an anchor, and export the whole graph.