Ruvector Node.js API Reference

Complete API reference for ruvector npm package.

Installation

npm install ruvector
# or
yarn add ruvector

VectorDB
AgenticDB
Types
Advanced Features
Error Handling

VectorDB

Core vector database class.

Constructor

new VectorDB(options: DbOptions): VectorDB

Create a new vector database.

Parameters:

interface DbOptions {
    dimensions: number;
    storagePath: string;
    distanceMetric?: 'euclidean' | 'cosine' | 'dotProduct' | 'manhattan';
    hnsw?: HnswConfig;
    quantization?: QuantizationConfig;
    mmapVectors?: boolean;
}

Example:

const { VectorDB } = require('ruvector');

const db = new VectorDB({
    dimensions: 128,
    storagePath: './vectors.db',
    distanceMetric: 'cosine'
});

insert

async insert(entry: VectorEntry): Promise<string>

Insert a single vector.

Parameters:

interface VectorEntry {
    id?: string;
    vector: Float32Array;
    metadata?: Record<string, any>;
}

Returns: Promise resolving to vector ID

Example:

const id = await db.insert({
    vector: new Float32Array(128).fill(0.1),
    metadata: { text: 'Example document' }
});

console.log('Inserted:', id);

insertBatch

async insertBatch(entries: VectorEntry[]): Promise<string[]>

Insert multiple vectors efficiently.

Parameters: Array of vector entries

Returns: Promise resolving to array of IDs

Example:

const entries = Array.from({ length: 1000 }, (_, i) => ({
    id: `vec_${i}`,
    vector: new Float32Array(128).map(() => Math.random()),
    metadata: { index: i }
}));

const ids = await db.insertBatch(entries);
console.log(`Inserted ${ids.length} vectors`);

search

async search(query: SearchQuery): Promise<SearchResult[]>

Search for similar vectors.

Parameters:

interface SearchQuery {
    vector: Float32Array;
    k: number;
    filter?: any;
    includeVectors?: boolean;
    includeMetadata?: boolean;
}

Returns: Promise resolving to search results

Example:

const results = await db.search({
    vector: new Float32Array(128).fill(0.1),
    k: 10,
    includeMetadata: true
});

results.forEach(result => {
    console.log(`ID: ${result.id}, Distance: ${result.distance}`);
    console.log(`Metadata:`, result.metadata);
});

delete

async delete(id: string): Promise<void>

Delete a vector by ID.

Parameters: Vector ID string

Returns: Promise resolving when complete

Example:

await db.delete('vec_001');
console.log('Deleted vec_001');

update

async update(id: string, entry: VectorEntry): Promise<void>

Update an existing vector.

Parameters:

id: Vector ID to update
entry: New vector data

Returns: Promise resolving when complete

Example:

await db.update('vec_001', {
    vector: new Float32Array(128).fill(0.2),
    metadata: { updated: true }
});

count

count(): number

Get total number of vectors.

Returns: Number of vectors

Example:

const total = db.count();
console.log(`Total vectors: ${total}`);

AgenticDB

Extended API for AI agents.

Constructor

new AgenticDB(options: DbOptions): AgenticDB

Create AgenticDB instance.

Example:

const { AgenticDB } = require('ruvector');

const db = new AgenticDB({
    dimensions: 128,
    storagePath: './agenticdb.db'
});

Reflexion Memory

storeEpisode

async storeEpisode(
    task: string,
    actions: string[],
    observations: string[],
    critique: string
): Promise<string>

Store self-critique episode.

Parameters:

task: Task description
actions: Actions taken
observations: Observations made
critique: Self-generated critique

Returns: Episode ID

Example:

const episodeId = await db.storeEpisode(
    'Solve coding problem',
    ['Read problem', 'Write solution', 'Submit'],
    ['Tests failed', 'Edge case missed'],
    'Should test edge cases before submitting'
);

retrieveEpisodes

async retrieveEpisodes(
    queryEmbedding: Float32Array,
    k: number
): Promise<ReflexionEpisode[]>

Retrieve similar past episodes.

Parameters:

queryEmbedding: Embedded critique or task
k: Number of episodes

Returns: Similar episodes

