Migrations

Browse docs

Migrations

Tap to expand

Contribute

MigrationsUpdated 2026-03-18

Migration from Legacy v2 to Latest

Complete guide to migrating from Whisper v2 to the latest version with minimal disruption.

Applies to: Whisper v2 users

This guide helps you migrate from Whisper v2 to the latest version.


Why Migrate?

Featurev2Latest
Latency~500ms<250ms
CachingBasicAdvanced
SDKLegacyNew
MCPLimitedFull support

Step 1: Add Compat Mode

Start with backward compatibility:

typescript
import { WhisperClient } from "@usewhisper/sdk";

const client = WhisperClient.fromEnv({
  compatMode: "fallback", // Keep v2 behavior
});

Step 2: Update Parameter Names

Old (v2) → New (latest)

v2 ParameterLatest Parameter
userIduser_id
sessionIdsession_id
projectIdproject
topKtop_k
userIDuser_id

SDK Handles Both

The SDK accepts both:

typescript
// Both work in compat mode
await client.memory.add({
  userId: "user-123",      // v2 style - works
  user_id: "user-123",     // Latest style - works
});

Step 3: Update Import Paths

Old

typescript
import { WhisperContext } from "@usewhisper/context";
const ctx = new WhisperContext({ apiKey: "..." });

New

typescript
import { WhisperClient } from "@usewhisper/sdk";
const client = WhisperClient.fromEnv();

Step 4: Update API Calls

v2 Memory Add

typescript
// v2
ctx.memories.add({
  userId: "user-123",
  content: "My memory",
});

Latest Memory Add

typescript
// Latest
client.memory.add({
  user_id: "user-123",
  content: "My memory",
});
typescript
// v2
ctx.memories.search({
  userId: "user-123",
  query: "search",
  limit: 10,
});
typescript
// Latest
client.memory.search({
  user_id: "user-123",
  query: "search",
  top_k: 10,
});

Step 5: Enable Strict Mode

After testing, enable strict mode:

typescript
const client = WhisperClient.fromEnv({
  compatMode: "strict", // Only accepts latest params
});

Complete Migration Example

Before (v2)

typescript
import { WhisperContext } from "@usewhisper/context";

const ctx = new WhisperContext({
  apiKey: process.env.WHISPER_API_KEY,
});

async function searchMemories(userId, query) {
  return await ctx.memories.search({
    userId,
    query,
    limit: 5,
  });
}

async function addMemory(userId, content) {
  return await ctx.memories.add({
    userId,
    content,
  });
}

After (Latest)

typescript
import { WhisperClient } from "@usewhisper/sdk";

const client = WhisperClient.fromEnv();

async function searchMemories(userId, query) {
  return await client.memory.search({
    user_id: userId,
    query,
    top_k: 5,
  });
}

async function addMemory(userId, content) {
  return await client.memory.add({
    user_id: userId,
    content,
  });
}

Breaking Changes

Changev2Latest
limitnumberUse top_k
userIdcamelCasesnake_case
SessionImplicitExplicit
Write modeSync defaultAsync default

Rollback Plan

If issues occur:

typescript
// Quick rollback to v2 behavior
const client = WhisperClient.fromEnv({
  compatMode: "fallback", // Restore v2 compatibility
});

Testing Checklist

  • Search returns correct results
  • Add memory works
  • Session management works
  • Error handling works
  • Latency is acceptable

Next step

Was this page helpful?

Your feedback helps us prioritize docs improvements weekly.