Scalability: mmap vectors, disk-backed chunks, incremental HNSW add

.github/workflows/ci.yml

@@ -60,7 +60,7 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@1.82.0
+      - uses: dtolnay/rust-toolchain@1.88.0
       - uses: Swatinem/rust-cache@v2
       - run: |
           sudo apt-get update

Cargo.toml

@@ -13,7 +13,7 @@ edition = "2021"
 authors = ["Captain Technologies <eng@runcaptain.com>"]
 repository = "https://github.com/runcaptain/compass"
 homepage = "https://runcaptain.com"
-rust-version = "1.82"
+rust-version = "1.88"
 
 [workspace.dependencies]
 # Async runtime + web framework
@@ -44,6 +44,11 @@ candle-nn = "0.8"
 candle-transformers = "0.8"
 hf-hub = "0.3"
 
+# Mmap + disk storage
+memmap2 = "0.9"
+bytemuck = { version = "1", features = ["derive"] }
+redb = "2.4"
+
 # Tracing
 tracing = "0.1"
 tracing-subscriber = "0.3"

Dockerfile

@@ -4,7 +4,7 @@
 # to a minimal Debian runtime. Final image is ~120MB instead of ~2GB.
 
 # ── Stage 1: Build ────────────────────────────────────────────────────────────
-FROM rust:1.82-bookworm AS builder
+FROM rust:latest AS builder
 
 WORKDIR /app
 
@@ -28,12 +28,13 @@ RUN mkdir -p crates/compass/src crates/compass-index-api/src \
     && echo "" > crates/compass-index-api/src/lib.rs \
     && cargo build --release -p compass --no-default-features 2>/dev/null || true
 
-# Now bring in the real source.
+# Now bring in the real source and rebuild everything that changed.
 COPY crates/ crates/
-RUN cargo build --release -p compass
+RUN touch crates/compass-index-api/src/lib.rs crates/compass/src/main.rs \
+    && cargo build --release -p compass
 
 # ── Stage 2: Runtime ──────────────────────────────────────────────────────────
-FROM debian:bookworm-slim
+FROM debian:trixie-slim
 
 RUN apt-get update && apt-get install -y \
     ca-certificates \

crates/compass-index-api/Cargo.toml

@@ -8,6 +8,10 @@ homepage.workspace = true
 rust-version.workspace = true
 description = "Stable trait API for Compass vector index backends. Implementors include the bundled USearch CPU backend and the optional cuVS GPU backend."
 
+[features]
+default = []
+gpu = []
+
 [dependencies]
 serde = { workspace = true }
 thiserror = { workspace = true }

crates/compass-vector-gpu/src/lib.rs

