claude-memory-layer 1.0.27 → 1.0.29

package/tests/core/memory-runtime-service.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  createMemoryRuntimeService,
+  type MemoryRuntimeServicesFactories
+} from '../../src/core/engine/memory-runtime-service.js';
+import type { EventStore } from '../../src/core/event-store.js';
+import type { Embedder } from '../../src/core/embedder.js';
+import type { GraduationPipeline } from '../../src/core/graduation.js';
+import type { Retriever } from '../../src/core/retriever.js';
+import type { VectorStore } from '../../src/core/vector-store.js';
+
+function makeHarness(options?: { readOnly?: boolean; lightweightMode?: boolean; embeddingOnly?: boolean }) {
+  const calls: string[] = [];
+  const eventStore = { marker: 'event-store' } as unknown as EventStore;
+  const vectorStore = {
+    initialize: async () => { calls.push('vector.initialize'); }
+  } as unknown as VectorStore;
+  const embedder = {
+    initialize: async () => { calls.push('embedder.initialize'); }
+  } as unknown as Embedder;
+  const graduation = {
+    marker: 'graduation',
+    recordAccess: (eventId: string, sessionId: string, confidence: number = 1.0) => {
+      calls.push(`graduation.recordAccess:${eventId}:${sessionId}:${confidence}`);
+    }
+  } as unknown as GraduationPipeline;
+  const retriever = {
+    setGraduationPipeline: (pipeline: GraduationPipeline) => {
+      calls.push(pipeline === graduation ? 'retriever.setGraduationPipeline' : 'retriever.setGraduationPipeline:unknown');
+    }
+  } as unknown as Retriever;
+
+  const vectorWorker = {
+    start: () => { calls.push('vectorWorker.start'); },
+    stop: () => { calls.push('vectorWorker.stop'); },
+    processAll: async () => {
+      calls.push('vectorWorker.processAll');
+      return 3;
+    }
+  };
+  const graduationWorker = {
+    start: () => { calls.push('graduationWorker.start'); },
+    stop: () => { calls.push('graduationWorker.stop'); },
+    forceRun: async () => {
+      calls.push('graduationWorker.forceRun');
+      return { evaluated: 2, graduated: 1, byLevel: { L0: 1 } };
+    }
+  };
+
+  const factories: MemoryRuntimeServicesFactories = {
+    createVectorWorker: (receivedEventStore, receivedVectorStore, receivedEmbedder) => {
+      calls.push(
+        receivedEventStore === eventStore && receivedVectorStore === vectorStore && receivedEmbedder === embedder
+          ? 'createVectorWorker'
+          : 'createVectorWorker:unknown'
+      );
+      return vectorWorker as unknown as ReturnType<NonNullable<MemoryRuntimeServicesFactories['createVectorWorker']>>;
+    },
+    createGraduationWorker: (receivedEventStore, receivedGraduation) => {
+      calls.push(
+        receivedEventStore === eventStore && receivedGraduation === graduation
+          ? 'createGraduationWorker'
+          : 'createGraduationWorker:unknown'
+      );
+      return graduationWorker as unknown as ReturnType<NonNullable<MemoryRuntimeServicesFactories['createGraduationWorker']>>;
+    }
+  };
+
+  const service = createMemoryRuntimeService({
+    sqliteStore: {
+      initialize: async () => { calls.push('sqlite.initialize'); },
+      close: async () => { calls.push('sqlite.close'); }
+    },
+    eventStore,
+    vectorStore,
+    embedder,
+    retriever,
+    graduation,
+    endlessMemoryServices: {
+      initializeFromSavedMode: async () => { calls.push('endless.initializeFromSavedMode'); },
+      shutdown: () => { calls.push('endless.shutdown'); }
+    },
+    sharedMemoryServices: {
+      initialize: async () => { calls.push('shared.initialize'); },
+      close: async () => { calls.push('shared.close'); }
+    },
+    readOnly: options?.readOnly ?? false,
+    lightweightMode: options?.lightweightMode ?? false,
+    embeddingOnly: options?.embeddingOnly ?? false,
+    factories
+  });
+
+  return { service, calls, vectorWorker };
+}
+
+describe('createMemoryRuntimeService', () => {
+  it('initializes only sqlite in lightweight mode and keeps initialize idempotent', async () => {
+    const harness = makeHarness({ lightweightMode: true });
+
+    await harness.service.initialize();
+    await harness.service.initialize();
+
+    expect(harness.service.isInitialized()).toBe(true);
+    expect(harness.calls).toEqual(['sqlite.initialize']);
+    await expect(harness.service.processPendingEmbeddings()).resolves.toBe(0);
+    await expect(harness.service.forceGraduation()).resolves.toEqual({ evaluated: 0, graduated: 0, byLevel: {} });
+  });
+
+  it('records memory access through the graduation pipeline without initializing runtime workers', () => {
+    const harness = makeHarness();
+
+    harness.service.recordMemoryAccess('event-1', 'session-2', 0.42);
+
+    expect(harness.service.isInitialized()).toBe(false);
+    expect(harness.calls).toEqual(['graduation.recordAccess:event-1:session-2:0.42']);
+  });
+
+  it('starts vector and graduation workers plus writable lifecycle services by default', async () => {
+    const harness = makeHarness();
+
+    await harness.service.initialize();
+
+    expect(harness.calls).toEqual([
+      'sqlite.initialize',
+      'vector.initialize',
+      'embedder.initialize',
+      'createVectorWorker',
+      'vectorWorker.start',
+      'retriever.setGraduationPipeline',
+      'createGraduationWorker',
+      'graduationWorker.start',
+      'endless.initializeFromSavedMode',
+      'shared.initialize'
+    ]);
+    expect(harness.service.getVectorWorker()).toBe(harness.vectorWorker);
+    await expect(harness.service.processPendingEmbeddings()).resolves.toBe(3);
+    await expect(harness.service.forceGraduation()).resolves.toEqual({ evaluated: 2, graduated: 1, byLevel: { L0: 1 } });
+  });
+
+  it('skips workers and write lifecycle services in read-only mode', async () => {
+    const harness = makeHarness({ readOnly: true });
+
+    await harness.service.initialize();
+
+    expect(harness.calls).toEqual([
+      'sqlite.initialize',
+      'vector.initialize',
+      'embedder.initialize'
+    ]);
+    expect(harness.service.getVectorWorker()).toBeNull();
+  });
+
+  it('embedding-only mode starts vector worker but skips graduation worker', async () => {
+    const harness = makeHarness({ embeddingOnly: true });
+
+    await harness.service.initialize();
+
+    expect(harness.calls).toEqual([
+      'sqlite.initialize',
+      'vector.initialize',
+      'embedder.initialize',
+      'createVectorWorker',
+      'vectorWorker.start',
+      'endless.initializeFromSavedMode',
+      'shared.initialize'
+    ]);
+    await expect(harness.service.forceGraduation()).resolves.toEqual({ evaluated: 0, graduated: 0, byLevel: {} });
+  });
+
+  it('returns a fresh empty graduation result when no graduation worker exists', async () => {
+    const harness = makeHarness({ embeddingOnly: true });
+    await harness.service.initialize();
+
+    const first = await harness.service.forceGraduation();
+    first.byLevel.L0 = 99;
+    first.evaluated = 99;
+
+    const second = await harness.service.forceGraduation();
+
+    expect(second).toEqual({ evaluated: 0, graduated: 0, byLevel: {} });
+    expect(second).not.toBe(first);
+    expect(second.byLevel).not.toBe(first.byLevel);
+  });
+
+  it('shuts down workers and backing services in the historical MemoryService order', async () => {
+    const harness = makeHarness();
+    await harness.service.initialize();
+    harness.calls.length = 0;
+
+    await harness.service.shutdown();
+
+    expect(harness.calls).toEqual([
+      'graduationWorker.stop',
+      'endless.shutdown',
+      'vectorWorker.stop',
+      'shared.close',
+      'sqlite.close'
+    ]);
+  });
+});

