How does multi-tenancy isolate memory?

The past several chapters have described scoping from the perspective of what a caller sends, a user identifier, a custom property, a request to isolate memory a particular way. This chapter looks underneath that surface, at the actual storage mechanism that makes strict user isolation hold reliably rather than merely appear to hold. That mechanism is multi-tenancy, and understanding it clarifies why user-scoped memory in a well-built system doesn’t depend on application code getting a filter right.

What Does It Actually Mean for a Memory Store to Assign Each Tenant Its Own Dedicated Shard?

A shard is a self-contained storage and query unit holding one specific slice of data, and in a multi-tenant architecture, each tenant gets assigned its own dedicated shard rather than sharing one undivided pool with everyone else. This means a tenant’s data physically lives somewhere structurally separate from another tenant’s data, not merely tagged differently within the same underlying storage. A query running against one tenant’s shard genuinely cannot see into a different tenant’s shard, because the two are separate storage units entirely, not one shared unit with an internal label distinguishing them.

Why Does Physical Separation at the Storage Layer Matter More Than a Filter Applied at Query Time?

A filter applied at query time depends on the code issuing that query remembering to apply it correctly, every single time, across every code path that ever touches search results. Physical separation removes that dependency entirely, since a query directed at one tenant’s shard has no path by which it could accidentally return a different tenant’s data, regardless of whether the application code asking the question got every detail right. This is the practical difference between isolation that’s merely intended and isolation that’s actually structurally guaranteed, and it’s exactly the difference this Part has been building toward since its opening chapter on why memory needs access control in the first place.

Does Assigning Each Tenant a Dedicated Shard Come at the Cost of Query Performance as the Number of Tenants Grows?

It doesn’t have to, and this is one of the more counterintuitive benefits of a well-built multi-tenant architecture. Because each tenant’s shard carries its own dedicated, high-performance index, a query against one tenant’s data behaves as though that tenant were the only one using the system at all, rather than having to sift through or filter around everyone else’s data mixed into the same shared index. A system supporting millions of tenants can maintain this same per-tenant responsiveness precisely because tenants aren’t actually competing within one shared index, they’re each working against their own independent one.

What Happens to Isolation When a Tenant’s Data Needs to Be Deleted Entirely, Whether for a Compliance Reason or Simply Because a User Left?

This is another area where physical separation pays off directly. Deleting an entire tenant’s data becomes a matter of removing that tenant’s own dedicated shard, a fast, complete, and unambiguous operation, rather than needing to hunt through a shared pool of data for every record tagged with a specific identifier and hoping nothing gets missed. This matters considerably for compliance obligations that require proving a specific person’s data has genuinely been removed in full, since a dedicated shard’s deletion leaves no ambiguity about whether some stray record was left behind in an unrelated part of the system.

Is Multi-Tenancy Only Relevant for Isolating Different Paying Customers From Each Other, or Does It Apply Just as Well to Isolating Individual Users Within a Single Application?

It applies equally well to both, and this is worth being explicit about since the word “tenant” can sound like it only means a separate paying customer. The same underlying mechanism that keeps one company’s data separate from a different company’s data in a shared platform is exactly what keeps one individual user’s memories separate from a different individual user’s memories within a single application serving many people. Whether the boundary being enforced separates organizations or separates individuals, the structural guarantee multi-tenancy provides works the same way underneath.

How Does Weaviate Engram Rely on This Underlying Multi-Tenancy Mechanism to Make Its User Scoping Actually Hold?

Weaviate Engram’s strict user isolation is built directly on Weaviate’s own multi-tenancy architecture, meaning a user-scoped memory lives in a shard dedicated to that specific user rather than in a shared pool distinguished only by a filterable field. Consider a genealogy research platform where members build and search their own family history records, and where one member’s research into their own ancestry must never surface, even partially, in a completely unrelated member’s search:

from engram import EngramClient

client = EngramClient(api_key=os.environ["ENGRAM_API_KEY"])

client.memories.add(
    "Member traced a great-grandparent's immigration records to a specific port of entry in 1911 and confirmed a family surname spelling change.",
    user_id="member-genealogy-8842",
)

member_search = client.memories.search(
    query="What did I find out about my great-grandparent's immigration?",
    user_id="member-genealogy-8842",
)

Because this member’s research memories live in a shard dedicated to their own user identifier, a different member’s search, even one exploring a coincidentally similar surname or the same historical port of entry, has no path to that shard at all, not because a filter happened to exclude it, but because the underlying storage never made it reachable in the first place. This is exactly the value multi-tenancy delivers for a use case like genealogy research, where the deeply personal nature of family history research means members need absolute confidence that their own findings stay theirs alone, structurally, not merely by policy.

Multi-tenancy is the storage-layer mechanism that makes strict user isolation an actual structural guarantee rather than a convention application code has to keep honoring correctly. Understanding this mechanism also clarifies exactly where the earlier distinction between hard and soft isolation actually comes from at the infrastructure level. Our next chapter, What is hard isolation vs soft isolation?, takes up that distinction directly.