compass

KO | EN

gitlite — search

#swift #cross-platform #rag #terminal #csharp #ui #gemini #claude #go #html

(★ 9)

Compass; high-performance vector + FTS engine in Rust

File Explorer

ZIP Download

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - cfn-publish.yml
  - ci.yml
  - docker.yml
  - release.yml
- CODEOWNERS
- FUNDING.yml
- PULL_REQUEST_TEMPLATE.md
- - Cargo.toml
- - Cargo.toml
- - Cargo.toml
- - compass-quickstart.yaml
- README.md
- compass-logo.svg
- deployment.md
- scale-envelope.md
- search-quality.md
- serverless-roadmap.md
- v0.4-filter-aware-ann.md
- - compass_client.py
- download-models.sh
- e2e.sh
.dockerignore
.env.example
.gitignore
ARCHITECTURE.md
audit.toml
Cargo.lock
Cargo.toml
CHANGELOG.md
CLAUDE.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
docker-compose.minio.yml
docker-compose.yml
Dockerfile
Dockerfile.gpu
LICENSE
README.md
rust-toolchain.toml
SECURITY.md

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <a href="https://runcaptain.com">
    <img src="https://files.buildwithfern.com/runcaptain.docs.buildwithfern.com/7bb93ea0ee016bc6af0af57fa0f197f331125faa2c217c1af23b63789952e295/docs/assets/Captain-Wordmark.svg" height="40" alt="Captain" />
  </a>
  <br><br>
  <img src="docs/compass-logo.svg" height="80" alt="Compass" />
  <h1>Compass</h1>
  <p>Embedded vector + full-text search engine. Single binary, zero external dependencies.</p>

