@ekkos/mcp-server 2.0.3 → 2.1.0

package/dist/index.d.ts

@@ -2,8 +2,11 @@
 /**
  * @ekkos/mcp-server
  *
- * Simple stdio proxy to ekkOS cloud MCP gateway.
- * This creates a local MCP server that forwards all requests to https://mcp.ekkos.dev
+ * Local-first MCP server for ekkOS cloud memory.
+ * - Caches patterns + directives locally for <5ms search
+ * - Falls back to cloud gateway for full results
+ * - Queues writes when offline, flushes on reconnect
+ * - Auto-discovers API key from ~/.ekkos/config.json
  */
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;GAQG"}

package/dist/index.js

@@ -2,8 +2,11 @@
 /**
  * @ekkos/mcp-server
  *
- * Simple stdio proxy to ekkOS cloud MCP gateway.
- * This creates a local MCP server that forwards all requests to https://mcp.ekkos.dev
+ * Local-first MCP server for ekkOS cloud memory.
+ * - Caches patterns + directives locally for <5ms search
+ * - Falls back to cloud gateway for full results
+ * - Queues writes when offline, flushes on reconnect
+ * - Auto-discovers API key from ~/.ekkos/config.json
  */
 // Sentry must be imported and initialized before other imports
 import * as Sentry from '@sentry/node';
