cloudflare workers support

[yashikabadaya]

Description

This section describes the implementation of Cloudflare Workers support for mem0ai.

Problem Statement

The original mem0ai TypeScript SDK had compatibility issues with Cloudflare Workers due to:

1. Native SQLite bindings - C++ modules not supported in Workers
2. Node.js APIs - File system and streaming APIs unavailable in Workers
3. Axios dependency - Uses Node.js HTTP implementation
4. Prototype chain issues - Objects not resolving to standard prototypes

Solution Overview

Created a Workers-compatible client that:

• Uses Web APIs (fetch, crypto.subtle) instead of Node.js APIs
• Avoids native bindings completely
• Pure JavaScript/TypeScript implementation
• Same API interface as the standard client
• Optimized for edge runtime constraints

Implementation Details

New Files Created

1. Core Client (mem0-ts/src/workers/index.ts)

• CloudflareWorkerMemoryClient class
• Web-only API implementation using fetch
• Workers-compatible hash generation using crypto.subtle
• Full TypeScript support with exported types

2. Example Implementation (mem0-ts/examples/cloudflare-workers/)

• Complete chat bot example (worker.ts)
• Wrangler configuration (wrangler.toml)
• Package configuration (package.json)
• Comprehensive README with setup instructions

3. Tests (mem0-ts/src/workers/index.test.ts)

• Unit tests for all client methods
• Mock implementations for Web APIs
• Platform compatibility validation

4. Documentation (docs/cloudflare-workers.md)

• Complete usage guide
• API reference
• Performance benchmarks
• Troubleshooting guide

Configuration Changes

Updated mem0-ts/package.json

{
  "exports": {
    "./workers": {
      "types": "./dist/workers/index.d.ts",
      "require": "./dist/workers/index.js",
      "import": "./dist/workers/index.mjs"
    }
  },
  "typesVersions": {
    "*": {
      "workers": ["./dist/workers/index.d.ts"]
    }
  }
}

Updated mem0-ts/tsup.config.ts

{
  entry: ["src/workers/index.ts"],
  outDir: "dist/workers",
  platform: "browser",  // Target browser/edge runtime
  external: []          // Bundle all dependencies
}

Key Features

1. Web-First Architecture

Instead of:

// Node.js approach (doesn't work in Workers)
import axios from 'axios';
import crypto from 'crypto';

const response = await axios.post(url, data);
const hash = crypto.createHash('sha256').update(input).digest('hex');

Uses:

// Workers approach (works everywhere)
const response = await fetch(url, {
  method: 'POST',
  body: JSON.stringify(data)
});

const encoder = new TextEncoder();
const data = encoder.encode(input);
const hashBuffer = await crypto.subtle.digest('SHA-256', data);

2. Same API Interface

// Standard client and Workers client have identical APIs
const client = new CloudflareWorkerMemoryClient({ apiKey });
const memories = await client.add(messages, { user_id });
const results = await client.search(query, { user_id });

3. Error Handling

class APIError extends Error {
  constructor(message: string) {
    super(message);
    this.name = "APIError";
  }
}

4. TypeScript Support

Full type definitions exported:

export type {
  MemoryOptions,
  Memory,
  SearchOptions,
  // ... all types from standard client
} from "../client/mem0.types";

Usage Examples

Basic Usage

import { CloudflareWorkerMemoryClient } from 'mem0ai/workers';

const client = new CloudflareWorkerMemoryClient({
  apiKey: env.MEM0_API_KEY
});

await client.add([
  { role: 'user', content: 'I love pizza' }
], { user_id: 'user123' });

Complete Worker

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const client = new CloudflareWorkerMemoryClient({
      apiKey: env.MEM0_API_KEY
    });
    
    // Use client for memory operations...
  }
};

Performance Benefits

Metric	Traditional Server	Cloudflare Workers
Cold Start	500-2000ms	0-10ms
Global Locations	1-5 regions	300+ locations
Scaling	Manual	Automatic
Memory Usage	High baseline	Zero when idle

Limitations

Current Limitations

1. Hosted Mode Only: Requires mem0ai hosted platform (no self-hosted)
2. Memory Constraints: 128MB RAM per request
3. Execution Time: 30 seconds maximum per request
4. No Local Storage: Cannot use SQLite or file system

Future Enhancements

• [ ] WebAssembly support for local embeddings
• [ ] Durable Objects integration for session state
• [ ] KV storage for caching frequent queries
• [ ] WebSocket support for real-time features

Developer Experience

Import Path

// Clear distinction from standard client
import { CloudflareWorkerMemoryClient } from 'mem0ai/workers';

Development Workflow

# Local development
wrangler dev

# Deploy to staging  
wrangler deploy --env staging

# Deploy to production
wrangler deploy --env production

Impact

This implementation:

1. Addresses Issue #3515: Provides full Cloudflare Workers compatibility
2. Maintains API Consistency: Same interface as standard client
3. Enables Edge Computing: AI agents at global edge locations
4. Improves Performance: Sub-10ms cold starts vs 500-2000ms traditional
5. Reduces Costs: Pay-per-request vs always-on servers

Next Steps

1. Community Testing: Gather feedback from Workers developers
2. Documentation: Update main docs with Workers examples
3. Performance Optimization: Further optimize bundle size
4. Advanced Features: Add WebAssembly support, Durable Objects integration

---

This implementation successfully enables mem0ai to run in Cloudflare Workers, providing developers with ultra-low-latency AI applications with persistent memory at the edge.

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)
• Documentation update

How Has This Been Tested?

• Unit Test - npm test -- src/workers/index.test.ts

The new Cloudflare Workers implementation passes all tests:

Constructor Tests • Should instantiate with valid API key • Should throw error with missing API key
• Should use custom host when provided

API Methods Tests
• Should have all expected methods • Should handle ping request • Should handle add request • Should handle search request • Should handle API errors gracefully

Error Handling Tests • Should validate update parameters

Platform Compatibility Tests • Should use Web APIs only

The passing tests confirm that the CloudflareWorkerMemoryClient:

1. Properly instantiates with correct validation
2. Has all required methods matching the standard client interface
3. Makes correct API calls using fetch instead of axios
4. Handles errors gracefully with proper error messages
5. Uses only Web APIs avoiding Node.js dependencies
6. Validates input parameters correctly
7. Works with mocked Web APIs (fetch, crypto.subtle)

Checklist:

• [ ] My code follows the style guidelines of this project
• [ ] I have performed a self-review of my own code
• [ ] I have commented my code, particularly in hard-to-understand areas
• [ ] I have made corresponding changes to the documentation
• [ ] My changes generate no new warnings
• [ ] I have added tests that prove my fix is effective or that my feature works
• [ ] New and existing unit tests pass locally with my changes
• [ ] Any dependent changes have been merged and published in downstream modules
• [ ] I have checked my code and corrected any misspellings

Maintainer Checklist

• closes #3515