Memorizer Migration Guide: 1.6.x to 1.7.1

memorizer-migration-1.6-to-1.7.1.md

Memorizer Migration Guide: 1.6.x to 1.7.1

This guide covers all changes required when upgrading Memorizer from version 1.6.x to 1.7.1.

Breaking Changes

1. MCP Endpoint URL Update (REQUIRED)

The MCP endpoint has changed from /sse to the root path / to use modern Streamable HTTP transport (MCP spec 2025-03-26+).

Old Configuration (1.6.x):

{
  "mcpServers": {
    "memorizer": {
      "url": "http://localhost:5000/sse"
    }
  }
}

New Configuration (1.7.1):

{
  "mcpServers": {
    "memorizer": {
      "url": "http://localhost:5000"
    }
  }
}

Note: The /sse endpoint still works for backward compatibility but is no longer recommended and may be removed in future versions.

2. Session Management Changes

Version 1.7.1 uses stateless mode, which means:

• No session tracking - Each request is independent
• No session IDs - Clients should not send Mcp-Session-Id headers
• Server restarts don't break connections - No session state to lose
• Multiple server instances work seamlessly - No session affinity required

Impact on Clients:

• If you see "The Mcp-Session-Id header is not supported in stateless mode" errors, remove and re-add the MCP server configuration to force a fresh connection
• Session persistence is no longer available - if you were relying on server-side session state, you'll need to manage state client-side

3. Client Information Not Tracked

In stateless mode, McpServer.ClientInfo is always null, meaning:

• Server does not track client name/version across requests
• This should not impact most users, but custom server extensions that relied on ClientInfo will need updates

New Features Available

Configurable CORS (Added in 1.7.0)

You can now configure CORS settings if running Memorizer with custom origins:

{
  "Cors": {
    "AllowedOrigins": ["https://yourdomain.com"],
    "AllowedMethods": ["GET", "POST"],
    "AllowedHeaders": ["Content-Type"],
    "AllowCredentials": true
  }
}

Default behavior allows all origins (*) if not configured.

Migration Steps

Step 1: Update MCP Client Configuration

1. Locate your MCP client configuration (e.g., Claude Code settings, custom MCP client config)
2. Change the URL from http://localhost:5000/sse to http://localhost:5000
3. Save the configuration

Step 2: Reconnect to Memorizer

1. Disconnect from the Memorizer MCP server (if currently connected)
2. Remove the server from your MCP client configuration
3. Re-add the server with the new URL
4. Connect - this ensures a fresh stateless connection

Step 3: Test the Connection

Verify the migration worked by running a simple search:

// Using MCP client
await mcpClient.search({
  query: "test",
  limit: 5
})

Expected: Search results return successfully without session errors.

Common Issues & Solutions

Issue: "Session not found" (HTTP 404)

Cause: Old MCP client trying to use session IDs with stateless server

Solution:

1. Update to the new endpoint URL (/ instead of /sse)
2. Remove and re-add the MCP server configuration
3. Restart your MCP client to clear any cached session state

Issue: "The Mcp-Session-Id header is not supported in stateless mode" (HTTP 400)

Cause: MCP client sending session headers to stateless server

Solution:

1. Disconnect from Memorizer
2. Remove server configuration completely
3. Re-add with new URL
4. Reconnect - this forces fresh connection without session headers

Issue: Server restarts breaking connections

Solution: This is now fixed in 1.7.1! Stateless mode eliminates this issue entirely. Just retry the request.

Claude Code Specific Instructions

If using Memorizer with Claude Code:

1. Open Claude Code Settings (.claude/config.json or Settings UI)
2. Remove existing Memorizer server:

   {
     "mcpServers": {
       // Remove the old memorizer entry
     }
   }

3. Add new Memorizer configuration:

   {
     "mcpServers": {
       "memorizer": {
         "url": "http://localhost:5000"
       }
     }
   }

4. Restart Claude Code or reload the MCP connection
5. Test with a search query in your conversation

Rollback Instructions

If you need to rollback to 1.6.x:

1. Downgrade the Memorizer server to version 1.6.x
2. Update MCP client URL back to http://localhost:5000/sse
3. Restart connections

Note: Data is forward compatible - no database changes needed for rollback.

Benefits of Upgrading

✅ Improved reliability - No more session expiration issues ✅ Better scalability - Run multiple Memorizer instances without sticky sessions ✅ Cleaner protocol - Modern Streamable HTTP transport (MCP spec 2025-03-26+) ✅ Bug fixes - Resolves server notification issues from SDK v0.4.0-preview.2

Questions or Issues?

• Documentation: https://github.com/petabridge/memorizer-v1
• Issues: https://github.com/petabridge/memorizer-v1/issues
• Release Notes: https://github.com/petabridge/memorizer-v1/releases/tag/1.7.1