Support global container tag override for API-key-scoped tenancy

[ramarivera]

Problem

When using an API key scoped to a specific container (e.g., "ramiro"), the plugin's getContainerTag() function auto-derives a hash-based tag (claudecode_project_<sha256>) that doesn't match the API key's scope, causing 400 Invalid container tag errors on every operation.

The only workaround is creating .claude/.supermemory-claude/config.json with personalContainerTag in every single project. This is tedious and easy to forget — the first memory save in any new project always fails until you remember to create the config.

Current resolution order

project config (.claude/.supermemory-claude/config.json) → git-path hash fallback

Proposed resolution order

project config → environment variable → global settings file → git-path hash fallback

Specifically:

1. Project config — .claude/.supermemory-claude/config.json → personalContainerTag (existing, unchanged)
2. Environment variable — e.g., SUPERMEMORY_CONTAINER_TAG or SUPERMEMORY_PERSONAL_CONTAINER_TAG (new)
3. Global settings file — ~/.supermemory-claude/settings.json → personalContainerTag (new)
4. Git-path hash — claudecode_project_${sha256(basePath)} (existing fallback)

The code change in container-tag.js would be minimal:

function getContainerTag(cwd) {
  const projectConfig = loadProjectConfig(cwd);
  if (projectConfig?.personalContainerTag) return projectConfig.personalContainerTag;
  
  // NEW: check env var
  if (process.env.SUPERMEMORY_CONTAINER_TAG) return process.env.SUPERMEMORY_CONTAINER_TAG;
  
  // NEW: check global settings
  const globalSettings = loadGlobalSettings();
  if (globalSettings?.personalContainerTag) return globalSettings.personalContainerTag;
  
  // Existing fallback
  const basePath = getGitRoot(cwd) || cwd;
  return `claudecode_project_${sha256(basePath)}`;
}

Cross-integration concern: unified container tag support

This isn't just a Claude Code plugin issue — Supermemory has integrations across multiple platforms:

• claude-supermemory (Claude Code plugin)
• supermemory-mcp (MCP server — used by Claude Desktop, Cursor, etc.)
• opencode-supermemory (OpenCode plugin)
• openclaw-supermemory (OpenClaw / Clawdbot)
• Notion integration
• Any future integrations

All of these would benefit from a consistent, cross-integration container tag configuration mechanism. When an API key is scoped to a container (e.g., for multi-tenancy or personal branding), every integration should respect the same tag without requiring per-integration, per-project configuration.

Recommendation

Consider standardizing across all integrations:

1. SUPERMEMORY_CONTAINER_TAG environment variable — works everywhere, set once in shell profile, respected by all integrations
2. Global config file (e.g., ~/.config/supermemory/config.json or ~/.supermemory/config.json) — a single file that all integrations read for shared settings like container tag, API URL, debug mode
3. Per-integration overrides remain available for cases where you genuinely want different containers per tool

This enables multi-tenancy use cases like:

• Personal vs. work memory separation via scoped API keys
• Team-shared memory pools where all team members' tools use the same container
• Custom container naming instead of opaque hashes

Environment

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

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

[Dhravya]

@claude can you implement? I like the SUPERMEMORY_CONTAINER_TAG approach. @Prasanna721 what do you think?

[claude]

Claude finished @Dhravya's task in 1m 55s —— View job • claude/issue-29-20260216-2346 • Create PR ➔

---

Implementation complete ✓

• Read CLAUDE.md for repo-specific instructions
• Locate and read container-tag.js
• Understand current implementation
• Implement environment variable support (SUPERMEMORY_CONTAINER_TAG)
• Implement global settings file support
• Create loadGlobalSettings() function
• Commit and push changes
• Provide PR creation link

Changes made

I've successfully implemented the global container tag override feature with the following changes:

1. Created src/lib/global-settings.js - New module for managing global settings

   • Reads/writes from ~/.supermemory-claude/settings.json
   • Provides loadGlobalSettings() and saveGlobalSettings() functions
   • Mirrors the structure of the existing project-config.js

2. Updated src/lib/container-tag.js - Implemented the new resolution order:

   • ✅ Project config (.claude/.supermemory-claude/config.json → personalContainerTag)
   • ✅ Environment variable (SUPERMEMORY_CONTAINER_TAG)
   • ✅ Global settings (~/.supermemory-claude/settings.json → personalContainerTag)
   • ✅ Git-path hash fallback (existing behavior)

Usage

Users can now set their container tag in three ways:

Environment variable (recommended for single global tag):

export SUPERMEMORY_CONTAINER_TAG="ramiro"

Global settings file (~/.supermemory-claude/settings.json):

{
  "personalContainerTag": "ramiro"
}

Per-project config (.claude/.supermemory-claude/config.json):

{
  "personalContainerTag": "work-project"
}

This solves the 400 Invalid container tag errors when using API keys scoped to specific containers, without requiring per-project configuration.

--- |

[Prasanna721]

We have plugin specific API keys for the ClaudeCode, Openclaw, Opencode plugins
The reason we didn't implement global override for containerTags (personal, repo), each claude code sessions generate memories about specific project and global override will tend to store all the memories in a same containerTag which corrupt the context Claudecode sessions which will inturn cause a bad experience and also will not respect project level overrides

@ramarivera can i know the usecase for this global specification?