spike: evaluate SQLite vector storage for desktop mode

backend/src/find_api/core/sqlite_vec_poc.py

@@ -0,0 +1,213 @@
+"""
+SQLite + sqlite-vec proof of concept.
+"""
+
+import sqlite3
+import struct
+
+EMBEDDING_DIM = 768
+
+
+def create_connection(db_path=":memory:"):
+    conn = sqlite3.connect(str(db_path))
+    conn.enable_load_extension(True)
+
+    try:
+        import sqlite_vec
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "sqlite-vec is required for this desktop-runtime proof of concept. "
+            "Install it manually with `pip install sqlite-vec` before running "
+            "the sqlite_vec_poc tests."
+        ) from exc
+
+    sqlite_vec.load(conn)
+    return conn
+
+
+def create_schema(conn, embedding_dim: int):
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS media (
+            id INTEGER PRIMARY KEY,
+            filename TEXT NOT NULL,
+            status TEXT NOT NULL
+        )
+    """
+    )
+
+    conn.execute(
+        f"""
+        CREATE VIRTUAL TABLE IF NOT EXISTS media_vectors
+        USING vec0(
+            media_id INTEGER PRIMARY KEY,
+            embedding FLOAT[{embedding_dim}]
+        )
+    """
+    )
+
+    conn.commit()
+
+
+def insert_vector(
+    conn,
+    media_id: int,
+    embedding: list[float],
+):
+    blob = struct.pack(f"{len(embedding)}f", *embedding)
+
+    conn.execute(
+        """
+        INSERT INTO media_vectors(media_id, embedding)
+        VALUES (?, ?)
+        """,
+        (media_id, blob),
+    )
+
+    conn.commit()
+
+
+def insert_media(
+    conn,
+    media_id: int,
+    filename: str,
+    status: str = "indexed",
+):
+    conn.execute(
+        """
+        INSERT INTO media(id, filename, status)
+        VALUES (?, ?, ?)
+        """,
+        (media_id, filename, status),
+    )
+    conn.commit()
+
+
+def count_vectors(conn) -> int:
+    row = conn.execute("SELECT COUNT(*) FROM media_vectors").fetchone()
+
+    return row[0]
+
+
+def search_vectors(
+    conn,
+    query_embedding: list[float],
+    limit: int = 10,
+):
+    blob = struct.pack(
+        f"{len(query_embedding)}f",
+        *query_embedding,
+    )
+
+    rows = conn.execute(
+        """
+        SELECT
+            media_id,
+            distance
+        FROM media_vectors
+        WHERE embedding MATCH ?
+        ORDER BY distance
+        LIMIT ?
+        """,
+        (blob, limit),
+    ).fetchall()
+
+    return rows
+
+
+def search_media(
+    conn,
+    query_embedding,
+    limit=10,
+):
+    blob = struct.pack(
+        f"{len(query_embedding)}f",
+        *query_embedding,
+    )
+
+    rows = conn.execute(
+        """
+        SELECT
+            m.id,
+            m.filename,
+            v.distance
+        FROM media_vectors v
+        JOIN media m
+            ON m.id = v.media_id
+        WHERE embedding MATCH ?
+        AND k = ?
+        """,
+        (blob, limit),
+    ).fetchall()
+
+    return rows
+
+
+class SQLiteVecPOC:
+    def __init__(self, db_path=":memory:"):
+        self.conn = create_connection(db_path)
+
+    def create_schema(self):
+        create_schema(
+            self.conn,
+            EMBEDDING_DIM,
+        )
+
+    def insert_media(
+        self,
+        media_id,
+        filename,
+        embedding,
+    ):
+        insert_media(
+            self.conn,
+            media_id,
+            filename,
+        )
+
+        insert_vector(
+            self.conn,
+            media_id,
+            embedding,
+        )
+
+    def search(
+        self,
+        embedding,
+        limit=10,
+    ):
+        rows = search_media(
+            self.conn,
+            embedding,
+            limit,
+        )
+
+        return [
+            {
+                "id": row[0],
+                "filename": row[1],
+                "distance": row[2],
+            }
+            for row in rows
+        ]
+
+    def gallery_query(self):
+        rows = self.conn.execute(
+            """
+            SELECT
+                id,
+                filename,
+                status
+            FROM media
+            ORDER BY id
+            """
+        ).fetchall()
+
+        return [
+            {
+                "id": row[0],
+                "filename": row[1],
+                "status": row[2],
+            }
+            for row in rows
+        ]

backend/tests/test_sqlite_vec_poc.py

@@ -0,0 +1,103 @@
+import importlib.util
+
+import pytest
+
+from find_api.core.sqlite_vec_poc import (
+    EMBEDDING_DIM,
+    SQLiteVecPOC,
+)
+
+SQLITE_VEC_AVAILABLE = importlib.util.find_spec("sqlite_vec") is not None
+
+
+@pytest.fixture
+def sqlite_vec_available():
+    if not SQLITE_VEC_AVAILABLE:
+        pytest.skip("sqlite-vec is optional and not installed")
+
+
+def test_missing_sqlite_vec_dependency_message(tmp_path):
+    if SQLITE_VEC_AVAILABLE:
+        pytest.skip("sqlite-vec is installed")
+
+    db_file = tmp_path / "sqlite_vec.db"
+
+    with pytest.raises(RuntimeError, match="sqlite-vec is required"):
+        SQLiteVecPOC(db_file)
+
+
+def test_schema_creation(tmp_path, sqlite_vec_available):
+    db_file = tmp_path / "sqlite_vec.db"
+
+    poc = SQLiteVecPOC(db_file)
+    poc.create_schema()
+
+    assert db_file.exists()
+
+
+def test_insert_768_dimension_vector(tmp_path, sqlite_vec_available):
+    db_file = tmp_path / "sqlite_vec.db"
+
+    poc = SQLiteVecPOC(db_file)
+    poc.create_schema()
+
+    poc.insert_media(
+        media_id=1,
+        filename="cat.jpg",
+        embedding=[0.1] * EMBEDDING_DIM,
+    )
+
+    gallery = poc.gallery_query()
+
+    assert len(gallery) == 1
+    assert gallery[0]["filename"] == "cat.jpg"
+
+
+def test_similarity_search(tmp_path, sqlite_vec_available):
+    db_file = tmp_path / "sqlite_vec.db"
+
+    poc = SQLiteVecPOC(db_file)
+    poc.create_schema()
+
+    poc.insert_media(
+        1,
+        "match.jpg",
+        [0.1] * EMBEDDING_DIM,
+    )
+
+    poc.insert_media(
+        2,
+        "far.jpg",
+        [0.2] * EMBEDDING_DIM,
+    )
+
+    results = poc.search(
+        [0.1] * EMBEDDING_DIM,
+        limit=2,
+    )
+
+    assert len(results) == 2
+    assert results[0]["id"] == 1
+
+
+def test_gallery_query_shape(tmp_path, sqlite_vec_available):
+    db_file = tmp_path / "sqlite_vec.db"
+
+    poc = SQLiteVecPOC(db_file)
+    poc.create_schema()
+
+    poc.insert_media(
+        1,
+        "image.jpg",
+        [0.1] * EMBEDDING_DIM,
+    )
+
+    gallery = poc.gallery_query()
+
+    assert gallery == [
+        {
+            "id": 1,
+            "filename": "image.jpg",
+            "status": "indexed",
+        }
+    ]

docs/plans/not-started/desktop-runtime-adr.md

@@ -2,7 +2,7 @@
 
 - **Status:** Not started
 - **Date:** 2026-05-18
-- **Last reviewed:** 2026-05-28
+- **Last reviewed:** 2026-06-19
 - **Owner:** Find maintainers
 - **Related:** Issue #43, Roadmap [local-first-roadmap.md](../partial/local-first-roadmap.md), Framework choice [desktop-tauri-vs-electron-adr.md](../partial/desktop-tauri-vs-electron-adr.md)
 
@@ -74,6 +74,37 @@ The desktop runtime must remain **local-first** by default: images, embeddings,
   - Query performance remains acceptable (<500ms for typical gallery + search)
   - Single-file backup and export mechanisms are straightforward
 
+**SQLite vector spike result (2026-06-19):**
+
+A focused proof of concept now exists at `backend/src/find_api/core/sqlite_vec_poc.py` with tests in `backend/tests/test_sqlite_vec_poc.py`. It validates the basic desktop-mode shape without changing the production Docker/PostgreSQL runtime:
+
+- creates a SQLite database and media metadata table
+- loads `sqlite-vec` as an optional local extension
+- creates a 768-dimensional vector table matching Find's current embedding size
+- inserts media rows and vector blobs
+- runs nearest-neighbor vector search
+- returns a gallery-style metadata result shape
+
+To run the spike manually:
+
+```bash
+cd backend
+pip install sqlite-vec
+uv run pytest tests/test_sqlite_vec_poc.py -q
+```
+
+The tests skip automatically when `sqlite-vec` is not installed because this is still a desktop-runtime spike, not a default backend dependency.
+
+Current limitations:
+
+- It does not replace PostgreSQL + pgvector in Docker mode.
+- It does not cover migrations from the existing PostgreSQL schema.
+- It does not benchmark larger libraries, concurrent writes, WAL behavior, or index build cost.
+- It does not yet validate Find's full hybrid search behavior, filters, clustering joins, or queue interactions.
+- It keeps `sqlite-vec` out of the default dependency set until the project decides whether desktop mode should ship it.
+
+Follow-up implementation should only happen after the spike is benchmarked against realistic local libraries and the query abstraction is designed so PostgreSQL and SQLite can coexist cleanly.
+
 ---
 
 ### 4.2 Object Storage: MinIO → Local Filesystem