@remnic/core 9.69.49 → 9.69.51

package/src/orchestration/recall-recognition-search.test.ts

@@ -0,0 +1,290 @@
+/**
+ * recall-recognition-search.test.ts — issue #2975 recall-slice wiring.
+ *
+ * Pins the fetchQmdMemoryResultsWithArtifactTopUp seam:
+ *  - gate off: original fetch only (zero extra I/O, same options object);
+ *  - under-threshold index: recognition pass, no vector fetch for that ns;
+ *  - above-threshold index: vector fetch, no recognizer call.
+ */
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import test from "node:test";
+
+import { saveRecognitionIndex, type RecognitionIndex } from "../recall-recognition-tier.js";
+import {
+  fetchQmdMemoryResultsWithRecognitionSwap,
+  type RecognitionSearchDeps,
+} from "./recall-recognition-search.js";
+import type { QmdSearchResult } from "../types.js";
+
+function vec(namespace: string, filePath: string, score = 1): QmdSearchResult {
+  return { docid: `${namespace}:${filePath}`, namespace, path: filePath, score, snippet: filePath };
+}
+
+function indexOf(ids: string[]): RecognitionIndex {
+  return {
+    version: 1,
+    entries: ids.map((id) => ({ id, description: `trigger for ${id}` })),
+  };
+}
+
+async function tmpDir(): Promise<string> {
+  return mkdtemp(path.join(os.tmpdir(), "remnic-recognition-search-"));
+}
+
+function makeDeps(args: {
+  recallRecognitionTier: boolean;
+  recognitionIndexMaxEntries?: number;
+  storages: Record<string, { dir: string; pathsById: Record<string, string> }>;
+  vectorResults?: QmdSearchResult[];
+  recognize?: (prompt: string) => Promise<string>;
+  recognizeError?: Error;
+}) {
+  const fetchCalls: Array<{
+    prompt: string;
+    qmdFetchLimit: number;
+    qmdHybridFetchLimit: number;
+    options: unknown;
+  }> = [];
+  const recognizePrompts: string[] = [];
+  const storageForCalls: string[] = [];
+
+  const deps = {
+    config: {
+      recallRecognitionTier: args.recallRecognitionTier,
+      recognitionIndexMaxEntries: args.recognitionIndexMaxEntries ?? 500,
+    },
+    storageRouter: {
+      storageFor: async (namespace: string) => {
+        storageForCalls.push(namespace);
+        const storage = args.storages[namespace];
+        if (!storage) throw new Error(`unknown namespace ${namespace}`);
+        return {
+          dir: storage.dir,
+          findExistingMemoryPaths: async (ids: string[]) => {
+            const found = new Map<string, string[]>();
+            for (const id of ids) {
+              const filePath = storage.pathsById[id];
+              if (filePath) found.set(id, [filePath]);
+            }
+            return found;
+          },
+        };
+      },
+    },
+    fastLlmForRerank: {
+      chatCompletion: async (messages: Array<{ role: string; content: string }>) => {
+        if (args.recognizeError) throw args.recognizeError;
+        const prompt = messages[0]?.content ?? "";
+        recognizePrompts.push(prompt);
+        return { content: await (args.recognize ?? (async () => ""))(prompt) };
+      },
+    },
+    fetchQmdMemoryResultsWithArtifactTopUp: async (
+      prompt: string,
+      qmdFetchLimit: number,
+      qmdHybridFetchLimit: number,
+      options: unknown,
+    ) => {
+      fetchCalls.push({ prompt, qmdFetchLimit, qmdHybridFetchLimit, options });
+      return args.vectorResults ?? [];
+    },
+  } as unknown as RecognitionSearchDeps;
+
+  return { deps, fetchCalls, recognizePrompts, storageForCalls };
+}
+
+const baseOptions = {
+  namespacesEnabled: true,
+  recallNamespaces: ["alpha"],
+  resolveNamespace: (filePath: string) => (filePath.startsWith("beta/") ? "beta" : "alpha"),
+};
+
+test("off-path: gate off calls original fetch once with the same options object", async () => {
+  const options = { ...baseOptions };
+  const { deps, fetchCalls, recognizePrompts, storageForCalls } = makeDeps({
+    recallRecognitionTier: false,
+    storages: {},
+    vectorResults: [vec("alpha", "facts/from-vector.md")],
+  });
+
+  const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "q", 7, 9, options);
+
+  assert.equal(fetchCalls.length, 1);
+  assert.equal(fetchCalls[0].prompt, "q");
+  assert.equal(fetchCalls[0].qmdFetchLimit, 7);
+  assert.equal(fetchCalls[0].qmdHybridFetchLimit, 9);
+  assert.equal(fetchCalls[0].options, options);
+  assert.equal(recognizePrompts.length, 0);
+  assert.equal(storageForCalls.length, 0);
+  assert.deepEqual(out.map((r) => r.path), ["facts/from-vector.md"]);
+});
+
+test("acceptance: under-threshold namespace uses recognition, not vector search", async () => {
+  const dir = await tmpDir();
+  try {
+    await saveRecognitionIndex(dir, indexOf(["m-001", "m-002", "m-003"]));
+    const { deps, fetchCalls, recognizePrompts } = makeDeps({
+      recallRecognitionTier: true,
+      recognitionIndexMaxEntries: 10,
+      storages: {
+        alpha: {
+          dir,
+          pathsById: {
+            "m-001": path.join(dir, "facts/m-001.md"),
+            "m-002": path.join(dir, "facts/m-002.md"),
+            "m-003": path.join(dir, "facts/m-003.md"),
+          },
+        },
+      },
+      recognize: async () => "m-002, m-003",
+      vectorResults: [vec("alpha", "facts/must-not-appear.md")],
+    });
+
+    const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "which memories?", 5, 5, {
+      ...baseOptions,
+    });
+
+    assert.equal(fetchCalls.length, 0, "vector search must not run on the recognition tier");
+    assert.equal(recognizePrompts.length, 1);
+    assert.ok(recognizePrompts[0].includes("m-001: trigger for m-001"));
+    assert.ok(recognizePrompts[0].includes("m-002: trigger for m-002"));
+    assert.ok(recognizePrompts[0].includes("m-003: trigger for m-003"));
+    assert.deepEqual(
+      out.map((r) => r.path),
+      ["facts/m-002.md", "facts/m-003.md"],
+    );
+    assert.deepEqual(
+      out.map((r) => r.namespace),
+      ["alpha", "alpha"],
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("acceptance: above-threshold namespace uses vector search, not the recognizer", async () => {
+  const dir = await tmpDir();
+  try {
+    await saveRecognitionIndex(dir, indexOf(["a", "b", "c", "d", "e"]));
+    const options = { ...baseOptions };
+    const { deps, fetchCalls, recognizePrompts } = makeDeps({
+      recallRecognitionTier: true,
+      recognitionIndexMaxEntries: 4,
+      storages: { alpha: { dir, pathsById: {} } },
+      vectorResults: [vec("alpha", "facts/vector-hit.md")],
+    });
+
+    const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "q", 3, 3, options);
+
+    assert.equal(recognizePrompts.length, 0);
+    assert.equal(fetchCalls.length, 1);
+    assert.equal(fetchCalls[0].options, options);
+    assert.deepEqual(out.map((r) => r.path), ["facts/vector-hit.md"]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("acceptance: missing index falls back to vector search with original options", async () => {
+  const dir = await tmpDir();
+  try {
+    const options = { ...baseOptions };
+    const { deps, fetchCalls, recognizePrompts } = makeDeps({
+      recallRecognitionTier: true,
+      storages: { alpha: { dir, pathsById: {} } },
+      vectorResults: [vec("alpha", "facts/fallback.md")],
+    });
+
+    const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "q", 2, 2, options);
+
+    assert.equal(recognizePrompts.length, 0);
+    assert.equal(fetchCalls.length, 1);
+    assert.equal(fetchCalls[0].options, options);
+    assert.deepEqual(out.map((r) => r.path), ["facts/fallback.md"]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("mixed namespaces: small ns recognizes; large ns stays on vector search", async () => {
+  const small = await tmpDir();
+  const large = await tmpDir();
+  try {
+    await saveRecognitionIndex(small, indexOf(["s-1", "s-2"]));
+    await saveRecognitionIndex(large, indexOf(["l-1", "l-2", "l-3"]));
+    const { deps, fetchCalls, recognizePrompts } = makeDeps({
+      recallRecognitionTier: true,
+      recognitionIndexMaxEntries: 2,
+      storages: {
+        alpha: {
+          dir: small,
+          pathsById: { "s-1": path.join(small, "facts/s-1.md") },
+        },
+        beta: { dir: large, pathsById: {} },
+      },
+      recognize: async () => "s-1",
+      vectorResults: [vec("beta", "facts/large-hit.md")],
+    });
+
+    const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "q", 10, 10, {
+      namespacesEnabled: true,
+      recallNamespaces: ["alpha", "beta"],
+      resolveNamespace: (filePath) => (filePath.includes("large") ? "beta" : "alpha"),
+    });
+
+    assert.equal(recognizePrompts.length, 1);
+    assert.equal(fetchCalls.length, 1);
+    assert.deepEqual(
+      (fetchCalls[0].options as { recallNamespaces: string[] }).recallNamespaces,
+      ["beta"],
+    );
+    assert.deepEqual(
+      out.map((r) => `${r.namespace}:${r.path}`),
+      ["alpha:facts/s-1.md", "beta:facts/large-hit.md"],
+    );
+  } finally {
+    await rm(small, { recursive: true, force: true });
+    await rm(large, { recursive: true, force: true });
+  }
+});
+
+test("loud degradation: recognizer throw routes that namespace back to vector search", async () => {
+  const dir = await tmpDir();
+  try {
+    await saveRecognitionIndex(dir, indexOf(["m-001"]));
+    const { deps, fetchCalls, recognizePrompts } = makeDeps({
+      recallRecognitionTier: true,
+      storages: { alpha: { dir, pathsById: { "m-001": path.join(dir, "facts/m-001.md") } } },
+      recognizeError: new Error("model down"),
+      vectorResults: [vec("alpha", "facts/degraded.md")],
+    });
+
+    const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "q", 4, 4, { ...baseOptions });
+
+    assert.equal(recognizePrompts.length, 0);
+    assert.equal(fetchCalls.length, 1);
+    assert.deepEqual(out.map((r) => r.path), ["facts/degraded.md"]);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("namespaces disabled: gate on still calls original fetch with the same options object", async () => {
+  const options = { ...baseOptions, namespacesEnabled: false };
+  const { deps, fetchCalls, recognizePrompts, storageForCalls } = makeDeps({
+    recallRecognitionTier: true,
+    storages: {},
+    vectorResults: [vec("alpha", "facts/from-vector.md")],
+  });
+
+  const out = await fetchQmdMemoryResultsWithRecognitionSwap(deps, "q", 2, 2, options);
+
+  assert.equal(fetchCalls.length, 1);
+  assert.equal(fetchCalls[0].options, options);
+  assert.equal(recognizePrompts.length, 0);
+  assert.equal(storageForCalls.length, 0);
+  assert.deepEqual(out.map((r) => r.path), ["facts/from-vector.md"]);
+});

package/src/orchestration/recall-recognition-search.ts

@@ -0,0 +1,160 @@
+/**
+ * Recognition-tier swap at fetchQmdMemoryResultsWithArtifactTopUp (issue #2975).
+ *
+ * Off-path (recallRecognitionTier !== true): original fetch only — no index
+ * load, no model call. On-path: namespaces whose index is at or under
+ * recognitionIndexMaxEntries go through one recognizer call; the rest keep
+ * vector search. A failing recognizer degrades that namespace to vector search.
+ */
+import path from "node:path";
+
+import { log } from "../logger.js";
+import { dedupeResultsByNamespace } from "../recall-memory-map.js";
+import {
+  decideRecognitionTier,
+  loadRecognitionIndex,
+  runRecognitionTier,
+  type RecognitionIndex,
+} from "../recall-recognition-tier.js";
+import type { QmdSearchResult } from "../types.js";
+import { throwIfRecallAborted } from "./orchestrator-helpers.js";
+import type { RecallInternalDeps } from "./recall-internal-deps.js";
+
+export type RecognitionSearchDeps = Pick<
+  RecallInternalDeps,
+  "config" | "storageRouter" | "fastLlmForRerank" | "fetchQmdMemoryResultsWithArtifactTopUp"
+>;
+
+type ArtifactTopUpOptions = Parameters<
+  RecognitionSearchDeps["fetchQmdMemoryResultsWithArtifactTopUp"]
+>[3];
+
+type RecognitionStorage = {
+  dir: string;
+  findExistingMemoryPaths(ids: string[]): Promise<Map<string, string[]>>;
+};
+
+export async function fetchQmdMemoryResultsWithRecognitionSwap(
+  deps: RecognitionSearchDeps,
+  prompt: string,
+  qmdFetchLimit: number,
+  qmdHybridFetchLimit: number,
+  options: ArtifactTopUpOptions,
+): Promise<QmdSearchResult[]> {
+  if (
+    deps.config.recallRecognitionTier !== true ||
+    options.collection ||
+    options.namespacesEnabled !== true
+  ) {
+    return deps.fetchQmdMemoryResultsWithArtifactTopUp(
+      prompt,
+      qmdFetchLimit,
+      qmdHybridFetchLimit,
+      options,
+    );
+  }
+
+  const namespaces = options.recallNamespaces.filter(Boolean);
+  if (namespaces.length === 0) {
+    return deps.fetchQmdMemoryResultsWithArtifactTopUp(
+      prompt,
+      qmdFetchLimit,
+      qmdHybridFetchLimit,
+      options,
+    );
+  }
+
+  throwIfRecallAborted(options.abortSignal);
+  const maxEntries = deps.config.recognitionIndexMaxEntries;
+  const recognitionNs: Array<{ namespace: string; storage: RecognitionStorage; index: RecognitionIndex }> = [];
+  const vectorNs: string[] = [];
+
+  for (const namespace of namespaces) {
+    throwIfRecallAborted(options.abortSignal);
+    const storage = (await deps.storageRouter.storageFor(namespace)) as RecognitionStorage;
+    const index = await loadRecognitionIndex(storage.dir);
+    const decision = decideRecognitionTier(index, { maxEntries });
+    if (index !== null && decision.tier === "recognition") {
+      recognitionNs.push({ namespace, storage, index });
+    } else {
+      vectorNs.push(namespace);
+    }
+  }
+
+  if (recognitionNs.length === 0) {
+    return deps.fetchQmdMemoryResultsWithArtifactTopUp(
+      prompt,
+      qmdFetchLimit,
+      qmdHybridFetchLimit,
+      options,
+    );
+  }
+
+  const recognize = async (recognitionPrompt: string): Promise<string | null | undefined> => {
+    const reply = await deps.fastLlmForRerank.chatCompletion(
+      [{ role: "user", content: recognitionPrompt }],
+      { operation: "recognition-tier", priority: "recall-critical" },
+    );
+    return reply?.content;
+  };
+
+  const recognized: QmdSearchResult[] = [];
+  for (const { namespace, storage, index } of recognitionNs) {
+    throwIfRecallAborted(options.abortSignal);
+    try {
+      const run = await runRecognitionTier(prompt, index.entries, recognize);
+      recognized.push(
+        ...(await hitsFromIds(namespace, storage, index, run.ids)),
+      );
+    } catch (err) {
+      log.warn(
+        `recognition tier degraded to vector search: recognizer failed${
+          err instanceof Error ? ` (${err.message})` : ""
+        }`,
+      );
+      vectorNs.push(namespace);
+    }
+  }
+
+  const vectorResults =
+    vectorNs.length === 0
+      ? []
+      : await deps.fetchQmdMemoryResultsWithArtifactTopUp(
+          prompt,
+          qmdFetchLimit,
+          qmdHybridFetchLimit,
+          { ...options, recallNamespaces: vectorNs },
+        );
+
+  return dedupeResultsByNamespace(
+    [...recognized, ...vectorResults],
+    options.resolveNamespace,
+    qmdFetchLimit,
+  );
+}
+
+async function hitsFromIds(
+  namespace: string,
+  storage: RecognitionStorage,
+  index: RecognitionIndex,
+  ids: readonly string[],
+): Promise<QmdSearchResult[]> {
+  if (ids.length === 0) return [];
+  const pathsById = await storage.findExistingMemoryPaths([...ids]);
+  const descriptionById = new Map(index.entries.map((entry) => [entry.id, entry.description]));
+  const hits: QmdSearchResult[] = [];
+  for (const [offset, id] of ids.entries()) {
+    const absPath = pathsById.get(id)?.[0];
+    if (!absPath) continue;
+    const rel = path.relative(storage.dir, absPath).split(path.sep).join("/");
+    if (!rel || rel.startsWith("..")) continue;
+    hits.push({
+      docid: `${namespace}:${rel}`,
+      namespace,
+      path: rel,
+      score: ids.length - offset,
+      snippet: descriptionById.get(id) ?? id,
+    });
+  }
+  return hits;
+}

package/src/procedural/procedure-recall.ts

@@ -1,5 +1,6 @@
 /**
  * Intent-gated recall for active procedure memories (issue #519).
+ * Session-end experience episodes (issue #2979) compete here after promotion.
  */
 
 import type { MemoryFile, PluginConfig } from "../types.js";
@@ -9,6 +10,10 @@ import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
 import { canRecallToolScopedMemory } from "../tool-scoped-memory.js";
 import { resolveSecurityCapabilities } from "../capabilities.js";
 import { renderAuthorityBoundContent } from "../recall-context-composition.js";
+import {
+  renderSessionExperiencePreview,
+  scoreSessionExperienceForPrompt,
+} from "../experience/session-experience-recall.js";
 
 function tokenOverlapScore(prompt: string, memoryText: string): number {
   const norm = (s: string) =>
@@ -31,12 +36,16 @@ function scoreProcedureForPrompt(
   m: MemoryFile,
   prompt: string,
   queryIntent: ReturnType<typeof inferIntentFromText>,
+  experienceEnabled: boolean,
 ): number {
   const memText = `${m.content}\n${(m.frontmatter.tags ?? []).join(" ")}`;
   const jaccard = tokenOverlapScore(prompt, memText);
   const memIntent = inferIntentFromText(m.content.slice(0, 2000));
   const intentScore = intentCompatibilityScore(queryIntent, memIntent);
-  return jaccard * 0.55 + intentScore * 0.45;
+  const base = jaccard * 0.55 + intentScore * 0.45;
+  if (!experienceEnabled) return base;
+  const experience = scoreSessionExperienceForPrompt(m, prompt);
+  return experience === null ? base : Math.max(base, experience);
 }
 
 /**
@@ -83,6 +92,7 @@ export async function buildProcedureRecallSection(
   );
 
   const all = await storage.readAllMemories();
+  const experienceEnabled = config.sessionExperience?.enabled === true;
   const scored = all
     .filter(
       (m) =>
@@ -91,7 +101,7 @@ export async function buildProcedureRecallSection(
         (options?.partitionToolScoped !== true ||
           canRecallToolScopedMemory(m.frontmatter, options.requestingConnector)),
     )
-    .map((m) => ({ m, score: scoreProcedureForPrompt(m, trimmed, queryIntent) }))
+    .map((m) => ({ m, score: scoreProcedureForPrompt(m, trimmed, queryIntent, experienceEnabled) }))
     .filter((x) => x.score > 0.04)
     .sort((a, b) => b.score - a.score)
     .slice(0, maxN);
@@ -110,7 +120,8 @@ export async function buildProcedureRecallSection(
   const security = resolveSecurityCapabilities(config);
   const blocks = scored.map(({ m, score }) => {
     const id = m.frontmatter.id;
-    const flat = m.content.replace(/\s+/g, " ").trim();
+    const labeled = experienceEnabled ? renderSessionExperiencePreview(m) : null;
+    const flat = (labeled ?? m.content).replace(/\s+/g, " ").trim();
     const preview = flat.slice(0, 320);
     const suffix = flat.length > 320 ? "…" : "";
     const body = renderAuthorityBoundContent(`${preview}${suffix}`, m.frontmatter.origin, {

package/src/recall-audit.test.ts

@@ -49,3 +49,37 @@ test("pruneRecallAuditEntries removes day directories older than retention", asy
   assert.equal((await stat(keepDir)).isDirectory(), true);
   await assert.rejects(stat(deleteDir));
 });
+
+test("#2972 audit entry persists degradation when present and omits it otherwise", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-recall-audit-deg-"));
+  const healthy = {
+    ts: "2026-04-12T14:30:12.445Z",
+    sessionKey: "agent/main:session/healthy",
+    agentId: "main",
+    trigger: "access-surface",
+    queryText: "How did the CI outage resolve?",
+    candidateMemoryIds: ["mem_1"],
+    summary: "CI recovered.",
+    injectedChars: 12,
+    toggleState: "enabled" as const,
+  };
+  const degraded = {
+    ...healthy,
+    sessionKey: "agent/main:session/degraded",
+    degradation: {
+      state: "degraded" as const,
+      reason: "budget-compacted" as const,
+      budget: { contextBudget: 80, fullChars: 200, deliveredChars: 80 },
+    },
+  };
+
+  await appendRecallAuditEntry(root, healthy);
+  await appendRecallAuditEntry(root, degraded);
+
+  const healthyPath = buildRecallAuditPath(root, healthy.ts, healthy.sessionKey);
+  const degradedPath = buildRecallAuditPath(root, degraded.ts, degraded.sessionKey);
+  assert.deepEqual(JSON.parse((await readFile(healthyPath, "utf8")).trim()), healthy);
+  assert.equal("degradation" in JSON.parse((await readFile(healthyPath, "utf8")).trim()), false);
+  assert.deepEqual(JSON.parse((await readFile(degradedPath, "utf8")).trim()), degraded);
+});
+

package/src/recall-audit.ts

@@ -2,6 +2,8 @@ import type { Dirent } from "node:fs";
 import { appendFile, mkdir, readdir, rm } from "node:fs/promises";
 import path from "node:path";
 
+import type { RecallContextDegradation } from "./recall-context-composition.js";
+
 export interface RecallAuditEntry {
   ts: string;
   sessionKey: string;
@@ -16,6 +18,8 @@ export interface RecallAuditEntry {
   plannerMode?: string;
   requestedMode?: string;
   fallbackUsed?: boolean;
+  /** Injected-context degradation (#2972). Absent on a healthy recall. */
+  degradation?: RecallContextDegradation;
 }
 
 function formatIsoDate(ts: string): string {