feat: Local embeddings with transformers.js - no API key required

Summary

Implemented local embedding generation using transformers.js, eliminating the need for API keys and enabling completely offline semantic search.

Changes in v1.8.7

Core Implementation

• Local Transformer Model: Uses @xenova/transformers with Xenova/all-MiniLM-L6-v2
• Embedding Dimensions: 384 (optimized, down from 1024)
• No API Keys Required: Completely free and offline
• Model Size: ~23MB (downloads on first use, cached afterward)
• Performance: 50-100ms per embedding generation

Technical Details

Files Modified:

• src/reasoningbank/utils/embeddings.ts - Complete rewrite with transformers.js
• src/reasoningbank/config/reasoningbank.yaml - Updated to use local provider
• package.json - Added @xenova/transformers dependency, updated build script
• .npmignore - Excluded Rust build artifacts (reduced package from 166.9 MB to 1.6 MB)

Key Features:

• ✅ WASM backend configuration for Node.js compatibility
• ✅ LRU cache with 1000 entry limit
• ✅ TTL-based cache expiration (configurable)
• ✅ Graceful fallback to hash-based embeddings if model fails
• ✅ Lazy initialization to avoid startup delays

Configuration

embeddings:
  provider: "local"
  model: "Xenova/all-MiniLM-L6-v2"
  dimensions: 384
  cache_ttl_seconds: 3600

Usage

# Store data with semantic embeddings
npx claude-flow@alpha memory store "python_tips" "Use list comprehensions..."

# Query with semantic search
npx claude-flow@alpha memory query "coding best practices"

Expected Output:

[ReasoningBank] Embeddings: local
[Embeddings] Initializing local embedding model (Xenova/all-MiniLM-L6-v2)...
[Embeddings] First run will download ~23MB model...
[Embeddings] Local model ready! (384 dimensions)

Benefits

• 🆓 Zero Cost: No API fees, completely free
• 🔒 Privacy: All processing happens locally
• 📴 Offline: Works without internet connection (after initial model download)
• ⚡ Fast: 50-100ms inference time
• 💾 Efficient: Smart caching reduces redundant computation
• 🛡️ Reliable: Automatic fallback if model loading fails

Testing

Tested successfully:

• ✅ Model initialization and download
• ✅ Embedding generation (384 dimensions)
• ✅ Cache functionality
• ✅ Semantic similarity search
• ✅ Graceful degradation

Migration Notes

For existing users:

• Existing embeddings are 1024-dimensional (OpenAI/Claude)
• New embeddings are 384-dimensional (transformers.js)
• Consider clearing .swarm/memory.db to regenerate with new dimensions
• Or run consolidation to migrate embeddings

Published

📦 agentic-flow@1.8.7 is now available on npm

npm install agentic-flow@1.8.7
# or
npx claude-flow@alpha  # will auto-update

Start by reviewing src/reasoningbank/utils/embeddings.ts, src/reasoningbank/config/reasoningbank.yaml, package.json, and .npmignore. Run the documented memory store and query commands, then verify local model initialization, 384-dimensional embeddings, caching, semantic search, and fallback behavior match the issue's expected output.