claude-memory-layer 1.0.31 → 1.0.33

package/src/core/engine/memory-query-service.ts

@@ -1,173 +0,0 @@
-import type { MemoryEvent } from '../types.js';
-
-interface RankedKeywordResult {
-  event: MemoryEvent;
-  rank: number;
-}
-
-export interface MemorySessionTurn {
-  turnId: string;
-  events: MemoryEvent[];
-  startedAt: Date;
-  promptPreview: string;
-  eventCount: number;
-  toolCount: number;
-  hasResponse: boolean;
-}
-
-export interface MemoryOutboxStats {
-  embedding: { pending: number; processing: number; failed: number; total: number };
-  vector: { pending: number; processing: number; failed: number; total: number };
-}
-
-export interface MemoryStats {
-  totalEvents: number;
-  vectorCount: number;
-  levelStats: Array<{ level: string; count: number }>;
-}
-
-interface QueryStore {
-  keywordSearch(query: string, topK: number): Promise<RankedKeywordResult[]>;
-  getSessionEvents(sessionId: string): Promise<MemoryEvent[]>;
-  getRecentEvents(limit: number): Promise<MemoryEvent[]>;
-}
-
-interface QueryMaintenanceStore extends QueryStore {
-  rebuildFtsIndex(): Promise<number>;
-  getOutboxStats(): Promise<MemoryOutboxStats>;
-  getEventsByLevel(level: string, options?: { limit?: number; offset?: number }): Promise<MemoryEvent[]>;
-  getEventLevel(eventId: string): Promise<string | null>;
-  getSessionTurns(sessionId: string, options?: { limit?: number; offset?: number }): Promise<MemorySessionTurn[]>;
-  getEventsByTurn(turnId: string): Promise<MemoryEvent[]>;
-  countSessionTurns(sessionId: string): Promise<number>;
-  backfillTurnIds(): Promise<number>;
-  deleteSessionEvents(sessionId: string): Promise<number>;
-}
-
-interface MemoryQueryServiceDeps {
-  vectorStore: { count(): Promise<number> };
-  graduation: { getStats(): Promise<Array<{ level: string; count: number }>> };
-}
-
-/**
- * Thin-core query service for lightweight read and maintenance paths.
- *
- * Higher-level retrieval orchestration lives in RetrievalOrchestrator;
- * this service keeps storage-backed read models and maintenance delegates separate.
- */
-export class MemoryQueryService {
-  constructor(
-    private readonly initialize: () => Promise<void>,
-    private readonly queryStore: QueryStore,
-    private readonly deps?: MemoryQueryServiceDeps
-  ) {}
-
-  async keywordSearch(
-    query: string,
-    options?: { topK?: number; minScore?: number }
-  ): Promise<Array<{ event: MemoryEvent; score: number }>> {
-    await this.initialize();
-
-    const results = await this.queryStore.keywordSearch(query, options?.topK ?? 10);
-    if (results.length === 0) return [];
-
-    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
-      }))
-      .filter((r) => !options?.minScore || r.score >= options.minScore);
-  }
-
-  async getSessionHistory(sessionId: string): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.queryStore.getSessionEvents(sessionId);
-  }
-
-  async getRecentEvents(limit: number = 100): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.queryStore.getRecentEvents(limit);
-  }
-
-  async rebuildFtsIndex(): Promise<number> {
-    await this.initialize();
-    return this.getMaintenanceStore('rebuildFtsIndex').rebuildFtsIndex();
-  }
-
-  async getOutboxStats(): Promise<MemoryOutboxStats> {
-    await this.initialize();
-    return this.getMaintenanceStore('getOutboxStats').getOutboxStats();
-  }
-
-  async getStats(): Promise<MemoryStats> {
-    await this.initialize();
-
-    const deps = this.getStatsDeps();
-    const recentEvents = await this.queryStore.getRecentEvents(10000);
-    const vectorCount = await deps.vectorStore.count();
-    const levelStats = await deps.graduation.getStats();
-
-    return {
-      totalEvents: recentEvents.length,
-      vectorCount,
-      levelStats
-    };
-  }
-
-  async getEventsByLevel(level: string, options?: { limit?: number; offset?: number }): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.getMaintenanceStore('getEventsByLevel').getEventsByLevel(level, options);
-  }
-
-  async getEventLevel(eventId: string): Promise<string | null> {
-    await this.initialize();
-    return this.getMaintenanceStore('getEventLevel').getEventLevel(eventId);
-  }
-
-  async getSessionTurns(
-    sessionId: string,
-    options?: { limit?: number; offset?: number }
-  ): Promise<MemorySessionTurn[]> {
-    await this.initialize();
-    return this.getMaintenanceStore('getSessionTurns').getSessionTurns(sessionId, options);
-  }
-
-  async getEventsByTurn(turnId: string): Promise<MemoryEvent[]> {
-    await this.initialize();
-    return this.getMaintenanceStore('getEventsByTurn').getEventsByTurn(turnId);
-  }
-
-  async countSessionTurns(sessionId: string): Promise<number> {
-    await this.initialize();
-    return this.getMaintenanceStore('countSessionTurns').countSessionTurns(sessionId);
-  }
-
-  async backfillTurnIds(): Promise<number> {
-    await this.initialize();
-    return this.getMaintenanceStore('backfillTurnIds').backfillTurnIds();
-  }
-
-  async deleteSessionEvents(sessionId: string): Promise<number> {
-    await this.initialize();
-    return this.getMaintenanceStore('deleteSessionEvents').deleteSessionEvents(sessionId);
-  }
-
-  private getMaintenanceStore(method: keyof QueryMaintenanceStore): QueryMaintenanceStore {
-    const store = this.queryStore as QueryStore & Partial<QueryMaintenanceStore>;
-    if (typeof store[method] !== 'function') {
-      throw new Error(`MemoryQueryService requires queryStore.${String(method)}() for this operation`);
-    }
-    return store as QueryMaintenanceStore;
-  }
-
-  private getStatsDeps(): MemoryQueryServiceDeps {
-    if (!this.deps) {
-      throw new Error('MemoryQueryService requires vectorStore and graduation dependencies for getStats()');
-    }
-    return this.deps;
-  }
-}

