ruvnet--ruflo/v3/@claude-flow/memory/docs/CROSS_PLATFORM.md

Cross-Platform Database Support

Overview

The @claude-flow/memory module provides universal cross-platform support through intelligent database provider selection. This ensures your application works seamlessly on Windows, macOS, and Linux without code changes.

Architecture

┌─────────────────────────────────────────┐
│      createDatabase() Factory           │
│    Platform-Aware Auto-Selection        │
└──────────────┬──────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│   Windows   │  │ macOS/Linux │
│   Detected  │  │   Detected  │
└──────┬──────┘  └──────┬──────┘
       │                │
       ▼                ▼
┌─────────────┐  ┌─────────────┐
│   sql.js    │  │better-sqlite│
│  (WASM)     │  │  (Native)   │
└──────┬──────┘  └──────┬──────┘
       │                │
       └────────┬────────┘
                │
                ▼
         ┌─────────────┐
         │JSON Fallback│
         │ (Universal) │
         └─────────────┘

Supported Providers

1. better-sqlite3 (Native SQLite)

Best for: macOS, Linux Performance: Fastest (native C++ bindings) Features:

• WAL mode for concurrent reads
• ACID transactions
• Optimal performance
• Native compilation required

const db = await createDatabase('./data/memory.db', {
  provider: 'better-sqlite3',
  walMode: true,
  optimize: true
});

2. sql.js (WASM SQLite)

Best for: Windows, environments without native compilation Performance: Good (WebAssembly) Features:

• Pure JavaScript/WASM (no native compilation)
• Works everywhere
• Auto-persistence to disk
• Slightly slower than native

const db = await createDatabase('./data/memory.db', {
  provider: 'sql.js',
  autoPersistInterval: 5000  // Persist every 5 seconds
});

3. JSON (Simple File Storage)

Best for: Maximum compatibility, small datasets Performance: Slower (brute-force search) Features:

• Zero dependencies
• Human-readable storage
• Works on all platforms
• Limited scalability

const db = await createDatabase('./data/memory.db', {
  provider: 'json'
});

Platform-Specific Recommendations

Windows

// Recommended: sql.js (no native compilation issues)
const db = await createDatabase('./data/memory.db', {
  provider: 'sql.js',
  autoPersistInterval: 10000,  // Auto-save every 10s
  verbose: true
});

Why sql.js on Windows?

• No Visual Studio build tools required
• No Python dependency for node-gyp
• Pure JavaScript/WASM stack
• Reliable across Windows versions

macOS

// Recommended: better-sqlite3 (native performance)
const db = await createDatabase('./data/memory.db', {
  provider: 'better-sqlite3',
  walMode: true,    // Enable WAL mode
  optimize: true    // Performance optimizations
});

Why better-sqlite3 on macOS?

• Native compilation works reliably
• Maximum performance
• WAL mode for concurrent access
• Apple's SQLite optimizations

Linux

// Recommended: better-sqlite3 (native performance)
const db = await createDatabase('./data/memory.db', {
  provider: 'better-sqlite3',
  walMode: true,
  optimize: true
});

Why better-sqlite3 on Linux?

• Native SQLite library widely available
• Excellent performance
• Production-ready
• Standard on most distributions

Automatic Provider Selection

The createDatabase() function uses intelligent platform detection:

// Auto-select best provider for current platform
const db = await createDatabase('./data/memory.db');

Selection Algorithm:

1. Detect platform (Windows, macOS, Linux)
2. Try recommended provider for platform
3. Test provider availability (compilation check)
4. Fallback to alternatives if needed
5. Final fallback to JSON if all fail

// Example: Auto-selection with fallback chain
Windows:  sql.js → JSON
macOS:    better-sqlite3 → sql.js → JSON
Linux:    better-sqlite3 → sql.js → JSON

Usage Examples

Example 1: Cross-Platform Application

import { createDatabase, getPlatformInfo } from '@claude-flow/memory';

async function initDatabase() {
  const platform = getPlatformInfo();
  console.log(`Running on ${platform.os}`);
  console.log(`Recommended: ${platform.recommendedProvider}`);

  // Auto-select best provider
  const db = await createDatabase('./data/app.db', {
    verbose: true
  });

  return db;
}

Example 2: Windows-Specific Setup

import { createDatabase } from '@claude-flow/memory';

async function windowsSetup() {
  // Force sql.js for Windows reliability
  const db = await createDatabase('./data/windows.db', {
    provider: 'sql.js',
    autoPersistInterval: 5000,
    verbose: true
  });

  // Store data
  await db.store({
    id: 'config-1',
    key: 'app-config',
    content: JSON.stringify({ theme: 'dark' }),
    // ... other fields
  });

  // Changes auto-persist every 5 seconds
  // Or manually trigger:
  await db.persist();

  return db;
}

Example 3: Unix Performance Optimization

import { createDatabase, getAvailableProviders } from '@claude-flow/memory';

async function unixSetup() {
  const available = await getAvailableProviders();

  if (available.betterSqlite3) {
    // Use native SQLite with optimizations
    const db = await createDatabase('./data/unix.db', {
      provider: 'better-sqlite3',
      walMode: true,        // Concurrent reads
      optimize: true,       // Performance tuning
      maxEntries: 1000000   // Large dataset support
    });

    return db;
  } else {
    // Fallback to sql.js
    const db = await createDatabase('./data/unix.db', {
      provider: 'sql.js'
    });

    return db;
  }
}

