feat: add embedding support with MLX integration and vector search foundation

[tantara]

Summary

Add foundation for embedding-based semantic search with comprehensive infrastructure for 768-dimensional vectors, platform-aware MLX support, and CLI integration.

Key Features

🔢 Embedding Infrastructure

• Database: Add nullable embedding BLOB column to messages table (768 dimensions)
• Model: Update Message struct with Option<Vec<f32>> embedding field
• Serialization: Implement f32 ↔ bytes conversion for efficient storage
• Builder pattern: Add with_embedding() helper method

🤖 Embedding Service (src/services/embedding_service.rs)

• Platform detection: Automatically detects macOS vs Windows/Linux
• MLX support: Conditional integration via RETROCHAT_USE_MLX env var
• Dummy embeddings: Deterministic hash-based 768-dim vectors for development
• L2 normalization: All embeddings normalized to unit length
• Graceful degradation: Warnings on unsupported platforms
• Test coverage: 4/4 tests passing ✅

🔍 CLI Integration

• Add --use-embedding flag to search commands:
  • retrochat search <query> --use-embedding
  • retrochat query search <query> --use-embedding
• Compatible with existing time range filters
• Sets search_type = "embedding" for service routing

📦 Dependencies

• sqlite-vec v0.1.6: Vector similarity search engine
• mlx-rs v0.25: ML framework (macOS-only, optional)
• New mlx feature flag for conditional compilation

Implementation Details

Database Layer

File: src/database/message_repo.rs

• embedding_to_blob(): Convert Vec → bytes for storage
• blob_to_embedding(): Convert bytes → Vec for retrieval
• Updated all SQL queries to include embedding column
• Handles NULL embeddings gracefully

Service Layer

File: src/services/embedding_service.rs

// Check if MLX is available
let service = EmbeddingService::new();

// Generate embedding (currently dummy)
let embedding = service.generate_embedding("text")?;
assert_eq!(embedding.len(), 768);

Features:

• Platform-aware initialization
• Deterministic dummy embeddings using hash-based RNG
• Ready for actual MLX model integration
• Full error handling

Environment Configuration

File: src/env.rs

# Enable MLX embeddings (macOS only)
export RETROCHAT_USE_MLX=true

Migration

File: migrations/008_add_message_embeddings.sql

ALTER TABLE messages ADD COLUMN embedding BLOB;

• Backwards compatible (NULL allowed)
• Existing data unaffected

Usage Examples

# Basic embedding search
retrochat search "machine learning concepts" --use-embedding

# With time range
retrochat search "performance optimization" --use-embedding \
  --since "7 days ago" --until "now"

# With result limit
retrochat search "bug fix" --use-embedding --limit 10

# Enable MLX on macOS
export RETROCHAT_USE_MLX=true
retrochat search "semantic query" --use-embedding

Testing

Passing Tests ✅

• test_dummy_embedding_generation - 768-dim vectors generated correctly
• test_embedding_deterministic - Same input → same output
• test_embedding_different_text - Different inputs → different outputs
• test_platform_support_check - Platform detection works

CLI Tests Updated ✅

• test_search_command_structure - Includes use_embedding field
• test_search_command_with_time_range - Time + embedding flags
• test_search_command_with_embedding - New test for embedding flag

Known Issues ⚠️

• Search integration tests fail due to missing migration in test DB
• Need to ensure migrations run in test environment
• Alternative: Make embedding column truly optional in queries

Technical Notes

Embedding Format

• Dimensions: 768 (standard for many embedding models)
• Type: f32 (single-precision float)
• Storage: Little-endian bytes in SQLite BLOB
• Normalization: L2-normalized to unit length

Platform Support

Platform	MLX Support	Embedding Generation
macOS	✅ Available	MLX or Dummy
Linux	❌ N/A	Dummy only
Windows	❌ N/A	Dummy only

Dummy Embedding Algorithm

1. Hash input text to seed value
2. Use Linear Congruential Generator (LCG) for deterministic randomness
3. Generate 768 values in [-1, 1] range
4. L2-normalize to unit length

Architecture

┌─────────────────────────────────────────────────────┐
│                  CLI Layer                          │
│  ├─ search --use-embedding                          │
│  └─ query search --use-embedding                    │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│               Service Layer                         │
│  ├─ QueryService (routes to vector/FTS search)     │
│  └─ EmbeddingService (generates embeddings)        │
└────────────────────┬────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────┐
│             Repository Layer                        │
│  ├─ MessageRepository (CRUD + embedding storage)   │
│  └─ (TODO: Vector search with sqlite-vec)          │
└─────────────────────────────────────────────────────┘

Next Steps (Future PRs)

1. Vector Search Implementation

   • Use sqlite-vec for similarity search
   • Implement k-NN retrieval
   • Add distance/similarity scoring

2. MLX Integration

   • Load embedding model
   • Implement actual inference
   • Handle model caching

3. Embedding Generation Flow

   • Auto-generate embeddings on message import
   • Batch processing for efficiency
   • Background job for existing messages

4. Search Enhancement

   • Hybrid search (combine FTS + vector)
   • Relevance score tuning
   • Query embedding caching

Files Changed

New Files

• migrations/008_add_message_embeddings.sql - Database migration
• src/services/embedding_service.rs - Embedding generation service

Modified Files

• Cargo.toml - Add dependencies (sqlite-vec, mlx-rs)
• Cargo.lock - Dependency lock file
• src/cli/mod.rs - Add --use-embedding flag
• src/cli/query.rs - Update search handler
• src/database/message_repo.rs - Embedding storage/retrieval
• src/env.rs - Add RETROCHAT_USE_MLX
• src/models/message.rs - Add embedding field
• src/services/mod.rs - Export EmbeddingService
• tests/contract/test_cli_add_command.rs - Update CLI tests

Breaking Changes

None - all changes are additive and backwards compatible.

🤖 Generated with Claude Code