claude-brain 0.15.2 → 0.16.0

package/src/server/services.ts

@@ -1,468 +1,468 @@
-/**
- * Shared Services Module
- * Provides access to initialized services for tool handlers
- */
-
-import type { Logger } from 'pino'
-import { existsSync } from 'fs'
-import * as path from 'path'
-import { MemoryManager } from '@/memory'
-import { VaultManager } from '@/vault'
-import { ContextManager } from '@/context'
-import { Phase12Manager } from '@/automation/phase12-manager'
-import { RetrievalService } from '@/retrieval/service'
-import { RetrievalPipeline } from '@/retrieval/pipeline'
-import { InMemoryKnowledgeGraph } from '@/knowledge/graph/memory-graph'
-import { GraphSearchEngine } from '@/knowledge/graph/search'
-import { KnowledgeGraphBuilder } from '@/knowledge/graph/builder'
-import { CrossReferenceLinker } from '@/knowledge/graph/linker'
-import { EpisodeManager } from '@/memory/episodic/manager'
-import { HookSessionTracker } from '@/hooks/session-tracker'
-import type { Config } from '@/config'
-import { SemanticCache } from '@/intelligence/optimization/semantic-cache'
-import { PrecomputeEngine } from '@/intelligence/optimization/precompute'
-
-export interface KnowledgeGraphServiceContainer {
-  graph: InMemoryKnowledgeGraph
-  search: GraphSearchEngine
-  builder: KnowledgeGraphBuilder
-  linker: CrossReferenceLinker
-}
-
-/**
- * Container for all shared services
- */
-export interface Services {
-  memory: MemoryManager
-  vault: VaultManager
-  context: ContextManager
-  phase12: Phase12Manager
-  retrieval: RetrievalService | null
-  retrievalPipeline: RetrievalPipeline | null
-  knowledgeGraph: KnowledgeGraphServiceContainer | null
-  episodeManager: EpisodeManager | null
-  sessionTracker: HookSessionTracker | null
-  semanticCache: SemanticCache | null
-  precompute: PrecomputeEngine | null
-  logger: Logger
-  config: Config
-}
-
-// Singleton services instance
-let services: Services | null = null
-let initializationPromise: Promise<void> | null = null
-
-/**
- * Initialize all services
- * Should be called once during server startup
- */
-export async function initializeServices(config: Config, logger: Logger): Promise<Services> {
-  // If already initialized, return existing services
-  if (services) {
-    logger.debug('Services already initialized')
-    return services
-  }
-
-  // If initialization is in progress, wait for it
-  if (initializationPromise) {
-    await initializationPromise
-    return services!
-  }
-
-  // Start initialization
-  initializationPromise = (async () => {
-    const serviceLogger = logger.child({ component: 'services' })
-    serviceLogger.info('Initializing services...')
-
-    // Validate vault path configuration
-    if (!config.vaultPath) {
-      throw new Error('Vault path not configured. Set VAULT_PATH environment variable.')
-    }
-
-    if (!existsSync(config.vaultPath)) {
-      serviceLogger.warn(
-        { vaultPath: config.vaultPath },
-        'Vault path does not exist - will be created on first use'
-      )
-    } else {
-      const projectsPath = path.join(config.vaultPath, 'Projects')
-      if (!existsSync(projectsPath)) {
-        serviceLogger.warn(
-          { projectsPath },
-          'Projects directory missing in vault - will be created when first project is added'
-        )
-      }
-    }
-
-    // Initialize Memory Manager
-    const memory = new MemoryManager(config.dbPath, logger)
-    await memory.initialize()
-    serviceLogger.info('Memory service initialized')
-
-    // Initialize Vault Manager
-    const vault = new VaultManager(config.vaultPath, logger, {
-      cacheEnabled: config.cacheSize > 0,
-      watchEnabled: config.enableFileWatch
-    })
-    await vault.initialize()
-    serviceLogger.info('Vault service initialized')
-
-    // Initialize Context Manager
-    const context = new ContextManager(logger, vault, memory)
-    serviceLogger.info('Context service initialized')
-
-    // Initialize Phase 12 Manager
-    const phase12 = new Phase12Manager(logger, vault, memory, context)
-    await phase12.initialize()
-    serviceLogger.info('Phase 12 service initialized')
-
-    // Initialize Retrieval Service (Phase 13) — requires ChromaDB
-    let retrieval: RetrievalService | null = null
-    if ((config.retrieval?.feedback?.enabled || config.retrieval?.enabled) && memory.isChromaDBEnabled()) {
-      retrieval = new RetrievalService(
-        logger,
-        memory.chroma.collections,
-        memory.chroma.embeddings,
-        config.retrieval
-      )
-      await retrieval.initialize()
-      serviceLogger.info('Retrieval service initialized')
-    } else if (config.retrieval?.enabled && !memory.isChromaDBEnabled()) {
-      serviceLogger.warn('Retrieval service requires ChromaDB, skipping initialization')
-    }
-
-    // Initialize Retrieval Pipeline (Phase 19) — hybrid search with BM25 + semantic + fusion
-    let retrievalPipeline: RetrievalPipeline | null = null
-    if (config.retrieval?.enabled && memory.isChromaDBEnabled()) {
-      try {
-        retrievalPipeline = new RetrievalPipeline(
-          logger,
-          memory.chroma.collections,
-          memory.chroma.embeddings,
-          config.retrieval
-        )
-        await retrievalPipeline.initialize()
-        serviceLogger.info('Retrieval pipeline initialized (hybrid search)')
-      } catch (error) {
-        serviceLogger.warn({ error }, 'Failed to initialize retrieval pipeline, continuing without hybrid search')
-      }
-    }
-
-    // Initialize Knowledge Graph Service (Phase 14)
-    let knowledgeGraph: KnowledgeGraphServiceContainer | null = null
-    if (config.knowledge?.graph?.enabled !== false) {
-      try {
-        const graph = new InMemoryKnowledgeGraph(logger)
-        const graphPersistPath = config.knowledge?.graph?.persistPath || './data/knowledge-graph.json'
-
-        // Load existing graph from disk
-        await graph.load(graphPersistPath)
-
-        const search = new GraphSearchEngine(graph, logger)
-        const builder = new KnowledgeGraphBuilder(graph, logger)
-        await builder.initialize()
-        const linker = new CrossReferenceLinker(graph, logger)
-
-        // Start auto-save
-        const autoSaveInterval = (config.knowledge?.graph?.autoSaveInterval || 60) * 1000
-        graph.startAutoSave(graphPersistPath, autoSaveInterval)
-
-        knowledgeGraph = { graph, search, builder, linker }
-
-        // Migrate existing decisions if graph is empty (requires ChromaDB)
-        if (graph.getNodeCount() === 0 && memory.isChromaDBEnabled()) {
-          serviceLogger.info('Empty graph detected, migrating existing decisions...')
-          const migrationResult = await builder.migrateExistingDecisions(memory.chroma.collections)
-          serviceLogger.info(
-            { processed: migrationResult.processed, errors: migrationResult.errors },
-            'Initial graph migration complete'
-          )
-        } else if (graph.getNodeCount() === 0) {
-          serviceLogger.info('Empty graph detected, but ChromaDB unavailable — graph will populate as new decisions are stored')
-        }
-
-        // Hook builder into decision storage for real-time graph population
-        // Uses MemoryManager listener so it works for both ChromaDB and SQLite paths
-        memory.addDecisionStoredListener((input) => {
-          builder.processDecision(input)
-        })
-
-        // Hook builder into decision deletion for graph synchronization
-        memory.addDecisionDeletedListener((id) => {
-          builder.removeDecision(id)
-
-          // Phase 20: Also unlink from active episodes
-          if (episodeManager) {
-            episodeManager.unlinkDecision(id)
-          }
-
-          // Phase 20: Invalidate semantic cache for deleted decisions
-          if (semanticCache) {
-            semanticCache.clear()
-          }
-        })
-
-        serviceLogger.info(
-          { nodes: graph.getNodeCount(), edges: graph.getEdgeCount() },
-          'Knowledge graph service initialized'
-        )
-      } catch (error) {
-        serviceLogger.warn({ error }, 'Failed to initialize knowledge graph, continuing without it')
-      }
-    }
-
-    // Initialize Episode Manager (Phase 14) — requires ChromaDB
-    let episodeManager: EpisodeManager | null = null
-    if (config.knowledge?.episodic?.enabled !== false && memory.isChromaDBEnabled()) {
-      try {
-        episodeManager = new EpisodeManager(
-          logger,
-          memory.chroma.collections,
-          memory.chroma.embeddings,
-          { sessionGapMinutes: config.knowledge?.episodic?.sessionGapMinutes || 30 }
-        )
-        serviceLogger.info('Episode manager initialized')
-      } catch (error) {
-        serviceLogger.warn({ error }, 'Failed to initialize episode manager, continuing without it')
-      }
-    }
-
-    // Initialize Session Tracker (Phase 21) — promoted from serve.ts
-    let sessionTracker: HookSessionTracker | null = null
-    if (config.hooks?.enabled !== false) {
-      try {
-        sessionTracker = new HookSessionTracker(logger, episodeManager, config.hooks?.sessions, memory)
-        serviceLogger.info('Session tracker initialized')
-      } catch (error) {
-        serviceLogger.warn({ error }, 'Failed to initialize session tracker, continuing without it')
-      }
-    }
-
-    // Initialize Semantic Cache & Precompute (Phase 15) — requires ChromaDB
-    let semanticCache: SemanticCache | null = null
-    let precompute: PrecomputeEngine | null = null
-    if (config.advancedIntelligence?.enabled !== false && config.advancedIntelligence?.cache?.enabled !== false && memory.isChromaDBEnabled()) {
-      try {
-        const cacheConfig = config.advancedIntelligence?.cache || {}
-        semanticCache = new SemanticCache(logger, {
-          maxSize: cacheConfig.maxSize || 1000,
-          ttlMs: cacheConfig.ttlMs || 60 * 60 * 1000,
-          similarityThreshold: cacheConfig.similarityThreshold || 0.80,
-          embeddings: memory.chroma.embeddings
-        })
-
-        precompute = new PrecomputeEngine(logger, memory.chroma.collections, semanticCache)
-        await precompute.initialize()
-        precompute.startAutoRefresh(5 * 60 * 1000) // Refresh every 5 minutes
-
-        serviceLogger.info('Phase 15 semantic cache & precompute initialized')
-      } catch (error) {
-        serviceLogger.warn({ error }, 'Failed to initialize Phase 15 caching, continuing without it')
-      }
-    }
-
-    // Store services
-    services = {
-      memory,
-      vault,
-      context,
-      phase12,
-      retrieval,
-      retrievalPipeline,
-      knowledgeGraph,
-      episodeManager,
-      sessionTracker,
-      semanticCache,
-      precompute,
-      logger,
-      config
-    }
-
-    serviceLogger.info('All services initialized successfully')
-  })()
-
-  await initializationPromise
-  return services!
-}
-
-/**
- * Get initialized services
- * Throws if services not initialized
- */
-export function getServices(): Services {
-  if (!services) {
-    throw new Error('Services not initialized. Call initializeServices() first.')
-  }
-  return services
-}
-
-/**
- * Get memory service
- * Throws if not initialized
- */
-export function getMemoryService(): MemoryManager {
-  return getServices().memory
-}
-
-/**
- * Get vault service
- * Throws if not initialized
- */
-export function getVaultService(): VaultManager {
-  return getServices().vault
-}
-
-export function getContextService(): ContextManager {
-  return getServices().context
-}
-
-/**
- * Get Phase 12 service
- * Throws if not initialized
- */
-export function getPhase12Service(): Phase12Manager {
-  return getServices().phase12
-}
-
-/**
- * Get Retrieval service
- * Returns null if retrieval is not enabled
- */
-export function getRetrievalService(): RetrievalService | null {
-  return getServices().retrieval
-}
-
-/**
- * Get Retrieval Pipeline (Phase 19)
- * Returns null if hybrid search is not enabled
- */
-export function getRetrievalPipeline(): RetrievalPipeline | null {
-  return getServices().retrievalPipeline
-}
-
-/**
- * Get Knowledge Graph service
- * Returns null if knowledge graph is not enabled
- */
-export function getKnowledgeGraphService(): KnowledgeGraphServiceContainer | null {
-  return getServices().knowledgeGraph
-}
-
-/**
- * Get Episode Manager service
- * Returns null if episodic memory is not enabled
- */
-export function getEpisodeService(): EpisodeManager | null {
-  return getServices().episodeManager
-}
-
-/**
- * Get Session Tracker service
- * Returns null if hooks are not enabled
- */
-export function getSessionTracker(): HookSessionTracker | null {
-  return getServices().sessionTracker
-}
-
-/**
- * Get Semantic Cache service
- * Returns null if caching is not enabled
- */
-export function getSemanticCacheService(): SemanticCache | null {
-  return getServices().semanticCache
-}
-
-/**
- * Get Precompute Engine service
- * Returns null if caching is not enabled
- */
-export function getPrecomputeService(): PrecomputeEngine | null {
-  return getServices().precompute
-}
-
-/**
- * Check if services are initialized
- */
-export function isServicesInitialized(): boolean {
-  return services !== null
-}
-
-/**
- * Inject services for testing
- * Allows tests to provide mock services without going through initializeServices
- * @internal - Only use in tests
- */
-export function _injectServicesForTesting(testServices: Services | null): void {
-  services = testServices
-}
-
-/**
- * Reset services for testing
- * Clears the services singleton without proper shutdown
- * @internal - Only use in tests
- */
-export function _resetServicesForTesting(): void {
-  services = null
-  initializationPromise = null
-}
-
-/**
- * Shutdown all services gracefully
- */
-export async function shutdownServices(): Promise<void> {
-  if (!services) {
-    return
-  }
-
-  const serviceLogger = services.logger.child({ component: 'services' })
-  serviceLogger.info('Shutting down services...')
-
-  // End all active sessions
-  if (services.sessionTracker) {
-    try {
-      await services.sessionTracker.endAllSessions()
-      serviceLogger.info('Session tracker shut down')
-    } catch (error) {
-      serviceLogger.error({ error }, 'Failed to end sessions on shutdown')
-    }
-  }
-
-  // Save and stop knowledge graph
-  if (services.knowledgeGraph) {
-    services.knowledgeGraph.graph.stopAutoSave()
-    const persistPath = services.config.knowledge?.graph?.persistPath || './data/knowledge-graph.json'
-    try {
-      await services.knowledgeGraph.graph.save(persistPath)
-      serviceLogger.info('Knowledge graph saved on shutdown')
-    } catch (error) {
-      serviceLogger.error({ error }, 'Failed to save knowledge graph on shutdown')
-    }
-  }
-
-  // Stop precompute auto-refresh
-  if (services.precompute) {
-    services.precompute.stopAutoRefresh()
-    serviceLogger.info('Precompute engine stopped')
-  }
-
-  // Clear semantic cache
-  if (services.semanticCache) {
-    services.semanticCache.clear()
-    serviceLogger.info('Semantic cache cleared')
-  }
-
-  // Cleanup Phase 12
-  services.phase12.cleanup()
-
-  // Stop vault watcher
-  services.vault.stopWatching()
-
-  // Close memory database
-  services.memory.close()
-
-  // Clear reference
-  services = null
-  initializationPromise = null
-
-  serviceLogger.info('All services shut down')
-}
+/**
+ * Shared Services Module
+ * Provides access to initialized services for tool handlers
+ */
+
+import type { Logger } from 'pino'
+import { existsSync } from 'fs'
+import * as path from 'path'
+import { MemoryManager } from '@/memory'
+import { VaultManager } from '@/vault'
+import { ContextManager } from '@/context'
+import { Phase12Manager } from '@/automation/phase12-manager'
+import { RetrievalService } from '@/retrieval/service'
+import { RetrievalPipeline } from '@/retrieval/pipeline'
+import { InMemoryKnowledgeGraph } from '@/knowledge/graph/memory-graph'
+import { GraphSearchEngine } from '@/knowledge/graph/search'
+import { KnowledgeGraphBuilder } from '@/knowledge/graph/builder'
+import { CrossReferenceLinker } from '@/knowledge/graph/linker'
+import { EpisodeManager } from '@/memory/episodic/manager'
+import { HookSessionTracker } from '@/hooks/session-tracker'
+import type { Config } from '@/config'
+import { SemanticCache } from '@/intelligence/optimization/semantic-cache'
+import { PrecomputeEngine } from '@/intelligence/optimization/precompute'
+
+export interface KnowledgeGraphServiceContainer {
+  graph: InMemoryKnowledgeGraph
+  search: GraphSearchEngine
+  builder: KnowledgeGraphBuilder
+  linker: CrossReferenceLinker
+}
+
+/**
+ * Container for all shared services
+ */
+export interface Services {
+  memory: MemoryManager
+  vault: VaultManager
+  context: ContextManager
+  phase12: Phase12Manager
+  retrieval: RetrievalService | null
+  retrievalPipeline: RetrievalPipeline | null
+  knowledgeGraph: KnowledgeGraphServiceContainer | null
+  episodeManager: EpisodeManager | null
+  sessionTracker: HookSessionTracker | null
+  semanticCache: SemanticCache | null
+  precompute: PrecomputeEngine | null
+  logger: Logger
+  config: Config
+}
+
+// Singleton services instance
+let services: Services | null = null
+let initializationPromise: Promise<void> | null = null
+
+/**
+ * Initialize all services
+ * Should be called once during server startup
+ */
+export async function initializeServices(config: Config, logger: Logger): Promise<Services> {
+  // If already initialized, return existing services
+  if (services) {
+    logger.debug('Services already initialized')
+    return services
+  }
+
+  // If initialization is in progress, wait for it
+  if (initializationPromise) {
+    await initializationPromise
+    return services!
+  }
+
+  // Start initialization
+  initializationPromise = (async () => {
+    const serviceLogger = logger.child({ component: 'services' })
+    serviceLogger.info('Initializing services...')
+
+    // Validate vault path configuration
+    if (!config.vaultPath) {
+      throw new Error('Vault path not configured. Set VAULT_PATH environment variable.')
+    }
+
+    if (!existsSync(config.vaultPath)) {
+      serviceLogger.warn(
+        { vaultPath: config.vaultPath },
+        'Vault path does not exist - will be created on first use'
+      )
+    } else {
+      const projectsPath = path.join(config.vaultPath, 'Projects')
+      if (!existsSync(projectsPath)) {
+        serviceLogger.warn(
+          { projectsPath },
+          'Projects directory missing in vault - will be created when first project is added'
+        )
+      }
+    }
+
+    // Initialize Memory Manager
+    const memory = new MemoryManager(config.dbPath, logger)
+    await memory.initialize()
+    serviceLogger.info('Memory service initialized')
+
+    // Initialize Vault Manager
+    const vault = new VaultManager(config.vaultPath, logger, {
+      cacheEnabled: config.cacheSize > 0,
+      watchEnabled: config.enableFileWatch
+    })
+    await vault.initialize()
+    serviceLogger.info('Vault service initialized')
+
+    // Initialize Context Manager
+    const context = new ContextManager(logger, vault, memory)
+    serviceLogger.info('Context service initialized')
+
+    // Initialize Phase 12 Manager
+    const phase12 = new Phase12Manager(logger, vault, memory, context)
+    await phase12.initialize()
+    serviceLogger.info('Phase 12 service initialized')
+
+    // Initialize Retrieval Service (Phase 13) — requires ChromaDB
+    let retrieval: RetrievalService | null = null
+    if ((config.retrieval?.feedback?.enabled || config.retrieval?.enabled) && memory.isChromaDBEnabled()) {
+      retrieval = new RetrievalService(
+        logger,
+        memory.chroma.collections,
+        memory.chroma.embeddings,
+        config.retrieval
+      )
+      await retrieval.initialize()
+      serviceLogger.info('Retrieval service initialized')
+    } else if (config.retrieval?.enabled && !memory.isChromaDBEnabled()) {
+      serviceLogger.warn('Retrieval service requires ChromaDB, skipping initialization')
+    }
+
+    // Initialize Retrieval Pipeline (Phase 19) — hybrid search with BM25 + semantic + fusion
+    let retrievalPipeline: RetrievalPipeline | null = null
+    if (config.retrieval?.enabled && memory.isChromaDBEnabled()) {
+      try {
+        retrievalPipeline = new RetrievalPipeline(
+          logger,
+          memory.chroma.collections,
+          memory.chroma.embeddings,
+          config.retrieval
+        )
+        await retrievalPipeline.initialize()
+        serviceLogger.info('Retrieval pipeline initialized (hybrid search)')
+      } catch (error) {
+        serviceLogger.warn({ error }, 'Failed to initialize retrieval pipeline, continuing without hybrid search')
+      }
+    }
+
+    // Initialize Knowledge Graph Service (Phase 14)
+    let knowledgeGraph: KnowledgeGraphServiceContainer | null = null
+    if (config.knowledge?.graph?.enabled !== false) {
+      try {
+        const graph = new InMemoryKnowledgeGraph(logger)
+        const graphPersistPath = config.knowledge?.graph?.persistPath || './data/knowledge-graph.json'
+
+        // Load existing graph from disk
+        await graph.load(graphPersistPath)
+
+        const search = new GraphSearchEngine(graph, logger)
+        const builder = new KnowledgeGraphBuilder(graph, logger)
+        await builder.initialize()
+        const linker = new CrossReferenceLinker(graph, logger)
+
+        // Start auto-save
+        const autoSaveInterval = (config.knowledge?.graph?.autoSaveInterval || 60) * 1000
+        graph.startAutoSave(graphPersistPath, autoSaveInterval)
+
+        knowledgeGraph = { graph, search, builder, linker }
+
+        // Migrate existing decisions if graph is empty (requires ChromaDB)
+        if (graph.getNodeCount() === 0 && memory.isChromaDBEnabled()) {
+          serviceLogger.info('Empty graph detected, migrating existing decisions...')
+          const migrationResult = await builder.migrateExistingDecisions(memory.chroma.collections)
+          serviceLogger.info(
+            { processed: migrationResult.processed, errors: migrationResult.errors },
+            'Initial graph migration complete'
+          )
+        } else if (graph.getNodeCount() === 0) {
+          serviceLogger.info('Empty graph detected, but ChromaDB unavailable — graph will populate as new decisions are stored')
+        }
+
+        // Hook builder into decision storage for real-time graph population
+        // Uses MemoryManager listener so it works for both ChromaDB and SQLite paths
+        memory.addDecisionStoredListener((input) => {
+          builder.processDecision(input)
+        })
+
+        // Hook builder into decision deletion for graph synchronization
+        memory.addDecisionDeletedListener((id) => {
+          builder.removeDecision(id)
+
+          // Phase 20: Also unlink from active episodes
+          if (episodeManager) {
+            episodeManager.unlinkDecision(id)
+          }
+
+          // Phase 20: Invalidate semantic cache for deleted decisions
+          if (semanticCache) {
+            semanticCache.clear()
+          }
+        })
+
+        serviceLogger.info(
+          { nodes: graph.getNodeCount(), edges: graph.getEdgeCount() },
+          'Knowledge graph service initialized'
+        )
+      } catch (error) {
+        serviceLogger.warn({ error }, 'Failed to initialize knowledge graph, continuing without it')
+      }
+    }
+
+    // Initialize Episode Manager (Phase 14) — requires ChromaDB
+    let episodeManager: EpisodeManager | null = null
+    if (config.knowledge?.episodic?.enabled !== false && memory.isChromaDBEnabled()) {
+      try {
+        episodeManager = new EpisodeManager(
+          logger,
+          memory.chroma.collections,
+          memory.chroma.embeddings,
+          { sessionGapMinutes: config.knowledge?.episodic?.sessionGapMinutes || 30 }
+        )
+        serviceLogger.info('Episode manager initialized')
+      } catch (error) {
+        serviceLogger.warn({ error }, 'Failed to initialize episode manager, continuing without it')
+      }
+    }
+
+    // Initialize Session Tracker (Phase 21) — promoted from serve.ts
+    let sessionTracker: HookSessionTracker | null = null
+    if (config.hooks?.enabled !== false) {
+      try {
+        sessionTracker = new HookSessionTracker(logger, episodeManager, config.hooks?.sessions, memory)
+        serviceLogger.info('Session tracker initialized')
+      } catch (error) {
+        serviceLogger.warn({ error }, 'Failed to initialize session tracker, continuing without it')
+      }
+    }
+
+    // Initialize Semantic Cache & Precompute (Phase 15) — requires ChromaDB
+    let semanticCache: SemanticCache | null = null
+    let precompute: PrecomputeEngine | null = null
+    if (config.advancedIntelligence?.enabled !== false && config.advancedIntelligence?.cache?.enabled !== false && memory.isChromaDBEnabled()) {
+      try {
+        const cacheConfig = config.advancedIntelligence?.cache || {}
+        semanticCache = new SemanticCache(logger, {
+          maxSize: cacheConfig.maxSize || 1000,
+          ttlMs: cacheConfig.ttlMs || 60 * 60 * 1000,
+          similarityThreshold: cacheConfig.similarityThreshold || 0.80,
+          embeddings: memory.chroma.embeddings
+        })
+
+        precompute = new PrecomputeEngine(logger, memory.chroma.collections, semanticCache)
+        await precompute.initialize()
+        precompute.startAutoRefresh(5 * 60 * 1000) // Refresh every 5 minutes
+
+        serviceLogger.info('Phase 15 semantic cache & precompute initialized')
+      } catch (error) {
+        serviceLogger.warn({ error }, 'Failed to initialize Phase 15 caching, continuing without it')
+      }
+    }
+
+    // Store services
+    services = {
+      memory,
+      vault,
+      context,
+      phase12,
+      retrieval,
+      retrievalPipeline,
+      knowledgeGraph,
+      episodeManager,
+      sessionTracker,
+      semanticCache,
+      precompute,
+      logger,
+      config
+    }
+
+    serviceLogger.info('All services initialized successfully')
+  })()
+
+  await initializationPromise
+  return services!
+}
+
+/**
+ * Get initialized services
+ * Throws if services not initialized
+ */
+export function getServices(): Services {
+  if (!services) {
+    throw new Error('Services not initialized. Call initializeServices() first.')
+  }
+  return services
+}
+
+/**
+ * Get memory service
+ * Throws if not initialized
+ */
+export function getMemoryService(): MemoryManager {
+  return getServices().memory
+}
+
+/**
+ * Get vault service
+ * Throws if not initialized
+ */
+export function getVaultService(): VaultManager {
+  return getServices().vault
+}
+
+export function getContextService(): ContextManager {
+  return getServices().context
+}
+
+/**
+ * Get Phase 12 service
+ * Throws if not initialized
+ */
+export function getPhase12Service(): Phase12Manager {
+  return getServices().phase12
+}
+
+/**
+ * Get Retrieval service
+ * Returns null if retrieval is not enabled
+ */
+export function getRetrievalService(): RetrievalService | null {
+  return getServices().retrieval
+}
+
+/**
+ * Get Retrieval Pipeline (Phase 19)
+ * Returns null if hybrid search is not enabled
+ */
+export function getRetrievalPipeline(): RetrievalPipeline | null {
+  return getServices().retrievalPipeline
+}
+
+/**
+ * Get Knowledge Graph service
+ * Returns null if knowledge graph is not enabled
+ */
+export function getKnowledgeGraphService(): KnowledgeGraphServiceContainer | null {
+  return getServices().knowledgeGraph
+}
+
+/**
+ * Get Episode Manager service
+ * Returns null if episodic memory is not enabled
+ */
+export function getEpisodeService(): EpisodeManager | null {
+  return getServices().episodeManager
+}
+
+/**
+ * Get Session Tracker service
+ * Returns null if hooks are not enabled
+ */
+export function getSessionTracker(): HookSessionTracker | null {
+  return getServices().sessionTracker
+}
+
+/**
+ * Get Semantic Cache service
+ * Returns null if caching is not enabled
+ */
+export function getSemanticCacheService(): SemanticCache | null {
+  return getServices().semanticCache
+}
+
+/**
+ * Get Precompute Engine service
+ * Returns null if caching is not enabled
+ */
+export function getPrecomputeService(): PrecomputeEngine | null {
+  return getServices().precompute
+}
+
+/**
+ * Check if services are initialized
+ */
+export function isServicesInitialized(): boolean {
+  return services !== null
+}
+
+/**
+ * Inject services for testing
+ * Allows tests to provide mock services without going through initializeServices
+ * @internal - Only use in tests
+ */
+export function _injectServicesForTesting(testServices: Services | null): void {
+  services = testServices
+}
+
+/**
+ * Reset services for testing
+ * Clears the services singleton without proper shutdown
+ * @internal - Only use in tests
+ */
+export function _resetServicesForTesting(): void {
+  services = null
+  initializationPromise = null
+}
+
+/**
+ * Shutdown all services gracefully
+ */
+export async function shutdownServices(): Promise<void> {
+  if (!services) {
+    return
+  }
+
+  const serviceLogger = services.logger.child({ component: 'services' })
+  serviceLogger.info('Shutting down services...')
+
+  // End all active sessions
+  if (services.sessionTracker) {
+    try {
+      await services.sessionTracker.endAllSessions()
+      serviceLogger.info('Session tracker shut down')
+    } catch (error) {
+      serviceLogger.error({ error }, 'Failed to end sessions on shutdown')
+    }
+  }
+
+  // Save and stop knowledge graph
+  if (services.knowledgeGraph) {
+    services.knowledgeGraph.graph.stopAutoSave()
+    const persistPath = services.config.knowledge?.graph?.persistPath || './data/knowledge-graph.json'
+    try {
+      await services.knowledgeGraph.graph.save(persistPath)
+      serviceLogger.info('Knowledge graph saved on shutdown')
+    } catch (error) {
+      serviceLogger.error({ error }, 'Failed to save knowledge graph on shutdown')
+    }
+  }
+
+  // Stop precompute auto-refresh
+  if (services.precompute) {
+    services.precompute.stopAutoRefresh()
+    serviceLogger.info('Precompute engine stopped')
+  }
+
+  // Clear semantic cache
+  if (services.semanticCache) {
+    services.semanticCache.clear()
+    serviceLogger.info('Semantic cache cleared')
+  }
+
+  // Cleanup Phase 12
+  services.phase12.cleanup()
+
+  // Stop vault watcher
+  services.vault.stopWatching()
+
+  // Close memory database
+  services.memory.close()
+
+  // Clear reference
+  services = null
+  initializationPromise = null
+
+  serviceLogger.info('All services shut down')
+}