native-vector-store 0.1.0 → 0.3.0

package/README.md

@@ -2,6 +2,17 @@
 
 High-performance vector store with SIMD optimization for MCP servers and local RAG applications.
 
+## Design Philosophy
+
+This vector store is designed for **immutable, one-time loading** scenarios common in modern cloud deployments:
+
+- **📚 Load Once, Query Many**: Documents are loaded at startup and remain immutable during serving
+- **🚀 Optimized for Cold Starts**: Perfect for serverless functions and containerized deployments
+- **📁 File-Based Organization**: Leverages filesystem for natural document organization and versioning
+- **🎯 Focused API**: Does one thing exceptionally well - fast similarity search over focused corpora (sweet spot: <100k documents)
+
+This design eliminates complex state management, ensures consistent performance, and aligns perfectly with cloud-native deployment patterns where domain-specific knowledge bases are the norm.
+
 ## Features
 
 - **🚀 High Performance**: C++ implementation with OpenMP SIMD optimization
@@ -17,7 +28,7 @@ High-performance vector store with SIMD optimization for MCP servers and local R
 - **Load Time**: <1 second for 100,000 documents (achieved: ~560ms)
 - **Search Latency**: <10ms for top-k similarity search (achieved: 1-2ms)
 - **Memory Efficiency**: Minimal fragmentation via arena allocation
-- **Scalability**: Designed for <1M embeddings
+- **Scalability**: Designed for focused corpora (<100k documents optimal, <1M maximum)
 - **Throughput**: 178k+ documents per second with parallel loading
 
 ## Installation
@@ -28,15 +39,22 @@ npm install native-vector-store
 
 ### Prerequisites
 
-For most users, **no prerequisites are needed** - prebuilt binaries are included for:
-- Linux (x64, arm64)
+**Runtime Requirements:**
+- OpenMP runtime library (for parallel processing)
+  - **Linux**: `sudo apt-get install libgomp1` (Ubuntu/Debian) or `dnf install libgomp` (Fedora)
+  - **Alpine**: `apk add libgomp`
+  - **macOS**: `brew install libomp`
+  - **Windows**: Included with Visual C++ runtime
+
+Prebuilt binaries are included for:
+- Linux (x64, arm64, musl/Alpine)
 - macOS (x64, arm64/Apple Silicon)
 - Windows (x64)
 
 If building from source, you'll need:
 - Node.js ≥14.0.0
 - C++ compiler with OpenMP support
-- simdjson library (automatically handled by node-gyp)
+- simdjson library (vendored, no installation needed)
 
 ## Quick Start
 
