Multi-tenancy overview

Most apps built on Supermemory serve more than one user, customer, or tenant out of a single Supermemory organization. Multi-tenancy is how you keep those memories apart — so User A’s data is never visible to User B, and so you can still slice and query within a user’s own data by things like category, status, or date. Supermemory gives you two complementary tools for this:

Namespaces

Isolation. A namespace is a hard boundary. Memories in one namespace are never returned by a search scoped to another namespace.

Metadata filtering

Organization. Metadata is a set of custom key/value properties on a memory that you filter by — category, priority, date, participants, anything you define.

They solve different problems, and most production apps use both together.

Why two mechanisms

It’s tempting to reach for one tool and make it do everything, but namespaces and metadata aren’t interchangeable — they answer different questions.

Question	Answer
”Which tenant does this memory belong to?”	Namespace
”Within this tenant’s memories, which ones match `status: open`?”	Metadata filter
”Can this API key even see tenant X’s data?”	Namespace (enforced as an access boundary)
“Find memories tagged `engineering` created after March”	Metadata filter

A namespace decides whether a memory is reachable at all for a given request. Metadata decides which of the reachable memories match. Filtering never crosses a namespace boundary — you can’t use metadata to peek into another tenant’s namespace.

How they work together

A typical multi-tenant write scopes the memory to a tenant with a namespace, then attaches metadata for finer-grained querying later:

await supermemory.add("org_acme", { // isolates to the "acme" tenant
  content: "Customer requested a refund for order #4821",
  metadata: {
    category: "support",
    status: "open",
    priority: "high",
  },
});

And a search combines both: the namespace restricts which tenant’s data is in scope, and the filter narrows down which memories within that tenant come back:

const results = await supermemory.search("org_acme", {
  query: "refund request",
  filter: {
    operator: "and",
    operands: [
      { field: "category", operator: "eq", value: "support" },
      { field: "status", operator: "eq", value: "open" },
    ],
  },
  searchMode: "chunks",
});

The namespace is required on every call (it is part of the URL) and validated as an access boundary. Metadata filters are optional — a search with just namespace and no filter still only returns that tenant’s memories.

Choosing your boundary

The namespace is the layer that should map to your actual tenancy model — pick the level that matches what “one isolated space” means in your app:

Pattern	Example	Use case
Per-user	`user_{userId}`	Consumer app, personal memory per user
Per-tenant/org	`org_{orgId}`	B2B SaaS, one namespace per customer org
Hierarchical	`org:{orgId}:user:{userId}`	Multi-level — isolate by org, and optionally drill into a user within it
Per-project	`project_{projectId}`	Workspace- or project-scoped content

The simplest form is one namespace per user, derived from an ID you already have:

await supermemory.add(userId, { // one namespace per user
  content: "User prefers morning workouts",
});

const results = await supermemory.search(userId, {
  query: "workout preferences",
});

Everything within that boundary — categories, statuses, dates, custom fields — is metadata, not a new namespace. Don’t create a new namespace for every property you want to filter on; that’s what metadata is for.

Access control

Namespaces aren’t just organizational — they’re enforced as an authorization boundary. API keys and org members can be restricted to specific namespaces, so a request for a namespace outside the caller’s allowed set is rejected with 403 Forbidden rather than silently filtered. See Namespaces → Access control for the details.

Next steps

Examples

Personal agents, company agents, email assistants, and support platforms.

Namespaces

How isolation works, naming rules, and access control.

Organizing & Filtering

Metadata filter operators, combining and/or, and query limits.

Scoped API keys

Mint keys that can only touch one namespace.

Getting started

Concepts

Using supermemory

Deployment

Other resources

Migration guides

Namespaces

Metadata filtering

Why two mechanisms

How they work together

Choosing your boundary

Access control

Next steps

Examples

Namespaces

Organizing & Filtering

Scoped API keys

Namespaces

Metadata filtering

​Why two mechanisms

​How they work together

​Choosing your boundary

​Access control

​Next steps

Examples

Namespaces

Organizing & Filtering

Scoped API keys

Why two mechanisms

How they work together

Choosing your boundary

Access control

Next steps