native-vector-store 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +242 -12
  2. package/binding.gyp +22 -10
  3. package/deps/simdjson/simdjson.cpp +56403 -0
  4. package/deps/simdjson/simdjson.h +123534 -0
  5. package/docs/PERFORMANCE_CASE_STUDY.md +130 -0
  6. package/docs/PREBUILDS.md +69 -0
  7. package/docs/VectorStore.html +180 -0
  8. package/docs/VectorStoreWrapper.html +1356 -0
  9. package/docs/fonts/OpenSans-Bold-webfont.eot +0 -0
  10. package/docs/fonts/OpenSans-Bold-webfont.svg +1830 -0
  11. package/docs/fonts/OpenSans-Bold-webfont.woff +0 -0
  12. package/docs/fonts/OpenSans-BoldItalic-webfont.eot +0 -0
  13. package/docs/fonts/OpenSans-BoldItalic-webfont.svg +1830 -0
  14. package/docs/fonts/OpenSans-BoldItalic-webfont.woff +0 -0
  15. package/docs/fonts/OpenSans-Italic-webfont.eot +0 -0
  16. package/docs/fonts/OpenSans-Italic-webfont.svg +1830 -0
  17. package/docs/fonts/OpenSans-Italic-webfont.woff +0 -0
  18. package/docs/fonts/OpenSans-Light-webfont.eot +0 -0
  19. package/docs/fonts/OpenSans-Light-webfont.svg +1831 -0
  20. package/docs/fonts/OpenSans-Light-webfont.woff +0 -0
  21. package/docs/fonts/OpenSans-LightItalic-webfont.eot +0 -0
  22. package/docs/fonts/OpenSans-LightItalic-webfont.svg +1835 -0
  23. package/docs/fonts/OpenSans-LightItalic-webfont.woff +0 -0
  24. package/docs/fonts/OpenSans-Regular-webfont.eot +0 -0
  25. package/docs/fonts/OpenSans-Regular-webfont.svg +1831 -0
  26. package/docs/fonts/OpenSans-Regular-webfont.woff +0 -0
  27. package/docs/global.html +561 -0
  28. package/docs/index.html +570 -0
  29. package/docs/scripts/linenumber.js +25 -0
  30. package/docs/scripts/prettify/Apache-License-2.0.txt +202 -0
  31. package/docs/scripts/prettify/lang-css.js +2 -0
  32. package/docs/scripts/prettify/prettify.js +28 -0
  33. package/docs/styles/jsdoc-default.css +358 -0
  34. package/docs/styles/prettify-jsdoc.css +111 -0
  35. package/docs/styles/prettify-tomorrow.css +132 -0
  36. package/index.js +162 -0
  37. package/package.json +30 -7
  38. package/prebuilds/darwin-arm64/native-vector-store.node +0 -0
  39. package/prebuilds/darwin-x64/native-vector-store.node +0 -0
  40. package/prebuilds/linux-arm64/native-vector-store.node +0 -0
  41. package/prebuilds/linux-x64/native-vector-store.node +0 -0
  42. package/prebuilds/linux-x64-musl/napi-v9/native-vector-store.node +0 -0
  43. package/prebuilds/linux-x64-musl/native-vector-store.node +0 -0
  44. package/prebuilds/win32-x64/native-vector-store.node +0 -0
  45. package/src/Makefile +87 -0
  46. package/src/test_main.cpp +173 -0
  47. package/src/test_stress.cpp +394 -0
  48. package/src/vector_store.cpp +344 -0
  49. package/src/vector_store.h +21 -323
  50. package/native-vector-store-0.1.0.tgz +0 -0
  51. package/scripts/build-prebuilds.sh +0 -23
  52. /package/{src → deps/atomic_queue}/atomic_queue.h +0 -0
  53. /package/{src → deps/atomic_queue}/defs.h +0 -0
