Support global container tag override across all integrations for API-key-scoped tenancy

[ramarivera]

Problem

When using an API key scoped to a specific container (e.g., "ramiro"), each Supermemory integration (Claude Code, MCP, OpenCode, OpenClaw, etc.) auto-derives its own hash-based container tag that doesn't match the API key's scope, causing 400 Invalid container tag errors.

The only workaround today is configuring the container tag per-project, per-integration — e.g., in claude-supermemory, creating .claude/.supermemory-claude/config.json with personalContainerTag in every single project. This is tedious, error-prone, and doesn't scale across integrations.

Affected integrations

• claude-supermemory — Claude Code plugin (also filed as Support global container tag override for API-key-scoped tenancy claude-supermemory#29)
• supermemory-mcp — MCP server (Claude Desktop, Cursor, etc.)
• opencode-supermemory — OpenCode plugin
• openclaw-supermemory — OpenClaw / Clawdbot
• Notion integration and any future integrations

Proposal: unified container tag resolution

Standardize a cross-integration container tag resolution order that all Supermemory integrations follow:

1. Per-project config (integration-specific, existing)
2. SUPERMEMORY_CONTAINER_TAG environment variable (NEW — set once, works everywhere)
3. Global config file (NEW — e.g., ~/.config/supermemory/config.json)
4. Integration-specific fallback (existing hash-based defaults)

1. Environment variable (highest impact, lowest effort)

A single SUPERMEMORY_CONTAINER_TAG environment variable, set once in the user's shell profile, would be respected by every integration automatically. This is the most impactful change:

# Set once in ~/.bashrc / ~/.zshrc / nushell env.nu / etc.
export SUPERMEMORY_CONTAINER_TAG="ramiro"

2. Global config file

A shared config file that all integrations read:

// ~/.config/supermemory/config.json (XDG-compliant)
{
  "containerTag": "ramiro",
  "apiUrl": "https://api.supermemory.ai",
  "debug": false
}

3. Per-integration overrides remain

Existing per-project configs continue to take highest priority for cases where you genuinely want different containers per project.

Use cases this enables

• API-key-scoped tenancy — API keys scoped to a container work out of the box across all tools without per-project config
• Personal vs. work separation — Different API keys with different containers, switched via env var
• Team-shared memory pools — All team members' tools use the same container via shared env var
• Custom container naming — Human-readable names instead of opaque claudecode_project_<hash> tags

Example implementation (minimal)

For each integration's container tag resolution function:

function getContainerTag(cwd) {
  // 1. Per-project config (existing)
  const projectConfig = loadProjectConfig(cwd);
  if (projectConfig?.personalContainerTag) return projectConfig.personalContainerTag;
  
  // 2. Environment variable (NEW)
  if (process.env.SUPERMEMORY_CONTAINER_TAG) return process.env.SUPERMEMORY_CONTAINER_TAG;
  
  // 3. Global config (NEW)
  const globalConfig = loadGlobalConfig(); // reads ~/.config/supermemory/config.json
  if (globalConfig?.containerTag) return globalConfig.containerTag;
  
  // 4. Fallback (existing)
  return deriveDefaultTag(cwd);
}

Environment

• claude-supermemory v0.0.2, macOS
• API key scoped to container "ramiro"
• Multiple projects, multiple integrations

🤖 This content was generated with AI assistance using Claude Opus 4.6.

[linear]

ENG-578