Multi-tenancy
How tenants are isolated — in the request path, in the database and in optional dedicated databases — and how tenant lifecycle and quotas affect API calls.
Agent Memory is multi-tenant from the ground up. A tenant is one customer organization; everything it stores lives in its own workspaces, and no request can read or write another tenant's data. See Scoping for the full tenant → workspace → application → run hierarchy.
Identity comes from the credential
The tenant a request acts for is never taken from the request body, query string or tags. It is derived from the credential:
- an API key pins its tenant, workspace (and optionally application) and capabilities;
- an OAuth or external-IdP token is resolved to a provisioned principal, and the workspace named in the request is checked against that principal's grants.
The request's workspaceId and applicationId are only a declaration that the server validates. A workspace the credential does not hold, or a resource that belongs to another tenant, answers 404 — never 403 — so callers cannot probe for the existence of other tenants' data.
Isolation in the database
Isolation is enforced in PostgreSQL, not only in application code:
- Every tenant table carries
tenant_id, and indexes lead with it. - Row-level security is enabled and forced on tenant tables. The policy compares
tenant_idwith a per-transaction tenant setting; with no setting, a query sees zero rows (fail-closed). - Separate database roles. The API's runtime role cannot bypass row-level security and does not own the tables; schema migrations run under a separate owner role. Registry and identity data live in a control-plane database that the tenant-data role never connects to.
- Per-operation transactions. Each operation opens a fresh transaction and sets the tenant for that transaction only, so a pooled connection can never carry one tenant's context into another's request.
- Composite foreign keys include
tenant_id, so a relationship between two rows of different tenants cannot exist.
Every store query also carries explicit tenant and workspace predicates; row-level security is defense in depth on top.
Isolation tiers
| Tier | Where tenant data lives |
|---|---|
| Standard | A shared tenant database, isolated by row-level security. |
| Dedicated | A database of its own (on the same or a separate server), selected by the operator when the tenant is provisioned. |
The API routes every request to the tenant's placement automatically; clients see no difference. While a dedicated database is being provisioned or migrated, that tenant's requests answer 503 PLACEMENT_UNAVAILABLE with Retry-After: 60 — other tenants are unaffected.
Sharing across workspaces
Workspaces are the unit of sharing. The only paths by which knowledge crosses a workspace boundary are deliberate:
- Tenant conventions — facts established independently in at least two workspaces become candidates that a tenant administrator approves. See Runs and consolidation.
tenantvisibility — a memory written or shared at tenant level (requires thepromotecapability) is visible to every agent in the tenant.- Tenant floors and platform memory — governance content managed by tenant administrators and the platform operator.
Nothing ever crosses a tenant boundary. There is no promotion from tenant to platform.
Tenant lifecycle
A tenant's status affects API calls:
| Status | Effect on the API |
|---|---|
| Active, Trial, Grace period | Normal operation. |
| Suspended | Requests are refused with 403 TENANT_SUSPENDED (with tenantStatus). |
| Pending deletion | Reads (and export) keep working; every mutating call answers 403 TENANT_SUSPENDED. |
Operators can also put a tenant into read-only maintenance (mutations answer 503 TENANT_MAINTENANCE with Retry-After: 300) or switch off its API access (403 API_ACCESS_DISABLED).
Plans and quotas
Plans set limits per tenant. Exceeding one answers 429 QUOTA_EXCEEDED with Retry-After and the resource, limit and current values. Limits include:
- Monthly operations — every call to the
/v1/memoryendpoints (and every MCP tool call) is metered; console reads are not. - Stored records — workspace memories, episodes, procedures and documented files.
- Active API keys and webhook subscriptions.
Features a plan doesn't include answer 403 ENTITLEMENT_REQUIRED. Request-rate limits are separate and per tenant — see Rate limits.
Deleting a tenant's data
- One memory —
DELETE /v1/memory/{id}runs the erasure cascade; see Updating and forgetting. - A workspace or a whole tenant — tenant administrators can delete data from the console, and platform operators can purge a workspace or tenant. Purges are recorded in a ledger so erasure is tracked to completion.
Authentication
Workspace API keys, the built-in OAuth 2.1 server for MCP clients, and how credentials carry capabilities and agent bindings.
Security
The controls that protect memory in Agent Memory — credentials, isolation, least privilege, content screening, secrets handling, erasure and webhook delivery.