package/src/core/engine/memory-runtime-service.ts

@@ -1,162 +0,0 @@
-/**
- * Memory Runtime Service
- * Owns MemoryService lifecycle concerns: initialization, background workers,
- * lightweight/read-only modes, and orderly shutdown.
- */
-
-import type { EventStore } from '../event-store.js';
-import type { Embedder } from '../embedder.js';
-import type { GraduationPipeline } from '../graduation.js';
-import {
-  createGraduationWorker as defaultCreateGraduationWorker,
-  type GraduationRunResult,
-  type GraduationWorker
-} from '../graduation-worker.js';
-import type { Retriever } from '../retriever.js';
-import type { VectorStore } from '../vector-store.js';
-import {
-  createVectorWorker as defaultCreateVectorWorker,
-  type VectorWorker
-} from '../vector-worker.js';
-
-export interface RuntimeSQLiteStore {
-  initialize(): Promise<void>;
-  close(): Promise<void>;
-}
-
-export interface RuntimeEndlessMemoryServices {
-  initializeFromSavedMode(): Promise<void>;
-  shutdown(): void;
-}
-
-export interface RuntimeSharedMemoryServices {
-  initialize(): Promise<void>;
-  close(): Promise<void>;
-}
-
-export interface MemoryRuntimeServicesFactories {
-  createVectorWorker?: typeof defaultCreateVectorWorker;
-  createGraduationWorker?: typeof defaultCreateGraduationWorker;
-}
-
-export interface MemoryRuntimeServicesDeps {
-  sqliteStore: RuntimeSQLiteStore;
-  eventStore: EventStore;
-  vectorStore: VectorStore;
-  embedder: Embedder;
-  retriever: Retriever;
-  graduation: GraduationPipeline;
-  endlessMemoryServices: RuntimeEndlessMemoryServices;
-  sharedMemoryServices: RuntimeSharedMemoryServices;
-  readOnly: boolean;
-  lightweightMode: boolean;
-  embeddingOnly: boolean;
-  factories?: MemoryRuntimeServicesFactories;
-}
-
-export interface MemoryRuntimeService {
-  initialize(): Promise<void>;
-  shutdown(): Promise<void>;
-  processPendingEmbeddings(): Promise<number>;
-  forceGraduation(): Promise<GraduationRunResult>;
-  recordMemoryAccess(eventId: string, sessionId: string, confidence?: number): void;
-  getVectorWorker(): VectorWorker | null;
-  isInitialized(): boolean;
-}
-
-function createEmptyGraduationResult(): GraduationRunResult {
-  return { evaluated: 0, graduated: 0, byLevel: {} };
-}
-
-export function createMemoryRuntimeService(deps: MemoryRuntimeServicesDeps): MemoryRuntimeService {
-  const createVectorWorker = deps.factories?.createVectorWorker ?? defaultCreateVectorWorker;
-  const createGraduationWorker = deps.factories?.createGraduationWorker ?? defaultCreateGraduationWorker;
-
-  let initialized = false;
-  let vectorWorker: VectorWorker | null = null;
-  let graduationWorker: GraduationWorker | null = null;
-
-  return {
-    async initialize(): Promise<void> {
-      if (initialized) return;
-
-      // Initialize PRIMARY store: SQLite (always)
-      await deps.sqliteStore.initialize();
-
-      // Lightweight mode: only SQLite, no embedder/vector/workers.
-      // Used for hooks that just need to store data quickly.
-      if (deps.lightweightMode) {
-        initialized = true;
-        return;
-      }
-
-      await deps.vectorStore.initialize();
-      await deps.embedder.initialize();
-
-      // Skip write-related workers in read-only mode.
-      if (!deps.readOnly) {
-        vectorWorker = createVectorWorker(
-          deps.eventStore,
-          deps.vectorStore,
-          deps.embedder
-        );
-        vectorWorker.start();
-
-        if (!deps.embeddingOnly) {
-          deps.retriever.setGraduationPipeline(deps.graduation);
-          graduationWorker = createGraduationWorker(
-            deps.eventStore,
-            deps.graduation
-          );
-          graduationWorker.start();
-        }
-
-        await deps.endlessMemoryServices.initializeFromSavedMode();
-        await deps.sharedMemoryServices.initialize();
-      }
-
-      initialized = true;
-    },
-
-    async shutdown(): Promise<void> {
-      if (graduationWorker) {
-        graduationWorker.stop();
-      }
-
-      deps.endlessMemoryServices.shutdown();
-
-      if (vectorWorker) {
-        vectorWorker.stop();
-      }
-
-      await deps.sharedMemoryServices.close();
-      await deps.sqliteStore.close();
-    },
-
-    async processPendingEmbeddings(): Promise<number> {
-      if (vectorWorker) {
-        return vectorWorker.processAll();
-      }
-      return 0;
-    },
-
-    async forceGraduation(): Promise<GraduationRunResult> {
-      if (!graduationWorker) {
-        return createEmptyGraduationResult();
-      }
-      return graduationWorker.forceRun();
-    },
-
-    recordMemoryAccess(eventId: string, sessionId: string, confidence: number = 1.0): void {
-      deps.graduation.recordAccess(eventId, sessionId, confidence);
-    },
-
-    getVectorWorker(): VectorWorker | null {
-      return vectorWorker;
-    },
-
-    isInitialized(): boolean {
-      return initialized;
-    }
-  };
-}

