Namespaces

A NamespaceId is a stable identity that scopes every memory, entity, statement, and relation. Think of it as the company or customer. Inside it, an agent is the app doing the work. The pair (namespace, agent) is the unit of isolation: every redb row, every HNSW and tantivy index, and every resolver lookup is keyed under it. Two memories with identical text under different agents are two separate memories; one agent's recall never sees another's.

What a namespace is not: a folder, a tag, or a per-user partition. It's a tenant boundary, so you create new ones for product-level or customer-tier-level boundaries — not for end-users. See Identity by key, which is where a key's (namespace, agent) scope is bound.

What lives inside a namespace

namespace  (owned per (namespace, agent))
├─ memories        text + 384-dim vector, arena slot, redb row
├─ entities        canonical nouns — id, type, aliases, attributes
├─ statements      Fact / Preference / Event claims about entities
├─ relations       directed edges between entities
├─ edges           SimilarTo / FollowedBy / Caused / … between memories
├─ schema          the active type + predicate declarations
└─ audit           the WAL-backed change trail

A fully-isolated agent's data is invisible to every other agent, and no cross-agent edges exist — relations and edges are agent-scoped.

Schema is always on

Every shard has an active schema from byte zero: the seeded brain: system namespace. It ships the built-in entity types (Person, Organization, Project, Place, Concept, Event) and system predicates, so extraction, retrieval, and indexing run on every shard whether or not a user has declared anything.

You narrow what gets accepted by uploading your own declarations. A schema upload merges additively into the active state (byte-equal idempotent, all-or-nothing on conflict) — it declares the entity types and predicates your domain uses. Declarations narrow what an explicit STATEMENT_CREATE / RELATION_CREATE / ENTITY_CREATE accepts and which extracted candidates persist; a write referencing a declared type is accepted, one referencing an undeclared type is rejected (explicit) or dropped (extractor best-effort). Declarations do not gate any retrieval, extraction, or index path. The destructive escape hatch — removing or narrowing a declaration — is SCHEMA_REPLACE (admin-only, requires an explicit force flag).

How namespaces map onto shards

Brain's parallelism is sharding (thread-per-core Glommio executors — see Architecture). A request is routed to a shard by its effective agent, so a tenant's data lands consistently on the same shard set and single-writer discipline holds per shard. Under act_as, routing follows the effective identity, not the connection principal — so a gateway serving many tenants over one connection still routes each op to the right tenant's shard.

When to create a namespace

A heuristic: create a namespace boundary when you'd want a hard tenant wall, not when you'd want a folder. Some calibrated examples:

• Per product — your company ships two products on Brain. They're independent corpuses; cross-retrieval would be a bug. Two namespaces, two sets of keys.
• Per customer — each customer is its own namespace, so no query can ever cross a customer boundary. One namespace per customer.
• Per environment — dev, staging, production are namespaces, not deployments. Same code, different namespaces in the keys.
• NOT per end-user — end-users don't need their own namespace. If you need per-user isolation, use a distinct agent per user inside one namespace; the (namespace, agent) wall already separates them.

Provisioning

Namespaces and agents are established when keys are minted — a key is bound to its (namespace, agent, permissions) scope at creation. There is no per-request namespace selection and no per-namespace external database or LLM to attach: Brain is a single binary with one deploy-time LLM provider key (Architecture). To onboard a new tenant, mint a key scoped to its namespace and agent; the SDK pointed at that key reads and writes into the new tenant automatically.