claude-memory-layer 1.0.28 → 1.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-layer",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Claude Code plugin that learns from conversations to provide personalized assistance",
   "main": "dist/index.js",
   "bin": {
@@ -23,7 +23,8 @@
     "ops:health": "npm run ops:sync-gap:report && npm run ops:sync-gap:heal && npm run ops:review:resolve",
     "ops:projects:clean-unknown": "node scripts/delete-unknown-projects.js",
     "benchmark:replay": "tsx scripts/replay-retrieval-benchmark.ts",
-    "benchmark:qrels": "tsx scripts/generate-session-qrels.ts"
+    "benchmark:qrels": "tsx scripts/generate-session-qrels.ts",
+    "postinstall": "node scripts/postinstall-embedding-backend.cjs"
   },
   "keywords": [
     "claude-code",
@@ -40,7 +41,6 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.13.0",
-    "@huggingface/transformers": "^3.8.1",
     "@lancedb/lancedb": "^0.5.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.6.2",
@@ -49,6 +49,9 @@
     "mongodb": "^6.14.0",
     "zod": "^3.22.0"
   },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^3.8.1"
+  },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^20.11.0",

package/scripts/postinstall-embedding-backend.cjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync, spawnSync } = require('node:child_process');
+const path = require('node:path');
+const { createRequire } = require('node:module');
+
+const EMBEDDING_BACKEND_PACKAGE_NAME = '@huggingface/transformers';
+const EMBEDDING_BACKEND_VERSION = '3.8.1';
+const EMBEDDING_BACKEND_PACKAGE = `${EMBEDDING_BACKEND_PACKAGE_NAME}@${EMBEDDING_BACKEND_VERSION}`;
+const REPAIR_GUARD_ENV = 'CLAUDE_MEMORY_LAYER_EMBEDDING_POSTINSTALL_REPAIR';
+const SKIP_ENV = 'CLAUDE_MEMORY_LAYER_SKIP_EMBEDDING_POSTINSTALL';
+
+function parseCudaMajor(output) {
+  const releaseMatch = String(output).match(/release\s+(\d+)(?:\.\d+)?/i);
+  if (releaseMatch) return Number(releaseMatch[1]);
+
+  const versionMatch = String(output).match(/\bV(\d+)\.\d+/i);
+  if (versionMatch) return Number(versionMatch[1]);
+
+  return null;
+}
+
+function parseCudaMajorFromEnv(env = process.env) {
+  const value = env.ONNXRUNTIME_NODE_INSTALL_CUDA || env.npm_config_onnxruntime_node_install_cuda;
+  if (!value) return null;
+  if (value === 'v11' || value === '11') return 11;
+  if (value === 'v12' || value === '12') return 12;
+  return null;
+}
+
+function detectCudaMajor({ env = process.env, execFileSyncImpl = execFileSync } = {}) {
+  const envMajor = parseCudaMajorFromEnv(env);
+  if (envMajor) return envMajor;
+
+  try {
+    return parseCudaMajor(execFileSyncImpl('nvcc', ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }));
+  } catch {
+    return null;
+  }
+}
+
+function isSkipRequested(env = process.env) {
+  if (env[SKIP_ENV] === '1' || env[REPAIR_GUARD_ENV] === '1') return true;
+  if (env.npm_config_optional === 'false') return true;
+  if (String(env.npm_config_omit || '').split(',').map((item) => item.trim()).includes('optional')) return true;
+  return false;
+}
+
+function isEmbeddingBackendAvailable(rootDir = process.cwd()) {
+  try {
+    const requireFromRoot = createRequire(path.join(rootDir, 'package.json'));
+    requireFromRoot.resolve(EMBEDDING_BACKEND_PACKAGE_NAME);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shouldAttemptAutoInstall({ platform, arch, transformersAvailable, skipRequested }) {
+  return platform === 'linux' &&
+    arch === 'x64' &&
+    !transformersAvailable &&
+    !skipRequested;
+}
+
+function createRepairEnv(env = process.env) {
+  return {
+    ...env,
+    ONNXRUNTIME_NODE_INSTALL_CUDA: 'skip',
+    [REPAIR_GUARD_ENV]: '1'
+  };
+}
+
+function createNpmInstallArgs() {
+  return [
+    'install',
+    '--no-save',
+    '--no-package-lock',
+    '--omit=dev',
+    EMBEDDING_BACKEND_PACKAGE
+  ];
+}
+
+function runPostinstall({
+  rootDir = process.cwd(),
+  env = process.env,
+  platform = process.platform,
+  arch = process.arch,
+  execFileSyncImpl = execFileSync,
+  spawnSyncImpl = spawnSync,
+  log = console.log,
+  warn = console.warn
+} = {}) {
+  const transformersAvailable = isEmbeddingBackendAvailable(rootDir);
+  const skipRequested = isSkipRequested(env);
+  const cudaMajor = detectCudaMajor({ env, execFileSyncImpl });
+
+  if (!shouldAttemptAutoInstall({ platform, arch, cudaMajor, transformersAvailable, skipRequested })) {
+    return { attempted: false, cudaMajor, transformersAvailable, skipRequested };
+  }
+
+  log('[claude-memory-layer] Optional embedding backend is missing on Linux x64. Installing CPU-only embedding backend...');
+
+  const npmCommand = platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSyncImpl(npmCommand, createNpmInstallArgs(), {
+    cwd: rootDir,
+    env: createRepairEnv(env),
+    stdio: 'inherit'
+  });
+
+  if (result.error || result.status !== 0) {
+    warn('[claude-memory-layer] Optional embedding backend repair failed. Claude Memory Layer is installed, but semantic/vector embeddings may be unavailable until you run:');
+    warn(`  ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install -g claude-memory-layer@latest`);
+    if (result.error) warn(`  ${result.error.message}`);
+    return { attempted: true, success: false, cudaMajor, transformersAvailable, skipRequested };
+  }
+
+  log('[claude-memory-layer] Optional embedding backend installed with CPU-only ONNX Runtime.');
+  return { attempted: true, success: true, cudaMajor, transformersAvailable, skipRequested };
+}
+
+if (require.main === module) {
+  runPostinstall();
+}
+
+module.exports = {
+  EMBEDDING_BACKEND_PACKAGE,
+  parseCudaMajor,
+  parseCudaMajorFromEnv,
+  detectCudaMajor,
+  isSkipRequested,
+  isEmbeddingBackendAvailable,
+  shouldAttemptAutoInstall,
+  createRepairEnv,
+  createNpmInstallArgs,
+  runPostinstall
+};

package/src/apps/cli/index.ts

@@ -59,6 +59,10 @@ import {
   renderExternalMarketContextReport,
   type ExternalMarketProvider
 } from '../../core/external-market-context.js';
+import {
+  DEFAULT_EMBEDDING_FALLBACK_MODEL,
+  DEFAULT_EMBEDDING_MODEL
+} from '../../extensions/vector/embedder.js';
 
 // ============================================================
 // Hook Installation Utilities
@@ -1025,7 +1029,7 @@ program
   .option('-l, --limit <number>', 'Limit messages per session')
   .option('--session-limit <number>', 'Limit recent matching sessions to import')
   .option('-f, --force', 'Force reimport: delete existing events and reimport with turn_id grouping')
-  .option('--embedding-model <name>', 'Embedding model override (default: jinaai/jina-embeddings-v5-text-nano-text-matching, or env CLAUDE_MEMORY_EMBEDDING_MODEL; fallback env: CLAUDE_MEMORY_EMBEDDING_FALLBACK_MODEL)')
+  .option('--embedding-model <name>', `Embedding model override (default: ${DEFAULT_EMBEDDING_MODEL}, or env CLAUDE_MEMORY_EMBEDDING_MODEL; fallback: ${DEFAULT_EMBEDDING_FALLBACK_MODEL} or env CLAUDE_MEMORY_EMBEDDING_FALLBACK_MODEL)`)
   .option('-v, --verbose', 'Show detailed progress')
   .action(async (options) => {
     const startTime = Date.now();

package/src/core/types.ts

@@ -152,8 +152,8 @@ export const ConfigSchema = z.object({
   }).default({}),
   embedding: z.object({
     provider: z.enum(['local', 'openai']).default('local'),
-    model: z.string().default('jinaai/jina-embeddings-v5-text-nano-text-matching'),
-    openaiModel: z.string().default('jinaai/jina-embeddings-v5-text-nano-text-matching'),
+    model: z.string().default('Xenova/multilingual-e5-small'),
+    openaiModel: z.string().default('Xenova/multilingual-e5-small'),
     batchSize: z.number().default(32)
   }).default({}),
   retrieval: z.object({

package/src/extensions/vector/embedder.ts

@@ -14,13 +14,16 @@ type FeatureExtractionPipelineFactory = (
   model: string
 ) => Promise<NonNullable<Embedder['pipeline']>>;
 
+export const DEFAULT_EMBEDDING_MODEL = 'Xenova/multilingual-e5-small';
+export const DEFAULT_EMBEDDING_FALLBACK_MODEL = 'intfloat/multilingual-e5-small';
+
 export class Embedder {
   private pipeline: ((input: string, options?: Record<string, unknown>) => Promise<{ data: Float32Array }>) | null = null;
   private readonly modelName: string;
   private activeModelName: string;
   private initialized = false;
 
-  constructor(modelName: string = 'jinaai/jina-embeddings-v5-text-nano-text-matching') {
+  constructor(modelName: string = DEFAULT_EMBEDDING_MODEL) {
     this.modelName = modelName;
     this.activeModelName = modelName;
   }
@@ -31,7 +34,16 @@ export class Embedder {
   async initialize(): Promise<void> {
     if (this.initialized) return;
 
-    const pipeline = await withSuppressedKnownTransformersWarnings(() => loadTransformersPipeline());
+    const pipeline = await withSuppressedKnownTransformersWarnings(async () => {
+      try {
+        return await loadTransformersPipeline();
+      } catch (error) {
+        if (isMissingTransformersDependencyError(error)) {
+          throw createEmbeddingBackendUnavailableError(error);
+        }
+        throw error;
+      }
+    });
 
     try {
       this.pipeline = await withSuppressedKnownTransformersWarnings(() => pipeline('feature-extraction', this.modelName));
@@ -39,7 +51,7 @@ export class Embedder {
       this.initialized = true;
       return;
     } catch (primaryError) {
-      const fallbackModel = process.env.CLAUDE_MEMORY_EMBEDDING_FALLBACK_MODEL || 'onnx-community/embeddinggemma-300m-ONNX';
+      const fallbackModel = process.env.CLAUDE_MEMORY_EMBEDDING_FALLBACK_MODEL || DEFAULT_EMBEDDING_FALLBACK_MODEL;
       if (fallbackModel === this.modelName) {
         throw primaryError;
       }
@@ -186,6 +198,30 @@ export function isKnownBenignTransformersWarning(message: string): boolean {
     message.includes('dtype not specified for "model"');
 }
 
+export function isMissingTransformersDependencyError(error: unknown): boolean {
+  const maybeError = error as { code?: unknown; message?: unknown } | null;
+  const message = typeof maybeError?.message === 'string' ? maybeError.message : '';
+  return maybeError?.code === 'ERR_MODULE_NOT_FOUND' &&
+    message.includes("@huggingface/transformers");
+}
+
+export function createEmbeddingBackendUnavailableError(cause: unknown): Error & { cause?: unknown } {
+  const error = new Error(
+    [
+      'Optional embedding backend is not installed.',
+      '',
+      'Claude Memory Layer can run embeddings on CPU-only ONNX Runtime; CUDA is not required.',
+      'Reinstall globally with:',
+      '  ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install -g claude-memory-layer@latest',
+      '',
+      'If you are inside a local checkout or package directory, repair only the backend with:',
+      '  ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --no-save --no-package-lock --omit=dev @huggingface/transformers@3.8.1'
+    ].join('\n')
+  ) as Error & { cause?: unknown };
+  error.cause = cause;
+  return error;
+}
+
 async function loadTransformersPipeline(): Promise<FeatureExtractionPipelineFactory> {
   // Keep @huggingface/transformers lazy so importing MemoryService or pure
   // adapter helpers does not eagerly dlopen onnxruntime native bindings.

package/tests/apps/postinstall-embedding-backend.test.ts

@@ -0,0 +1,175 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+
+import { describe, expect, it } from 'vitest';
+
+const require = createRequire(import.meta.url);
+
+type SpawnCall = {
+  cmd: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+};
+
+type PostinstallEmbeddingBackend = {
+  EMBEDDING_BACKEND_PACKAGE: string;
+  parseCudaMajor(output: string): number | null;
+  shouldAttemptAutoInstall(input: {
+    platform: NodeJS.Platform;
+    arch: string;
+    cudaMajor: number | null;
+    transformersAvailable: boolean;
+    skipRequested: boolean;
+  }): boolean;
+  createRepairEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+  createNpmInstallArgs(): string[];
+  runPostinstall(input?: {
+    rootDir?: string;
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    execFileSyncImpl?: () => string;
+    spawnSyncImpl?: (cmd: string, args: string[], options: { env: NodeJS.ProcessEnv }) => { status: number };
+    log?: () => void;
+    warn?: () => void;
+  }): { attempted: boolean; success?: boolean; cudaMajor: number | null; transformersAvailable: boolean; skipRequested: boolean };
+};
+
+function loadPostinstallModule(): PostinstallEmbeddingBackend {
+  return require('../../scripts/postinstall-embedding-backend.cjs') as PostinstallEmbeddingBackend;
+}
+
+describe('embedding backend postinstall repair', () => {
+  it('keeps the install-time embedding backend optional and registers postinstall repair', () => {
+    const pkg = JSON.parse(readFileSync('package.json', 'utf-8')) as {
+      scripts: Record<string, string>;
+      dependencies?: Record<string, string>;
+      optionalDependencies?: Record<string, string>;
+    };
+
+    expect(pkg.dependencies).not.toHaveProperty('@huggingface/transformers');
+    expect(pkg.optionalDependencies).toMatchObject({
+      '@huggingface/transformers': '^3.8.1'
+    });
+    expect(pkg.scripts.postinstall).toBe('node scripts/postinstall-embedding-backend.cjs');
+  });
+
+  it('detects CUDA major version from nvcc output', () => {
+    const postinstall = loadPostinstallModule();
+
+    expect(postinstall.parseCudaMajor('Cuda compilation tools, release 11.8, V11.8.89')).toBe(11);
+    expect(postinstall.parseCudaMajor('Cuda compilation tools, release 12.4, V12.4.131')).toBe(12);
+    expect(postinstall.parseCudaMajor('nvcc: NVIDIA (R) Cuda compiler driver')).toBeNull();
+  });
+
+  it('auto-installs a missing embedding backend for Linux x64 even when CUDA cannot be detected', () => {
+    const postinstall = loadPostinstallModule();
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'linux',
+      arch: 'x64',
+      cudaMajor: 11,
+      transformersAvailable: false,
+      skipRequested: false
+    })).toBe(true);
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'linux',
+      arch: 'x64',
+      cudaMajor: null,
+      transformersAvailable: false,
+      skipRequested: false
+    })).toBe(true);
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'linux',
+      arch: 'x64',
+      cudaMajor: 12,
+      transformersAvailable: false,
+      skipRequested: false
+    })).toBe(true);
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'linux',
+      arch: 'x64',
+      cudaMajor: null,
+      transformersAvailable: true,
+      skipRequested: false
+    })).toBe(false);
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'linux',
+      arch: 'arm64',
+      cudaMajor: null,
+      transformersAvailable: false,
+      skipRequested: false
+    })).toBe(false);
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'darwin',
+      arch: 'x64',
+      cudaMajor: null,
+      transformersAvailable: false,
+      skipRequested: false
+    })).toBe(false);
+
+    expect(postinstall.shouldAttemptAutoInstall({
+      platform: 'linux',
+      arch: 'x64',
+      cudaMajor: null,
+      transformersAvailable: false,
+      skipRequested: true
+    })).toBe(false);
+  });
+
+  it('repairs missing transformers with CPU-only onnxruntime install settings', () => {
+    const postinstall = loadPostinstallModule();
+
+    expect(postinstall.createRepairEnv({})).toMatchObject({
+      ONNXRUNTIME_NODE_INSTALL_CUDA: 'skip',
+      CLAUDE_MEMORY_LAYER_EMBEDDING_POSTINSTALL_REPAIR: '1'
+    });
+    expect(postinstall.createNpmInstallArgs()).toEqual([
+      'install',
+      '--no-save',
+      '--no-package-lock',
+      '--omit=dev',
+      postinstall.EMBEDDING_BACKEND_PACKAGE
+    ]);
+  });
+
+  it('runs the automatic repair command when Linux x64 skipped the optional backend without detectable CUDA', () => {
+    const postinstall = loadPostinstallModule();
+    const rootDir = mkdtempSync(join(tmpdir(), 'cml-postinstall-test-'));
+    const calls: SpawnCall[] = [];
+
+    try {
+      writeFileSync(join(rootDir, 'package.json'), JSON.stringify({ name: 'claude-memory-layer-install-root' }));
+
+      const result = postinstall.runPostinstall({
+        rootDir,
+        env: {},
+        platform: 'linux',
+        arch: 'x64',
+        execFileSyncImpl: () => '',
+        spawnSyncImpl: (cmd, args, options) => {
+          calls.push({ cmd, args, env: options.env });
+          return { status: 0 };
+        },
+        log: () => undefined,
+        warn: () => undefined
+      });
+
+      expect(result).toMatchObject({ attempted: true, success: true, cudaMajor: null, transformersAvailable: false });
+      expect(calls).toHaveLength(1);
+      expect(calls[0]?.cmd).toBe('npm');
+      expect(calls[0]?.args).toEqual(postinstall.createNpmInstallArgs());
+      expect(calls[0]?.env.ONNXRUNTIME_NODE_INSTALL_CUDA).toBe('skip');
+      expect(calls[0]?.env.CLAUDE_MEMORY_LAYER_EMBEDDING_POSTINSTALL_REPAIR).toBe('1');
+    } finally {
+      rmSync(rootDir, { recursive: true, force: true });
+    }
+  });
+});

