spheni

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #claude-code #codex #cli #developer-tools #react #windows

★ 188 Open GitHub ↗

Lightweight Vector Search Library focused on Memory Efficiency

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h2 align="center">Spheni</h2>

<p align="center">
  A lightweight vector search library focused on <b>memory-efficient</b> approximate nearest neighbor search.
</p>

## Index

1. [Overview](#overview)
2. [Features](#features)
3. [Getting Started](#getting-started)
4. [API Reference](#api-reference)
5. [Benchmarks](#benchmarks)
6. [Roadmap](#roadmap)
7. [References](#references)

## Overview

The goal of Spheni is to be **focused on memory efficiency** rather than accuracy, and act a candidate generation system.

It implements *inverted indexing* and *product quantization* with *residual encoding* to reduce memory usage while supporting fast similarity search.

With [**Cohere 1M Embeddings**](https://huggingface.co/datasets/makneeee/cohere_medium_1m), the current benchmark reports up to **213.9x** compression (**13.69 MB** index at M=8) and up to **94.20% Recall@10-in-100** (M=64, nprobe=32), with the baseline at **80.1x** compression and **83.25% Recall@10-in-100** (M=32, nprobe=32).

## Features

- **Indexes**: Flat, IVF, FlatPQ, IVF-PQ
- **Metrics**: Cosine similarity, L2 distance
- **Operations**: `train`, `add`, `search`

## Getting Started

### Build

Requirements:

- CMake >= 3.15
- A C++20 compiler (GCC/Clang)

Quick build

```bash
chmod +x build.sh
./build.sh
```

After building, this repository produces `build/libspheni.a`. You only need the public header (`include/spheni.h`) and the static library (`libspheni.a`) to consume Spheni in another project.

Usage

```bash
g++ -std=c++20 -O3 main.cpp -I /path/to/spheni/include /path/to/libspheni.a -o main
```

### Example

Check out `examples/` folder for more.

```cpp
#include "spheni.h"
#include <iostream>

int main() {
        // define
        spheni::IVFSpec spec{{3, spheni::Metric::Cosine, true}, 2, 1};
        spheni::IVFIndex index(spec);

long long ids[] = {0, 1, 2};
        float vecs[] = {
            1.0f, 0.0f, 0.0f, 0.0f, 1.0f, 0.0f, 1.0f, 1.0f, 0.0f,
        };
        // train
        index.train(ids, vecs);

float query[] = {1.0f, 0.2f, 0.0f};
        // search
        auto hits = index.search(query, 3);

for (const auto &h : hits) {
                std::cout << h.id << " " << h.score << "\n";
        }
        return 0;
}
```

## API Reference

Detailed public API documentation is available in [docs/api-reference.md](docs/api-reference.md).

## Benchmarks

[Current Benchmark Report](docs/benchmark.md) (single-core run, 200 queries, Recall@k-in-100).  
[Legacy Report](docs/legacy/benchmarks/benchmarks.md) is also available.

## Roadmap

- [ ] Implement `save`/`load` for seralized data
- [ ] Implement multithreading with OpenMP wherever applicable
- [ ] Implement OPQ (tough for me)
- [ ] SIMD vectorizations

## References

**Papers**

1. FAISS: [ArXiv Paper](https://arxiv.org/pdf/2401.08281)
2. [Near Neighbor Search in Large Metric Spaces](https://vldb.org/conf/1995/P574.PDF)
3. [The Binary Vector as the Basis of an Inverted Index File](https://ital.corejournals.org/index.php/ital/article/view/8961/8080)
4. [Product Quantization for Nearest Neighbour Search](https://inria.hal.science/inria-00514462v2/document)

**Blogs**

1. [A Bhayani - Product Quantization](https://arpitbhayani.me/blogs/product-quantization/)
2. [W Lin - Building a high recall vector database serving 1 billion embeddings from a single machine](https://blog.wilsonl.in/corenn/#product-quantization)

spheni

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README