Container tags: organizing and isolating memories

What a container tag is

A container tag is the primary way you organize and isolate memories in Supermemory. Each tag is its own namespace: memories written under user_alex are stored and searched independently of memories written under user_jordan, with no shared index to filter through.

Because a tag is a hard boundary rather than a filter, it is the right tool for answering "who owns this data?" Every search is scoped to a single container tag.

Creating a tag

You do not provision tags ahead of time. The first write with a new tag creates the container automatically.

await client.add({
  content: "User preferences data",
  containerTag: "user_alex",
});

Use the singular containerTag field. The older plural containerTags array is deprecated for new integrations.

Naming rules

• Maximum 100 characters.
• Letters, numbers, hyphens, underscores, and colons only (pattern ^[a-zA-Z0-9_:-]+$).

Common patterns that map to a real tenancy model:

• user_{userId} for consumer apps
• org_{orgId} for B2B SaaS
• org:{orgId}:user:{userId} for hierarchical tenancy
• project_{projectId} for workspace-scoped apps

Isolating memories per end user

For most applications, one container tag per end user is the standard pattern and is all you need. Derive the tag from an identifier you already trust — your internal user ID — rather than something a user can change, such as an email address.

Container tags also act as an authorization checkpoint. API keys can be scoped to specific tags, and out-of-scope requests are rejected with a 403 rather than silently returning nothing.

Sharing one tag across several agents or clients

This is supported and is the intended design. A container tag is a property of the data, not of the client that wrote it. Any agent, plugin, or integration authenticating to the same organization and using the same tag reads and writes the same pool of memories — so a web app, a Slack bot, and an MCP client can all contribute to and recall from one user's memory.

If you instead want a client to have its own separate pool, give it its own tag.

Container tags versus conversation IDs

Do not create a container tag per conversation. Tags are isolation boundaries; a per-conversation tag would prevent memories from one conversation being recalled in the next, which defeats the point of persistent memory.

Keep the tag at the tenant level (usually the user) and put the conversation or session ID in metadata, then filter on it at search time with AND/OR conditions. The general rule: anything you want to filter by is metadata, and anything that defines who may see the data is a container tag.

How many tags is too many

Container tags are designed for multi-tenancy, so one tag per end user is expected and normal — thousands of user tags is an ordinary shape, not a warning sign. The documentation does not publish a maximum tag count. If you are planning for an unusually large or unusual tag layout, check the details with support before you build around it.

What does cause problems is using tags for things metadata should handle — a tag per team, per category, or per conversation. That fragments memory into pools that can never be searched together.

Finding and listing your tags

There is no documented endpoint that enumerates every container tag in an organization. In practice:

• Your own system is the source of truth. Since tags are derived from your user or tenant IDs, list them from your database.
• To inspect one known tag, call GET /v3/container-tags/{containerTag}. It returns the tag's display name, its custom context prompt, and its profile bucket configuration. Update the same fields with PATCH /v3/container-tags/{containerTag}.
• To see what a tag actually holds, call POST /v3/documents/list.

If you have lost track of which tags exist — for example after a migration — support can help you recover the picture.

Renaming, merging, and deleting tags

There is no rename operation. Renaming is done as a merge into the tag you want to keep.

Merge: POST /v3/container-tags/merge takes exactly two tags in containerTags plus a targetContainerTag. Documents from the source tags are reassigned to the target, and the source tags are deleted once the merge succeeds. The call returns 202 with a mergeId because the work is queued; poll GET /v3/container-tags/merge/{mergeId} for progress. Merges are limited to two tags at a time, so consolidating several tags means running several merges.

Delete: DELETE /v3/container-tags/{containerTag} removes the tag along with all of its documents and memories, and returns counts of what was deleted. This is permanent.

Both merging and deleting a container tag require organization owner or admin permissions; other members receive a 403.

Cleaning up tag sprawl

1. List the tags you believe should exist from your own user or tenant records.
2. For each questionable tag, call POST /v3/documents/list to see what it actually contains before touching it.
3. Merge tags that represent the same tenant under different names into the one you want to keep.
4. Delete tags belonging to tenants that no longer exist.
5. Move any dimension that is really a filter — team, category, conversation — into metadata so the sprawl does not return.

Because merges and deletes are irreversible, verify contents first. If a tag holds production data you cannot afford to lose, talk to support before running the cleanup.

Contacting support

Reach out at support@supermemory.com for tag layouts you are unsure about, merges involving more than a couple of tags, or recovering an inventory of existing tags. Include your organization ID, the exact container tags involved, the target tag if you are merging, and the mergeId if a merge is already running.