Example:

const episodes = await db.retrieveEpisodes(critiqueEmbedding, 5);

episodes.forEach(ep => {
    console.log(`Task: ${ep.task}`);
    console.log(`Critique: ${ep.critique}`);
    console.log(`Actions: ${ep.actions.join(', ')}`);
});

Skill Library

createSkill

async createSkill(
    name: string,
    description: string,
    parameters: Record<string, string>,
    examples: string[]
): Promise<string>

Create a reusable skill.

Parameters:

name: Skill name
description: What the skill does
parameters: Required parameters
examples: Usage examples

Returns: Skill ID

Example:

const skillId = await db.createSkill(
    'authenticate_user',
    'Authenticate user with JWT token',
    {
        token: 'string',
        userId: 'string'
    },
    ['authenticate_user(token, userId)']
);

searchSkills

async searchSkills(
    queryEmbedding: Float32Array,
    k: number
): Promise<Skill[]>

Search for relevant skills.

Parameters:

queryEmbedding: Embedded task description
k: Number of skills

Returns: Relevant skills

Example:

const skills = await db.searchSkills(taskEmbedding, 3);

skills.forEach(skill => {
    console.log(`${skill.name}: ${skill.description}`);
    console.log(`Success rate: ${(skill.successRate * 100).toFixed(1)}%`);
    console.log(`Usage count: ${skill.usageCount}`);
});

Causal Memory

addCausalEdge

async addCausalEdge(
    causes: string[],
    effects: string[],
    confidence: number,
    context: string
): Promise<string>

Add cause-effect relationship.

Parameters:

causes: Cause actions/states
effects: Effect actions/states
confidence: Confidence score (0-1)
context: Context description

Returns: Edge ID

Example:

const edgeId = await db.addCausalEdge(
    ['authenticate', 'validate_token'],
    ['access_granted'],
    0.95,
    'User authentication flow'
);

queryCausal

async queryCausal(
    queryEmbedding: Float32Array,
    k: number
): Promise<CausalQueryResult[]>

Query causal relationships.

Parameters:

queryEmbedding: Embedded context
k: Number of results

Returns: Causal edges with utility scores

Example:

const results = await db.queryCausal(contextEmbedding, 10);

results.forEach(result => {
    console.log(`${result.edge.causes.join(', ')} → ${result.edge.effects.join(', ')}`);
    console.log(`Confidence: ${result.edge.confidence}`);
    console.log(`Utility: ${result.utilityScore.toFixed(4)}`);
});

Learning Sessions

createLearningSession

async createLearningSession(
    algorithm: string,
    stateDim: number,
    actionDim: number
): Promise<string>

Create RL training session.

Parameters:

algorithm: RL algorithm (Q-Learning, DQN, PPO, etc.)
stateDim: State dimensionality
actionDim: Action dimensionality

Returns: Session ID

Example:

const sessionId = await db.createLearningSession('PPO', 64, 4);

addExperience

async addExperience(
    sessionId: string,
    state: Float32Array,
    action: Float32Array,
    reward: number,
    nextState: Float32Array,
    done: boolean
): Promise<void>

Add experience to session.

Example:

await db.addExperience(
    sessionId,
    state,
    action,
    1.0,      // reward
    nextState,
    false     // not done
);

predictWithConfidence

async predictWithConfidence(
    sessionId: string,
    state: Float32Array
): Promise<Prediction>

Predict action with confidence intervals.

Returns:

interface Prediction {
    action: Float32Array;
    confidenceLower: number;
    confidenceUpper: number;
    meanConfidence: number;
}

Example:

const prediction = await db.predictWithConfidence(sessionId, state);

console.log('Action:', Array.from(prediction.action));
console.log(`Confidence: [${prediction.confidenceLower.toFixed(2)}, ${prediction.confidenceUpper.toFixed(2)}]`);

Types

VectorEntry

interface VectorEntry {
    id?: string;
    vector: Float32Array;
    metadata?: Record<string, any>;
}

SearchQuery

interface SearchQuery {
    vector: Float32Array;
    k: number;
    filter?: any;
    includeVectors?: boolean;
    includeMetadata?: boolean;
}

