claude-flow 2.7.23 → 2.7.25

package/docs/TRANSFORMER_INITIALIZATION_ISSUE.md

@@ -0,0 +1,362 @@
+# Transformer Model Initialization Issue in npx
+
+## Status: ⚠️ Known Issue with Graceful Fallback
+
+**Date:** October 25, 2025
+**Versions:** claude-flow@2.7.24, agentic-flow@1.8.7
+**Impact:** Low - System works with hash-based embeddings fallback
+
+---
+
+## Summary
+
+When using `npx claude-flow@alpha memory` commands, the local transformer model (Xenova/all-MiniLM-L6-v2) fails to initialize in npx temporary directories due to ONNX runtime and WASM backend issues. The system gracefully falls back to hash-based embeddings, maintaining full functionality.
+
+## Error Output
+
+```bash
+npx claude-flow@alpha memory store "test" "Local embeddings working!"
+
+[Embeddings] Initializing local embedding model (Xenova/all-MiniLM-L6-v2)...
+[Embeddings] First run will download ~23MB model...
+
+Error: /onnxruntime_src/include/onnxruntime/core/common/logging/logging.h:371
+static const onnxruntime::logging::Logger& onnxruntime::logging::LoggingManager::DefaultLogger()
+Attempt to use DefaultLogger but none has been registered.
+
+Something went wrong during model construction (most likely a missing operation).
+Using `wasm` as a fallback.
+
+[Embeddings] Failed to initialize: no available backend found. ERR:
+[Embeddings] Falling back to hash-based embeddings
+
+✅ ✅ Stored successfully in ReasoningBank  ← Still works!
+```
+
+## Root Causes
+
+### 1. ONNX Runtime Issue
+**Error:** `Attempt to use DefaultLogger but none has been registered`
+
+**Location:** `onnxruntime-node` backend initialization
+
+**Why it happens:**
+- ONNX runtime expects a logger to be registered before use
+- In npx temporary directories, initialization order may be different
+- The logger registration doesn't happen before model loading
+
+### 2. WASM Fallback Issue
+**Error:** `no available backend found`
+
+**Why it happens:**
+- After ONNX fails, @xenova/transformers tries WASM backend
+- WASM backend also fails in npx environment
+- Likely due to missing WASM files or incorrect paths in temporary directory
+
+### 3. NPX Environment Constraints
+- Temporary installation directories
+- Limited file system access
+- Different initialization order than local installs
+- Optional dependencies may not install
+
+---
+
+## Current Behavior (Working as Designed)
+
+### ✅ What Works
+
+1. **Memory system fully functional**
+   - Store, query, list, export, import all work
+   - SQLite database persistence
+   - ReasoningBank integration
+
+2. **Graceful degradation**
+   - Automatic fallback to hash-based embeddings
+   - No crashes or errors that break functionality
+   - Clear logging of what's happening
+
+3. **Hash-based embeddings**
+   - Deterministic similarity based on text content
+   - Fast (no model loading time)
+   - Works offline without any dependencies
+
+### ⚠️ What's Limited
+
+1. **Semantic search quality**
+   - Hash-based embeddings don't capture semantic meaning
+   - "authentication" won't match "JWT" or "OAuth" semantically
+   - Still provides basic text similarity
+
+2. **True vector similarity**
+   - Can't find conceptually similar content
+   - Limited to exact or partial text matching
+
+---
+
+## Workarounds
+
+### Option 1: Local Installation (Best Results)
+
+```bash
+# Install globally (not via npx)
+npm install -g claude-flow@alpha
+
+# Now transformers work better
+claude-flow memory store "test" "value"
+# ✅ Real transformer embeddings may work
+```
+
+### Option 2: Use Hash-Based Embeddings (Current Default)
+
+```bash
+# Just use it - fallback works automatically
+npx claude-flow@alpha memory store "key" "value"
+npx claude-flow@alpha memory query "search"
+# ✅ Works with hash-based similarity
+```
+
+### Option 3: Disable Embedding Attempts
+
+Set environment variable to skip transformer initialization:
+
+```bash
+export SKIP_TRANSFORMERS=true
+npx claude-flow@alpha memory store "key" "value"
+# ✅ Skips transformer loading, uses hash directly
+```
+
+---
+
+## Proposed Fixes
+
+### Short-Term: Improve Error Handling
+
+**File:** `agentic-flow/src/reasoningbank/utils/embeddings.ts`
+
+```typescript
+async function initializeEmbeddings(): Promise<boolean> {
+  // Skip if in npx environment (known issue)
+  const isNpx = process.env.npm_config_user_agent?.includes('npx') ||
+                process.cwd().includes('_npx');
+
+  if (isNpx && !process.env.FORCE_TRANSFORMERS) {
+    console.log('[Embeddings] Detected npx environment');
+    console.log('[Embeddings] Using hash-based embeddings (set FORCE_TRANSFORMERS=true to try local model)');
+    return false;
+  }
+
+  // Try to initialize...
+}
+```
+
+### Mid-Term: Fix ONNX Logger Registration
+
+**File:** `agentic-flow/src/reasoningbank/utils/embeddings.ts`
+
+```typescript
+import { env } from '@xenova/transformers';
+
+async function initializeEmbeddings(): Promise<boolean> {
+  try {
+    // Configure ONNX runtime before loading
+    if (env.backends?.onnx) {
+      // Disable ONNX runtime in npx (use WASM instead)
+      env.backends.onnx = false;
+    }
+
+    // Force WASM backend with proper configuration
+    if (env.backends?.wasm) {
+      env.backends.wasm.numThreads = 1;
+      env.backends.wasm.simd = false; // Disable SIMD for compatibility
+    }
+
+    // Now load pipeline
+    embeddingPipeline = await pipeline(
+      'feature-extraction',
+      'Xenova/all-MiniLM-L6-v2',
+      { device: 'wasm' } // Force WASM backend
+    );
+
+    return true;
+  } catch (error) {
+    console.log('[Embeddings] Transformer initialization failed, using hash-based embeddings');
+    return false;
+  }
+}
+```
+
+### Long-Term: Make Transformers Truly Optional
+
+**File:** `agentic-flow/package.json`
+
+```json
+{
+  "dependencies": {
+    "better-sqlite3": "^11.10.0",
+    // ... other deps
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^3.2.0"
+  },
+  "peerDependencies": {
+    "@xenova/transformers": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@xenova/transformers": {
+      "optional": true
+    }
+  }
+}
+```
+
+Then update embeddings.ts to check if module exists:
+
+```typescript
+let transformersAvailable = false;
+
+try {
+  await import('@xenova/transformers');
+  transformersAvailable = true;
+} catch {
+  console.log('[Embeddings] @xenova/transformers not installed - using hash-based embeddings');
+  transformersAvailable = false;
+}
+```
+
+---
+
+## Testing
+
+### Verify Fallback Works
+
+```bash
+# Test with npx (uses fallback)
+npx claude-flow@alpha memory store "test" "value"
+npx claude-flow@alpha memory query "test"
+# ✅ Should work with hash-based embeddings
+
+# Test with local install (may use transformers)
+npm install -g claude-flow@alpha
+claude-flow memory store "test" "value"
+# ✅ May use real transformers if environment supports it
+```
+
+### Verify Database Integrity
+
+```bash
+# Store data
+npx claude-flow@alpha memory store "key1" "value1"
+npx claude-flow@alpha memory store "key2" "value2"
+
+# List data
+npx claude-flow@alpha memory list
+# ✅ Should show both entries
+
+# Query data
+npx claude-flow@alpha memory query "key"
+# ✅ Should find both (text matching)
+```
+
+---
+
+## Impact Analysis
+
+### User Experience
+
+✅ **Positive:**
+- Memory system works out of the box with npx
+- No crashes or broken functionality
+- Clear error messages explaining fallback
+- Hash-based embeddings provide basic similarity
+
+⚠️ **Limitations:**
+- Not true semantic search (can't find "JWT" when searching "authentication")
+- Users may expect better semantic matching
+- Documentation should clarify this limitation
+
+### Performance
+
+✅ **Faster startup:**
+- No 23MB model download
+- Instant hash-based embedding generation
+- Lower memory usage
+
+⚠️ **Lower quality:**
+- Less accurate similarity matching
+- Misses conceptual relationships
+- Limited to text overlap
+
+---
+
+## Documentation Updates
+
+### README.md
+
+Add section:
+
+```markdown
+## Memory System: Semantic Search
+
+The memory system includes semantic search capabilities with automatic fallback:
+
+### Local Installation (Recommended for Semantic Search)
+```bash
+npm install -g claude-flow@alpha
+claude-flow memory query "authentication"
+# ✅ Attempts to use local transformer model
+```
+
+### NPX Usage (Hash-Based Similarity)
+```bash
+npx claude-flow@alpha memory query "authentication"
+# ✅ Uses hash-based text matching (fallback)
+```
+
+**Note:** Due to npx environment limitations, local transformer models
+may not initialize. The system automatically falls back to hash-based
+embeddings which provide basic text similarity matching.
+
+For best semantic search quality, install globally instead of using npx.
+```
+
+---
+
+## Related Issues
+
+- GitHub Issue #840: SQLite memory command fixes (resolved)
+- GitHub Issue (NEW): Transformer initialization in npx environments
+- Upstream: @xenova/transformers ONNX/WASM initialization in temporary directories
+
+---
+
+## Recommendations
+
+### For Users:
+
+1. **Use local installation** if semantic search quality matters
+2. **Use npx** if basic text matching is sufficient
+3. **Be aware** that "semantic search enabled" message appears even with fallback
+
+### For Developers:
+
+1. **Document fallback behavior** clearly in user-facing messages
+2. **Make transformers optional** in package.json
+3. **Add environment detection** to skip transformer loading in npx
+4. **Fix ONNX logger registration** for environments where it's possible
+5. **Test in npx** as part of CI/CD to catch these issues
+
+---
+
+## Conclusion
+
+The transformer initialization issue in npx is a known limitation that's being
+handled gracefully. The system remains fully functional with hash-based embeddings
+as a fallback. Users who need true semantic search can install globally.
+
+**Priority:** Medium - System works, but semantic search quality is reduced in npx
+
+**Next Steps:**
+1. Make @xenova/transformers truly optional
+2. Add environment detection for npx
+3. Improve WASM backend initialization
+4. Update documentation to clarify behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "2.7.23",
+  "version": "2.7.25",
   "description": "Enterprise-grade AI agent orchestration with WASM-powered ReasoningBank memory and AgentDB vector database (always uses latest agentic-flow)",
   "mcpName": "io.github.ruvnet/claude-flow",
   "main": "cli.mjs",
@@ -120,7 +120,7 @@
     "@anthropic-ai/claude-code": "^2.0.1",
     "@anthropic-ai/sdk": "^0.65.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "agentic-flow": "^1.8.5",
+    "agentic-flow": "^1.8.9",
     "blessed": "^0.1.81",
     "chalk": "^4.1.2",
     "cli-table3": "^0.6.3",
@@ -143,6 +143,7 @@
   },
   "optionalDependencies": {
     "@types/better-sqlite3": "^7.6.13",
+    "@xenova/transformers": "^3.2.0",
     "agentdb": "^1.3.9",
     "better-sqlite3": "^12.2.0",
     "diskusage": "^1.1.3",