[![CI](https://github.com/runcaptain/compass/actions/workflows/ci.yml/badge.svg)](https://github.com/runcaptain/compass/actions/workflows/ci.yml)
  [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://raw.githubusercontent.com/runcaptain/compass/main/LICENSE)
  [![Rust](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org)
  [![Image](https://img.shields.io/badge/ghcr.io-runcaptain%2Fcompass-2496ED?logo=docker&logoColor=white)](https://github.com/runcaptain/compass/pkgs/container/compass)
  [![Deploy](https://img.shields.io/badge/%E2%98%81%20one--command%20deploy-Kubernetes%20%2F%20AWS-326CE5?logo=kubernetes&logoColor=white)](https://raw.githubusercontent.com/runcaptain/compass/main/)
  <br>
  <a href="https://console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/quickcreate?stackName=compass&templateURL=https://runcaptain-compass-cloudformation.s3.amazonaws.com/compass-quickstart.yaml"><img src="https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png" alt="Launch Stack on AWS"></a>
</div>

Built by [Captain](https://runcaptain.com) for high-throughput retrieval in on-prem enterprise deployments where customer data cannot leave their VPC.

## What it does

- **Full-text search** via Tantivy (BM25) with precomputed bitset faceting (microsecond facets)
- **Vector search** via USearch HNSW (mmap-backed, disk-persistent)
- **Hybrid search** via Reciprocal Rank Fusion (RRF, k=60)
- **Filter-aware ANN with `/explain`**. Metadata filters are pushed into the HNSW walk via roaring-bitmap masks, so filtered semantic queries stay fast and recall-accurate instead of over-fetching and discarding. Set `"explain": true` to get the query plan back: filter selectivity, ANN engine, candidates inspected, and the effective `ef_search`.
- **Memory-mapped vector storage**. Raw vectors live on disk, not in RAM. Zero-copy reads via mmap.
- **Disk-backed chunk metadata** via redb (pure Rust embedded DB). Handles millions of documents without loading them all into memory.
- **Incremental HNSW indexing**. Adding vectors appends to the index — no full rebuild required.
- **Named vector spaces** ... run multiple embedding models on the same collection
- **One-click model upgrades** with background re-embedding and atomic swap
- **Parent-child documents** with relationship-aware scoring (TAMS video search compatible)
- **Typed chunk relations**: directed, labeled, many-to-many edges between chunks (`cites`, `supersedes`, anything) — disk-backed, queryable per chunk, returnable inline with search results
- **Deletes**: soft-delete by id or metadata filter (tombstones — instant disappearance from results), with compaction to reclaim space
- **Query-time scoring**: recency decay, metadata boosting, relationship boosting
- **Metadata filtering**: exact match, numeric range (gte/lte), array contains, set membership. Typed values (string, int, float, bool, timestamp, string list)
- **Native query embedding** via Candle BGE-small (Rust, no Python). GPU endpoint support for larger models.
- **Fully offline**. No API calls. Model weights on disk. Data never leaves the machine.
- **Optional object-storage persistence** (`--features object-storage`): point `COMPASS_STORAGE` at S3/GCS/Azure/MinIO/R2 and the bucket becomes the source of truth — an ephemeral container that loses its disk recovers every collection (chunks, hierarchy, relations) from the bucket on boot. Local disk stays the zero-config default.

## Quick start

```bash
cargo build --release
./target/release/compass
```

Or skip the build entirely: `docker run -p 4001:4001 ghcr.io/runcaptain/compass:latest`
— and for the full serverless topology on a Kubernetes cluster, see
[Deploy to Kubernetes / AWS](#deploy-to-kubernetes--aws-one-command) (one command, no clone).

Environment variables: `PORT` (default 4001), `DATA_DIR` (default ./data), `COMPASS_API_KEY` (bearer-token auth; unauthenticated when unset), `COMPASS_STORAGE` (see [Object storage](#object-storage-s3--gcs--azure)). See [`.env.example`](.env.example) for the full list.

## Examples

### Basic: create, ingest, search

```bash
# Create a collection
curl -X POST localhost:4001/collections \
  -H 'Content-Type: application/json' \
  -d '{"name": "docs"}'

# Ingest chunks
curl -X POST localhost:4001/collections/docs/ingest \
  -H 'Content-Type: application/json' \
  -d '{"chunks": [{"file_id": "readme", "chunk_index": 0, "text": "Compass is a search engine"}]}'

# Search
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "search engine", "mode": "hybrid"}'
```

### Named vector spaces

Create a collection with two embedding models (text + multimodal):

```bash
curl -X POST localhost:4001/collections \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "media",
    "vector_spaces": {
      "qwen3": {"dims": 1024, "model": "Qwen/Qwen3-Embedding-8B", "status": "active"},
      "qwen3-vl": {"dims": 896, "model": "Qwen/Qwen3-VL-Embedding-2B", "status": "active"}
    }
  }'

# Search a specific vector space
curl -X POST localhost:4001/collections/media/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "sunset over ocean", "mode": "semantic", "vector_space": "qwen3-vl"}'
```

### Multi-space retrieval + reranking

Embed every document into multiple vector spaces at ingest time. At query time, search one space, multiple spaces, or all of them. A cross-encoder reranker re-scores the merged candidates for maximum accuracy.

```
Query
  |
  +-- Tantivy BM25 -----------> FTS candidates
  +-- Harrier HNSW -----------> text semantic candidates
  +-- Qwen3-VL HNSW ----------> multimodal candidates
  |
  v
  RRF merge (all three)
  |
  v
  Reranker (cross-encoder re-scores top candidates)
  |
  v
  Filter -> Score (recency, boost, relationships)
  |
  v
  Return top_k
```

Pick the right retrieval path for the query:

- **Text query, text docs:** search `harrier` space only
- **Text query, find images/video:** search `qwen3-vl` space (cross-modal)
- **Mixed collection, best accuracy:** search both spaces, RRF merge, rerank

```bash
# Search multiple vector spaces at once (merged via RRF, then reranked)
curl -X POST localhost:4001/collections/media/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "goal celebration slow motion",
    "mode": "hybrid",
    "vector_space": ["harrier", "qwen3-vl"],
    "top_k": 10
  }'
```

Three retrievers, one reranker, one scoring pipeline. The reranker doesn't care which retriever found the candidate. It just scores (query, text) relevance from scratch.

### Recency bias + metadata boosting

Pick a preset to favor newer results. Older docs score lower but never disappear:

```bash
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "quarterly report",
    "recency_preset": "mild",
    "recency_field": "created_at",
    "boosts": [
      {"field": "department", "value": "Legal", "weight": 2.0},
      {"field": "priority", "gte": 3, "weight": 1.5}
    ]
  }'
```

Four presets. How quickly old docs lose ranking:

```
  strong bias ◄───────────────► weak bias

aggressive    recent     mild       archive
  ├── 3d ──┤  ├── 7d ──┤  ├── 30d ──┤  ├── 90d ──┤
```

| Use case                                     | Preset       | Docs lose half their recency score after... | Old docs bottom out at... |
| -------------------------------------------- | ------------ | ------------------------------------------- | ------------------------- |
| Real-time alerts, live events, TAMS segments | `aggressive` | 3 days                                      | 5%                        |
| News, feeds, support tickets                 | `recent`     | 7 days                                      | 20%                       |
| Docs, reports, meeting notes                 | `mild`       | 30 days                                     | 30%                       |
| Long-lived content, legal docs, compliance   | `archive`    | 90 days                                     | 50%                       |

For full control, use `recency` instead (overrides any preset):

```bash
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "quarterly report",
    "recency": {"field": "created_at", "half_life_days": 30, "min_score": 0.1}
  }'
```

Recency decay formula: `score *= max(min_score, 2^(-age_days / half_life_days))`. A 30-day-old doc scores 0.5x with the default. The `field` is always user-controlled. Compass never assumes which metadata field represents "time".

### Metadata filtering

Filters are hard constraints applied before scoring. Only matching documents are scored and returned.

```bash
# Exact match (string, bool, number)
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "compliance",
    "filters": {"department": "Legal", "active": true}
  }'

# Numeric range (gte/lte)
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "quarterly report",
    "filters": {"priority": {"gte": 3, "lte": 10}}
  }'

# Array contains
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "highlights",
    "filters": {"tags": {"contains": "sports"}}
  }'

# Set membership (doc_type, category, etc.)
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "meeting notes",
    "filters": {"doc_type": {"in": ["segment", "flow"]}}
  }'
```

All operators: exact match (backward compatible), `gte`/`lte` (numeric range), `contains` (array membership), `in` (set membership). Operators combine as AND across fields.

### Filter-aware ANN + query explain

When a semantic or hybrid query carries filters, Compass pushes the filter into the HNSW walk itself via a roaring-bitmap mask, rather than over-fetching neighbors and discarding the ones that fail the filter. Filtered vector search stays fast and keeps recall high even at low selectivity.

Set `"explain": true` to get the query plan alongside the results:

```bash
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "quarterly revenue",
    "mode": "semantic",
    "filters": {"department": "Finance", "priority": {"gte": 3}},
    "explain": true
  }'
```

The response adds an `explain` object:

```json
{
  "explain": {
    "filter": { "eligible_count": 1842, "universe_count": 50000, "selectivity": 0.0368 },
    "ann":    { "engine": "hnsw", "candidates_inspected": 5120, "ef_search_used": 128 }
  }
}
```

`engine` is `"hnsw"` when the filter-aware walk ran, or `"brute_force"` for the exhaustive fallback at very low selectivity. Use the plan to see why a query was fast or slow without guessing.

### Parent-child documents + relationship boost

Ingest a document hierarchy using `client_id` and `parent_ref` to link chunks within a single batch:

```bash
curl -X POST localhost:4001/collections/media/ingest \
  -H 'Content-Type: application/json' \
  -d '{
    "chunks": [
      {
        "client_id": "src-001",
        "file_id": "video-001",
        "chunk_index": 0,
        "doc_type": "source",
        "text": "Premier League: Arsenal vs Chelsea",
        "metadata": {"asset_type": "video", "created_at": "2026-03-15T15:00:00Z"}
      },
      {
        "client_id": "seg-001",
        "file_id": "segment-001",
        "chunk_index": 0,
        "doc_type": "segment",
        "parent_ref": "src-001",
        "group_id": "src-001",
        "text": "Goal celebration, minute 34",
        "metadata": {"timerange_start_ms": 2040000, "timerange_end_ms": 2055000, "scene_type": "goal"}
      }
    ]
  }'
```

Then search with relationship boosting. Segments whose parent also matches the query get a score boost:

```bash
curl -X POST localhost:4001/collections/media/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "goal celebration",
    "relationship_boost": {"parent_weight": 0.3, "sibling_weight": 0.1, "mode": "max"}
  }'
```

### TAMS time-range search

[TAMS](https://github.com/bbc/tams) (Time-Addressable Media Store) is BBC R&D's open spec for media archives. Media is addressed by time, not by file. The data model: **Source** (logical content) → **Flow** (specific rendition) → **Segment** (time-bounded chunk with `timerange_start_ms`/`timerange_end_ms`).

Compass models this hierarchy via `doc_type` + `parent_id` + `group_id`. Time is stored as integer milliseconds throughout: `timerange_start_ms` and `timerange_end_ms` are numeric metadata fields. Instants (zero-duration events) are stored as segments where `timerange_start_ms == timerange_end_ms`.

Ingest segments with time range metadata, then query by content and time:

```bash
curl -X POST localhost:4001/collections/media/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "goal celebration",
    "filters": {
      "doc_type": {"in": ["segment"]},
      "timerange_start_ms": {"gte": 2040000},
      "timerange_end_ms": {"lte": 2100000}
    },
    "relationship_boost": {"parent_weight": 0.3, "sibling_weight": 0.1}
  }'
```

This finds segments matching "goal celebration" within the 2040000-2100000 ms window (33:60 → 35:00 in HH:MM:SS). Relationship boosting surfaces sibling segments and the parent flow alongside the match.

### Typed chunk relations

Beyond the parent/group hierarchy, chunks can be linked with directed, labeled, many-to-many edges:

```bash
# Create relations (server mints relation_ids)
curl -X POST localhost:4001/collections/docs/relations \
  -H 'Content-Type: application/json' \
  -d '{
    "relations": [
      {"source_chunk_id": 12, "target_chunk_id": 40, "relation_type": "cites"},
      {"source_chunk_id": 12, "target_chunk_id": 41, "relation_type": "supersedes"}
    ]
  }'

# List a chunk's relations (direction: outgoing|incoming|both; optional type filter)
curl 'localhost:4001/collections/docs/chunks/12/relations?direction=both&types=cites'

# Delete an edge
curl -X DELETE localhost:4001/collections/docs/relations/{relation_id}

# Return relations inline with search hits
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{"query": "contract", "include_relations": true, "relation_direction": "outgoing"}'
```

Each edge carries a `target_status` (`"found"` / `"missing"`) resolved against the live chunk set, so dangling references are visible, never silent.

### Deleting chunks

Deletes are soft (tombstones): the chunk disappears from search results immediately; physical removal happens at the next compaction/rebuild.

```bash
# Delete one chunk
curl -X DELETE localhost:4001/collections/docs/chunks/42

# Delete by ids and/or metadata filter
curl -X POST localhost:4001/collections/docs/delete \
  -H 'Content-Type: application/json' \
  -d '{"ids": [1, 2], "filters": {"file_id": "old-report"}}'

# Reclaim space (object-storage mode; folds the WAL + segments, drops tombstoned data)
curl -X POST localhost:4001/collections/docs/compact
```

### Hybrid score weights

Control how FTS and semantic scores blend in hybrid mode. Useful when one signal matters more for your use case:

```bash
curl -X POST localhost:4001/collections/docs/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "quarterly earnings",
    "mode": "hybrid",
    "score_weights": {"rrf_k": 60.0, "fts_weight": 2.0, "semantic_weight": 0.5}
  }'
```

`rrf_k` is the RRF constant (default 60). Lower values amplify top-rank differences. `fts_weight` and `semantic_weight` control relative contribution (default 1.0 each). Set `fts_weight: 2.0` to favor keyword matches, or `semantic_weight: 2.0` when meaning matters more than exact terms.

### Facets

```bash
# Get facet counts for all metadata fields
curl 'localhost:4001/collections/docs/facets'

# Facet counts scoped to a text query
curl 'localhost:4001/collections/docs/facets?query=compliance'
```

### One-click model upgrade

```bash
# 1. Add a new vector space
curl -X POST localhost:4001/collections/docs/vector-spaces \
  -H 'Content-Type: application/json' \
  -d '{"name": "qwen3", "dims": 1024, "model": "Qwen/Qwen3-Embedding-8B"}'

# 2. Trigger re-embedding (uses external GPU endpoint for speed)
curl -X POST localhost:4001/collections/docs/vector-spaces/qwen3/rebuild \
  -H 'Content-Type: application/json' \
  -d '{"embed_endpoint": "http://gpu-server:8080/embed"}'

# 3. Check progress
curl localhost:4001/collections/docs/vector-spaces/qwen3/status

# 4. Swap the default (zero downtime, old space stays for rollback)
curl -X PUT localhost:4001/collections/docs/default-vector-space \
  -H 'Content-Type: application/json' \
  -d '{"name": "qwen3"}'

# 5. (Optional) Delete old space when you're confident
curl -X DELETE localhost:4001/collections/docs/vector-spaces/default
```

## Docker

```bash
docker build -t compass .
docker run -p 4001:4001 -v ./data:/app/data compass
```

## Deploy to Kubernetes / AWS (one command)

**AWS, zero tools installed** — the Launch Stack button opens the AWS console
with everything pre-filled; one Create click gives you a running serverless
Compass (Fargate task + private encrypted S3 bucket + least-privilege IAM,
no long-lived keys — the task role is picked up automatically):

The bucket is retained when the stack is deleted — your data outlives the
compute, always. Template source: [`deploy/cloudformation/compass-quickstart.yaml`](deploy/cloudformation/compass-quickstart.yaml).

**Kubernetes** — one command deploys the full multi-node topology — serving
nodes on persistent volumes, stateless writers, an optional cold tier, and a
bundled dev S3 — onto **any** cluster, no clone required:

```bash
kubectl apply -k "https://github.com/runcaptain/compass//deploy/kubernetes/overlays/minio-dev?ref=main"
kubectl -n compass-dev get pods   # serving-0, writer, cold, minio
```

Production on AWS is two steps: `terraform apply` in
[`deploy/terraform/aws`](deploy/terraform/aws) (private encrypted S3 bucket +
least-privilege IAM, IRSA-ready), then point
[`deploy/kubernetes/overlays/aws`](deploy/kubernetes/overlays/aws) at the
bucket and `kubectl apply -k` it. Full walkthrough and operational notes:
[deploy/README.md](deploy/README.md).

## Object storage (S3 / GCS / Azure)

By default Compass persists to local disk — zero config, no credentials. Optionally, it can persist to your own cloud object storage instead (a hard either/or, chosen at startup):

```bash
# Build with the object-storage backend (off by default; local builds stay lean)
cargo build --release --features object-storage

# Point at a bucket; credentials come from the standard provider env vars
COMPASS_STORAGE=s3://my-bucket/my-prefix \
AWS_ACCESS_KEY_ID=… AWS_SECRET_ACCESS_KEY=… AWS_REGION=us-east-1 \
./target/release/compass
```

Supported: `s3://bucket[/prefix]` (AWS S3, MinIO, Cloudflare R2 — set `COMPASS_S3_ENDPOINT` for S3-compatible endpoints), `gs://bucket[/prefix]`, `az://container[/prefix]`. The optional `/prefix` scopes all keys so multiple deployments can share one bucket.

In this mode the bucket is the **source of truth**: every write lands durably in object storage first (an LSM of immutable WAL fragments + a CAS-committed manifest), and a node that boots with an empty disk discovers its collections from the bucket and rebuilds all local indexes — chunks, hierarchy, and typed relations included. Compaction (automatic past a WAL threshold, or via `POST /compact`) folds fragments into segments and physically reclaims deleted data.

### Serverless topologies

With the bucket as the source of truth, nodes become disposable roles you mix per workload (full reference: [docs/deployment.md](docs/deployment.md)):

- **Serving node** (default): full local indexes, fast reads; converges on other nodes' writes via a background manifest refresher (`COMPASS_REFRESH_INTERVAL`, default 5s). Writes return a `seq`; pass it back as `min_seq` for read-your-writes.
- **Writer node** (`COMPASS_ROLE=writer`): stateless, append-only, boots in milliseconds, refuses reads. Durable immediately; searchable on serving nodes within the refresh interval.
- **Cold serving** (`COMPASS_COLD_SERVE=true`): answers *semantic* queries on collections it has never attached, straight from object-storage range reads — first query in ~tens of ms instead of a minutes-long index rebuild. Repeated hits promote a background attach (`COMPASS_WARM_AFTER`). Full-text on a cold collection returns a clear error until it warms. Recall characteristics: [docs/search-quality.md](docs/search-quality.md).
- **Lazy attach + LRU** (`COMPASS_LAZY_ATTACH`, `COMPASS_MAX_ATTACHED`): boot registers namespaces without loading them; RAM tracks the hot set.

### Multi-tenant partitions

Create a collection with `"config": {"partition_by": "tenant_id"}` and every chunk routes to an internal per-tenant partition — its own indexes and attach/evict lifecycle behind one collection API. Searches and deletes filter by the partition field (exact match, or `{"in": [...]}` to fan out across up to 16 tenants); chunk ids stay collection-unique; partitions auto-create on first ingest and cascade-delete with the parent. Serving RAM tracks the hot-tenant set, not the tenant count — this also works fully offline in local mode.

For local development against MinIO:

```bash
docker compose -f docker-compose.minio.yml up   # MinIO + Compass wired together
```

## Embedding models

Compass supports any embedding model via named vector spaces. Pick the right model for your use case:

### Recommended open-weight models (May 2026)

**For text search** (documents, code, multilingual), use Harrier or Qwen3:

| Model               | Score | Benchmark | Dims    | License    | GPU   | When to use                                          |
| ------------------- | ----- | --------- | ------- | ---------- | ----- | ---------------------------------------------------- |
| Harrier-OSS-v1-0.6B | ~68   | MTEB v2   | 768     | MIT        | 8GB   | Default for most deployments. Best quality-per-VRAM. |
| Qwen3-Embedding-8B  | 70.58 | MTEB v2   | 32-7168 | Apache 2.0 | 16GB+ | When you need top-2 accuracy and have an A100/H100.  |
| Harrier-OSS-v1-27B  | 74.3  | MTEB v2   | 1024    | MIT        | 48GB+ | Maximum accuracy. Requires H100.                     |

**For multimodal** (text queries finding images, video frames, PDFs):

| Model                 | Score | Benchmark          | Dims | License    | GPU  | When to use                                                           |
| --------------------- | ----- | ------------------ | ---- | ---------- | ---- | --------------------------------------------------------------------- |
| Qwen3-VL-Embedding-2B | 0.945 | MMEB (cross-modal) | 896+ | Apache 2.0 | 8GB+ | Best cross-modal accuracy. Handles text + image + video in one space. |

**For reranking** (re-scoring top results after retrieval):

| Model                     | Score      | Benchmark | License     | GPU   | When to use                                        |
| ------------------------- | ---------- | --------- | ----------- | ----- | -------------------------------------------------- |
| Qwen3-Reranker-8B         | 69.76      | MTEB-R    | Apache 2.0  | 16GB+ | Best open-source reranker for multilingual + code. |
| Contextual AI Reranker v2 | SOTA on QA | Various   | Open source | 8GB+  | Best for Q&A-style retrieval.                      |

**CPU-only fallback** (no GPU available, degraded mode):

| Model             | Score | Benchmark | Dims | License | When to use                                                                      |
| ----------------- | ----- | --------- | ---- | ------- | -------------------------------------------------------------------------------- |
| BGE-small-en-v1.5 | ~63   | MTEB      | 384  | MIT     | Local dev, CI/CD tests, or hardware with no GPU. Not recommended for production. |

### Typical setup

Most deployments need two vector spaces: one for text, one for multimodal (if applicable).

```bash
# Run HuggingFace TEI with the recommended text model
docker run -p 8080:80 --gpus all ghcr.io/huggingface/text-embeddings-inference \
  --model-id microsoft/harrier-oss-v1-0.6b
```

MTEB and MMEB are different benchmarks on different scales. MTEB scores are 0-100 (text tasks). MMEB scores are 0-1 (cross-modal retrieval). They cannot be compared directly.

## Storage architecture

Compass keeps vector data and chunk metadata on disk, not in RAM.

```
data/{collection}/
├── collection.json                  # Collection metadata (name, dims, spaces)
├── chunks.redb                      # Chunk metadata + delete tombstones (redb)
├── relations.redb                   # Typed chunk relations + endpoint indexes (redb)
├── relationships.bin                # Parent-child + sibling graph
├── tantivy/                         # BM25 inverted index (disk-backed)
└── vectors/
    ├── {space}.index                # USearch HNSW graph (mmap on read)
    ├── {space}.bin                  # Raw f32 vectors (mmap via MmapVectors)
    └── {space}.keymap               # HNSW key → chunk ID mapping
```

**Vectors**: Stored in a flat `[magic "CMV2"][u32 dims][u64 count][f32...]` file, memory-mapped at query time. Adding vectors appends to the file and remaps — no full rewrite. Legacy u32-count files read transparently and migrate on first append. At 1M vectors × 768 dims this is ~3GB on disk, near-zero RSS.

**HNSW index**: Built incrementally via USearch `.add()` + `.save()`. Loaded via `.load()` for mutation or `.view()` for read-only mmap. The graph structure is separate from the raw vectors.

**Chunk metadata**: Persisted via redb (pure Rust, ACID, MVCC). Point lookups by chunk ID during search result assembly. Batch inserts during ingestion.

**Ingestion path**: New vectors are appended to the mmap file, inserted into the HNSW graph incrementally, and chunk metadata is written to redb — all without cloning existing data.

## Throughput and scaling

**Query throughput.** USearch HNSW serves around 15k QPS per instance on a 16-core box at p99 < 50ms for top-10 retrieval. For very high QPS workloads, shard collections across multiple Compass instances behind a load balancer.

**Indexing throughput.** Point `embed_endpoint` at a GPU-backed HuggingFace TEI or vLLM cluster. A single A10G handles around 1,500 docs/sec on Qwen3-Embedding-8B. Scale linearly by adding GPU replicas.

```bash
# Spin up TEI with the recommended text model
docker run -p 8080:80 --gpus all ghcr.io/huggingface/text-embeddings-inference \
  --model-id Qwen/Qwen3-Embedding-8B

# Point Compass at it during rebuild or ingestion
curl -X POST localhost:4001/collections/docs/vector-spaces/qwen3/rebuild \
  -d '{"embed_endpoint": "http://localhost:8080/embed"}'
```

## API

```
POST   /collections                                    Create collection
GET    /collections                                    List collections
GET    /collections/:name                              Get collection info
DELETE /collections/:name                              Delete collection + data

POST   /collections/:name/ingest                       Bulk ingest chunks
POST   /collections/:name/search                       Search (fts|semantic|hybrid); filter-aware ANN, "explain":true for query plan
GET    /collections/:name/facets                       Facet counts

DELETE /collections/:name/chunks/:id                   Soft-delete one chunk
POST   /collections/:name/delete                       Soft-delete by ids and/or metadata filters
POST   /collections/:name/compact                      Fold WAL + segments, reclaim deleted data (object-storage mode)

POST   /collections/:name/relations                    Create typed chunk relations (batch)
DELETE /collections/:name/relations/:relation_id       Delete a relation
GET    /collections/:name/chunks/:id/relations         List a chunk's relations (?direction=&types=)

POST   /collections/:name/vector-spaces                Add a vector space
GET    /collections/:name/vector-spaces                List vector spaces
DELETE /collections/:name/vector-spaces/:space         Remove a vector space
POST   /collections/:name/vector-spaces/:space/rebuild Trigger re-embedding
GET    /collections/:name/vector-spaces/:space/status  Rebuild progress
PUT    /collections/:name/default-vector-space         Switch default space

GET    /collections/:name/segments/at                  Temporal segment lookup (TAMS)

GET    /health                                         Health check
GET    /metrics                                        Prometheus-text metrics (unauthenticated by design, like /health — exposes collection names + counts; firewall it if that matters)
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, PR guidelines, and commit conventions.

## Telemetry

Telemetry is **off by default** — Compass never phones home unless you set `COMPASS_TELEMETRY=on`. When opted in, it sends a startup event and a daily heartbeat to PostHog (random instance id, version, OS/arch, collection and vector counts — never document content, queries, or metadata). `DO_NOT_TRACK=1` is honored even when opted in.

## Security

To report a vulnerability, email **support@runcaptain.com**. See [SECURITY.md](SECURITY.md) for details.

## License

Apache 2.0. See [LICENSE](LICENSE).

compass

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README