package/tests/core/memory-service-composition.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  createMemoryServiceComposition,
+  type MemoryServiceCompositionFactories
+} from '../../src/core/engine/memory-service-composition.js';
+import type { SharedStoreConfig, ToolObservationPayload } from '../../src/core/types.js';
+
+const sharedStoreConfig: SharedStoreConfig = {
+  enabled: true,
+  autoPromote: true,
+  searchShared: true,
+  minConfidenceForPromotion: 0.8,
+  sharedStoragePath: '~/shared-memory'
+};
+
+describe('createMemoryServiceComposition', () => {
+  it('wires engine, endless, shared, runtime, and embedding maintenance services for MemoryService', async () => {
+    const initialize = vi.fn(async () => undefined);
+    let projectHash: string | null = 'project-hash-1';
+    let projectPath: string | null = '/repo/project';
+
+    const sqliteStore = {
+      clearEmbeddingOutbox: vi.fn(async () => undefined),
+      getEventsPage: vi.fn(async () => [{ id: 'event-1', content: 'event content' }]),
+      enqueueForEmbedding: vi.fn(async () => undefined)
+    };
+    const vectorStore = { name: 'vector-store' };
+    const embedder = { getModelName: vi.fn(() => 'test-embedding-model') };
+    const retriever = { setSharedStores: vi.fn() };
+    const graduation = { name: 'graduation' };
+    const ingestService = { name: 'ingest' };
+    const queryService = { name: 'query' };
+    const retrievalOrchestrator = { name: 'retrieval-orchestrator' };
+    const retrievalDisclosureService = { name: 'retrieval-disclosure' };
+    const retrievalAnalyticsService = { name: 'retrieval-analytics' };
+    const endlessMemoryServices = { name: 'endless-memory' };
+    const sharedMemoryServices = {
+      isEnabled: vi.fn(() => true),
+      getEntryForDisclosure: vi.fn(async (entryId: string) => ({ id: entryId }))
+    };
+    const runtimeService = { getVectorWorker: vi.fn(() => ({ name: 'vector-worker' })) };
+    const embeddingMaintenanceService = { getEmbeddingModelName: vi.fn(() => 'maintenance-model') };
+
+    const factories: MemoryServiceCompositionFactories = {
+      expandPath: vi.fn((targetPath: string) => targetPath.replace('~', '/home/test')),
+      createToolObservationEmbedding: vi.fn((toolName: string) => `embedding:${toolName}`),
+      createMemoryEngineServices: vi.fn(() => ({
+        storagePath: '/expanded/storage',
+        sqliteStore,
+        vectorStore,
+        embedder,
+        matcher: { name: 'matcher' },
+        retriever,
+        retrievalOrchestrator,
+        retrievalDisclosureService,
+        retrievalAnalyticsService,
+        graduation,
+        mdMirror: { name: 'md-mirror' },
+        ingestService,
+        queryService
+      }) as any),
+      createEndlessMemoryServices: vi.fn(() => endlessMemoryServices as any),
+      createSharedMemoryServices: vi.fn(() => sharedMemoryServices as any),
+      createMemoryRuntimeService: vi.fn(() => runtimeService as any),
+      createEmbeddingMaintenanceService: vi.fn(() => embeddingMaintenanceService as any)
+    };
+
+    const composition = createMemoryServiceComposition({
+      config: {
+        storagePath: '~/memory-store',
+        embeddingModel: 'explicit-model',
+        readOnly: true,
+        lightweightMode: true,
+        embeddingOnly: true,
+        projectHash,
+        projectPath,
+        sharedStoreConfig
+      },
+      defaultSharedStoragePath: '/default/shared',
+      initialize,
+      getProjectHash: () => projectHash,
+      getProjectPath: () => projectPath,
+      factories
+    });
+
+    expect(factories.expandPath).toHaveBeenCalledWith('~/memory-store');
+    expect(factories.createMemoryEngineServices).toHaveBeenCalledWith(expect.objectContaining({
+      storagePath: '/home/test/memory-store',
+      readOnly: true,
+      embeddingModel: 'explicit-model',
+      cwd: '/repo/project',
+      initialize,
+      getProjectHash: expect.any(Function),
+      getProjectPath: expect.any(Function),
+      hasSharedStore: expect.any(Function),
+      sharedStore: expect.objectContaining({ get: expect.any(Function) }),
+      createToolObservationEmbedding: expect.any(Function)
+    }));
+
+    const engineOptions = vi.mocked(factories.createMemoryEngineServices).mock.calls[0][0];
+    expect(engineOptions.createToolObservationEmbedding({
+      toolName: 'Read',
+      metadata: { path: 'README.md' },
+      success: true
+    } as ToolObservationPayload)).toBe('embedding:Read');
+    expect(factories.createToolObservationEmbedding).toHaveBeenCalledWith(
+      'Read',
+      { path: 'README.md' },
+      true
+    );
+
+    expect(factories.createEndlessMemoryServices).toHaveBeenCalledWith({
+      eventStore: sqliteStore,
+      configStore: sqliteStore,
+      initialize
+    });
+    expect(factories.createSharedMemoryServices).toHaveBeenCalledWith({
+      config: sharedStoreConfig,
+      defaultSharedStoragePath: '/default/shared',
+      readOnly: true,
+      expandPath: expect.any(Function),
+      embedder,
+      retriever
+    });
+    expect(factories.createMemoryRuntimeService).toHaveBeenCalledWith(expect.objectContaining({
+      sqliteStore,
+      eventStore: sqliteStore,
+      vectorStore,
+      embedder,
+      retriever,
+      graduation,
+      endlessMemoryServices,
+      sharedMemoryServices,
+      readOnly: true,
+      lightweightMode: true,
+      embeddingOnly: true
+    }));
+    expect(factories.createEmbeddingMaintenanceService).toHaveBeenCalledWith(expect.objectContaining({
+      storagePath: '/home/test/memory-store',
+      initialize,
+      getEmbeddingModelName: expect.any(Function),
+      vectorStore,
+      eventStore: expect.objectContaining({
+        clearEmbeddingOutbox: expect.any(Function),
+        getEventsPage: expect.any(Function),
+        enqueueForEmbedding: expect.any(Function)
+      }),
+      getVectorWorker: expect.any(Function)
+    }));
+
+    const embeddingOptions = vi.mocked(factories.createEmbeddingMaintenanceService).mock.calls[0][0];
+    expect(embeddingOptions.getEmbeddingModelName()).toBe('test-embedding-model');
+    expect(embeddingOptions.getVectorWorker()).toEqual({ name: 'vector-worker' });
+    await embeddingOptions.eventStore.clearEmbeddingOutbox();
+    await expect(embeddingOptions.eventStore.getEventsPage(10, 0)).resolves.toEqual([
+      { id: 'event-1', content: 'event content' }
+    ]);
+    await embeddingOptions.eventStore.enqueueForEmbedding('event-1', 'event content');
+    expect(sqliteStore.clearEmbeddingOutbox).toHaveBeenCalled();
+    expect(sqliteStore.getEventsPage).toHaveBeenCalledWith(10, 0);
+    expect(sqliteStore.enqueueForEmbedding).toHaveBeenCalledWith('event-1', 'event content');
+
+    expect(await engineOptions.sharedStore?.get('shared-1')).toEqual({ id: 'shared-1' });
+    expect(engineOptions.hasSharedStore()).toBe(true);
+    projectHash = 'project-hash-2';
+    projectPath = '/repo/other';
+    expect(engineOptions.getProjectHash()).toBe('project-hash-2');
+    expect(engineOptions.getProjectPath?.()).toBe('/repo/other');
+
+    expect(composition).toMatchObject({
+      storagePath: '/home/test/memory-store',
+      readOnly: true,
+      lightweightMode: true,
+      embeddingOnly: true,
+      sqliteStore,
+      vectorStore,
+      embedder,
+      retriever,
+      retrievalOrchestrator,
+      retrievalDisclosureService,
+      retrievalAnalyticsService,
+      graduation,
+      ingestService,
+      queryService,
+      endlessMemoryServices,
+      sharedMemoryServices,
+      runtimeService,
+      embeddingMaintenanceService
+    });
+  });
+});

