memorix 1.7.2 → 1.7.3

package/dist/vector-backfill-runner.js

@@ -176,6 +176,7 @@ function loadYamlConfig(projectRoot) {
     llm: { ...userConfig.llm, ...projectConfig.llm },
     agent: { ...userConfig.agent, ...projectConfig.agent },
     embedding: { ...userConfig.embedding, ...projectConfig.embedding },
+    rerank: { ...userConfig.rerank, ...projectConfig.rerank },
     git: { ...userConfig.git, ...projectConfig.git },
     codegraph: { ...userConfig.codegraph, ...projectConfig.codegraph },
     behavior: { ...userConfig.behavior, ...projectConfig.behavior },
@@ -1836,6 +1837,7 @@ function mergeTomlConfig(base, override) {
       llm: { ...base.memory?.llm, ...override.memory?.llm }
     },
     embedding: { ...base.embedding, ...override.embedding },
+    rerank: { ...base.rerank, ...override.rerank },
     hooks: { ...base.hooks, ...override.hooks },
     git: { ...base.git, ...override.git },
     codegraph: { ...base.codegraph, ...override.codegraph },
@@ -1932,6 +1934,7 @@ __export(resolved_config_exports, {
   getResolvedConfigForCwd: () => getResolvedConfigForCwd,
   getResolvedEmbeddingLane: () => getResolvedEmbeddingLane,
   getResolvedMemoryLane: () => getResolvedMemoryLane,
+  getResolvedRerankLane: () => getResolvedRerankLane,
   resetResolvedConfigCache: () => resetResolvedConfigCache
 });
 import { homedir as homedir5 } from "os";
@@ -1964,6 +1967,16 @@ function getResolvedConfig(options = {}) {
     legacy.llm?.baseUrl
   );
   const openRouterMemoryLlmApiKey = isOpenRouterMemoryLane(memoryLlmProvider, memoryLlmBaseUrl) ? process.env.OPENROUTER_API_KEY : void 0;
+  const memoryLlmApiKey = first(
+    process.env.MEMORIX_LLM_API_KEY,
+    process.env.MEMORIX_API_KEY,
+    toml.memory?.llm?.api_key,
+    yaml.llm?.apiKey,
+    legacy.llm?.apiKey,
+    process.env.OPENAI_API_KEY,
+    process.env.ANTHROPIC_API_KEY,
+    openRouterMemoryLlmApiKey
+  );
   const resolved = {
     agent: {
       provider: first(
@@ -2004,16 +2017,7 @@ function getResolvedConfig(options = {}) {
         provider: memoryLlmProvider,
         model: memoryLlmModel,
         baseUrl: memoryLlmBaseUrl,
-        apiKey: first(
-          process.env.MEMORIX_LLM_API_KEY,
-          process.env.MEMORIX_API_KEY,
-          toml.memory?.llm?.api_key,
-          yaml.llm?.apiKey,
-          legacy.llm?.apiKey,
-          process.env.OPENAI_API_KEY,
-          process.env.ANTHROPIC_API_KEY,
-          openRouterMemoryLlmApiKey
-        )
+        apiKey: memoryLlmApiKey
       }
     },
     embedding: {
@@ -2023,6 +2027,12 @@ function getResolvedConfig(options = {}) {
       apiKey: first(process.env.MEMORIX_EMBEDDING_API_KEY, toml.embedding?.api_key, yaml.embedding?.apiKey, legacy.embeddingApi?.apiKey, openRouterEmbeddingApiKey),
       dimensions: firstNumber(parseNumber(process.env.MEMORIX_EMBEDDING_DIMENSIONS), toml.embedding?.dimensions, yaml.embedding?.dimensions, legacy.embeddingApi?.dimensions)
     },
+    rerank: resolveRerankLane({
+      toml,
+      yaml,
+      memoryLlmApiKey,
+      memoryLlmBaseUrl
+    }),
     git: {
       autoHook: firstBool(toml.git?.auto_hook, yaml.git?.autoHook),
       ingestOnCommit: firstBool(toml.git?.ingest_on_commit, yaml.git?.ingestOnCommit),
@@ -2092,6 +2102,9 @@ function getResolvedMemoryLane(options = {}) {
 function getResolvedEmbeddingLane(options = {}) {
   return getResolvedConfig(options).embedding;
 }
+function getResolvedRerankLane(options = {}) {
+  return getResolvedConfig(options).rerank;
+}
 function resetResolvedConfigCache() {
 }
 function first(...values) {
@@ -2134,6 +2147,10 @@ function getEnvSourceNames() {
     "MEMORIX_EMBEDDING_BASE_URL",
     "MEMORIX_EMBEDDING_MODEL",
     "MEMORIX_EMBEDDING_DIMENSIONS",
+    "MEMORIX_RERANK_PROVIDER",
+    "MEMORIX_RERANK_MODEL",
+    "MEMORIX_RERANK_BASE_URL",
+    "MEMORIX_RERANK_API_KEY",
     "MEMORIX_CODEGRAPH_EXTERNAL_CONTEXT",
     "MEMORIX_CODEGRAPH_EXTERNAL_COMMAND",
     "MEMORIX_CODEGRAPH_EXTERNAL_TIMEOUT_MS",
@@ -2157,6 +2174,63 @@ function normalizeExternalContext(value) {
   if (normalized === "auto" || normalized === "off") return normalized;
   return void 0;
 }
+function normalizeRerankProvider(value) {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "http") return "http";
+  return "off";
+}
+function resolveRerankLane(args) {
+  const provider2 = normalizeRerankProvider(first(
+    process.env.MEMORIX_RERANK_PROVIDER,
+    args.toml.rerank?.provider,
+    args.yaml.rerank?.provider,
+    "off"
+  ));
+  const model = first(
+    process.env.MEMORIX_RERANK_MODEL,
+    args.toml.rerank?.model,
+    args.yaml.rerank?.model
+  );
+  const explicitBaseUrl = first(
+    process.env.MEMORIX_RERANK_BASE_URL,
+    args.toml.rerank?.base_url,
+    args.yaml.rerank?.baseUrl
+  );
+  const baseUrl = provider2 === "http" ? first(explicitBaseUrl, args.memoryLlmBaseUrl) : explicitBaseUrl;
+  const dedicatedApiKey = first(
+    process.env.MEMORIX_RERANK_API_KEY,
+    args.toml.rerank?.api_key,
+    args.yaml.rerank?.apiKey
+  );
+  const sameEndpoint = provider2 === "http" && sameTrustedEndpoint(baseUrl, args.memoryLlmBaseUrl);
+  const inheritedApiKey = sameEndpoint ? args.memoryLlmApiKey : void 0;
+  const apiKey = first(dedicatedApiKey, inheritedApiKey);
+  const canSendRequest = provider2 === "http" && Boolean(baseUrl) && (Boolean(apiKey) || !args.memoryLlmApiKey || sameEndpoint);
+  return { provider: provider2, model, baseUrl, apiKey, canSendRequest };
+}
+function sameTrustedEndpoint(left, right) {
+  const a = normalizeTrustedEndpoint(left);
+  const b = normalizeTrustedEndpoint(right);
+  return Boolean(a && b && a === b);
+}
+function normalizeTrustedEndpoint(value) {
+  const trimmed = value?.trim();
+  if (!trimmed) return void 0;
+  try {
+    const url = new URL(trimmed);
+    const protocol = url.protocol.toLowerCase();
+    const hostname = url.hostname.toLowerCase();
+    const port = url.port;
+    let pathname = url.pathname.replace(/\/+$/, "");
+    if (pathname.toLowerCase().endsWith("/rerank")) {
+      pathname = pathname.slice(0, -"/rerank".length).replace(/\/+$/, "");
+    }
+    return `${protocol}//${hostname}${port ? `:${port}` : ""}${pathname}`;
+  } catch {
+    const fallback = trimmed.replace(/\/+$/, "").replace(/\/rerank$/i, "").replace(/\/+$/, "");
+    return fallback.toLowerCase() || void 0;
+  }
+}
 var init_resolved_config = __esm({
   "src/config/resolved-config.ts"() {
     "use strict";
@@ -4392,9 +4466,27 @@ __export(provider_exports2, {
   getLLMConfig: () => getLLMConfig,
   initLLM: () => initLLM,
   isLLMEnabled: () => isLLMEnabled,
+  normalizeOpenAICompatibleBaseUrl: () => normalizeOpenAICompatibleBaseUrl,
   parseLLMTimeoutMs: () => parseLLMTimeoutMs,
   setLLMConfig: () => setLLMConfig
 });
+function normalizeOpenAICompatibleBaseUrl(baseUrl) {
+  const base = baseUrl.trim().replace(/\/+$/, "");
+  if (!base) return base;
+  let pathname = "";
+  try {
+    pathname = new URL(base).pathname.replace(/\/+$/, "");
+  } catch {
+    pathname = base.split(/[?#]/, 1)[0].replace(/\/+$/, "");
+  }
+  const lastSegment = pathname.split("/").filter(Boolean).at(-1);
+  if (lastSegment && OPENAI_API_VERSION_SEGMENT.test(lastSegment)) {
+    return base;
+  }
+  const queryOrHash = base.match(/[?#].*$/)?.[0] ?? "";
+  const pathWithoutQuery = base.slice(0, base.length - queryOrHash.length).replace(/\/+$/, "");
+  return `${pathWithoutQuery}/v1${queryOrHash}`;
+}
 function parseLLMTimeoutMs(raw) {
   if (raw === void 0 || raw.trim() === "") return LLM_TIMEOUT_DEFAULT_MS;
   const parsed = Number(raw);
@@ -4498,8 +4590,7 @@ async function callLLM(systemPrompt, userMessage, signal) {
 }
 async function callOpenAICompatible(systemPrompt, userMessage, signal) {
   const config = currentConfig;
-  let base = config.baseUrl.replace(/\/+$/, "");
-  if (!base.endsWith("/v1")) base += "/v1";
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl);
   const url = `${base}/chat/completions`;
   const fetchSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(LLM_CALL_TIMEOUT_MS)]) : AbortSignal.timeout(LLM_CALL_TIMEOUT_MS);
   const response = await fetch(url, {
@@ -4578,8 +4669,7 @@ async function callLLMWithTools(messages, tools, signal) {
 }
 async function callOpenAIWithTools(messages, tools, signal) {
   const config = currentConfig;
-  let base = config.baseUrl.replace(/\/+$/, "");
-  if (!base.endsWith("/v1")) base += "/v1";
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl);
   const url = `${base}/chat/completions`;
   const openaiMessages = messages.map((msg) => {
     if (msg.role === "tool") {
@@ -4729,8 +4819,7 @@ async function callAnthropicWithTools(messages, tools, signal) {
 }
 async function* callOpenAIWithToolsStream(messages, tools) {
   const config = currentConfig;
-  let base = config.baseUrl.replace(/\/+$/, "");
-  if (!base.endsWith("/v1")) base += "/v1";
+  const base = normalizeOpenAICompatibleBaseUrl(config.baseUrl);
   const url = `${base}/chat/completions`;
   const openaiMessages = messages.map((msg) => {
     if (msg.role === "tool") {
@@ -4978,7 +5067,7 @@ async function* callAnthropicWithToolsStream(messages, tools) {
     }
   };
 }
-var LLM_TIMEOUT_DEFAULT_MS, LLM_TIMEOUT_MIN_MS, LLM_TIMEOUT_MAX_MS, MAX_LLM_RESPONSE_BYTES, LLM_CALL_TIMEOUT_MS, PROVIDER_DEFAULTS, currentConfig;
+var LLM_TIMEOUT_DEFAULT_MS, LLM_TIMEOUT_MIN_MS, LLM_TIMEOUT_MAX_MS, MAX_LLM_RESPONSE_BYTES, OPENAI_API_VERSION_SEGMENT, LLM_CALL_TIMEOUT_MS, PROVIDER_DEFAULTS, currentConfig;
 var init_provider2 = __esm({
   "src/llm/provider.ts"() {
     "use strict";
@@ -4988,6 +5077,7 @@ var init_provider2 = __esm({
     LLM_TIMEOUT_MIN_MS = 1e3;
     LLM_TIMEOUT_MAX_MS = 3e5;
     MAX_LLM_RESPONSE_BYTES = 2 * 1024 * 1024;
+    OPENAI_API_VERSION_SEGMENT = /^v\d+(?:[a-z][a-z0-9-]*)?$/i;
     LLM_CALL_TIMEOUT_MS = parseLLMTimeoutMs(process.env.MEMORIX_LLM_TIMEOUT_MS);
     PROVIDER_DEFAULTS = {
       openai: { baseUrl: "https://api.openai.com/v1", model: "gpt-4.1-nano" },
@@ -5047,6 +5137,48 @@ Rules:
   }
 });
 
+// src/rerank/policy.ts
+function parseRerankTimeoutMs(raw) {
+  const value = raw?.trim();
+  if (!value) return DEFAULT_RERANK_TIMEOUT_MS;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || Number.isNaN(parsed)) {
+    console.warn(
+      `[memorix] MEMORIX_RERANK_TIMEOUT_MS="${raw}" is invalid (must be a positive integer between ${RERANK_TIMEOUT_MIN_MS}-${RERANK_TIMEOUT_MAX_MS}ms). Using default ${DEFAULT_RERANK_TIMEOUT_MS}ms.`
+    );
+    return DEFAULT_RERANK_TIMEOUT_MS;
+  }
+  if (parsed < RERANK_TIMEOUT_MIN_MS) return RERANK_TIMEOUT_MIN_MS;
+  if (parsed > RERANK_TIMEOUT_MAX_MS) return RERANK_TIMEOUT_MAX_MS;
+  return parsed;
+}
+function resolveRerankTimeoutMs(explicitTimeoutMs) {
+  if (typeof explicitTimeoutMs === "number" && Number.isFinite(explicitTimeoutMs) && explicitTimeoutMs > 0) {
+    return explicitTimeoutMs;
+  }
+  return parseRerankTimeoutMs(process.env.MEMORIX_RERANK_TIMEOUT_MS);
+}
+function shouldAttemptHttpRerank(input) {
+  return input.quality === "thorough" && input.hasQuery && input.candidateCount >= MIN_RERANK_CANDIDATES;
+}
+function shouldAttemptLlmRerank(input) {
+  if (input.httpRerankConfigured) return false;
+  if (input.quality !== "thorough" || input.tier !== "heavy" || !input.hasQuery) return false;
+  if (input.candidateCount < MIN_RERANK_CANDIDATES) return false;
+  return input.topScore > 0 && input.secondScore / input.topScore > 0.7;
+}
+var DEFAULT_RERANK_TIMEOUT_MS, RERANK_TIMEOUT_MIN_MS, RERANK_TIMEOUT_MAX_MS, MIN_RERANK_CANDIDATES;
+var init_policy = __esm({
+  "src/rerank/policy.ts"() {
+    "use strict";
+    init_esm_shims();
+    DEFAULT_RERANK_TIMEOUT_MS = 3e4;
+    RERANK_TIMEOUT_MIN_MS = 1e3;
+    RERANK_TIMEOUT_MAX_MS = 3e5;
+    MIN_RERANK_CANDIDATES = 3;
+  }
+});
+
 // src/timeout.ts
 function withTimeout(promise, ms, label) {
   return new Promise((resolve, reject) => {
@@ -5332,6 +5464,148 @@ var init_aliases = __esm({
   }
 });
 
+// src/rerank/http-provider.ts
+function buildRerankUrl(baseUrl) {
+  const trimmed = baseUrl.trim().replace(/\/+$/, "");
+  if (trimmed.endsWith("/rerank")) return trimmed;
+  return `${trimmed}/rerank`;
+}
+function parseRerankResponse(payload) {
+  const rows = extractRows(payload);
+  if (rows.length === 0) {
+    throw new Error("Neural rerank response contained no ranked results");
+  }
+  return rows.sort((a, b) => b.score - a.score);
+}
+function extractRows(payload) {
+  if (Array.isArray(payload)) {
+    return payload.map(rowFromUnknown).filter((row) => row !== null);
+  }
+  if (payload && typeof payload === "object" && "results" in payload) {
+    const results = payload.results;
+    if (Array.isArray(results)) {
+      return results.map(rowFromUnknown).filter((row) => row !== null);
+    }
+  }
+  throw new Error("Neural rerank response was not Cohere or TEI shaped");
+}
+function rowFromUnknown(value) {
+  if (!value || typeof value !== "object") return null;
+  const row = value;
+  if (typeof row.index !== "number" || !Number.isFinite(row.index)) return null;
+  const score = typeof row.relevance_score === "number" ? row.relevance_score : typeof row.score === "number" ? row.score : null;
+  if (score === null || !Number.isFinite(score)) return null;
+  return { index: row.index, score };
+}
+function buildRerankBody(query, documents, model) {
+  const body = {
+    query,
+    documents,
+    top_n: documents.length,
+    return_documents: false
+  };
+  const trimmed = model?.trim();
+  if (trimmed) body.model = trimmed;
+  return body;
+}
+async function rerankViaHttp(query, documents, config) {
+  if (documents.length === 0) return [];
+  const url = buildRerankUrl(config.baseUrl);
+  const headers = {
+    "content-type": "application/json"
+  };
+  if (config.apiKey) {
+    headers.authorization = `Bearer ${config.apiKey}`;
+  }
+  const controller = new AbortController();
+  const timeoutMs = resolveRerankTimeoutMs(config.timeoutMs);
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const fetchImpl = config.fetchImpl ?? fetch;
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers,
+      signal: controller.signal,
+      body: JSON.stringify(buildRerankBody(query, documents, config.model))
+    });
+    if (!response.ok) {
+      throw new Error(`Neural rerank HTTP ${response.status} from ${url}`);
+    }
+    return parseRerankResponse(await response.json());
+  } finally {
+    clearTimeout(timer);
+  }
+}
+var init_http_provider = __esm({
+  "src/rerank/http-provider.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_policy();
+  }
+});
+
+// src/rerank/index.ts
+var rerank_exports = {};
+__export(rerank_exports, {
+  DEFAULT_RERANK_TIMEOUT_MS: () => DEFAULT_RERANK_TIMEOUT_MS,
+  MIN_RERANK_CANDIDATES: () => MIN_RERANK_CANDIDATES,
+  isNeuralRerankEnabled: () => isNeuralRerankEnabled,
+  neuralRerankCandidates: () => neuralRerankCandidates,
+  parseRerankTimeoutMs: () => parseRerankTimeoutMs,
+  resolveRerankTimeoutMs: () => resolveRerankTimeoutMs,
+  shouldAttemptHttpRerank: () => shouldAttemptHttpRerank,
+  shouldAttemptLlmRerank: () => shouldAttemptLlmRerank
+});
+function isNeuralRerankEnabled(options = {}) {
+  const lane = getResolvedRerankLane(options);
+  return lane.provider === "http" && Boolean(lane.baseUrl);
+}
+async function neuralRerankCandidates(query, candidates, options = {}) {
+  if (!isNeuralRerankEnabled(options) || candidates.length === 0) return null;
+  const lane = getResolvedRerankLane(options);
+  if (!lane.canSendRequest || !lane.baseUrl) return null;
+  const toRerank = candidates.slice(0, MAX_RERANK);
+  const rest = candidates.slice(MAX_RERANK);
+  const documents = toRerank.map((candidate) => candidateText(candidate));
+  const ranked = await rerankViaHttp(query, documents, {
+    provider: "http",
+    model: lane.model,
+    baseUrl: lane.baseUrl,
+    apiKey: lane.apiKey,
+    timeoutMs: resolveRerankTimeoutMs()
+  });
+  const seen = /* @__PURE__ */ new Set();
+  const reranked = [];
+  for (const row of ranked) {
+    const candidate = toRerank[row.index];
+    if (!candidate || seen.has(row.index)) continue;
+    reranked.push(candidate);
+    seen.add(row.index);
+  }
+  for (const [index, candidate] of toRerank.entries()) {
+    if (!seen.has(index)) reranked.push(candidate);
+  }
+  reranked.push(...rest);
+  return reranked;
+}
+function candidateText(candidate) {
+  const narrative = candidate.narrative?.trim();
+  if (narrative) return `${candidate.title} \u2014 ${narrative.slice(0, 200)}`;
+  return candidate.title;
+}
+var MAX_RERANK;
+var init_rerank = __esm({
+  "src/rerank/index.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_resolved_config();
+    init_http_provider();
+    init_policy();
+    init_policy();
+    MAX_RERANK = 10;
+  }
+});
+
 // src/llm/quality.ts
 var quality_exports = {};
 __export(quality_exports, {
@@ -5371,9 +5645,9 @@ async function rerankResults(query, candidates) {
   if (!isLLMEnabled() || candidates.length <= 2) {
     return { reranked: candidates, usedLLM: false };
   }
-  const MAX_RERANK = 10;
-  const toRerank = candidates.slice(0, MAX_RERANK);
-  const rest = candidates.slice(MAX_RERANK);
+  const MAX_RERANK2 = 10;
+  const toRerank = candidates.slice(0, MAX_RERANK2);
+  const rest = candidates.slice(MAX_RERANK2);
   try {
     const candidateList = toRerank.map(
       (c) => `[ID: ${c.id}] (${c.type}) ${c.title}${c.narrative ? ` \u2014 ${c.narrative.substring(0, 100)}` : ""}`
@@ -6266,46 +6540,78 @@ async function searchObservations(options) {
       }
     }
   }
-  const shouldRerank = quality === "thorough" && tier === "heavy" && hasQuery && intermediate.length > 2 && (() => {
-    const top = intermediate[0]?.score ?? 0;
-    const second = intermediate[1]?.score ?? 0;
-    return top > 0 && second / top > 0.7;
-  })();
-  if (shouldRerank) {
-    try {
-      const { rerankResults: rerankResults2 } = await Promise.resolve().then(() => (init_quality(), quality_exports));
-      const narrativeMap = /* @__PURE__ */ new Map();
-      for (const hit of results.hits) {
-        const doc = hit.document;
-        narrativeMap.set(makeEntryKey(doc.projectId, doc.observationId), doc.narrative);
-      }
-      const RERANK_TOP_K = 5;
-      const toRerank = intermediate.slice(0, RERANK_TOP_K);
-      const candidates = toRerank.map((e2, index) => ({
-        id: `r${index + 1}`,
-        title: e2.title,
-        type: e2.type,
-        score: e2.score,
-        narrative: narrativeMap.get(makeEntryKey(e2.projectId, e2.id))
-      }));
-      const _parsedRerank = parseInt(process.env.MEMORIX_RERANK_TIMEOUT_MS || "", 10);
-      const RERANK_TIMEOUT_MS = Number.isFinite(_parsedRerank) && _parsedRerank > 0 ? _parsedRerank : 5e3;
-      const { reranked, usedLLM } = await withTimeout(
-        rerankResults2(originalQuery, candidates),
-        RERANK_TIMEOUT_MS,
-        "LLM rerank"
-      );
-      mark(`rerank(usedLLM=${usedLLM})`);
-      if (usedLLM) {
-        lastSearchModeByProject.set(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + LLM rerank");
-        const candidateMap = new Map(candidates.map((candidate, index) => [candidate.id, toRerank[index]]));
-        const rerankedTop = reranked.map((r2) => candidateMap.get(r2.id)).filter((e2) => e2 != null);
-        if (rerankedTop.length > 0) {
-          intermediate = [...rerankedTop, ...intermediate.slice(RERANK_TOP_K)];
+  const httpGate = shouldAttemptHttpRerank({
+    quality,
+    hasQuery: Boolean(hasQuery),
+    candidateCount: intermediate.length
+  });
+  const llmGateWithoutHttp = shouldAttemptLlmRerank({
+    quality,
+    tier,
+    hasQuery: Boolean(hasQuery),
+    candidateCount: intermediate.length,
+    topScore: intermediate[0]?.score ?? 0,
+    secondScore: intermediate[1]?.score ?? 0,
+    httpRerankConfigured: false
+  });
+  if (httpGate || llmGateWithoutHttp) {
+    const narrativeMap = /* @__PURE__ */ new Map();
+    for (const hit of results.hits) {
+      const doc = hit.document;
+      narrativeMap.set(makeEntryKey(doc.projectId, doc.observationId), doc.narrative);
+    }
+    const RERANK_TOP_K = 5;
+    const toRerank = intermediate.slice(0, RERANK_TOP_K);
+    const candidates = toRerank.map((e2, index) => ({
+      id: `r${index + 1}`,
+      title: e2.title,
+      type: e2.type,
+      score: e2.score,
+      narrative: narrativeMap.get(makeEntryKey(e2.projectId, e2.id))
+    }));
+    const RERANK_TIMEOUT_MS = parseRerankTimeoutMs(process.env.MEMORIX_RERANK_TIMEOUT_MS);
+    const candidateMap = new Map(candidates.map((candidate, index) => [candidate.id, toRerank[index]]));
+    const { isNeuralRerankEnabled: isNeuralRerankEnabled2, neuralRerankCandidates: neuralRerankCandidates2 } = await Promise.resolve().then(() => (init_rerank(), rerank_exports));
+    const httpConfigured = isNeuralRerankEnabled2();
+    if (httpConfigured && httpGate) {
+      try {
+        const neural = await withTimeout(
+          neuralRerankCandidates2(originalQuery, candidates),
+          RERANK_TIMEOUT_MS,
+          "neural rerank"
+        );
+        if (neural && neural.length > 0) {
+          const rerankedTop = neural.map((row) => candidateMap.get(row.id)).filter((entry) => entry != null);
+          if (rerankedTop.length > 0) {
+            intermediate = [...rerankedTop, ...intermediate.slice(RERANK_TOP_K)];
+            lastSearchModeByProject.set(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + neural rerank");
+            mark("rerank(usedNeural=true)");
+          }
         }
+      } catch {
+        console.error("[memorix] neural rerank failed or timed out; keeping original order");
       }
-    } catch (error) {
-      console.error("[memorix] LLM rerank failed or timed out, using original order");
+    } else if (!httpConfigured && llmGateWithoutHttp) {
+      try {
+        const { rerankResults: rerankResults2 } = await Promise.resolve().then(() => (init_quality(), quality_exports));
+        const { reranked, usedLLM } = await withTimeout(
+          rerankResults2(originalQuery, candidates),
+          RERANK_TIMEOUT_MS,
+          "LLM rerank"
+        );
+        mark(`rerank(usedLLM=${usedLLM})`);
+        if (usedLLM) {
+          lastSearchModeByProject.set(modeKey, (lastSearchModeByProject.get(modeKey) ?? "fulltext") + " + LLM rerank");
+          const rerankedTop = reranked.map((row) => candidateMap.get(row.id)).filter((entry) => entry != null);
+          if (rerankedTop.length > 0) {
+            intermediate = [...rerankedTop, ...intermediate.slice(RERANK_TOP_K)];
+          }
+        }
+      } catch {
+        console.error("[memorix] LLM rerank failed or timed out, using original order");
+      }
+    } else {
+      mark(`rerank(skipped,tier=${tier})`);
     }
   } else {
     mark(`rerank(skipped,tier=${tier})`);
@@ -6486,6 +6792,7 @@ var init_orama_store = __esm({
     init_project_affinity();
     init_intent_detector();
     init_query_expansion();
+    init_policy();
     init_timeout();
     db = null;
     dbInitPromise = null;

package/docs/ARCHITECTURE.md

@@ -391,7 +391,7 @@ Resolution order:
 2. project `.env`
 3. user `~/.memorix/.env`
 
-The primary lanes are `[agent]` for memcode, `[memory.llm]` for formation/rerank/summaries, and `[embedding]` for semantic search. The dashboard and `memorix status` expose config provenance so the active value source is visible.
+The primary lanes are `[agent]` for memcode, `[memory.llm]` for formation/summaries/LLM-rerank fallback, `[rerank]` for optional HTTP rerank against a compatible `/rerank` API, and `[embedding]` for semantic search. The dashboard and `memorix status` expose config provenance so the active value source is visible.
 
 ---
 

package/docs/CONFIGURATION.md

@@ -47,6 +47,12 @@ model = "text-embedding-v4"
 base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
 api_key = "..."
 
+# Optional HTTP rerank. Off unless provider = "http".
+# [rerank]
+# provider = "http"
+# model = "rerank-model"
+# base_url = "https://api.example.com/v1"
+
 [memory]
 inject = "minimal"
 formation = "active"
@@ -127,7 +133,7 @@ Used by Memorix background memory intelligence:
 - memory formation
 - summarization
 - deduplication
-- optional reranking
+- optional LLM reranking fallback
 - cleanup assistance
 
 Common keys:
@@ -139,6 +145,9 @@ Common keys:
 
 For OpenAI-compatible providers such as DashScope, DeepSeek-compatible gateways,
 or internal model gateways, use `provider = "openai"` and set `base_url`.
+Memorix uses an explicit provider path as-is: for example,
+`https://ark.cn-beijing.volces.com/api/v3` remains `/api/v3`. Only a bare host
+without a versioned path receives the convenience suffix `/v1`.
 
 ### `[embedding]`
 
@@ -186,6 +195,53 @@ OpenAI-only default. The equivalent env-var form is
 `MEMORIX_EMBEDDING=api`, `MEMORIX_EMBEDDING_BASE_URL=https://openrouter.ai/api/v1`,
 `MEMORIX_EMBEDDING_MODEL=qwen/qwen3-embedding-8b`.
 
+### `[rerank]`
+
+Optional HTTP rerank for thorough search. Off by default.
+When `provider = "http"`, Memorix POSTs a Cohere-compatible
+`{model, query, documents}` body to `{base_url}/rerank` (or an explicit
+`/rerank` path). Any compatible endpoint works — hosted APIs, TEI, vLLM,
+or a local gateway. Memorix sends the configured `model` string unchanged.
+
+Common keys:
+
+- `provider` — `off` (default) or `http`
+- `model` — user-configured model id (no built-in default). Example:
+  `rerank-model`
+- `base_url` — API root that serves `/rerank`, for example
+  `https://api.example.com/v1` or `http://127.0.0.1:8080`. When unset and
+  `provider = "http"`, Memorix inherits `[memory.llm].base_url`.
+- `api_key` — bearer token. When unset, inherits the memory LLM key
+  (`MEMORIX_LLM_API_KEY`, `MEMORIX_API_KEY`, or `[memory.llm].api_key`)
+  only if the effective `base_url` is the same trusted endpoint as
+  `[memory.llm].base_url`. A different rerank URL requires
+  `MEMORIX_RERANK_API_KEY` or `rerank.api_key`.
+
+Environment overrides (highest priority after CLI flags):
+
+```bash
+MEMORIX_RERANK_PROVIDER=http
+MEMORIX_RERANK_MODEL=rerank-model
+MEMORIX_RERANK_BASE_URL=https://api.example.com/v1
+# MEMORIX_RERANK_API_KEY=   # required when base_url is not the memory LLM endpoint
+```
+
+If the memory LLM lane already points at the same gateway, you can enable
+rerank with:
+
+```toml
+[rerank]
+provider = "http"
+model = "rerank-model"
+```
+
+or set `MEMORIX_RERANK_PROVIDER=http` and `MEMORIX_RERANK_MODEL=...`.
+Timeout is `MEMORIX_RERANK_TIMEOUT_MS` (default 30000). Thorough search
+with at least 3 candidates uses HTTP rerank when configured. On HTTP miss
+or timeout, Memorix keeps the original order and does not fall through to
+LLM rerank. LLM rerank remains available when HTTP rerank is off, on the
+existing thorough/heavy/ambiguous gate.
+
 Image analysis (visual description for ingested images) runs on the LLM lane
 through an OpenAI-compatible vision endpoint, so it can also use OpenRouter
 with a multimodal model — for example `qwen/qwen3-vl-8b-instruct` via

package/docs/PERFORMANCE.md

@@ -75,7 +75,9 @@ On the release development machine used for this check, the healthy HTTP service
 | `MEMORIX_FORMATION_TIMEOUT_MS` | `12000` (12 s) | Raise when LLM-backed formation should outlive slow proxy/provider hops |
 | `MEMORIX_LLM_API_KEY` / `OPENAI_API_KEY` | unset | Enable LLM-backed enrichment, extraction, rerank, or skill generation |
 | `MEMORIX_LLM_TIMEOUT_MS` | `30000` (30 s) | Bound a single LLM-backed extraction/resolve call |
-| `MEMORIX_RERANK_TIMEOUT_MS` | provider default | Bound slow LLM rerank calls |
+| `MEMORIX_RERANK_TIMEOUT_MS` | 30000 | Bound HTTP and LLM rerank calls |
+| `MEMORIX_RERANK_PROVIDER` | `off` | Set `http` to enable optional HTTP rerank |
+| `MEMORIX_RERANK_BASE_URL` | `[memory.llm].base_url` | Compatible `/rerank` API root (path `/rerank` is appended) |
 | `memorix memory search --quality fast` | n/a | Force a fully local retrieval path for a latency-sensitive call |
 | `npm run benchmark:retrieval -- --records 1000 --runs 100` | n/a | Reproduce hot in-process lexical retrieval latency; not an end-to-end claim |
 | `npm run gate:large-store -- --records 40000` | n/a | Exercise SDK, HTTP MCP, hook persistence, cache integrity, and reopen behavior against a large isolated store |

package/docs/SETUP.md

@@ -498,7 +498,8 @@ What each lane does:
 | Lane | Used by |
 | --- | --- |
 | `[agent]` | model used by memcode while coding |
-| `[memory.llm]` | memory formation, summaries, deduplication, optional rerank |
+| `[memory.llm]` | memory formation, summaries, deduplication, optional LLM rerank fallback |
+| `[rerank]` | optional HTTP rerank against a compatible `/rerank` API |
 | `[embedding]` | semantic/vector search |
 | `[memory]` | memory injection and formation behavior |
 | `[git]` | Git Memory hook and ingestion behavior |