OpenClaw Supermemory Integration: 5 Real Config Traps and Solutions

I spent 3 days configuring the Supermemory plugin for a personal AI assistant project, and hit 5 distinct traps along the way. This is a record of my actual troubleshooting process — not the textbook flow from the documentation, but how I found the root causes when things went wrong.

Supermemory is an AI memory layer that keeps conversation context continuous across Telegram, WhatsApp, Discord, and Slack. It connects to OpenClaw via the MCP (Model Context Protocol). The official docs look clean, but there are 5 spots where configuration goes sideways in practice.

This article contains affiliate links. I earn a small commission at no extra cost to you.

Pitfall 1: API Key in the Wrong Place

**Symptoms**: After running openclaw supermemory setup and entering the API Key, the connection fails with 401 Unauthorized or Authentication failed.

Troubleshooting:

I created an API Key in the Supermemory console (app.supermemory.ai) and pasted it directly into the Authorization request header. But the error confused me for hours:

[error] Failed to connect: 401 Unauthorized
[error] Supermemory: authentication failed

**Root cause**: Supermemory API v3 uses the Authorization: Bearer YOUR_API_KEY format, but there are several common misplacements:

• `x-api-key: YOUR_API_KEY`
• `Authorization: API_KEY YOUR_API_KEY`
• Putting it in the URL parameter: `?api_key=YOUR_API_KEY`

Solution: Verify the correct API Key placement. According to the Supermemory official docs:

curl https://api.supermemory.ai/v3/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "user preferences", "containerTags": ["user_123"]}'

For MCP config files, the format is:

{
  "mcpServers": {
    "supermemory": {
      "url": "https://mcp.supermemory.ai/mcp",
      "headers": {
        "Authorization": "Bearer sm_your_api_key_here"
      }
    }
  }
}

**Note**: The headers field in MCP config is optional. If you're using OAuth, you don't need it.

Pitfall 2: OAuth vs API Key — Mixing Them Causes Conflicts

**Symptoms**: openclaw supermemory setup shows a successful connection, but searching memories returns empty results or a permission denied error.

Troubleshooting:

I initially configured using an API Key, then switched to OAuth (auto-renewing tokens) by running:

openclaw plugins install @supermemory/openclaw-supermemory
openclaw supermemory setup

This time I went through the OAuth authorization flow. After configuration, strange problems appeared — some containers were readable, others returned empty results.

Root cause: Supermemory's API Key and OAuth tokens correspond to different permission scopes. API Keys default to global permissions, while OAuth authorization limits scope based on what you approved. If your OAuth app only authorized certain containers, querying an unauthorized container with an API Key returns empty — not an error.

Solution:

1. Verify your API Key has permission to access the target container tag

2. If using OAuth, check whether the authorization scope includes the target container

3. Use openclaw supermemory profile to check current authorization status:

openclaw supermemory profile
# Example output:
# User: xxx@email.com
# Scopes: [read:memory, write:memory, read:profile]
# Active containers: ["personal", "work"]

Lesson: Don't mix authentication methods between development and production environments.

Pitfall 3: Container Tags Isolation — personal and work Don't Cross-Reference

Symptoms: Slack conversation records don't appear in Telegram; or Claude Code's memories mix with your personal memories in the same project.

Troubleshooting:

I configured a personal container for Telegram and WhatsApp, and a work container for Slack and Gmail. But every time I switched platforms, the AI said "I don't remember anything from before."

**Root cause**: Supermemory's containers are logically isolated. If you didn't specify a default container during openclaw supermemory setup, or didn't configure routing rules correctly in custom instructions, the AI randomly picks a container for storing memories.

Solution: Add custom instructions in the OpenClaw config to specify routing rules. Per Supermemory's official docs:

# Add to OpenClaw skill config or system prompt:
When the active channel is slack or gmail, always use the work container for storing and recalling memories.
When the active channel is telegram or whatsapp, always use the personal container.

# Prohibition rule:
# Never save anything to the twitter-bookmarks container — it is read-only

You can also specify containerTags during queries:

{
  "q": "project timeline",
  "containerTags": ["work"]  // Only search in work container
}

Verification commands:

openclaw supermemory search "project timeline" --container personal
# Search only in personal container

openclaw supermemory search "project timeline" --container work
# Search only in work container

Pitfall 4: Missing Project ID (x-sm-project header)

**Symptoms**: MCP connection succeeds, but returns 403 Forbidden with an invalid project ID message.

Troubleshooting:

I configured the API Key correctly per the official docs, but the MCP server returned a strange 403 error:

[error] Supermemory MCP: 403 Forbidden - Invalid project ID

But I never configured any project ID.

**Root cause**: The Supermemory MCP server requires an x-sm-project request header to distinguish between projects. When using an API Key directly instead of OAuth, you need to explicitly specify the project ID.

**Solution**: Add the x-sm-project header to your MCP config:

{
  "mcpServers": {
    "supermemory": {
      "url": "https://mcp.supermemory.ai/mcp",
      "headers": {
        "Authorization": "Bearer sm_your_api_key_here",
        "x-sm-project": "your-project-id"
      }
    }
  }
}

The Project ID is found in the developer console at app.supermemory.ai (console.supermemory.ai).

Verification command:

# Test if API Key has project permissions
curl https://api.supermemory.ai/v3/profile \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-sm-project: your-project-id"

Pitfall 5: Network / CORS Issues — Local Dev vs Cloud MCP

**Symptoms**: openclaw supermemory search times out locally, but the same MCP works fine on a server; or cross-origin requests get blocked.

Troubleshooting:

My dev environment was on a local machine (macOS), while OpenClaw runs on a VPS. Testing locally:

openclaw supermemory search "test query"
# Timeout: Request timed out after 30000ms

But the same command succeeded on the server.

**Root cause**: The Supermemory API endpoint https://mcp.supermemory.ai/mcp has rate limits and CORS policies. If your local network quality is poor, you'll hit frequent timeouts.

Solution:

1. Check local network connectivity to supermemory.ai:

curl -v https://mcp.supermemory.ai/mcp --max-time 10

2. If you need a self-hosted option, use the official Docker approach:

git clone https://github.com/supermemoryai/memorybench
cd memorybench
bun install
# Configure SUPERMEMORY_API_KEY
bun start

3. Or use OpenClaw's offline mode and only sync memories when needed.

Rate limit note: According to Supermemory's official pricing (app.supermemory.ai/billing), the free tier has request limits. For production environments, upgrading to the Scale plan is recommended.

Complete Configuration Checklist

If your OpenClaw Supermemory plugin still isn't working properly, check in this order:

# 1. Verify plugin installation
openclaw plugins list | grep supermemory

# 2. Verify API Key is valid
curl https://api.supermemory.ai/v3/profile \
  -H "Authorization: Bearer YOUR_API_KEY"

# 3. Verify MCP config is correct
cat ~/.openclaw/config.json | jq '.mcpServers.supermemory'

# 4. Test search functionality
openclaw supermemory search "test" --container personal

# 5. View detailed logs
openclaw supermemory --debug

Bottom Line

The 5 core traps in OpenClaw + Supermemory integration: Authorization header format, OAuth vs API Key scope differences, Container Tags routing rules, Missing x-sm-project header, and network CORS issues. Working through the checklist systematically, most problems get resolved.

If you're also configuring multi-platform memory for an AI assistant, start with one small container, verify the routing rules work, then expand to multi-platform.

👉 If config feels too complex, MiniMax's Token Plan lets you call various models on demand — testing showed it's simpler than local deployment.

👉 Join now: https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews