@ruvector/rvf-node

Native Node.js bindings for the RuVector Format (RVF) vector database. Built with Rust via N-API for native speed with zero serialization overhead.

Install

npm install @ruvector/rvf-node

Features

• Native Rust performance via N-API (napi-rs), no FFI marshaling
• Single-file vector database — crash-safe, no WAL, append-only
• k-NN search with HNSW progressive indexing (recall 0.70 → 0.95)
• Metadata filtering — Eq, Ne, Lt, Gt, Range, In, And, Or, Not
• Lineage tracking — DNA-style parent/child derivation chains
• Kernel & eBPF embedding — embed compute alongside vector data
• Segment inspection — enumerate all segments in the file
• Cross-platform — Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon), Windows (x86_64)
• AGI methods — HNSW index stats, witness chain verification, state freeze, metric introspection

AGI Methods

Four introspection and integrity methods for advanced use cases.

db.indexStats() → RvfIndexStats

Returns HNSW index statistics.

| Field | Type | Description | |-------|------|-------------| | indexedVectors | number | Number of indexed vectors | | layers | number | Number of HNSW layers | | m | number | M parameter (max edges per node per layer) | | efConstruction | number | ef_construction parameter | | needsRebuild | boolean | Whether index needs rebuilding (dead_space_ratio > 0.3) |

db.verifyWitness() → RvfWitnessResult

Verifies SHAKE-256 witness chain integrity.

| Field | Type | Description | |-------|------|-------------| | valid | boolean | Whether the chain is valid | | entries | number | Number of entries in the chain | | error | string? | Error message if invalid |

db.freeze() → number

Snapshot-freeze current state. Returns the epoch number.

db.metric() → string

Returns the distance metric name ("l2", "cosine", or "inner_product").

Usage Example

const stats = db.indexStats();
console.log(`Indexed: ${stats.indexedVectors}, HNSW layers: ${stats.layers}`);

const witness = db.verifyWitness();
console.log(`Witness chain: ${witness.entries} entries, valid: ${witness.valid}`);

console.log(`Distance metric: ${db.metric()}`);

const epoch = db.freeze();
console.log(`State frozen at epoch ${epoch}`);

Quick Start

const { RvfDatabase } = require('@ruvector/rvf-node');

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

// Insert vectors
const vectors = new Float32Array(384 * 2); // 2 vectors, 384 dims each
vectors.fill(0.1);
db.ingestBatch(vectors, [1, 2]);

// Query nearest neighbors
const query = new Float32Array(384);
query.fill(0.15);
const results = db.query(query, 5);
// [{ id: 1, distance: 0.002 }, { id: 2, distance: 0.002 }]

db.close();

API Reference

Store Lifecycle

// Create a new store
const db = RvfDatabase.create(path: string, options: RvfOptions);

// Open existing store (read-write, acquires writer lock)
const db = RvfDatabase.open(path: string);

// Open read-only (no lock, concurrent readers allowed)
const db = RvfDatabase.openReadonly(path: string);

// Close and flush
db.close();

RvfOptions:

| Field | Type | Default | Description | |-------|------|---------|-------------| | dimension | number | required | Vector dimensionality | | metric | string | "l2" | "l2", "cosine", or "inner_product" | | profile | number | 0 | Hardware profile: 0=Generic, 1=Core, 2=Hot, 3=Full | | signing | boolean | false | Enable segment signing | | m | number | 16 | HNSW M parameter (neighbor count) | | efConstruction | number | 200 | HNSW index build quality |

Ingest Vectors

const result = db.ingestBatch(
  vectors: Float32Array,  // flat array of n * dimension floats
  ids: number[],          // vector IDs
  metadata?: RvfMetadataEntry[]  // optional metadata per vector
);
// Returns: { accepted: number, rejected: number, epoch: number }

Metadata entry format:

{ fieldId: 0, valueType: 'string', value: 'category_a' }
{ fieldId: 1, valueType: 'f64',    value: '0.95' }
{ fieldId: 2, valueType: 'u64',    value: '42' }

Query

const results = db.query(
  vector: Float32Array,      // query vector
  k: number,                 // number of neighbors
  options?: RvfQueryOptions   // optional search parameters
);
// Returns: [{ id: number, distance: number }, ...]

RvfQueryOptions:

| Field | Type | Default | Description | |-------|------|---------|-------------| | efSearch | number | 100 | HNSW search quality (higher = better recall, slower) | | filter | string | — | Filter expression as JSON string | | timeoutMs | number | 0 | Query timeout in ms (0 = no timeout) |

Filter Expressions

Filters are passed as JSON strings. All leaf filters require fieldId, valueType, and value:

// Equality
db.query(vec, 10, {
  filter: '{"op":"eq","fieldId":0,"valueType":"string","value":"science"}'
});

