@ruvector/rvf

Unified TypeScript/JavaScript SDK for the RuVector Format (RVF) — a cognitive container that stores vectors, carries models, boots compute kernels, and proves everything in a single .rvf file.

Platform Support

Deno: The WASM build targets wasm32-unknown-unknown, which runs natively in Deno. Import via npm: specifier or load the .wasm bundle directly.

Browser: The @ruvector/rvf-wasm package provides a ~46 KB control-plane WASM module plus a ~5.5 KB tile-compute module. Works in any browser with WebAssembly support.

Install

# Node.js (auto-detects native or WASM)
npm install @ruvector/rvf

# WASM only (browser, Deno, edge)
npm install @ruvector/rvf-wasm

Quick Start

Node.js

import { RvfDatabase } from '@ruvector/rvf';

// Create a vector store
const db = RvfDatabase.create('vectors.rvf', { dimension: 384 });

// Insert vectors
db.ingestBatch(new Float32Array(384), [1]);

// Query nearest neighbors
const results = db.query(new Float32Array(384), 10);

// Lineage & inspection
console.log(db.fileId());       // unique file UUID
console.log(db.dimension());    // 384
console.log(db.segments());     // [{ type, id, size }]

// Derive child (COW branching)
const child = db.derive('child.rvf');

db.close();

Browser (WASM)

<script type="module">
import init, { RvfStore } from '@ruvector/rvf-wasm';

await init();

const store = RvfStore.create(384, 'cosine');
store.ingest(new Float32Array(384), 0);
const results = store.query(new Float32Array(384), 10);
console.log('Results:', results);
</script>

Deno

// Import via npm: specifier
import init, { RvfStore } from "npm:@ruvector/rvf-wasm";

await init();

const store = RvfStore.create(384, 'cosine');
store.ingest(new Float32Array(384), 0);
const results = store.query(new Float32Array(384), 10);
console.log('Results:', results);

What is RVF?

RVF (RuVector Format) is a universal binary substrate that merges database, model, graph engine, kernel, and attestation into a single deployable file. A .rvf file is segmented — each segment carries a different payload type, and unknown segments are preserved by all tools.

Segment Types

N-API Methods (Node.js)

19 methods on the RvfDatabase class:

WASM Exports

29 exported functions for browser and edge runtimes:

Control plane (10): rvf_create, rvf_open, rvf_close, rvf_ingest, rvf_query, rvf_delete, rvf_status, rvf_compact, rvf_derive, rvf_segments

Tile compute (14): tile_dot_f32, tile_cosine_f32, tile_l2_f32, tile_dot_f16, tile_cosine_f16, tile_l2_f16, tile_topk, tile_quantize_sq8, tile_dequantize_sq8, tile_scan_filtered, tile_merge_topk, tile_batch_distance, tile_prefetch, tile_accumulate

Segment parsing (3): parse_segment_header, parse_vec_header, parse_manifest

Memory (2): rvf_alloc, rvf_free

CLI (Rust)

18 subcommands available through the rvf binary:

# Core operations
rvf create vectors.rvf --dimension 384 --metric cosine
rvf ingest vectors.rvf --input data.json
rvf query vectors.rvf --vector "[0.1,0.2,...]" --k 10
rvf delete vectors.rvf --ids "[1,2,3]"
rvf status vectors.rvf
rvf inspect vectors.rvf
rvf compact vectors.rvf

# Branching & lineage
rvf derive vectors.rvf --output child.rvf
rvf filter vectors.rvf --include "[1,2,3]"
rvf freeze vectors.rvf
rvf rebuild-refcounts vectors.rvf

# Compute containers
rvf serve vectors.rvf --port 8080
rvf launch vectors.rvf
rvf embed-kernel vectors.rvf --image bzImage
rvf embed-ebpf vectors.rvf --program filter.o

# Verification
rvf verify-witness vectors.rvf
rvf verify-attestation vectors.rvf

# Export
rvf export vectors.rvf --output dump.json

Build the CLI:

cargo install --path crates/rvf/rvf-cli

Example .rvf Files

45 pre-built example files are available for download (~11 MB total). These demonstrate every segment type and use case.

Download

# Download a specific example
curl -LO https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output/basic_store.rvf

# Clone just the examples
git clone --depth 1 --filter=blob:none --sparse https://github.com/ruvnet/ruvector.git
cd ruvector && git sparse-checkout set examples/rvf/output

Example Catalog

Generate Examples Locally

cd crates/rvf
cargo run --example generate_all
ls output/  # 45 .rvf files

Integration

With ruvector (npx ruvector)

The ruvector npm package includes 8 RVF CLI commands:

npm install ruvector @ruvector/rvf

# Enable RVF backend
export RUVECTOR_BACKEND=rvf

# Or use --backend flag
npx ruvector --backend rvf create mydb.rvf -d 384

# RVF-specific commands
npx ruvector rvf create mydb.rvf -d 384
npx ruvector rvf ingest mydb.rvf --input data.json
npx ruvector rvf query mydb.rvf --vector "[0.1,...]" --k 10
npx ruvector rvf status mydb.rvf
npx ruvector rvf segments mydb.rvf
npx ruvector rvf derive mydb.rvf --output child.rvf
npx ruvector rvf compact mydb.rvf
npx ruvector rvf export mydb.rvf --output dump.json

With rvlite

npm install rvlite @ruvector/rvf-wasm

When @ruvector/rvf-wasm is installed, rvlite can use RVF as a persistent storage backend:

import { createRvLite } from 'rvlite';

// rvlite auto-detects @ruvector/rvf-wasm for persistence
const db = await createRvLite({ dimensions: 384 });
await db.insert([0.1, 0.2, ...], { text: "Hello world" });
const results = await db.search([0.1, 0.2, ...], 5);

Packages

Crate Structure (Rust)

License

MIT