SearchResult

interface SearchResult {
    id: string;
    distance: number;
    vector?: Float32Array;
    metadata?: Record<string, any>;
}

ReflexionEpisode

interface ReflexionEpisode {
    id: string;
    task: string;
    actions: string[];
    observations: string[];
    critique: string;
    embedding: Float32Array;
    timestamp: number;
    metadata?: Record<string, any>;
}

Skill

interface Skill {
    id: string;
    name: string;
    description: string;
    parameters: Record<string, string>;
    examples: string[];
    embedding: Float32Array;
    usageCount: number;
    successRate: number;
    createdAt: number;
    updatedAt: number;
}

CausalEdge

interface CausalEdge {
    id: string;
    causes: string[];
    effects: string[];
    confidence: number;
    context: string;
    embedding: Float32Array;
    observations: number;
    timestamp: number;
}

Configuration

DbOptions

interface DbOptions {
    dimensions: number;
    storagePath: string;
    distanceMetric?: 'euclidean' | 'cosine' | 'dotProduct' | 'manhattan';
    hnsw?: HnswConfig;
    quantization?: QuantizationConfig;
    mmapVectors?: boolean;
}

HnswConfig

interface HnswConfig {
    m?: number;              // 16-64, default 32
    efConstruction?: number; // 100-400, default 200
    efSearch?: number;       // 50-500, default 100
    maxElements?: number;    // default 10_000_000
}

QuantizationConfig

interface QuantizationConfig {
    type: 'none' | 'scalar' | 'product' | 'binary';
    subspaces?: number;  // For product quantization
    k?: number;          // For product quantization
}

Advanced Features

HybridSearch

const { HybridSearch } = require('ruvector');

const hybrid = new HybridSearch(db, {
    vectorWeight: 0.7,
    bm25Weight: 0.3,
    k1: 1.5,
    b: 0.75
});

const results = await hybrid.search(
    queryVector,
    ['machine', 'learning'],
    10
);

FilteredSearch

const { FilteredSearch } = require('ruvector');

const filtered = new FilteredSearch(db, 'preFilter');

const results = await filtered.search(queryVector, 10, {
    and: [
        { field: 'category', op: 'eq', value: 'tech' },
        { field: 'score', op: 'gte', value: 0.8 }
    ]
});

MMRSearch

const { MMRSearch } = require('ruvector');

const mmr = new MMRSearch(db, {
    lambda: 0.5,
    diversityWeight: 0.3
});

const results = await mmr.search(queryVector, 20);

Error Handling

All async operations throw errors on failure:

try {
    const id = await db.insert(entry);
    console.log('Success:', id);
} catch (error) {
    if (error.message.includes('dimension mismatch')) {
        console.error('Wrong vector dimensions');
    } else {
        console.error('Error:', error.message);
    }
}

TypeScript Support

Full TypeScript type definitions included:

import { VectorDB, VectorEntry, SearchResult } from 'ruvector';

const db = new VectorDB({
    dimensions: 128,
    storagePath: './vectors.db'
});

const entry: VectorEntry = {
    vector: new Float32Array(128),
    metadata: { text: 'Example' }
};

const id: string = await db.insert(entry);
const results: SearchResult[] = await db.search({
    vector: new Float32Array(128),
    k: 10
});

Complete Examples

See examples/nodejs/ for complete working examples.

FilesExpand file tree

NODEJS_API.md

Latest commit

History

NODEJS_API.md

File metadata and controls

Ruvector Node.js API Reference

Installation

Table of Contents

VectorDB

Constructor

insert

insertBatch

search

delete

update

count

AgenticDB

Constructor

Reflexion Memory

storeEpisode

retrieveEpisodes

Skill Library

createSkill

searchSkills

Causal Memory

addCausalEdge

queryCausal

Learning Sessions

createLearningSession

addExperience

predictWithConfidence

Types

VectorEntry

SearchQuery

SearchResult

ReflexionEpisode

Skill

CausalEdge

Configuration

DbOptions

HnswConfig

QuantizationConfig

Advanced Features

HybridSearch

FilteredSearch

MMRSearch

Error Handling

TypeScript Support

Complete Examples