memorix 1.7.2 → 1.7.3

package/src/rerank/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Optional HTTP rerank lane. LLM rerank stays in quality.ts when HTTP is off.
+ */
+
+import { getResolvedRerankLane, type ResolvedLaneOptions } from '../config/resolved-config.js';
+import { rerankViaHttp } from './http-provider.js';
+import { resolveRerankTimeoutMs } from './policy.js';
+
+export {
+  DEFAULT_RERANK_TIMEOUT_MS,
+  MIN_RERANK_CANDIDATES,
+  parseRerankTimeoutMs,
+  resolveRerankTimeoutMs,
+  shouldAttemptHttpRerank,
+  shouldAttemptLlmRerank,
+} from './policy.js';
+
+/** Minimal search hit the HTTP reranker can reorder. */
+export interface NeuralRerankCandidate {
+  id: string;
+  title: string;
+  type: string;
+  score: number;
+  narrative?: string;
+}
+
+const MAX_RERANK = 10;
+
+/**
+ * True when an HTTP `/rerank` endpoint is configured.
+ */
+export function isNeuralRerankEnabled(options: ResolvedLaneOptions = {}): boolean {
+  const lane = getResolvedRerankLane(options);
+  return lane.provider === 'http' && Boolean(lane.baseUrl);
+}
+
+/**
+ * Reorder search candidates via the configured remote reranker.
+ * Returns null when the provider is off or the HTTP call cannot be used.
+ */
+export async function neuralRerankCandidates(
+  query: string,
+  candidates: NeuralRerankCandidate[],
+  options: ResolvedLaneOptions = {},
+): Promise<NeuralRerankCandidate[] | null> {
+  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 = new Set<number>();
+  const reranked: NeuralRerankCandidate[] = [];
+  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: NeuralRerankCandidate): string {
+  const narrative = candidate.narrative?.trim();
+  if (narrative) return `${candidate.title} — ${narrative.slice(0, 200)}`;
+  return candidate.title;
+}

package/src/rerank/policy.ts

@@ -0,0 +1,88 @@
+/**
+ * Product rules for optional HTTP rerank and the existing LLM rerank path.
+ *
+ * HTTP rerank is opt-in. When it is configured, thorough search with enough
+ * candidates uses the HTTP lane only — a miss or timeout keeps the original
+ * order instead of falling through to LLM rerank.
+ */
+
+export const DEFAULT_RERANK_TIMEOUT_MS = 30_000;
+export const RERANK_TIMEOUT_MIN_MS = 1_000;
+export const RERANK_TIMEOUT_MAX_MS = 300_000;
+export const MIN_RERANK_CANDIDATES = 3;
+
+/**
+ * Parse and validate MEMORIX_RERANK_TIMEOUT_MS.
+ *
+ * @param raw - Environment value, or undefined when unset
+ * @returns Timeout in milliseconds (default 30000)
+ */
+export function parseRerankTimeoutMs(raw: string | undefined): number {
+  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;
+}
+
+/**
+ * Resolve the rerank timeout from an explicit override or the environment.
+ *
+ * @param explicitTimeoutMs - Caller-supplied timeout, when present
+ * @returns Timeout in milliseconds
+ */
+export function resolveRerankTimeoutMs(explicitTimeoutMs?: number): number {
+  if (typeof explicitTimeoutMs === 'number' && Number.isFinite(explicitTimeoutMs) && explicitTimeoutMs > 0) {
+    return explicitTimeoutMs;
+  }
+  return parseRerankTimeoutMs(process.env.MEMORIX_RERANK_TIMEOUT_MS);
+}
+
+/**
+ * True when thorough search has enough candidates for HTTP rerank.
+ *
+ * @param input - Retrieval quality, query presence, and hit count
+ * @returns Whether the HTTP rerank lane should run
+ */
+export function shouldAttemptHttpRerank(input: {
+  quality?: string;
+  hasQuery: boolean;
+  candidateCount: number;
+}): boolean {
+  return input.quality === 'thorough'
+    && input.hasQuery
+    && input.candidateCount >= MIN_RERANK_CANDIDATES;
+}
+
+/**
+ * True when the existing LLM rerank path should run.
+ *
+ * LLM rerank stays on the original thorough + heavy + close top-2 gate.
+ * It never runs when an HTTP rerank lane is configured.
+ *
+ * @param input - Search gate inputs plus whether HTTP rerank is configured
+ * @returns Whether LLM rerank should run
+ */
+export function shouldAttemptLlmRerank(input: {
+  quality?: string;
+  tier: string;
+  hasQuery: boolean;
+  candidateCount: number;
+  topScore: number;
+  secondScore: number;
+  httpRerankConfigured: boolean;
+}): boolean {
+  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;
+}

