@remnic/core 9.47.0 → 9.48.0

package/src/orchestrator.ts

@@ -120,6 +120,7 @@ import { ConsolidationRunCoordinator } from "./orchestration/consolidation-run.j
 import { ExtractionPersistCoordinator } from "./orchestration/extraction-persist.js";
 import { RecallInternalCoordinator } from "./orchestration/recall-internal.js";
 import { RecallSearchPipelineCoordinator } from "./orchestration/recall-search-pipeline.js";
+import type { ArtifactRecallOptions } from "./orchestration/recall-search-prefilter.js";
 import { TurnIngestionCoordinator, type TurnIngestionOptions } from "./orchestration/turn-ingestion.js";
 import { RecallIntrospectionCoordinator } from "./orchestration/recall-introspection.js";
 import { OrchestratorInitCoordinator } from "./orchestration/orchestrator-init.js";
@@ -2460,11 +2461,10 @@ export class Orchestrator {
     namespace: string,
     prompt: string,
     targetCount: number,
+    options: ArtifactRecallOptions = {},
   ): Promise<MemoryFile[]> {
     return this.recallSearchPipelineCoordinator.fetchActiveArtifactsForNamespace(
-      namespace,
-      prompt,
-      targetCount,
+      namespace, prompt, targetCount, options,
     );
   }
 
@@ -2472,11 +2472,10 @@ export class Orchestrator {
     prompt: string,
     recallNamespaces: string[],
     targetCount: number,
+    options: ArtifactRecallOptions = {},
   ): Promise<MemoryFile[]> {
     return this.namespaceReadFanoutCoordinator.recallArtifactsAcrossNamespaces(
-      prompt,
-      recallNamespaces,
-      targetCount,
+      prompt, recallNamespaces, targetCount, options,
     );
   }
 

package/src/recall-qos.test.ts

@@ -1,7 +1,12 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { throwIfAborted } from "./abort-error.js";
 import {
+  createBoundedCoreSectionRunner,
   createRecallSectionMetricRecorder,
+  resolveRecallCoreSectionDeadlineMs,
+  runRecallSectionWithinDeadline,
+  yieldToEventLoop,
   type RecallSectionMetric,
 } from "./recall-qos.js";
 
@@ -83,3 +88,287 @@ test("recall section metric recorder respects timing overrides and logs enrichme
     success: true,
   });
 });
