claude-memory-layer 1.0.27 → 1.0.28

package/src/services/memory-service.ts

@@ -3,479 +3,170 @@
  * Coordinates EventStore, VectorStore, Retriever, and Graduation
  */
 
-import * as path from 'path';
 import * as os from 'os';
-import * as fs from 'fs';
-import * as crypto from 'crypto';
-
-import { EventStore } from '../core/event-store.js';
-import { SQLiteEventStore } from '../core/sqlite-event-store.js';
-import { VectorStore } from '../core/vector-store.js';
-import { Embedder, getDefaultEmbedder } from '../core/embedder.js';
-import { VectorWorker, createVectorWorker } from '../core/vector-worker.js';
-import { Matcher, getDefaultMatcher } from '../core/matcher.js';
-import { Retriever, createRetriever, RetrievalResult, UnifiedRetrievalResult } from '../core/retriever.js';
-import { GraduationPipeline, createGraduationPipeline } from '../core/graduation.js';
-import { SharedEventStore, createSharedEventStore } from '../core/shared-event-store.js';
-import { SharedStore, createSharedStore } from '../core/shared-store.js';
-import { SharedVectorStore, createSharedVectorStore } from '../core/shared-vector-store.js';
-import { SharedPromoter, createSharedPromoter, PromotionResult } from '../core/shared-promoter.js';
+
+import type { RetrievalResult, UnifiedRetrievalResult } from '../core/retriever.js';
+import type { PromotionResult } from '../core/shared-promoter.js';
+import type { SharedMemoryServices } from '../extensions/shared-memory/index.js';
 import type {
-  MemoryEventInput,
   AppendResult,
   MemoryEvent,
-  Config,
-  ConfigSchema,
   ToolObservationPayload,
   MemoryMode,
   EndlessModeConfig,
-  EndlessModeConfigSchema,
   WorkingSet,
   ConsolidatedMemory,
   EndlessModeStatus,
-  ContextSnapshot,
   ContinuityScore,
   SharedStoreConfig,
   Entry
 } from '../core/types.js';
