Hybrid search that fuses BM25, vectors, and metadata — in one SQL query.

The three signals

Every result has three scores. The total ranking is a weighted sum; defaults are tuned for code+docs corpora, but you can override per query.

1. FTS5 BM25 — SQLite's built-in full-text index. Precise for keyword queries; tokenization is Unicode-aware. Filename and path tokens get a small boost.
2. Vector cosine similarity — embeddings from a local ONNX model (BGE Base EN v1.5 by default). Captures intent and synonyms. Stored in sqlite-vec with an HNSW index for sub-linear retrieval.
3. Metadata scoring — recency (modified time), filename match, content-type bonus (e.g. .md > .log), and source priority.

The query, in one CTE

Conceptually, the hybrid query looks like this:

WITH
  fts AS (
    SELECT chunk_id, bm25(file_chunks_fts) AS score
    FROM file_chunks_fts WHERE file_chunks_fts MATCH ?
  ),
  vec AS (
    SELECT chunk_id, 1.0 - distance AS score
    FROM file_chunks_vec
    WHERE embedding MATCH ? AND k = 50
  ),
  meta AS (
    SELECT id AS chunk_id,
           recency_score(updated_at) * 0.4 +
           filename_match(?, path) * 0.4 +
           filetype_bonus(content_type) * 0.2 AS score
    FROM file_chunks
  )
SELECT c.*, w.total
FROM file_chunks c
JOIN (
  SELECT chunk_id,
         COALESCE(fts.score, 0) * :w_fts +
         COALESCE(vec.score, 0) * :w_vec +
         COALESCE(meta.score, 0) * :w_meta AS total
  FROM fts FULL OUTER JOIN vec USING (chunk_id)
            FULL OUTER JOIN meta USING (chunk_id)
) w USING (id)
ORDER BY w.total DESC
LIMIT :limit;

Three modes, one flag

The mode parameter clamps the weights:

• mode=hybrid (default) — all three signals contribute. Best for natural-language queries.
• mode=fts — pure BM25. Use when you know the exact phrase or identifier (e.g. "OAuth2RefreshGrant").
• mode=vector — pure semantic. Use when the answer might live in a file whose vocabulary differs from yours.

Filters

Filters apply before ranking, in the SQL WHERE clause — so they're as fast as a regular SQLite query:

• source: local, s3://bucket, jira://infra, ...
• path glob: "src/**/*.go", "docs/**/*.md"
• content_type: code, markdown, pdf, spreadsheet
• since: "2025-01-01" or relative "7d"

Performance

On a 2024 MacBook Air, indexing throughput is 50–100 files per second and warm search latency is under 100 ms on a 10 000-file corpus. At 500 000 chunks, hybrid queries land in the 100–300 ms range. Cold queries (first search after process start) take roughly one second while the embedding model loads into memory.

Query it from anywhere

The same search engine is exposed three ways:

• CLI: stratafs search "where do we handle JWT refresh" --mode hybrid --limit 5
• REST: GET /search?q=...&mode=hybrid&source=docs&limit=10
• MCP: tools/call with name=stratafs.search, arguments identical to the REST shape. See the MCP page.