+
+test("timed-out section metric reports the breach instead of a plain duration", () => {
+  const timings: Record<string, string> = {};
+  const calls: Array<{ level: "info" | "debug"; payload: unknown[] }> = [];
+  const recorder = createRecallSectionMetricRecorder({
+    timings,
+    logger: {
+      info: (_message: string, ...payload: unknown[]) => calls.push({ level: "info", payload }),
+      debug: (_message: string, ...payload: unknown[]) => calls.push({ level: "debug", payload }),
+    },
+  });
+
+  recorder({
+    section: "entityRetrieval",
+    priority: "core",
+    durationMs: 75_004,
+    deadlineMs: 75_000,
+    source: "timeout",
+    success: false,
+  });
+
+  assert.equal(timings.entityRetrieval, "timeout(75004ms)");
+  // A breach is not a success, so it must not be logged as one.
+  assert.equal(calls[0]?.level, "debug");
+});
+
+test("recall section deadline degrades to the fallback and cancels the section", async () => {
+  let observedSignal: AbortSignal | undefined;
+  let cancelledDuringWork = false;
+
+  // A real timer is the subject here, not a guessed wait: the section below
+  // never settles on its own, so the deadline always wins regardless of load.
+  const outcome = await runRecallSectionWithinDeadline({
+    deadlineMs: 15,
+    fallback: "degraded",
+    run: async (sectionSignal) => {
+      observedSignal = sectionSignal;
+      const cancelled = Promise.withResolvers<void>();
+      sectionSignal.addEventListener("abort", () => {
+        cancelledDuringWork = true;
+        cancelled.resolve();
+      });
+      await cancelled.promise;
+      return "late value";
+    },
+  });
+
+  assert.equal(outcome.timedOut, true);
+  assert.equal(outcome.value, "degraded");
+  assert.equal(observedSignal?.aborted, true);
+  assert.equal(cancelledDuringWork, true);
+});
+
+test("recall section deadline returns the real value when the section finishes in time", async () => {
+  const outcome = await runRecallSectionWithinDeadline({
+    deadlineMs: 5_000,
+    fallback: null as string | null,
+    run: async (sectionSignal) => {
+      assert.equal(sectionSignal.aborted, false);
+      return "section body";
+    },
+  });
+
+  assert.equal(outcome.timedOut, false);
+  assert.equal(outcome.value, "section body");
+});
+
+test("a zero deadline disables the bound rather than failing every section", async () => {
+  const released = Promise.withResolvers<void>();
+  const pending = runRecallSectionWithinDeadline({
+    deadlineMs: 0,
+    fallback: "degraded",
+    run: async () => {
+      await released.promise;
+      return "unbounded value";
+    },
+  });
+
+  // Two full event-loop turns: any 0ms timer would already have fired, so a
+  // still-pending section proves the bound was disabled rather than instant.
+  for (let turn = 0; turn < 2; turn += 1) {
+    const turned = Promise.withResolvers<void>();
+    setImmediate(turned.resolve);
+    await turned.promise;
+  }
+  released.resolve();
+
+  const outcome = await pending;
+  assert.equal(outcome.timedOut, false);
+  assert.equal(outcome.value, "unbounded value");
+});
+
+test("a caller abort propagates into the section signal", async () => {
+  const caller = new AbortController();
+  let cancelledDuringWork = false;
+
+  const pending = runRecallSectionWithinDeadline({
+    deadlineMs: 5_000,
+    fallback: "degraded",
+    parentSignal: caller.signal,
+    run: async (sectionSignal) => {
+      const cancelled = Promise.withResolvers<void>();
+      sectionSignal.addEventListener("abort", () => {
+        cancelledDuringWork = true;
+        cancelled.resolve();
+      });
+      await cancelled.promise;
+      return "cancelled";
+    },
+  });
+
+  caller.abort();
+  const outcome = await pending;
+
+  assert.equal(cancelledDuringWork, true);
+  assert.equal(outcome.timedOut, false);
+  assert.equal(outcome.value, "cancelled");
+});
+
+test("an already-aborted caller signal cancels the section before it does work", async () => {
+  const caller = new AbortController();
+  caller.abort();
+
+  const outcome = await runRecallSectionWithinDeadline({
+    deadlineMs: 5_000,
+    fallback: "degraded",
+    parentSignal: caller.signal,
+    run: async (sectionSignal) => {
+      assert.equal(sectionSignal.aborted, true);
+      return "observed";
+    },
+  });
+
+  assert.equal(outcome.value, "observed");
+});
+
+test("a section rejection surfaces to the caller instead of being swallowed", async () => {
+  await assert.rejects(
+    runRecallSectionWithinDeadline({
+      deadlineMs: 5_000,
+      fallback: "degraded",
+      run: async () => {
+        throw new Error("section exploded");
+      },
+    }),
+    /section exploded/,
+  );
+});
+
+test("the default core section budget is capped below the remaining request budget", () => {
+  // Both settings default to 75s. Taken at face value the section deadline could
+  // never fire first, so degradation would be unreachable on default config.
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({
+      configuredCoreDeadlineMs: 75_000,
+      remainingOuterMs: 75_000,
+    }),
+    60_000,
+  );
+});
+
+test("the core section budget shrinks with the request budget already spent", () => {
+  // A section that starts 20s into a 75s request must finish inside the 55s left,
+  // not inside the original ceiling — otherwise the request is aborted wholesale.
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({
+      configuredCoreDeadlineMs: 75_000,
+      remainingOuterMs: 55_000,
+    }),
+    44_000,
+  );
+});
+
+test("a request already over budget degrades its sections immediately", () => {
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({
+      configuredCoreDeadlineMs: 75_000,
+      remainingOuterMs: 0,
+    }),
+    1,
+  );
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({
+      configuredCoreDeadlineMs: 75_000,
+      remainingOuterMs: -5_000,
+    }),
+    1,
+  );
+});
+
+test("an explicitly lowered core section budget is honored exactly", () => {
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({
+      configuredCoreDeadlineMs: 5_000,
+      remainingOuterMs: 75_000,
+    }),
+    5_000,
+  );
+});
+
+test("a zero budget on either side keeps the configured value", () => {
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({ configuredCoreDeadlineMs: 0, remainingOuterMs: 75_000 }),
+    0,
+  );
+  // No request ceiling means nothing to reserve headroom against.
+  assert.equal(
+    resolveRecallCoreSectionDeadlineMs({ configuredCoreDeadlineMs: 75_000, remainingOuterMs: null }),
+    75_000,
+  );
+});
+
+test("a bounded core section resolves its budget from the budget left when it starts", async () => {
+  const metrics: RecallSectionMetric[] = [];
+  const clockMs = 1_000_000;
+  const runSection = createBoundedCoreSectionRunner({
+    configuredDeadlineMs: 75_000,
+    // 75s request that started 20s ago: 55s left, so the section gets 80% of 55s.
+    outerDeadlineAtMs: clockMs + 55_000,
+    record: (metric) => metrics.push(metric),
+    logger: { warn: () => {} },
+    now: () => clockMs,
+  });
+
+  await runSection("entityRetrieval", null as string | null, async () => "section body");
+
+  assert.equal(metrics[0]?.deadlineMs, 44_000);
+});
+
+test("a bounded core section degrades on cancellation rather than rejecting", async () => {
+  // The phase this section belongs to is awaited through a race the caller's
+  // abort also wins, so a rejection here would be an unhandled rejection.
+  const metrics: RecallSectionMetric[] = [];
+  const caller = new AbortController();
+  const runSection = createBoundedCoreSectionRunner({
+    configuredDeadlineMs: 5_000,
+    outerDeadlineAtMs: null,
+    parentSignal: caller.signal,
+    record: (metric) => metrics.push(metric),
+    logger: { warn: () => {} },
+  });
+
+  caller.abort();
+  const value = await runSection("artifacts", [] as string[], async (sectionSignal) => {
+    throwIfAborted(sectionSignal, "artifact search aborted");
+    return ["should not be reached"];
+  });
+
+  assert.deepEqual(value, []);
+  assert.equal(metrics[0]?.section, "artifacts");
+  assert.equal(metrics[0]?.success, false);
+  assert.match(metrics[0]?.timing ?? "", /^cancelled\(\d+ms\)$/);
+});
+
+test("a bounded core section still surfaces a non-abort failure", async () => {
+  const runSection = createBoundedCoreSectionRunner({
+    configuredDeadlineMs: 5_000,
+    outerDeadlineAtMs: null,
+    record: () => {},
+    logger: { warn: () => {} },
+  });
+
+  await assert.rejects(
+    runSection("artifacts", [] as string[], async () => {
+      throw new Error("artifact tier unreadable");
+    }),
+    /artifact tier unreadable/,
+  );
+});
+
+test("yieldToEventLoop lets a pending timer run", async () => {
+  // The guarantee corpus scans depend on: without a yield the timer that carries
+  // a section deadline cannot fire while the scan holds the loop.
+  let timerFired = false;
+  const timer = setTimeout(() => {
+    timerFired = true;
+  }, 0);
+
+  await yieldToEventLoop();
+  await yieldToEventLoop();
+  clearTimeout(timer);
+
+  assert.equal(timerFired, true);
+});