-import { createToolObservationEmbedding } from '../core/metadata-extractor.js';
-import { WorkingSetStore, createWorkingSetStore } from '../core/working-set-store.js';
-import { ConsolidatedStore, createConsolidatedStore } from '../core/consolidated-store.js';
-import { ConsolidationWorker, createConsolidationWorker } from '../core/consolidation-worker.js';
-import { ContinuityManager, createContinuityManager } from '../core/continuity-manager.js';
-import { GraduationWorker, createGraduationWorker, GraduationRunResult } from '../core/graduation-worker.js';
-import { MarkdownMirror } from '../core/md-mirror.js';
+import type { EndlessMemoryServices } from '../extensions/endless-memory/index.js';
 import {
-  IngestInterceptor,
-  IngestInterceptorRegistry,
-  mergeHierarchicalMetadata
-} from '../core/ingest-interceptor.js';
-import { normalizeTags } from '../core/tag-taxonomy.js';
-
-export interface MemoryServiceConfig {
-  storagePath: string;
-  embeddingModel?: string;
-  readOnly?: boolean;
-  /** Enable DuckDB analytics store (default: true for server, false for hooks) */
-  analyticsEnabled?: boolean;
-  /** Lightweight mode for hooks - skip heavy initialization (default: false) */
-  lightweightMode?: boolean;
-  /** Start only VectorWorker, skip GraduationWorker and SyncWorker (default: false) */
-  embeddingOnly?: boolean;
-}
-
-// ============================================================
-// Project Path Utilities
-// ============================================================
-
-/**
- * Normalize and resolve a project path, handling symlinks
- */
-function normalizePath(projectPath: string): string {
-  const expanded = projectPath.startsWith('~')
-    ? path.join(os.homedir(), projectPath.slice(1))
-    : projectPath;
-
-  try {
-    // Resolve symlinks for consistent paths
-    return fs.realpathSync(expanded);
-  } catch {
-    // Path doesn't exist yet, just resolve it
-    return path.resolve(expanded);
-  }
-}
-
-/**
- * Generate a stable 8-character hash from a project path
- */
-export function hashProjectPath(projectPath: string): string {
-  const normalizedPath = normalizePath(projectPath);
-  return crypto.createHash('sha256')
-    .update(normalizedPath)
-    .digest('hex')
-    .slice(0, 8);
-}
-
-/**
- * Get the storage path for a specific project
- */
-export function getProjectStoragePath(projectPath: string): string {
-  const hash = hashProjectPath(projectPath);
-  return path.join(os.homedir(), '.claude-code', 'memory', 'projects', hash);
-}
-
-// ============================================================
-// Session Registry
-// ============================================================
-
-const REGISTRY_PATH = path.join(os.homedir(), '.claude-code', 'memory', 'session-registry.json');
-const SHARED_STORAGE_PATH = path.join(os.homedir(), '.claude-code', 'memory', 'shared');
-
-export interface SessionRegistryEntry {
-  projectPath: string;
-  projectHash: string;
-  registeredAt: string;
-}
-
-export interface SessionRegistry {
-  version: number;
-  sessions: Record<string, SessionRegistryEntry>;
-}
-
-export function loadSessionRegistry(): SessionRegistry {
-  try {
-    if (fs.existsSync(REGISTRY_PATH)) {
-      const data = fs.readFileSync(REGISTRY_PATH, 'utf-8');
-      return JSON.parse(data);
-    }
-  } catch (error) {
-    console.error('Failed to load session registry:', error);
-  }
-  return { version: 1, sessions: {} };
-}
-
-function saveSessionRegistry(registry: SessionRegistry): void {
-  const dir = path.dirname(REGISTRY_PATH);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-
-  // Atomic write using temp file
-  const tempPath = REGISTRY_PATH + '.tmp';
-  fs.writeFileSync(tempPath, JSON.stringify(registry, null, 2));
-  fs.renameSync(tempPath, REGISTRY_PATH);
-}
-
-/**
- * Register a session with its project path
- */
-export function registerSession(sessionId: string, projectPath: string): void {
-  const registry = loadSessionRegistry();
-
-  registry.sessions[sessionId] = {
-    projectPath: normalizePath(projectPath),
-    projectHash: hashProjectPath(projectPath),
-    registeredAt: new Date().toISOString()
-  };
-
-  // Clean up old sessions (keep last 1000)
-  const entries = Object.entries(registry.sessions);
-  if (entries.length > 1000) {
-    const sorted = entries.sort((a, b) =>
-      new Date(b[1].registeredAt).getTime() - new Date(a[1].registeredAt).getTime()
-    );
-    registry.sessions = Object.fromEntries(sorted.slice(0, 1000));
-  }
-
-  saveSessionRegistry(registry);
-}
-
-/**
- * Get the project path for a session
- */
-export function getSessionProject(sessionId: string): SessionRegistryEntry | null {
-  const registry = loadSessionRegistry();
-  return registry.sessions[sessionId] || null;
-}
+  type EmbeddingMaintenanceService,
+  type EmbeddingModelMaintenanceOptions,
+  type EmbeddingModelMaintenanceResult
+} from '../core/engine/embedding-maintenance-service.js';
+import type { MemoryRuntimeService } from '../core/engine/memory-runtime-service.js';
+import type { GraduationRunResult } from '../core/graduation-worker.js';
+import type { IngestInterceptor } from '../core/ingest-interceptor.js';
+import type { MemoryIngestService } from '../core/engine/memory-ingest-service.js';
+import type { MemoryQueryService } from '../core/engine/memory-query-service.js';
+import { createMemoryServiceComposition } from '../core/engine/memory-service-composition.js';
+import {
+  getProjectStoragePath as defaultGetProjectStoragePath,
+  hashProjectPath as defaultHashProjectPath
+} from '../core/registry/project-path.js';
+import { getSessionProject as defaultGetSessionProject } from '../core/registry/session-registry.js';
+import {
+  DEFAULT_ENABLED_SHARED_STORE_CONFIG,
+  DEFAULT_SHARED_STORAGE_PATH,
+  DISABLED_SHARED_STORE_CONFIG,
+  type MemoryServiceConfig
+} from './memory-service-config.js';
+import { createMemoryServiceRegistry } from './memory-service-registry.js';
+import {
+  type AccessedMemory,
+  type HelpfulMemory,
+  type HelpfulnessStats,
+  type RecordQueryTraceInput,
+  type RetrievalAnalyticsService,
+  type RetrievalDisclosureExpansion,
+  type RetrievalDisclosureExpandOptions,
+  type RetrievalDisclosureSearchOptions,
+  type RetrievalDisclosureSearchResponse,
+  type RetrievalDisclosureService,
+  type RetrievalDisclosureSource,
+  type RetrievalOrchestrator,
+  type RetrievalTrace,
+  type RetrievalTraceStats,
+  type RetrieveMemoriesOptions
+} from '../core/engine/retrieval-services.js';
+export { getProjectStoragePath, hashProjectPath } from '../core/registry/project-path.js';
+export {
+  getSessionProject,
+  registerSession,
+  type SessionRegistry,
+  type SessionRegistryEntry,
+  loadSessionRegistry
+} from '../core/registry/session-registry.js';
+
+export {
+  DEFAULT_ENABLED_SHARED_STORE_CONFIG,
+  DEFAULT_SHARED_STORAGE_PATH,
+  DISABLED_SHARED_STORE_CONFIG,
+  type MemoryServiceConfig
+} from './memory-service-config.js';
 
 export class MemoryService {
-  // Primary store: SQLite (WAL mode) - for hooks, always available
-  private readonly sqliteStore: SQLiteEventStore;
-
-  private readonly vectorStore: VectorStore;
-  private readonly embedder: Embedder;
-  private readonly matcher: Matcher;
-  private readonly retriever: Retriever;
-  private readonly graduation: GraduationPipeline;
-  private vectorWorker: VectorWorker | null = null;
-  private graduationWorker: GraduationWorker | null = null;
-  private initialized = false;
-  private readonly ingestInterceptors = new IngestInterceptorRegistry();
+  private readonly retrievalOrchestrator: RetrievalOrchestrator;
+  private readonly retrievalDisclosureService: RetrievalDisclosureService;
+  private readonly retrievalAnalyticsService: RetrievalAnalyticsService;
+  private readonly embeddingMaintenanceService: EmbeddingMaintenanceService;
+  private readonly runtimeService: MemoryRuntimeService;
 
   // Endless Mode components
-  private workingSetStore: WorkingSetStore | null = null;
-  private consolidatedStore: ConsolidatedStore | null = null;
-  private consolidationWorker: ConsolidationWorker | null = null;
-  private continuityManager: ContinuityManager | null = null;
-  private endlessMode: MemoryMode = 'session';
+  private readonly endlessMemoryServices: EndlessMemoryServices;
 
   // Shared Store components (cross-project knowledge)
-  private sharedEventStore: SharedEventStore | null = null;
-  private sharedStore: SharedStore | null = null;
-  private sharedVectorStore: SharedVectorStore | null = null;
-  private sharedPromoter: SharedPromoter | null = null;
-  private sharedStoreConfig: SharedStoreConfig | null = null;
+  private sharedMemoryServices!: SharedMemoryServices;
   private projectHash: string | null = null;
   private projectPath: string | null = null;
 
   private readonly readOnly: boolean;
   private readonly lightweightMode: boolean;
   private readonly embeddingOnly: boolean;
-  private readonly mdMirror: MarkdownMirror;
-  private readonly storagePath: string;
+  private readonly ingestService: MemoryIngestService;
+  private readonly queryService: MemoryQueryService;
 
   constructor(config: MemoryServiceConfig & { projectHash?: string; projectPath?: string; sharedStoreConfig?: SharedStoreConfig }) {
-    const storagePath = this.expandPath(config.storagePath);
-    this.storagePath = storagePath;
     this.readOnly = config.readOnly ?? false;
     this.lightweightMode = config.lightweightMode ?? false;
     this.embeddingOnly = config.embeddingOnly ?? false;
-    this.mdMirror = new MarkdownMirror(process.cwd());
-
-    // Ensure storage directory exists (only if not read-only)
-    if (!this.readOnly && !fs.existsSync(storagePath)) {
-      fs.mkdirSync(storagePath, { recursive: true });
-    }
 
     // Store project hash for shared store operations
     this.projectHash = config.projectHash || null;
     this.projectPath = config.projectPath || null;
-    // Default: shared store enabled
-    this.sharedStoreConfig = config.sharedStoreConfig ?? { enabled: true };
-
-    // Initialize PRIMARY store: SQLite (WAL mode)
-    // This is always used for writes and is the source of truth
-    this.sqliteStore = new SQLiteEventStore(
-      path.join(storagePath, 'events.sqlite'),
-      {
-        readonly: this.readOnly,
-        markdownMirrorRoot: storagePath
-      }
-    );
-
-    this.vectorStore = new VectorStore(path.join(storagePath, 'vectors'));
-    const embeddingModel = config.embeddingModel || process.env.CLAUDE_MEMORY_EMBEDDING_MODEL;
-    this.embedder = embeddingModel
-      ? new Embedder(embeddingModel)
-      : getDefaultEmbedder();
-    this.matcher = getDefaultMatcher();
-    // Retriever uses SQLite as primary (always available)
-    this.retriever = createRetriever(
-      this.sqliteStore as unknown as EventStore, // Interface compatible
-      this.vectorStore,
-      this.embedder,
-      this.matcher
-    );
-    this.retriever.setQueryRewriter((q) => this.rewriteQueryIntent(q));
-    this.graduation = createGraduationPipeline(this.sqliteStore as unknown as EventStore);
+    const sharedStoreConfig = config.sharedStoreConfig ?? DEFAULT_ENABLED_SHARED_STORE_CONFIG;
+
+    const composition = createMemoryServiceComposition({
+      config: {
+        ...config,
+        storagePath: config.storagePath,
+        readOnly: this.readOnly,
+        lightweightMode: this.lightweightMode,
+        embeddingOnly: this.embeddingOnly,
+        sharedStoreConfig
+      },
+      defaultSharedStoragePath: DEFAULT_SHARED_STORAGE_PATH,
+      defaultSharedStoreConfig: DEFAULT_ENABLED_SHARED_STORE_CONFIG,
+      initialize: () => this.initialize(),
+      getProjectHash: () => this.projectHash,
+      getProjectPath: () => this.projectPath
+    });
+
+    this.retrievalOrchestrator = composition.retrievalOrchestrator;
+    this.retrievalDisclosureService = composition.retrievalDisclosureService;
+    this.retrievalAnalyticsService = composition.retrievalAnalyticsService;
+    this.ingestService = composition.ingestService;
+    this.queryService = composition.queryService;
+    this.endlessMemoryServices = composition.endlessMemoryServices;
+    this.sharedMemoryServices = composition.sharedMemoryServices;
+    this.runtimeService = composition.runtimeService;
+    this.embeddingMaintenanceService = composition.embeddingMaintenanceService;
   }
 
   /**
    * Initialize all components
    */
   async initialize(): Promise<void> {
-    if (this.initialized) return;
-
-    // Initialize PRIMARY store: SQLite (always)
-    await this.sqliteStore.initialize();
-
-    // Lightweight mode: only SQLite, no embedder/vector/workers
-    // Used for hooks that just need to store data quickly
-    if (this.lightweightMode) {
-      this.initialized = true;
-      return;
-    }
-
-    await this.vectorStore.initialize();
-    await this.embedder.initialize();
-
-    // Skip write-related workers in read-only mode
-    if (!this.readOnly) {
-      // Start vector worker (uses SQLite as source)
-      this.vectorWorker = createVectorWorker(
-        this.sqliteStore as unknown as EventStore,
-        this.vectorStore,
-        this.embedder
-      );
-      this.vectorWorker.start();
-
-      if (!this.embeddingOnly) {
-        // Connect graduation pipeline to retriever for access tracking
-        this.retriever.setGraduationPipeline(this.graduation);
-
-        // Start graduation worker for automatic level promotion
-        this.graduationWorker = createGraduationWorker(
-          this.sqliteStore as unknown as EventStore,
-          this.graduation
-        );
-        this.graduationWorker.start();
-
-      }
-
-      // Load endless mode setting
-      const savedMode = await this.sqliteStore.getEndlessConfig('mode') as MemoryMode | null;
-      if (savedMode === 'endless') {
-        this.endlessMode = 'endless';
-        await this.initializeEndlessMode();
-      }
-
-      // Initialize shared store (enabled by default)
-      if (this.sharedStoreConfig?.enabled !== false) {
-        await this.initializeSharedStore();
-      }
-    }
-
-    this.initialized = true;
-  }
-
-  /**
-   * Initialize Shared Store components
-   */
-  private async initializeSharedStore(): Promise<void> {
-    const sharedPath = this.sharedStoreConfig?.sharedStoragePath
-      ? this.expandPath(this.sharedStoreConfig.sharedStoragePath)
-      : SHARED_STORAGE_PATH;
-
-    // Ensure shared directory exists
-    if (!fs.existsSync(sharedPath)) {
-      fs.mkdirSync(sharedPath, { recursive: true });
-    }
-
-    this.sharedEventStore = createSharedEventStore(
-      path.join(sharedPath, 'shared.duckdb')
-    );
-    await this.sharedEventStore.initialize();
-
-    this.sharedStore = createSharedStore(this.sharedEventStore);
-    this.sharedVectorStore = createSharedVectorStore(
-      path.join(sharedPath, 'vectors')
-    );
-    await this.sharedVectorStore.initialize();
-
-    this.sharedPromoter = createSharedPromoter(
-      this.sharedStore,
-      this.sharedVectorStore,
-      this.embedder,
-      this.sharedStoreConfig || undefined
-    );
-
-    // Connect shared stores to retriever
-    this.retriever.setSharedStores(this.sharedStore, this.sharedVectorStore);
+    await this.runtimeService.initialize();
   }
 
   registerIngestBefore(interceptor: IngestInterceptor): () => void {
-    return this.ingestInterceptors.registerBefore(interceptor);
+    return this.ingestService.registerIngestBefore(interceptor);
   }
 
   registerIngestAfter(interceptor: IngestInterceptor): () => void {
-    return this.ingestInterceptors.registerAfter(interceptor);
+    return this.ingestService.registerIngestAfter(interceptor);
   }
 
   registerIngestOnError(interceptor: IngestInterceptor): () => void {
-    return this.ingestInterceptors.registerOnError(interceptor);
-  }
-
-  private async ingestWithInterceptors(
-    operation: 'user_prompt' | 'agent_response' | 'session_summary' | 'tool_observation',
-    input: MemoryEventInput,
-    onSuccess?: (eventId: string) => Promise<void>
-  ): Promise<AppendResult> {
-    const normalizedInput: MemoryEventInput = {
-      ...input,
-      metadata: mergeHierarchicalMetadata(
-        {
-          ingest: {
-            operation,
-            pipeline: 'default',
-            ts: new Date().toISOString()
-          },
-          ...(this.projectHash
-            ? {
-                scope: {
-                  project: {
-                    hash: this.projectHash,
-                    ...(this.projectPath ? { path: this.projectPath } : {})
-                  }
-                },
-                tags: [`proj:${this.projectHash}`]
-              }
-            : {})
-        },
-        input.metadata
-      )
-    };
-
-    if (this.projectHash && normalizedInput.metadata) {
-      const meta = normalizedInput.metadata as Record<string, unknown>;
-      const currentTags = Array.isArray(meta.tags)
-        ? meta.tags.filter((x): x is string => typeof x === 'string')
-        : [];
-      const projectTag = `proj:${this.projectHash}`;
-      if (!currentTags.includes(projectTag)) {
-        meta.tags = [...currentTags, projectTag];
-      }
-    }
-
-    if (normalizedInput.metadata) {
-      const meta = normalizedInput.metadata as Record<string, unknown>;
-      const normalizedTags = normalizeTags(meta.tags);
-      if (normalizedTags.length > 0) {
-        meta.tags = normalizedTags;
-      }
-    }
-
-    await this.ingestInterceptors.run('before', {
-      operation,
-      sessionId: normalizedInput.sessionId,
-      event: normalizedInput
-    });
-
-    try {
-      const result = await this.sqliteStore.append(normalizedInput);
-      if (result.success && !result.isDuplicate) {
-        if (onSuccess) {
-          await onSuccess(result.eventId);
-        }
-        try {
-          await this.mdMirror.append(normalizedInput, result.eventId);
-        } catch {
-          // non-breaking markdown mirror write
-        }
-      }
-
-      await this.ingestInterceptors.run('after', {
-        operation,
-        sessionId: normalizedInput.sessionId,
-        event: normalizedInput
-      });
-
-      return result;
-    } catch (error) {
-      const normalizedError = error instanceof Error ? error : new Error(String(error));
-      await this.ingestInterceptors.run('error', {
-        operation,
-        sessionId: normalizedInput.sessionId,
-        event: normalizedInput,
-        error: normalizedError
-      });
-      throw error;
-    }
+    return this.ingestService.registerIngestOnError(interceptor);
   }
 
   /**
    * Start a new session
    */
   async startSession(sessionId: string, projectPath?: string): Promise<void> {
-    await this.initialize();
-
-    await this.sqliteStore.upsertSession({
-      id: sessionId,
-      startedAt: new Date(),
-      projectPath
-    });
+    return this.ingestService.startSession(sessionId, projectPath);
   }
 
   /**
    * End a session
    */
   async endSession(sessionId: string, summary?: string): Promise<void> {
-    await this.initialize();
-
-    await this.sqliteStore.upsertSession({
-      id: sessionId,
-      endedAt: new Date(),
-      summary
-    });
+    return this.ingestService.endSession(sessionId, summary);
   }
 
   /**
@@ -486,21 +177,7 @@ export class MemoryService {
     content: string,
     metadata?: Record<string, unknown>
   ): Promise<AppendResult> {
-    await this.initialize();
-
-    return this.ingestWithInterceptors(
-      'user_prompt',
-      {
-        eventType: 'user_prompt',
-        sessionId,
-        timestamp: new Date(),
-        content,
-        metadata
-      },
-      async (eventId) => {
-        await this.sqliteStore.enqueueForEmbedding(eventId, content);
-      }
-    );
+    return this.ingestService.storeUserPrompt(sessionId, content, metadata);
   }
 
   /**
@@ -511,21 +188,7 @@ export class MemoryService {
     content: string,
     metadata?: Record<string, unknown>
   ): Promise<AppendResult> {
-    await this.initialize();
-
-    return this.ingestWithInterceptors(
-      'agent_response',
-      {
-        eventType: 'agent_response',
-        sessionId,
-        timestamp: new Date(),
-        content,
-        metadata
-      },
-      async (eventId) => {
-        await this.sqliteStore.enqueueForEmbedding(eventId, content);
-      }
-    );
+    return this.ingestService.storeAgentResponse(sessionId, content, metadata);
   }
 
   /**
@@ -536,21 +199,7 @@ export class MemoryService {
     summary: string,
     metadata?: Record<string, unknown>
   ): Promise<AppendResult> {
-    await this.initialize();
-
-    return this.ingestWithInterceptors(
-      'session_summary',
-      {
-        eventType: 'session_summary',
-        sessionId,
-        timestamp: new Date(),
-        content: summary,
-        metadata
-      },
-      async (eventId) => {
-        await this.sqliteStore.enqueueForEmbedding(eventId, summary);
-      }
-    );
+    return this.ingestService.storeSessionSummary(sessionId, summary, metadata);
   }
 
   /**
@@ -558,17 +207,7 @@ export class MemoryService {
    * Called from session-start hook to catch sessions that ended without Stop hook.
    */
   async backfillMissingSummaries(currentSessionId: string, limit = 5): Promise<void> {
-    await this.initialize();
-
-    // Get recent sessions that don't have a summary event
-    const recentSessionIds = await this.sqliteStore.getSessionsWithoutSummary(currentSessionId, limit);
-    for (const sid of recentSessionIds) {
-      try {
-        await this.generateSessionSummary(sid);
-      } catch {
-        // non-critical
-      }
-    }
+    return this.ingestService.backfillMissingSummaries(currentSessionId, limit);
   }
 
   /**
@@ -577,41 +216,7 @@ export class MemoryService {
    * Skips if a summary already exists for this session.
    */
   async generateSessionSummary(sessionId: string): Promise<void> {
-    await this.initialize();
-
-    const events = await this.sqliteStore.getSessionEvents(sessionId);
-    if (events.length < 3) return; // Too short to summarize
-
-    // Skip if summary already exists
-    const hasSummary = events.some((e) => e.eventType === 'session_summary');
-    if (hasSummary) return;
-
-    const prompts = events.filter((e) => e.eventType === 'user_prompt');
-    const toolObs = events.filter((e) => e.eventType === 'tool_observation');
-    const toolNames = [...new Set(
-      toolObs.map((e) => (e.metadata as Record<string, unknown>)?.toolName as string).filter(Boolean)
-    )];
-    const errorObs = toolObs.filter((e) => {
-      const meta = e.metadata as Record<string, unknown>;
-      return meta?.exitCode !== undefined && meta.exitCode !== 0;
-    });
-
-    const datePart = events[0].timestamp.toISOString().split('T')[0];
-    const parts: string[] = [`[${datePart}] ${prompts.length}턴 세션.`];
-
-    if (prompts.length > 0) {
-      const firstPrompt = prompts[0].content.slice(0, 120).replace(/\n/g, ' ');
-      parts.push(`주요 작업: ${firstPrompt}`);
-    }
-    if (toolNames.length > 0) {
-      parts.push(`사용 툴: ${toolNames.slice(0, 6).join(', ')}`);
-    }
-    if (errorObs.length > 0) {
-      parts.push(`오류 ${errorObs.length}건 발생`);
-    }
-
-    const summary = parts.join('. ');
-    await this.storeSessionSummary(sessionId, summary, { generated: 'rule-based', eventCount: events.length });
+    return this.ingestService.generateSessionSummary(sessionId);
   }
 
   /**
@@ -621,36 +226,7 @@ export class MemoryService {
     sessionId: string,
     payload: ToolObservationPayload
   ): Promise<AppendResult> {
-    await this.initialize();
-
-    // Create content for storage (JSON stringified payload)
-    const content = JSON.stringify(payload);
-
-    // Extract turnId from payload metadata if present (set by PostToolUse hook)
-    const turnId = payload.metadata?.turnId;
-
-    return this.ingestWithInterceptors(
-      'tool_observation',
-      {
-        eventType: 'tool_observation',
-        sessionId,
-        timestamp: new Date(),
-        content,
-        metadata: {
-          toolName: payload.toolName,
-          success: payload.success,
-          ...(turnId ? { turnId } : {})
-        }
-      },
-      async (eventId) => {
-        const embeddingContent = createToolObservationEmbedding(
-          payload.toolName,
-          payload.metadata || {},
-          payload.success
-        );
-        await this.sqliteStore.enqueueForEmbedding(eventId, embeddingContent);
-      }
-    );
+    return this.ingestService.storeToolObservation(sessionId, payload);
   }
 
   /**
@@ -658,193 +234,36 @@ export class MemoryService {
    */
   async retrieveMemories(
     query: string,
-    options?: {
-      topK?: number;
-      minScore?: number;
-      sessionId?: string;
-      includeShared?: boolean;
-      adaptiveRerank?: boolean;
-      intentRewrite?: boolean;
-      projectScopeMode?: 'strict' | 'prefer' | 'global';
-      allowedProjectHashes?: string[];
-    }
+    options?: RetrieveMemoriesOptions
   ): Promise<UnifiedRetrievalResult> {
-    await this.initialize();
-
-    // Note: Pending embeddings are processed by the background worker
-    // Don't block retrieval - search with whatever vectors are available
-
-    const rerankWeights = await this.getRerankWeights(options?.adaptiveRerank === true);
-
-    // Use unified retrieval if shared search is requested
-    let result: UnifiedRetrievalResult;
-
-    if (options?.includeShared && this.sharedStore) {
-      result = await this.retriever.retrieveUnified(query, {
-        ...options,
-        intentRewrite: options?.intentRewrite === true,
-        rerankWeights,
-        includeShared: true,
-        projectHash: this.projectHash || undefined,
-        projectScopeMode: options?.projectScopeMode ?? (this.projectHash ? 'strict' : 'global'),
-        allowedProjectHashes: options?.allowedProjectHashes
-      });
-    } else {
-      result = await this.retriever.retrieve(query, {
-        ...options,
-        intentRewrite: options?.intentRewrite === true,
-        rerankWeights,
-        projectHash: this.projectHash || undefined,
-        projectScopeMode: options?.projectScopeMode ?? (this.projectHash ? 'strict' : 'global'),
-        allowedProjectHashes: options?.allowedProjectHashes
-      });
-    }
-
-    try {
-      const selectedEventIds = result.memories.map((m) => m.event.id);
-      const selectedDetails = (result.selectedDebug || []).map((d) => ({
-        eventId: d.eventId,
-        score: d.score,
-        semanticScore: d.semanticScore,
-        lexicalScore: d.lexicalScore,
-        recencyScore: d.recencyScore,
-      }));
-      const candidateDetails = (result.candidateDebug || []).map((d) => ({
-        eventId: d.eventId,
-        score: d.score,
-        semanticScore: d.semanticScore,
-        lexicalScore: d.lexicalScore,
-        recencyScore: d.recencyScore,
-      }));
-      const candidateEventIds = candidateDetails.length > 0
-        ? candidateDetails.map((d) => d.eventId)
-        : selectedEventIds;
-      await this.sqliteStore.recordRetrievalTrace({
-        sessionId: options?.sessionId,
-        projectHash: this.projectHash || undefined,
-        queryText: query,
-        strategy: options?.strategy || 'auto',
-        candidateEventIds,
-        selectedEventIds,
-        candidateDetails,
-        selectedDetails,
-        confidence: result.matchResult.confidence,
-        fallbackTrace: result.fallbackTrace || []
-      });
-    } catch {
-      // non-blocking telemetry
-    }
-
-    return result;
-  }
-
-  private getConfiguredRerankWeights(): { semantic: number; lexical: number; recency: number } | undefined {
-    const semantic = Number(process.env.MEMORY_RERANK_WEIGHT_SEMANTIC ?? '');
-    const lexical = Number(process.env.MEMORY_RERANK_WEIGHT_LEXICAL ?? '');
-    const recency = Number(process.env.MEMORY_RERANK_WEIGHT_RECENCY ?? '');
-
-    const allFinite = [semantic, lexical, recency].every((v) => Number.isFinite(v));
-    if (!allFinite) return undefined;
-
-    const nonNegative = [semantic, lexical, recency].every((v) => v >= 0);
-    const total = semantic + lexical + recency;
-    if (!nonNegative || total <= 0) return undefined;
-
-    return {
-      semantic: semantic / total,
-      lexical: lexical / total,
-      recency: recency / total,
-    };
-  }
-
-  private async getRerankWeights(adaptive: boolean): Promise<{ semantic: number; lexical: number; recency: number } | undefined> {
-    const configured = this.getConfiguredRerankWeights();
-    if (configured) return configured;
-    if (adaptive) return this.getAdaptiveRerankWeights();
-    return undefined;
-  }
-
-  private async rewriteQueryIntent(query: string): Promise<string | null> {
-    if (process.env.MEMORY_INTENT_REWRITE_ENABLED !== '1') return null;
-
-    const apiUrl = process.env.COMPANY_STOCK_API_URL || process.env.COMPANY_INT_API_URL;
-    if (!apiUrl) return null;
-
-    const controller = new AbortController();
-    const timeoutMs = Number(process.env.MEMORY_INTENT_REWRITE_TIMEOUT_MS || 5000);
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-      const prompt = [
-        'Rewrite user query for memory retrieval intent expansion.',
-        'Return plain text only, one line, no markdown.',
-        `Query: ${query}`,
-      ].join('\n');
-
-      const res = await fetch(apiUrl, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          Accept: '*/*',
-          Origin: process.env.COMPANY_INT_ORIGIN || 'http://company-int.aplusai.ai',
-          Referer: process.env.COMPANY_INT_REFERER || 'http://company-int.aplusai.ai/',
-        },
-        body: JSON.stringify({
-          question: prompt,
-          company_name: null,
-          conversation_id: null,
-        }),
-        signal: controller.signal,
-      });
-
-      const text = (await res.text()).trim();
-      if (!text) return null;
-
-      const oneLine = text
-        .replace(/^data:\s*/gm, '')
-        .split(/\r?\n/)
-        .map((x) => x.trim())
-        .filter(Boolean)
-        .join(' ')
-        .slice(0, 240);
-
-      if (!oneLine || oneLine.toLowerCase() === query.toLowerCase()) return null;
-      return oneLine;
-    } catch {
-      return null;
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-
-  private async getAdaptiveRerankWeights(): Promise<{ semantic: number; lexical: number; recency: number } | undefined> {
-    try {
-      const s = await this.sqliteStore.getHelpfulnessStats();
-      if (s.totalEvaluated < 20) return undefined;
-
-      // base weights
-      let semantic = 0.7;
-      let lexical = 0.2;
-      let recency = 0.1;
-
-      if (s.avgScore < 0.45) {
-        semantic -= 0.1;
-        lexical += 0.1;
-      } else if (s.avgScore > 0.75) {
-        semantic += 0.05;
-        lexical -= 0.05;
-      }
-
-      if (s.unhelpful > s.helpful) {
-        recency += 0.05;
-        semantic -= 0.03;
-        lexical -= 0.02;
-      }
-
-      return { semantic, lexical, recency };
-    } catch {
-      return undefined;
-    }
+    return this.retrievalOrchestrator.retrieveMemories(query, options);
+  }
+
+  /**
+   * Layer 1 retrieval disclosure: lightweight search envelopes for UI/API/agent use.
+   */
+  async searchDisclosure(
+    query: string,
+    options?: RetrievalDisclosureSearchOptions
+  ): Promise<RetrievalDisclosureSearchResponse> {
+    return this.retrievalDisclosureService.search(query, options);
+  }
+
+  /**
+   * Layer 2 retrieval disclosure: expand a search result into surrounding timeline context.
+   */
+  async expandDisclosure(
+    resultId: string,
+    options?: RetrievalDisclosureExpandOptions
+  ): Promise<RetrievalDisclosureExpansion | null> {
+    return this.retrievalDisclosureService.expand(resultId, options);
+  }
+
+  /**
+   * Layer 3 retrieval disclosure: resolve a search result to its raw source event.
+   */
+  async sourceDisclosure(resultId: string): Promise<RetrievalDisclosureSource | null> {
+    return this.retrievalDisclosureService.source(resultId);
   }
 
   /**
@@ -855,44 +274,28 @@ export class MemoryService {
     query: string,
     options?: { topK?: number; minScore?: number }
   ): Promise<Array<{event: MemoryEvent; score: number}>> {
-    await this.initialize();
-
-    const results = await this.sqliteStore.keywordSearch(query, options?.topK ?? 10);
-
-    // Normalize FTS5 rank to a score (0-1 range)
-    // FTS5 rank is negative (higher is worse), so we convert it
-    const maxRank = Math.min(...results.map(r => r.rank), -0.001);
-    const minRank = Math.max(...results.map(r => r.rank), -1000);
-    const rankRange = maxRank - minRank || 1;
-
-    return results.map(r => ({
-      event: r.event,
-      score: 1 - (r.rank - minRank) / rankRange  // Normalize to 0-1
-    })).filter(r => !options?.minScore || r.score >= options.minScore);
+    return this.queryService.keywordSearch(query, options);
   }
 
   /**
    * Rebuild FTS index (call after database upgrade)
    */
   async rebuildFtsIndex(): Promise<number> {
-    await this.initialize();
-    return this.sqliteStore.rebuildFtsIndex();
+    return this.queryService.rebuildFtsIndex();
   }
 
   /**
    * Get session history
    */
   async getSessionHistory(sessionId: string): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.sqliteStore.getSessionEvents(sessionId);
+    return this.queryService.getSessionHistory(sessionId);
   }
 
   /**
    * Get recent events
    */
   async getRecentEvents(limit: number = 100): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.sqliteStore.getRecentEvents(limit);
