Memory API v2 Migration Guide

Last Updated: November 11, 2025 Deprecation Date: January 15, 2025 Sunset Date: June 30, 2026

Overview

The legacy workspace-scoped Memory API (/api/v1/memories) has been deprecated in favor of the user-scoped Memory v2 API (/api/v1/memory). This guide will help you migrate your applications.

What's Changing?

Deprecated Routes (Workspace-Scoped)

POST /api/v1/memories Deprecated
GET /api/v1/memories Deprecated

Current Routes (User-Scoped)

POST /api/v1/memory Recommended
GET /api/v1/memory Recommended
GET /api/v1/memory/search Recommended
POST /api/v1/memory/batch Recommended
GET/PATCH/DELETE /api/v1/memories/[id] Current (uses memory_v2)

Key Differences

| Feature | Legacy (/api/v1/memories) | Current (/api/v1/memory) | |---------|--------------------------|-------------------------| | Scope | Workspace-based | User-based | | Table | memories | memory_v2 | | Required Params | workspaceId, userId | API key (auto-scoped) | | Thread Support | Limited | Full support (thread_id) | | Batch Operations | Not available | Available (/batch) | | Semantic Search | Not available | Available (/search) |

Migration Steps

1. Update Your Endpoints

Before (Deprecated):

// Old workspace-scoped endpoint
POST https://sovant.ai/api/v1/memories
{
  "workspaceId": "workspace-123",
  "userId": "user-456",
  "content": "Meeting notes",
  "kind": "journal"
}

After (Recommended):

// New user-scoped endpoint
POST https://sovant.ai/api/v1/memory
{
  "content": "Meeting notes",
  "type": "journal",
  "tags": ["meeting"],
  "thread_id": "optional-thread-uuid"
}
// Note: userId is automatically extracted from API key

2. Update Field Names

| Old Field | New Field | Notes | |-----------|-----------|-------| | kind | type | Renamed for clarity | | workspaceId | N/A | Auto-scoped via API key | | userId | N/A | Auto-scoped via API key | | ttlMinutes | N/A | No longer supported | | ttl_expires_at | N/A | No longer supported |

3. Use the Latest SDKs

The easiest way to migrate is to upgrade to the latest SDK versions which use the current API:

TypeScript:

npm install @sovant/sdk@1.2.0

Python:

pip install sovant==1.1.0

These SDKs automatically use the correct endpoints.

SDK Migration Examples

TypeScript Migration

Before (v1.0.x - manually calling deprecated endpoint):

import { Sovant } from '@sovant/sdk';

const client = new Sovant({ apiKey: 'sk_...' });

// This was using deprecated route
await fetch('https://sovant.ai/api/v1/memories', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    workspaceId: 'workspace-123',
    userId: 'user-456',
    content: 'Meeting notes',
    kind: 'journal'
  })
});

After (v1.2.0 - using SDK):

import { Sovant } from '@sovant/sdk';

const client = new Sovant({
  apiKey: 'sk_...',
  maxRetries: 3,  // NEW: automatic retry
  onError: (err) => console.error(err)  // NEW: telemetry
});

// Clean SDK interface - no workspace/user IDs needed
await client.memory.create({
  data: 'Meeting notes',
  type: 'journal',
  tags: ['meeting']
});

// NEW: Batch operations
await client.memory.createBatch([
  { data: 'Note 1', type: 'journal' },
  { data: 'Note 2', type: 'task' }
]);

Python Migration

Before (v1.0.x):

from sovant import Sovant

client = Sovant(api_key='sk_...')

# Manual API call
import httpx
response = httpx.post(
    'https://sovant.ai/api/v1/memories',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'workspaceId': 'workspace-123',
        'userId': 'user-456',
        'content': 'Meeting notes',
        'kind': 'journal'
    }
)

After (v1.1.0):

from sovant import Sovant, MemoryCreate

client = Sovant(
    api_key='sk_...',
    max_retries=3,  # NEW: automatic retry
    on_error=lambda err: print(err)  # NEW: telemetry
)

# Clean SDK interface
client.memory_create(MemoryCreate(
    data='Meeting notes',
    type='journal',
    tags=['meeting']
))

# NEW: Batch operations
client.memory_create_batch([
    {'data': 'Note 1', 'type': 'journal'},
    {'data': 'Note 2', 'type': 'task'}
])

New Features in Current API

1. Retry Logic with Exponential Backoff New

Automatically retries failed requests (rate limits, server errors, timeouts):

Configurable retries (default: 3)
Exponential backoff (1s → 2s → 4s)

2. Telemetry Hooks New

Monitor SDK behavior with callback functions:

const client = new Sovant({
  apiKey: 'sk_...',
  onRequest: (req) => console.log(`→ ${req.method} ${req.path}`),
  onResponse: (res) => console.log(`← ${res.status} (${res.duration}ms)`),
  onError: (err) => console.error(`✗ ${err.code}: ${err.message}`)
});

3. Batch Operations New

Create multiple memories in a single request:

const result = await client.memory.createBatch([
  { data: 'Memory 1', type: 'journal' },
  { data: 'Memory 2', type: 'task' },
  { data: 'Memory 3', type: 'insight' }
]);

console.log(`Created ${result.summary.successful}/3 memories`);

4. Semantic Search (Recall) New

Search memories using natural language:

const results = await client.memory.recall({
  query: 'what are my project preferences?',
  limit: 10
});

5. Thread Support New

Organize memories by conversation threads:

await client.memory.create({
  data: 'Discussion about pricing',
  type: 'journal',
  thread_id: 'thread-uuid-here',
  tags: ['pricing', 'discussion']
});

Timeline

| Date | Event | |------|-------| | January 15, 2025 | Legacy routes deprecated, headers added | | June 30, 2026 | Legacy routes sunset (removed) |

Detection

All responses from deprecated endpoints include these headers:

Deprecation: true
Sunset: Wed, 30 Jun 2026 23:59:59 GMT
Link: <https://sovant.ai/docs/api/migration>; rel="deprecation"
X-API-Warn: This endpoint is deprecated. Use /api/v1/memory instead.

Support

If you need help migrating:

Documentation: https://sovant.ai/docs
TypeScript SDK: SDK Documentation
Python SDK: SDK Documentation
Email: support@sovant.ai

FAQ

Q: Do I need to migrate immediately? A: No. You have until June 30, 2026. However, we recommend migrating soon to access new features.

Q: Will my existing memories be migrated automatically? A: The /api/v1/memories/[id] GET/PATCH/DELETE routes already use memory_v2, so existing memories are accessible. Only the collection endpoints (POST /api/v1/memories, GET /api/v1/memories) are deprecated.

Q: What if I'm using workspace-scoped access control? A: The new API is user-scoped. Each API key is tied to a specific user (workspace owner). Contact support if you need multi-user workspace access patterns.

Q: Are the SDKs backward compatible? A: Yes! SDK v1.2.0 (TS) and v1.1.0 (Py) are 100% backward compatible with v1.0.x. All existing code works unchanged.

Q: Can I use both old and new routes during migration? A: Yes, both work until June 30, 2026. However, we recommend switching entirely to new routes to avoid confusion.