package/tests/core/memory-service-config.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  DEFAULT_ENABLED_SHARED_STORE_CONFIG as CONFIG_DEFAULT_ENABLED_SHARED_STORE_CONFIG,
+  DISABLED_SHARED_STORE_CONFIG as CONFIG_DISABLED_SHARED_STORE_CONFIG,
+  DEFAULT_SHARED_STORAGE_PATH as CONFIG_DEFAULT_SHARED_STORAGE_PATH
+} from '../../src/services/memory-service-config.js';
+import {
+  DEFAULT_ENABLED_SHARED_STORE_CONFIG as FACADE_DEFAULT_ENABLED_SHARED_STORE_CONFIG,
+  DISABLED_SHARED_STORE_CONFIG as FACADE_DISABLED_SHARED_STORE_CONFIG
+} from '../../src/services/memory-service.js';
+
+/**
+ * MemoryService should stay a thin compatibility facade. Shared defaults are
+ * owned by memory-service-config so registries can import them without pulling
+ * in the MemoryService class and creating a service-locator cycle.
+ */
+describe('memory-service-config', () => {
+  it('owns disabled shared-store defaults while memory-service preserves the public export', () => {
+    expect(CONFIG_DISABLED_SHARED_STORE_CONFIG).toMatchObject({
+      enabled: false,
+      autoPromote: false,
+      searchShared: false,
+      minConfidenceForPromotion: 0.8
+    });
+    expect(CONFIG_DISABLED_SHARED_STORE_CONFIG.sharedStoragePath).toContain('.claude-code');
+    expect(CONFIG_DISABLED_SHARED_STORE_CONFIG.sharedStoragePath).toContain('shared');
+    expect(FACADE_DISABLED_SHARED_STORE_CONFIG).toBe(CONFIG_DISABLED_SHARED_STORE_CONFIG);
+  });
+
+  it('owns enabled shared-store defaults while memory-service preserves the public export', () => {
+    expect(CONFIG_DEFAULT_ENABLED_SHARED_STORE_CONFIG).toEqual({
+      enabled: true,
+      autoPromote: true,
+      searchShared: true,
+      minConfidenceForPromotion: 0.8,
+      sharedStoragePath: CONFIG_DEFAULT_SHARED_STORAGE_PATH
+    });
+    expect(FACADE_DEFAULT_ENABLED_SHARED_STORE_CONFIG).toBe(CONFIG_DEFAULT_ENABLED_SHARED_STORE_CONFIG);
+  });
+});