Example 4: Migration Between Providers

import { createDatabase } from '@claude-flow/memory';

async function migrateDatabase() {
  // Load from JSON
  const sourceDb = await createDatabase('./old/data.db', {
    provider: 'json'
  });

  const entries = await sourceDb.query({
    type: 'hybrid',
    limit: 10000
  });

  await sourceDb.shutdown();

  // Migrate to SQLite
  const destDb = await createDatabase('./new/data.db', {
    provider: 'auto'  // Auto-select best for platform
  });

  await destDb.bulkInsert(entries);
  console.log(`Migrated ${entries.length} entries`);

  await destDb.shutdown();
}

API Reference

createDatabase()

async function createDatabase(
  path: string,
  options?: DatabaseOptions
): Promise<IMemoryBackend>

Parameters:

• path - Database file path (:memory: for in-memory)
• options.provider - Provider type ('auto', 'better-sqlite3', 'sql.js', 'json')
• options.verbose - Enable logging
• options.walMode - Enable WAL mode (better-sqlite3 only)
• options.optimize - Enable optimizations
• options.autoPersistInterval - Auto-save interval in ms (sql.js only)
• options.wasmPath - Custom WASM file path (sql.js only)

Returns: Initialized IMemoryBackend instance

getPlatformInfo()

function getPlatformInfo(): PlatformInfo

Returns:

{
  os: string;                        // 'win32', 'darwin', 'linux'
  isWindows: boolean;
  isMacOS: boolean;
  isLinux: boolean;
  recommendedProvider: DatabaseProvider;
}

getAvailableProviders()

async function getAvailableProviders(): Promise<{
  betterSqlite3: boolean;
  sqlJs: boolean;
  json: boolean;
}>

Returns: Which providers are available and working

Performance Comparison

Provider	Read Speed	Write Speed	Memory	Compilation
better-sqlite3	⚡⚡⚡⚡⚡	⚡⚡⚡⚡⚡	Low	Required
sql.js	⚡⚡⚡⚡	⚡⚡⚡⚡	Medium	None
JSON	⚡⚡	⚡⚡	Low	None

Installation

All Platforms

npm install @claude-flow/memory

Dependencies are installed automatically:

• better-sqlite3 (tries to compile, fails gracefully)
• sql.js (pure JavaScript, always works)

Windows-Specific

If you encounter compilation errors with better-sqlite3:

# Skip better-sqlite3 compilation
npm install @claude-flow/memory --no-optional

# The module will automatically use sql.js

Linux-Specific

Install SQLite development headers:

# Debian/Ubuntu
sudo apt-get install libsqlite3-dev

# RHEL/Fedora
sudo yum install sqlite-devel

# Then install
npm install @claude-flow/memory

Troubleshooting

Windows: better-sqlite3 Compilation Fails

Problem: node-gyp errors, missing Visual Studio

Solution: Use sql.js provider (automatic fallback)

const db = await createDatabase('./data/memory.db', {
  provider: 'sql.js'
});

macOS: Code Signing Issues

Problem: "cannot be opened because the developer cannot be verified"

Solution: Allow native module in System Preferences or use sql.js

# Allow native module
xattr -d com.apple.quarantine node_modules/better-sqlite3/build/Release/better_sqlite3.node

Linux: Missing SQLite Headers

Problem: sqlite3.h not found

Solution: Install development headers

sudo apt-get install libsqlite3-dev

Best Practices

1. Use Auto-Selection in Production

// Let the library choose the best provider
const db = await createDatabase('./data/memory.db');

2. Persist Regularly on Windows

// sql.js is in-memory, persist frequently
const db = await createDatabase('./data/memory.db', {
  provider: 'sql.js',
  autoPersistInterval: 5000  // 5 seconds
});

3. Enable WAL Mode on Unix

// Better concurrency on macOS/Linux
const db = await createDatabase('./data/memory.db', {
  provider: 'better-sqlite3',
  walMode: true
});

4. Check Health Regularly

const health = await db.healthCheck();
if (health.status !== 'healthy') {
  console.warn('Database issues:', health.issues);
  console.log('Recommendations:', health.recommendations);
}

5. Handle Shutdown Gracefully

// Always shutdown to persist changes
process.on('SIGINT', async () => {
  await db.shutdown();
  process.exit(0);
});

Environment Variables

# Force specific provider
CLAUDE_FLOW_DB_PROVIDER=sql.js

# Enable verbose logging
CLAUDE_FLOW_DB_VERBOSE=true

# Set auto-persist interval (ms)
CLAUDE_FLOW_DB_PERSIST_INTERVAL=10000

Docker Support

FROM node:20-alpine

# Install SQLite for better-sqlite3 (optional)
RUN apk add --no-cache sqlite-dev python3 make g++

WORKDIR /app
COPY package*.json ./
RUN npm install

# Will use better-sqlite3 if compilation succeeds,
# otherwise falls back to sql.js automatically

Testing

Run cross-platform tests:

# Run all tests
npm test

# Test specific provider
npm test -- --grep "sql.js"
npm test -- --grep "better-sqlite3"

# Test on current platform
npm test -- src/database-provider.test.ts

License

MIT