feat: make external services optional with LOCAL_ONLY mode

jonathanpeterwu · claude · jonathanpeterwu · commit b9297db7fb5b · 2026-01-27T11:37:51.000-05:00
- Add feature flags system (src/core/config/feature-flags.ts)
- Add STACKMEMORY_LOCAL=true env to disable all external services
- Lazy-load Linear integration (only when API key present)
- Lazy-load WhatsApp/SMS commands (only when Twilio configured)
- Add LocalFallbackProvider for AI summaries without API key
- MCP server now works without Linear credentials

Set STACKMEMORY_LOCAL=true to run fully offline as open source.

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/src/cli/index.ts b/src/cli/index.ts
@@ -22,8 +22,8 @@ import { sharedContextLayer } from '../core/context/shared-context-layer.js';
 import { UpdateChecker } from '../core/utils/update-checker.js';
 import { ProgressTracker } from '../core/monitoring/progress-tracker.js';
 import { registerProjectCommands } from './commands/projects.js';
-import { registerLinearCommands } from './commands/linear.js';
 import { createSessionCommands } from './commands/session.js';
+import { isFeatureEnabled, isLocalOnly } from '../core/config/feature-flags.js';
 import { registerWorktreeCommands } from './commands/worktree.js';
 import { registerOnboardingCommand } from './commands/onboard.js';
 import { createTaskCommands } from './commands/tasks.js';
@@ -53,7 +53,6 @@ import { createShellCommand } from './commands/shell.js';
 import { createAPICommand } from './commands/api.js';
 import { createCleanupProcessesCommand } from './commands/cleanup-processes.js';
 import { createAutoBackgroundCommand } from './commands/auto-background.js';
-import { createSMSNotifyCommand } from './commands/sms-notify.js';
 import { createSettingsCommand } from './commands/settings.js';
 import { createRetrievalCommands } from './commands/retrieval.js';
 import { createDiscoveryCommands } from './commands/discovery.js';
@@ -69,7 +68,6 @@ import {
   enableChromaDB,
   getStorageModeDescription,
 } from '../core/config/storage-config.js';
-import { loadSMSConfig } from '../hooks/sms-notify.js';
 import { spawn } from 'child_process';
 import { homedir } from 'os';
 