@@ -85,11 +85,7 @@ impl CuvsHnswIndex {
 
     /// Bulk-add vectors. Faster than calling [`VectorIndex::add`] in a loop
     /// because the GPU build is amortized over the whole batch.
-    pub fn add_batch(
-        &mut self,
-        vectors: &[Vec<f32>],
-        chunk_ids: &[u64],
-    ) -> Result<(), IndexError> {
+    pub fn add_batch(&mut self, vectors: &[Vec<f32>], chunk_ids: &[u64]) -> Result<(), IndexError> {
         if vectors.len() != chunk_ids.len() {
             return Err(IndexError::Backend(format!(
                 "vectors ({}) and chunk_ids ({}) length mismatch",
@@ -153,9 +149,10 @@ impl VectorIndex for CuvsHnswIndex {
                 actual: query.len(),
             });
         }
-        let inner = self.index.as_ref().ok_or_else(|| {
-            IndexError::Backend("search called before build".into())
-        })?;
+        let inner = self
+            .index
+            .as_ref()
+            .ok_or_else(|| IndexError::Backend("search called before build".into()))?;
 
         let raw = cuvs_bridge::search_hnsw(&inner.inner, query, top_k, self.params.ef_search)
             .map_err(|e| IndexError::Backend(format!("cuVS search failed: {e}")))?;
@@ -186,9 +183,10 @@ impl VectorIndex for CuvsHnswIndex {
     }
 
     fn save(&self, path: &Path) -> Result<(), IndexError> {
-        let inner = self.index.as_ref().ok_or_else(|| {
-            IndexError::Backend("save called before build".into())
-        })?;
+        let inner = self
+            .index
+            .as_ref()
+            .ok_or_else(|| IndexError::Backend("save called before build".into()))?;
         cuvs_bridge::serialize_hnsw(&inner.inner, path)
             .map_err(|e| IndexError::Io(format!("cuVS serialize failed: {e}")))?;
 
@@ -314,7 +312,10 @@ mod cuvs_bridge {
         // First-pass implementation lands in v0.2.0 of compass-vector-gpu.
 
         let _ = (vectors, dims, graph_degree, intermediate_graph_degree);
-        Err("cuVS build path not yet wired in this build; see crates/compass-vector-gpu/src/lib.rs".into())
+        Err(
+            "cuVS build path not yet wired in this build; see crates/compass-vector-gpu/src/lib.rs"
+                .into(),
+        )
     }
 
     pub(crate) fn search_hnsw(

crates/compass/Cargo.toml

@@ -40,6 +40,9 @@ candle-core = { workspace = true }
 candle-nn = { workspace = true }
 candle-transformers = { workspace = true }
 hf-hub = { workspace = true }
+memmap2 = { workspace = true }
+bytemuck = { workspace = true }
+redb = { workspace = true }
 tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 

crates/compass/src/api/collections.rs

@@ -22,9 +22,7 @@ pub async fn create_collection(
 }
 
 /// GET /collections — list all collections
-pub async fn list_collections(
-    State(state): State<Arc<AppState>>,
-) -> Json<Vec<CollectionInfo>> {
+pub async fn list_collections(State(state): State<Arc<AppState>>) -> Json<Vec<CollectionInfo>> {
     let collections = state.manager.list_collections().await;
     Json(collections.iter().map(collection_to_info).collect())
 }
@@ -34,8 +32,12 @@ pub async fn get_collection(
     State(state): State<Arc<AppState>>,
     Path(name): Path<String>,
 ) -> Result<Json<CollectionInfo>, (StatusCode, String)> {
-    let collection = state.manager.get_collection(&name).await
-        .ok_or_else(|| (StatusCode::NOT_FOUND, format!("Collection '{}' not found", name)))?;
+    let collection = state.manager.get_collection(&name).await.ok_or_else(|| {
+        (
+            StatusCode::NOT_FOUND,
+            format!("Collection '{}' not found", name),
+        )
+    })?;
     Ok(Json(collection_to_info(&collection)))
 }
 
@@ -44,7 +46,10 @@ pub async fn delete_collection(
     State(state): State<Arc<AppState>>,
     Path(name): Path<String>,
 ) -> Result<StatusCode, (StatusCode, String)> {
-    state.manager.delete_collection(&name).await
+    state
+        .manager
+        .delete_collection(&name)
+        .await
         .map_err(|e| (StatusCode::NOT_FOUND, e.to_string()))?;
     Ok(StatusCode::NO_CONTENT)
 }
@@ -57,28 +62,37 @@ pub async fn add_vector_space(
     Path(name): Path<String>,
     Json(req): Json<AddVectorSpaceRequest>,
 ) -> Result<(StatusCode, Json<VectorSpaceInfo>), (StatusCode, String)> {
-    state.manager
+    state
+        .manager
         .add_vector_space(&name, &req.name, req.dims, &req.model)
         .await
         .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;
 
-    Ok((StatusCode::CREATED, Json(VectorSpaceInfo {
-        name: req.name,
-        dims: req.dims,
-        model: req.model,
-        status: "building".to_string(),
-    })))
+    Ok((
+        StatusCode::CREATED,
+        Json(VectorSpaceInfo {
+            name: req.name,
+            dims: req.dims,
+            model: req.model,
+            status: "building".to_string(),
+        }),
+    ))
 }
 
 /// GET /collections/:name/vector-spaces — list vector spaces
 pub async fn list_vector_spaces(
     State(state): State<Arc<AppState>>,
     Path(name): Path<String>,
 ) -> Result<Json<Vec<VectorSpaceInfo>>, (StatusCode, String)> {
-    let collection = state.manager.get_collection(&name).await
-        .ok_or_else(|| (StatusCode::NOT_FOUND, format!("Collection '{}' not found", name)))?;
-
-    let spaces: Vec<VectorSpaceInfo> = collection.vector_spaces
+    let collection = state.manager.get_collection(&name).await.ok_or_else(|| {
+        (
+            StatusCode::NOT_FOUND,
+            format!("Collection '{}' not found", name),
+        )
+    })?;
+
+    let spaces: Vec<VectorSpaceInfo> = collection
+        .vector_spaces
         .iter()
         .map(|(sname, config)| VectorSpaceInfo {
             name: sname.clone(),
@@ -96,7 +110,10 @@ pub async fn delete_vector_space(
     State(state): State<Arc<AppState>>,
     Path((name, space)): Path<(String, String)>,
 ) -> Result<StatusCode, (StatusCode, String)> {
-    state.manager.delete_vector_space(&name, &space).await
+    state
+        .manager
+        .delete_vector_space(&name, &space)
+        .await
         .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;
     Ok(StatusCode::NO_CONTENT)
 }
@@ -107,7 +124,10 @@ pub async fn set_default_vector_space(
     Path(name): Path<String>,
     Json(req): Json<SetDefaultSpaceRequest>,
 ) -> Result<StatusCode, (StatusCode, String)> {
-    state.manager.set_default_vector_space(&name, &req.name).await
+    state
+        .manager
+        .set_default_vector_space(&name, &req.name)
+        .await
         .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;
     Ok(StatusCode::OK)
 }
@@ -119,15 +139,29 @@ pub async fn trigger_rebuild(
     Json(req): Json<RebuildRequest>,
 ) -> Result<StatusCode, (StatusCode, String)> {
     // Get collection metadata to find dims
-    let collection = state.manager.get_collection(&name).await
-        .ok_or_else(|| (StatusCode::NOT_FOUND, format!("Collection '{}' not found", name)))?;
-
-    let dims = collection.vector_spaces.get(&space)
+    let collection = state.manager.get_collection(&name).await.ok_or_else(|| {
+        (
+            StatusCode::NOT_FOUND,
+            format!("Collection '{}' not found", name),
+        )
+    })?;
+
+    let dims = collection
+        .vector_spaces
+        .get(&space)
         .map(|c| c.dims)
-        .ok_or_else(|| (StatusCode::NOT_FOUND, format!("Vector space '{}' not found", space)))?;
+        .ok_or_else(|| {
+            (
+                StatusCode::NOT_FOUND,
+                format!("Vector space '{}' not found", space),
+            )
+        })?;
 
     // Get all chunk data for re-embedding
-    let (texts, chunk_ids) = state.manager.get_all_chunk_data(&name).await
+    let (texts, chunk_ids) = state
+        .manager
+        .get_all_chunk_data(&name)
+        .await
         .map_err(|e| (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()))?;
 
     let vectors_dir = state.manager.vectors_dir(&name);
@@ -143,7 +177,9 @@ pub async fn trigger_rebuild(
         req.batch_size,
         state.manager.rebuild_tracker.clone(),
         name,
-    ).await.map_err(|e| (StatusCode::CONFLICT, e))?;
+    )
+    .await
+    .map_err(|e| (StatusCode::CONFLICT, e))?;
 
     Ok(StatusCode::ACCEPTED)
 }
@@ -154,23 +190,33 @@ pub async fn rebuild_status(
     Path((name, space)): Path<(String, String)>,
 ) -> Result<Json<RebuildStatus>, (StatusCode, String)> {
     let status = crate::collections::rebuild::get_rebuild_status(
-        &state.manager.rebuild_tracker, &name, &space,
-    ).await;
+        &state.manager.rebuild_tracker,
+        &name,
+        &space,
+    )
+    .await;
 
     match status {
         Some(s) => Ok(Json(s)),
         None => {
             // Check if the space exists and is already active
-            let collection = state.manager.get_collection(&name).await
-                .ok_or_else(|| (StatusCode::NOT_FOUND, format!("Collection '{}' not found", name)))?;
+            let collection = state.manager.get_collection(&name).await.ok_or_else(|| {
+                (
+                    StatusCode::NOT_FOUND,
+                    format!("Collection '{}' not found", name),
+                )
+            })?;
             match collection.vector_spaces.get(&space) {
                 Some(config) => Ok(Json(RebuildStatus {
                     status: config.status.clone(),
                     embedded: collection.chunk_count,
                     total: collection.chunk_count,
                     percent: 100.0,
                 })),
-                None => Err((StatusCode::NOT_FOUND, format!("Vector space '{}' not found", space))),
+                None => Err((
+                    StatusCode::NOT_FOUND,
+                    format!("Vector space '{}' not found", space),
+                )),
             }
         }
     }