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/CameronTofer/bare-usearch
cd bare-usearch

Or if already cloned:

git submodule update --init --recursive

Install dependencies and build:

npm install
npm run build

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
• topics.js - Topic extraction using vector similarity

Run examples with:

bare examples/basic.js

Testing

npm test            # bare
npm run test:node   # node

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, arm64 | | Android | arm64, arm, x64, ia32 | | iOS | arm64, x64 (simulator) |

License

MIT