claude-memory-layer 1.0.29 → 1.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-layer",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "Claude Code plugin that learns from conversations to provide personalized assistance",
   "main": "dist/index.js",
   "bin": {
@@ -40,18 +40,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@hono/node-server": "^1.13.0",
+    "@hono/node-server": "^1.19.14",
+    "@huggingface/transformers": "^3.8.1",
     "@lancedb/lancedb": "^0.5.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.6.2",
     "commander": "^12.0.0",
-    "hono": "^4.0.0",
+    "hono": "^4.12.18",
     "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

@@ -45,8 +45,6 @@ function detectCudaMajor({ env = process.env, execFileSyncImpl = execFileSync }
 
 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;
 }
 
@@ -60,10 +58,9 @@ function isEmbeddingBackendAvailable(rootDir = process.cwd()) {
   }
 }
 
-function shouldAttemptAutoInstall({ platform, arch, cudaMajor, transformersAvailable, skipRequested }) {
+function shouldAttemptAutoInstall({ platform, arch, transformersAvailable, skipRequested }) {
   return platform === 'linux' &&
     arch === 'x64' &&
-    cudaMajor === 11 &&
     !transformersAvailable &&
     !skipRequested;
 }
@@ -104,7 +101,7 @@ function runPostinstall({
     return { attempted: false, cudaMajor, transformersAvailable, skipRequested };
   }
 
-  log('[claude-memory-layer] CUDA 11 detected and optional embedding backend is missing. Installing CPU-only embedding backend...');
+  log('[claude-memory-layer] Required embedding backend is missing on Linux x64. Repairing with CPU-only ONNX Runtime...');
 
   const npmCommand = platform === 'win32' ? 'npm.cmd' : 'npm';
   const result = spawnSyncImpl(npmCommand, createNpmInstallArgs(), {
@@ -114,13 +111,13 @@ function runPostinstall({
   });
 
   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('[claude-memory-layer] Required embedding backend repair failed. 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.');
+  log('[claude-memory-layer] Required embedding backend repaired with CPU-only ONNX Runtime.');
   return { attempted: true, success: true, cudaMajor, transformersAvailable, skipRequested };
 }
 

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,31 @@ 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(
+    [
+      'Required embedding backend is not installed.',
+      '',
+      'Claude Memory Layer requires @huggingface/transformers for local semantic/vector embeddings.',
+      'The backend runs 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

@@ -16,6 +16,7 @@ type SpawnCall = {
 type PostinstallEmbeddingBackend = {
   EMBEDDING_BACKEND_PACKAGE: string;
   parseCudaMajor(output: string): number | null;
+  isSkipRequested(env: NodeJS.ProcessEnv): boolean;
   shouldAttemptAutoInstall(input: {
     platform: NodeJS.Platform;
     arch: string;
@@ -42,20 +43,29 @@ function loadPostinstallModule(): PostinstallEmbeddingBackend {
 }
 
 describe('embedding backend postinstall repair', () => {
-  it('keeps the install-time embedding backend optional and registers postinstall repair', () => {
+  it('requires the embedding backend at install time and registers a broken-install repair hook', () => {
     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({
+    expect(pkg.dependencies).toMatchObject({
       '@huggingface/transformers': '^3.8.1'
     });
+    expect(pkg.optionalDependencies ?? {}).not.toHaveProperty('@huggingface/transformers');
     expect(pkg.scripts.postinstall).toBe('node scripts/postinstall-embedding-backend.cjs');
   });
 
+  it('only skips required-backend repair when the explicit repair guards are set', () => {
+    const postinstall = loadPostinstallModule();
+
+    expect(postinstall.isSkipRequested({ CLAUDE_MEMORY_LAYER_SKIP_EMBEDDING_POSTINSTALL: '1' })).toBe(true);
+    expect(postinstall.isSkipRequested({ CLAUDE_MEMORY_LAYER_EMBEDDING_POSTINSTALL_REPAIR: '1' })).toBe(true);
+    expect(postinstall.isSkipRequested({ npm_config_optional: 'false' })).toBe(false);
+    expect(postinstall.isSkipRequested({ npm_config_omit: 'optional' })).toBe(false);
+  });
+
   it('detects CUDA major version from nvcc output', () => {
     const postinstall = loadPostinstallModule();
 
@@ -64,7 +74,7 @@ describe('embedding backend postinstall repair', () => {
     expect(postinstall.parseCudaMajor('nvcc: NVIDIA (R) Cuda compiler driver')).toBeNull();
   });
 
-  it('only auto-installs the embedding backend for Linux x64 CUDA 11 when it is missing', () => {
+  it('auto-installs a missing embedding backend for Linux x64 even when CUDA cannot be detected', () => {
     const postinstall = loadPostinstallModule();
 
     expect(postinstall.shouldAttemptAutoInstall({
@@ -78,31 +88,39 @@ describe('embedding backend postinstall repair', () => {
     expect(postinstall.shouldAttemptAutoInstall({
       platform: 'linux',
       arch: 'x64',
-      cudaMajor: 11,
-      transformersAvailable: true,
+      cudaMajor: null,
+      transformersAvailable: false,
       skipRequested: false
-    })).toBe(false);
+    })).toBe(true);
 
     expect(postinstall.shouldAttemptAutoInstall({
       platform: 'linux',
-      arch: 'arm64',
-      cudaMajor: 11,
+      arch: 'x64',
+      cudaMajor: 12,
       transformersAvailable: false,
       skipRequested: false
-    })).toBe(false);
+    })).toBe(true);
 
     expect(postinstall.shouldAttemptAutoInstall({
-      platform: 'darwin',
+      platform: 'linux',
       arch: 'x64',
-      cudaMajor: 11,
-      transformersAvailable: false,
+      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: 12,
+      cudaMajor: null,
       transformersAvailable: false,
       skipRequested: false
     })).toBe(false);
@@ -110,7 +128,7 @@ describe('embedding backend postinstall repair', () => {
     expect(postinstall.shouldAttemptAutoInstall({
       platform: 'linux',
       arch: 'x64',
-      cudaMajor: 11,
+      cudaMajor: null,
       transformersAvailable: false,
       skipRequested: true
     })).toBe(false);
@@ -132,7 +150,7 @@ describe('embedding backend postinstall repair', () => {
     ]);
   });
 
-  it('runs the automatic repair command when Linux x64 CUDA 11 skipped the optional backend', () => {
+  it('runs the repair command when Linux x64 is missing the required backend without detectable CUDA', () => {
     const postinstall = loadPostinstallModule();
     const rootDir = mkdtempSync(join(tmpdir(), 'cml-postinstall-test-'));
     const calls: SpawnCall[] = [];
@@ -145,7 +163,7 @@ describe('embedding backend postinstall repair', () => {
         env: {},
         platform: 'linux',
         arch: 'x64',
-        execFileSyncImpl: () => 'Cuda compilation tools, release 11.8, V11.8.89',
+        execFileSyncImpl: () => '',
         spawnSyncImpl: (cmd, args, options) => {
           calls.push({ cmd, args, env: options.env });
           return { status: 0 };
@@ -154,7 +172,7 @@ describe('embedding backend postinstall repair', () => {
         warn: () => undefined
       });
 
-      expect(result).toMatchObject({ attempted: true, success: true, cudaMajor: 11, transformersAvailable: false });
+      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());

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

@@ -1,11 +1,42 @@
 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 required @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('Required embedding backend is not installed');
+    expect(friendly.message).toContain('Claude Memory Layer requires @huggingface/transformers');
+    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);