memorix 1.7.1 → 1.7.3

package/src/rerank/http-provider.ts

@@ -0,0 +1,125 @@
+/**
+ * Optional HTTP rerank client.
+ *
+ * Posts a Cohere-compatible `{model, query, documents}` body to
+ * `{base_url}/rerank` (or an explicit `/rerank` path). Compatible with
+ * any `/rerank` endpoint that accepts that body. The model id is
+ * whatever the user configured — Memorix does not rewrite it.
+ */
+
+import { resolveRerankTimeoutMs } from './policy.js';
+
+export type NeuralRerankProviderName = 'http';
+
+export interface NeuralRerankRequestConfig {
+  provider: NeuralRerankProviderName;
+  model?: string;
+  baseUrl: string;
+  apiKey?: string;
+  timeoutMs?: number;
+  fetchImpl?: typeof fetch;
+}
+
+export interface RerankedDocument {
+  index: number;
+  score: number;
+}
+
+/**
+ * Join a provider base URL with `/rerank`, leaving an explicit path intact.
+ */
+export function buildRerankUrl(baseUrl: string): string {
+  const trimmed = baseUrl.trim().replace(/\/+$/, '');
+  if (trimmed.endsWith('/rerank')) return trimmed;
+  return `${trimmed}/rerank`;
+}
+
+/**
+ * Accept Cohere-compatible `{results:[{index,relevance_score}]}` and TEI `[{index,score}]`.
+ */
+export function parseRerankResponse(payload: unknown): RerankedDocument[] {
+  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: unknown): RerankedDocument[] {
+  if (Array.isArray(payload)) {
+    return payload.map(rowFromUnknown).filter((row): row is RerankedDocument => row !== null);
+  }
+  if (payload && typeof payload === 'object' && 'results' in payload) {
+    const results = (payload as { results: unknown }).results;
+    if (Array.isArray(results)) {
+      return results.map(rowFromUnknown).filter((row): row is RerankedDocument => row !== null);
+    }
+  }
+  throw new Error('Neural rerank response was not Cohere or TEI shaped');
+}
+
+function rowFromUnknown(value: unknown): RerankedDocument | null {
+  if (!value || typeof value !== 'object') return null;
+  const row = value as { index?: unknown; relevance_score?: unknown; score?: unknown };
+  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: string, documents: string[], model?: string): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    query,
+    documents,
+    top_n: documents.length,
+    return_documents: false,
+  };
+  const trimmed = model?.trim();
+  if (trimmed) body.model = trimmed;
+  return body;
+}
+
+/**
+ * POST query + documents to a compatible `/rerank` endpoint and return ranked indexes.
+ */
+export async function rerankViaHttp(
+  query: string,
+  documents: string[],
+  config: NeuralRerankRequestConfig,
+): Promise<RerankedDocument[]> {
+  if (documents.length === 0) return [];
+
+  const url = buildRerankUrl(config.baseUrl);
+  const headers: Record<string, string> = {
+    '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);
+  }
+}

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

@@ -8,7 +8,7 @@
  * Vector search (embeddings) will be added in P1 phase.
  */
 
-import { create, insert, search, remove, update, count, getByID, type AnyOrama } from '@orama/orama';
+import { create, insert, insertMultiple, search, remove, update, count, getByID, type AnyOrama } from '@orama/orama';
 import type { MemorixDocument, SearchOptions, IndexEntry, KnowledgeLayer, ObservationReader } from '../types.js';
 import { OBSERVATION_ICONS, type ObservationType } from '../types.js';
 import { resolveKnowledgeLayer } from '../skills/mini-skills.js';
@@ -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;
@@ -405,7 +406,7 @@ export async function hydrateIndex(
     ? candidates.map(() => null)
     : await getCachedEmbeddings(candidates.map(({ observation }) => observationEmbeddingText(observation)));
 
-  let inserted = 0;
+  const documents: MemorixDocument[] = [];
   for (let index = 0; index < candidates.length; index++) {
     const { observation: obs, id } = candidates[index];
     try {
@@ -439,19 +440,39 @@ export async function hydrateIndex(
         knowledgeLayer: resolveKnowledgeLayer('observation', obs.sourceDetail, obs.source),
         ...(compatibleVector ? { embedding: compatibleVector } : {}),
       };
-      await insert(database, doc);
-      rememberObservationDoc(doc);
-      inserted++;
-      // Keep the HTTP event loop alive on large corpora so /health still answers.
-      if (inserted % 50 === 0) {
-        await new Promise<void>((resolve) => setImmediate(resolve));
-      }
-      if (inserted % 200 === 0) {
-        await new Promise<void>((resolve) => setTimeout(resolve, 0));
-      }
+      documents.push(doc);
     } catch { /* skip malformed entries */ }
   }
 
+  let inserted = 0;
+  const hydrationBatchSize = 200;
+  for (let start = 0; start < documents.length; start += hydrationBatchSize) {
+    const batch = documents.slice(start, start + hydrationBatchSize);
+    try {
+      // Orama can rebalance its indexes once per batch instead of once per
+      // document. Keep batches bounded so HTTP health remains responsive.
+      await insertMultiple(database, batch, batch.length);
+      for (const doc of batch) rememberObservationDoc(doc);
+      inserted += batch.length;
+    } catch {
+      // A concurrent write or malformed document can partially complete a
+      // batch. Preserve the old best-effort behavior without double-inserting.
+      for (const doc of batch) {
+        if (getByID(database, doc.id)) {
+          rememberObservationDoc(doc);
+          inserted++;
+          continue;
+        }
+        try {
+          await insert(database, doc);
+          rememberObservationDoc(doc);
+          inserted++;
+        } catch { /* skip malformed or concurrently inserted entries */ }
+      }
+    }
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+
   deferredCachedVectorHydration = options.skipCachedVectors
     ? null
     : deferCachedVectors
@@ -1034,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})`);