om-memory-system 4.23.0-next.144 → 4.25.0

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

@@ -2,9 +2,12 @@ import { createHash, randomUUID } from "node:crypto";
 import { promises as fs, readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { applyEdits, modify, parse } from "jsonc-parser";
-import { CONFIG_TEMPLATE, getGlobalConfigSourcePath, getGlobalConfigWritePath, validateGlobalConfig, } from "../config.js";
+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([
     "opencodeProvider",
     "opencodeModel",
@@ -33,6 +36,13 @@ const keys = new Set([
     "autoCaptureMaxContextBytes",
     "userProfileMaxContextBytes",
     "retrievalMaxTokens",
+    "similarityThreshold",
+    "keywordMode",
+    "rerankerEnabled",
+    "rerankerApiUrl",
+    "rerankerModel",
+    "rerankerApiKey",
+    "rerankerTimeoutMs",
 ]);
 /**
  * Written only by the embedding apply route, together, after a passing test.
@@ -58,8 +68,37 @@ const MEMORY_PROVIDERS = [
 export function isSecretReference(value) {
     return (typeof value === "string" && /^(env:\/\/[A-Za-z_][A-Za-z0-9_]*|file:\/\/.+)$/.test(value.trim()));
 }
+/** Reranker keys that a null edit removes, the same wire form as a limit reset. */
+const OPTIONAL_RERANKER_KEYS = ["rerankerApiUrl", "rerankerModel", "rerankerApiKey"];
 function isValidEdit(key, value) {
-    // `undefined` removes the key from the file.
+    // `undefined` removes the key from the file. `null` is the wire form of
+    // "reset to default", accepted for the six memory limits and the optional reranker keys.
+    const memoryLimit = getMemoryLimitRule(key);
+    if (memoryLimit && value === null)
+        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";
+    if (key === "rerankerApiUrl") {
+        return value === undefined || (typeof value === "string" && /^https?:\/\/\S+$/.test(value));
+    }
+    if (key === "rerankerModel") {
+        return value === undefined || (typeof value === "string" && value.trim().length > 0);
+    }
+    if (key === "rerankerApiKey") {
+        return value === undefined || isSecretReference(value);
+    }
+    if (key === "rerankerTimeoutMs") {
+        return (typeof value === "number" &&
+            Number.isSafeInteger(value) &&
+            value >= RERANKER_TIMEOUT_MIN_MS &&
+            value <= RERANKER_TIMEOUT_MAX_MS);
+    }
     if (key === "embeddingApiUrl") {
         return value === undefined || (typeof value === "string" && /^https?:\/\/\S+$/.test(value));
     }
@@ -98,8 +137,8 @@ function isValidEdit(key, value) {
     // Entries are checked by the startup validation below.
     if (key === "importPathMaps" || key === "importIgnoredDirectories")
         return Array.isArray(value);
-    // The five memory limits share one validation rule set.
-    const memoryLimit = getMemoryLimitRule(key);
+    // The five memory limits share one validation rule set (six with
+    // similarityThreshold; null means reset, handled above).
     if (memoryLimit)
         return memoryLimit.isValid(value);
     // An empty value clears the field.
@@ -147,11 +186,20 @@ options = {}) {
         if (!isValidEdit(key, value)) {
             // Never echo the value: a rejected memoryApiKey may be a literal key.
             const memoryRule = getMemoryLimitRule(key);
-            throw new Error(["memoryApiKey", "embeddingApiKey", "webServerAuthPassword"].includes(key)
+            const rerankerAccepted = {
+                rerankerEnabled: "boolean",
+                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`
                 : memoryRule
                     ? `Invalid ${key} setting: accepted ${memoryRule.accepted}`
-                    : `Invalid ${key} setting`);
+                    : rerankerAccepted[key]
+                        ? `Invalid ${key} setting: accepted ${rerankerAccepted[key]}`
+                        : `Invalid ${key} setting`);
         }
     }
     const wasQueued = pending > 0;
@@ -173,7 +221,13 @@ options = {}) {
             // A nested limit identifier maps to its JSONC leaf path, so
             // chatMessage.maxMemories writes the leaf, never a literal dotted key.
             const jsoncPath = (getMemoryLimitRule(key)?.path ?? [key]);
-            content = applyEdits(content, modify(content, jsoncPath, value, {
+            // 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) || key === "keywordMode")
+                ? undefined
+                : value;
+            content = applyEdits(content, modify(content, jsoncPath, jsoncValue, {
                 formattingOptions: { insertSpaces: true, tabSize: 2, eol: "\n" },
             }));
         }

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/request-timeouts.d.ts

@@ -9,3 +9,8 @@ export declare const NODE_HTTP_IDLE_TIMEOUT_MS: number;
  * without memory rather than stalling the agent.
  */
 export declare const V2_RETRIEVAL_TIMEOUT_MS = 5000;
+export declare const RERANKER_TIMEOUT_DEFAULT_MS = 4000;
+export declare const RERANKER_TIMEOUT_MIN_MS = 500;
+export declare const RERANKER_TIMEOUT_MAX_MS = 30000;
+/** Candidates the reranker sees per search. A constant until evidence says otherwise. */
+export declare const RERANKER_POOL_SIZE = 50;

package/dist/services/request-timeouts.js

@@ -11,3 +11,11 @@ export const NODE_HTTP_IDLE_TIMEOUT_MS = Math.max(EXTERNAL_PROFILE_CLEANUP_TIMEO
  * without memory rather than stalling the agent.
  */
 export const V2_RETRIEVAL_TIMEOUT_MS = 5_000;
+// Opt-in reranker (openspec change retrieval-threshold-and-reranker). The
+// default keeps total search time inside OpenCode V2's 5-second wait; a user
+// who sets more than 5000 accepts that V2 may send the request with no memory.
+export const RERANKER_TIMEOUT_DEFAULT_MS = 4_000;
+export const RERANKER_TIMEOUT_MIN_MS = 500;
+export const RERANKER_TIMEOUT_MAX_MS = 30_000;
+/** Candidates the reranker sees per search. A constant until evidence says otherwise. */
+export const RERANKER_POOL_SIZE = 50;

package/dist/services/reranker-test.d.ts

@@ -0,0 +1 @@
+export declare function testReranker(req: Request, method: string, remoteAddress: string | undefined): Promise<Response>;

package/dist/services/reranker-test.js

@@ -0,0 +1,94 @@
+/**
+ * The Reranker card's Test route (openspec change
+ * retrieval-threshold-and-reranker, task 6.1). Sends two fixed sample
+ * documents, never real memory text, through the same rerankDocuments the
+ * search uses, and reports success or a failure code only. Same guard rules
+ * as the embedding test route: loopback caller, authorised API request,
+ * JSON body.
+ */
+import { isAuthorizedApiRequest } from "./auth-token.js";
+import { isLoopbackAddress } from "./web-api-auth.js";
+import { resolveSecretValue } from "./secret-resolver.js";
+import { rerankDocuments, RerankError } from "./reranker.js";
+import { RERANKER_TIMEOUT_DEFAULT_MS, RERANKER_TIMEOUT_MAX_MS, RERANKER_TIMEOUT_MIN_MS, } from "./request-timeouts.js";
+// Fixed samples: they carry no user content, so the test never leaks memory
+// text to an unverified server beyond these two strings.
+const TEST_QUERY = "Which document is about the omms reranker test?";
+const TEST_DOCUMENTS = [
+    { id: "sample-1", memory: "This document describes the omms reranker connectivity test." },
+    { id: "sample-2", memory: "This document describes an unrelated topic for comparison." },
+];
+function reject(message) {
+    return Response.json({ error: message }, { status: 400 });
+}
+/** Draft validation mirrors the save route's rules; values are never echoed. */
+function draftSettings(draft) {
+    const url = typeof draft.rerankerApiUrl === "string" ? draft.rerankerApiUrl.trim() : "";
+    if (!/^https?:\/\/\S+$/.test(url)) {
+        return reject("Invalid rerankerApiUrl setting: accepted an http:// or https:// URL");
+    }
+    const model = typeof draft.rerankerModel === "string" ? draft.rerankerModel.trim() : "";
+    if (!model) {
+        return reject("Invalid rerankerModel setting: accepted a non-empty string");
+    }
+    let apiKey;
+    if (draft.rerankerApiKey !== undefined && draft.rerankerApiKey !== "") {
+        const key = draft.rerankerApiKey;
+        if (typeof key !== "string" ||
+            !/^(env:\/\/[A-Za-z_][A-Za-z0-9_]*|file:\/\/.+)$/.test(key.trim())) {
+            return reject("rerankerApiKey must be an env:// or file:// reference");
+        }
+        try {
+            apiKey = resolveSecretValue(key);
+        }
+        catch {
+            return reject("rerankerApiKey could not be resolved");
+        }
+    }
+    let timeoutMs = RERANKER_TIMEOUT_DEFAULT_MS;
+    if (draft.rerankerTimeoutMs !== undefined && draft.rerankerTimeoutMs !== null) {
+        const value = draft.rerankerTimeoutMs;
+        if (typeof value !== "number" ||
+            !Number.isSafeInteger(value) ||
+            value < RERANKER_TIMEOUT_MIN_MS ||
+            value > RERANKER_TIMEOUT_MAX_MS) {
+            return reject(`Invalid rerankerTimeoutMs setting: accepted integers from ${RERANKER_TIMEOUT_MIN_MS} to ${RERANKER_TIMEOUT_MAX_MS}`);
+        }
+        timeoutMs = value;
+    }
+    return { apiUrl: url.replace(/\/+$/, ""), model, apiKey, timeoutMs };
+}
+export async function testReranker(req, method, remoteAddress) {
+    if (method !== "POST") {
+        return Response.json({ error: "Not found" }, { status: 404 });
+    }
+    if (!isLoopbackAddress(remoteAddress) || !isAuthorizedApiRequest(req)) {
+        return Response.json({ error: "Only this machine can test a reranker" }, { status: 403 });
+    }
+    const body = (await req.json().catch(() => null));
+    if (!body || typeof body !== "object") {
+        return reject("A JSON body with the drafted reranker settings is required");
+    }
+    const settings = draftSettings(body);
+    if (settings instanceof Response)
+        return settings;
+    const started = Date.now();
+    try {
+        const { ordered } = await rerankDocuments(settings, TEST_QUERY, TEST_DOCUMENTS);
+        // The spec passes the test only when the relevant sample ranks first.
+        if (ordered[0]?.id !== "sample-1") {
+            return Response.json({
+                success: false,
+                code: "reranker_wrong_order",
+                elapsedMs: Date.now() - started,
+            });
+        }
+        return Response.json({ success: true });
+    }
+    catch (error) {
+        // Success or a failure code only; never prompt or memory text.
+        const code = error instanceof RerankError ? error.code : "reranker_unreachable";
+        const elapsedMs = error instanceof RerankError ? error.elapsedMs : 0;
+        return Response.json({ success: false, code, elapsedMs });
+    }
+}

package/dist/services/reranker.d.ts

@@ -0,0 +1,45 @@
+export interface RerankerSettings {
+    apiUrl: string;
+    model: string;
+    apiKey?: string;
+    timeoutMs: number;
+}
+/** A rerank candidate: the memory text plus the id used to break score ties. */
+export interface RerankCandidate {
+    id: string;
+    memory: string;
+}
+/** Structural input so rerankSettingsFrom works with any config-shaped object. */
+export interface RerankerConfigSlice {
+    rerankerEnabled?: boolean;
+    rerankerApiUrl?: string;
+    rerankerModel?: string;
+    rerankerApiKey?: string;
+    rerankerTimeoutMs?: number;
+}
+/** Codes are metadata-only: safe to log, unlike the query or memory text. */
+export declare class RerankError extends Error {
+    readonly code: "reranker_unreachable" | "reranker_timeout" | "reranker_http_error" | "reranker_invalid_reply";
+    readonly elapsedMs: number;
+    readonly status?: number | undefined;
+    constructor(code: "reranker_unreachable" | "reranker_timeout" | "reranker_http_error" | "reranker_invalid_reply", elapsedMs: number, status?: number | undefined, detail?: string);
+}
+/**
+ * Map a config to reranker settings. Undefined means "off": the switch is
+ * off, or the URL or model is missing (an incomplete setup is treated as
+ * off, never as a broken search). A key reference that does not resolve in
+ * this process sends no Authorization header; the server then answers 401
+ * and the caller falls back.
+ */
+export declare function rerankSettingsFrom(config: RerankerConfigSlice): RerankerSettings | undefined;
+/**
+ * Ask the reranker to order the documents. Throws RerankError on any
+ * failure; the caller falls back to the threshold result. A reply is valid
+ * only when it has one entry per document, each index is an integer inside
+ * the document range and appears once, and each relevance_score is finite.
+ * Partial reranking is never used.
+ */
+export declare function rerankDocuments<T extends RerankCandidate>(settings: RerankerSettings, query: string, documents: T[], fetchImpl?: typeof fetch): Promise<{
+    ordered: T[];
+    scores: number[];
+}>;

package/dist/services/reranker.js

@@ -0,0 +1,133 @@
+/**
+ * Pure client for the opt-in reranker (openspec change
+ * retrieval-threshold-and-reranker). Never imports CONFIG: callers pass the
+ * settings so tests and the search path share one module without stubbing
+ * src/config.js. The endpoint contract matches llama-server --reranking
+ * (path /v1/rerank), Jina, and Cohere-style servers: POST <url>/rerank with
+ * {model, query, documents, top_n}; reply {results: [{index, relevance_score}]}.
+ */
+import { resolveSecretValue } from "./secret-resolver.js";
+import { RERANKER_TIMEOUT_DEFAULT_MS } from "./request-timeouts.js";
+/** Codes are metadata-only: safe to log, unlike the query or memory text. */
+export class RerankError extends Error {
+    code;
+    elapsedMs;
+    status;
+    constructor(code, elapsedMs, status, detail) {
+        // The detail can quote transport text; callers redact the key first.
+        super(detail ? `${code}: ${detail}` : code);
+        this.code = code;
+        this.elapsedMs = elapsedMs;
+        this.status = status;
+        this.name = "RerankError";
+    }
+}
+function redactKey(text, key) {
+    if (!key)
+        return text;
+    return text.split(key).join("[redacted]");
+}
+/** Documents are cut so one long memory cannot dominate the request. */
+const MAX_DOCUMENT_CHARS = 4000;
+/**
+ * Map a config to reranker settings. Undefined means "off": the switch is
+ * off, or the URL or model is missing (an incomplete setup is treated as
+ * off, never as a broken search). A key reference that does not resolve in
+ * this process sends no Authorization header; the server then answers 401
+ * and the caller falls back.
+ */
+export function rerankSettingsFrom(config) {
+    if (!config.rerankerEnabled)
+        return undefined;
+    const apiUrl = config.rerankerApiUrl?.trim();
+    const model = config.rerankerModel?.trim();
+    if (!apiUrl || !model)
+        return undefined;
+    let apiKey;
+    if (config.rerankerApiKey) {
+        try {
+            apiKey = resolveSecretValue(config.rerankerApiKey);
+        }
+        catch {
+            apiKey = undefined;
+        }
+    }
+    return {
+        apiUrl: apiUrl.replace(/\/+$/, ""),
+        model,
+        apiKey,
+        timeoutMs: config.rerankerTimeoutMs ?? RERANKER_TIMEOUT_DEFAULT_MS,
+    };
+}
+/**
+ * Ask the reranker to order the documents. Throws RerankError on any
+ * failure; the caller falls back to the threshold result. A reply is valid
+ * only when it has one entry per document, each index is an integer inside
+ * the document range and appears once, and each relevance_score is finite.
+ * Partial reranking is never used.
+ */
+export async function rerankDocuments(settings, query, documents, fetchImpl = fetch) {
+    const started = Date.now();
+    const elapsed = () => Date.now() - started;
+    const documentsText = documents.map((doc) => doc.memory.slice(0, MAX_DOCUMENT_CHARS));
+    const headers = { "Content-Type": "application/json" };
+    if (settings.apiKey)
+        headers.Authorization = `Bearer ${settings.apiKey}`;
+    let response;
+    try {
+        response = await fetchImpl(`${settings.apiUrl}/rerank`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                model: settings.model,
+                query,
+                documents: documentsText,
+                top_n: documents.length,
+            }),
+            signal: AbortSignal.timeout(settings.timeoutMs),
+        });
+    }
+    catch (error) {
+        const name = error?.name;
+        const detail = error instanceof Error ? error.message : String(error);
+        if (name === "AbortError" || name === "TimeoutError" || /abort/i.test(detail)) {
+            throw new RerankError("reranker_timeout", elapsed(), undefined, "timed out");
+        }
+        throw new RerankError("reranker_unreachable", elapsed(), undefined, redactKey(detail, settings.apiKey));
+    }
+    if (!response.ok) {
+        throw new RerankError("reranker_http_error", elapsed(), response.status);
+    }
+    let results;
+    try {
+        const body = (await response.json());
+        results = body.results;
+    }
+    catch {
+        throw new RerankError("reranker_invalid_reply", elapsed());
+    }
+    if (!Array.isArray(results) || results.length !== documents.length) {
+        throw new RerankError("reranker_invalid_reply", elapsed());
+    }
+    const seen = new Set();
+    const scored = results.map((entry) => {
+        const index = entry?.index;
+        const score = entry?.relevance_score;
+        const indexOk = typeof index === "number" &&
+            Number.isInteger(index) &&
+            index >= 0 &&
+            index < documents.length;
+        const scoreOk = typeof score === "number" && Number.isFinite(score);
+        if (!indexOk || !scoreOk || seen.has(index)) {
+            throw new RerankError("reranker_invalid_reply", elapsed());
+        }
+        seen.add(index);
+        return { index: index, score: score };
+    });
+    // Highest relevance first; ties break by memory id so the order is stable.
+    scored.sort((a, b) => b.score - a.score || documents[a.index].id.localeCompare(documents[b.index].id));
+    return {
+        ordered: scored.map((entry) => documents[entry.index]),
+        scores: scored.map((entry) => entry.score),
+    };
+}

package/dist/services/retrieval-rerank.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The reranker stage of memory search (openspec change
+ * retrieval-threshold-and-reranker, design decision 7). vector-search.ts
+ * sits at its file-size ceiling, so this module wraps the existing shard
+ * search instead of changing it: one shard read with no threshold returns
+ * the best candidates; the reranker reorders them; any failure falls back
+ * to the normal threshold result. Pure plumbing only — the settings and the
+ * search/fetch/log implementations are passed in, never imported from
+ * CONFIG, so tests run without a store or a server.
+ */
+import type { SearchResult, ShardInfo } from "./turso/types.js";
+import { type RerankerSettings } from "./reranker.js";
+/** The shape of tursoVectorSearch.searchAcrossShards, injectable for tests. */
+export type SearchAcrossShards = (shards: ShardInfo[], queryVector: Float32Array, containerTag: string, limit: number, similarityThreshold: number, queryText?: string) => Promise<{
+    results: SearchResult[];
+    warnings: string[];
+}>;
+export interface RerankedSearchOptions {
+    shards: ShardInfo[];
+    queryVector: Float32Array;
+    containerTag: string;
+    queryText: string;
+    maxMemories: number;
+    similarityThreshold: number;
+}
+export interface RerankedSearchDeps {
+    search: SearchAcrossShards;
+    fetchImpl?: typeof fetch;
+    /** Defaults to silence; the real caller passes the shared logger. */
+    log?: (message: string, meta: Record<string, unknown>) => void;
+}
+/**
+ * Search with an optional reranker. The shard search always runs once with a
+ * threshold of 0 and a limit of max(maxMemories, pool size), so the same
+ * read serves the reranked path and the fallback. The candidates come back
+ * sorted by similarity, so applying the threshold and the limit to the same
+ * list reproduces the no-reranker result exactly.
+ */
+export declare function rerankedSearch(options: RerankedSearchOptions, settings: RerankerSettings, deps: RerankedSearchDeps): Promise<{
+    results: SearchResult[];
+    warnings: string[];
+    reranked: boolean;
+}>;

package/dist/services/retrieval-rerank.js

@@ -0,0 +1,42 @@
+import { RERANKER_POOL_SIZE } from "./request-timeouts.js";
+import { rerankDocuments } from "./reranker.js";
+/**
+ * Search with an optional reranker. The shard search always runs once with a
+ * threshold of 0 and a limit of max(maxMemories, pool size), so the same
+ * read serves the reranked path and the fallback. The candidates come back
+ * sorted by similarity, so applying the threshold and the limit to the same
+ * list reproduces the no-reranker result exactly.
+ */
+export async function rerankedSearch(options, settings, deps) {
+    const { search } = deps;
+    const { results: candidates, warnings } = await search(options.shards, options.queryVector, options.containerTag, Math.max(options.maxMemories, RERANKER_POOL_SIZE), 0, options.queryText);
+    // Nothing to reorder: skip the server round trip for an empty search.
+    if (candidates.length === 0)
+        return { results: [], warnings, reranked: false };
+    try {
+        const { ordered } = await rerankDocuments(settings, options.queryText, candidates, deps.fetchImpl);
+        return { results: ordered.slice(0, options.maxMemories), warnings, reranked: true };
+    }
+    catch (error) {
+        // Metadata only: the code, the elapsed time, and the candidate count.
+        // The query and any memory text never reach the log.
+        const code = typeof error?.code === "string"
+            ? error.code
+            : "reranker_unreachable";
+        const elapsedMs = typeof error?.elapsedMs === "number"
+            ? error.elapsedMs
+            : 0;
+        deps.log?.("Reranker failed; returning the threshold result", {
+            code,
+            elapsedMs,
+            candidates: candidates.length,
+        });
+        return {
+            results: candidates
+                .filter((result) => result.similarity >= options.similarityThreshold)
+                .slice(0, options.maxMemories),
+            warnings,
+            reranked: false,
+        };
+    }
+}

package/dist/services/settings-snapshot.js

@@ -29,6 +29,11 @@ const editable = [
     "importIgnoredDirectories",
     "claudeConfigDir",
     "autoCaptureLanguage",
+    "rerankerEnabled",
+    "rerankerApiUrl",
+    "rerankerModel",
+    "rerankerTimeoutMs",
+    "keywordMode",
     ...MEMORY_LIMIT_SETTINGS,
 ];
 /** Keys a project config cannot override, so the page always shows the global value. */
@@ -45,6 +50,11 @@ const globalOnly = [
     "importPathMaps",
     "importIgnoredDirectories",
     "claudeConfigDir",
+    "rerankerEnabled",
+    "rerankerApiUrl",
+    "rerankerModel",
+    "rerankerApiKey",
+    "rerankerTimeoutMs",
 ];
 function readSettingsFile(path) {
     if (!path)
@@ -86,6 +96,8 @@ function nestedMemorySetting(rule, global, project) {
         source: hasValue ? (projectHasParent ? "project" : "global") : "default",
         globalValue: hasGlobal ? globalContainer[leaf] : rule.default,
         default: rule.default,
+        // Whether the leaf exists in the global file: the Reset action needs it.
+        hasGlobal,
     };
 }
 export function getSettingsSnapshot(directory) {
@@ -109,20 +121,30 @@ export function getSettingsSnapshot(directory) {
                 ? "global"
                 : "default";
         const value = projectOverrides ? project[key] : (global[key] ?? runtime[key]);
-        // The five memory limits also carry their documented default for the UI.
+        // The six memory limits also carry their documented default for the UI;
+        // similarityThreshold's default follows the active embedder. hasGlobal
+        // tells the Reset action whether the key exists in the global file.
+        const ruleDefault = limitRule?.defaultFor?.(CONFIG.embeddingModel) ?? limitRule?.default;
         return [
             key,
             limitRule
                 ? {
                     value,
                     source,
-                    globalValue: global[key] ?? limitRule.default,
-                    default: limitRule.default,
+                    globalValue: global[key] ?? ruleDefault,
+                    default: ruleDefault,
+                    hasGlobal: Object.hasOwn(global, key),
                 }
                 : { value, source, globalValue: global[key] ?? runtime[key] },
         ];
     }));
-    const secrets = Object.fromEntries(["memoryApiKey", "embeddingApiKey", "webServerApiToken", "webServerAuthPassword"].map((key) => {
+    const secrets = Object.fromEntries([
+        "memoryApiKey",
+        "embeddingApiKey",
+        "webServerApiToken",
+        "webServerAuthPassword",
+        "rerankerApiKey",
+    ].map((key) => {
         const raw = global[key];
         const source = typeof raw === "string"
             ? raw.startsWith("env://")

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;