@@ -69,6 +87,164 @@ const results = store.search(queryEmbedding, 5); // Top 5 results
 console.log(results[0]); // { score: 0.95, id: 'doc-1', text: '...', metadata_json: '...' }
 ```
 
+## Usage Patterns
+
+### Serverless Deployment (AWS Lambda, Vercel)
+
+```javascript
+// Initialize once during cold start
+let store;
+
+async function initializeStore() {
+  if (!store) {
+    store = new VectorStore(1536);
+    store.loadDir('./knowledge-base'); // Loads and finalizes
+  }
+  return store;
+}
+
+// Handler reuses the store across invocations
+export async function handler(event) {
+  const store = await initializeStore();
+  const embedding = new Float32Array(event.embedding);
+  return store.search(embedding, 10);
+}
+```
+
+### Local MCP Server
+
+```javascript
+const { VectorStore } = require('native-vector-store');
+
+// Load different knowledge domains at startup
+const stores = {
+  products: new VectorStore(1536),
+  support: new VectorStore(1536),
+  general: new VectorStore(1536)
+};
+
+stores.products.loadDir('./knowledge/products');
+stores.support.loadDir('./knowledge/support');
+stores.general.loadDir('./knowledge/general');
+
+// Route searches to appropriate domain
+server.on('search', (query) => {
+  const store = stores[query.domain] || stores.general;
+  const results = store.search(query.embedding, 5);
+  return results.filter(r => r.score > 0.7);
+});
+```
+
+### CLI Tool with Persistent Context
+
+```javascript
+#!/usr/bin/env node
+const { VectorStore } = require('native-vector-store');
+
+// Load knowledge base once
+const store = new VectorStore(1536);
+store.loadDir(process.env.KNOWLEDGE_PATH || './docs');
+
+// Interactive REPL with fast responses
+const repl = require('repl');
+const r = repl.start('> ');
+r.context.search = (embedding, k = 5) => store.search(embedding, k);
+```
+
+### File Organization Best Practices
+
+Structure your documents by category for separate vector stores:
+
+```
+knowledge-base/
+├── products/          # Product documentation
+│   ├── api-reference.json
+│   └── user-guide.json
+├── support/           # Support articles
+│   ├── faq.json
+│   └── troubleshooting.json
+└── context/           # Context-specific docs
+    ├── company-info.json
+    └── policies.json
+```
+
+Load each category into its own VectorStore:
+
+```javascript
+// Create separate stores for different domains
+const productStore = new VectorStore(1536);
+const supportStore = new VectorStore(1536);
+const contextStore = new VectorStore(1536);
+
+// Load each category independently
+productStore.loadDir('./knowledge-base/products');
+supportStore.loadDir('./knowledge-base/support');
+contextStore.loadDir('./knowledge-base/context');
+
+// Search specific domains
+const productResults = productStore.search(queryEmbedding, 5);
+const supportResults = supportStore.search(queryEmbedding, 5);
+```
+
+Each JSON file contains self-contained documents with embeddings:
+
+```json
+{
+  "id": "unique-id",
+  "text": "Document content...",
+  "metadata": {
+    "embedding": [0.1, 0.2, ...],
+    "category": "product",
+    "lastUpdated": "2024-01-01"
+  }
+}
+```
+
+### Deployment Strategies
+
+#### Blue-Green Deployment
+
+```javascript
+// Load new version without downtime
+const newStore = new VectorStore(1536);
+newStore.loadDir('./knowledge-base-v2');
+
+// Atomic switch
+app.locals.store = newStore;
+```
+
+#### Versioned Directories
+
+```
+deployments/
+├── v1.0.0/
+│   └── documents/
+├── v1.1.0/
+│   └── documents/
+└── current -> v1.1.0  # Symlink to active version
+```
+
+#### Watch for Updates (Development)
+
+```javascript
+const fs = require('fs');
+
+function reloadStore() {
+  const newStore = new VectorStore(1536);
+  newStore.loadDir('./documents');
+  global.store = newStore;
+  console.log(`Reloaded ${newStore.size()} documents`);
+}
+
+// Initial load
+reloadStore();
+
+// Watch for changes in development
+if (process.env.NODE_ENV === 'development') {
+  fs.watch('./documents', { recursive: true }, reloadStore);
+}
+```
+
 ## MCP Server Integration
 
 Perfect for building local RAG capabilities in MCP servers:
@@ -141,6 +317,60 @@ Check if the store has been finalized and is ready for searching.
 ##### `size(): number`
 Get the number of documents in the store.
 
+## Performance
+
+### Why It's Fast
+
+The native-vector-store achieves exceptional performance through:
+
+1. **Producer-Consumer Loading**: Parallel file I/O and JSON parsing achieve 178k+ documents/second
+2. **SIMD Optimizations**: OpenMP vectorization for dot product calculations
+3. **Arena Allocation**: Contiguous memory layout with 64MB chunks for cache efficiency
+4. **Zero-Copy Design**: String views and pre-allocated buffers minimize allocations
+5. **Two-Phase Architecture**: Loading phase allows concurrent writes, serving phase optimizes for reads
+
+### Benchmarks
+
+Performance on typical hardware (M1 MacBook Pro):
+
+| Operation | Documents | Time | Throughput |
+|-----------|-----------|------|------------|
+| Loading (from disk) | 100,000 | ~560ms | 178k docs/sec |
+| Search (k=10) | 10,000 corpus | 1-2ms | 500-1000 queries/sec |
+| Search (k=100) | 100,000 corpus | 8-12ms | 80-125 queries/sec |
+| Normalization | 100,000 | <100ms | 1M+ docs/sec |
+
+### Performance Tips
+
+1. **Optimal File Organization**: 
+   - Keep 1000-10000 documents per JSON file for best I/O performance
+   - Use arrays of documents in each file rather than one file per document
+
+2. **Memory Considerations**:
+   - Each document requires: `embedding_size * 4 bytes + metadata_size + text_size`
+   - 100k documents with 1536-dim embeddings ≈ 600MB embeddings + metadata
+
+3. **Search Performance**:
+   - Scales linearly with corpus size and k value
+   - Use smaller k values (5-20) for interactive applications
+   - Pre-normalize query embeddings if making multiple searches
+
+4. **Corpus Size Optimization**:
+   - Sweet spot: <100k documents for optimal load/search balance
+   - Beyond 100k: Consider if your use case truly needs all documents
+   - Focus on curated, domain-specific content rather than exhaustive datasets
+
+### Comparison with Alternatives
+
+| Feature | native-vector-store | Faiss | ChromaDB | Pinecone |
+|---------|-------------------|--------|----------|----------|
+| Load 100k docs | <1s | 2-5s | 30-60s | N/A (API) |
+| Search latency | 1-2ms | 0.5-1ms | 50-200ms | 50-300ms |
+| Memory efficiency | High | Medium | Low | N/A |
+| Dependencies | Minimal | Heavy | Heavy | None |
+| Deployment | Simple | Complex | Complex | SaaS |
+| Sweet spot | <100k docs | Any size | Any size | Any size |
+
 ## Building from Source
 
 ```bash
