@wirecat/cli-core 0.433.0 → 0.434.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ shape of this file.
 
 ## Unreleased
 
+## 0.434.0 — 25.10.2026
+
+### Changed — may break callers
+
+- **Search by meaning ranks by a sqlite-vec index in the store (store version 34), and every store connection loads the extension.** Each embedding model gets a `vec0` table, `vector_index_<id>`, listed in the new `vector_indexes`; triggers on `chunks`, `embeddings` and `messages` keep it in step inside each write's own transaction. `nearestMessages`, `nearestImages` and conversation search (without a person, project, scope or conversation list) take candidates from it, check them with the scan's own SQL and score them as before, so they answer exactly what the scan answers; the scan stays for the filters the index cannot express. A store that held vectors is indexed on its first open by this version, in short batches. **Version 34 raises `minCompatible` to 34**: a build without the extension cannot write chunks to a store with these triggers, so older CLIs refuse the file and ask to be upgraded. The extension ships in `@wirecat/cli-core-sqlite` 1.1.0 (now a required runtime piece on every platform, Windows included); when it is missing or does not load, opening the store fails with `store.vector-extension-missing` or `store.vector-extension-failed` and says to reinstall. Under Node the store is opened with `allowExtension`, and SQL's `load_extension()` is switched off again right after.
+- **`store check` reports `vector_indexes`** — per model, the rows its index holds and the rows it should, and how many differ either way (`missing`, `extra`), compared whole — and fails `checks.vector_indexes` when a ready index is off.
+- **Vectors are stored at length one.** `saveVectors` and a document picture's vector are scaled to unit length before they are kept, so search by dot product and by the index rank alike; a vector with a non-finite value is refused (`store.vector-invalid`). Vectors stored before keep their length. The `not_applicable.extensions` field ("SQLite needs none") is gone.
+
 ## 0.433.0 — 25.10.2026
 
 ### Changed — may break callers

package/dist/cli/messenger/store-maintenance-command.js

@@ -12,7 +12,7 @@ import { migrate } from "../../store/migrations.js";
 import { openCache } from "../../store/open.js";
 import { storePath } from "../../store/path.js";
 import { deleteCopy, repairStore } from "../../store/repair.js";