package/tests/extensions/embedder-warning-suppression.test.ts

@@ -1,11 +1,41 @@
 import { describe, expect, it, vi } from 'vitest';
 
 import {
+  DEFAULT_EMBEDDING_MODEL,
+  Embedder,
+  createEmbeddingBackendUnavailableError,
   isKnownBenignTransformersWarning,
+  isMissingTransformersDependencyError,
   withSuppressedKnownTransformersWarnings
 } from '../../src/extensions/vector/embedder.js';
+import { ConfigSchema } from '../../src/core/types.js';
 
 describe('Embedder warning suppression', () => {
+  it('uses a CPU-friendly multilingual Korean-capable default embedding model', () => {
+    expect(DEFAULT_EMBEDDING_MODEL).toBe('Xenova/multilingual-e5-small');
+    expect(new Embedder().getModelName()).toBe(DEFAULT_EMBEDDING_MODEL);
+
+    const parsedConfig = ConfigSchema.parse({});
+    expect(parsedConfig.embedding.model).toBe(DEFAULT_EMBEDDING_MODEL);
+    expect(parsedConfig.embedding.openaiModel).toBe(DEFAULT_EMBEDDING_MODEL);
+  });
+
+  it('turns missing optional @huggingface/transformers errors into actionable install guidance', () => {
+    const missingBackendError = Object.assign(
+      new Error("Cannot find package '@huggingface/transformers' imported from /tmp/dist/cli/index.js"),
+      { code: 'ERR_MODULE_NOT_FOUND' }
+    );
+
+    expect(isMissingTransformersDependencyError(missingBackendError)).toBe(true);
+    expect(isMissingTransformersDependencyError(new Error('network failure'))).toBe(false);
+
+    const friendly = createEmbeddingBackendUnavailableError(missingBackendError);
+    expect(friendly.message).toContain('Optional embedding backend is not installed');
+    expect(friendly.message).toContain('ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install -g claude-memory-layer@latest');
+    expect(friendly.message).toContain('ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install --no-save --no-package-lock --omit=dev @huggingface/transformers@3.8.1');
+    expect(friendly.cause).toBe(missingBackendError);
+  });
+
   it('recognizes known benign transformer warnings', () => {
     expect(isKnownBenignTransformersWarning('Unknown model class "eurobert", attempting to construct from base class.')).toBe(true);
     expect(isKnownBenignTransformersWarning('dtype not specified for "model". Using the default dtype (fp32).')).toBe(true);