How to Give Your AI a Human Memory with Supermemory

TL;DR / Quick Answer

Supermemory gives AI apps a memory and context layer, but memory systems are harder to debug than normal CRUD APIs. A reliable workflow is to test Supermemory ingestion, profile, and search paths directly, isolate containerTag values per user or project, and verify async behavior before trusting what an MCP client or agent shows in chat.

Try Apidog today

Introduction

AI memory bugs rarely look like standard API bugs. The request succeeds, but the agent recalls the wrong fact. A profile is empty for one user and overloaded for another. Search works in a notebook but becomes noisy in production. By the time someone notices, the issue may be hidden behind an SDK wrapper, an MCP client, and a prompt.

Supermemory is worth testing carefully because it positions itself as a memory and context layer for AI apps. It supports memory extraction, user profiles, hybrid search, connectors, file processing, and an MCP server for clients like Cursor, Claude Code, VS Code, Windsurf, and Claude Desktop.

The repo shows quickstart methods such as:

client.add()
client.profile()
client.search.memories()

The hosted API docs expose endpoints such as:

POST /v3/documents
POST /v3/search
POST /v4/profile
POST /v3/documents/file

That split matters. Your team does not just need “memory.” You need to inspect what was ingested, how it was scoped, what a profile call returns, and whether hybrid search is retrieving the right mix of document context and personal context.

A shared API workflow tool helps because you can keep auth and containerTag values in environments, save exact requests, add assertions, and turn a fragile memory experiment into a repeatable workflow.

Why AI Memory APIs Are Harder to Debug Than Standard APIs

A normal API bug is usually visible quickly. The response is wrong, the status code is wrong, or the request never reaches the service.

Memory systems are different. You can get a 200 response and still have incorrect product behavior.

The real questions are:

• Did the right content get ingested?
• Was it attached to the correct user or project scope?
• Did profile extraction finish before the next request?
• Did the search query use the right mode and threshold?
• Did a newer fact override an older one?
• Did the MCP client pass the same context boundary used in API tests?

Supermemory includes several moving parts:

• memory extraction from conversations and documents
• user profiles with static and dynamic context
• hybrid search across memories and documents
• connectors such as Google Drive, Gmail, Notion, OneDrive, GitHub, and web crawling
• file processing for PDFs, images, videos, and code
• an MCP server for AI clients

That means you are debugging state, timing, and retrieval quality at the same time.

A typical flow looks like this:

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

If you only test from the chat layer, you cannot tell which stage is wrong. Testing the underlying API flow first lets you isolate each step.

What Supermemory Gives You Out of the Box

The Supermemory repo shows the main developer-facing primitives:

• client.add() to store content
• client.profile() to fetch a user profile and optional search results
• client.search.memories() for hybrid search
• document upload support
• framework integrations for tools like Vercel AI SDK, LangChain, LangGraph, OpenAI Agents SDK, Mastra, Agno, and n8n
• an MCP endpoint for assistants such as Claude, Cursor, and VS Code

The REST API is versioned and split by capability. Public docs show examples such as:

POST /v3/documents
POST /v3/search
POST /v4/profile
POST /v3/documents/file

Your first debugging task is not to learn every feature. It is to lock down the exact flow your app uses.

For most teams, that flow is:

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

If you cannot repeat those three steps with the same inputs and expected outputs, your AI memory layer is still in prototype mode.

Build a Reliable Supermemory Test Workflow

Start by testing Supermemory directly before adding wrappers, chat interfaces, or agent orchestration.

Step 1: Define your scope strategy first

Supermemory’s docs and README emphasize containerTag or containerTags. Treat this as a core design decision.

A clean scope plan could be:

user tag:     user_123
project tag:  project_alpha
environment:  staging or production

Use separate values for staging and production. If you reuse tags across unrelated users or projects, profile and search results will become noisy.

Step 2: Ingest one known fact set

Start with a small, obvious payload. Do not begin with a giant PDF dump or full connector sync.

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"
    }
  }'

The important part is not the content itself. It is that every field is deliberate:

• known fact
• known user scope
• known project scope
• known customId
• known metadata

That gives you a baseline for later assertions.

Step 3: Query profile after ingestion

The profile endpoint returns a condensed view of the user. Test it separately from search.

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?"
  }'

The public docs show a response shape that includes:

• profile.static
• profile.dynamic
• searchResults

Inspect that response before saying “the agent remembers correctly.”

Step 4: Test search separately

Search is not the same as profile retrieval. If your app uses retrieval for grounding or answer generation, test it independently.

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
  }'

Supermemory’s docs recommend searchMode: "hybrid" when you want both memory and document context in one query. That is a practical default for AI assistants because real user answers often need both personal context and knowledge-base context.

Step 5: Check async assumptions

Supermemory does asynchronous processing for document and file flows. The docs show queued processing and status-based behavior for uploads.

This creates an easy bug pattern:

1. Ingest content.
2. Query profile immediately.
3. Get a thin or incomplete result.
4. Blame retrieval quality instead of timing.

If an endpoint is async, your test workflow should include waits or polling before validating profile and search behavior.

Turn Supermemory into a Repeatable API Workflow

Raw curl is useful for first checks, but memory APIs need repeatability. You want the same requests, variables, and assertions available to the whole team.

Step 1: Create a Supermemory environment

Create environment 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

This lets you switch users, projects, and workspaces without editing request bodies by hand.

Step 2: Build the ingest request

Create a request:

Method: POST
URL: {{base_url}}/v3/documents
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"
  }
}

Add 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 a queued response, treat that as signal. The next request should account for processing time.

Step 3: Build the profile request

Create a second request:

Method: POST
URL: {{base_url}}/v4/profile
Authorization: Bearer {{supermemory_api_key}}
Content-Type: application/json

Body:

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

Helpful 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);
});

This separates three cases quickly:

• ingestion did not happen
• ingestion happened but processing is incomplete
• profile exists but query or scope is wrong

Step 4: Build the search request

Add a third request for retrieval quality.

Body:

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

Good checks include:

• response time is within your team’s target
• at least one result is returned
• the top result includes the expected topic
• no unrelated user or project context appears

Example assertion:

pm.test("Top result mentions expected topic", function () {
  const json = pm.response.json();
  const serialized = JSON.stringify(json).toLowerCase();

  pm.expect(serialized).to.include("rate limits");
});

A shared API workflow makes it easier to compare variants:

• searchMode: "hybrid" versus memory-only behavior
• one containerTag versus another
• lower threshold versus higher threshold
• short query versus noisy natural-language query

That comparison is harder to maintain with one-off shell commands.

Step 5: Turn the requests into a scenario

Create a scenario that runs:

1. Add content.
2. Wait or poll if processing is async.
3. Query profile.
4. Query search.
5. Assert that profile and search both reflect the new fact set.

That gives you a regression test for memory behavior, not just endpoint availability.

Step 6: Document the workflow for the team

Memory bugs cross team boundaries. Backend may think retrieval works. QA may see noisy search. Product may think the assistant is hallucinating.

A documented workflow should show:

• exact request used to ingest memory
• scope boundary for user and project
• profile response shape
• search response shape
• assertions expected to pass

This turns memory debugging into a repeatable engineering process instead of a chat transcript investigation.

Where MCP Fits in the Debugging Loop

Supermemory includes a quick MCP install path and shows a hosted MCP server URL. That is useful for connecting Claude, Cursor, Windsurf, or VS Code, but MCP should not be the first place you debug memory issues.

If your assistant remembers the wrong thing, work in this order:

1. Check direct API requests in your API workspace.
2. Verify the exact containerTag or project boundary.
3. Confirm the content was ingested and processed.
4. Verify profile and search results directly.
5. Then inspect the MCP client configuration.

MCP adds another abstraction layer. A bad recall result could come from:

• wrong API key or auth mode
• wrong scope boundary
• stale or incomplete ingestion
• client-specific tool-calling behavior
• prompt instructions that misuse memory output