@@ -19,18 +22,173 @@ if (process.env.SENTRY_DSN) {
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// Configuration
-const EKKOS_API_KEY = process.env.EKKOS_API_KEY || '';
+import { readFileSync, existsSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { loadCacheFromDisk, warmCache, searchLocal, getDirectives, invalidateCache, isCacheStale, startPeriodicRefresh, getCacheStats, } from './local-cache.js';
+import { isWriteTool, queueWrite, flushQueue, getPendingCount, } from './offline-queue.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// CONFIGURATION — resolve API key from env, then ~/.ekkos/config.json
+// ═══════════════════════════════════════════════════════════════════════════
+function resolveApiKey() {
+    // Priority 1: Environment variable
+    if (process.env.EKKOS_API_KEY) {
+        return process.env.EKKOS_API_KEY;
+    }
+    // Priority 2: ~/.ekkos/config.json (from prior `ekkos init`)
+    try {
+        const configPath = join(homedir(), '.ekkos', 'config.json');
+        if (existsSync(configPath)) {
+            const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+            if (config.apiKey) {
+                console.error('[ekkOS] Using API key from ~/.ekkos/config.json');
+                return config.apiKey;
+            }
+        }
+    }
+    catch {
+        // Config unreadable — fall through to degraded mode
+    }
+    // No key found — caller will enable degraded mode
+    return null;
+}
+const EKKOS_API_KEY = resolveApiKey();
+/**
+ * Degraded mode: no API key available.
+ * Search returns local cache only. Writes are queued to offline queue.
+ * All tools still register normally so Claude sees no missing tools.
+ */
+const degradedMode = EKKOS_API_KEY === null;
 const EKKOS_USER_ID = process.env.EKKOS_USER_ID || '';
 const EKKOS_MCP_URL = process.env.EKKOS_MCP_URL || 'https://mcp.ekkos.dev/api/v1/mcp';
 const DEBUG = process.env.EKKOS_DEBUG === 'true';
-if (!EKKOS_API_KEY) {
-    console.error('[ekkOS] ERROR: EKKOS_API_KEY environment variable is required');
-    console.error('[ekkOS] Get your API key at https://platform.ekkos.dev/dashboard/settings/api-keys');
-    process.exit(1);
+// ═══════════════════════════════════════════════════════════════════════════
+// SESSION METRICS — written to ~/.ekkos/session-metrics.json after each tool call
+// ═══════════════════════════════════════════════════════════════════════════
+const METRICS_DIR = join(homedir(), '.ekkos');
+const METRICS_FILE = join(METRICS_DIR, 'session-metrics.json');
+// In-process counters — reset each MCP server process lifetime (= one Claude session)
+const sessionMetrics = {
+    session_id: `mcp-${Date.now()}`,
+    session_name: '',
+    turn: 0,
+    started_at: new Date().toISOString(),
+    updated_at: new Date().toISOString(),
+    tool_calls: 0,
+    patterns_recalled: 0,
+    patterns_forged: 0,
+    directives_active: 0,
+    cache_backend: 'json',
+    cache_patterns: 0,
+    tokens_in: 0,
+    tokens_out: 0,
+};
+/** Fire-and-forget write of metrics to disk. Never throws. */
+function writeMetrics() {
+    try {
+        mkdirSync(METRICS_DIR, { recursive: true });
+        const stats = getCacheStats();
+        sessionMetrics.updated_at = new Date().toISOString();
+        sessionMetrics.cache_backend = stats.backend;
+        sessionMetrics.cache_patterns = stats.patterns;
+        sessionMetrics.directives_active = stats.directives;
+        writeFileSync(METRICS_FILE, JSON.stringify(sessionMetrics, null, 2), 'utf-8');
+    }
+    catch {
+        // best-effort — never block the tool response
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// CIRCUIT BREAKER — fast-fail when cloud is unreachable
+// ═══════════════════════════════════════════════════════════════════════════
+let circuitFailures = 0;
+let circuitOpenUntil = 0;
+const CIRCUIT_THRESHOLD = 3; // failures before opening
+const CIRCUIT_RESET_MS = 60_000; // 60s before half-open retry
+const GATEWAY_TIMEOUT_MS = 8_000; // 8s request timeout
+function isCircuitOpen() {
+    if (circuitFailures < CIRCUIT_THRESHOLD)
+        return false;
+    if (Date.now() > circuitOpenUntil) {
+        // Half-open: allow one request through
+        return false;
+    }
+    return true;
+}
+function recordSuccess() {
+    circuitFailures = 0;
+    circuitOpenUntil = 0;
+}
+function recordFailure() {
+    circuitFailures++;
+    if (circuitFailures >= CIRCUIT_THRESHOLD) {
+        circuitOpenUntil = Date.now() + CIRCUIT_RESET_MS;
+        console.error(`[ekkOS:circuit] OPEN — ${circuitFailures} failures, retrying in ${CIRCUIT_RESET_MS / 1000}s`);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// RESULT SLIMMING — strip verbose _ekkos_* metadata from gateway responses
+// These fields (_ekkos_stream_message, _ekkos_context, _ekkos_pattern_contract,
+// _ekkos_acknowledgment_*) are designed for Cursor's sidebar UI.  When returned
+// via MCP stdio to CLI clients (Gemini, Claude Code) the model sees them as
+// raw tool output and parrots them back, producing noisy verbose responses.
+// ═══════════════════════════════════════════════════════════════════════════
+const VERBOSE_EKKOS_KEYS = new Set([
+    '_ekkos_stream_message',
+    '_ekkos_context',
+    '_ekkos_pattern_contract',
+    '_ekkos_acknowledgment_required',
+    '_ekkos_acknowledgment_instruction',
+    '_ekkos_enforcement',
+    '_ekkos_session_summary',
+]);
+/**
+ * Strip verbose _ekkos_* fields from a gateway result.
+ * Keeps compact fields like _ekkos_patterns and _ekkos_auto_retrieved.
+ */
+function slimGatewayResult(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    // If result has content[].text with JSON, parse → strip → re-serialize
+    if (data.result && typeof data.result === 'object') {
+        for (const key of VERBOSE_EKKOS_KEYS) {
+            delete data.result[key];
+        }
+    }
+    // Also strip from top-level content array (MCP format)
+    if (data.content && Array.isArray(data.content)) {
+        for (const part of data.content) {
+            if (part.type === 'text' && typeof part.text === 'string') {
+                try {
+                    const parsed = JSON.parse(part.text);
+                    if (parsed && typeof parsed === 'object') {
+                        let changed = false;
+                        for (const key of VERBOSE_EKKOS_KEYS) {
+                            if (key in parsed) {
+                                delete parsed[key];
+                                changed = true;
+                            }
+                        }
+                        if (changed) {
+                            part.text = JSON.stringify(parsed);
+                        }
+                    }
+                }
+                catch {
+                    // Not JSON — leave as-is
+                }
+            }
+        }
+    }
+    return data;
 }
-// Simple HTTP client for MCP gateway
+// ═══════════════════════════════════════════════════════════════════════════
+// GATEWAY CLIENT — HTTP calls to cloud MCP gateway
+// ═══════════════════════════════════════════════════════════════════════════
 async function callGateway(endpoint, method, params) {
+    if (degradedMode) {
+        throw new Error('ekkOS running in cache-only mode — no API key');
+    }
     const url = `${EKKOS_MCP_URL}/${endpoint}`;
     const headers = {
         'Content-Type': 'application/json',
@@ -42,24 +200,155 @@ async function callGateway(endpoint, method, params) {
     if (DEBUG) {
         console.error(`[ekkOS] → ${method} ${endpoint}`);
     }
-    const response = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: JSON.stringify({ method, params: params || {} }),
-    });
-    if (!response.ok) {
-        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), GATEWAY_TIMEOUT_MS);
+    try {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ method, params: params || {} }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (DEBUG) {
+            console.error(`[ekkOS] ← ${method} OK`);
+        }
+        recordSuccess();
+        return slimGatewayResult(data);
     }
-    const data = await response.json();
-    if (DEBUG) {
-        console.error(`[ekkOS] ← ${method} OK`);
+    catch (err) {
+        recordFailure();
+        throw err;
+    }
+    finally {
+        clearTimeout(timeout);
     }
-    return data;
 }
-// Create MCP server
+/**
+ * Call gateway with offline fallback.
+ * For write tools: queues when offline.
+ * For read tools: returns null when offline (caller handles fallback).
+ */
+async function callGatewayWithFallback(endpoint, method, params, toolName) {
+    // If circuit is open, don't even try
+    if (isCircuitOpen()) {
+        if (toolName && isWriteTool(toolName)) {
+            queueWrite(toolName, params?.arguments || {});
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ _offline: true, _queued: true, message: 'Queued for sync when connection restores' }) }],
+            };
+        }
+        return null; // Caller handles fallback
+    }
+    try {
+        const result = await callGateway(endpoint, method, params);
+        // Connectivity restored — flush any pending writes in background
+        const pendingCount = getPendingCount();
+        if (pendingCount > 0) {
+            flushQueue(callGateway).catch(() => { });
+        }
+        return result;
+    }
+    catch {
+        if (toolName && isWriteTool(toolName)) {
+            queueWrite(toolName, params?.arguments || {});
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ _offline: true, _queued: true, message: 'Queued for sync when connection restores' }) }],
+            };
+        }
+        return null; // Caller handles fallback
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// LOCAL-FIRST SEARCH — check cache before cloud
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Handle ekkOS_Search with local-first strategy:
+ * 1. Search local cache (<5ms)
+ * 2. If cache has results, return them immediately
+ * 3. Background: also query cloud for freshness
+ * 4. If cache miss or stale, fall through to cloud
+ */
+async function handleSearchLocally(args) {
+    const query = args.query || '';
+    const limit = args.limit || 5;
+    const start = Date.now();
+    // Try local cache first
+    const localPatterns = searchLocal(query, limit);
+    const localDirectives = getDirectives();
+    const localLatency = Date.now() - start;
+    if (localPatterns.length > 0 || localDirectives.length > 0) {
+        // Build a response that matches the cloud format
+        const localResult = {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        patterns: localPatterns.map(p => ({
+                            id: p.id,
+                            title: p.title,
+                            similarity: 0.75, // Approximate — local search doesn't compute embeddings
+                            success_rate: p.success_rate,
+                            applied_count: p.applied_count,
+                            tags: p.tags?.slice(0, 3),
+                        })),
+                        directives: localDirectives,
+                        total: localPatterns.length + localDirectives.length,
+                        _cache: 'local',
+                        _cache_latency_ms: localLatency,
+                    }),
+                }],
+            _ekkos_status: `[ekkOS_RETRIEVE] ⚡ Local: ${localPatterns.length} patterns, ${localDirectives.length} directives (${localLatency}ms)`,
+        };
+        // If cache is stale, trigger background refresh (don't block)
+        if (isCacheStale()) {
+            warmCache(callGateway, EKKOS_USER_ID).catch(() => { });
+        }
+        // Also query cloud in background to update cache (don't await)
+        callGatewayWithFallback('tools/call', 'tools/call', {
+            name: 'ekkOS_Search',
+            arguments: args,
+        }).then(cloudResult => {
+            if (cloudResult) {
+                // Update cache with fresh cloud results
+                warmCache(callGateway, EKKOS_USER_ID).catch(() => { });
+            }
+        }).catch(() => { });
+        return localResult;
+    }
+    // No local results — fall through to cloud
+    const cloudResult = await callGatewayWithFallback('tools/call', 'tools/call', {
+        name: 'ekkOS_Search',
+        arguments: args,
+    }, 'ekkOS_Search');
+    if (cloudResult) {
+        // Trigger cache update with fresh data
+        warmCache(callGateway, EKKOS_USER_ID).catch(() => { });
+        return cloudResult;
+    }
+    // Both local and cloud failed
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    patterns: [],
+                    directives: [],
+                    total: 0,
+                    _cache: 'miss',
+                    _offline: true,
+                    message: 'No cached patterns and cloud unreachable',
+                }),
+            }],
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// MCP SERVER
+// ═══════════════════════════════════════════════════════════════════════════
 const server = new Server({
     name: 'ekkos-memory',
-    version: '1.0.0',
+    version: '1.1.0',
 }, {
     capabilities: {
         tools: {},
@@ -67,26 +356,195 @@ const server = new Server({
         prompts: {},
     },
 });
-// List tools - proxy to gateway
+// Cache-invalidating tools — after these succeed, refresh local cache
+const CACHE_INVALIDATING_TOOLS = new Set([
+    'ekkOS_Forge',
+    'ekkOS_Directive',
+    'ekkOS_UpdateDirective',
+    'ekkOS_DeleteDirective',
+]);
+// List tools - proxy to gateway (or return cached list in degraded mode)
 server.setRequestHandler(ListToolsRequestSchema, async () => {
+    // AutoForge tool — always available, handled locally in MCP server
+    const autoForgeTool = {
+        name: 'ekkOS_AutoForge',
+        description: 'Lightweight pattern forge. Call this instead of writing [ekkOS_LEARN]. Accepts a title and context string, uses Gemini Flash to extract a structured pattern, and forges it. Much lighter than ekkOS_Forge — use for quick lessons learned.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: { type: 'string', description: 'Pattern title (e.g. "Fix: missing await on async Supabase client")' },
+                context: { type: 'string', description: 'Full context: what was the problem, what was the fix, what files were involved. Include code snippets if relevant.' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags for categorization' },
+            },
+            required: ['title', 'context'],
+        },
+    };
+    if (degradedMode) {
+        return { tools: [autoForgeTool] };
+    }
     const result = await callGateway('tools/list', 'tools/list');
+    // Inject AutoForge into the tool list from gateway
+    if (result?.tools && Array.isArray(result.tools)) {
+        const hasAutoForge = result.tools.some((t) => t.name === 'ekkOS_AutoForge');
+        if (!hasAutoForge) {
+            result.tools.push(autoForgeTool);
+        }
+    }
     return result;
 });
-// Call tool - proxy to gateway
+// Call tool - local-first for search, gateway for everything else
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const result = await callGateway('tools/call', 'tools/call', {
-        name: request.params.name,
-        arguments: request.params.arguments,
-    });
-    return result;
+    const toolName = request.params.name;
+    const toolArgs = request.params.arguments || {};
+    // ── Increment global tool-call counter ──────────────────────────────────
+    sessionMetrics.tool_calls++;
+    // Extract session_name from ekkOS_Search / ekkOS_Forge args if present
+    const argsAny = toolArgs;
+    if (argsAny.session_name && typeof argsAny.session_name === 'string' && !sessionMetrics.session_name) {
+        sessionMetrics.session_name = argsAny.session_name;
+    }
+    // LOCAL-FIRST: ekkOS_Search uses local cache
+    if (toolName === 'ekkOS_Search') {
+        const result = await handleSearchLocally(argsAny);
+        // Count patterns returned as "recalled" — parse result text if available
+        try {
+            const text = result?.content?.[0]?.text;
+            if (text) {
+                const parsed = JSON.parse(text);
+                sessionMetrics.patterns_recalled += (parsed.patterns?.length ?? 0);
+                // Infer turn from total search calls (each search ≈ one turn)
+                sessionMetrics.turn = sessionMetrics.patterns_recalled > 0
+                    ? Math.max(sessionMetrics.turn, Math.ceil(sessionMetrics.tool_calls / 2))
+                    : sessionMetrics.turn;
+            }
+        }
+        catch { /* ignore parse errors */ }
+        writeMetrics();
+        return result;
+    }
+    // AUTO-FORGE: lightweight forge via Gemini Flash extraction
+    if (toolName === 'ekkOS_AutoForge') {
+        const title = argsAny.title || 'Untitled Pattern';
+        const context = argsAny.context || '';
+        const tags = argsAny.tags || [];
+        // Call Gemini Flash to extract structured pattern from the context
+        try {
+            const extractionPrompt = `Extract a reusable pattern from this context. Return JSON only.
+
+Title: ${title}
+Context: ${context}
+
+Return: {"problem": "what problem this solves", "solution": "the solution approach", "works_when": ["condition1"], "anti_patterns": ["what not to do"]}`;
+            const geminiKey = process.env.GOOGLE_AI_API_KEY || process.env.GEMINI_API_KEY;
+            let extraction = { problem: title, solution: context.slice(0, 500), works_when: [], anti_patterns: [] };
+            if (geminiKey) {
+                const geminiResp = await fetch('https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json', 'x-goog-api-key': geminiKey },
+                    body: JSON.stringify({
+                        contents: [{ parts: [{ text: extractionPrompt }] }],
+                        generationConfig: { temperature: 0.1, maxOutputTokens: 512 },
+                    }),
+                    signal: AbortSignal.timeout(5000),
+                });
+                if (geminiResp.ok) {
+                    const geminiData = await geminiResp.json();
+                    const text = geminiData.candidates?.[0]?.content?.parts?.[0]?.text || '';
+                    const jsonMatch = text.match(/\{[\s\S]*\}/);
+                    if (jsonMatch) {
+                        try {
+                            extraction = { ...extraction, ...JSON.parse(jsonMatch[0]) };
+                        }
+                        catch { /* use defaults */ }
+                    }
+                }
+            }
+            // Forge via gateway (same path as ekkOS_Forge)
+            const forgeResult = await callGatewayWithFallback('tools/call', 'tools/call', {
+                name: 'ekkOS_Forge',
+                arguments: {
+                    title,
+                    problem: extraction.problem,
+                    solution: extraction.solution,
+                    context,
+                    tags: [...tags, 'auto-forge', 'gemini-extracted'],
+                    works_when: extraction.works_when,
+                    anti_patterns: extraction.anti_patterns,
+                },
+            }, 'ekkOS_AutoForge');
+            sessionMetrics.patterns_forged++;
+            writeMetrics();
+            return forgeResult || {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: true,
+                            _auto_forged: true,
+                            title,
+                            message: `Auto-forged: "${title}" (Gemini Flash extracted)`,
+                        }) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: JSON.stringify({
+                            success: false,
+                            error: `AutoForge failed: ${err.message}`,
+                            _fallback: 'Pattern not forged — try ekkOS_Forge manually',
+                        }) }],
+            };
+        }
+    }
+    // WRITE TOOLS: use fallback with offline queue
+    if (isWriteTool(toolName)) {
+        const result = await callGatewayWithFallback('tools/call', 'tools/call', {
+            name: toolName,
+            arguments: toolArgs,
+        }, toolName);
+        // Invalidate cache after successful writes
+        if (result && CACHE_INVALIDATING_TOOLS.has(toolName)) {
+            invalidateCache();
+            warmCache(callGateway, EKKOS_USER_ID).catch(() => { });
+        }
+        // Track forged patterns
+        if (toolName === 'ekkOS_Forge' && result && !result.content?.[0]?.text?.includes('_offline')) {
+            sessionMetrics.patterns_forged++;
+        }
+        writeMetrics();
+        return result || {
+            content: [{ type: 'text', text: JSON.stringify({ _offline: true, _queued: true }) }],
+        };
+    }
+    // ALL OTHER TOOLS: proxy to cloud with graceful fallback
+    const result = await callGatewayWithFallback('tools/call', 'tools/call', {
+        name: toolName,
+        arguments: toolArgs,
+    }, toolName);
+    writeMetrics();
+    if (result)
+        return result;
+    // Offline fallback for read tools
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    _offline: true,
+                    message: `Cloud unreachable — ${toolName} requires connectivity`,
+                    cache_stats: getCacheStats(),
+                }),
+            }],
+    };
 });
 // List resources - proxy to gateway
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    if (degradedMode)
+        return { resources: [] };
     const result = await callGateway('resources/list', 'resources/list');
     return result;
 });
 // Read resource - proxy to gateway
 server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (degradedMode) {
+        return { contents: [{ uri: request.params.uri, text: 'ekkOS running in cache-only mode. Run `ekkos init` to connect.' }] };
+    }
     const result = await callGateway('resources/read', 'resources/read', {
         uri: request.params.uri,
     });