package/src/recall-qos.ts

@@ -1,7 +1,29 @@
+import { abortError, isAbortError } from "./abort-error.js";
 import { log, type LoggerBackend } from "./logger.js";
 
+/**
+ * Hand the event loop one macrotask.
+ *
+ * A recall section deadline is a timer, and a timer cannot fire while a
+ * synchronous scan holds the loop — so a provider that iterates the whole corpus
+ * must call this periodically or its budget is unenforceable (issue #2291).
+ * `setImmediate` (check phase) is used rather than a `0ms` timer so the yield
+ * cannot be starved by the timer queue it exists to let run.
+ */
+export function yieldToEventLoop(): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setImmediate(resolve);
+  return promise;
+}
+
 export type RecallSectionPriority = "core" | "enrichment";
-export type RecallSectionSource = "fresh" | "stale" | "skip";
+/**
+ * `timeout` records a section that started, exceeded its deadline, and was
+ * degraded to its neutral value (issue #2291).  It is distinct from `skip`
+ * (never ran: disabled or zero-limit) so operators can tell a configuration
+ * choice from a budget breach in the section metric log.
+ */
+export type RecallSectionSource = "fresh" | "stale" | "skip" | "timeout";
 
 export interface RecallSectionMetric {
   section: string;
@@ -31,6 +53,9 @@ function defaultTiming(metric: RecallSectionMetric): string {
   if (typeof metric.timing === "string" && metric.timing.length > 0) {
     return metric.timing;
   }
+  if (metric.source === "timeout") {
+    return `timeout(${Math.max(0, Math.round(metric.durationMs))}ms)`;
+  }
   if (metric.source === "skip") {
     return "skip";
   }
@@ -80,3 +105,215 @@ export function createRecallSectionMetricRecorder(options: {
     return entry;
   };
 }
+
+/**
+ * Fraction of the request's REMAINING budget that a single core section may
+ * consume.  The remainder is what makes degradation possible at all: time to
+ * assemble and return the sections that did arrive before the outer timeout
+ * kills the request outright.
+ */
+const CORE_SECTION_MAX_SHARE_OF_REQUEST = 0.8;
+
+/**
+ * Effective per-section deadline for optional core recall providers.
+ *
+ * Two things make the configured value unusable as-is (issue #2291):
+ *
+ *  - `recallCoreDeadlineMs` and `recallOuterTimeoutMs` both default to 75s, so a
+ *    section budget taken at face value can never fire before the request ceiling
+ *    that cancels everything — the caller loses the whole recall rather than one
+ *    section.
+ *  - Sections start *after* planning, namespace resolution, and mode selection.
+ *    Capping against the original ceiling would let a section that starts 20s in
+ *    still be running when the request is aborted, which is the same failure.
+ *
+ * So the cap is taken against `remainingOuterMs` — the request budget left when
+ * the section actually starts. An operator who lowers `recallCoreDeadlineMs`
+ * below that still gets exactly what they asked for.
+ *
+ * `remainingOuterMs === null` means the request is unbounded and there is nothing
+ * to reserve headroom against. A non-positive remainder means the request is
+ * already over budget, so the section degrades immediately rather than starting
+ * work that cannot be delivered.
+ */
+export function resolveRecallCoreSectionDeadlineMs(options: {
+  configuredCoreDeadlineMs: number;
+  remainingOuterMs: number | null;
+}): number {
+  const configured = options.configuredCoreDeadlineMs;
+  if (!Number.isFinite(configured) || configured <= 0) return configured;
+  const remaining = options.remainingOuterMs;
+  if (remaining === null || !Number.isFinite(remaining)) return configured;
+  if (remaining <= 0) return 1;
+  return Math.min(
+    configured,
+    Math.max(1, Math.floor(remaining * CORE_SECTION_MAX_SHARE_OF_REQUEST)),
+  );
+}
+
+export interface RecallSectionDeadlineOutcome<T> {
+  /** The section's value, or `fallback` when the deadline was exceeded. */
+  value: T;
+  timedOut: boolean;
+  durationMs: number;
+}
+
+/**
+ * Run one recall section under a deadline, degrading to `fallback` instead of
+ * blocking the phase it belongs to (issue #2291).
+ *
+ * Before this existed, `deadlineMs` was recorded in the section metric but
+ * never enforced for core sections: a provider doing a multi-minute scan on a
+ * slow filesystem blocked the whole phase-one `Promise.all`, and kept scanning
+ * after the caller aborted.  Two guarantees fix that:
+ *
+ *  1. The returned promise settles within `deadlineMs`, with `timedOut: true`
+ *     and the caller's neutral value, so one slow optional provider degrades
+ *     independently rather than holding the response.
+ *  2. `run` receives a signal that fires on the deadline AND on the caller's
+ *     abort, so the section can stop its own work at its next checkpoint.
+ *
+ * `deadlineMs <= 0` (or non-finite) means unbounded, matching the config
+ * contract that a zero budget disables the limit.  The section signal is still
+ * created and still tracks the parent, so cancellation propagates either way.
+ */
+export async function runRecallSectionWithinDeadline<T>(options: {
+  deadlineMs: number;
+  fallback: T;
+  parentSignal?: AbortSignal;
+  run: (sectionSignal: AbortSignal) => Promise<T>;
+  now?: () => number;
+}): Promise<RecallSectionDeadlineOutcome<T>> {
+  const now = options.now ?? Date.now;
+  const startedAtMs = now();
+  const controller = new AbortController();
+  const parentSignal = options.parentSignal;
+  const onParentAbort = () => controller.abort();
+  if (parentSignal?.aborted) {
+    controller.abort();
+  } else if (parentSignal) {
+    parentSignal.addEventListener("abort", onParentAbort, { once: true });
+  }
+
+  const bounded = Number.isFinite(options.deadlineMs) && options.deadlineMs > 0;
+  let timer: NodeJS.Timeout | undefined;
+
+  try {
+    // Wrap in a tagged result rather than racing raw values against a sentinel:
+    // T is caller-chosen and must never be mistaken for the timeout marker.
+    const work = options.run(controller.signal).then(
+      (value) => ({ kind: "value" as const, value }),
+    );
+    if (!bounded) {
+      const settled = await work;
+      return { value: settled.value, timedOut: false, durationMs: now() - startedAtMs };
+    }
+    const deadline = Promise.withResolvers<{ kind: "timeout" }>();
+    // Deliberately NOT unref'd: the caller is awaiting this bound, so the timer
+    // must keep the loop alive until it fires or `finally` clears it.
+    timer = setTimeout(() => deadline.resolve({ kind: "timeout" }), options.deadlineMs);
+    const settled = await Promise.race([work, deadline.promise]);
+    if (settled.kind === "timeout") {
+      controller.abort(abortError("recall section deadline exceeded"));
+      // The abandoned work outlives this call; swallow its settlement so a
+      // late rejection is not reported as unhandled.
+      void work.catch(() => {});
+      return { value: options.fallback, timedOut: true, durationMs: now() - startedAtMs };
+    }
+    return { value: settled.value, timedOut: false, durationMs: now() - startedAtMs };
+  } finally {
+    clearTimeout(timer);
+    parentSignal?.removeEventListener("abort", onParentAbort);
+  }
+}
+
+/**
+ * Runs one *optional* core recall section, bounded and accounted for.
+ *
+ * Binds a section's deadline, the caller's abort signal, and the QoS recorder
+ * once so each provider is one call (issue #2291).  A breach degrades the
+ * section to `fallback`, warns with the section name and budget, and records the
+ * section as `timeout` — so a slow provider costs its own section, not the
+ * response.
+ *
+ * The budget is resolved when each section STARTS, against the request budget
+ * still left at that moment (`outerDeadlineAtMs`), not against the original
+ * configured ceiling: sections begin after planning and namespace resolution, and
+ * a section sized to the full request would otherwise still be running when the
+ * request itself is aborted.
+ *
+ * Cancellation degrades too, and must: the section signal fires on the caller's
+ * abort, and the phase this section belongs to is awaited through a race that the
+ * caller's abort also wins.  A rejection here would therefore land on a promise
+ * nobody is awaiting any more — an unhandled rejection rather than a signal.  The
+ * caller learns of its own abort from that race, not from a section result.
+ *
+ * Only sections whose absence leaves recall coherent belong here: the fallback
+ * IS the degraded contract.
+ */
+export function createBoundedCoreSectionRunner(options: {
+  configuredDeadlineMs: number;
+  /** Absolute time the whole request is aborted, or null when unbounded. */
+  outerDeadlineAtMs: number | null;
+  parentSignal?: AbortSignal;
+  record: (metric: RecallSectionMetric) => unknown;
+  logger?: Pick<LoggerBackend, "warn">;
+  now?: () => number;
+}): <T>(
+  section: string,
+  fallback: T,
+  run: (sectionSignal: AbortSignal) => Promise<T>,
+) => Promise<T> {
+  const logger = options.logger ?? log;
+  const now = options.now ?? Date.now;
+  return async <T>(
+    section: string,
+    fallback: T,
+    run: (sectionSignal: AbortSignal) => Promise<T>,
+  ): Promise<T> => {
+    const startedAtMs = now();
+    const deadlineMs = resolveRecallCoreSectionDeadlineMs({
+      configuredCoreDeadlineMs: options.configuredDeadlineMs,
+      remainingOuterMs:
+        options.outerDeadlineAtMs === null ? null : options.outerDeadlineAtMs - startedAtMs,
+    });
+    let outcome: RecallSectionDeadlineOutcome<T>;
+    try {
+      outcome = await runRecallSectionWithinDeadline({
+        deadlineMs,
+        fallback,
+        parentSignal: options.parentSignal,
+        run,
+        now,
+      });
+    } catch (err) {
+      if (!isAbortError(err)) throw err;
+      const durationMs = now() - startedAtMs;
+      options.record({
+        section,
+        priority: "core",
+        durationMs,
+        deadlineMs,
+        source: "skip",
+        success: false,
+        timing: `cancelled(${durationMs}ms)`,
+      });
+      return fallback;
+    }
+    if (outcome.timedOut) {
+      logger.warn(
+        `recall section [${section}] exceeded its ${deadlineMs}ms core deadline ` +
+          `after ${outcome.durationMs}ms; recall continues without it`,
+      );
+    }
+    options.record({
+      section,
+      priority: "core",
+      durationMs: outcome.durationMs,
+      deadlineMs,
+      source: outcome.timedOut ? "timeout" : "fresh",
+      success: !outcome.timedOut,
+    });
+    return outcome.value;
+  };
+}

package/src/storage.ts

@@ -16,6 +16,7 @@ import {
 import { appendFileSync, createReadStream, mkdirSync, readFileSync, statSync, type Dirent } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { normalizeContent, computeContentHash } from "./content-hash.js";
+import { selectArtifactMatches, type ArtifactSearchOptions } from "./artifact-search.js";
 import path from "node:path";
 import { log } from "./logger.js";
 import { createMemorySnapshot } from "./memory-snapshot.js";
@@ -235,36 +236,6 @@ import {
 // stripCitation import removed: legacy rebuild fallback was replaced by a
 // skip-with-warning strategy (Finding 1 — Uhol).  See ensureFactHashIndexAuthoritative.
 
-const ARTIFACT_SEARCH_STOPWORDS = new Set([
-  "a",
-  "an",
-  "and",
-  "are",
-  "as",
-  "at",
-  "be",
-  "but",
-  "by",
-  "for",
-  "from",
-  "has",
-  "have",
-  "i",
-  "in",
-  "is",
-  "it",
-  "of",
-  "on",
-  "or",
-  "that",
-  "the",
-  "this",
-  "to",
-  "was",
-  "were",
-  "with",
-]);
-
 type SharedVersionKind = "memory-status" | "artifact-write" | "cold-write" | "memory-corpus" | "entity-mutation";
 
 type OfflineSyncDigestCacheEntry = {
@@ -323,15 +294,6 @@ export interface MemoryLifecycleEventWriteOptions {
   correlationId?: string;
 }
 
-function tokenizeArtifactSearchText(input: string): string[] {
-  return input
-    .toLowerCase()
-    .split(/[^a-z0-9]+/i)
-    .map((t) => t.trim())
-    .filter((t) => t.length >= 2)
-    .filter((t) => !ARTIFACT_SEARCH_STOPWORDS.has(t));
-}
-
 /**
  * Validate a Memory Worth counter (`mw_success` / `mw_fail`) before we persist
  * it. Rejects non-finite, non-integer, and negative values rather than silently
@@ -4389,23 +4351,17 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return this.memoryReadStore.readAllArtifactsCached();
   }
 
-  async searchArtifacts(query: string, maxResults: number): Promise<MemoryFile[]> {
-    const tokens = tokenizeArtifactSearchText(query);
-    if (tokens.length === 0) return [];
-
-    const artifacts = await this.readAllArtifactsCached();
-    const hits: Array<{ score: number; memory: MemoryFile }> = [];
-    for (const memory of artifacts) {
-      const indexedTokens = new Set(
-        tokenizeArtifactSearchText(`${memory.content} ${(memory.frontmatter.tags ?? []).join(" ")}`)
-      );
-      const score = tokens.reduce((sum, t) => sum + (indexedTokens.has(t) ? 1 : 0), 0);
-      if (score > 0) {
-        hits.push({ score, memory });
-      }
-    }
-    hits.sort((a, b) => b.score - a.score);
-    return hits.slice(0, maxResults).map((h) => h.memory);
+  async searchArtifacts(
+    query: string,
+    maxResults: number,
+    options: ArtifactSearchOptions = {},
+  ): Promise<MemoryFile[]> {
+    return selectArtifactMatches(
+      () => this.readAllArtifactsCached(),
+      query,
+      maxResults,
+      options,
+    );
   }
 
   async writeEntity(