Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
default
✓ import RuVector from '@ruvector/attention'
✗ const RuVector = require('@ruvector/attention')
ESM-only since v2.0. The main entry point is @ruvector/attention, not ruvector.
HybridSearch
✓ import { HybridSearch } from '@ruvector/attention'
✗ import { HybridSearch } from 'ruvector'
Named export available from @ruvector/attention. Requires peer dep @ruvector/router.
HNSWIndex
✓ import { HNSWIndex } from '@ruvector/attention'
✗ import { HNSWIndex } from 'hnswlib'
RuVector provides its own HNSW implementation; do not mix with hnswlib.
Demonstrates core operations: creating a vector database, adding vectors, hybrid search, FlashAttention-3, and HNSW indexing.
import RuVector, { HNSWIndex, HybridSearch, FlashAttention } from '@ruvector/attention'
// Create a new vector database instance
const db = new RuVector({ dimension: 384, metric: 'cosine' })
// Add vectors with metadata
const id1 = await db.add([0.1, 0.2, 0.3, /* ... 384-d vector */], { label: 'doc1' })
const id2 = await db.add([0.4, 0.5, 0.6, /* ... */], { label: 'doc2' })
// Perform hybrid search (sparse + dense fusion)
const hybrid = new HybridSearch(db, { alpha: 0.5 })
const results = await hybrid.search([0.1, 0.2, 0.3], { topK: 5, rerank: true })
console.log('Hybrid results:', results)
// Use FlashAttention-3 for exact nearest neighbor
const attn = new FlashAttention({ heads: 8, headDim: 64 })
const scores = await attn.compute(queryVectors, keyVectors)
// Build HNSW index for fast approximate search
const index = new HNSWIndex({ dimension: 384, M: 16, efConstruction: 200 })
await index.build(vectors)
const neighbors = await index.search(query, 10)
console.log('ANN neighbors:', neighbors)
// Persist to disk using DiskANN
await db.save('./my_index.ruv')
Errors
Common errors & fixes
Error: Cannot find module '@ruvector/attention' or 'ruvector'
Package not installed or wrong package name used.
fixInstall the correct package: npm install @ruvector/attention
Error [ERR_REQUIRE_ESM]: require() of ES Module not supported
Using CommonJS require() with an ESM-only package.
fixUse import syntax or set type: module in package.json. Alternatively, use dynamic import().
TypeError: RuVector is not a constructor
Importing the wrong default export, possibly from an older version or wrong subpackage.
fixUse import RuVector from '@ruvector/attention' (default export) and ensure version >=2.0.0.
Uncaught RuntimeError: memory access out of bounds (WASM)
Native addon failed to load, falling back to WASM with insufficient memory allocation.
fixSet RUVECTOR_FORCE_WASM=1 and allocate more memory via WebAssembly.Memory, or install platform-specific native package.
Audit
Dependencies
@ruvector/pi-brainrequiredProvides neural attention and memory subsystems required by the core vector operations
@ruvector/routerrequiredHandles intelligent agent routing and query distribution across vector indexes
@ruvector/ruvllmrequiredEnables LLM integration for Graph RAG and natural language query parsing
@ruvector/diskannrequiredProvides DiskANN and Vamana graph-based ANN for large-scale persistent storage