Function rankEpisodes

src/context/episodic-memory.ts:107–142

(query: string, episodes: Episode[], opts: RankOptions = {})

   * episodes, so the K injected are relevant AND distinct. 0 = legacy (pure relevance).
   * Default 0.3 (gentle — relevance still dominates).
   */
  diversity?: number;
  /**
   * Optional file-existence predicate (injected; keeps this function PURE). An episode whose
   * recorded `filesChanged` mostly no longer exist is stale guidance — its relevance is
   * scaled down (not dropped: the *approach* may still help). Episodes with no files are
   * unaffected. Mirrors the codebase-fit grounding used in skill judgment.
   */
  fileExists?: (file: string) => boolean;
}

/** Fraction of an episode's touched files that still exist (1 when none recorded — nothing to judge). */
export function fileFreshness(files: string[], exists: (f: string) => boolean): number {
  if (files.length === 0) return 1;
  return files.filter(exists).length / files.length;
}

/**
 * Rank episodes against a query by lexical similarity (prompt + summary), then select a
 * RELEVANT-and-DIVERSE top-K. PURE.
 *
 *  - Excludes near-identical re-runs of the exact same prompt (score ≥ 0.98) so "similar
 *    past work" doesn't just echo the current task back.
 *  - File grounding: episodes pointing at files that no longer exist are scaled down
 *    (`fileExists`), so stale episodes lose to fresh ones.
 *  - MMR diversity (`diversity`): greedily pick highest relevance, penalising each remaining
 *    candidate by its similarity to what's already chosen — kills redundant injection.
 *  - Recency tie-break: episodes arrive oldest→newest, so a later index breaks near-ties
 *    toward the more recent solution (clock-free, stays pure).
 */
/**
 * Light FA→EN gloss for recall only (not skill-dedup). Lets «لاگ» overlap `log`
 * without a translation model. PURE.
 */
const RECALL_GLOSS: [RegExp, string][] = [
  [/لاگ/g, ' log '],
  [/فرمت/g, ' format '],
  [/هلپر/g, ' helper '],
  [/تست(?:‌ها)?/g, ' test '],