Migration from Supermemory

This guide is for teams that already have memory or retrieval in production and need a controlled move to Whisper.

The main goal is not “feature parity on paper.” The main goal is preserving the behaviors users actually notice:

• writes still feel fast
• fresh context is still visible quickly
• user and session boundaries do not drift
• relevance does not collapse during cutover

The mindset shift

When moving to Whisper, three ideas matter more than exact endpoint names:

1. Scope is explicit

Be precise about project, user_id, and session_id. If those identifiers drift during migration, the system will look worse than it is.

2. Async writes are normal

Whisper does not need to block on full processing before acknowledging a write. Use pending visibility to preserve continuity.

3. Retrieval and memory are separate jobs

Do not assume that replacing a write endpoint also replaces your retrieval strategy. Validate both sides independently.

A safe migration plan

Phase 1: map the current integration

Write down:

• where writes happen today
• where reads happen today
• what user identity you rely on
• whether session continuity matters in your product

Phase 2: create the Whisper project model

Choose the project boundary first. This is where many migrations go wrong.

Phase 3: replace one write path

Start with one memory write path, not the entire app.

Phase 4: replace one retrieval path

Validate retrieval against the same user and session scope used during the write test.

Phase 5: cut over gradually

Use a short dual-write or shadow-read window if the workflow is business-critical.

Minimal replacement patterns

Write path

Start from:

curl -X POST "https://context.usewhisper.dev/v1/memory" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "migration-demo",
    "user_id": "user-42",
    "session_id": "sess-42",
    "content": "User prefers concise answers"
  }'

Retrieval path

Pair it with:

curl -X POST "https://context.usewhisper.dev/v1/memory/search" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "migration-demo",
    "user_id": "user-42",
    "session_id": "sess-42",
    "query": "How should I answer this user?",
    "include_pending": true
  }'

Recommended migration path by surface

Raw API users

Move to the v1 memory and context routes directly and validate request payloads carefully.

SDK users

Use WhisperClient rather than rebuilding a thin wrapper around raw HTTP.

Agent and MCP users

Map agent behaviors to the Whisper MCP tool model instead of trying to preserve every old tool name literally.

Common migration mistakes

Treating user_id as optional when it is core to your product

If you previously depended on stable user memory, keep that identity stable through the migration.

Forgetting include_pending

This is one of the easiest ways to make a healthy async write path look broken.

Rebuilding the old abstraction without reconsidering it

Migration is a good time to remove accidental complexity. Do not preserve a bad wrapper just because it already exists.

What “done” looks like

Your migration is in good shape when:

• a fresh write is visible in the expected scope
• long-term user context still carries across sessions
• latency is acceptable for your real workload
• support or QA cannot trigger obvious cross-scope confusion

Next step

If you are moving application code to the SDK, read SDK migration: WhisperContext to WhisperClient. If you want the canonical first-run validation loop after migration, return to 5-minute quickstart.