How to Give Your AI a Human Memory with Supermemory

TL;DR / Quick Answer

Supermemory provides a memory and context layer for AI applications, but its memory systems are more complex to debug than standard CRUD APIs. The best practice is to directly test Supermemory’s ingestion, profile, and search paths, use distinct containerTag values per user or project, and validate asynchronous behaviors before relying on outputs from an MCP client or agent chat.

Try Apidog today

Introduction

AI memory bugs can be subtle: requests may succeed, but the agent might recall wrong facts, profiles may be empty or overloaded, and searches might behave inconsistently between dev and production. These issues often hide behind SDK wrappers, MCP clients, and prompts.

supermemory addresses this by offering a comprehensive memory and context layer for AI, with features like memory extraction, user profiles, hybrid search, connectors, file processing, and an MCP server for popular clients (Cursor, Claude Code, VS Code, etc.). The repository includes quickstart methods (client.add(), client.profile(), client.search.memories()), and the hosted API docs expose endpoints (POST /v3/documents, POST /v3/search, POST /v4/profile).

For effective debugging, you must go beyond simply storing memories. Inspect the ingestion results, grouping logic, profile outputs, and verify that hybrid search pulls the right blend of document and personal context.

💡 Tip: Use a shared API workflow tool to manage authentication and containerTag values, save exact requests, add assertions, and create repeatable, documented test workflows. Apidog is a practical option to avoid building a test harness from scratch.

Why AI Memory APIs Are Harder to Debug Than Standard APIs

Standard API bugs are obvious: incorrect responses, bad status codes, or failed requests.

AI memory systems are different. You might get a 200 response, but still get incorrect product behavior. Key questions to check:

• Was the correct content ingested?
• Was it correctly associated with the user/project scope?
• Did profile extraction complete before the next step?
• Did the search use the right mode and threshold?
• Did a newer fact overwrite an older one?
• Did the MCP client maintain the same context boundaries as your API tests?

Supermemory tackles these issues by handling:

• Memory extraction (from conversations, documents)
• User profiles (static/dynamic context)
• Hybrid search (memories + docs)
• Connectors (Google Drive, Gmail, Notion, OneDrive, GitHub, web crawling)
• File processing (PDF, images, video, code)
• MCP server for AI clients

You’re debugging state, timing, and retrieval—often all at once.

Typical flow:

App or MCP client -> Supermemory ingest -> extraction/profile update -> search/profile call -> agent prompt -> user-visible answer

Testing only at the chat/UI layer hides where things break. Testing the underlying API flow in a shared workspace lets you isolate each stage.

What Supermemory Gives You Out of the Box

The supermemory repo highlights main developer primitives:

• client.add() – Store content
• client.profile() – Fetch user profile (+ optional search)
• client.search.memories() – Hybrid search
• Document upload support
• Framework integrations (Vercel AI SDK, LangChain, LangGraph, OpenAI Agents SDK, etc.)
• MCP endpoint for assistants (Claude, Cursor, VS Code)

REST API endpoints are versioned and separated by function:

• POST /v3/documents – Ingest content
• POST /v3/search – Search
• POST /v4/profile – Profile retrieval
• POST /v3/documents/file – File uploads

Your first debugging task: lock in the exact workflow your app uses—don’t try to learn every feature at once.

Typical flow:

1. Send content into Supermemory
2. Query profile or search with stable user/project scope
3. Confirm what the app/agent should see next

If you can’t reliably repeat those three steps with known inputs/outputs, your AI product isn’t production-ready.

Build a Reliable Supermemory Test Workflow

Test Supermemory’s API directly before adding custom wrappers, chat interfaces, or orchestration.

Step 1: Plan Your Scope Strategy

Supermemory’s docs emphasize containerTag/containerTags—treat this as a core design choice.

Good scope plan:

• Tag per user, e.g. user_123
• Tag per project, e.g. project_alpha
• Separate tags for staging and production

Failing to plan scope yields noisy, unreliable results.

Step 2: Ingest a Known Fact Set

Start with a small, clear payload—not a huge PDF or full connector sync.

Direct API Example:

curl https://api.supermemory.ai/v3/documents \
  --request POST \
  --header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "content": "User prefers TypeScript, ships API backends, and is debugging rate limits this week.",
    "containerTags": ["user_123", "project_alpha"],
    "customId": "session-001",
    "metadata": {
      "source": "support_chat",
      "team": "platform"
    }
  }'

Key: Use deliberate, controlled values for every field.

Step 3: Query Profile Post-Ingestion

The profile endpoint offers a condensed, user-centric view of memory.

curl https://api.supermemory.ai/v4/profile \
  --request POST \
  --header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "containerTag": "user_123",
    "q": "What stack does this user prefer?"
  }'

Response includes:

• profile.static
• profile.dynamic
• searchResults

Inspect this before trusting that the agent’s recall is correct.

Step 4: Test Search Independently

Profile ≠ Search. If your app uses retrieval for grounding/answer generation, test search directly.

curl https://api.supermemory.ai/v3/search \
  --request POST \
  --header "Authorization: Bearer $SUPERMEMORY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "q": "What is the user working on?",
    "containerTag": "user_123",
    "searchMode": "hybrid",
    "limit": 5
  }'

Use searchMode: "hybrid" for combined memory + document context (recommended default).

Step 5: Check Asynchronous Processing

Supermemory processes documents/files asynchronously. If you query too soon after upload, results may be incomplete.

Common pitfall:

1. Ingest content
2. Query profile immediately
3. Get incomplete result
4. Blame memory engine (instead of timing)

Solution: Add short waits or polling for async endpoints.

Turn Supermemory into a Repeatable Test Workflow

Using a shared API workflow tool (like Apidog) increases repeatability and documentation.

Step 1: Create a Supermemory Environment

Define variables:

base_url = https://api.supermemory.ai
supermemory_api_key = sm_your_api_key
user_tag = user_123
project_tag = project_alpha
custom_id = session-001

Swap users/projects/workspaces without hand-editing requests.

Step 2: Build the Ingest Request

Request:

• Method: POST
• URL: {{base_url}}/v3/documents
• Headers:
  • Authorization: Bearer {{supermemory_api_key}}
  • Content-Type: application/json
• Body:

{
  "content": "User prefers TypeScript, ships API backends, and is debugging rate limits this week.",
  "containerTags": ["{{user_tag}}", "{{project_tag}}"],
  "customId": "{{custom_id}}",
  "metadata": {
    "source": "api_workflow_test"
  }
}

Assertions:

pm.test("Status is success", function () {
  pm.expect(pm.response.code).to.be.oneOf([200, 201, 202]);
});

pm.test("Response contains memory id", function () {
  const json = pm.response.json();
  pm.expect(json.id).to.exist;
});

If the service returns queued, your next request should wait for processing to complete.

Step 3: Build the Profile Request

Request:

• Method: POST
• URL: {{base_url}}/v4/profile
• Body:

{
  "containerTag": "{{user_tag}}",
  "q": "What stack does this user prefer?"
}

Assertions:

pm.test("Profile payload exists", function () {
  const json = pm.response.json();
  pm.expect(json.profile).to.exist;
});

pm.test("Static or dynamic profile content returned", function () {
  const json = pm.response.json();
  const staticItems = json.profile?.static || [];
  const dynamicItems = json.profile?.dynamic || [];
  pm.expect(staticItems.length + dynamicItems.length).to.be.above(0);
});

Quickly separates: ingestion failures, incomplete processing, or scope/query issues.

Step 4: Build the Search Request

Request body:

{
  "q": "What is the user debugging?",
  "containerTag": "{{user_tag}}",
  "searchMode": "hybrid",
  "limit": 5
}

Checks:

• Response timing within target
• At least one result returned
• Top result matches expected topic
• Correct user/project scope, no data leaks

A shared workflow tool lets you clone/compare:

• searchMode: "hybrid" vs. memory-only
• Different containerTag values
• Varying thresholds or queries

Step 5: Chain Requests into a Scenario

Build a test scenario:

1. Add content
2. Wait (if async)
3. Query profile
4. Query search
5. Assert both reflect the new fact set

Provides a reusable regression test for memory behavior.