+    return this.queryService.getRecentEvents(limit);
   }
 
   /**
@@ -903,23 +306,15 @@ export class MemoryService {
     embedding: { pending: number; processing: number; failed: number; total: number };
     vector: { pending: number; processing: number; failed: number; total: number };
   }> {
-    await this.initialize();
-    return this.sqliteStore.getOutboxStats();
+    return this.queryService.getOutboxStats();
   }
 
-  async getRetrievalTraceStats(): Promise<{
-    totalQueries: number;
-    avgCandidateCount: number;
-    avgSelectedCount: number;
-    selectionRate: number;
-  }> {
-    await this.initialize();
-    return this.sqliteStore.getRetrievalTraceStats();
+  async getRetrievalTraceStats(): Promise<RetrievalTraceStats> {
+    return this.retrievalAnalyticsService.getRetrievalTraceStats();
   }
 
-  async getRecentRetrievalTraces(limit: number = 50) {
-    await this.initialize();
-    return this.sqliteStore.getRecentRetrievalTraces(limit);
+  async getRecentRetrievalTraces(limit: number = 50): Promise<RetrievalTrace[]> {
+    return this.retrievalAnalyticsService.getRecentRetrievalTraces(limit);
   }
 
   async getStats(): Promise<{
@@ -927,63 +322,35 @@ export class MemoryService {
     vectorCount: number;
     levelStats: Array<{ level: string; count: number }>;
   }> {
-    await this.initialize();
-
-    const recentEvents = await this.sqliteStore.getRecentEvents(10000);
-    const vectorCount = await this.vectorStore.count();
-    const levelStats = await this.graduation.getStats();
-
-    return {
-      totalEvents: recentEvents.length,
-      vectorCount,
-      levelStats
-    };
+    return this.queryService.getStats();
   }
 
   /**
    * Process pending embeddings
    */
   async processPendingEmbeddings(): Promise<number> {
-    if (this.vectorWorker) {
-      return this.vectorWorker.processAll();
-    }
-    return 0;
+    return this.runtimeService.processPendingEmbeddings();
   }
 
   /**
    * Get events by memory level
    */
   async getEventsByLevel(level: string, options?: { limit?: number; offset?: number }): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.sqliteStore.getEventsByLevel(level, options);
