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?
| Feature | v2 | Latest |
|---|---|---|
| Latency | ~500ms | <250ms |
| Caching | Basic | Advanced |
| SDK | Legacy | New |
| MCP | Limited | Full 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 Parameter | Latest Parameter |
|---|---|
userId | user_id |
sessionId | session_id |
projectId | project |
topK | top_k |
userID | user_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",
});v2 Search
typescript
// v2
ctx.memories.search({
userId: "user-123",
query: "search",
limit: 10,
});Latest Search
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
| Change | v2 | Latest |
|---|---|---|
limit | number | Use top_k |
userId | camelCase | snake_case |
| Session | Implicit | Explicit |
| Write mode | Sync default | Async 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.