@@ -94,11 +552,16 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 });
 // List prompts - proxy to gateway
 server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    if (degradedMode)
+        return { prompts: [] };
     const result = await callGateway('prompts/list', 'prompts/list');
     return result;
 });
 // Get prompt - proxy to gateway
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (degradedMode) {
+        return { description: 'ekkOS cache-only mode', messages: [] };
+    }
     const result = await callGateway('prompts/get', 'prompts/get', {
         name: request.params.name,
         arguments: request.params.arguments,
@@ -117,17 +580,42 @@ process.on('SIGINT', async () => {
     await server.close();
     process.exit(0);
 });
-// Start server
+// ═══════════════════════════════════════════════════════════════════════════
+// STARTUP
+// ═══════════════════════════════════════════════════════════════════════════
 async function main() {
+    // Step 1: Load cache from disk (instant, <1ms)
+    const diskCache = loadCacheFromDisk();
+    if (diskCache.patterns > 0 || diskCache.directives > 0) {
+        console.error(`[ekkOS] Cache loaded: ${diskCache.patterns} patterns, ${diskCache.directives} directives`);
+    }
+    // Degraded mode: no API key — run cache-only, skip all cloud steps
+    if (degradedMode) {
+        console.error('[ekkOS] WARNING: ekkOS running in cache-only mode. Run `ekkos init` to connect.');
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        return;
+    }
+    // Step 2: Flush any pending offline writes (background)
+    const pendingCount = getPendingCount();
+    if (pendingCount > 0) {
+        console.error(`[ekkOS] Flushing ${pendingCount} pending offline writes...`);
+        flushQueue(callGateway).catch(() => { });
+    }
+    // Step 3: Start MCP transport
     if (DEBUG) {
-        console.error('[ekkOS] Starting MCP proxy to ekkOS Memory...');
+        console.error('[ekkOS] Starting ekkOS Memory MCP Server...');
         console.error(`[ekkOS] Gateway: ${EKKOS_MCP_URL}`);
         console.error(`[ekkOS] User ID: ${EKKOS_USER_ID || '(not set)'}`);
     }
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Step 4: Warm cache from cloud (non-blocking background task)
+    warmCache(callGateway, EKKOS_USER_ID).catch(() => { });
+    // Step 5: Start periodic cache refresh (every 5 min)
+    startPeriodicRefresh(callGateway, EKKOS_USER_ID);
     if (DEBUG) {
-        console.error('[ekkOS] ✓ Ready! Your AI can now access ekkOS memory.');
+        console.error('[ekkOS] ✓ Ready! Local-first memory with cloud sync.');
     }
 }
 main().catch((error) => {