wifi-densepose/vendor/ruvector/npm/packages/rvlite/README.md

RvLite

Lightweight vector database with SQL, SPARQL, and Cypher - runs everywhere (Node.js, Browser, Edge).

Built on WebAssembly for maximum performance and portability. Only ~850KB!

Features

• Vector Search - Semantic similarity with cosine, euclidean, or dot product distance
• SQL - Query vectors with standard SQL plus distance operations
• Cypher - Property graph queries (Neo4j-compatible syntax)
• SPARQL - RDF triple store with W3C SPARQL queries
• Persistence - Save/load to file (Node.js) or IndexedDB (browser)
• Tiny - ~850KB WASM bundle, no external dependencies

Installation

npm install rvlite

CLI Usage

# Initialize a new database
npx rvlite init

# Insert a vector
npx rvlite insert "[0.1, 0.2, 0.3, ...]" --metadata '{"text": "Hello"}'

# Search for similar vectors
npx rvlite search "[0.1, 0.2, 0.3, ...]" --top 5

# SQL queries
npx rvlite sql "SELECT * FROM vectors LIMIT 10"

# Cypher queries
npx rvlite cypher "CREATE (p:Person {name: 'Alice'})"
npx rvlite cypher "MATCH (p:Person) RETURN p"

# SPARQL queries
npx rvlite triple "http://example.org/alice" "http://xmlns.com/foaf/0.1/name" "Alice"
npx rvlite sparql "SELECT ?s ?p ?o WHERE { ?s ?p ?o }"

# Interactive REPL
npx rvlite repl

# Database stats
npx rvlite stats

# Export/Import
npx rvlite export backup.json
npx rvlite import backup.json

REPL Commands

.sql      - Switch to SQL mode
.cypher   - Switch to Cypher mode
.sparql   - Switch to SPARQL mode
.stats    - Show database statistics
.save     - Save database
.exit     - Exit REPL

SDK Usage

Basic Vector Operations

import { RvLite, createRvLite } from 'rvlite';

// Create instance
const db = await createRvLite({ dimensions: 384 });

// Insert vectors
const id = await db.insert([0.1, 0.2, 0.3, ...], { text: "Hello world" });

// Insert with custom ID
await db.insertWithId("my-doc-1", [0.1, 0.2, ...], { source: "article" });

// Search similar
const results = await db.search([0.1, 0.2, ...], 5);
// [{ id: "...", score: 0.95, metadata: {...} }, ...]

// Get by ID
const item = await db.get("my-doc-1");

// Delete
await db.delete("my-doc-1");

SQL Queries

// Create table and insert
await db.sql("CREATE TABLE documents (id TEXT, title TEXT, embedding VECTOR)");
await db.sql("INSERT INTO documents VALUES ('doc1', 'Hello', '[0.1, 0.2, ...]')");

// Query with vector distance
const results = await db.sql(`
  SELECT id, title, distance(embedding, '[0.1, 0.2, ...]') as dist
  FROM documents
  WHERE dist < 0.5
  ORDER BY dist
`);

Cypher Graph Queries

// Create nodes
await db.cypher("CREATE (alice:Person {name: 'Alice', age: 30})");
await db.cypher("CREATE (bob:Person {name: 'Bob', age: 25})");

// Create relationships
await db.cypher(`
  MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
  CREATE (a)-[:KNOWS {since: 2020}]->(b)
`);

// Query
const friends = await db.cypher(`
  MATCH (p:Person)-[:KNOWS]->(friend:Person)
  WHERE p.name = 'Alice'
  RETURN friend.name
`);

SPARQL RDF Queries

// Add triples
await db.addTriple(
  "http://example.org/alice",
  "http://xmlns.com/foaf/0.1/name",
  "Alice"
);

await db.addTriple(
  "http://example.org/alice",
  "http://xmlns.com/foaf/0.1/knows",
  "http://example.org/bob"
);

// Query
const results = await db.sparql(`
  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
  SELECT ?name WHERE {
    <http://example.org/alice> foaf:name ?name
  }
`);

Persistence

// Node.js - Export to file
const state = await db.exportJson();
fs.writeFileSync('db.json', JSON.stringify(state));

// Node.js - Import from file
const data = JSON.parse(fs.readFileSync('db.json'));
await db.importJson(data);

// Browser - Save to IndexedDB
await db.save();

// Browser - Load from IndexedDB
const db = await RvLite.load({ dimensions: 384 });