package/src/store/orama-store.ts

@@ -23,6 +23,7 @@ import {
 import { calculateProjectAffinity, extractProjectKeywords, type AffinityContext, type MemoryContent } from './project-affinity.js';
 import { detectQueryIntent, applyIntentBoost } from '../search/intent-detector.js';
 import { maybeExpandSearchQuery } from '../search/query-expansion.js';
+import { parseRerankTimeoutMs, shouldAttemptHttpRerank, shouldAttemptLlmRerank } from '../rerank/policy.js';
 import { withTimeout, withTimeoutSignal } from '../timeout.js';
 
 let db: AnyOrama | null = null;
@@ -1054,62 +1055,87 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
     }
   }
 
-  // ── LLM Reranking (heavy-tier only) ────────────────────────────
-  // Only triggered for heavy-tier queries with ambiguous top results.
-  // Non-thorough profiles, fast, and standard tiers skip entirely.
-  // Ambiguity check: top-2 scores within 30% → results are uncertain.
-  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; // top-2 within 30% = ambiguous
-    })();
-
-  if (shouldRerank) {
-    try {
-      const { rerankResults } = await import('../llm/quality.js');
-      const narrativeMap = new Map<string, string>();
-      for (const hit of results.hits) {
-        const doc = hit.document as unknown as MemorixDocument;
-        narrativeMap.set(makeEntryKey(doc.projectId, doc.observationId), doc.narrative);
+  // HTTP rerank: thorough search with enough candidates.
+  // LLM rerank: original thorough + heavy + close top-2 gate, and only when
+  // HTTP rerank is not configured. A configured HTTP miss keeps original order.
+  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 = new Map<string, string>();
+    for (const hit of results.hits) {
+      const doc = hit.document as unknown as MemorixDocument;
+      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((e, index) => ({
+      id: `r${index + 1}`,
+      title: e.title,
+      type: e.type,
+      score: e.score,
+      narrative: narrativeMap.get(makeEntryKey(e.projectId, e.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, neuralRerankCandidates } = await import('../rerank/index.js');
+    const httpConfigured = isNeuralRerankEnabled();
+
+    if (httpConfigured && httpGate) {
+      try {
+        const neural = await withTimeout(
+          neuralRerankCandidates(originalQuery!, candidates),
+          RERANK_TIMEOUT_MS,
+          'neural rerank',
+        );
+        if (neural && neural.length > 0) {
+          const rerankedTop = neural
+            .map((row) => candidateMap.get(row.id))
+            .filter((entry): entry is NonNullable<typeof 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');
       }
-      // Rerank only top-5 (was 10) to save LLM tokens and latency
-      const RERANK_TOP_K = 5;
-      const toRerank = intermediate.slice(0, RERANK_TOP_K);
-      const candidates = toRerank.map((e, index) => ({
-        id: `r${index + 1}`,
-        title: e.title,
-        type: e.type,
-        score: e.score,
-        narrative: narrativeMap.get(makeEntryKey(e.projectId, e.id)),
-      }));
-      
-      // LLM rerank timeout: configurable via MEMORIX_RERANK_TIMEOUT_MS, default 5s
-      const _parsedRerank = parseInt(process.env.MEMORIX_RERANK_TIMEOUT_MS || '', 10);
-      const RERANK_TIMEOUT_MS = Number.isFinite(_parsedRerank) && _parsedRerank > 0 ? _parsedRerank : 5000;
-      const { reranked, usedLLM } = await withTimeout(
-        rerankResults(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(r => candidateMap.get(r.id))
-          .filter((e): e is NonNullable<typeof e> => e != null);
-        if (rerankedTop.length > 0) {
-          intermediate = [...rerankedTop, ...intermediate.slice(RERANK_TOP_K)];
+    } else if (!httpConfigured && llmGateWithoutHttp) {
+      try {
+        const { rerankResults } = await import('../llm/quality.js');
+        const { reranked, usedLLM } = await withTimeout(
+          rerankResults(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 is NonNullable<typeof 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');
       }
-    } catch (error) {
-      // Reranking is best-effort: fall back to original order on timeout or error
-      console.error('[memorix] LLM rerank failed or timed out, using original order');
+    } else {
+      mark(`rerank(skipped,tier=${tier})`);
     }
   } else {
     mark(`rerank(skipped,tier=${tier})`);