claude-memory-layer 1.0.29 → 1.0.31

package/README.md

@@ -36,7 +36,7 @@ npx claude-memory-layer status
 ```
 
 - `install`은 **한 번만** 하면 됩니다(Claude Code hooks 등록).
-- Linux x64 + CUDA 11 환경에서는 설치 중 optional embedding backend를 CPU-only ONNX Runtime으로 자동 복구합니다.
+- `@huggingface/transformers`는 일반 dependency라 기본 설치에 포함됩니다. 따라서 정상 설치 후 embedding runtime 누락으로 `ERR_MODULE_NOT_FOUND`가 나는 것을 방지합니다.
 - 이후 프로젝트별로 메모리 저장소가 자동 분리됩니다.
 - `install` / `uninstall`은 `~/.claude/settings.json`을 수정합니다.
 
@@ -48,27 +48,41 @@ Linux x64 서버에 CUDA 11이 설치되어 있으면 `@huggingface/transformers
 Error: CUDA 11 binaries are not supported by this script yet.
 ```
 
-Claude Memory Layer는 설치 시 Linux x64 + CUDA 11 환경을 감지하면 `@huggingface/transformers`를 optional dependency로 처리한 뒤 CPU-only ONNX Runtime 설정으로 자동 복구합니다. 그래서 일반적으로 사용자가 환경변수를 직접 지정할 필요는 없습니다.
-
-만약 구버전 패키지를 설치 중이거나 postinstall 복구가 실패하면 아래처럼 수동으로 CUDA 바이너리 다운로드만 건너뛰어 재설치할 수 있습니다.
+Claude Memory Layer는 로컬 semantic/vector embedding에 필요한 `@huggingface/transformers`를 필수 dependency로 설치합니다. 이 선택은 정상 설치 후 backend 누락을 조용히 넘기지 않기 위한 것입니다. 다만 CUDA 11 환경에서는 하위 의존성 설치가 Claude Memory Layer의 postinstall repair 전에 실패할 수 있으므로, 아래처럼 CUDA 바이너리 다운로드를 건너뛰고 CPU-only ONNX Runtime으로 재설치하세요.
 
 ```bash
 # 실패한 전역 설치가 일부 남아 있으면 먼저 제거
 npm uninstall -g claude-memory-layer || true
 
-# 수동 fallback: CPU-only ONNX Runtime으로 재설치
+# CPU-only ONNX Runtime으로 재설치
 ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install -g claude-memory-layer@latest
 claude-memory-layer --version
 ```
 
-로컬 checkout 개발 환경에서 구버전 의존성 설치가 같은 오류를 내면 아래처럼 수동 fallback을 사용할 수 있습니다.
+로컬 checkout 개발 환경에서 같은 오류가 나면 아래처럼 설치합니다.
 
 ```bash
 ONNXRUNTIME_NODE_INSTALL_CUDA=skip npm install
 ```
 
+이미 설치된 패키지 디렉터리에서 backend만 손상/누락된 경우에는 postinstall repair와 런타임 오류 메시지가 동일한 CPU-only 복구 명령을 안내합니다.
+
 `npm warn deprecated ...` 경고는 하위 의존성 경고이며 설치 실패 원인이 아닙니다.
 
+#### Embedding model
+
+기본 로컬 embedding 모델은 `Xenova/multilingual-e5-small`입니다.
+
+- `@huggingface/transformers`/ONNX Runtime CPU에서 동작하므로 CUDA가 필요 없습니다.
+- 원본 `intfloat/multilingual-e5-small`은 multilingual + Korean(`ko`) 지원 모델이고, Xenova variant는 Transformers.js용 ONNX 파일을 제공합니다.
+- 384차원이라 대규모 세션 import에서도 CPU/메모리 부담이 작습니다.
+- 더 높은 품질이 필요하면 `--embedding-model <hf-model>` 또는 `CLAUDE_MEMORY_EMBEDDING_MODEL`로 `onnx-community/Qwen3-Embedding-0.6B-ONNX`, `onnx-community/embeddinggemma-300m-ONNX` 같은 Transformers.js/ONNX 모델을 실험할 수 있습니다. 다만 이들은 다운로드/CPU 비용이 더 크거나 모델/라이선스 성숙도를 별도 검토해야 합니다.
+
+```bash
+claude-memory-layer import --project "$PWD" --embedding-model Xenova/multilingual-e5-small
+CLAUDE_MEMORY_EMBEDDING_MODEL=onnx-community/Qwen3-Embedding-0.6B-ONNX claude-memory-layer process --project "$PWD"
+```
+
 ### 1) 새 프로젝트에서 초기 메모리 생성
 
 ```bash