+    return this.queryService.getEventsByLevel(level, options);
   }
 
   /**
    * Get memory level for a specific event
    */
   async getEventLevel(eventId: string): Promise<string | null> {
-    await this.initialize();
-    return this.sqliteStore.getEventLevel(eventId);
+    return this.queryService.getEventLevel(eventId);
   }
 
   /**
    * Format retrieval results as context for Claude
    */
   formatAsContext(result: RetrievalResult): string {
-    if (!result.context) {
-      return '';
-    }
-
-    const confidence = result.matchResult.confidence;
-    let header = '';
-
-    if (confidence === 'high') {
-      header = '🎯 **High-confidence memory match found:**\n\n';
-    } else if (confidence === 'suggested') {
-      header = '💡 **Suggested memories (may be relevant):**\n\n';
-    }
-
-    return header + result.context;
+    return this.retrievalOrchestrator.formatAsContext(result);
   }
 
   // ============================================================
@@ -994,21 +361,14 @@ export class MemoryService {
    * Check if shared store is enabled and initialized
    */
   isSharedStoreEnabled(): boolean {
-    return this.sharedStore !== null;
+    return this.sharedMemoryServices.isEnabled();
   }
 
   /**
    * Promote an entry to shared storage
    */
   async promoteToShared(entry: Entry): Promise<PromotionResult> {
-    if (!this.sharedPromoter || !this.projectHash) {
-      return {
-        success: false,
-        error: 'Shared store not initialized or project hash not set'
-      };
-    }
-
-    return this.sharedPromoter.promoteEntry(entry, this.projectHash);
+    return this.sharedMemoryServices.promoteToShared(entry, this.projectHash);
   }
 
   /**
@@ -1020,8 +380,7 @@ export class MemoryService {
     topTopics: Array<{ topic: string; count: number }>;
     totalUsageCount: number;
   } | null> {
-    if (!this.sharedStore) return null;
-    return this.sharedStore.getStats();
+    return this.sharedMemoryServices.getStats();
   }
 
   /**
@@ -1031,8 +390,7 @@ export class MemoryService {
     query: string,
     options?: { topK?: number; minConfidence?: number }
   ) {
-    if (!this.sharedStore) return [];
-    return this.sharedStore.search(query, options);
+    return this.sharedMemoryServices.search(query, options);
   }
 
   /**
@@ -1046,119 +404,60 @@ export class MemoryService {
   // Endless Mode Methods
   // ============================================================
 
-  /**
-   * Get the default endless mode config
-   */
-  private getDefaultEndlessConfig(): EndlessModeConfig {
-    return {
-      enabled: true,
-      workingSet: {
-        maxEvents: 100,
-        timeWindowHours: 24,
-        minRelevanceScore: 0.5
-      },
-      consolidation: {
-        triggerIntervalMs: 3600000, // 1 hour
-        triggerEventCount: 100,
-        triggerIdleMs: 1800000, // 30 minutes
-        useLLMSummarization: false
-      },
-      continuity: {
-        minScoreForSeamless: 0.7,
-        topicDecayHours: 48
-      }
-    };
-  }
-
   /**
    * Initialize Endless Mode components
    */
   async initializeEndlessMode(): Promise<void> {
-    const config = await this.getEndlessConfig();
-
-    this.workingSetStore = createWorkingSetStore(this.sqliteStore, config);
-    this.consolidatedStore = createConsolidatedStore(this.sqliteStore);
-    this.consolidationWorker = createConsolidationWorker(
-      this.workingSetStore,
-      this.consolidatedStore,
-      config
-    );
-    this.continuityManager = createContinuityManager(this.sqliteStore, config);
-
-    // Start consolidation worker
-    this.consolidationWorker.start();
+    return this.endlessMemoryServices.initializeEndlessMode();
   }
 
   /**
    * Get Endless Mode configuration
    */
   async getEndlessConfig(): Promise<EndlessModeConfig> {
-    const savedConfig = await this.sqliteStore.getEndlessConfig('config') as EndlessModeConfig | null;
-    return savedConfig || this.getDefaultEndlessConfig();
+    return this.endlessMemoryServices.getEndlessConfig();
   }
 
   /**
    * Set Endless Mode configuration
    */
   async setEndlessConfig(config: Partial<EndlessModeConfig>): Promise<void> {
-    const current = await this.getEndlessConfig();
-    const merged = { ...current, ...config };
-    await this.sqliteStore.setEndlessConfig('config', merged);
+    return this.endlessMemoryServices.setEndlessConfig(config);
   }
 
   /**
    * Set memory mode (session or endless)
    */
   async setMode(mode: MemoryMode): Promise<void> {
-    await this.initialize();
-
-    if (mode === this.endlessMode) return;
-
-    this.endlessMode = mode;
-    await this.sqliteStore.setEndlessConfig('mode', mode);
-
-    if (mode === 'endless') {
-      await this.initializeEndlessMode();
-    } else {
-      // Stop endless mode components
-      if (this.consolidationWorker) {
-        this.consolidationWorker.stop();
-        this.consolidationWorker = null;
-      }
-      this.workingSetStore = null;
-      this.consolidatedStore = null;
-      this.continuityManager = null;
-    }
+    return this.endlessMemoryServices.setMode(mode);
   }
 
   /**
    * Get current memory mode
    */
   getMode(): MemoryMode {
-    return this.endlessMode;
+    return this.endlessMemoryServices.getMode();
   }
 
   /**
    * Check if endless mode is active
    */
   isEndlessModeActive(): boolean {
-    return this.endlessMode === 'endless';
+    return this.endlessMemoryServices.isEndlessModeActive();
   }
 
   /**
    * Add event to Working Set (Endless Mode)
    */
   async addToWorkingSet(eventId: string, relevanceScore?: number): Promise<void> {
-    if (!this.workingSetStore) return;
-    await this.workingSetStore.add(eventId, relevanceScore);
+    return this.endlessMemoryServices.addToWorkingSet(eventId, relevanceScore);
   }
 
   /**
    * Get the current Working Set
    */
   async getWorkingSet(): Promise<WorkingSet | null> {
-    if (!this.workingSetStore) return null;
-    return this.workingSetStore.get();
+    return this.endlessMemoryServices.getWorkingSet();
   }
 
   /**
@@ -1168,138 +467,50 @@ export class MemoryService {
     query: string,
     options?: { topK?: number }
   ): Promise<ConsolidatedMemory[]> {
-    if (!this.consolidatedStore) return [];
-    return this.consolidatedStore.search(query, options);
+    return this.endlessMemoryServices.searchConsolidated(query, options);
   }
 
   /**
    * Get all consolidated memories
    */
   async getConsolidatedMemories(limit?: number): Promise<ConsolidatedMemory[]> {
-    if (!this.consolidatedStore) return [];
-    return this.consolidatedStore.getAll({ limit });
-  }
-
-  /**
-   * Extract topic keywords from event content (markdown headings and key terms)
-   */
-  private extractTopicsFromContent(content: string): string[] {
-    const topics: Set<string> = new Set();
-
-    // Extract markdown headings (## heading)
-    const headings = content.match(/^#{1,3}\s+(.+)$/gm);
-    if (headings) {
-      for (const h of headings.slice(0, 5)) {
-        const text = h.replace(/^#+\s+/, '').replace(/[*_`#]/g, '').trim();
-        if (text.length > 2 && text.length < 50) {
-          topics.add(text);
-        }
-      }
-    }
-
-    // Extract bold terms (**term**)
-    const boldTerms = content.match(/\*\*([^*]+)\*\*/g);
-    if (boldTerms) {
-      for (const b of boldTerms.slice(0, 5)) {
-        const text = b.replace(/\*\*/g, '').trim();
-        if (text.length > 2 && text.length < 30) {
-          topics.add(text);
-        }
-      }
-    }
-
-    return Array.from(topics).slice(0, 5);
+    return this.endlessMemoryServices.getConsolidatedMemories(limit);
   }
 
   /**
    * Increment access count for memories that were used in prompts
    */
   async incrementMemoryAccess(eventIds: string[]): Promise<void> {
-    if (eventIds.length === 0) return;
-
-    // Use SQLite event store if available
-    if (this.sqliteStore) {
-      await this.sqliteStore.incrementAccessCount(eventIds);
-    } else if (this.eventStore) {
-      // Fallback to regular event store (which has a stub implementation)
-      await this.eventStore.incrementAccessCount(eventIds);
-    }
+    return this.retrievalOrchestrator.incrementMemoryAccess(eventIds);
   }
 
   /**
    * Get most accessed memories from events
    */
-  async getMostAccessedMemories(limit: number = 10): Promise<any[]> {
-    console.log('[getMostAccessedMemories] sqliteStore available:', !!this.sqliteStore);
-
-    // Try to get from SQLite event store if available
-    if (this.sqliteStore) {
-      const events = await this.sqliteStore.getMostAccessed(limit);
-      console.log('[getMostAccessedMemories] Got events from SQLite:', events.length);
-      return events.map(event => ({
-        memoryId: event.id,
-        summary: event.content.substring(0, 200) + (event.content.length > 200 ? '...' : ''),
-        topics: this.extractTopicsFromContent(event.content),
-        accessCount: (event as any).access_count || 0,
-        lastAccessed: (event as any).last_accessed_at || null,
-        confidence: 1.0,
-        createdAt: event.timestamp
-      }));
-    }
-
-    // Fallback to consolidated store if available
-    if (this.consolidatedStore) {
-      const consolidated = await this.consolidatedStore.getMostAccessed(limit);
-      return consolidated.map(m => ({
-        memoryId: m.memoryId,
-        summary: m.summary,
-        topics: m.topics,
-        accessCount: m.accessCount,
-        lastAccessed: m.accessedAt,
-        confidence: m.confidence,
-        createdAt: m.createdAt
-      }));
-    }
-
-    return [];
+  async getMostAccessedMemories(limit: number = 10): Promise<AccessedMemory[]> {
+    return this.retrievalAnalyticsService.getMostAccessedMemories(limit);
   }
 
   /**
    * Record a memory retrieval for helpfulness tracking
    */
   async recordRetrieval(eventId: string, sessionId: string, score: number, query: string): Promise<void> {
-    await this.initialize();
-    await this.sqliteStore.recordRetrieval(eventId, sessionId, score, query);
+    return this.retrievalOrchestrator.recordRetrieval(eventId, sessionId, score, query);
   }
 
   /**
    * Record a query-level retrieval trace (used by user-prompt-submit hook).
    * Feeds the retrieval_traces table that powers dashboard stats.
    */
-  async recordQueryTrace(input: {
-    sessionId: string;
-    queryText: string;
-    strategy: string;
-    candidateEventIds: string[];
-    selectedEventIds: string[];
-    confidence: string;
-  }): Promise<void> {
-    await this.initialize();
-    await this.sqliteStore.recordRetrievalTrace({
-      ...input,
-      projectHash: this.projectHash || undefined,
-      candidateDetails: [],
-      selectedDetails: [],
-      fallbackTrace: [],
-    });
+  async recordQueryTrace(input: RecordQueryTraceInput): Promise<void> {
+    return this.retrievalOrchestrator.recordQueryTrace(input);
   }
 
   /**
    * Evaluate helpfulness of retrievals in a session (called at session end)
    */
   async evaluateSessionHelpfulness(sessionId: string): Promise<void> {
-    await this.initialize();
-    await this.sqliteStore.evaluateSessionHelpfulness(sessionId);
+    await this.retrievalAnalyticsService.evaluateSessionHelpfulness(sessionId);
   }
 
   /**
@@ -1307,52 +518,28 @@ export class MemoryService {
    * Call on first turn of a new session to catch missed evaluations.
    */
   async evaluatePendingSessions(currentSessionId: string): Promise<void> {
-    await this.initialize();
-    const sessions = await this.sqliteStore.getUnevaluatedSessions(currentSessionId, 5);
-    for (const sid of sessions) {
-      try {
-        await this.sqliteStore.evaluateSessionHelpfulness(sid);
-      } catch {
-        // non-critical, skip failed
-      }
-    }
+    await this.retrievalAnalyticsService.evaluatePendingSessions(currentSessionId);
   }
 
   /**
    * Get most helpful memories ranked by helpfulness score
    */
-  async getHelpfulMemories(limit: number = 10): Promise<Array<{
-    eventId: string;
-    summary: string;
-    helpfulnessScore: number;
-    accessCount: number;
-    evaluationCount: number;
-  }>> {
-    await this.initialize();
-    return this.sqliteStore.getHelpfulMemories(limit);
+  async getHelpfulMemories(limit: number = 10): Promise<HelpfulMemory[]> {
+    return this.retrievalAnalyticsService.getHelpfulMemories(limit);
   }
 
   /**
    * Get helpfulness statistics for dashboard
    */
-  async getHelpfulnessStats(): Promise<{
-    avgScore: number;
-    totalEvaluated: number;
-    totalRetrievals: number;
-    helpful: number;
-    neutral: number;
-    unhelpful: number;
-  }> {
-    await this.initialize();
-    return this.sqliteStore.getHelpfulnessStats();
+  async getHelpfulnessStats(): Promise<HelpfulnessStats> {
+    return this.retrievalAnalyticsService.getHelpfulnessStats();
   }
 
   /**
    * Mark a consolidated memory as accessed
    */
   async markMemoryAccessed(memoryId: string): Promise<void> {
-    if (!this.consolidatedStore) return;
-    await this.consolidatedStore.markAccessed(memoryId);
+    return this.endlessMemoryServices.markMemoryAccessed(memoryId);
   }
 
   /**
@@ -1362,63 +549,28 @@ export class MemoryService {
     content: string,
     metadata?: { files?: string[]; entities?: string[] }
   ): Promise<ContinuityScore | null> {
-    if (!this.continuityManager) return null;
-
-    const snapshot = this.continuityManager.createSnapshot(
-      crypto.randomUUID(),
-      content,
-      metadata
-    );
-
-    return this.continuityManager.calculateScore(snapshot);
+    return this.endlessMemoryServices.calculateContinuity(content, metadata);
   }
 
   /**
    * Record activity (for consolidation idle trigger)
    */
   recordActivity(): void {
-    if (this.consolidationWorker) {
-      this.consolidationWorker.recordActivity();
-    }
+    this.endlessMemoryServices.recordActivity();
   }
 
   /**
    * Force a consolidation run
    */
   async forceConsolidation(): Promise<number> {
-    if (!this.consolidationWorker) return 0;
-    return this.consolidationWorker.forceRun();
+    return this.endlessMemoryServices.forceConsolidation();
   }
 
   /**
    * Get Endless Mode status
    */
   async getEndlessModeStatus(): Promise<EndlessModeStatus> {
-    await this.initialize();
-
-    let workingSetSize = 0;
-    let continuityScore = 0.5;
-    let consolidatedCount = 0;
-    let lastConsolidation: Date | null = null;
-
-    if (this.workingSetStore) {
-      workingSetSize = await this.workingSetStore.count();
-      const workingSet = await this.workingSetStore.get();
-      continuityScore = workingSet.continuityScore;
-    }
-
-    if (this.consolidatedStore) {
-      consolidatedCount = await this.consolidatedStore.count();
-      lastConsolidation = await this.consolidatedStore.getLastConsolidationTime();
-    }
-
-    return {
-      mode: this.endlessMode,
-      workingSetSize,
-      continuityScore,
-      consolidatedCount,
-      lastConsolidation
-    };
+    return this.endlessMemoryServices.getEndlessModeStatus();
   }
 
   // ============================================================
@@ -1437,207 +589,70 @@ export class MemoryService {
     toolCount: number;
     hasResponse: boolean;
   }>> {
-    await this.initialize();
-    return this.sqliteStore.getSessionTurns(sessionId, options);
+    return this.queryService.getSessionTurns(sessionId, options);
   }
 
   /**
    * Get all events for a specific turn
    */
   async getEventsByTurn(turnId: string): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.sqliteStore.getEventsByTurn(turnId);
+    return this.queryService.getEventsByTurn(turnId);
   }
 
   /**
    * Count total turns for a session
    */
   async countSessionTurns(sessionId: string): Promise<number> {
-    await this.initialize();
-    return this.sqliteStore.countSessionTurns(sessionId);
+    return this.queryService.countSessionTurns(sessionId);
   }
 
   /**
    * Backfill turn_ids from metadata for events stored before the migration
    */
   async backfillTurnIds(): Promise<number> {
-    await this.initialize();
-    return this.sqliteStore.backfillTurnIds();
+    return this.queryService.backfillTurnIds();
   }
 
   /**
    * Delete all events for a session (for force reimport)
    */
   async deleteSessionEvents(sessionId: string): Promise<number> {
-    await this.initialize();
-    return this.sqliteStore.deleteSessionEvents(sessionId);
+    return this.queryService.deleteSessionEvents(sessionId);
   }
 
   /**
    * Format Endless Mode context for Claude
    */
   async formatEndlessContext(query: string): Promise<string> {
-    if (!this.isEndlessModeActive()) {
-      return '';
-    }
-
-    const workingSet = await this.getWorkingSet();
-    const consolidated = await this.searchConsolidated(query, { topK: 3 });
-    const continuity = await this.calculateContinuity(query);
-
-    const parts: string[] = [];
-
-    // Continuity status
-    if (continuity) {
-      const statusEmoji = continuity.transitionType === 'seamless' ? '🔗' :
-                          continuity.transitionType === 'topic_shift' ? '↪️' : '🆕';
-      parts.push(`${statusEmoji} Context: ${continuity.transitionType} (score: ${continuity.score.toFixed(2)})`);
-    }
-
-    // Working set summary
-    if (workingSet && workingSet.recentEvents.length > 0) {
-      parts.push('\n## Recent Context (Working Set)');
-      const recent = workingSet.recentEvents.slice(0, 5);
-      for (const event of recent) {
-        const preview = event.content.slice(0, 80) + (event.content.length > 80 ? '...' : '');
-        const time = event.timestamp.toLocaleTimeString();
-        parts.push(`- ${time} [${event.eventType}] ${preview}`);
-      }
-    }
-
-    // Consolidated memories
-    if (consolidated.length > 0) {
-      parts.push('\n## Related Knowledge (Consolidated)');
-      for (const memory of consolidated) {
-        parts.push(`- ${memory.topics.slice(0, 3).join(', ')}: ${memory.summary.slice(0, 100)}...`);
-      }
-    }
-
-    return parts.join('\n');
+    return this.endlessMemoryServices.formatEndlessContext(query);
   }
 
   /**
    * Force a graduation evaluation run
    */
   async forceGraduation(): Promise<GraduationRunResult> {
-    if (!this.graduationWorker) {
-      return { evaluated: 0, graduated: 0, byLevel: {} };
-    }
-    return this.graduationWorker.forceRun();
+    return this.runtimeService.forceGraduation();
   }
 
   /**
    * Record access to a memory event (for graduation scoring)
    */
   recordMemoryAccess(eventId: string, sessionId: string, confidence: number = 1.0): void {
-    this.graduation.recordAccess(eventId, sessionId, confidence);
+    this.runtimeService.recordMemoryAccess(eventId, sessionId, confidence);
   }
 
   getEmbeddingModelName(): string {
-    return this.embedder.getModelName();
+    return this.embeddingMaintenanceService.getEmbeddingModelName();
   }
 
   /**
    * Ensure embedding model metadata is in sync and optionally migrate vectors.
    * Migration strategy: clear vector index + clear embedding outbox + re-enqueue all events.
    */
-  async ensureEmbeddingModelForImport(options?: { autoMigrate?: boolean }): Promise<{
-    changed: boolean;
-    previousModel: string | null;
-    currentModel: string;
-    enqueued: number;
-    reason?: string;
-  }> {
-    await this.initialize();
-
-    const currentModel = this.getEmbeddingModelName();
-    const metaPath = path.join(this.storagePath, 'embedding-meta.json');
-
-    let previousModel: string | null = null;
-    try {
-      if (fs.existsSync(metaPath)) {
-        const parsed = JSON.parse(fs.readFileSync(metaPath, 'utf-8')) as { model?: string };
-        previousModel = parsed?.model || null;
-      }
-    } catch {
-      previousModel = null;
-    }
-
-    const stats = await this.getStats();
-    const hasExistingVectors = (stats.vectorCount || 0) > 0;
-
-    // First-time metadata write (no migration needed unless legacy vectors exist)
-    if (!previousModel && !hasExistingVectors) {
-      fs.writeFileSync(metaPath, JSON.stringify({ model: currentModel, updatedAt: new Date().toISOString() }, null, 2));
-      return { changed: false, previousModel: null, currentModel, enqueued: 0, reason: 'initialized-meta' };
-    }
-
-    const modelChanged = previousModel !== currentModel;
-    const legacyUnknownButVectorsExist = !previousModel && hasExistingVectors;
-
-    if (!modelChanged && !legacyUnknownButVectorsExist) {
-      return { changed: false, previousModel, currentModel, enqueued: 0 };
-    }
-
-    if (options?.autoMigrate === false) {
-      return {
-        changed: true,
-        previousModel,
-        currentModel,
-        enqueued: 0,
-        reason: legacyUnknownButVectorsExist ? 'legacy-vectors-without-meta' : 'model-mismatch'
-      };
-    }
-
-    // Pause background vector processing while preparing migration
-    const wasRunning = this.vectorWorker?.isRunning() || false;
-    if (wasRunning) this.vectorWorker?.stop();
-
-    // Reset vector and outbox state
-    await this.vectorStore.clearAll();
-    await this.sqliteStore.clearEmbeddingOutbox();
-
-    // Re-enqueue all events for new embeddings
-    const pageSize = 1000;
-    let offset = 0;
-    let enqueued = 0;
-
-    while (true) {
-      const page = await this.sqliteStore.getEventsPage(pageSize, offset);
-      if (page.length === 0) break;
-
-      for (const event of page) {
-        await this.sqliteStore.enqueueForEmbedding(event.id, event.content);
-        enqueued += 1;
-      }
-
-      offset += page.length;
-      if (page.length < pageSize) break;
-    }
-
-    fs.writeFileSync(
-      metaPath,
-      JSON.stringify(
-        {
-          model: currentModel,
-          previousModel,
-          migratedAt: new Date().toISOString(),
-          enqueued
-        },
-        null,
-        2
-      )
-    );
-
-    if (wasRunning) this.vectorWorker?.start();
-
-    return {
-      changed: true,
-      previousModel,
-      currentModel,
-      enqueued,
-      reason: legacyUnknownButVectorsExist ? 'legacy-vectors-without-meta' : 'model-mismatch'
-    };
+  async ensureEmbeddingModelForImport(
+    options?: EmbeddingModelMaintenanceOptions
+  ): Promise<EmbeddingModelMaintenanceResult> {
+    return this.embeddingMaintenanceService.ensureEmbeddingModelForImport(options);
   }
 
   /**
@@ -1651,152 +666,23 @@ export class MemoryService {
    * Shutdown service
    */
   async shutdown(): Promise<void> {
-    // Stop graduation worker
-    if (this.graduationWorker) {
-      this.graduationWorker.stop();
-    }
-
-    // Stop endless mode components
-    if (this.consolidationWorker) {
-      this.consolidationWorker.stop();
-    }
-
-    if (this.vectorWorker) {
-      this.vectorWorker.stop();
-    }
-
-    // Close shared store
-    if (this.sharedEventStore) {
-      await this.sharedEventStore.close();
-    }
-
-    // Close primary store (SQLite)
-    await this.sqliteStore.close();
-
-  }
-
-  /**
-   * Expand ~ to home directory
-   */
-  private expandPath(p: string): string {
-    if (p.startsWith('~')) {
-      return path.join(os.homedir(), p.slice(1));
-    }
-    return p;
-  }
-}
-
-// ============================================================
-// Service Instance Management
-// ============================================================
-
-// Instance cache: Map from project hash (or '__global__') to MemoryService
-const serviceCache = new Map<string, MemoryService>();
-const GLOBAL_KEY = '__global__';
-const GLOBAL_READONLY_KEY = '__global_readonly__';
-
-/**
- * Get the global memory service (backward compatibility)
- * Use this for operations not tied to a specific project
- * Note: analyticsEnabled=false and sharedStore disabled to avoid DuckDB lock conflicts
- */
-export function getDefaultMemoryService(): MemoryService {
-  if (!serviceCache.has(GLOBAL_KEY)) {
-    serviceCache.set(GLOBAL_KEY, new MemoryService({
-      storagePath: '~/.claude-code/memory',
-      analyticsEnabled: false,  // Hooks don't need DuckDB
-      sharedStoreConfig: { enabled: false }  // Shared store uses DuckDB too
-    }));
-  }
-  return serviceCache.get(GLOBAL_KEY)!;
-}
-
-/**
- * Get a read-only global memory service
- * Use this for web server/dashboard that only needs to read data
- * Creates a fresh connection each time to avoid blocking the main writer process
- * Uses SQLite (WAL mode) which supports concurrent readers
- */
-export function getReadOnlyMemoryService(): MemoryService {
-  // Don't cache - create fresh instance each time to avoid holding locks
-  // The connection will be closed when the request completes
-  // Uses SQLite which supports concurrent readers via WAL mode
-  return new MemoryService({
-    storagePath: '~/.claude-code/memory',
-    readOnly: true,
-    analyticsEnabled: false,  // Use SQLite for reads (WAL supports concurrent readers)
-    sharedStoreConfig: { enabled: false }  // Skip shared store for now
-  });
-}
-
-/**
- * Get memory service for a specific project path
- * Creates isolated storage at ~/.claude-code/memory/projects/{hash}/
- * Note: analyticsEnabled=false and sharedStore disabled to avoid DuckDB lock conflicts
- */
-export function getMemoryServiceForProject(
-  projectPath: string,
-  sharedStoreConfig?: SharedStoreConfig
-): MemoryService {
-  const hash = hashProjectPath(projectPath);
-
-  if (!serviceCache.has(hash)) {
-    const storagePath = getProjectStoragePath(projectPath);
-    serviceCache.set(hash, new MemoryService({
-      storagePath,
-      projectHash: hash,
-      projectPath,
-      // Override shared store config - hooks don't need DuckDB
-      sharedStoreConfig: sharedStoreConfig ?? { enabled: false },
-      analyticsEnabled: false  // Hooks don't need DuckDB
-    }));
-  }
-
-  return serviceCache.get(hash)!;
-}
-
-/**
- * Get memory service for a session by looking up its project
- * Falls back to global storage if session not found in registry
- */
-export function getMemoryServiceForSession(sessionId: string): MemoryService {
-  const projectInfo = getSessionProject(sessionId);
-
-  if (projectInfo) {
-    return getMemoryServiceForProject(projectInfo.projectPath);
+    await this.runtimeService.shutdown();
   }
-
-  // Fallback to global storage for unknown sessions (backward compat)
-  return getDefaultMemoryService();
 }
 
-/**
- * Get a lightweight memory service for hooks
- * Only initializes SQLite - no embedder, no vector store, no workers
- * This is FAST (<100ms) compared to full initialization (3-5s)
- */
-export function getLightweightMemoryService(sessionId: string): MemoryService {
-  const projectInfo = getSessionProject(sessionId);
-  const key = projectInfo ? `lightweight_${projectInfo.projectHash}` : 'lightweight_global';
-
-  if (!serviceCache.has(key)) {
-    const storagePath = projectInfo
-      ? getProjectStoragePath(projectInfo.projectPath)
-      : path.join(os.homedir(), '.claude-code', 'memory');
-
-    serviceCache.set(key, new MemoryService({
-      storagePath,
-      projectHash: projectInfo?.projectHash,
-      projectPath: projectInfo?.projectPath,
-      lightweightMode: true,  // Skip embedder/vector/workers
-      analyticsEnabled: false,
-      sharedStoreConfig: { enabled: false }
-    }));
-  }
-
-  return serviceCache.get(key)!;
-}
-
-export function createMemoryService(config: MemoryServiceConfig): MemoryService {
-  return new MemoryService(config);
-}
+const defaultRegistry = createMemoryServiceRegistry<MemoryService>({
+  createService: (config) => new MemoryService(config),
+  hashProjectPath: defaultHashProjectPath,
+  getProjectStoragePath: defaultGetProjectStoragePath,
+  getSessionProject: defaultGetSessionProject,
+  homedir: os.homedir,
+  disabledSharedStoreConfig: DISABLED_SHARED_STORE_CONFIG
+});
+
+export const getDefaultMemoryService = defaultRegistry.getDefaultMemoryService;
+export const getReadOnlyMemoryService = defaultRegistry.getReadOnlyMemoryService;
+export const getMemoryServiceForProject = defaultRegistry.getMemoryServiceForProject;
+export const getMemoryServiceForSession = defaultRegistry.getMemoryServiceForSession;
+export const getLightweightMemoryService = defaultRegistry.getLightweightMemoryService;
+export const getLightweightMemoryServiceForProject = defaultRegistry.getLightweightMemoryServiceForProject;
+export const createMemoryService = defaultRegistry.createMemoryService;