-import { drainNoteIndex, fillSearchIndex, fillStems, involvementStoreOver, noteIndexState, openSqlite, openStore, orphanPointers, pendingNormalization, resetAttachmentWords, resetNoteIndex, resetSearchIndex, resetStems, searchIndexState, stemmerCache, stemsState, } from "../../store/store.js";
+import { drainNoteIndex, fillSearchIndex, fillStems, involvementStoreOver, noteIndexState, openSqlite, openStore, orphanPointers, pendingNormalization, resetAttachmentWords, resetNoteIndex, resetSearchIndex, resetStems, searchIndexState, stemmerCache, stemsState, vectorIndexCounts, } from "../../store/store.js";
 import { environmentOf, outputFor } from "../context.js";
 import { destroysNothing, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
@@ -241,11 +241,14 @@ const inspect = (path) => reading(path, (database) => {
     const { bavail, bsize } = statfsSync(dirname(path));
     const free = Number(bavail) * Number(bsize);
     const behind = schema.version > 0 ? chatsBehind(database) : [];
+    const vectorIndexes = schema.version >= 34 ? vectorIndexCounts(database) : [];
     const checks = {
         schema: schema.version >= SPEAKS && schema.writable,
         integrity: integrity.length === 1 && integrity[0] === "ok",
         foreignKeys: foreignKeys === 0,
         searchIndexes: Object.values(searchIndexes).every((state) => state === "ok"),
+        // One that is still filling is short by design; a ready one must hold exactly the rows its sources give.
+        vectorIndexes: vectorIndexes.every(({ ready, missing, extra }) => !ready || missing + extra === 0),
         // A backup or a VACUUM needs about as much again.
         disk: free >= size,
     };
@@ -268,7 +271,7 @@ const inspect = (path) => reading(path, (database) => {
         orphanPointers: schema.version > 0 ? orphanPointers(database) : [],
         conversations: conversationsBuilt(database),
         vectors: vectorsHeld(database),
-        notApplicable: { extensions: "SQLite needs none" },
+        vectorIndexes,
     };
 });
 /** `rank = 1` compares the index with its table; without it a stale external-content index passes. */

package/dist/entities/index.d.ts

@@ -9690,6 +9690,7 @@ export declare const ENTITIES: {
             readonly integrity: v.BooleanSchema<undefined>;
             readonly foreign_keys: v.BooleanSchema<undefined>;
             readonly search_indexes: v.BooleanSchema<undefined>;
+            readonly vector_indexes: v.BooleanSchema<undefined>;
             readonly disk: v.BooleanSchema<undefined>;
         }, undefined>;
         readonly schema: v.StrictObjectSchema<{
@@ -9756,9 +9757,15 @@ export declare const ENTITIES: {
             readonly models: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
             readonly unused: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
         }, undefined>, undefined>;
-        readonly not_applicable: v.StrictObjectSchema<{
-            readonly extensions: v.StringSchema<undefined>;
-        }, undefined>;
+        readonly vector_indexes: v.ArraySchema<v.StrictObjectSchema<{
+            readonly model: v.StringSchema<undefined>;
+            readonly dims: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly ready: v.BooleanSchema<undefined>;
+            readonly indexed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly expected: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly missing: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly extra: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        }, undefined>, undefined>;
     }, undefined>], undefined>;
     readonly store_migration: v.UnionSchema<[v.StrictObjectSchema<{
         readonly path: v.StringSchema<undefined>;

package/dist/entities/store-maintenance.d.ts

@@ -222,6 +222,7 @@ export declare const storeCheck: v.UnionSchema<[v.StrictObjectSchema<{
         readonly integrity: v.BooleanSchema<undefined>;
         readonly foreign_keys: v.BooleanSchema<undefined>;
         readonly search_indexes: v.BooleanSchema<undefined>;
+        readonly vector_indexes: v.BooleanSchema<undefined>;
         readonly disk: v.BooleanSchema<undefined>;
     }, undefined>;
     readonly schema: v.StrictObjectSchema<{
@@ -288,9 +289,15 @@ export declare const storeCheck: v.UnionSchema<[v.StrictObjectSchema<{
         readonly models: v.RecordSchema<v.StringSchema<undefined>, v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
         readonly unused: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
     }, undefined>, undefined>;
-    readonly not_applicable: v.StrictObjectSchema<{
-        readonly extensions: v.StringSchema<undefined>;
-    }, undefined>;
+    readonly vector_indexes: v.ArraySchema<v.StrictObjectSchema<{
+        readonly model: v.StringSchema<undefined>;
+        readonly dims: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly ready: v.BooleanSchema<undefined>;
+        readonly indexed: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly expected: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly missing: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly extra: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>, undefined>;
 }, undefined>], undefined>;
 export declare const storeMigration: v.UnionSchema<[v.StrictObjectSchema<{
     readonly path: v.StringSchema<undefined>;

package/dist/entities/store-maintenance.js

@@ -87,6 +87,7 @@ export const storeCheck = v.union([
             integrity: v.boolean(),
             foreign_keys: v.boolean(),
             search_indexes: v.boolean(),
+            vector_indexes: v.boolean(),
             disk: v.boolean(),
         }),
         schema,
@@ -118,7 +119,15 @@ export const storeCheck = v.union([
             stale_agent_links: count,
         })),
         vectors: v.nullable(v.strictObject({ models: v.record(text, count), unused: count })),
-        not_applicable: v.strictObject({ extensions: text }),
+        vector_indexes: v.array(v.strictObject({
+            model: text,
+            dims: count,
+            ready: v.boolean(),
+            indexed: count,
+            expected: count,
+            missing: count,
+            extra: count,
+        })),
     }),
 ]);
 const indexed = { normalized: count, indexed: count, terms: count, stemmed: count, notes_indexed: count };

package/dist/errors/reasons.js

@@ -55,6 +55,13 @@ const OTHERS = [
     ["state.invalid", "configuration_error", "the saved sync state is unreadable or invalid; it is kept, not reset"],
     validation("store.refused", "the local store refused the document text"),
     ["store.not-writable", "permission_error", "the message store cannot be written from this process"],
+    [
+        "store.vector-extension-missing",
+        "configuration_error",
+        "the install has no sqlite-vec extension for this platform; reinstall the CLI",
+    ],
+    ["store.vector-extension-failed", "configuration_error", "the sqlite-vec extension did not load; reinstall the CLI"],
+    validation("store.vector-invalid", "a vector to store had a non-finite value"),
     validation("catalog.scope-limit", "the selected catalog exceeds its entry limit"),
     validation("evidence.row-too-large", "one evidence row is over its size limit"),
     validation("index.not-ready", "the search index is still being built"),

package/dist/store/drivers/bun-sqlite.d.ts

@@ -9,6 +9,7 @@ interface BunStatement {
 export interface BunDatabase {
     exec(sql: string): void;
     query(sql: string): BunStatement;
+    loadExtension(path: string): void;
     close(): void;
 }
 export interface BunDatabaseClass {
@@ -25,5 +26,10 @@ export interface BunDatabaseClass {
  */
 export declare const bunDatabase: () => Promise<BunDatabaseClass>;
 export declare const openWithBunSqlite: (path: string) => Promise<CacheDatabase>;
+/** A connection with the vector extension loaded; it closes again when the extension does not load. */
+export declare const bunClient: (path: string, options?: {
+    readonly?: boolean;
+    create?: boolean;
+}) => Promise<BunDatabase>;
 export declare const cacheOverBunSqlite: (database: BunDatabase) => CacheDatabase;
 export {};

package/dist/store/drivers/bun-sqlite.js

@@ -1,3 +1,4 @@
+import { loadVectorExtension, vectorExtension } from "../vector-extension.js";
 let customised = false;
 /**
  * Bun on macOS takes the system's SQLite, which can be older than the store needs, so it always
@@ -29,7 +30,21 @@ export const bunDatabase = async () => {
     }
     return Database;
 };
-export const openWithBunSqlite = async (path) => cacheOverBunSqlite(new (await bunDatabase())(path));
+export const openWithBunSqlite = async (path) => cacheOverBunSqlite(await bunClient(path));
+/** A connection with the vector extension loaded; it closes again when the extension does not load. */
+export const bunClient = async (path, options) => {
+    const Database = await bunDatabase();
+    const extension = await vectorExtension();
+    const client = options ? new Database(path, options) : new Database(path);
+    try {
+        loadVectorExtension(client, extension);
+        return client;
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
+};
 export const cacheOverBunSqlite = (database) => {
     return {
         exec: (sql) => database.exec(sql),

package/dist/store/drivers/node-sqlite.d.ts

@@ -4,5 +4,9 @@ import type { CacheDatabase } from "../driver.js";
  * Import this module only through a dynamic import that follows `quietSqliteWarning()`: a static import loads
  * `node:sqlite`, and on Node 22 its ExperimentalWarning, before the filter can run.
  */
-export declare const openWithNodeSqlite: (path: string) => CacheDatabase;
+export declare const openWithNodeSqlite: (path: string) => Promise<CacheDatabase>;
+/** A connection with the vector extension loaded; it closes again when the extension does not load. */
+export declare const nodeClient: (path: string, { readOnly }?: {
+    readOnly?: boolean;
+}) => Promise<DatabaseSync>;
 export declare const cacheOverNodeSqlite: (database: DatabaseSync) => CacheDatabase;

package/dist/store/drivers/node-sqlite.js

@@ -1,10 +1,24 @@
 // biome-ignore-all lint/plugin/no-sqlite-driver: cli-core owns the store, so it opens the driver itself
 import { DatabaseSync } from "node:sqlite";
+import { loadVectorExtension, vectorExtension } from "../vector-extension.js";
 /**
  * Import this module only through a dynamic import that follows `quietSqliteWarning()`: a static import loads
  * `node:sqlite`, and on Node 22 its ExperimentalWarning, before the filter can run.
  */
-export const openWithNodeSqlite = (path) => cacheOverNodeSqlite(new DatabaseSync(path));
+export const openWithNodeSqlite = async (path) => cacheOverNodeSqlite(await nodeClient(path));
+/** A connection with the vector extension loaded; it closes again when the extension does not load. */
+export const nodeClient = async (path, { readOnly = false } = {}) => {
+    const extension = await vectorExtension();
+    const client = new DatabaseSync(path, { readOnly, allowExtension: true });
+    try {
+        loadVectorExtension(client, extension);
+        return client;
+    }
+    catch (error) {
+        client.close();
+        throw error;
+    }
+};
 export const cacheOverNodeSqlite = (database) => {
     return {
         exec: (sql) => database.exec(sql),

package/dist/store/exports.d.ts

@@ -54,6 +54,7 @@ export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";
 export { DEFAULT_FIRST_PASS_PER_CHAT, firstPassPerChatOf, savedFirstPassPerChat } from "./sqlite/task-first-pass.js";
 export { inboxKey } from "./sqlite/tasks.js";
+export { vectorIndexCounts } from "./sqlite/vector-index.js";
 export type { MatchPlace, ScoredHit } from "./sqlite/words.js";
 export type { TaskDetails } from "./sqlite/work-tasks.js";
 export type { SyncStore } from "./sync.js";

package/dist/store/exports.js

@@ -24,3 +24,4 @@ export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";
 export { DEFAULT_FIRST_PASS_PER_CHAT, firstPassPerChatOf, savedFirstPassPerChat } from "./sqlite/task-first-pass.js";
 export { inboxKey } from "./sqlite/tasks.js";
+export { vectorIndexCounts } from "./sqlite/vector-index.js";

package/dist/store/sqlite/document-pictures.js

@@ -1,5 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { write } from "./transaction.js";
+import { ensureVectorIndex, unitVector } from "./vector-index.js";
 import { dot } from "./vectors.js";
 /** A document's picture is one chunk of this type at position 0; its vector is the picture's, not text's. */
 export const DOCUMENT_PICTURE = "document_picture";
@@ -44,10 +45,12 @@ export const documentPicturesOver = ({ database, now }) => ({
                 throw new CliError("not_found", `no document ${ref} in the local store`);
             const at = now();
             dropDocumentPicture(database, id);
+            ensureVectorIndex(database, model, dims);
+            const unit = unitVector(vector);
             database
                 .prepare(`INSERT INTO embeddings (model, content_hash, dims, vector, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)
             ON CONFLICT DO NOTHING`)
-                .run(model, hash, dims, Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength), at, at);
+                .run(model, hash, dims, Buffer.from(unit.buffer, unit.byteOffset, unit.byteLength), at, at);
             database
                 .prepare(`INSERT INTO chunks (chunkable_type, chunkable_id, position, start_offset, end_offset, content_hash, scope,
               account_id, occurred_at, created_at, updated_at) VALUES (?, ?, 0, 0, ?, ?, ?, ?, ?, ?, ?)`)

package/dist/store/sqlite/image-chunks.d.ts

@@ -46,7 +46,7 @@ export interface NearestImage {
  * The images of the account nearest to `query` by the vector of `model`, best first. Position 0 of an image is
  * its context text, position 1 its picture (`PICTURE_POSITION`): a model's vectors only ever sit at one.
  */
-export declare const nearestImages: ({ orm }: StoreContext, accountPk: number, { chatKey, model, since, limit, query, position, }: {
+export declare const nearestImages: (context: StoreContext, accountPk: number, { chatKey, model, since, limit, query, position, }: {
     chatKey?: number;
     model: string;
     since?: number;

package/dist/store/sqlite/image-chunks.js

@@ -1,4 +1,5 @@
 import { sql } from "./drizzle/core.js";
+import { searchIndex } from "./vector-index.js";
 import { dot } from "./vectors.js";
 const IS_IMAGE = sql `(a.kind = 'photo' OR a.mime LIKE 'image/%')`;
 const neighbours = ({ orm }, chatKey, messagePk, sentAt, { messages, withinMs }, side) => orm.all(sql `SELECT sender_name AS sender, text, sent_at AS sentAt FROM messages
@@ -62,32 +63,64 @@ export const embeddedHashes = ({ orm }, model, hashes) => new Set(hashes.length
               WHERE model = ${model} AND content_hash IN (SELECT value FROM json_each(${JSON.stringify(hashes)}))`)
         .map(({ hash }) => hash));
 const SCAN_PAGE = 5_000;
+/** The scan's rows: one page after `after`, or the `ids` the index picked. */
+const imageRows = ({ orm }, accountPk, { chatKey, model, since, position }, rows) => orm.all(sql `SELECT k.id, k.content_hash AS hash, ch.external_id AS chatId, m.external_id AS messageId, v.vector
+      FROM chunks k CROSS JOIN attachments a ON a.id = k.chunkable_id AND a.attachable_type = 'message'
+        JOIN messages m ON m.id = a.attachable_id AND m.deleted_at IS NULL
+        JOIN chats ch ON ch.id = m.chat_id
+        JOIN embeddings v ON v.model = ${model} AND v.content_hash = k.content_hash
+      WHERE k.chunkable_type = 'image' AND k.position = ${position} AND ch.account_id = ${accountPk}
+        ${chatKey === undefined ? sql `AND ch.searchable = 1` : sql `AND m.chat_id = ${chatKey}`}
+        ${since === undefined ? sql `` : sql `AND k.occurred_at >= ${since}`}
+        ${"ids" in rows
+    ? sql `AND k.id IN (SELECT value FROM json_each(${JSON.stringify(rows.ids)})) ORDER BY k.id`
+    : sql `AND k.id > ${rows.after} ORDER BY k.id LIMIT ${SCAN_PAGE}`}`);
 /**
  * The images of the account nearest to `query` by the vector of `model`, best first. Position 0 of an image is
  * its context text, position 1 its picture (`PICTURE_POSITION`): a model's vectors only ever sit at one.
  */
-export const nearestImages = ({ orm }, accountPk, { chatKey, model, since, limit, query, position = 0, }) => {
+export const nearestImages = (context, accountPk, { chatKey, model, since, limit, query, position = 0, }) => {
+    const filter = {
+        model,
+        position,
+        ...(chatKey === undefined ? {} : { chatKey }),
+        ...(since === undefined ? {} : { since }),
+    };
+    const score = (row) => ({
+        id: row.id,
+        chatId: row.chatId,
+        messageId: row.messageId,
+        score: dot(query, row.vector),
+    });
+    // Stable, so equal scores keep the scan's order, by chunk id.
+    const best = (found) => found.sort((a, b) => b.score - a.score).slice(0, limit);
+    const indexed = searchIndex(context.database, model, {
+        kind: "image",
+        account: accountPk,
+        ...(chatKey === undefined ? {} : { chat: chatKey }),
+        ...(since === undefined ? {} : { since }),
+    }, query, limit, (candidates) => {
+        const hashes = new Map(candidates.map(({ id, hash }) => [id, hash]));
+        const results = best(imageRows(context, accountPk, filter, { ids: [...hashes.keys()] })
+            .filter((row) => hashes.get(row.id) === row.hash)
+            .map(score));
+        return { results, best: results.map(({ id }) => id) };
+    });
+    const plain = (found) => found.map(({ chatId, messageId, score }) => ({ chatId, messageId, score }));
+    if (indexed)
+        return plain(indexed);
     const found = [];
     let after = 0;
     for (;;) {
-        const rows = orm.all(sql `SELECT k.id, ch.external_id AS chatId, m.external_id AS messageId, v.vector
-        FROM chunks k CROSS JOIN attachments a ON a.id = k.chunkable_id AND a.attachable_type = 'message'
-          JOIN messages m ON m.id = a.attachable_id AND m.deleted_at IS NULL
-          JOIN chats ch ON ch.id = m.chat_id
-          JOIN embeddings v ON v.model = ${model} AND v.content_hash = k.content_hash
-        WHERE k.chunkable_type = 'image' AND k.position = ${position} AND ch.account_id = ${accountPk}
-          AND k.id > ${after}
-          ${chatKey === undefined ? sql `AND ch.searchable = 1` : sql `AND m.chat_id = ${chatKey}`}
-          ${since === undefined ? sql `` : sql `AND k.occurred_at >= ${since}`}
-        ORDER BY k.id LIMIT ${SCAN_PAGE}`);
+        const rows = imageRows(context, accountPk, filter, { after });
         for (const row of rows)
-            found.push({ chatId: row.chatId, messageId: row.messageId, score: dot(query, row.vector) });
+            found.push(score(row));
         const last = rows.at(-1);
         if (!last || rows.length < SCAN_PAGE)
             break;
         after = last.id;
     }
-    return found.sort((a, b) => b.score - a.score).slice(0, limit);
+    return plain(best(found));
 };
 /** An image's own vector is its chunk at this position; position 0 is the text around it. */
 export const PICTURE_POSITION = 1;

package/dist/store/sqlite/manifest.js

@@ -43,6 +43,8 @@ export const MANIFEST = [
     { name: "20261025071850_version-32-files-data", version: 32, minCompatible: 32 },
     { name: "20261025072643_version-33-calendars", version: 33, minCompatible: 32 },
     { name: "20261025072644_version-33-calendars-triggers", version: 33, minCompatible: 32 },
+    { name: "20261025182500_version-34-vector-index", version: 34, minCompatible: 34 },
+    { name: "20261025182501_version-34-vector-index-triggers", version: 34, minCompatible: 34 },
 ];
 export const generatedMigrations = (manifest = MANIFEST, generated = GENERATED) => {
     const migrations = [];

package/dist/store/sqlite/message-chunks.d.ts

@@ -33,12 +33,15 @@ export interface NearestMessage {
     messageId: string;
     score: number;
 }
-/** The account's live messages nearest to `query` by their vector of `model`, best first: a scan of every vector. */
-export declare const nearestMessages: ({ orm }: StoreContext, accountPk: number, { chatKey, model, since, before, limit, query, }: {
+type MessageFilter = {
     chatKey?: number;
     model: string;
     since?: number;
     before?: number;
+};
+/** The account's live messages nearest to `query` by their vector of `model`, best first. */
+export declare const nearestMessages: (context: StoreContext, accountPk: number, { limit, query, ...filter }: MessageFilter & {
     limit: number;
     query: Float32Array;
 }) => NearestMessage[];
+export {};

package/dist/store/sqlite/message-chunks.js

@@ -1,4 +1,5 @@
 import { sql } from "./drizzle/core.js";
+import { searchIndex } from "./vector-index.js";
 import { dot } from "./vectors.js";
 /** Live messages with text of the account, by pk after `after`; the caller compares hashes. */
 export const messagesToEmbed = ({ orm }, accountPk, { chatKey, model, after, limit }) => orm
@@ -51,26 +52,54 @@ export const dropGoneMessageChunks = (context, accountPk) => {
 export const hasMessageVectors = ({ orm }, accountPk, model) => orm.get(sql `SELECT 1 FROM chunks k JOIN embeddings v ON v.model = ${model} AND v.content_hash = k.content_hash
       WHERE k.chunkable_type = 'message' AND k.account_id = ${accountPk} LIMIT 1`) !== undefined;
 const SCAN_PAGE = 5_000;
-/** The account's live messages nearest to `query` by their vector of `model`, best first: a scan of every vector. */
-export const nearestMessages = ({ orm }, accountPk, { chatKey, model, since, before, limit, query, }) => {
+/** The scan's rows: one page after `after`, or the `ids` the index picked. */
+const messageRows = ({ orm }, accountPk, { chatKey, model, since, before }, rows) => orm.all(sql `SELECT k.id, k.content_hash AS hash, ch.external_id AS chatId, m.external_id AS messageId, v.vector
+      FROM chunks k CROSS JOIN messages m ON m.id = k.chunkable_id AND m.deleted_at IS NULL
+        JOIN chats ch ON ch.id = m.chat_id
+        JOIN embeddings v ON v.model = ${model} AND v.content_hash = k.content_hash
+      WHERE k.chunkable_type = 'message' AND k.position = 0 AND k.account_id = ${accountPk}
+        ${chatKey === undefined ? sql `AND ch.searchable = 1` : sql `AND m.chat_id = ${chatKey}`}
+        ${since === undefined ? sql `` : sql `AND m.sent_at >= ${since}`}
+        ${before === undefined ? sql `` : sql `AND m.sent_at < ${before}`}
+        ${"ids" in rows
+    ? sql `AND k.id IN (SELECT value FROM json_each(${JSON.stringify(rows.ids)})) ORDER BY k.id`
+    : sql `AND k.id > ${rows.after} ORDER BY k.id LIMIT ${SCAN_PAGE}`}`);
+/** The account's live messages nearest to `query` by their vector of `model`, best first. */
+export const nearestMessages = (context, accountPk, { limit, query, ...filter }) => {
+    const score = (row) => ({
+        id: row.id,
+        chatId: row.chatId,
+        messageId: row.messageId,
+        score: dot(query, row.vector),
+    });
+    // Stable, so equal scores keep the scan's order, by chunk id.
+    const best = (found) => found.sort((a, b) => b.score - a.score).slice(0, limit);
+    const indexed = searchIndex(context.database, filter.model, {
+        kind: "message",
+        account: accountPk,
+        ...(filter.chatKey === undefined ? {} : { chat: filter.chatKey }),
+        ...(filter.since === undefined ? {} : { since: filter.since }),
+        ...(filter.before === undefined ? {} : { before: filter.before }),
+    }, query, limit, (candidates) => {
+        const hashes = new Map(candidates.map(({ id, hash }) => [id, hash]));
+        const results = best(messageRows(context, accountPk, filter, { ids: [...hashes.keys()] })
+            .filter((row) => hashes.get(row.id) === row.hash)
+            .map(score));
+        return { results, best: results.map(({ id }) => id) };
+    });
+    const plain = (found) => found.map(({ chatId, messageId, score }) => ({ chatId, messageId, score }));
+    if (indexed)
+        return plain(indexed);
     const found = [];
     let after = 0;
     for (;;) {
-        const rows = orm.all(sql `SELECT k.id, ch.external_id AS chatId, m.external_id AS messageId, v.vector
-        FROM chunks k CROSS JOIN messages m ON m.id = k.chunkable_id AND m.deleted_at IS NULL
-          JOIN chats ch ON ch.id = m.chat_id
-          JOIN embeddings v ON v.model = ${model} AND v.content_hash = k.content_hash
-        WHERE k.chunkable_type = 'message' AND k.position = 0 AND k.account_id = ${accountPk} AND k.id > ${after}
-          ${chatKey === undefined ? sql `AND ch.searchable = 1` : sql `AND m.chat_id = ${chatKey}`}
-          ${since === undefined ? sql `` : sql `AND m.sent_at >= ${since}`}
-          ${before === undefined ? sql `` : sql `AND m.sent_at < ${before}`}
-        ORDER BY k.id LIMIT ${SCAN_PAGE}`);
+        const rows = messageRows(context, accountPk, filter, { after });
         for (const row of rows)
-            found.push({ chatId: row.chatId, messageId: row.messageId, score: dot(query, row.vector) });
+            found.push(score(row));
         const last = rows.at(-1);
         if (!last || rows.length < SCAN_PAGE)
             break;
         after = last.id;
     }
-    return found.sort((a, b) => b.score - a.score).slice(0, limit);
+    return plain(best(found));
 };

package/dist/store/sqlite/migrations.generated.js

@@ -739,5 +739,27 @@ export const GENERATED = [
             "INSERT OR IGNORE INTO search_index_state (name, watermark, filled_through, terms_through, normalizer_version, built_at, analyzer)\n  VALUES ('event_index', 0, 0, 0, 1, NULL, NULL);",
             "INSERT OR IGNORE INTO event_index_pending (indexable_type, id) SELECT 'event', id FROM events;"
         ]
+    },
+    {
+        "name": "20261025182500_version-34-vector-index",
+        "statements": [
+            "CREATE TABLE `vector_index_redo` (\n\t`chunk_id` integer NOT NULL\n);",
+            "CREATE TABLE `vector_indexes` (\n\t`id` integer PRIMARY KEY,\n\t`model` text NOT NULL UNIQUE,\n\t`dims` integer NOT NULL,\n\t`ready` integer NOT NULL,\n\t`filled_through` text NOT NULL\n);"
+        ]
+    },
+    {
+        "name": "20261025182501_version-34-vector-index-triggers",
+        "statements": [
+            "-- Every change that can add, drop or move a chunk's vector passes the chunk's id through vector_index_redo, where\n-- each model's own trigger (made with its vec0 table, `vector-index.ts`) re-derives that row. Writes in TypeScript\n-- and the schema's own delete triggers (document_bd, note_bd, …) all reach the index this way.\n-- A chunk usually comes before its vector; the vector's own trigger indexes it then.\n-- CROSS JOIN: led by the vectors, SQLite read every one of them per chunk (7 ms each at 100k).\nCREATE TRIGGER vector_index_chunk_ai AFTER INSERT ON chunks WHEN EXISTS (SELECT 1 FROM vector_indexes i\n    CROSS JOIN embeddings v ON v.model = i.model AND v.content_hash = new.content_hash) BEGIN\n  INSERT INTO vector_index_redo (chunk_id) VALUES (new.id);\n  DELETE FROM vector_index_redo;\nEND;",
+            "CREATE TRIGGER vector_index_chunk_ad AFTER DELETE ON chunks BEGIN\n  INSERT INTO vector_index_redo (chunk_id) VALUES (old.id);\n  DELETE FROM vector_index_redo;\nEND;",
+            "CREATE TRIGGER vector_index_chunk_au AFTER UPDATE OF content_hash, chunkable_type, chunkable_id, account_id, occurred_at\n  ON chunks WHEN old.content_hash IS NOT new.content_hash OR old.chunkable_type IS NOT new.chunkable_type\n    OR old.chunkable_id IS NOT new.chunkable_id OR old.account_id IS NOT new.account_id\n    OR old.occurred_at IS NOT new.occurred_at BEGIN\n  INSERT INTO vector_index_redo (chunk_id) VALUES (new.id);\n  DELETE FROM vector_index_redo;\nEND;",
+            "CREATE TRIGGER vector_index_embedding_ai AFTER INSERT ON embeddings\n  WHEN EXISTS (SELECT 1 FROM vector_indexes WHERE model = new.model) BEGIN\n  INSERT INTO vector_index_redo (chunk_id) SELECT id FROM chunks WHERE content_hash = new.content_hash;\n  DELETE FROM vector_index_redo;\nEND;",
+            "CREATE TRIGGER vector_index_embedding_ad AFTER DELETE ON embeddings\n  WHEN EXISTS (SELECT 1 FROM vector_indexes WHERE model = old.model) BEGIN\n  INSERT INTO vector_index_redo (chunk_id) SELECT id FROM chunks WHERE content_hash = old.content_hash;\n  DELETE FROM vector_index_redo;\nEND;",
+            "CREATE TRIGGER vector_index_embedding_au AFTER UPDATE OF model, content_hash, vector ON embeddings BEGIN\n  INSERT INTO vector_index_redo (chunk_id)\n    SELECT id FROM chunks WHERE content_hash = old.content_hash OR content_hash = new.content_hash;\n  DELETE FROM vector_index_redo;\nEND;",
+            "-- A message's chunk and its images' chunks are indexed under its chat and send time; a chat merge moves messages.\nCREATE TRIGGER vector_index_message_au AFTER UPDATE OF chat_id, sent_at ON messages\n  WHEN old.chat_id IS NOT new.chat_id OR old.sent_at IS NOT new.sent_at BEGIN\n  INSERT INTO vector_index_redo (chunk_id)\n    SELECT id FROM chunks WHERE chunkable_type = 'message' AND chunkable_id = new.id\n    UNION ALL SELECT k.id FROM attachments a JOIN chunks k ON k.chunkable_type = 'image' AND k.chunkable_id = a.id\n      WHERE a.attachable_type = 'message' AND a.attachable_id = new.id;\n  DELETE FROM vector_index_redo;\nEND;",
+            "-- An image's chat and account come from its message; a chat merge moves attachments to the kept copy.\nCREATE TRIGGER vector_index_attachment_au AFTER UPDATE OF attachable_type, attachable_id ON attachments\n  WHEN old.attachable_type IS NOT new.attachable_type OR old.attachable_id IS NOT new.attachable_id BEGIN\n  INSERT INTO vector_index_redo (chunk_id) SELECT id FROM chunks WHERE chunkable_type = 'image' AND chunkable_id = new.id;\n  DELETE FROM vector_index_redo;\nEND;",
+            "CREATE TRIGGER vector_index_conversation_au AFTER UPDATE OF chat_id ON conversations\n  WHEN old.chat_id IS NOT new.chat_id BEGIN\n  INSERT INTO vector_index_redo (chunk_id)\n    SELECT id FROM chunks WHERE chunkable_type = 'conversation' AND chunkable_id = new.id;\n  DELETE FROM vector_index_redo;\nEND;",
+            "-- Images and conversations are indexed under their chat's account; messages carry their own.\nCREATE TRIGGER vector_index_chat_au AFTER UPDATE OF account_id ON chats WHEN old.account_id IS NOT new.account_id BEGIN\n  INSERT INTO vector_index_redo (chunk_id)\n    SELECT k.id FROM messages m JOIN attachments a ON a.attachable_type = 'message' AND a.attachable_id = m.id\n      JOIN chunks k ON k.chunkable_type = 'image' AND k.chunkable_id = a.id WHERE m.chat_id = new.id\n    UNION ALL SELECT k.id FROM conversations c JOIN chunks k ON k.chunkable_type = 'conversation' AND k.chunkable_id = c.id\n      WHERE c.chat_id = new.id;\n  DELETE FROM vector_index_redo;\nEND;"
+        ]
     }
 ];

package/dist/store/sqlite/open-store.js

@@ -15,6 +15,7 @@ import { loadProviders } from "./providers.js";
 import { assertReadCompatible } from "./read-compatibility.js";
 import { stemsState } from "./stems.js";
 import { fillStems, followDefaultStemmers } from "./stems-fill.js";
+import { fillVectorIndexes } from "./vector-index.js";
 export const BACKFILL_ON_OPEN = 5_000;
 const NOT_WRITABLE = new Set(["EACCES", "EPERM", "EROFS"]);
 const createWritable = (file) => {
@@ -62,6 +63,9 @@ export const openStoreContext = async ({ path, env, now = Date.now, command, ver
                 stemming.watermark - stemming.filledThrough + stemming.pending <= BACKFILL_ON_OPEN)
                 fillStems(database, { now });
             logPruner(database, now)();
+            fillVectorIndexes(database, {
+                notice: (model) => warn(`indexing the stored vectors of ${model} for search by meaning — once; a large archive takes minutes`),
+            });
         }
         loadProviders(database);
         return { ...opened, now, sharedConfig: sharedConfigPath(file, env ?? process.env) };

package/dist/store/sqlite/open.js

@@ -20,10 +20,9 @@ export const openSqlite = async (path, { readOnly = false } = {}) => {
 };
 const openUnderNode = async (path, readOnly) => {
     quietSqliteWarning();
-    const { DatabaseSync } = await import("node:sqlite");
     const { drizzle } = await import("./drizzle/node.js");
-    const { cacheOverNodeSqlite } = await import("../drivers/node-sqlite.js");
-    const client = new DatabaseSync(path, { readOnly });
+    const { cacheOverNodeSqlite, nodeClient } = await import("../drivers/node-sqlite.js");
+    const client = await nodeClient(path, { readOnly });
     try {
         return { database: cacheOverNodeSqlite(client), orm: drizzle({ client }) };
     }
@@ -33,10 +32,9 @@ const openUnderNode = async (path, readOnly) => {
     }
 };
 const openUnderBun = async (path, readOnly) => {
-    const { bunDatabase, cacheOverBunSqlite } = await import("../drivers/bun-sqlite.js");
-    const Database = await bunDatabase();
+    const { bunClient, cacheOverBunSqlite } = await import("../drivers/bun-sqlite.js");
     const { drizzle } = (await import("./drizzle/bun.js"));
-    const client = readOnly ? new Database(path, { readonly: true, create: false }) : new Database(path);
+    const client = await bunClient(path, readOnly ? { readonly: true, create: false } : undefined);
     try {
         return { database: cacheOverBunSqlite(client), orm: drizzle({ client }) };
     }

package/dist/store/sqlite/schema.d.ts

@@ -16637,6 +16637,123 @@ export declare const mentionPending: import("drizzle-orm/sqlite-core").SQLiteTab
     dialect: 'sqlite';
     isAlias: false;
 }>;
+/**
+ * One sqlite-vec `vec0` table per embedding model, `vector_index_<id>`, created at run time with its trigger since
+ * its width is the model's: a row per chunk with a vector of that model, rowid `chunks.id` (`vector-index.ts`).
+ */
+export declare const vectorIndexes: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "vector_indexes";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "vector_indexes";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        model: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "vector_indexes";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        dims: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "vector_indexes";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        ready: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "vector_indexes";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+        filledThrough: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "vector_indexes";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: 'sqlite';
+    isAlias: false;
+}>;
+/** Always empty: each changed chunk's id passes through it so that every model's index re-derives its row. */
+export declare const vectorIndexRedo: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "vector_index_redo";
+    schema: undefined;
+    columns: {
+        chunkId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: string;
+            tableName: "vector_index_redo";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}>;
+    };
+    dialect: 'sqlite';
+    isAlias: false;
+}>;
 /** Settings of the store file itself, shared by every profile, tg and MAX — unlike a profile's config file. */
 export declare const storeSettings: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
     name: "store_settings";

package/dist/store/sqlite/schema.js

@@ -1684,6 +1684,23 @@ export const mentionPending = sqliteTable("mention_pending", {
     sourceType: text("source_type").notNull(),
     sourceId: integer("source_id").notNull(),
 }, (table) => [primaryKey({ columns: [table.sourceType, table.sourceId] })]);
+/**
+ * One sqlite-vec `vec0` table per embedding model, `vector_index_<id>`, created at run time with its trigger since
+ * its width is the model's: a row per chunk with a vector of that model, rowid `chunks.id` (`vector-index.ts`).
+ */
+export const vectorIndexes = sqliteTable("vector_indexes", {
+    id: integer("id").primaryKey(),
+    model: text("model").notNull().unique(),
+    dims: integer("dims").notNull(),
+    /** 1 once it holds every vector; until then searches scan. */
+    ready: integer("ready").notNull(),
+    /** The last `content_hash` the fill of older vectors reached. */
+    filledThrough: text("filled_through").notNull(),
+});
+/** Always empty: each changed chunk's id passes through it so that every model's index re-derives its row. */
+export const vectorIndexRedo = sqliteTable("vector_index_redo", {
+    chunkId: integer("chunk_id").notNull(),
+});
 /** Settings of the store file itself, shared by every profile, tg and MAX — unlike a profile's config file. */
 export const storeSettings = sqliteTable("store_settings", {
     key: text("key").primaryKey(),

package/dist/store/sqlite/vector-index.d.ts

@@ -0,0 +1,67 @@
+import type { CacheDatabase } from "../driver.js";
+/**
+ * Every stored vector has length one, so the scan's dot product and the index's cosine rank alike. A model that
+ * already gives unit vectors (e5, the API models) changes by float rounding only. A zero vector (a text the model
+ * knows nothing of) stays zero: vec0 puts it first with no distance, so it is always among the candidates and scores
+ * 0 both ways.
+ */
+export declare const unitVector: (vector: Float32Array) => Float32Array;
+export interface VectorIndex {
+    table: string;
+    dims: number;
+    ready: boolean;
+}
+export declare const vectorIndexOf: (database: CacheDatabase, model: string) => VectorIndex | undefined;
+/**
+ * The model's index, made on its first vector. A model that already has vectors (an older store) is filled by
+ * `fillVectorIndexes` in short batches, and searched by scan until it is ready.
+ */
+export declare const ensureVectorIndex: (database: CacheDatabase, model: string, dims: number) => void;
+/**
+ * Indexes the vectors a store held before its index existed, in hash order from where the last batch stopped. Rows
+ * the triggers wrote meanwhile are skipped. Returns the models it filled.
+ */
+export declare const fillVectorIndexes: (database: CacheDatabase, { batch, notice }?: {
+    batch?: number;
+    notice?: (model: string) => void;
+}) => string[];
+export interface IndexFilter {
+    kind: string;
+    account: number;
+    chat?: number;
+    since?: number;
+    before?: number;
+}
+export interface Candidate {
+    id: number;
+    hash: string;
+    /** None for a zero vector. */
+    distance: number | null;
+}
+/**
+ * The best `limit` results by the index, or `undefined` when the caller must scan: no ready index for the model, or
+ * no exact answer within the most candidates vec0 returns. `survivors` applies the scan's own SQL to the candidates,
+ * in the scan's order (and checks each one's hash, so a reused chunk id is never taken for the old chunk), scores
+ * them, and names the chunks behind its best `limit` results. Those are exact once each is nearer than the last
+ * candidate by more than `NEAR_TIE`: every row nearer than that is among the candidates, and the rest cannot outrank
+ * them even where float32 and float64 disagree. A text many
+ * chunks share has one vector, so a tie that crosses the last candidate asks for more, as the scan's order decides it.
+ */
+export declare const searchIndex: <T>(database: CacheDatabase, model: string, filter: IndexFilter, query: Float32Array, limit: number, survivors: (candidates: Candidate[]) => {
+    results: T[];
+    best: number[];
+}) => T[] | undefined;
+/**
+ * Per model, `store check`'s safety net: the rows its index holds against the rows `source` derives now, compared
+ * whole (chunk, kind, account, chat, time, hash, vector) both ways. `missing` are rows the index lacks or holds
+ * wrong; `extra` rows it should not hold.
+ */
+export declare const vectorIndexCounts: (database: CacheDatabase) => {
+    model: string;
+    dims: number;
+    ready: boolean;
+    indexed: number;
+    expected: number;
+    missing: number;
+    extra: number;
+}[];

package/dist/store/sqlite/vector-index.js

@@ -0,0 +1,180 @@
+import { CliError } from "@wirecat/cli-base";
+import { writeBatch } from "./transaction.js";
+/**
+ * One sqlite-vec `vec0` table per embedding model, a row per chunk that has a vector of that model: rowid is
+ * `chunks.id`. The static triggers of store version 34 push every changed chunk id through `vector_index_redo`, and
+ * each model's own trigger re-derives that chunk's row, so every writer — the store's functions, the schema's own
+ * delete triggers, a raw `DELETE` — keeps the index in step inside its own transaction.
+ *
+ * `kind` and `account` are partition keys, `occurred_at` and `chat` metadata: the filters a KNN query applies before
+ * it ranks. `account`, `chat` and `occurred_at` are the columns each kind's scan filters on, so the index never
+ * leaves out a row the scan would keep; filters it cannot express are checked on the candidates after.
+ */
+const source = (model, dims) => `SELECT k.id, k.chunkable_type,
+    coalesce(CASE k.chunkable_type
+      WHEN 'image' THEN (SELECT ch.account_id FROM attachments a JOIN messages m ON m.id = a.attachable_id
+        JOIN chats ch ON ch.id = m.chat_id WHERE a.id = k.chunkable_id AND a.attachable_type = 'message')
+      WHEN 'conversation' THEN (SELECT ch.account_id FROM conversations c JOIN chats ch ON ch.id = c.chat_id
+        WHERE c.id = k.chunkable_id)
+      ELSE k.account_id END, 0),
+    coalesce(CASE k.chunkable_type
+      WHEN 'message' THEN (SELECT m.chat_id FROM messages m WHERE m.id = k.chunkable_id)
+      WHEN 'image' THEN (SELECT m.chat_id FROM attachments a JOIN messages m ON m.id = a.attachable_id
+        WHERE a.id = k.chunkable_id AND a.attachable_type = 'message')
+      WHEN 'conversation' THEN (SELECT c.chat_id FROM conversations c WHERE c.id = k.chunkable_id) END, 0),
+    coalesce(CASE k.chunkable_type
+      WHEN 'message' THEN (SELECT m.sent_at FROM messages m WHERE m.id = k.chunkable_id)
+      ELSE k.occurred_at END, 0),
+    v.vector, k.content_hash
+  FROM chunks k JOIN embeddings v ON v.model = ${literal(model)} AND v.content_hash = k.content_hash
+    AND length(v.vector) = ${dims * 4}`;
+/**
+ * Every stored vector has length one, so the scan's dot product and the index's cosine rank alike. A model that
+ * already gives unit vectors (e5, the API models) changes by float rounding only. A zero vector (a text the model
+ * knows nothing of) stays zero: vec0 puts it first with no distance, so it is always among the candidates and scores
+ * 0 both ways.
+ */
+export const unitVector = (vector) => {
+    let sum = 0;
+    for (const value of vector)
+        sum += value * value;
+    const length = Math.sqrt(sum);
+    if (!Number.isFinite(length))
+        throw new CliError("validation_error", "a vector must have finite values", { reason: "store.vector-invalid" });
+    return length === 0 ? vector : vector.map((value) => value / length);
+};
+const literal = (text) => `'${text.replaceAll("'", "''")}'`;
+const COLUMNS = "rowid, kind, account, chat, occurred_at, embedding, hash";
+const tableOf = (id) => `vector_index_${id}`;
+export const vectorIndexOf = (database, model) => {
+    const row = database.prepare("SELECT id, dims, ready FROM vector_indexes WHERE model = ?").get(model);
+    return row && { table: tableOf(Number(row.id)), dims: Number(row.dims), ready: row.ready === 1 };
+};
+/**
+ * The model's index, made on its first vector. A model that already has vectors (an older store) is filled by
+ * `fillVectorIndexes` in short batches, and searched by scan until it is ready.
+ */
+export const ensureVectorIndex = (database, model, dims) => {
+    if (vectorIndexOf(database, model))
+        return;
+    const held = database.prepare("SELECT 1 FROM embeddings WHERE model = ? LIMIT 1").get(model) !== undefined;
+    const id = Number(database
+        .prepare("INSERT INTO vector_indexes (model, dims, ready, filled_through) VALUES (?, ?, ?, '') RETURNING id")
+        .get(model, dims, held ? 0 : 1)?.id);
+    const table = tableOf(id);
+    database.exec(`CREATE VIRTUAL TABLE ${table} USING vec0(kind text partition key, account integer partition key,
+    chat integer, occurred_at integer, embedding float[${dims}] distance_metric=cosine, +hash text)`);
+    database.exec(`CREATE TRIGGER ${table}_redo AFTER INSERT ON vector_index_redo BEGIN
+    DELETE FROM ${table} WHERE rowid = new.chunk_id;
+    INSERT INTO ${table} (${COLUMNS}) ${source(model, dims)} WHERE k.id = new.chunk_id;
+  END`);
+};
+/** The models with vectors and no index, by a walk of the primary key rather than a scan of every vector. */
+const modelsWithoutIndex = (database) => database
+    .prepare(`WITH RECURSIVE m(model) AS (SELECT min(model) FROM embeddings
+         UNION ALL SELECT (SELECT min(model) FROM embeddings WHERE model > m.model) FROM m WHERE m.model IS NOT NULL)
+       SELECT m.model, (SELECT dims FROM embeddings WHERE model = m.model LIMIT 1) AS dims FROM m
+       WHERE m.model IS NOT NULL AND NOT EXISTS (SELECT 1 FROM vector_indexes i WHERE i.model = m.model)`)
+    .all();
+/** Hashes per batch: a batch is one short write transaction, so other processes wait less than their timeout. */
+const FILL_HASHES = 1_000;
+/**
+ * Indexes the vectors a store held before its index existed, in hash order from where the last batch stopped. Rows
+ * the triggers wrote meanwhile are skipped. Returns the models it filled.
+ */
+export const fillVectorIndexes = (database, { batch = FILL_HASHES, notice = () => { } } = {}) => {
+    for (const { model, dims } of modelsWithoutIndex(database))
+        writeBatch(database, () => ensureVectorIndex(database, model, Number(dims)));
+    const pending = database
+        .prepare("SELECT id, model, dims, filled_through FROM vector_indexes WHERE ready = 0 ORDER BY id")
+        .all();
+    for (const { id, model, dims, filled_through } of pending) {
+        notice(model);
+        const table = tableOf(id);
+        const step = database.prepare(`INSERT INTO ${table} (${COLUMNS}) ${source(model, dims)}
+        WHERE k.content_hash IN (SELECT value FROM json_each(?)) AND NOT EXISTS (SELECT 1 FROM ${table} WHERE rowid = k.id)`);
+        const hashes = database.prepare("SELECT content_hash AS hash FROM embeddings WHERE model = ? AND content_hash > ? ORDER BY content_hash LIMIT ?");
+        let after = filled_through;
+        for (;;) {
+            const done = writeBatch(database, () => {
+                const page = hashes.all(model, after, batch).map(({ hash }) => hash);
+                if (page.length > 0)
+                    step.run(JSON.stringify(page));
+                after = page.at(-1) ?? after;
+                const finished = page.length < batch;
+                // Another process may be filling too: neither moves the other back, nor un-readies a finished index.
+                database
+                    .prepare("UPDATE vector_indexes SET filled_through = ?, ready = ? WHERE id = ? AND ready = 0 AND filled_through <= ?")
+                    .run(after, finished ? 1 : 0, id, after);
+                return finished;
+            });
+            if (done)
+                break;
+        }
+    }
+    return pending.map(({ model }) => model);
+};
+/**
+ * vec0 measures in float32 and the scan in float64, so two results closer than this may swap. Far above float32's
+ * error at these lengths, far below any distance that matters for ranking.
+ */
+const NEAR_TIE = 1e-5;
+/** vec0 refuses a k above this. */
+const MAX_K = 4_096;
+const knn = (database, index, filter, query, k) => database
+    .prepare(`SELECT rowid AS id, hash, distance FROM ${index.table} WHERE embedding MATCH ? AND k = ? AND kind = ? AND account = ?
+        ${filter.chat === undefined ? "" : "AND chat = ?"}
+        ${filter.since === undefined ? "" : "AND occurred_at >= ?"}
+        ${filter.before === undefined ? "" : "AND occurred_at < ?"}`)
+    .all(new Uint8Array(query.buffer, query.byteOffset, query.byteLength), BigInt(k), filter.kind, 
+// node:sqlite binds a JS number as REAL, which vec0's integer columns refuse.
+BigInt(filter.account), ...[filter.chat, filter.since, filter.before].flatMap((value) => (value === undefined ? [] : [BigInt(value)])));
+/**
+ * The best `limit` results by the index, or `undefined` when the caller must scan: no ready index for the model, or
+ * no exact answer within the most candidates vec0 returns. `survivors` applies the scan's own SQL to the candidates,
+ * in the scan's order (and checks each one's hash, so a reused chunk id is never taken for the old chunk), scores
+ * them, and names the chunks behind its best `limit` results. Those are exact once each is nearer than the last
+ * candidate by more than `NEAR_TIE`: every row nearer than that is among the candidates, and the rest cannot outrank
+ * them even where float32 and float64 disagree. A text many
+ * chunks share has one vector, so a tie that crosses the last candidate asks for more, as the scan's order decides it.
+ */
+export const searchIndex = (database, model, filter, query, limit, survivors) => {
+    const index = vectorIndexOf(database, model);
+    if (!index?.ready || index.dims !== query.length)
+        return undefined;
+    let k = Math.min(MAX_K, Math.max(100, limit * 4));
+    for (;;) {
+        const candidates = knn(database, index, filter, query, k);
+        const { results, best } = survivors(candidates);
+        if (candidates.length < k)
+            return results;
+        const edge = candidates.at(-1)?.distance ?? null;
+        const distance = new Map(candidates.map((candidate) => [candidate.id, candidate.distance]));
+        // A last candidate with no distance is a zero vector: nothing is known to be nearer yet.
+        const nearer = (id) => edge !== null && (distance.get(id) ?? edge) < edge - NEAR_TIE;
+        if (best.length >= limit && best.every(nearer))
+            return results;
+        if (k === MAX_K)
+            return undefined;
+        k = Math.min(MAX_K, k * 4);
+    }
+};
+/**
+ * Per model, `store check`'s safety net: the rows its index holds against the rows `source` derives now, compared
+ * whole (chunk, kind, account, chat, time, hash, vector) both ways. `missing` are rows the index lacks or holds
+ * wrong; `extra` rows it should not hold.
+ */
+export const vectorIndexCounts = (database) => database.prepare("SELECT id, model, dims, ready FROM vector_indexes ORDER BY id").all().map(({ id, model, dims, ready }) => {
+    const held = `SELECT ${COLUMNS} FROM ${tableOf(id)}`;
+    const wanted = source(model, Number(dims));
+    const count = (sql) => Number(database.prepare(`SELECT count(*) AS n FROM (${sql})`).get()?.n ?? 0);
+    return {
+        model,
+        dims: Number(dims),
+        ready: ready === 1,
+        indexed: count(held),
+        expected: count(wanted),
+        missing: count(`${wanted} EXCEPT ${held}`),
+        extra: count(`${held} EXCEPT ${wanted}`),
+    };
+});

package/dist/store/sqlite/vectors.d.ts

@@ -36,8 +36,11 @@ export declare const conversationVectors: (context: StoreContext, conversationPk
     chunks: number;
     vectors: Float32Array[];
 };
-/** A vector already there for the same model and text is kept: the same text gives the same vector. */
-export declare const saveVectors: ({ orm, now }: StoreContext, model: string, dims: number, vectors: {
+/**
+ * A vector already there for the same model and text is kept: the same text gives the same vector. Each is stored at
+ * length one; a zero or non-finite vector is refused.
+ */
+export declare const saveVectors: ({ orm, now, database }: StoreContext, model: string, dims: number, vectors: {
     hash: string;
     vector: Float32Array;
 }[]) => void;
@@ -65,7 +68,7 @@ export declare const dot: (query: Float32Array, blob: Uint8Array) => number;
  * The conversations of the current builds in scope nearest to `query`, best first: each scored by its
  * best chunk. Vectors are unit length, so the dot product is the cosine (phase 5 E3).
  */
-export declare const nearestChunks: ({ orm }: StoreContext, accountPk: number, { chatKey, model, since, limit, query, exclude, conversations, scope, projectId, before, personId, }: {
+export declare const nearestChunks: (context: StoreContext, accountPk: number, filter: {
     chatKey?: number;
     model: string;
     since?: number;

package/dist/store/sqlite/vectors.js

@@ -1,5 +1,6 @@
 import { chunkHash, chunkTextOf } from "../../conversations/chunks.js";
 import { sql } from "./drizzle/core.js";
+import { ensureVectorIndex, searchIndex, unitVector } from "./vector-index.js";
 const currentChunks = (chatKey) => sql `SELECT k.content_hash, k.chunkable_id AS conversation_id, r.first_message_id,
     r.last_message_id, r.text_start, r.text_end FROM chunks k JOIN chunk_messages r ON r.chunk_id = k.id
     JOIN conversations c ON k.chunkable_type = 'conversation' AND c.id = k.chunkable_id
@@ -113,10 +114,17 @@ export const conversationVectors = (context, conversationPk, model) => {
         : []);
     return { chunks: rows.length, vectors };
 };
-/** A vector already there for the same model and text is kept: the same text gives the same vector. */
-export const saveVectors = ({ orm, now }, model, dims, vectors) => {
+/**
+ * A vector already there for the same model and text is kept: the same text gives the same vector. Each is stored at
+ * length one; a zero or non-finite vector is refused.
+ */
+export const saveVectors = ({ orm, now, database }, model, dims, vectors) => {
+    if (vectors.length === 0)
+        return;
+    ensureVectorIndex(database, model, dims);
     const at = now();
-    for (const { hash, vector } of vectors) {
+    for (const { hash, vector: given } of vectors) {
+        const vector = unitVector(given);
         orm.run(sql `INSERT INTO embeddings (model, content_hash, dims, vector, created_at, updated_at)
         VALUES (${model}, ${hash}, ${dims}, ${Buffer.from(vector.buffer, vector.byteOffset, vector.byteLength)}, ${at}, ${at})
         ON CONFLICT DO NOTHING`);
@@ -157,14 +165,13 @@ export const dot = (query, blob) => {
  * The conversations of the current builds in scope nearest to `query`, best first: each scored by its
  * best chunk. Vectors are unit length, so the dot product is the cosine (phase 5 E3).
  */
-export const nearestChunks = ({ orm }, accountPk, { chatKey, model, since, limit, query, exclude, conversations, scope, projectId, before, personId, }) => {
-    const best = new Map();
-    let after = { conversation: 0, ordinal: -1 };
-    for (;;) {
-        const rows = orm.all(
-        // CROSS JOIN keeps the chunks first, so each page walks their key; led by the vectors, SQLite re-read and
-        // sorted every one of them per page — 1.3 s against 140 ms at 42k chunks (bench/embeddings/README.md).
-        sql `SELECT k.chunkable_id AS conversation, k.position AS ordinal, r.first_message_id AS first, r.last_message_id AS last,
+export const nearestChunks = (context, accountPk, filter) => {
+    const { orm } = context;
+    const { chatKey, model, since, limit, query, exclude, conversations, scope, projectId, before, personId } = filter;
+    const rows = (page) => orm.all(
+    // CROSS JOIN keeps the chunks first, so each page walks their key; led by the vectors, SQLite re-read and
+    // sorted every one of them per page — 1.3 s against 140 ms at 42k chunks (bench/embeddings/README.md).
+    sql `SELECT k.id, k.chunkable_id AS conversation, k.position AS ordinal, r.first_message_id AS first, r.last_message_id AS last,
           r.text_start AS start, r.text_end AS end, k.content_hash AS hash, v.vector FROM chunks k
         CROSS JOIN conversations c ON c.id = k.chunkable_id
         JOIN chunk_messages r ON r.chunk_id = k.id
@@ -180,29 +187,62 @@ export const nearestChunks = ({ orm }, accountPk, { chatKey, model, since, limit
           ${since === undefined ? sql `` : sql `AND k.occurred_at >= ${since}`}
           ${exclude === undefined ? sql `` : sql `AND c.id <> ${exclude}`}
           ${conversations === undefined ? sql `` : sql `AND c.id IN (SELECT value FROM json_each(${JSON.stringify(conversations)}))`}
-          AND (k.chunkable_id, k.position) > (${after.conversation}, ${after.ordinal})
-        ORDER BY k.chunkable_id, k.position LIMIT ${SCAN_PAGE}`);
-        for (const row of rows) {
-            const score = dot(query, row.vector);
-            const held = best.get(row.conversation);
-            if (!held || score > held.score) {
-                const range = rangeOf(row.start, row.end);
-                best.set(row.conversation, {
-                    conversationPk: row.conversation,
-                    firstMessagePk: row.first,
-                    lastMessagePk: row.last,
-                    ...(range ? { range } : {}),
-                    hash: row.hash,
-                    score,
-                });
-            }
-        }
-        const last = rows.at(-1);
-        if (!last || rows.length < SCAN_PAGE)
+          ${"ids" in page
+        ? sql `AND k.id IN (SELECT value FROM json_each(${JSON.stringify(page.ids)}))
+                  ORDER BY k.chunkable_id, k.position`
+        : sql `AND (k.chunkable_id, k.position) > (${page.after.conversation}, ${page.after.ordinal})
+                  ORDER BY k.chunkable_id, k.position LIMIT ${SCAN_PAGE}`}`);
+    const keepBest = (best, row) => {
+        const score = dot(query, row.vector);
+        const held = best.get(row.conversation);
+        if (held && score <= held.score)
+            return;
+        const range = rangeOf(row.start, row.end);
+        best.set(row.conversation, {
+            id: row.id,
+            conversationPk: row.conversation,
+            firstMessagePk: row.first,
+            lastMessagePk: row.last,
+            ...(range ? { range } : {}),
+            hash: row.hash,
+            score,
+        });
+    };
+    // Stable, so equal scores keep the scan's order, by conversation.
+    const ranked = (found) => found.sort((a, b) => b.score - a.score).slice(0, limit);
+    const plain = (found) => found.map(({ id: _, ...chunk }) => chunk);
+    // The index has no person, project, scope or conversation list; with one of those the scan stays.
+    const indexable = personId === undefined && projectId === undefined && scope === undefined && conversations === undefined;
+    const indexed = indexable &&
+        searchIndex(context.database, model, {
+            kind: "conversation",
+            account: accountPk,
+            ...(chatKey === undefined ? {} : { chat: chatKey }),
+            ...(since === undefined ? {} : { since }),
+            ...(before === undefined ? {} : { before }),
+        }, query, limit, (candidates) => {
+            const hashes = new Map(candidates.map(({ id, hash }) => [id, hash]));
+            const best = new Map();
+            for (const row of rows({ ids: [...hashes.keys()] }))
+                if (hashes.get(row.id) === row.hash)
+                    keepBest(best, row);
+            const results = ranked([...best.values()]);
+            return { results, best: results.map(({ id }) => id) };
+        });
+    if (indexed)
+        return plain(indexed);
+    const best = new Map();
+    let after = { conversation: 0, ordinal: -1 };
+    for (;;) {
+        const page = rows({ after });
+        for (const row of page)
+            keepBest(best, row);
+        const last = page.at(-1);
+        if (!last || page.length < SCAN_PAGE)
             break;
         after = { conversation: last.conversation, ordinal: last.ordinal };
     }
-    return [...best.values()].sort((a, b) => b.score - a.score).slice(0, limit);
+    return plain(ranked([...best.values()]));
 };
 const hasVectorOf = (models) => sql `EXISTS (SELECT 1 FROM chunks k
     JOIN conversations c ON k.chunkable_type = 'conversation' AND c.id = k.chunkable_id

package/dist/store/vector-extension.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The sqlite-vec extension every store connection loads: the vector index's tables and triggers cannot be
+ * read or written without it. It ships in `@wirecat/cli-core-sqlite`, so a missing file is a broken install.
+ */
+export declare const vectorExtension: () => Promise<string>;
+/** Loads the extension into a connection that allows it, then closes the door for SQL's `load_extension()`. */
+export declare const loadVectorExtension: (database: {
+    loadExtension(path: string): void;
+    enableLoadExtension?(allow: boolean): void;
+}, path: string) => void;

package/dist/store/vector-extension.js

@@ -0,0 +1,53 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "@wirecat/cli-base";
+const musl = () => {
+    if (process.platform !== "linux")
+        return false;
+    try {
+        return readFileSync("/proc/self/maps", "utf8").includes("ld-musl");
+    }
+    catch {
+        return false;
+    }
+};
+let found;
+/**
+ * The sqlite-vec extension every store connection loads: the vector index's tables and triggers cannot be
+ * read or written without it. It ships in `@wirecat/cli-core-sqlite`, so a missing file is a broken install.
+ */
+export const vectorExtension = () => {
+    found ??= locate();
+    return found;
+};
+const locate = async () => {
+    const onMusl = musl();
+    const target = `${process.platform}-${process.arch}${onMusl ? "-musl" : ""}`;
+    let path;
+    try {
+        const { extensionFor } = await import("@wirecat/cli-core-sqlite");
+        path = extensionFor({ musl: onMusl });
+    }
+    catch {
+        path = undefined;
+    }
+    if (path === undefined) {
+        found = undefined;
+        throw new CliError("configuration_error", `the message store needs the sqlite-vec extension, and @wirecat/cli-core-sqlite has none for ${target} — ` +
+            "reinstall the CLI so its dependencies install with it (an install that skips optional or native " +
+            "packages leaves it out)", { reason: "store.vector-extension-missing", target });
+    }
+    return path;
+};
+/** Loads the extension into a connection that allows it, then closes the door for SQL's `load_extension()`. */
+export const loadVectorExtension = (database, path) => {
+    try {
+        database.loadExtension(path);
+    }
+    catch (error) {
+        throw new CliError("configuration_error", `the sqlite-vec extension did not load on ${process.platform}-${process.arch} — reinstall the CLI; on macOS ` +
+            "under Bun, @wirecat/cli-core-sqlite's SQLite must be installed, since the system's cannot load extensions", { reason: "store.vector-extension-failed", cause: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        database.enableLoadExtension?.(false);
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.433.0",
+  "version": "0.434.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -177,7 +177,7 @@
     "@resvg/resvg-js": "2.6.2",
     "@valibot/to-json-schema": "1.8.0",
     "@wirecat/cli-core-onnx": "1.0.1",
-    "@wirecat/cli-core-sqlite": "1.0.1",
+    "@wirecat/cli-core-sqlite": "1.1.0",
     "@xmldom/xmldom": "0.9.12",
     "chardet": "2.2.0",
     "defuddle": "0.19.6",