package/dist/cli/index.js

@@ -1533,12 +1533,14 @@ import * as fs5 from "fs";
 import * as path4 from "path";
 
 // src/extensions/vector/embedder.ts
+var DEFAULT_EMBEDDING_MODEL = "Xenova/multilingual-e5-small";
+var DEFAULT_EMBEDDING_FALLBACK_MODEL = "intfloat/multilingual-e5-small";
 var Embedder = class _Embedder {
   pipeline = null;
   modelName;
   activeModelName;
   initialized = false;
-  constructor(modelName = "jinaai/jina-embeddings-v5-text-nano-text-matching") {
+  constructor(modelName = DEFAULT_EMBEDDING_MODEL) {
     this.modelName = modelName;
     this.activeModelName = modelName;
   }
@@ -1548,14 +1550,23 @@ var Embedder = class _Embedder {
   async initialize() {
     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));
       this.activeModelName = this.modelName;
       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;
       }
@@ -1674,6 +1685,28 @@ async function withSuppressedKnownTransformersWarnings(fn) {
 function isKnownBenignTransformersWarning(message) {
   return message.includes('Unknown model class "eurobert"') || message.includes('dtype not specified for "model"');
 }
+function isMissingTransformersDependencyError(error) {
+  const maybeError = error;
+  const message = typeof maybeError?.message === "string" ? maybeError.message : "";
+  return maybeError?.code === "ERR_MODULE_NOT_FOUND" && message.includes("@huggingface/transformers");
+}
+function createEmbeddingBackendUnavailableError(cause) {
+  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")
+  );
+  error.cause = cause;
+  return error;
+}
 async function loadTransformersPipeline() {
   const dynamicImport = new Function("specifier", "return import(specifier)");
   const transformers = await dynamicImport("@huggingface/transformers");
@@ -12904,7 +12937,7 @@ async function runMarketContextCommand(options) {
   }
 }
 var program = new Command();
-program.name("claude-memory-layer").description("Claude Code Memory Plugin CLI").version("1.0.29");
+program.name("claude-memory-layer").description("Claude Code Memory Plugin CLI").version("1.0.31");
 program.command("market-context").description("Fetch read-only DART/FRED/Finnhub context with structured MarketContextSnapshot bull/bear/risk/catalyst analysis").option("--company <name>", "Company name for DART fallback search and report subject").option("--dart-corp-code <code>", "Exact DART corp_code for issuer-specific filings").option("--symbol <ticker>", "Listed ticker for Finnhub company profile").option("--providers <list>", "Comma-separated providers: dart,fred,finnhub").option("--fred-series <list>", "Comma-separated FRED series IDs").option("--json", "Print structured JSON including analysis.marketSnapshot").option("--no-snapshot", "Disable MarketContextSnapshot and DART company snapshot analysis").action(async (options) => {
   try {
     await runMarketContextCommand(options);
@@ -13435,7 +13468,7 @@ program.command("organize-import [sourceDir]").description("Import existing mark
     process.exit(1);
   }
 });
-program.command("import").description("Import existing Claude Code conversation history").option("-p, --project <path>", "Import from specific project path").option("-s, --session <file>", "Import specific session file (JSONL)").option("-a, --all", "Import all sessions from all projects").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("-v, --verbose", "Show detailed progress").action(async (options) => {
+program.command("import").description("Import existing Claude Code conversation history").option("-p, --project <path>", "Import from specific project path").option("-s, --session <file>", "Import specific session file (JSONL)").option("-a, --all", "Import all sessions from all projects").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: ${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();
   const targetProjectPath = options.project || process.cwd();
   if (options.embeddingModel) {