package/src/core/engine/memory-service-composition.ts

@@ -1,231 +0,0 @@
-/**
- * Memory Service Composition
- *
- * Owns constructor-time service graph wiring for MemoryService so the public
- * facade can stay focused on state assignment and method delegation.
- */
-
-import * as os from 'os';
-import * as path from 'path';
-
-import type { EventStore } from '../event-store.js';
-import type { Embedder } from '../embedder.js';
-import type { GraduationPipeline } from '../graduation.js';
-import { createToolObservationEmbedding as defaultCreateToolObservationEmbedding } from '../metadata-extractor.js';
-import type { Retriever } from '../retriever.js';
-import type { SQLiteEventStore } from '../sqlite-event-store.js';
-import type { ToolObservationPayload, SharedStoreConfig } from '../types.js';
-import type { VectorStore } from '../vector-store.js';
-import {
-  createEmbeddingMaintenanceService as defaultCreateEmbeddingMaintenanceService,
-  type EmbeddingMaintenanceService,
-  type EmbeddingMaintenanceServiceOptions
-} from './embedding-maintenance-service.js';
-import {
-  createEndlessMemoryServices as defaultCreateEndlessMemoryServices,
-  type EndlessMemoryServices,
-  type EndlessMemoryServicesOptions
-} from './endless-memory-services.js';
-import {
-  createMemoryEngineServices as defaultCreateMemoryEngineServices,
-  type MemoryEngineServices,
-  type MemoryEngineServicesOptions
-} from './memory-engine-services.js';
-import {
-  createMemoryRuntimeService as defaultCreateMemoryRuntimeService,
-  type MemoryRuntimeService,
-  type MemoryRuntimeServicesDeps
-} from './memory-runtime-service.js';
-import type {
-  MemoryIngestService
-} from './memory-ingest-service.js';
-import type {
-  MemoryQueryService
-} from './memory-query-service.js';
-import {
-  createSharedMemoryServices as defaultCreateSharedMemoryServices,
-  type SharedMemoryServices,
-  type SharedMemoryServicesOptions
-} from './shared-memory-services.js';
-import type {
-  RetrievalAnalyticsService,
-  RetrievalDisclosureService,
-  RetrievalOrchestrator
-} from './retrieval-services.js';
-
-export interface MemoryServiceCompositionConfig {
-  storagePath: string;
-  embeddingModel?: string;
-  readOnly?: boolean;
-  lightweightMode?: boolean;
-  embeddingOnly?: boolean;
-  projectHash?: string;
-  projectPath?: string;
-  sharedStoreConfig?: SharedStoreConfig;
-}
-
-export interface MemoryServiceCompositionFactories {
-  expandPath?: (targetPath: string) => string;
-  createToolObservationEmbedding?: (
-    toolName: string,
-    metadata: Record<string, unknown>,
-    success: boolean
-  ) => string;
-  createMemoryEngineServices?: (options: MemoryEngineServicesOptions) => MemoryEngineServices;
-  createEndlessMemoryServices?: (options: EndlessMemoryServicesOptions) => EndlessMemoryServices;
-  createSharedMemoryServices?: (options: SharedMemoryServicesOptions) => SharedMemoryServices;
-  createMemoryRuntimeService?: (deps: MemoryRuntimeServicesDeps) => MemoryRuntimeService;
-  createEmbeddingMaintenanceService?: (
-    options: EmbeddingMaintenanceServiceOptions
-  ) => EmbeddingMaintenanceService;
-}
-
-export interface MemoryServiceCompositionOptions {
-  config: MemoryServiceCompositionConfig;
-  defaultSharedStoragePath: string;
-  defaultSharedStoreConfig?: SharedStoreConfig;
-  initialize: () => Promise<void>;
-  getProjectHash: () => string | null;
-  getProjectPath?: () => string | null;
-  factories?: MemoryServiceCompositionFactories;
-}
-
-export interface MemoryServiceComposition {
-  storagePath: string;
-  readOnly: boolean;
-  lightweightMode: boolean;
-  embeddingOnly: boolean;
-  sqliteStore: SQLiteEventStore;
-  vectorStore: VectorStore;
-  embedder: Embedder;
-  retriever: Retriever;
-  retrievalOrchestrator: RetrievalOrchestrator;
-  retrievalDisclosureService: RetrievalDisclosureService;
-  retrievalAnalyticsService: RetrievalAnalyticsService;
-  embeddingMaintenanceService: EmbeddingMaintenanceService;
-  runtimeService: MemoryRuntimeService;
-  graduation: GraduationPipeline;
-  endlessMemoryServices: EndlessMemoryServices;
-  sharedMemoryServices: SharedMemoryServices;
-  ingestService: MemoryIngestService;
-  queryService: MemoryQueryService;
-}
-
-export function createMemoryServiceComposition(
-  options: MemoryServiceCompositionOptions
-): MemoryServiceComposition {
-  const factories = options.factories ?? {};
-  const expandPath = factories.expandPath ?? defaultExpandPath;
-  const createToolEmbedding = factories.createToolObservationEmbedding ?? defaultCreateToolObservationEmbedding;
-
-  const storagePath = expandPath(options.config.storagePath);
-  const projectPathForMirror = options.getProjectPath?.() ?? options.config.projectPath ?? process.cwd();
-  const readOnly = options.config.readOnly ?? false;
-  const lightweightMode = options.config.lightweightMode ?? false;
-  const embeddingOnly = options.config.embeddingOnly ?? false;
-  const sharedStoreConfig = options.config.sharedStoreConfig ?? options.defaultSharedStoreConfig ?? {
-    enabled: true,
-    autoPromote: true,
-    searchShared: true,
-    minConfidenceForPromotion: 0.8,
-    sharedStoragePath: options.defaultSharedStoragePath
-  };
-
-  let sharedMemoryServices: SharedMemoryServices | null = null;
-
-  const engineServices = (factories.createMemoryEngineServices ?? defaultCreateMemoryEngineServices)({
-    storagePath,
-    readOnly,
-    embeddingModel: options.config.embeddingModel,
-    cwd: projectPathForMirror,
-    initialize: options.initialize,
-    getProjectHash: options.getProjectHash,
-    getProjectPath: options.getProjectPath,
-    hasSharedStore: () => sharedMemoryServices?.isEnabled() ?? false,
-    sharedStore: {
-      get: (entryId: string) => sharedMemoryServices?.getEntryForDisclosure(entryId) ?? Promise.resolve(null)
-    },
-    createToolObservationEmbedding: (payload: ToolObservationPayload) => createToolEmbedding(
-      payload.toolName,
-      payload.metadata || {},
-      payload.success
-    )
-  });
-
-  const endlessMemoryServices = (factories.createEndlessMemoryServices ?? defaultCreateEndlessMemoryServices)({
-    eventStore: engineServices.sqliteStore as unknown as EventStore,
-    configStore: engineServices.sqliteStore,
-    initialize: options.initialize
-  });
-
-  sharedMemoryServices = (factories.createSharedMemoryServices ?? defaultCreateSharedMemoryServices)({
-    config: sharedStoreConfig,
-    defaultSharedStoragePath: options.defaultSharedStoragePath,
-    readOnly,
-    expandPath,
-    embedder: engineServices.embedder,
-    retriever: engineServices.retriever
-  });
-
-  const runtimeService = (factories.createMemoryRuntimeService ?? defaultCreateMemoryRuntimeService)({
-    sqliteStore: engineServices.sqliteStore,
-    eventStore: engineServices.sqliteStore as unknown as EventStore,
-    vectorStore: engineServices.vectorStore,
-    embedder: engineServices.embedder,
-    retriever: engineServices.retriever,
-    graduation: engineServices.graduation,
-    endlessMemoryServices,
-    sharedMemoryServices,
-    readOnly,
-    lightweightMode,
-    embeddingOnly
-  });
-
-  const embeddingMaintenanceService = (
-    factories.createEmbeddingMaintenanceService ?? defaultCreateEmbeddingMaintenanceService
-  )({
-    storagePath,
-    initialize: options.initialize,
-    getEmbeddingModelName: () => engineServices.embedder.getModelName(),
-    vectorStore: engineServices.vectorStore,
-    eventStore: {
-      clearEmbeddingOutbox: () => engineServices.sqliteStore.clearEmbeddingOutbox(),
-      getEventsPage: async (limit, offset) => {
-        const events = await engineServices.sqliteStore.getEventsPage(limit, offset);
-        return events.map((event) => ({ id: event.id, content: event.content }));
-      },
-      enqueueForEmbedding: async (eventId, content) => {
-        await engineServices.sqliteStore.enqueueForEmbedding(eventId, content);
-      }
-    },
-    getVectorWorker: () => runtimeService.getVectorWorker()
-  });
-
-  return {
-    storagePath,
-    readOnly,
-    lightweightMode,
-    embeddingOnly,
-    sqliteStore: engineServices.sqliteStore,
-    vectorStore: engineServices.vectorStore,
-    embedder: engineServices.embedder,
-    retriever: engineServices.retriever,
-    retrievalOrchestrator: engineServices.retrievalOrchestrator,
-    retrievalDisclosureService: engineServices.retrievalDisclosureService,
-    retrievalAnalyticsService: engineServices.retrievalAnalyticsService,
-    embeddingMaintenanceService,
-    runtimeService,
-    graduation: engineServices.graduation,
-    endlessMemoryServices,
-    sharedMemoryServices,
-    ingestService: engineServices.ingestService,
-    queryService: engineServices.queryService
-  };
-}
-
-function defaultExpandPath(targetPath: string): string {
-  if (targetPath.startsWith('~')) {
-    return path.join(os.homedir(), targetPath.slice(1));
-  }
-  return targetPath;
-}