@@ -181,21 +411,21 @@ npm run example
 
 ### MCP Servers
 Ideal for building local RAG (Retrieval-Augmented Generation) capabilities:
-- Fast document loading from knowledge bases
+- Fast document loading from focused knowledge bases
 - Low-latency similarity search for context retrieval
-- Memory-efficient storage for large document collections
+- Memory-efficient storage for domain-specific corpora
 
 ### Knowledge Management
 Perfect for personal knowledge management systems:
-- Index personal documents and notes
-- Fast semantic search across content
+- Index personal documents and notes (typically <10k documents)
+- Fast semantic search across focused content
 - Offline operation without external dependencies
 
 ### Research Applications
-Suitable for academic and research projects:
-- Literature review and citation analysis
-- Semantic clustering of research papers
-- Cross-reference discovery in document collections
+Suitable for academic and research projects with focused datasets:
+- Literature review within specific domains
+- Semantic clustering of curated paper collections
+- Cross-reference discovery in specialized corpora
 
 ## Contributing
 

package/binding.gyp

@@ -2,10 +2,12 @@
   "targets": [
     {
       "target_name": "vector_store",
-      "sources": ["src/binding.cc", "src/vector_store_loader.cpp", "src/vector_store_loader_mmap.cpp", "src/vector_store_loader_adaptive.cpp"],
+      "sources": ["src/binding.cc", "src/vector_store.cpp", "src/vector_store_loader.cpp", "src/vector_store_loader_mmap.cpp", "src/vector_store_loader_adaptive.cpp", "deps/simdjson/simdjson.cpp"],
       "include_dirs": [
         "<!@(node -p \"require('node-addon-api').include\")",
-        "src"
+        "src",
+        "deps/simdjson",
+        "deps/atomic_queue"
       ],
       "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
       "cflags_cc": [
@@ -17,27 +19,37 @@
       "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
       "conditions": [
         ["OS=='mac'", {
-          "include_dirs": ["/opt/homebrew/opt/libomp/include", "/opt/homebrew/include"],
+          "include_dirs": [
+            "/opt/homebrew/opt/libomp/include",
+            "/usr/local/opt/libomp/include"
+          ],
           "xcode_settings": {
             "GCC_ENABLE_CPP_EXCEPTIONS": "NO",
             "OTHER_CFLAGS": ["-Xpreprocessor", "-fopenmp"],
-            "OTHER_CPLUSPLUSFLAGS": ["-Xpreprocessor", "-fopenmp"],
-            "OTHER_LDFLAGS": ["-L/opt/homebrew/opt/libomp/lib", "-lomp"]
+            "OTHER_CPLUSPLUSFLAGS": ["-Xpreprocessor", "-fopenmp", "-std=c++17"],
+            "OTHER_LDFLAGS": ["-lomp"],
+            "CLANG_CXX_LANGUAGE_STANDARD": "c++17"
           },
-          "libraries": ["-L/opt/homebrew/opt/libomp/lib", "-lomp", "-L/opt/homebrew/lib", "-lsimdjson"]
+          "libraries": ["-lomp"],
+          "library_dirs": [
+            "/opt/homebrew/opt/libomp/lib",
+            "/usr/local/opt/libomp/lib"
+          ]
         }],
         ["OS=='linux'", {
           "cflags_cc": ["-fopenmp"],
-          "libraries": ["-lgomp", "-lsimdjson"]
+          "libraries": ["-lgomp"]
         }],
         ["OS=='win'", {
           "msvs_settings": {
             "VCCLCompilerTool": {
               "ExceptionHandling": 0,
-              "OpenMP": "true"
+              "OpenMP": "true",
+              "AdditionalOptions": [
+                "/openmp:experimental"
+              ]
             }
-          },
-          "libraries": ["simdjson.lib"]
+          }
         }]
       ]
     }