package/tests/core/memory-service-facade.test.ts

@@ -0,0 +1,30 @@
+import { mkdtemp } from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+  DISABLED_SHARED_STORE_CONFIG,
+  MemoryService
+} from '../../src/services/memory-service.js';
+
+describe('MemoryService facade delegation', () => {
+  it('reads the embedding model name through the embedding maintenance facade', async () => {
+    const storagePath = await mkdtemp(path.join(os.tmpdir(), 'memory-service-facade-'));
+    const service = new MemoryService({
+      storagePath,
+      sharedStoreConfig: DISABLED_SHARED_STORE_CONFIG
+    });
+    const serviceInternals = service as unknown as {
+      embedder: { getModelName(): string };
+      embeddingMaintenanceService: { getEmbeddingModelName(): string };
+    };
+    serviceInternals.embedder = { getModelName: () => 'direct-embedder-model' };
+    serviceInternals.embeddingMaintenanceService = {
+      getEmbeddingModelName: () => 'maintenance-facade-model'
+    };
+
+    expect(service.getEmbeddingModelName()).toBe('maintenance-facade-model');
+  });
+});

package/tests/core/memory-service-registry.test.ts

@@ -0,0 +1,206 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+import { createMemoryServiceRegistry } from '../../src/services/memory-service-registry.js';
+import type { SharedStoreConfig } from '../../src/core/types.js';
+
+interface FakeService {
+  config: Record<string, unknown>;
+}
+
+const disabledSharedStoreConfig: SharedStoreConfig = {
+  enabled: false,
+  autoPromote: false,
+  searchShared: false,
+  minConfidenceForPromotion: 0.8,
+  sharedStoragePath: '/home/test/.claude-code/memory/shared'
+};
+
+function createRegistry(sessionProject?: { projectHash: string; projectPath: string }) {
+  const createdConfigs: Array<Record<string, unknown>> = [];
+  const registry = createMemoryServiceRegistry<FakeService>({
+    createService: (config) => {
+      createdConfigs.push(config as unknown as Record<string, unknown>);
+      return { config: config as unknown as Record<string, unknown> };
+    },
+    hashProjectPath: (projectPath) => `hash:${projectPath}`,
+    getProjectStoragePath: (projectPath) => `/storage/${projectPath}`,
+    getSessionProject: (sessionId) => sessionId === 'known-session' ? sessionProject ?? null : null,
+    homedir: () => '/home/test',
+    disabledSharedStoreConfig
+  });
+
+  return { registry, createdConfigs };
+}
+
+describe('createMemoryServiceRegistry', () => {
+  it('stays independent from the MemoryService facade to avoid service-locator cycles', () => {
+    const source = readFileSync('src/services/memory-service-registry.ts', 'utf8');
+
+    expect(source).not.toContain("from './memory-service.js'");
+    expect(source).not.toContain('from "./memory-service.js"');
+  });
+
+  it('caches the default writable service with global storage and disabled shared store', () => {
+    const { registry, createdConfigs } = createRegistry();
+
+    const first = registry.getDefaultMemoryService();
+    const second = registry.getDefaultMemoryService();
+
+    expect(first).toBe(second);
+    expect(createdConfigs).toHaveLength(1);
+    expect(first.config).toMatchObject({
+      storagePath: '~/.claude-code/memory',
+      analyticsEnabled: false,
+      sharedStoreConfig: disabledSharedStoreConfig
+    });
+  });
+
+  it('creates fresh read-only services to avoid holding locks', () => {
+    const { registry, createdConfigs } = createRegistry();
+
+    const first = registry.getReadOnlyMemoryService();
+    const second = registry.getReadOnlyMemoryService();
+
+    expect(first).not.toBe(second);
+    expect(createdConfigs).toHaveLength(2);
+    expect(first.config).toMatchObject({
+      storagePath: '~/.claude-code/memory',
+      readOnly: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: disabledSharedStoreConfig
+    });
+  });
+
+  it('caches project services by project hash and preserves project scope config', () => {
+    const { registry, createdConfigs } = createRegistry();
+
+    const first = registry.getMemoryServiceForProject('/workspace/app');
+    const second = registry.getMemoryServiceForProject('/workspace/app');
+
+    expect(first).toBe(second);
+    expect(createdConfigs).toHaveLength(1);
+    expect(first.config).toMatchObject({
+      storagePath: '/storage//workspace/app',
+      projectHash: 'hash:/workspace/app',
+      projectPath: '/workspace/app',
+      analyticsEnabled: false,
+      sharedStoreConfig: disabledSharedStoreConfig
+    });
+  });
+
+  it('preserves the first shared store config for cached project services', () => {
+    const { registry, createdConfigs } = createRegistry();
+    const firstSharedConfig: SharedStoreConfig = {
+      ...disabledSharedStoreConfig,
+      enabled: true,
+      searchShared: true,
+      sharedStoragePath: '/shared/first'
+    };
+    const laterSharedConfig: SharedStoreConfig = {
+      ...disabledSharedStoreConfig,
+      enabled: true,
+      autoPromote: true,
+      sharedStoragePath: '/shared/later'
+    };
+
+    const first = registry.getMemoryServiceForProject('/workspace/app', firstSharedConfig);
+    const second = registry.getMemoryServiceForProject('/workspace/app', laterSharedConfig);
+
+    expect(second).toBe(first);
+    expect(createdConfigs).toHaveLength(1);
+    expect(first.config.sharedStoreConfig).toBe(firstSharedConfig);
+    expect(first.config.sharedStoreConfig).not.toBe(laterSharedConfig);
+  });
+
+  it('resolves session services from the session registry and falls back to global service', () => {
+    const { registry } = createRegistry({
+      projectHash: 'registered-hash',
+      projectPath: '/workspace/registered'
+    });
+
+    const projectService = registry.getMemoryServiceForSession('known-session');
+    const directService = registry.getMemoryServiceForProject('/workspace/registered');
+    const fallbackService = registry.getMemoryServiceForSession('unknown-session');
+
+    expect(projectService).toBe(directService);
+    expect(fallbackService).toBe(registry.getDefaultMemoryService());
+  });
+
+  it('keeps registry methods safe when callers destructure a custom registry', () => {
+    const { registry } = createRegistry({
+      projectHash: 'registered-hash',
+      projectPath: '/workspace/registered'
+    });
+    const {
+      getDefaultMemoryService,
+      getMemoryServiceForProject,
+      getMemoryServiceForSession
+    } = registry;
+
+    const projectService = getMemoryServiceForSession('known-session');
+    const directService = getMemoryServiceForProject('/workspace/registered');
+    const fallbackService = getMemoryServiceForSession('unknown-session');
+
+    expect(projectService).toBe(directService);
+    expect(fallbackService).toBe(getDefaultMemoryService());
+  });
+
+  it('caches lightweight services separately for project and global sessions', () => {
+    const { registry } = createRegistry({
+      projectHash: 'registered-hash',
+      projectPath: '/workspace/registered'
+    });
+
+    const projectService = registry.getLightweightMemoryService('known-session');
+    const sameProjectService = registry.getLightweightMemoryService('known-session');
+    const globalService = registry.getLightweightMemoryService('unknown-session');
+
+    expect(projectService).toBe(sameProjectService);
+    expect(projectService).not.toBe(globalService);
+    expect(projectService.config).toMatchObject({
+      storagePath: '/storage//workspace/registered',
+      projectHash: 'registered-hash',
+      projectPath: '/workspace/registered',
+      lightweightMode: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: disabledSharedStoreConfig
+    });
+    expect(globalService.config).toMatchObject({
+      storagePath: '/home/test/.claude-code/memory',
+      lightweightMode: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: disabledSharedStoreConfig
+    });
+  });
+
+  it('caches lightweight project services for CLI read paths without reusing the full project service', () => {
+    const { registry, createdConfigs } = createRegistry();
+
+    const fullProjectService = registry.getMemoryServiceForProject('/workspace/app');
+    const lightweightProjectService = registry.getLightweightMemoryServiceForProject('/workspace/app');
+    const sameLightweightProjectService = registry.getLightweightMemoryServiceForProject('/workspace/app');
+
+    expect(lightweightProjectService).toBe(sameLightweightProjectService);
+    expect(lightweightProjectService).not.toBe(fullProjectService);
+    expect(createdConfigs).toHaveLength(2);
+    expect(lightweightProjectService.config).toMatchObject({
+      storagePath: '/storage//workspace/app',
+      projectHash: 'hash:/workspace/app',
+      projectPath: '/workspace/app',
+      lightweightMode: true,
+      analyticsEnabled: false,
+      sharedStoreConfig: disabledSharedStoreConfig
+    });
+  });
+
+  it('creates uncached services through the explicit factory facade', () => {
+    const { registry } = createRegistry();
+
+    const first = registry.createMemoryService({ storagePath: '/tmp/a' });
+    const second = registry.createMemoryService({ storagePath: '/tmp/a' });
+
+    expect(first).not.toBe(second);
+    expect(first.config).toMatchObject({ storagePath: '/tmp/a' });
+  });
+});