@@ -86,7 +84,11 @@ UpdateChecker.checkForUpdates(VERSION, true).catch(() => {
 
 // Auto-start webhook and ngrok if notifications are enabled
 async function startNotificationServices(): Promise<void> {
+  // Skip in local-only mode
+  if (isLocalOnly() || !isFeatureEnabled('whatsapp')) return;
+
   try {
+    const { loadSMSConfig } = await import('../hooks/sms-notify.js');
     const config = loadSMSConfig();
     if (!config.enabled) return;
 
@@ -644,8 +646,14 @@ registerDbCommands(program);
 registerProjectCommands(program);
 registerWorktreeCommands(program);
 
-// Register Linear integration commands
-registerLinearCommands(program);
+// Register Linear integration commands (lazy-loaded, optional)
+if (isFeatureEnabled('linear')) {
+  import('./commands/linear.js')
+    .then(({ registerLinearCommands }) => registerLinearCommands(program))
+    .catch(() => {
+      // Linear integration not available - silently skip
+    });
+}
 
 // Register session management commands
 program.addCommand(createSessionCommands());
@@ -673,8 +681,18 @@ program.addCommand(createShellCommand());
 program.addCommand(createAPICommand());
 program.addCommand(createCleanupProcessesCommand());
 program.addCommand(createAutoBackgroundCommand());
-program.addCommand(createSMSNotifyCommand());
 program.addCommand(createSettingsCommand());
+
+// Register WhatsApp/SMS commands (lazy-loaded, optional)
+if (isFeatureEnabled('whatsapp')) {
+  import('./commands/sms-notify.js')
+    .then(({ createSMSNotifyCommand }) =>
+      program.addCommand(createSMSNotifyCommand())
+    )
+    .catch(() => {
+      // WhatsApp integration not available - silently skip
+    });
+}
 program.addCommand(createRetrievalCommands());
 program.addCommand(createDiscoveryCommands());
 program.addCommand(createModelCommand());
diff --git a/src/core/config/feature-flags.ts b/src/core/config/feature-flags.ts
@@ -0,0 +1,99 @@
+/**
+ * Feature Flags Configuration
+ * Controls which external integrations are enabled
+ *
+ * Set STACKMEMORY_LOCAL=true to run without any external services
+ */
+
+export interface FeatureFlags {
+  // Core features (always available)
+  core: true;
+
+  // External integrations (can be disabled)
+  linear: boolean;
+  whatsapp: boolean;
+  chromadb: boolean;
+  aiSummaries: boolean;
+}
+
+/**
+ * Check if running in local-only mode
+ * When true, all external service integrations are disabled
+ */
+export function isLocalOnly(): boolean {
+  return (
+    process.env['STACKMEMORY_LOCAL'] === 'true' ||
+    process.env['STACKMEMORY_LOCAL'] === '1' ||
+    process.env['LOCAL_ONLY'] === 'true'
+  );
+}
+
+/**
+ * Check if a specific feature is enabled
+ */
+export function isFeatureEnabled(feature: keyof FeatureFlags): boolean {
+  if (feature === 'core') return true;
+
+  // In local-only mode, external integrations are disabled
+  if (isLocalOnly()) return false;
+
+  // Check feature-specific env vars
+  switch (feature) {
+    case 'linear':
+      return (
+        process.env['STACKMEMORY_LINEAR'] !== 'false' &&
+        (!!process.env['LINEAR_API_KEY'] || !!process.env['LINEAR_OAUTH_TOKEN'])
+      );
+    case 'whatsapp':
+      return (
+        process.env['STACKMEMORY_WHATSAPP'] !== 'false' &&
+        !!process.env['TWILIO_ACCOUNT_SID']
+      );
+    case 'chromadb':
+      return process.env['STACKMEMORY_CHROMADB'] === 'true';
+    case 'aiSummaries':
+      return (
+        process.env['STACKMEMORY_AI'] !== 'false' &&
+        (!!process.env['ANTHROPIC_API_KEY'] || !!process.env['OPENAI_API_KEY'])
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get all feature flags
+ */
+export function getFeatureFlags(): FeatureFlags {
+  return {
+    core: true,
+    linear: isFeatureEnabled('linear'),
+    whatsapp: isFeatureEnabled('whatsapp'),
+    chromadb: isFeatureEnabled('chromadb'),
+    aiSummaries: isFeatureEnabled('aiSummaries'),
+  };
+}
+
+/**
+ * Log feature flags status (for debugging)
+ */
+export function logFeatureStatus(): void {
+  const flags = getFeatureFlags();
+  const local = isLocalOnly();
+
+  console.log(
+    `StackMemory Mode: ${local ? 'LOCAL (no external services)' : 'FULL'}`
+  );
+  if (!local) {
+    console.log(
+      `  Linear: ${flags.linear ? 'enabled' : 'disabled (no API key)'}`
+    );
+    console.log(
+      `  WhatsApp: ${flags.whatsapp ? 'enabled' : 'disabled (no Twilio)'}`
+    );
+    console.log(`  ChromaDB: ${flags.chromadb ? 'enabled' : 'disabled'}`);
+    console.log(
+      `  AI Summaries: ${flags.aiSummaries ? 'enabled' : 'disabled (no API key)'}`
+    );
+  }
+}
diff --git a/src/core/retrieval/llm-provider.ts b/src/core/retrieval/llm-provider.ts
@@ -152,17 +152,60 @@ export class AnthropicLLMProvider implements LLMProvider {
   }
 }
 
+/**
+ * Local fallback LLM provider - uses heuristic summarization without external APIs
+ * This ensures StackMemory works in LOCAL_ONLY mode
+ */
+export class LocalFallbackProvider implements LLMProvider {
+  async analyze(prompt: string, maxTokens: number): Promise<string> {
+    // Extract content from prompt and create a heuristic summary
+    const lines = prompt.split('\n').filter((l) => l.trim());
+    const contentStart = lines.findIndex((l) => l.includes('Content:'));
+
+    if (contentStart === -1 || lines.length < 3) {
+      return 'Context summary not available (local mode)';
+    }
+
+    // Extract key information heuristically
+    const content = lines.slice(contentStart + 1).join('\n');
+    const sentences = content
+      .split(/[.!?]+/)
+      .filter((s) => s.trim().length > 10);
+
+    // Take first few sentences up to maxTokens (rough approximation: 4 chars = 1 token)
+    const maxChars = maxTokens * 4;
+    let summary = '';
+    for (const sentence of sentences.slice(0, 5)) {
+      if (summary.length + sentence.length > maxChars) break;
+      summary += sentence.trim() + '. ';
+    }
+
+    return (
+      summary.trim() || 'Context available (use LLM API for detailed analysis)'
+    );
+  }
+}
+
 /**
  * Factory function to create an LLM provider based on environment
  */
 export function createLLMProvider(): LLMProvider | undefined {
+  // Check for local-only mode
+  if (
+    process.env['STACKMEMORY_LOCAL'] === 'true' ||
+    process.env['LOCAL_ONLY'] === 'true'
+  ) {
+    logger.info('LOCAL mode - using heuristic summarization');
+    return new LocalFallbackProvider();
+  }
+
   const apiKey = process.env['ANTHROPIC_API_KEY'];
 
   if (!apiKey) {
     logger.info(
       'No ANTHROPIC_API_KEY found, LLM retrieval will use heuristics'
     );
-    return undefined;
+    return new LocalFallbackProvider();
   }
 
   return new AnthropicLLMProvider({
diff --git a/src/integrations/mcp/server.ts b/src/integrations/mcp/server.ts
@@ -22,14 +22,20 @@ import { readFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { execSync } from 'child_process';
 import { FrameManager, FrameType } from '../../core/context/index.js';
-import {
-  LinearTaskManager,
+import { logger } from '../../core/monitoring/logger.js';
+import { isFeatureEnabled } from '../../core/config/feature-flags.js';
+
+// Linear types - imported dynamically when needed
+type LinearTaskManager =
+  import('../../features/tasks/linear-task-manager.js').LinearTaskManager;
+type LinearAuthManager = import('../linear/auth.js').LinearAuthManager;
+type LinearSyncEngine = import('../linear/sync.js').LinearSyncEngine;
+
+// Re-export task types for handlers (these are just enums/types, not runtime deps)
+export {
   TaskPriority,
   TaskStatus,
 } from '../../features/tasks/linear-task-manager.js';
-import { LinearAuthManager, LinearOAuthSetup } from '../linear/auth.js';
-import { LinearSyncEngine, DEFAULT_SYNC_CONFIG } from '../linear/sync.js';
-import { logger } from '../../core/monitoring/logger.js';
 import { BrowserMCPIntegration } from '../../features/browser/browser-mcp.js';
 import { TraceDetector } from '../../core/trace/trace-detector.js';
 import { ToolCall, Trace } from '../../core/trace/types.js';
@@ -59,9 +65,9 @@ class LocalStackMemoryMCP {
   private db: Database.Database;
   private projectRoot: string;
   private frameManager: FrameManager;
-  private taskStore: LinearTaskManager;
-  private linearAuthManager: LinearAuthManager;
-  private linearSync: LinearSyncEngine;
+  private taskStore: LinearTaskManager | null = null;
+  private linearAuthManager: LinearAuthManager | null = null;
+  private linearSync: LinearSyncEngine | null = null;
   private projectId: string;
   private contexts: Map<string, any> = new Map();
   private browserMCP: BrowserMCPIntegration;
@@ -88,16 +94,8 @@ class LocalStackMemoryMCP {
     // Initialize frame manager
     this.frameManager = new FrameManager(this.db, this.projectId);
 
-    // Initialize task store
-    this.taskStore = new LinearTaskManager(this.projectRoot, this.db);
-
-    // Initialize Linear integration
-    this.linearAuthManager = new LinearAuthManager(this.projectRoot);
-    this.linearSync = new LinearSyncEngine(
-      this.taskStore,
-      this.linearAuthManager,
-      DEFAULT_SYNC_CONFIG
-    );
+    // Initialize Linear integration (optional - lazy loaded)
+    this.initLinearIfEnabled();
 
     // Initialize MCP server
     this.server = new Server(
@@ -161,6 +159,36 @@ class LocalStackMemoryMCP {
     return process.cwd();
   }
 
+  /**
+   * Initialize Linear integration if enabled and credentials available
+   */
+  private async initLinearIfEnabled(): Promise<void> {
+    if (!isFeatureEnabled('linear')) {
+      logger.info('Linear integration disabled (no API key or LOCAL mode)');
+      return;
+    }
+
+    try {
+      const { LinearTaskManager } =
+        await import('../../features/tasks/linear-task-manager.js');
+      const { LinearAuthManager } = await import('../linear/auth.js');
+      const { LinearSyncEngine, DEFAULT_SYNC_CONFIG } =
+        await import('../linear/sync.js');
+
+      this.taskStore = new LinearTaskManager(this.projectRoot, this.db);
+      this.linearAuthManager = new LinearAuthManager(this.projectRoot);
+      this.linearSync = new LinearSyncEngine(
+        this.taskStore,
+        this.linearAuthManager,
+        DEFAULT_SYNC_CONFIG
+      );
+
+      logger.info('Linear integration initialized');
+    } catch (error) {
+      logger.warn('Failed to initialize Linear integration', { error });
+    }
+  }
+
   private initDB() {
     // Note: Don't create frames table here - FrameManager handles the schema
     // with the full run_id, project_id, parent_frame_id columns