Supermemory’s README shows a manual MCP config pattern like this:

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

If that client path behaves strangely, reproduce the underlying memory behavior through the HTTP API first.

Advanced Techniques and Common Mistakes

1. Mixing scopes

If you reuse the same containerTag across unrelated users, the memory system will look noisy even when it is doing exactly what you asked.

Use explicit tags:

user_123
project_alpha
env_staging

Avoid vague shared tags unless you intentionally want shared memory.

2. Testing only the happy path

Also test:

• profile query before ingestion
• profile query immediately after ingestion
• search with a weak query
• search with the wrong project tag
• uploads that are still processing

These cases reveal scope, timing, and retrieval issues earlier.

3. Treating profile and search as interchangeable

They solve different problems:

• Profile: condensed user context
• Search: retrieval over memories and documents

Your app may need one, the other, or both.

4. Ignoring version differences

The repo README focuses on SDK methods. The docs show versioned HTTP endpoints like /v3 and /v4.

Lock the exact API version your team is shipping against, then mirror that in your API test workflow.

5. Skipping update and contradiction tests

Memory systems are useful because users change over time.

Test what happens when a newer fact contradicts an older one. For example:

Old fact: User prefers JavaScript.
New fact: User now prefers TypeScript for backend work.

Then verify whether profile and search behavior reflects the newer fact appropriately.

Alternatives and Comparison

There are three common ways to work with Supermemory during development:

Approach	Good for	Weak point
SDK only	Fast local prototyping	Harder to inspect exact HTTP behavior
curl and scripts	Low-friction endpoint checks	Hard to reuse, share, and compare over time
Shared API workflow	Team-ready debugging, assertions, docs, scenarios	Requires setup up front

A tool like Apidog fits beside Supermemory rather than replacing it. Supermemory provides the memory engine. The workflow layer gives you a repeatable way to validate the engine’s API behavior before that behavior becomes part of a larger AI product.

Real-World Use Cases

A support copilot needs to remember a user’s preferred stack, active incident, and recent account context. Supermemory can hold that memory, while an API workflow validates that profile and search queries return the right facts for the right user.

A product team using Cursor or Claude Code with MCP wants assistant memory across long projects. Before trusting the chat experience, the team should verify ingestion, scope boundaries, and retrieval quality directly against the API.

A platform team syncing docs from GitHub or Notion needs to confirm hybrid search behavior before enabling it for internal agents. A structured test workflow helps compare document-heavy queries against memory-heavy queries in the same suite.

Conclusion

Supermemory is compelling because it treats memory as infrastructure, not a thin vector-search demo. The repo and docs show a broad platform: ingestion, profiles, search, connectors, file handling, framework integrations, and MCP support.

The catch is that memory behavior is easy to misread if you only test from the chat surface.

Before shipping an agent or MCP-powered workflow:

1. Ingest a known fact set.
2. Scope it with deliberate containerTag values.
3. Query profile.
4. Query search.
5. Validate async behavior.
6. Save the workflow with assertions.

That gives your team a repeatable way to catch the memory bugs that are hardest to explain later.

FAQ

What is Supermemory used for?

Supermemory is used to add memory, profiles, search, connectors, and context retrieval to AI apps and agents. The public repo and docs position it as a memory and context layer rather than only a vector search tool.

Does Supermemory have a REST API?

Yes. The public docs show versioned HTTP endpoints for documents, search, profile retrieval, and file uploads. The README also exposes SDK methods that map to those capabilities.

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

Because a successful response does not guarantee correct user-facing behavior. You also need to validate scope, timing, profile extraction, retrieval quality, and how the agent consumes those outputs.

What should I test first in Supermemory?

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

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

Yes. It helps you validate the underlying HTTP API behavior before debugging the assistant client. That makes it easier to tell whether the problem is in memory retrieval or the MCP layer above it.

What is the most important Supermemory parameter to get right?

containerTag or containerTags is one of the most important because it controls how memories are grouped and retrieved. A weak tagging strategy creates noisy results even if ingestion and search both succeed.