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

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,10 @@ const editable = [
     "importIgnoredDirectories",
     "claudeConfigDir",
     "autoCaptureLanguage",
+    "rerankerEnabled",
+    "rerankerApiUrl",
+    "rerankerModel",
+    "rerankerTimeoutMs",
     ...MEMORY_LIMIT_SETTINGS,
 ];
 /** Keys a project config cannot override, so the page always shows the global value. */
@@ -45,6 +49,11 @@ const globalOnly = [
     "importPathMaps",
     "importIgnoredDirectories",
     "claudeConfigDir",
+    "rerankerEnabled",
+    "rerankerApiUrl",
+    "rerankerModel",
+    "rerankerApiKey",
+    "rerankerTimeoutMs",
 ];
 function readSettingsFile(path) {
     if (!path)
@@ -86,6 +95,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 +120,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/web-server.js

@@ -12,6 +12,7 @@ import { isOlderVersion } from "./version-compare.js";
 import { AUTH_HEADER, getOrCreateAuthToken, isAuthorizedApiRequest } from "./auth-token.js";
 import { WebAuth } from "./web-auth.js";
 import { NODE_HTTP_IDLE_TIMEOUT_MS } from "./request-timeouts.js";
+import { testReranker } from "./reranker-test.js";
 import { handleListTags, handleListKeywords, handleListMemories, handleAddMemory, handleDeleteMemory, handleBulkDelete, handleUpdateMemory, handleSearch, handleStats, handlePinMemory, handleUnpinMemory, handleRunCleanup, handleRunDeduplication, handleDetectMigration, handleRunMigration, handleDetectTagMigration, handleRunTagMigrationBatch, handleGetTagMigrationProgress, handleDeletePrompt, handleBulkDeletePrompts, handleGetUserProfile, handleGetProfileChangelog, handleGetProfileSnapshot, handleRefreshProfile, handleCategoryCleanupApply, handleCategoryCleanupStart, handleCategoryCleanupStatus, handleCategoryCleanupUndo, handleUpdateProfileItem, } from "./api-handlers.js";
 import { routeProfileCleanup } from "./profile-cleanup-routes.js";
 const isBun = typeof globalThis.Bun !== "undefined";
@@ -1043,6 +1044,8 @@ export class WebServer {
                 if (response)
                     return response;
             }
+            if (path === "/api/settings/reranker/test")
+                return testReranker(req, method, remoteAddress);
             if (path === "/api/settings/external-api/test" && method === "POST") {
                 const { testExternalApi } = await import("../importer/web-import-api.js");
                 return this.jsonResponse(await testExternalApi());

package/dist/utils/memory-limits.d.ts

@@ -1,16 +1,14 @@
-/**
- * Shared validation rules for the five memory-limit settings
- * (openspec change memory-context-controls). Pure functions only: values
- * are passed in, so config.ts, the settings writer, and the settings
- * snapshot share one rule set without importing CONFIG. Do not import
- * CONFIG here: many tests stub src/config.js with a partial module.
- */
 export interface MemoryLimitRule {
     /** Settings identifier used by files, requests, and the UI. Nested settings use one dot. */
     readonly setting: string;
     /** JSONC leaf path. A nested setting maps to its leaf, never a literal dotted key. */
     readonly path: readonly string[];
     readonly default: number;
+    /**
+     * Embedder-aware default when the file omits the key. Only
+     * similarityThreshold needs it; the other limits keep `default`.
+     */
+    readonly defaultFor?: (embeddingModel: string | undefined) => number;
     readonly unit: string;
     /** Accepted-values text for error messages and help text. */
     readonly accepted: string;
@@ -22,8 +20,9 @@ export declare const MEMORY_LIMITS: {
     readonly autoCaptureMaxContextBytes: MemoryLimitRule;
     readonly userProfileMaxContextBytes: MemoryLimitRule;
     readonly retrievalMaxTokens: MemoryLimitRule;
+    readonly similarityThreshold: MemoryLimitRule;
 };
-/** The five settings identifiers, in Memory card order. */
+/** The six settings identifiers, in Memory card order. */
 export declare const MEMORY_LIMIT_SETTINGS: readonly string[];
 export declare function getMemoryLimitRule(setting: string): MemoryLimitRule | undefined;
 /**

package/dist/utils/memory-limits.js

@@ -1,18 +1,23 @@
 /**
- * Shared validation rules for the five memory-limit settings
+ * Shared validation rules for the six memory-limit settings
  * (openspec change memory-context-controls). Pure functions only: values
  * are passed in, so config.ts, the settings writer, and the settings
  * snapshot share one rule set without importing CONFIG. Do not import
  * CONFIG here: many tests stub src/config.js with a partial module.
  */
+import { defaultSimilarityThreshold } from "./threshold-default.js";
 function isPositiveSafeInteger(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
 function integerInRange(min, max) {
     return (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
 }
-function rule(setting, path, defaultValue, unit, accepted, isValid) {
-    return { setting, path, default: defaultValue, unit, accepted, isValid };
+/** Any finite number from 0 to 1 inclusive (similarityThreshold). */
+function decimalFrom0To1(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+function rule(setting, path, defaultValue, unit, accepted, isValid, defaultFor) {
+    return { setting, path, default: defaultValue, defaultFor, unit, accepted, isValid };
 }
 export const MEMORY_LIMITS = {
     maxMemories: rule("maxMemories", ["maxMemories"], 10, "results", "positive safe integers", isPositiveSafeInteger),
@@ -20,8 +25,9 @@ export const MEMORY_LIMITS = {
     autoCaptureMaxContextBytes: rule("autoCaptureMaxContextBytes", ["autoCaptureMaxContextBytes"], 131072, "UTF-8 bytes", "integers from 16384 to 16777216", integerInRange(16384, 16777216)),
     userProfileMaxContextBytes: rule("userProfileMaxContextBytes", ["userProfileMaxContextBytes"], 32768, "UTF-8 bytes", "integers from 1024 to 16777216", integerInRange(1024, 16777216)),
     retrievalMaxTokens: rule("retrievalMaxTokens", ["retrievalMaxTokens"], 2000, "approximate tokens", "integers from 256 to 65536", integerInRange(256, 65536)),
+    similarityThreshold: rule("similarityThreshold", ["similarityThreshold"], 0.6, "similarity score", "numbers from 0 to 1", decimalFrom0To1, defaultSimilarityThreshold),
 };
-/** The five settings identifiers, in Memory card order. */
+/** The six settings identifiers, in Memory card order. */
 export const MEMORY_LIMIT_SETTINGS = Object.keys(MEMORY_LIMITS);
 const RULES = MEMORY_LIMITS;
 export function getMemoryLimitRule(setting) {

package/dist/utils/threshold-default.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The embedder-dependent default for similarityThreshold (openspec change
+ * retrieval-threshold-and-reranker). Pure function: callers pass the model
+ * name, so config.ts, the settings writer, and the settings snapshot share
+ * one table without importing CONFIG. Do not import CONFIG here: many tests
+ * stub src/config.js with a partial module.
+ *
+ * Evidence: 0.5 was measured with qwen3-embedding:0.6b only (Experiments 24
+ * to 26). Other embedders keep the historical 0.6 until someone measures
+ * them and adds a line to the list below.
+ */
+export declare function defaultSimilarityThreshold(embeddingModel: string | undefined): number;

package/dist/utils/threshold-default.js

@@ -0,0 +1,22 @@
+/**
+ * The embedder-dependent default for similarityThreshold (openspec change
+ * retrieval-threshold-and-reranker). Pure function: callers pass the model
+ * name, so config.ts, the settings writer, and the settings snapshot share
+ * one table without importing CONFIG. Do not import CONFIG here: many tests
+ * stub src/config.js with a partial module.
+ *
+ * Evidence: 0.5 was measured with qwen3-embedding:0.6b only (Experiments 24
+ * to 26). Other embedders keep the historical 0.6 until someone measures
+ * them and adds a line to the list below.
+ */
+const MEASURED_THRESHOLD_0_5 = new Set([
+    "qwen3-embedding:0.6b",
+    "qwen/qwen3-embedding-0.6b",
+    "qwen/qwen3-embedding-0.6b-gguf:q8_0",
+]);
+const UNMEASURED_THRESHOLD = 0.6;
+export function defaultSimilarityThreshold(embeddingModel) {
+    if (!embeddingModel)
+        return UNMEASURED_THRESHOLD;
+    return MEASURED_THRESHOLD_0_5.has(embeddingModel.toLowerCase()) ? 0.5 : UNMEASURED_THRESHOLD;
+}