memorix 1.7.1 → 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)}` : ""}`
@@ -5597,7 +5871,7 @@ __export(orama_store_exports, {
   searchObservations: () => searchObservations,
   updateObservationMetadata: () => updateObservationMetadata
 });
-import { create, insert as insert2, search, remove as remove2, update, count, getByID } from "@orama/orama";
+import { create, insert as insert2, insertMultiple, search, remove as remove2, update, count, getByID } from "@orama/orama";
 function getLastSearchMode(projectId) {
   return lastSearchModeByProject.get(projectId ?? SEARCH_MODE_DEFAULT_KEY) ?? "fulltext";
 }
@@ -5809,7 +6083,7 @@ async function hydrateIndex(observations2, options = {}) {
   }
   const deferCachedVectors = options.deferCachedVectors === true && Boolean(indexEmbeddingProvider?.getCachedEmbeddings);
   const cachedVectors = deferCachedVectors ? candidates.map(() => null) : await getCachedEmbeddings(candidates.map(({ observation }) => observationEmbeddingText(observation)));
-  let inserted = 0;
+  const documents = [];
   for (let index = 0; index < candidates.length; index++) {
     const { observation: obs, id } = candidates[index];
     try {
@@ -5843,18 +6117,35 @@ async function hydrateIndex(observations2, options = {}) {
         knowledgeLayer: resolveKnowledgeLayer("observation", obs.sourceDetail, obs.source),
         ...compatibleVector ? { embedding: compatibleVector } : {}
       };
-      await insert2(database, doc);
-      rememberObservationDoc(doc);
-      inserted++;
-      if (inserted % 50 === 0) {
-        await new Promise((resolve) => setImmediate(resolve));
-      }
-      if (inserted % 200 === 0) {
-        await new Promise((resolve) => setTimeout(resolve, 0));
-      }
+      documents.push(doc);
     } catch {
     }
   }
+  let inserted = 0;
+  const hydrationBatchSize = 200;
+  for (let start = 0; start < documents.length; start += hydrationBatchSize) {
+    const batch = documents.slice(start, start + hydrationBatchSize);
+    try {
+      await insertMultiple(database, batch, batch.length);
+      for (const doc of batch) rememberObservationDoc(doc);
+      inserted += batch.length;
+    } catch {
+      for (const doc of batch) {
+        if (getByID(database, doc.id)) {
+          rememberObservationDoc(doc);
+          inserted++;
+          continue;
+        }
+        try {
+          await insert2(database, doc);
+          rememberObservationDoc(doc);
+          inserted++;
+        } catch {
+        }
+      }
+    }
+    await new Promise((resolve) => setImmediate(resolve));
+  }
   deferredCachedVectorHydration = options.skipCachedVectors ? null : deferCachedVectors ? attachCachedVectors(database, candidates).catch(() => {
   }) : null;
   return inserted;
@@ -6249,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})`);
@@ -6469,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.
 
 ---