Step 6: Document the Workflow for the Team

Memory bugs often cross team boundaries. Publishing your workflow in Apidog lets everyone see:

• Exact ingest request
• Scope boundaries
• Profile/response shapes
• Team assertions

Where MCP Fits in the Debugging Loop

Supermemory supports quick MCP install and a hosted server URL for fast integration with Claude, Cursor, Windsurf, VS Code, etc. However, do not start debugging here.

Debug in this order:

1. Direct API requests in your workspace
2. Validate containerTag/project scope
3. Confirm ingestion + processing
4. Check profile/search results
5. Only then move to MCP client config

MCP is an additional abstraction. A recall issue could be from:

• Wrong API key/auth
• Incorrect scope
• Stale/incomplete ingestion
• Client-side tool-calling
• Prompt instructions using memory output incorrectly

Manual MCP config example:

{
  "mcpServers": {
    "supermemory": {
      "url": "https://mcp.supermemory.ai/mcp"
    }
  }
}

If the client path fails, always reproduce the underlying behavior via HTTP API first.

Advanced Techniques and Common Mistakes

Top production mistakes:

1. Mixing scopes

Reusing the same containerTag for different users leads to noisy data—even if the engine works correctly.

2. Only Testing the Happy Path

Also test:

• Profile query before ingestion
• Profile query immediately after ingestion
• Weak search queries
• Incorrect project tags
• Uploads still processing

3. Treating Profile and Search as Interchangeable

They solve different problems: profile = condensed context, search = retrieval. Use both as needed.

4. Ignoring Version Differences

SDK methods vs. versioned HTTP endpoints (/v3, /v4). Lock API versions and mirror them in your test workflow.

5. Skipping Update and Contradiction Tests

Test how the system handles updates and contradictions (e.g., user preference changes).

Alternatives and Comparison

Three main ways to work with Supermemory:

Approach	Good for	Weak point
SDK only	Fast local prototyping	Harder to inspect HTTP behavior
cURL and scripts	Low-friction endpoint checks	Hard to reuse/share/compare over time
Shared API workflow	Team debugging, docs, asserts	Requires some setup

A tool like Apidog complements Supermemory: the engine provides memory, the workflow tool makes API validation repeatable and transparent.

Real-World Use Cases

• Support copilot: Remembers user’s stack, incidents, account context. Supermemory holds memory; workflow tool validates queries return correct facts.
• Product team (Cursor/Claude Code): Wants assistant memory for long projects. Validate ingestion, scope, and retrieval via API before trusting chat.
• Platform team (GitHub/Notion sync): Needs to check hybrid search before enabling for internal agents. Test workflows help compare document-heavy and memory-heavy queries.

Conclusion

Supermemory treats memory as infrastructure: ingestion, profiles, search, connectors, file handling, framework integrations, MCP support. Memory behavior is easy to misread if you only test via chat layers.

Testing at the API level before shipping agents or MCP-powered workflows helps catch the hardest-to-debug issues. To save requests, add assertions, and share workflows, Apidog is a strong fit for this validation layer.

---

FAQ

What is Supermemory used for?

Supermemory adds memory, profiles, search, connectors, and context retrieval to AI apps and agents. It's designed as a memory/context layer, not just a vector search tool.

Does Supermemory have a REST API?

Yes. Versioned HTTP endpoints cover documents, search, profile retrieval, and file uploads. The SDK maps to these endpoints.

Why is an AI memory API harder to debug than a normal API?

A successful response doesn’t guarantee correct behavior. You must validate scope, timing, profile extraction, retrieval quality, and how outputs are consumed by the agent.

What should I test first in Supermemory?

Start with one ingest request, one profile request, and one search request for a single user or project scope. Establish a baseline before adding connectors/files/MCP clients.

Can an API workflow tool help if my app uses MCP?

Yes. It lets you validate underlying HTTP API behavior before debugging the assistant client, making it easier to isolate memory retrieval vs. MCP issues.

What is the most important Supermemory parameter to get right?

containerTag (or containerTags) is critical—it controls grouping and retrieval of memories. A poor tagging strategy creates noisy results, even if ingestion/search succeed.