{"id":43069295,"url":"https://github.com/mensonones/expo-vector-search","last_synced_at":"2026-01-31T13:50:04.350Z","repository":{"id":334040647,"uuid":"1136915840","full_name":"mensonones/expo-vector-search","owner":"mensonones","description":"High-performance on-device vector search engine for Expo \u0026 React Native. Powered by C++ JSI and USearch (HNSW) for sub-millisecond similarity matching.","archived":false,"fork":false,"pushed_at":"2026-01-30T03:01:42.000Z","size":29705,"stargazers_count":20,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-30T18:51:20.452Z","etag":null,"topics":["android","cpp","expo","hnsw","jsi","on-device-ml","react-native","semantic-search","similarity-search","usearch","vector-search"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mensonones.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-18T15:39:29.000Z","updated_at":"2026-01-30T03:01:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mensonones/expo-vector-search","commit_stats":null,"previous_names":["mensonones/expo-vector-search"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mensonones/expo-vector-search","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensonones%2Fexpo-vector-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensonones%2Fexpo-vector-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensonones%2Fexpo-vector-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensonones%2Fexpo-vector-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mensonones","download_url":"https://codeload.github.com/mensonones/expo-vector-search/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mensonones%2Fexpo-vector-search/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28944789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T13:02:32.153Z","status":"ssl_error","status_checked_at":"2026-01-31T13:00:07.528Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","cpp","expo","hnsw","jsi","on-device-ml","react-native","semantic-search","similarity-search","usearch","vector-search"],"created_at":"2026-01-31T13:50:03.802Z","updated_at":"2026-01-31T13:50:04.344Z","avatar_url":"https://github.com/mensonones.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Expo Vector Search\n\nA high-performance, on-device **vector search engine** demonstration for Expo and React Native. This project showcases the capabilities of the `expo-vector-search` module, providing a real-world implementation of semantic similarity search and machine learning features without server-side dependencies.\n\n## Key Features\n\n- **Blazing Fast On-Device Search**: Sub-millisecond similarity search over 10,000+ vectors using the HNSW algorithm.\n- **Privacy-First Architecture**: All vector indexing and similarity matching occurs locally on the device.\n- **Production-Grade Features**: Support for Int8 quantization, native persistence, and high-fidelity JSI communication.\n- **Extended Metrics**: Support for Cosine, Euclidean (L2), Hamming (Binary), and Jaccard (Set) distances.\n- **Cross-Industry Use Cases**:\n  - **E-commerce**: Visual product similarity matching.\n  - **Support**: Automated message classification and routing.\n  - **Safety**: On-device moderation and anomaly detection.\n\n3. **Application Layer**: A modern Expo app demonstrating real-world use cases, benchmarks, and diagnostic tools.\n\n## How it Works\n\nUnlike traditional databases that search for exact matches (e.g., \"Product ID = 123\"), this engine uses **Vector Embeddings**. \n- **Embeddings**: Data (images, text) is converted into an array of numbers (vectors) that represent its meaning.\n- **Distance**: The \"similarity\" between two items is calculated using the **Cosine Distance** between their vectors.\n- **Native Binary Loading**: Since `v0.2.0`, vectors can be loaded directly from `.bin` files into C++ memory, eliminating the JavaScript bridge bottleneck for large datasets.\n- **Dynamic CRUD \u0026 Hooks**: Since `v0.3.0`, the engine supports live updates (`remove`/`update`) and provides a simplified `useVectorSearch` hook for React.\n- **HNSW Algorithm**: Instead of checking every single item (slow), we use a mathematical graph that lets us jump through the data to find the nearest neighbors in sub-millisecond time.\n\n## Project Structure\n\nThis repository is organized as a monorepo-style Expo project:\n\n```text\n├── app/                    # Demo Application (Expo Router)\n│   ├── (tabs)/             # Main search and performance lab screens\n│   └── ...\n├── modules/\n│   └── expo-vector-search/ # Core Engine (Native Module)\n│       ├── ios/            # Swift \u0026 C++ bindings for iOS\n│       ├── android/        # Kotlin \u0026 C++ (JNI) for Android\n│       ├── src/            # TypeScript API \u0026 types\n│       └── README.md       # Technical module documentation\n├── assets/                 # Demo assets (product data \u0026 images)\n├── scripts/                # Python scripts for data generation\n└── README.md               # You are here\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js and npm/yarn.\n- Development Build environment (required for custom native modules).\n\n### Installation\n\n1. Clone the repository and install dependencies:\n   ```bash\n   npm install\n   ```\n\n2. Start the development server:\n   ```bash\n   npx expo start\n   ```\n\n3. Run the application:\n   - For Android: Press `a`.\n   - For iOS: Press `i`.\n   - *Note: This project requires a development build to run the custom native module.*\n\n## Demo Data Setup\n\nTo test the **Visual Search** demo, you need to download and process the sample product dataset. Follow these steps:\n\n### 1. Prerequisites (Python)\nEnsure you have Python 3.8+ installed. Install the processing dependencies:\n```bash\npip install -r scripts/requirements.txt\n```\n\n### 2. Download \u0026 Process Data\nRun the following commands from the **project root**:\n\n```bash\n# Step A: Download the dataset and convert to JSON (~150MB)\npython scripts/download_and_convert_products.py\n\n# Step B: Split the dataset into optimized chunks for the mobile app\npython scripts/split_dataset.py\n\n# Step C: Convert to Binary for Native C++ Loader (Ultra Fast)\npython scripts/convert_to_binary.py\n```\n\n### 3. Verify\nAfter running the scripts, your `assets/chunks/` directory should contain multiple `.json` files and an `index.ts`. The app will automatically load these files on the next launch.\n\n## Platform Support\n\n\u003e [!IMPORTANT]\n\u003e The current version of this module has been primary developed and **thoroughly tested on Android**. \n\u003e - **Android**: Fully supported (tested on Galaxy S23 FE).\n\u003e - **iOS**: Fully supported (tested on iPhone 12).\n\n## Module Documentation\n\nThe core logic resides in the `modules/expo-vector-search` directory. For detailed API documentation, performance specifications, and implementation details, please refer to the [Module README](./modules/expo-vector-search/README.md).\n\n## Performance and Benchmarks\n\nThe application includes a built-in benchmark tool that compares the native C++ implementation against a naive JavaScript baseline. Results obtained using **Release builds** on physical devices.\n\n### JS vs. Native Engine Race\n| Platform | JavaScript (Runtime Loop) | Expo Vector Search (Native) | Speedup |\n| :--- | :--- | :--- | :--- |\n| **Android** (S23 FE) | 6.20 ms | 0.15 ms | **~41x** |\n| **iOS** (iPhone 12) | 12.06 ms | 0.10 ms | **~120x** |\n\n### Bulk Ingestion (1,000 items)\n| Platform | Individual `.add` | Batch `.addBatch` |\n| :--- | :--- | :--- |\n| **Android** (S23 FE) | 79.87 ms | 76.70 ms |\n| **iOS** (iPhone 12) | 107.94 ms | 102.59 ms |\n\n### Memory Optimization (10,000 items, 384 dims)\n| Platform | Full Precision (F32) | Quantized (Int8) | Savings |\n| :--- | :--- | :--- | :--- |\n| **Android** (S23 FE) | 36,943.84 KB | 20,559.84 KB | **~44%** |\n| **iOS** (iPhone 12) | 36,943.97 KB | 20,559.97 KB | **~44%** |\n\n## Acknowledgements\n\n- **[USearch](https://github.com/unum-cloud/usearch)**: The high-performance C++ engine powering the similarity search.\n- **[Expo Modules SDK](https://docs.expo.dev/modules/overview/)**: For the robust infrastructure that makes JSI modules accessible in the Expo ecosystem.\n- **[Crossing Minds](https://huggingface.co/datasets/crossingminds/shopping-queries-image-dataset)**: For the sample product dataset.\n\n## Future Roadmap\n\n- [x] **Dynamic CRUD Support**: Implement `remove(key)` and `update(key, vector)` for live index management.\n- [x] **Metadata Filtering**: Enable search with predicates (e.g., filtering by category or availability).\n- [x] **Simplified React Hooks**: Abstractions like `useVectorSearch` for automatic resource management.\n- [ ] **Architecture-Specific SIMD**: Enable NEON/SVE/AVX optimizations for Android to narrow the F32/Int8 performance gap.\n- [ ] **On-Device Embeddings**: Local text/image to vector conversion (using MediaPipe or ONNX).\n- [ ] **Hybrid Search**: Combine vector similarity with traditional keyword-based search.\n- [ ] **USearch Engine Upgrade**: Migrate from `v2.9.0` to `v2.23.0+` for better precision.\n- [ ] **Background Indexing**: Offload heavy ingestion to native threads to prevent UI stutters.\n- [ ] **SQLite Synchronization**: Built-in utilities to sync vector indices with `expo-sqlite`.\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE).\n\n---\n*Maintained with a focus on high-performance mobile engineering.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmensonones%2Fexpo-vector-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmensonones%2Fexpo-vector-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmensonones%2Fexpo-vector-search/lists"}