// Range
db.query(vec, 10, {
  filter: '{"op":"range","fieldId":1,"valueType":"f64","low":"0.5","high":"1.0"}'
});

// In-set
db.query(vec, 10, {
  filter: '{"op":"in","fieldId":0,"valueType":"u64","values":["1","2","5"]}'
});

// Boolean combinations
db.query(vec, 10, {
  filter: JSON.stringify({
    op: 'and',
    children: [
      { op: 'eq', fieldId: 0, valueType: 'string', value: 'science' },
      { op: 'gt', fieldId: 1, valueType: 'f64', value: '0.8' }
    ]
  })
});

// Negation
db.query(vec, 10, {
  filter: '{"op":"not","child":{"op":"eq","fieldId":0,"valueType":"string","value":"spam"}}'
});

Supported operators: eq, ne, lt, le, gt, ge, in, range, and, or, not

Supported value types: u64, i64, f64, string, bool

Delete

// Delete by ID
const result = db.delete([1, 2, 3]);
// Returns: { deleted: number, epoch: number }

// Delete by filter
const result = db.deleteByFilter(
  '{"op":"gt","fieldId":1,"valueType":"f64","value":"0.9"}'
);

Compact

Reclaims space from deleted vectors:

const result = db.compact();
// Returns: { segmentsCompacted: number, bytesReclaimed: number, epoch: number }

Status

const status = db.status();
// {
//   totalVectors: number,
//   totalSegments: number,
//   fileSize: number,
//   currentEpoch: number,
//   profileId: number,
//   compactionState: 'idle' | 'running' | 'emergency',
//   deadSpaceRatio: number,
//   readOnly: boolean
// }

Lineage & Derivation

RVF tracks parent/child relationships with cryptographic hashes:

db.fileId();        // hex string — unique file identifier
db.parentId();      // hex string — parent's ID (zeros if root)
db.lineageDepth();  // 0 for root files

// Derive a child store (inherits dimensions and options)
const child = db.derive('/tmp/child.rvf');
child.lineageDepth(); // 1
child.parentId();     // matches parent's fileId()

Kernel & eBPF Embedding

Embed compute segments alongside vector data:

// Embed a Linux microkernel
db.embedKernel(
  1,                           // arch: 0=x86_64, 1=aarch64
  0,                           // kernel type
  0,                           // flags
  Buffer.from(kernelImage),    // kernel binary
  8080,                        // API port
  'console=ttyS0 quiet'       // kernel cmdline (optional)
);

// Extract kernel
const kernel = db.extractKernel();
if (kernel) {
  console.log(kernel.header);  // Buffer: 128-byte KernelHeader
  console.log(kernel.image);   // Buffer: kernel image bytes
}

// Embed an eBPF XDP program
db.embedEbpf(
  1,                          // program type (XDP distance)
  2,                          // attach type (XDP ingress)
  384,                        // max vector dimension
  Buffer.from(bytecode),      // BPF ELF object
  Buffer.from(btf)            // optional BTF section
);

// Extract eBPF
const ebpf = db.extractEbpf();
if (ebpf) {
  console.log(ebpf.header);   // Buffer: 64-byte EbpfHeader
  console.log(ebpf.payload);  // Buffer: bytecode + BTF
}

Segment Inspection

const segments = db.segments();
// [{ id: 1, offset: 0, payloadLength: 4096, segType: 'manifest' },
//  { id: 2, offset: 4160, payloadLength: 51200, segType: 'vec' },
//  { id: 3, offset: 55424, payloadLength: 12288, segType: 'index' }]

db.dimension(); // 384

Self-Booting RVF

An .rvf file can embed a Linux kernel, eBPF programs, and SSH keys alongside vector data — producing a single file that boots as a microservice.

The Claude Code Appliance example builds a complete AI dev environment:

cd examples/rvf
cargo run --example claude_code_appliance

claude_code_appliance.rvf
  ├── KERNEL_SEG    Linux 6.8.12 bzImage (5.2 MB, x86_64)
  ├── EBPF_SEG      Socket filter — ports 2222, 8080 only
  ├── VEC_SEG       20 package embeddings (128-dim)
  ├── INDEX_SEG     HNSW graph for package search
  ├── WITNESS_SEG   6-entry tamper-evident audit trail
  └── CRYPTO_SEG    3 Ed25519 SSH user keys

Final file: 5.1 MB single .rvf — boots Linux, serves queries, runs Claude Code.

See the full RVF documentation for details.

Build from Source

# Prerequisites: Rust 1.87+, Node.js 18+
cd crates/rvf/rvf-node
npm install
npm run build

Related Packages

| Package | Description | |---------|-------------| | @ruvector/rvf | Unified TypeScript SDK | | @ruvector/rvf-wasm | Browser WASM package | | @ruvector/rvf-mcp-server | MCP server for AI agents | | rvf-runtime | Rust runtime (powers this package) |

License

MIT OR Apache-2.0