@@ -0,0 +1,570 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>JSDoc: Home</title>
6
+
7
+ <script src="scripts/prettify/prettify.js"> </script>
8
+ <script src="scripts/prettify/lang-css.js"> </script>
9
+ <!--[if lt IE 9]>
10
+ <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
11
+ <![endif]-->
12
+ <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
13
+ <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
14
+ </head>
15
+
16
+ <body>
17
+
18
+ <div id="main">
19
+
20
+ <h1 class="page-title">Home</h1>
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+ <h3> </h3>
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+ <section>
46
+ <article><h1 id="native-vector-store">native-vector-store</h1>
47
+ <p>High-performance vector store with SIMD optimization for MCP servers and local RAG applications.</p>
48
+ <h2 id="design-philosophy">Design Philosophy</h2>
49
+ <p>This vector store is designed for <strong>immutable, one-time loading</strong> scenarios common in modern cloud deployments:</p>
50
+ <ul>
51
+ <li><strong>📚 Load Once, Query Many</strong>: Documents are loaded at startup and remain immutable during serving</li>
52
+ <li><strong>🚀 Optimized for Cold Starts</strong>: Perfect for serverless functions and containerized deployments</li>
53
+ <li><strong>📁 File-Based Organization</strong>: Leverages filesystem for natural document organization and versioning</li>
54
+ <li><strong>🎯 Focused API</strong>: Does one thing exceptionally well - fast similarity search over focused corpora (sweet spot: &lt;100k documents)</li>
55
+ </ul>
56
+ <p>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.</p>
57
+ <h2 id="features">Features</h2>
58
+ <ul>
59
+ <li><strong>🚀 High Performance</strong>: C++ implementation with OpenMP SIMD optimization</li>
60
+ <li><strong>📦 Arena Allocation</strong>: Memory-efficient storage with 64MB chunks</li>
61
+ <li><strong>⚡ Fast Search</strong>: Sub-10ms similarity search for large document collections</li>
62
+ <li><strong>🔧 MCP Integration</strong>: Built for Model Context Protocol servers</li>
63
+ <li><strong>🌐 Cross-Platform</strong>: Works on Linux, macOS, and Windows</li>
64
+ <li><strong>📊 TypeScript Support</strong>: Full type definitions included</li>
65
+ <li><strong>🔄 Producer-Consumer Loading</strong>: Parallel document loading at 178k+ docs/sec</li>
66
+ </ul>
67
+ <h2 id="performance-targets">Performance Targets</h2>
68
+ <ul>
69
+ <li><strong>Load Time</strong>: &lt;1 second for 100,000 documents (achieved: ~560ms)</li>
70
+ <li><strong>Search Latency</strong>: &lt;10ms for top-k similarity search (achieved: 1-2ms)</li>
71
+ <li><strong>Memory Efficiency</strong>: Minimal fragmentation via arena allocation</li>
72
+ <li><strong>Scalability</strong>: Designed for focused corpora (&lt;100k documents optimal, &lt;1M maximum)</li>
73
+ <li><strong>Throughput</strong>: 178k+ documents per second with parallel loading</li>
74
+ </ul>
75
+ <h2 id="installation">Installation</h2>
76
+ <pre class="prettyprint source lang-bash"><code>npm install native-vector-store
77
+ </code></pre>
78
+ <h3 id="prerequisites">Prerequisites</h3>
79
+ <p><strong>Runtime Requirements:</strong></p>
80
+ <ul>
81
+ <li>OpenMP runtime library (for parallel processing)
82
+ <ul>
83
+ <li><strong>Linux</strong>: <code>sudo apt-get install libgomp1</code> (Ubuntu/Debian) or <code>dnf install libgomp</code> (Fedora)</li>
84
+ <li><strong>Alpine</strong>: <code>apk add libgomp</code></li>
85
+ <li><strong>macOS</strong>: <code>brew install libomp</code></li>
86
+ <li><strong>Windows</strong>: Included with Visual C++ runtime</li>
87
+ </ul>
88
+ </li>
89
+ </ul>
90
+ <p>Prebuilt binaries are included for:</p>
91
+ <ul>
92
+ <li>Linux (x64, arm64, musl/Alpine)</li>
93
+ <li>macOS (x64, arm64/Apple Silicon)</li>
94
+ <li>Windows (x64)</li>
95
+ </ul>
96
+ <p>If building from source, you'll need:</p>
97
+ <ul>
98
+ <li>Node.js ≥14.0.0</li>
99
+ <li>C++ compiler with OpenMP support</li>
100
+ <li>simdjson library (vendored, no installation needed)</li>
101
+ </ul>
102
+ <h2 id="quick-start">Quick Start</h2>
103
+ <pre class="prettyprint source lang-javascript"><code>const { VectorStore } = require('native-vector-store');
104
+
105
+ // Initialize with embedding dimensions (e.g., 1536 for OpenAI)
106
+ const store = new VectorStore(1536);
107
+
108
+ // Load documents from directory
109
+ store.loadDir('./documents'); // Automatically finalizes after loading
110
+
111
+ // Or add documents manually then finalize
112
+ const document = {
113
+ id: 'doc-1',
114
+ text: 'Example document text',
115
+ metadata: {
116
+ embedding: new Array(1536).fill(0).map(() => Math.random()),
117
+ category: 'example'
118
+ }
119
+ };
120
+
121
+ store.addDocument(document);
122
+ store.finalize(); // Must call before searching!
123
+
124
+ // Search for similar documents
125
+ const queryEmbedding = new Float32Array(1536);
126
+ const results = store.search(queryEmbedding, 5); // Top 5 results
127
+
128
+ console.log(results[0]); // { score: 0.95, id: 'doc-1', text: '...', metadata_json: '...' }
129
+ </code></pre>
130
+ <h2 id="usage-patterns">Usage Patterns</h2>
131
+ <h3 id="serverless-deployment-(aws-lambda%2C-vercel)">Serverless Deployment (AWS Lambda, Vercel)</h3>
132
+ <pre class="prettyprint source lang-javascript"><code>// Initialize once during cold start
133
+ let store;
134
+
135
+ async function initializeStore() {
136
+ if (!store) {
137
+ store = new VectorStore(1536);
138
+ store.loadDir('./knowledge-base'); // Loads and finalizes
139
+ }
140
+ return store;
141
+ }
142
+
143
+ // Handler reuses the store across invocations
144
+ export async function handler(event) {
145
+ const store = await initializeStore();
146
+ const embedding = new Float32Array(event.embedding);
147
+ return store.search(embedding, 10);
148
+ }
149
+ </code></pre>
150
+ <h3 id="local-mcp-server">Local MCP Server</h3>
151
+ <pre class="prettyprint source lang-javascript"><code>const { VectorStore } = require('native-vector-store');
152
+
153
+ // Load different knowledge domains at startup
154
+ const stores = {
155
+ products: new VectorStore(1536),
156
+ support: new VectorStore(1536),
157
+ general: new VectorStore(1536)
158
+ };
159
+
160
+ stores.products.loadDir('./knowledge/products');
161
+ stores.support.loadDir('./knowledge/support');
162
+ stores.general.loadDir('./knowledge/general');
163
+
164
+ // Route searches to appropriate domain
165
+ server.on('search', (query) => {
166
+ const store = stores[query.domain] || stores.general;
167
+ const results = store.search(query.embedding, 5);
168
+ return results.filter(r => r.score > 0.7);
169
+ });
170
+ </code></pre>
171
+ <h3 id="cli-tool-with-persistent-context">CLI Tool with Persistent Context</h3>
172
+ <pre class="prettyprint source lang-javascript"><code>#!/usr/bin/env node
173
+ const { VectorStore } = require('native-vector-store');
174
+
175
+ // Load knowledge base once
176
+ const store = new VectorStore(1536);
177
+ store.loadDir(process.env.KNOWLEDGE_PATH || './docs');
178
+
179
+ // Interactive REPL with fast responses
180
+ const repl = require('repl');
181
+ const r = repl.start('> ');
182
+ r.context.search = (embedding, k = 5) => store.search(embedding, k);
183
+ </code></pre>
184
+ <h3 id="file-organization-best-practices">File Organization Best Practices</h3>
185
+ <p>Structure your documents by category for separate vector stores:</p>
186
+ <pre class="prettyprint source"><code>knowledge-base/
187
+ ├── products/ # Product documentation
188
+ │ ├── api-reference.json
189
+ │ └── user-guide.json
190
+ ├── support/ # Support articles
191
+ │ ├── faq.json
192
+ │ └── troubleshooting.json
193
+ └── context/ # Context-specific docs
194
+ ├── company-info.json
195
+ └── policies.json
196
+ </code></pre>
197
+ <p>Load each category into its own VectorStore:</p>
198
+ <pre class="prettyprint source lang-javascript"><code>// Create separate stores for different domains
199
+ const productStore = new VectorStore(1536);
200
+ const supportStore = new VectorStore(1536);
201
+ const contextStore = new VectorStore(1536);
202
+
203
+ // Load each category independently
204
+ productStore.loadDir('./knowledge-base/products');
205
+ supportStore.loadDir('./knowledge-base/support');
206
+ contextStore.loadDir('./knowledge-base/context');
207
+
208
+ // Search specific domains
209
+ const productResults = productStore.search(queryEmbedding, 5);
210
+ const supportResults = supportStore.search(queryEmbedding, 5);
211
+ </code></pre>
212
+ <p>Each JSON file contains self-contained documents with embeddings:</p>
213
+ <pre class="prettyprint source lang-json"><code>{
214
+ &quot;id&quot;: &quot;unique-id&quot;,
215
+ &quot;text&quot;: &quot;Document content...&quot;,
216
+ &quot;metadata&quot;: {
217
+ &quot;embedding&quot;: [0.1, 0.2, ...],
218
+ &quot;category&quot;: &quot;product&quot;,
219
+ &quot;lastUpdated&quot;: &quot;2024-01-01&quot;
220
+ }
221
+ }
222
+ </code></pre>
223
+ <h3 id="deployment-strategies">Deployment Strategies</h3>
224
+ <h4 id="blue-green-deployment">Blue-Green Deployment</h4>
225
+ <pre class="prettyprint source lang-javascript"><code>// Load new version without downtime
226
+ const newStore = new VectorStore(1536);
227
+ newStore.loadDir('./knowledge-base-v2');
228
+
229
+ // Atomic switch
230
+ app.locals.store = newStore;
231
+ </code></pre>
232
+ <h4 id="versioned-directories">Versioned Directories</h4>
233
+ <pre class="prettyprint source"><code>deployments/
234
+ ├── v1.0.0/
235
+ │ └── documents/
236
+ ├── v1.1.0/
237
+ │ └── documents/
238
+ └── current -> v1.1.0 # Symlink to active version
239
+ </code></pre>
240
+ <h4 id="watch-for-updates-(development)">Watch for Updates (Development)</h4>
241
+ <pre class="prettyprint source lang-javascript"><code>const fs = require('fs');
242
+
243
+ function reloadStore() {
244
+ const newStore = new VectorStore(1536);
245
+ newStore.loadDir('./documents');
246
+ global.store = newStore;
247
+ console.log(`Reloaded ${newStore.size()} documents`);
248
+ }
249
+
250
+ // Initial load
251
+ reloadStore();
252
+
253
+ // Watch for changes in development
254
+ if (process.env.NODE_ENV === 'development') {
255
+ fs.watch('./documents', { recursive: true }, reloadStore);
256
+ }
257
+ </code></pre>
258
+ <h2 id="mcp-server-integration">MCP Server Integration</h2>
259
+ <p>Perfect for building local RAG capabilities in MCP servers:</p>
260
+ <pre class="prettyprint source lang-javascript"><code>const { MCPVectorServer } = require('native-vector-store/examples/mcp-server');
261
+
262
+ const server = new MCPVectorServer(1536);
263
+
264
+ // Load document corpus
265
+ await server.loadDocuments('./documents');
266
+
267
+ // Handle MCP requests
268
+ const response = await server.handleMCPRequest('vector_search', {
269
+ query: queryEmbedding,
270
+ k: 5,
271
+ threshold: 0.7
272
+ });
273
+ </code></pre>
274
+ <h2 id="api-reference">API Reference</h2>
275
+ <h3 id="vectorstore"><code>VectorStore</code></h3>
276
+ <h4 id="constructor">Constructor</h4>
277
+ <pre class="prettyprint source lang-typescript"><code>new VectorStore(dimensions: number)
278
+ </code></pre>
279
+ <h4 id="methods">Methods</h4>
280
+ <h5 id="loaddir(path%3A-string)%3A-void"><code>loadDir(path: string): void</code></h5>
281
+ <p>Load all JSON documents from a directory and automatically finalize the store. Files should contain document objects with embeddings.</p>
282
+ <h5 id="adddocument(doc%3A-document)%3A-void"><code>addDocument(doc: Document): void</code></h5>
283
+ <p>Add a single document to the store. Only works during loading phase (before finalization).</p>
284
+ <pre class="prettyprint source lang-typescript"><code>interface Document {
285
+ id: string;
286
+ text: string;
287
+ metadata: {
288
+ embedding: number[];
289
+ [key: string]: any;
290
+ };
291
+ }
292
+ </code></pre>
293
+ <h5 id="search(query%3A-float32array%2C-k%3A-number%2C-normalizequery%3F%3A-boolean)%3A-searchresult%5B%5D"><code>search(query: Float32Array, k: number, normalizeQuery?: boolean): SearchResult[]</code></h5>
294
+ <p>Search for k most similar documents.</p>
295
+ <pre class="prettyprint source lang-typescript"><code>interface SearchResult {
296
+ score: number;
297
+ id: string;
298
+ text: string;
299
+ metadata_json: string;
300
+ }
301
+ </code></pre>
302
+ <h5 id="finalize()%3A-void"><code>finalize(): void</code></h5>
303
+ <p>Finalize the store: normalize all embeddings and switch to serving mode. After this, no more documents can be added but searches become available. This is automatically called by <code>loadDir()</code>.</p>
304
+ <h5 id="isfinalized()%3A-boolean"><code>isFinalized(): boolean</code></h5>
305
+ <p>Check if the store has been finalized and is ready for searching.</p>
306
+ <h5 id="normalize()%3A-void"><code>normalize(): void</code></h5>
307
+ <p><strong>Deprecated</strong>: Use <code>finalize()</code> instead.</p>
308
+ <h5 id="size()%3A-number"><code>size(): number</code></h5>
309
+ <p>Get the number of documents in the store.</p>
310
+ <h2 id="performance">Performance</h2>
311
+ <h3 id="why-it's-fast">Why It's Fast</h3>
312
+ <p>The native-vector-store achieves exceptional performance through:</p>
313
+ <ol>
314
+ <li><strong>Producer-Consumer Loading</strong>: Parallel file I/O and JSON parsing achieve 178k+ documents/second</li>
315
+ <li><strong>SIMD Optimizations</strong>: OpenMP vectorization for dot product calculations</li>
316
+ <li><strong>Arena Allocation</strong>: Contiguous memory layout with 64MB chunks for cache efficiency</li>
317
+ <li><strong>Zero-Copy Design</strong>: String views and pre-allocated buffers minimize allocations</li>
318
+ <li><strong>Two-Phase Architecture</strong>: Loading phase allows concurrent writes, serving phase optimizes for reads</li>
319
+ </ol>
320
+ <h3 id="benchmarks">Benchmarks</h3>
321
+ <p>Performance on typical hardware (M1 MacBook Pro):</p>
322
+ <table>
323
+ <thead>
324
+ <tr>
325
+ <th>Operation</th>
326
+ <th>Documents</th>
327
+ <th>Time</th>
328
+ <th>Throughput</th>
329
+ </tr>
330
+ </thead>
331
+ <tbody>
332
+ <tr>
333
+ <td>Loading (from disk)</td>
334
+ <td>100,000</td>
335
+ <td>~560ms</td>
336
+ <td>178k docs/sec</td>
337
+ </tr>
338
+ <tr>
339
+ <td>Search (k=10)</td>
340
+ <td>10,000 corpus</td>
341
+ <td>1-2ms</td>
342
+ <td>500-1000 queries/sec</td>
343
+ </tr>
344
+ <tr>
345
+ <td>Search (k=100)</td>
346
+ <td>100,000 corpus</td>
347
+ <td>8-12ms</td>
348
+ <td>80-125 queries/sec</td>
349
+ </tr>
350
+ <tr>
351
+ <td>Normalization</td>
352
+ <td>100,000</td>
353
+ <td>&lt;100ms</td>
354
+ <td>1M+ docs/sec</td>
355
+ </tr>
356
+ </tbody>
357
+ </table>
358
+ <h3 id="performance-tips">Performance Tips</h3>
359
+ <ol>
360
+ <li>
361
+ <p><strong>Optimal File Organization</strong>:</p>
362
+ <ul>
363
+ <li>Keep 1000-10000 documents per JSON file for best I/O performance</li>
364
+ <li>Use arrays of documents in each file rather than one file per document</li>
365
+ </ul>
366
+ </li>
367
+ <li>
368
+ <p><strong>Memory Considerations</strong>:</p>
369
+ <ul>
370
+ <li>Each document requires: <code>embedding_size * 4 bytes + metadata_size + text_size</code></li>
371
+ <li>100k documents with 1536-dim embeddings ≈ 600MB embeddings + metadata</li>
372
+ </ul>
373
+ </li>
374
+ <li>
375
+ <p><strong>Search Performance</strong>:</p>
376
+ <ul>
377
+ <li>Scales linearly with corpus size and k value</li>
378
+ <li>Use smaller k values (5-20) for interactive applications</li>
379
+ <li>Pre-normalize query embeddings if making multiple searches</li>
380
+ </ul>
381
+ </li>
382
+ <li>
383
+ <p><strong>Corpus Size Optimization</strong>:</p>
384
+ <ul>
385
+ <li>Sweet spot: &lt;100k documents for optimal load/search balance</li>
386
+ <li>Beyond 100k: Consider if your use case truly needs all documents</li>
387
+ <li>Focus on curated, domain-specific content rather than exhaustive datasets</li>
388
+ </ul>
389
+ </li>
390
+ </ol>
391
+ <h3 id="comparison-with-alternatives">Comparison with Alternatives</h3>
392
+ <table>
393
+ <thead>
394
+ <tr>
395
+ <th>Feature</th>
396
+ <th>native-vector-store</th>
397
+ <th>Faiss</th>
398
+ <th>ChromaDB</th>
399
+ <th>Pinecone</th>
400
+ </tr>
401
+ </thead>
402
+ <tbody>
403
+ <tr>
404
+ <td>Load 100k docs</td>
405
+ <td>&lt;1s</td>
406
+ <td>2-5s</td>
407
+ <td>30-60s</td>
408
+ <td>N/A (API)</td>
409
+ </tr>
410
+ <tr>
411
+ <td>Search latency</td>
412
+ <td>1-2ms</td>
413
+ <td>0.5-1ms</td>
414
+ <td>50-200ms</td>
415
+ <td>50-300ms</td>
416
+ </tr>
417
+ <tr>
418
+ <td>Memory efficiency</td>
419
+ <td>High</td>
420
+ <td>Medium</td>
421
+ <td>Low</td>
422
+ <td>N/A</td>
423
+ </tr>
424
+ <tr>
425
+ <td>Dependencies</td>
426
+ <td>Minimal</td>
427
+ <td>Heavy</td>
428
+ <td>Heavy</td>
429
+ <td>None</td>
430
+ </tr>
431
+ <tr>
432
+ <td>Deployment</td>
433
+ <td>Simple</td>
434
+ <td>Complex</td>
435
+ <td>Complex</td>
436
+ <td>SaaS</td>
437
+ </tr>
438
+ <tr>
439
+ <td>Sweet spot</td>
440
+ <td>&lt;100k docs</td>
441
+ <td>Any size</td>
442
+ <td>Any size</td>
443
+ <td>Any size</td>
444
+ </tr>
445
+ </tbody>
446
+ </table>
447
+ <h2 id="building-from-source">Building from Source</h2>
448
+ <pre class="prettyprint source lang-bash"><code># Install dependencies
449
+ npm install
450
+
451
+ # Build native module
452
+ npm run build
453
+
454
+ # Run tests
455
+ npm test
456
+
457
+ # Run performance benchmarks
458
+ npm run benchmark
459
+
460
+ # Try MCP server example
461
+ npm run example
462
+ </code></pre>
463
+ <h2 id="architecture">Architecture</h2>
464
+ <h3 id="memory-layout">Memory Layout</h3>
465
+ <ul>
466
+ <li><strong>Arena Allocator</strong>: 64MB chunks for cache-friendly access</li>
467
+ <li><strong>Contiguous Storage</strong>: Embeddings, strings, and metadata in single allocations</li>
468
+ <li><strong>Zero-Copy Design</strong>: Direct memory access without serialization overhead</li>
469
+ </ul>
470
+ <h3 id="simd-optimization">SIMD Optimization</h3>
471
+ <ul>
472
+ <li><strong>OpenMP Pragmas</strong>: Vectorized dot product operations</li>
473
+ <li><strong>Parallel Processing</strong>: Multi-threaded JSON loading and search</li>
474
+ <li><strong>Cache-Friendly</strong>: Aligned memory access patterns</li>
475
+ </ul>
476
+ <h3 id="performance-characteristics">Performance Characteristics</h3>
477
+ <ul>
478
+ <li><strong>Load Performance</strong>: O(n) with parallel JSON parsing</li>
479
+ <li><strong>Search Performance</strong>: O(n⋅d) with SIMD acceleration</li>
480
+ <li><strong>Memory Usage</strong>: ~(d⋅4 + text_size) bytes per document</li>
481
+ </ul>
482
+ <h2 id="use-cases">Use Cases</h2>
483
+ <h3 id="mcp-servers">MCP Servers</h3>
484
+ <p>Ideal for building local RAG (Retrieval-Augmented Generation) capabilities:</p>
485
+ <ul>
486
+ <li>Fast document loading from focused knowledge bases</li>
487
+ <li>Low-latency similarity search for context retrieval</li>
488
+ <li>Memory-efficient storage for domain-specific corpora</li>
489
+ </ul>
490
+ <h3 id="knowledge-management">Knowledge Management</h3>
491
+ <p>Perfect for personal knowledge management systems:</p>
492
+ <ul>
493
+ <li>Index personal documents and notes (typically &lt;10k documents)</li>
494
+ <li>Fast semantic search across focused content</li>
495
+ <li>Offline operation without external dependencies</li>
496
+ </ul>
497
+ <h3 id="research-applications">Research Applications</h3>
498
+ <p>Suitable for academic and research projects with focused datasets:</p>
499
+ <ul>
500
+ <li>Literature review within specific domains</li>
501
+ <li>Semantic clustering of curated paper collections</li>
502
+ <li>Cross-reference discovery in specialized corpora</li>
503
+ </ul>
504
+ <h2 id="contributing">Contributing</h2>
505
+ <ol>
506
+ <li>Fork the repository</li>
507
+ <li>Create a feature branch</li>
508
+ <li>Make your changes</li>
509
+ <li>Add tests for new functionality</li>
510
+ <li>Ensure all tests pass</li>
511
+ <li>Submit a pull request</li>
512
+ </ol>
513
+ <h2 id="license">License</h2>
514
+ <p>MIT License - see LICENSE file for details.</p>
515
+ <h2 id="benchmarks-1">Benchmarks</h2>
516
+ <p>Performance on M1 MacBook Pro with 1536-dimensional embeddings:</p>
517
+ <table>
518
+ <thead>
519
+ <tr>
520
+ <th>Operation</th>
521
+ <th>Document Count</th>
522
+ <th>Time</th>
523
+ <th>Rate</th>
524
+ </tr>
525
+ </thead>
526
+ <tbody>
527
+ <tr>
528
+ <td>Load</td>
529
+ <td>10,000</td>
530
+ <td>245ms</td>
531
+ <td>40.8k docs/sec</td>
532
+ </tr>
533
+ <tr>
534
+ <td>Search</td>
535
+ <td>10,000</td>
536
+ <td>3.2ms</td>
537
+ <td>3.1M docs/sec</td>
538
+ </tr>
539
+ <tr>
540
+ <td>Normalize</td>
541
+ <td>10,000</td>
542
+ <td>12ms</td>
543
+ <td>833k docs/sec</td>
544
+ </tr>
545
+ </tbody>
546
+ </table>
547
+ <p><em>Results may vary based on hardware and document characteristics.</em></p></article>
548
+ </section>
549
+
550
+
551
+
552
+
553
+
554
+
555
+ </div>
556
+
557
+ <nav>
558
+ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="VectorStore.html">VectorStore</a></li><li><a href="VectorStoreWrapper.html">VectorStoreWrapper</a></li></ul><h3><a href="global.html">Global</a></h3>
559
+ </nav>
560
+
561
+ <br class="clear">
562
+
563
+ <footer>
564
+ Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.4</a>
565
+ </footer>
566
+
567
+ <script> prettyPrint(); </script>
568
+ <script src="scripts/linenumber.js"> </script>
569
+ </body>
570
+ </html>
@@ -0,0 +1,25 @@
1
+ /*global document */
2
+ (() => {
3
+ const source = document.getElementsByClassName('prettyprint source linenums');
4
+ let i = 0;
5
+ let lineNumber = 0;
6
+ let lineId;
7
+ let lines;
8
+ let totalLines;
9
+ let anchorHash;
10
+
11
+ if (source && source[0]) {
12
+ anchorHash = document.location.hash.substring(1);
13
+ lines = source[0].getElementsByTagName('li');
14
+ totalLines = lines.length;
15
+
16
+ for (; i < totalLines; i++) {
17
+ lineNumber++;
18
+ lineId = `line${lineNumber}`;
19
+ lines[i].id = lineId;
20
+ if (lineId === anchorHash) {
21
+ lines[i].className += ' selected';
22
+ }
23
+ }
24
+ }
25
+ })();