RuVector

0.2.23 verified Sat Apr 25 auth: no javascript

RuVector is a self-learning vector database for Node.js built in Rust, offering sub-millisecond hybrid search, Graph RAG, FlashAttention-3, HNSW, and DiskANN, with over 50 attention mechanisms. Current stable version is 2.2.0, with frequent releases (weekly to monthly). Key differentiators: single npm package, no external services required, native Node.js performance via Rust native bindings with WASM fallback, TypeScript-first API, and built-in self-learning capabilities. It integrates deeply with the Claude Code ecosystem and provides enterprise-grade features like ONNX embeddings, AST analysis, and security scanning.

Common errors

error Error: Cannot find module '@ruvector/attention' or 'ruvector' ↓

cause Package not installed or wrong package name used.

fix

Install the correct package: npm install @ruvector/attention

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() with an ESM-only package.

fix

Use import syntax or set type: module in package.json. Alternatively, use dynamic import().

error TypeError: RuVector is not a constructor ↓

cause Importing the wrong default export, possibly from an older version or wrong subpackage.

fix

Use import RuVector from '@ruvector/attention' (default export) and ensure version >=2.0.0.

error Uncaught RuntimeError: memory access out of bounds (WASM) ↓

cause Native addon failed to load, falling back to WASM with insufficient memory allocation.

fix

Set RUVECTOR_FORCE_WASM=1 and allocate more memory via WebAssembly.Memory, or install platform-specific native package.

Warnings

breaking Since v2.0.0, the package has moved from default export 'ruvector' to package '@ruvector/attention'. All imports from 'ruvector' will fail. ↓

fix Change imports to use '@ruvector/attention' instead of 'ruvector'.

breaking Node.js <18.0.0 is no longer supported. Engine requirement is >=18.0.0. ↓

fix Upgrade Node.js to version 18 or later.

deprecated The 'ruvector' package on npm is legacy and will not receive updates. Use '@ruvector/attention' for all new projects. ↓

fix Migrate to @ruvector/attention.

gotcha The package uses native Node.js addons (N-API) by default. If they fail to load, it falls back to WASM, which may be slower and lack some features (e.g., DiskANN). ↓

fix Ensure your platform is supported or set environment variable RUVECTOR_FORCE_WASM=1 to force WASM.

gotcha HybridSearch requires both 'alpha' parameter in constructor and both sparse/dense indexes to be built. Missing one will cause silent fallback to dense-only. ↓

fix Always ensure both sparse (e.g., SPLADE) and dense indexes are added to the database before using HybridSearch.

breaking In v0.x to v1.x migration, the API for adding vectors changed from 'db.add(vector, metadata)' to 'db.add({ vector, metadata })' as an object parameter. ↓

fix Update calls to pass an object with 'vector' and 'metadata' keys.

Install

npm install ruvector

yarn add ruvector

pnpm add ruvector

Imports

default
wrong
```
const RuVector = require('@ruvector/attention')
```
correct
```
import RuVector from '@ruvector/attention'
```
ESM-only since v2.0. The main entry point is @ruvector/attention, not ruvector.
HybridSearch
wrong
```
import { HybridSearch } from 'ruvector'
```
correct
```
import { HybridSearch } from '@ruvector/attention'
```
Named export available from @ruvector/attention. Requires peer dep @ruvector/router.
HNSWIndex
wrong
```
import { HNSWIndex } from 'hnswlib'
```
correct
```
import { HNSWIndex } from '@ruvector/attention'
```
RuVector provides its own HNSW implementation; do not mix with hnswlib.

Quickstart

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')