bare-usearch

Native USearch bindings for Bare.

Fast approximate nearest neighbor search for high-dimensional vectors.

Requirements

• CMake 3.25+
• C/C++ compiler (clang, gcc, or MSVC)
• Node.js (for npm/cmake-bare)
• Bare runtime

Building

Clone with submodules:

git clone --recursive https://github.com/user/bare-usearch
cd bare-usearch

Or if already cloned:

git submodule update --init --recursive

Install dependencies and build:

npm install
npm run prebuild

Or manually:

bare-make generate
bare-make build
bare-make install

Usage

const { Index } = require('bare-usearch')

// Create index with 128-dimensional vectors
const index = new Index({
  dimensions: 128,
  metric: 'cos'  // cosine similarity
})

// Add vectors (key, vector)
index.add(1, new Float32Array([0.1, 0.2, ...]))
index.add(2, new Float32Array([0.3, 0.4, ...]))

// Search for k nearest neighbors
const results = index.search(queryVector, 10)
console.log(results.keys)       // [2, 1, ...]
console.log(results.distances)  // Float32Array

// Persistence
index.save('index.usearch')
index.load('index.usearch')

// Cleanup
index.free()

See examples/ for more:

• basic.js - Basic usage with add/search/remove
• persistence.js - Saving and loading indexes

Run examples with:

bare examples/basic.js

API Reference

Index

new Index(options?)

Option	Type	Default	Description
dimensions	number	required	Vector dimensionality
metric	string	'cos'	Distance metric
quantization	string	'f32'	Scalar quantization
connectivity	number	auto	Graph connectivity (M)
multi	boolean	false	Allow multiple vectors per key

Metrics: 'cos', 'ip' (inner product), 'l2' (L2 squared), 'hamming', 'jaccard'

Quantization: 'f32', 'f16', 'i8'

Properties:

• size - Number of vectors in index
• dimensions - Vector dimensionality
• capacity - Current capacity

Methods:

• add(key, vector) - Add a vector with numeric key
• search(query, k) - Find k nearest neighbors, returns { keys, distances, count }
• remove(key) - Remove vector by key
• contains(key) - Check if key exists
• get(key) - Retrieve vector by key (returns Float32Array or null)
• reserve(capacity) - Pre-allocate space for vectors
• save(path) - Save index to file
• load(path) - Load index from file
• view(path) - Memory-map index from file (read-only)
• clear() - Remove all vectors
• free() - Release resources

Platform Support

Platform	Architecture
macOS	arm64, x64
Linux	x64, arm64
Windows	x64

License

MIT