om-memory-system 4.24.0-next.147 → 4.25.1

package/dist/services/chat/chat-store.js

@@ -0,0 +1,352 @@
+import { randomUUID } from "node:crypto";
+import { tursoConnectionManager } from "../turso/connection-manager.js";
+import { ChatStoreError, } from "./chat-types.js";
+/** Bump when the tables change, and add the step to `migrate`. */
+export const CHAT_SCHEMA_VERSION = 1;
+export const FOLDER_NAME_MAX = 80;
+export const BULK_DELETE_MAX = 500;
+// The file is copied between computers by hand (ADR-032), so it keeps the
+// default rollback journal: committed data lives in chats.db alone.
+const SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS chat_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS chat_folders (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    name_key TEXT NOT NULL UNIQUE,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`,
+    `CREATE TABLE IF NOT EXISTS chat_conversations (
+    id TEXT PRIMARY KEY,
+    folder_id TEXT REFERENCES chat_folders(id) ON DELETE CASCADE,
+    title TEXT NOT NULL,
+    scope_tag TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL
+  )`,
+    `CREATE TABLE IF NOT EXISTS chat_messages (
+    id TEXT PRIMARY KEY,
+    conversation_id TEXT NOT NULL REFERENCES chat_conversations(id) ON DELETE CASCADE,
+    role TEXT NOT NULL,
+    content TEXT NOT NULL,
+    sources_json TEXT,
+    plan_json TEXT,
+    model TEXT,
+    error_code TEXT,
+    notice TEXT,
+    created_at INTEGER NOT NULL
+  )`,
+    `CREATE INDEX IF NOT EXISTS chat_messages_conversation ON chat_messages(conversation_id, created_at)`,
+    `CREATE INDEX IF NOT EXISTS chat_conversations_folder ON chat_conversations(folder_id)`,
+];
+// Only these fields are written, so a source never carries a folder path or an email.
+const SOURCE_FIELDS = [
+    "label",
+    "kind",
+    "id",
+    "text",
+    "projectName",
+    "projectTag",
+    "createdAt",
+    "tags",
+    "score",
+    "section",
+    "category",
+    "evidence",
+];
+function snapshot(source) {
+    const out = {};
+    for (const field of SOURCE_FIELDS) {
+        if (source[field] !== undefined)
+            out[field] = source[field];
+    }
+    return out;
+}
+function parseJson(value, fallback) {
+    if (typeof value !== "string" || !value)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}
+function toConversation(row) {
+    return {
+        id: String(row.id),
+        folderId: row.folder_id == null ? null : String(row.folder_id),
+        title: String(row.title),
+        scopeTag: row.scope_tag == null ? null : String(row.scope_tag),
+        createdAt: Number(row.created_at),
+        updatedAt: Number(row.updated_at),
+    };
+}
+function toMessage(row) {
+    return {
+        id: String(row.id),
+        conversationId: String(row.conversation_id),
+        role: String(row.role),
+        content: String(row.content),
+        sources: parseJson(row.sources_json, []),
+        plan: parseJson(row.plan_json, null),
+        model: row.model == null ? null : String(row.model),
+        errorCode: row.error_code == null ? null : String(row.error_code),
+        notice: row.notice == null ? null : String(row.notice),
+        createdAt: Number(row.created_at),
+    };
+}
+function folderName(name) {
+    const trimmed = name.trim();
+    if (!trimmed || trimmed.length > FOLDER_NAME_MAX) {
+        throw new ChatStoreError(`Folder names have 1 to ${FOLDER_NAME_MAX} characters`, "invalid");
+    }
+    return { name: trimmed, key: trimmed.toLowerCase() };
+}
+/**
+ * Conversations, messages, and folders in `chats.db`. One instance per file;
+ * every write checks the schema version so a file from a newer OMMS stays
+ * untouched.
+ */
+export class ChatStore {
+    dbPath;
+    connect;
+    readOnly = false;
+    // Strictly increasing timestamps keep "newest first" stable within one millisecond.
+    lastStamp = 0;
+    constructor(dbPath, connect = (path) => tursoConnectionManager.getConnection(path)) {
+        this.dbPath = dbPath;
+        this.connect = connect;
+    }
+    db() {
+        return this.connect(this.dbPath);
+    }
+    now() {
+        this.lastStamp = Math.max(Date.now(), this.lastStamp + 1);
+        return this.lastStamp;
+    }
+    async init() {
+        const db = await this.db();
+        await db.execute(SCHEMA[0]);
+        const row = await db.get("SELECT value FROM chat_meta WHERE key = 'schema_version'");
+        const version = row ? Number(row.value) : 0;
+        if (version > CHAT_SCHEMA_VERSION) {
+            this.readOnly = true;
+            return;
+        }
+        this.readOnly = false;
+        await db.batch(SCHEMA.slice(1).map((sql) => ({ sql })));
+        if (version < CHAT_SCHEMA_VERSION) {
+            await db.run("INSERT INTO chat_meta (key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value", [String(CHAT_SCHEMA_VERSION)]);
+        }
+    }
+    isReadOnly() {
+        return this.readOnly;
+    }
+    writable() {
+        if (this.readOnly) {
+            throw new ChatStoreError("chats.db is from a newer OMMS and is read-only", "read_only");
+        }
+    }
+    async listConversations() {
+        const db = await this.db();
+        const rows = await db.all("SELECT * FROM chat_conversations ORDER BY updated_at DESC, created_at DESC");
+        return rows.map(toConversation);
+    }
+    async getConversation(id) {
+        const db = await this.db();
+        const row = await db.get("SELECT * FROM chat_conversations WHERE id = ?", [id]);
+        if (!row)
+            return null;
+        const messages = await db.all("SELECT * FROM chat_messages WHERE conversation_id = ? ORDER BY created_at, rowid", [id]);
+        return { conversation: toConversation(row), messages: messages.map(toMessage) };
+    }
+    async createConversation(input) {
+        this.writable();
+        const db = await this.db();
+        if (input.folderId)
+            await this.requireFolder(input.folderId);
+        const stamp = this.now();
+        const conversation = {
+            id: randomUUID(),
+            folderId: input.folderId ?? null,
+            title: input.title.trim() || "New chat",
+            scopeTag: input.scopeTag,
+            createdAt: stamp,
+            updatedAt: stamp,
+        };
+        await db.run("INSERT INTO chat_conversations (id, folder_id, title, scope_tag, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?)", [
+            conversation.id,
+            conversation.folderId,
+            conversation.title,
+            conversation.scopeTag,
+            stamp,
+            stamp,
+        ]);
+        return conversation;
+    }
+    async updateConversation(id, set, args) {
+        this.writable();
+        const db = await this.db();
+        const changed = await db.run(`UPDATE chat_conversations SET ${set}, updated_at = ? WHERE id = ?`, [...args, this.now(), id]);
+        if (changed === 0)
+            throw new ChatStoreError("Conversation not found", "not_found");
+    }
+    async renameConversation(id, title) {
+        const trimmed = title.trim();
+        if (!trimmed)
+            throw new ChatStoreError("A title is required", "invalid");
+        await this.updateConversation(id, "title = ?", [trimmed.slice(0, 200)]);
+    }
+    async setConversationScope(id, scopeTag) {
+        await this.updateConversation(id, "scope_tag = ?", [scopeTag]);
+    }
+    async moveConversation(id, folderId) {
+        if (folderId)
+            await this.requireFolder(folderId);
+        await this.updateConversation(id, "folder_id = ?", [folderId]);
+    }
+    async deleteConversation(id) {
+        this.writable();
+        const db = await this.db();
+        const changed = await db.run("DELETE FROM chat_conversations WHERE id = ?", [id]);
+        if (changed === 0)
+            throw new ChatStoreError("Conversation not found", "not_found");
+    }
+    /** Deletes every id or none: an unknown id fails the whole request. */
+    async bulkDeleteConversations(ids) {
+        this.writable();
+        const unique = [...new Set(ids)];
+        if (unique.length === 0 || unique.length > BULK_DELETE_MAX) {
+            throw new ChatStoreError(`Select 1 to ${BULK_DELETE_MAX} conversations`, "invalid");
+        }
+        const db = await this.db();
+        const marks = unique.map(() => "?").join(",");
+        return db.transaction("write", async (tx) => {
+            const found = await tx.execute({
+                sql: `SELECT COUNT(*) AS n FROM chat_conversations WHERE id IN (${marks})`,
+                args: unique,
+            });
+            if (Number(found.rows[0]?.n) !== unique.length) {
+                throw new ChatStoreError("Conversation not found", "not_found");
+            }
+            const result = await tx.execute({
+                sql: `DELETE FROM chat_conversations WHERE id IN (${marks})`,
+                args: unique,
+            });
+            return Number(result.rowsAffected);
+        });
+    }
+    async appendMessage(conversationId, input) {
+        this.writable();
+        const db = await this.db();
+        const stamp = this.now();
+        const sources = (input.sources ?? []).map(snapshot);
+        const message = {
+            id: randomUUID(),
+            conversationId,
+            role: input.role,
+            content: input.content,
+            sources,
+            plan: input.plan ?? null,
+            model: input.model ?? null,
+            errorCode: input.errorCode ?? null,
+            notice: input.notice ?? null,
+            createdAt: stamp,
+        };
+        await db.batch([
+            {
+                sql: "INSERT INTO chat_messages (id, conversation_id, role, content, sources_json, plan_json, model, error_code, notice, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                args: [
+                    message.id,
+                    conversationId,
+                    message.role,
+                    message.content,
+                    sources.length ? JSON.stringify(sources) : null,
+                    message.plan ? JSON.stringify(message.plan) : null,
+                    message.model,
+                    message.errorCode,
+                    message.notice,
+                    stamp,
+                ],
+            },
+            {
+                sql: "UPDATE chat_conversations SET updated_at = ? WHERE id = ?",
+                args: [stamp, conversationId],
+            },
+        ]);
+        return message;
+    }
+    async deleteMessage(id) {
+        this.writable();
+        const db = await this.db();
+        await db.run("DELETE FROM chat_messages WHERE id = ?", [id]);
+    }
+    async countMessages() {
+        const db = await this.db();
+        const row = await db.get("SELECT COUNT(*) AS n FROM chat_messages");
+        return Number(row?.n ?? 0);
+    }
+    async listFolders() {
+        const db = await this.db();
+        const rows = await db.all(`SELECT f.*, (SELECT COUNT(*) FROM chat_conversations c WHERE c.folder_id = f.id) AS n
+       FROM chat_folders f ORDER BY f.name_key`);
+        return rows.map((row) => ({
+            id: String(row.id),
+            name: String(row.name),
+            createdAt: Number(row.created_at),
+            updatedAt: Number(row.updated_at),
+            conversationCount: Number(row.n),
+        }));
+    }
+    async requireFolder(id) {
+        const db = await this.db();
+        if (!(await db.get("SELECT id FROM chat_folders WHERE id = ?", [id]))) {
+            throw new ChatStoreError("Folder not found", "not_found");
+        }
+    }
+    async assertNameFree(key, exceptId) {
+        const db = await this.db();
+        const clash = await db.get("SELECT id FROM chat_folders WHERE name_key = ? AND id != ?", [
+            key,
+            exceptId ?? "",
+        ]);
+        if (clash)
+            throw new ChatStoreError("A folder with this name exists", "conflict");
+    }
+    async createFolder(name) {
+        this.writable();
+        const clean = folderName(name);
+        await this.assertNameFree(clean.key);
+        const db = await this.db();
+        const stamp = this.now();
+        const id = randomUUID();
+        await db.run("INSERT INTO chat_folders (id, name, name_key, created_at, updated_at) VALUES (?, ?, ?, ?, ?)", [id, clean.name, clean.key, stamp, stamp]);
+        return { id, name: clean.name, createdAt: stamp, updatedAt: stamp, conversationCount: 0 };
+    }
+    async renameFolder(id, name) {
+        this.writable();
+        const clean = folderName(name);
+        await this.assertNameFree(clean.key, id);
+        const db = await this.db();
+        const changed = await db.run("UPDATE chat_folders SET name = ?, name_key = ?, updated_at = ? WHERE id = ?", [clean.name, clean.key, this.now(), id]);
+        if (changed === 0)
+            throw new ChatStoreError("Folder not found", "not_found");
+    }
+    /** Deletes the folder and every conversation in it. Returns how many conversations went. */
+    async deleteFolder(id) {
+        this.writable();
+        const db = await this.db();
+        return db.transaction("write", async (tx) => {
+            const count = await tx.execute({
+                sql: "SELECT COUNT(*) AS n FROM chat_conversations WHERE folder_id = ?",
+                args: [id],
+            });
+            const result = await tx.execute({ sql: "DELETE FROM chat_folders WHERE id = ?", args: [id] });
+            if (Number(result.rowsAffected) === 0) {
+                throw new ChatStoreError("Folder not found", "not_found");
+            }
+            return Number(count.rows[0]?.n ?? 0);
+        });
+    }
+}

package/dist/services/chat/chat-types.d.ts

@@ -0,0 +1,59 @@
+/** Shared shapes for the web chat: stored conversations, sources, and the search plan. */
+export type ChatRole = "user" | "assistant";
+/** A source as it was sent to the model, saved with the answer so it still opens later. */
+export interface ChatSource {
+    /** `S1`, `S2`, … for memories; `P1`, `P2`, … for profile items. */
+    label: string;
+    kind: "memory" | "profile";
+    id: string;
+    text: string;
+    projectName?: string;
+    projectTag?: string;
+    createdAt?: number;
+    tags?: string[];
+    score?: number;
+    /** Profile sources only. */
+    section?: "preferences" | "patterns" | "workflows";
+    category?: string;
+    evidence?: string[];
+}
+export interface ChatPlanRecord {
+    queries: string[];
+    tags: string[];
+    profileCategories: string[];
+    /** True when the plan call failed or returned nothing usable. */
+    skipped: boolean;
+}
+/** Shown with an assistant message that is not a normal cited answer. */
+export type ChatNotice = "no_sources" | "insufficient" | "uncited";
+export interface ChatMessage {
+    id: string;
+    conversationId: string;
+    role: ChatRole;
+    content: string;
+    sources: ChatSource[];
+    plan: ChatPlanRecord | null;
+    model: string | null;
+    errorCode: string | null;
+    notice: ChatNotice | null;
+    createdAt: number;
+}
+export interface ChatConversation {
+    id: string;
+    folderId: string | null;
+    title: string;
+    scopeTag: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface ChatFolder {
+    id: string;
+    name: string;
+    createdAt: number;
+    updatedAt: number;
+    conversationCount: number;
+}
+export declare class ChatStoreError extends Error {
+    readonly code: "not_found" | "conflict" | "invalid" | "read_only";
+    constructor(message: string, code: "not_found" | "conflict" | "invalid" | "read_only");
+}

package/dist/services/chat/chat-types.js

@@ -0,0 +1,8 @@
+/** Shared shapes for the web chat: stored conversations, sources, and the search plan. */
+export class ChatStoreError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}

package/dist/services/client.d.ts

@@ -22,6 +22,7 @@ export declare class LocalMemoryClient {
         results: import("./turso/types.js").SearchResult[];
         total: number;
         timing: number;
+        queryVector: Float32Array<ArrayBufferLike>;
         error?: undefined;
     } | {
         success: false;

package/dist/services/client.js

@@ -92,7 +92,10 @@ export class LocalMemoryClient {
         // embedding, and shard reads all await, and a config edit during them must
         // not change this search's limit or reranker target.
         const maxMemories = CONFIG.maxMemories;
+        const keywordBoost = CONFIG.keywordBoost;
         const reranker = rerankSettingsFrom(CONFIG);
+        // The reranker path below always uses the boost: it needs a full pool on the similarity scale.
+        const keywordMode = CONFIG.keywordMode;
         if (CONFIG.rerankerEnabled && !reranker) {
             // On but incomplete: search must keep working, so treat it as off.
             log("Reranker enabled without a URL or model; searching without it", {
@@ -105,7 +108,7 @@ export class LocalMemoryClient {
             const resolved = resolveScopeValue(scope, containerTag);
             const shards = (await Promise.all(resolved.map((ref) => tursoShardManager.getAllShards(ref.scope, ref.hash)))).flat();
             if (shards.length === 0) {
-                return { success: true, results: [], total: 0, timing: 0 };
+                return { success: true, results: [], total: 0, timing: 0, queryVector };
             }
             let results;
             let warnings;
@@ -120,18 +123,20 @@ export class LocalMemoryClient {
                     maxMemories,
                     similarityThreshold: CONFIG.similarityThreshold,
                 }, reranker, {
-                    search: (shardList, vector, tag, limit, threshold, queryText) => tursoVectorSearch.searchAcrossShards(shardList, vector, tag, limit, threshold, queryText),
+                    search: (shardList, vector, tag, limit, threshold, queryText) => tursoVectorSearch.searchAcrossShards(shardList, vector, tag, limit, threshold, queryText, keywordBoost),
                     log: (message, meta) => log(message, meta),
                 }));
             }
             else {
-                ({ results, warnings } = await tursoVectorSearch.searchAcrossShards(shards, queryVector, scope === "all-projects" ? "" : containerTag, maxMemories, CONFIG.similarityThreshold, query));
+                ({ results, warnings } = await tursoVectorSearch.searchAcrossShards(shards, queryVector, scope === "all-projects" ? "" : containerTag, maxMemories, CONFIG.similarityThreshold, query, keywordBoost, keywordMode));
             }
             return {
                 success: true,
                 results,
                 total: results.length,
                 timing: 0,
+                // The embedded prompt, so callers (the profile step) need not embed it again.
+                queryVector,
                 ...(warnings.length > 0 ? { warnings } : {}),
             };
         }

package/dist/services/context.d.ts

@@ -15,5 +15,7 @@ interface MemoriesResponseMinimal {
  * order, and the first oversized memory is shortened with a visible marker.
  * Hosts emit several sections in one request by passing `maxBytes` residuals.
  */
-export declare function formatContextForPrompt(userId: string | null, projectMemories: MemoriesResponseMinimal, budget?: ContextBudgetOptions): Promise<string>;
+export declare function formatContextForPrompt(userId: string | null, projectMemories: MemoriesResponseMinimal, budget?: ContextBudgetOptions, 
+/** The embedded prompt, when there is one. Lets the profile block follow the prompt. */
+queryVector?: ArrayLike<number>): Promise<string>;
 export {};

package/dist/services/context.js

@@ -13,10 +13,12 @@ const HEADER_TEXT = "The following block is reference context injected from the
  * order, and the first oversized memory is shortened with a visible marker.
  * Hosts emit several sections in one request by passing `maxBytes` residuals.
  */
-export async function formatContextForPrompt(userId, projectMemories, budget) {
+export async function formatContextForPrompt(userId, projectMemories, budget, 
+/** The embedded prompt, when there is one. Lets the profile block follow the prompt. */
+queryVector) {
     const blocks = [];
     if (CONFIG.injectProfile && userId) {
-        const profileContext = await getUserProfileContext(userId);
+        const profileContext = await getUserProfileContext(userId, queryVector);
         if (profileContext) {
             blocks.push({
                 prefix: "<user_profile>\n",

package/dist/services/global-config-writer.js

@@ -5,6 +5,7 @@ import { applyEdits, modify, parse } from "jsonc-parser";
 import { getGlobalConfigSourcePath, getGlobalConfigWritePath, validateGlobalConfig, } from "../config.js";
 import { CONFIG_TEMPLATE } from "../config-template.js";
 import { isValidClaudeConfigDir } from "./claude-folder.js";
+import { KEYWORD_MODES } from "../utils/keyword-boost.js";
 import { getMemoryLimitRule } from "../utils/memory-limits.js";
 import { RERANKER_TIMEOUT_MAX_MS, RERANKER_TIMEOUT_MIN_MS } from "./request-timeouts.js";
 const keys = new Set([
@@ -36,6 +37,7 @@ const keys = new Set([
     "userProfileMaxContextBytes",
     "retrievalMaxTokens",
     "similarityThreshold",
+    "keywordMode",
     "rerankerEnabled",
     "rerankerApiUrl",
     "rerankerModel",
@@ -76,6 +78,9 @@ function isValidEdit(key, value) {
         return true;
     if (OPTIONAL_RERANKER_KEYS.includes(key) && value === null)
         return true;
+    // keywordMode: null removes the key, so the mode follows the default again.
+    if (key === "keywordMode")
+        return value === null || KEYWORD_MODES.includes(value);
     // The five opt-in reranker keys (openspec retrieval-threshold-and-reranker).
     if (key === "rerankerEnabled")
         return typeof value === "boolean";
@@ -186,6 +191,7 @@ options = {}) {
                 rerankerApiUrl: "an http:// or https:// URL",
                 rerankerModel: "a non-empty string",
                 rerankerTimeoutMs: `integers from ${RERANKER_TIMEOUT_MIN_MS} to ${RERANKER_TIMEOUT_MAX_MS}`,
+                keywordMode: KEYWORD_MODES.join(" or "),
             };
             throw new Error(["memoryApiKey", "embeddingApiKey", "webServerAuthPassword", "rerankerApiKey"].includes(key)
                 ? `${key} must be an env:// or file:// reference`
@@ -217,7 +223,8 @@ options = {}) {
             const jsoncPath = (getMemoryLimitRule(key)?.path ?? [key]);
             // null is the wire form of "reset to default": remove the key so the
             // value follows the default again (undefined removes in jsonc modify).
-            const jsoncValue = value === null && (getMemoryLimitRule(key) || OPTIONAL_RERANKER_KEYS.includes(key))
+            const jsoncValue = value === null &&
+                (getMemoryLimitRule(key) || OPTIONAL_RERANKER_KEYS.includes(key) || key === "keywordMode")
                 ? undefined
                 : value;
             content = applyEdits(content, modify(content, jsoncPath, jsoncValue, {

package/dist/services/privacy.js

@@ -64,6 +64,6 @@ export function stripPrivateContent(content) {
  * than storing a message that is private in its entirety.
  */
 export function isFullyPrivate(content) {
-    const stripped = stripPrivateContent(content).trim();
-    return stripped === REDACTED || stripped === "";
+    // Several private regions leave several markers, so remove them all.
+    return stripPrivateContent(content).split(REDACTED).join("").trim() === "";
 }

package/dist/services/settings-snapshot.js

@@ -33,6 +33,7 @@ const editable = [
     "rerankerApiUrl",
     "rerankerModel",
     "rerankerTimeoutMs",
+    "keywordMode",
     ...MEMORY_LIMIT_SETTINGS,
 ];
 /** Keys a project config cannot override, so the page always shows the global value. */

package/dist/services/turso/exact-scan.d.ts

@@ -0,0 +1,6 @@
+import type { TursoDb } from "./turso-db.js";
+/** Exact (non-indexed) nearest-neighbour scan, used when `vector_top_k` fails. */
+export declare function exactScanKind(db: TursoDb, queryJson: string, k: number, containerTag: string, columnName: string): Promise<Array<{
+    id: string;
+    similarity: number;
+}>>;

package/dist/services/turso/exact-scan.js

@@ -0,0 +1,23 @@
+import { distanceToSimilarity } from "./vector-utils.js";
+/** Exact (non-indexed) nearest-neighbour scan, used when `vector_top_k` fails. */
+export async function exactScanKind(db, queryJson, k, containerTag, columnName) {
+    const rows = await db.all(containerTag === ""
+        ? `
+      SELECT m.id AS id, vector_distance_cos(m.${columnName}, vector32(?)) AS dist
+      FROM memories m
+      WHERE m.${columnName} IS NOT NULL
+      ORDER BY dist ASC
+      LIMIT ?
+    `
+        : `
+      SELECT m.id AS id, vector_distance_cos(m.${columnName}, vector32(?)) AS dist
+      FROM memories m
+      WHERE m.${columnName} IS NOT NULL AND m.container_tag = ?
+      ORDER BY dist ASC
+      LIMIT ?
+    `, containerTag === "" ? [queryJson, k] : [queryJson, containerTag, k]);
+    return rows.map((row) => ({
+        id: String(row.id),
+        similarity: distanceToSimilarity(Number(row.dist)),
+    }));
+}

package/dist/services/turso/keyword-search.d.ts

@@ -0,0 +1,35 @@
+import type { KeywordMode } from "../../utils/keyword-boost.js";
+import type { TursoDb } from "./turso-db.js";
+/**
+ * FTS5 query for the words of a prompt: lower-case terms from letters and
+ * digits only ("ADR-023" gives `adr` and `023`), each in quotes, joined by OR.
+ * Quoting and the character filter keep prompt text from becoming index
+ * syntax. Returns null when no usable term is left.
+ */
+export declare function buildKeywordQuery(queryText: string | undefined): string | null;
+/**
+ * Similarity after the keyword boost: `base + keywordBoost × score ÷ best`,
+ * where `score` is the memory's match strength and `best` the strongest in the
+ * same search. The share is capped at 1 so the boost never passes
+ * `keywordBoost`, and the result never passes 1.
+ */
+export declare function applyKeywordBoost(base: number, score: number, bestScore: number, keywordBoost: number): number;
+/** Create or rebuild the keyword index of a shard. Idempotent. */
+export declare function ensureKeywordIndex(db: TursoDb): Promise<void>;
+export interface KeywordHits {
+    /** Match strength per memory id; higher is stronger. */
+    scores: Map<string, number>;
+    best: number;
+}
+/**
+ * Memories of one shard that contain a word of the prompt, strongest first.
+ * Returns null when there is nothing to match or the index fails: search then
+ * continues with vector and tag results. The log holds a code and an error
+ * name only, never the prompt or memory text.
+ */
+export declare function searchKeywords(db: TursoDb, queryText: string | undefined, containerTag: string, limit: number): Promise<KeywordHits | null>;
+/**
+ * `base` with the boost for memory `id`; `base` itself when it has no keyword hit
+ * or the mode is `rrf` (rank fusion keeps each memory's own similarity).
+ */
+export declare function boostedSimilarity(base: number, hits: KeywordHits | null, id: string, keywordBoost: number, mode?: KeywordMode): number;