// Browser - Clear storage
await RvLite.clearStorage();

Semantic Memory for AI

import { RvLite, SemanticMemory, createRvLite } from 'rvlite';

// Create with embedding provider
const db = await createRvLite({ dimensions: 1536 });
const memory = new SemanticMemory(db);

// Store memories with embeddings
await memory.store("conv-1", "User asked about weather", embedding1);
await memory.store("conv-2", "Discussed travel plans", embedding2);

// Add relationships
await memory.addRelation("conv-1", "LEADS_TO", "conv-2");

// Query by similarity
const similar = await memory.query("What was the weather question?", queryEmbedding);

// Find related through graph
const related = await memory.findRelated("conv-1", 2);

RVF Storage Backend

RvLite can use RVF (RuVector Format) as a persistent storage backend. When the optional @ruvector/rvf-wasm package is installed, rvlite gains file-backed persistence using the .rvf cognitive container format.

Install

npm install rvlite @ruvector/rvf-wasm

Usage

import { createRvLite } from 'rvlite';

// rvlite auto-detects @ruvector/rvf-wasm when installed
const db = await createRvLite({ dimensions: 384 });

// All operations persist to RVF format
await db.insert([0.1, 0.2, ...], { text: "Hello world" });
const results = await db.search([0.1, 0.2, ...], 5);

Platform Support

The RVF backend works everywhere rvlite runs:

Platform	RVF Backend	Notes
Node.js (Linux, macOS, Windows)	Native or WASM	Auto-detected
Browser (Chrome, Firefox, Safari)	WASM	IndexedDB + RVF
Deno	WASM	Via npm: specifier
Cloudflare Workers / Edge	WASM	Stateless queries

Rust Feature Flag

If building from source, enable the rvf-backend feature in crates/rvlite:

[dependencies]
rvlite = { version = "0.1", features = ["rvf-backend"] }

This enables epoch-based reconciliation between RVF and metadata stores:

• Monotonic epoch counter shared between RVF and metadata
• On startup, compares epochs and rebuilds the lagging side
• RVF file is source of truth; metadata (IndexedDB) is rebuildable cache

Download Example .rvf Files

# Download pre-built examples to test with
curl -LO https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output/basic_store.rvf
curl -LO https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output/semantic_search.rvf
curl -LO https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output/agent_memory.rvf

# 45 examples available at:
# https://github.com/ruvnet/ruvector/tree/main/examples/rvf/output

---

Integration with claude-flow

RvLite can enhance claude-flow's memory system with semantic search:

import { RvLite, SemanticMemory } from 'rvlite';

// In your claude-flow hooks
const db = await createRvLite({ dimensions: 1536 });

// Pre-task hook: Find relevant context
async function preTask(task) {
  const embedding = await getEmbedding(task.description);
  const context = await db.search(embedding, 5);
  return { ...task, context };
}

// Post-task hook: Store results
async function postTask(task, result) {
  const embedding = await getEmbedding(result.summary);
  await db.insert(embedding, {
    task: task.id,
    result: result.summary,
    timestamp: Date.now()
  });
}

API Reference

RvLite Class

Method	Description
insert(vector, metadata?)	Insert vector, returns ID
insertWithId(id, vector, metadata?)	Insert with custom ID
search(query, k)	Find k nearest vectors
get(id)	Get vector by ID
delete(id)	Delete vector by ID
len()	Count of vectors
sql(query)	Execute SQL query
cypher(query)	Execute Cypher query
cypherStats()	Get graph statistics
sparql(query)	Execute SPARQL query
addTriple(s, p, o, graph?)	Add RDF triple
tripleCount()	Count of triples
exportJson()	Export state to JSON
importJson(data)	Import state from JSON
save()	Save to IndexedDB (browser)
RvLite.load(config)	Load from IndexedDB
RvLite.clearStorage()	Clear IndexedDB

CLI Commands

Command	Description
rvlite init	Initialize database
rvlite insert <vector>	Insert vector
rvlite search <vector>	Search similar
rvlite sql <query>	Execute SQL
rvlite cypher <query>	Execute Cypher
rvlite sparql <query>	Execute SPARQL
rvlite triple <s> <p> <o>	Add triple
rvlite stats	Show statistics
rvlite export <file>	Export to JSON
rvlite import <file>	Import from JSON
rvlite repl	Start interactive mode

License

MIT OR Apache-2.0