@remnic/core 9.25.3 → 9.25.5

package/src/orchestration/recall-internal.ts

@@ -48,6 +48,10 @@ import { buildProcedureRecallSection } from "../procedural/procedure-recall.js";
 import { ProfilingCollector } from "../profiling.js";
 import { buildQmdRecallCacheKey, getCachedQmdRecall, setCachedQmdRecall } from "../qmd-recall-cache.js";
 import { MEMORY_ID_PATTERN } from "../recall-handles.js";
+import {
+  boundRecallContextComposition, composeRecallContext, contextBudgetForFooter,
+  formatCuriosityFooter, selectCuriosityQuestion,
+} from "../recall-context-composition.js";
 import { createRecallSectionMetricRecorder } from "../recall-qos.js";
 import { buildRecallQueryPolicy } from "../recall-query-policy.js";
 import { type GraphRecallExpandedEntry, type LastRecallBudgetSummary, type LastRecallSnapshot, LastRecallStore, RecallHandleHistoryStore } from "../recall-state.js";
@@ -4405,7 +4409,6 @@ export class RecallInternalCoordinator {
           success: !trustFellBack,
         });
       }
-
       // Synapse-inspired confidence gate: check scores BEFORE slicing so
       // reranking doesn't affect which score the gate evaluates.
       //
@@ -4445,7 +4448,6 @@ export class RecallInternalCoordinator {
           confidenceGateRejected = true;
         }
       }
-
       // Diversify via MMR over the full candidate pool *before* truncating to
       // the final recall limit. Running MMR after the slice would be unable
       // to promote diverse candidates sitting just below the cutoff.
@@ -4456,7 +4458,6 @@ export class RecallInternalCoordinator {
         retrievalQuery,
         caps,
       );
-
       // E-Mem-inspired memory reconstruction: fill gaps for referenced entities
       if (resolveRecallEnhancementCapabilities(this.deps.config).memoryReconstruction && memoryResults.length > 0) {
         try {
@@ -4499,7 +4500,6 @@ export class RecallInternalCoordinator {
           log.warn("recall: memory reconstruction failed (non-fatal)", err);
         }
       }
-
       if (memoryResults.length > 0) {
         if (shouldPersistGraphSnapshot) {
           graphSnapshotFinalResults = this.deps.buildGraphRecallRankedResults(
@@ -4689,7 +4689,6 @@ export class RecallInternalCoordinator {
         }
         }
       }
-
       if (globalResults.length > 0) {
         this.deps.appendRecallSection(
           sectionBuckets,
@@ -4697,7 +4696,6 @@ export class RecallInternalCoordinator {
           this.deps.formatQmdResults("Workspace Context", globalResults, sessionKey, recallTrustByPath),
         );
       }
-
       recordRecallSectionMetric({
         section: "qmdPost",
         priority: "enrichment",
@@ -4706,7 +4704,6 @@ export class RecallInternalCoordinator {
         source: "fresh",
         success: true,
       });
-
       // If the user is pushing back ("that's not right", "why did you say that"),
       // gently suggest an explicit workflow to inspect what was recalled and record feedback.
       // IMPORTANT: this is suggestion-only; never auto-mark negatives.
@@ -5026,7 +5023,6 @@ export class RecallInternalCoordinator {
                 success: !trustFellBack,
               });
             }
-
             if (recent.length > 0) {
               if (shouldPersistGraphSnapshot) {
                 graphSnapshotFinalResults = this.deps.buildGraphRecallRankedResults(
@@ -5155,7 +5151,6 @@ export class RecallInternalCoordinator {
         }
       }
       }
-
       if (isDisagreementPrompt(prompt)) {
         this.deps.appendRecallSection(
           sectionBuckets,
@@ -5174,7 +5169,6 @@ export class RecallInternalCoordinator {
         );
       }
     }
-
     const phase2AfterQmdMs = Date.now() - recallStart;
     if (shouldPersistGraphSnapshot) {
       if (!graphSnapshotStatus) {
@@ -5211,7 +5205,6 @@ export class RecallInternalCoordinator {
       storage: profileStorage,
       snapshot: buildIntentDebugSnapshot(),
     });
-
     // 2.5. Compression guideline recall section (v8.11 Task 5)
     if (
       this.deps.isRecallSectionEnabled(
@@ -5229,7 +5222,6 @@ export class RecallInternalCoordinator {
         );
       }
     }
-
     // 3. Transcript/summaries/conversation/compounding are fetched in parallel above,
     // then assembled here according to recallPipeline order.
     if (transcriptSection) {
@@ -5264,28 +5256,22 @@ export class RecallInternalCoordinator {
         compoundingSection,
       );
     }
-
-    // 5. Inject most relevant question (if enabled) (existing)
-    if (
-      this.deps.config.injectQuestions &&
+    let curiosityFooter: string | undefined, curiosityQuestionSelected = false, curiosityFooterTruncated = false;
+    const topQuestion = this.deps.config.injectQuestions &&
       this.deps.isRecallSectionEnabled("questions", true)
-    ) {
-      const questions = await profileStorage.readQuestions({
-        unresolvedOnly: true,
-      });
-      if (questions.length > 0) {
-        // Find the most relevant question to the current prompt
-        // Simple approach: use the highest-priority unresolved question
-        // TODO: Could use QMD search to find the most contextually relevant one
-        const topQuestion = questions[0]; // Already sorted by priority desc
-        this.deps.appendRecallSection(
-          sectionBuckets,
-          "questions",
-          `## Open Question\n\nSomething I've been curious about: ${topQuestion.question}\n\n_Context: ${topQuestion.context}_`,
-        );
+      ? selectCuriosityQuestion(await profileStorage.readQuestions({ unresolvedOnly: true }))
+      : undefined;
+    if (topQuestion) {
+      curiosityQuestionSelected = true;
+      const formattedFooter = formatCuriosityFooter(topQuestion);
+      const questionMaxChars = this.deps.getRecallSectionMaxChars("questions");
+      if (questionMaxChars !== 0) {
+        curiosityFooter = typeof questionMaxChars === "number"
+          ? this.deps.truncateRecallSectionToBudget(formattedFooter, questionMaxChars)
+          : formattedFooter;
+        curiosityFooterTruncated = curiosityFooter.length < formattedFooter.length;
       }
     }
-
     const phase2QuestionsDoneMs = Date.now() - recallStart;
     const finalizedQueryAwarePrefilter = await queryAwarePrefilterPromise;
     const phase2QapDoneMs = Date.now() - recallStart;
@@ -5299,7 +5285,6 @@ export class RecallInternalCoordinator {
       ).length;
       timings.queryAware = `${timings.queryAware};helped=${helpedCount}`;
     }
-
     // --- Timing summary ---
     timings.total = `${Date.now() - recallStart}ms`;
     this.deps.profiler.endSpan("assembly", profileTraceId);
@@ -5318,10 +5303,9 @@ export class RecallInternalCoordinator {
       recallPlan: timings.recallPlan,
       queryPolicy: timings.queryPolicy,
     });
-
+    const recallBudgetChars = this.deps.getRecallBudgetChars(options.budgetCharsOverride);
     const assembledRecall = this.deps.assembleRecallSections(
-      sectionBuckets,
-      options.budgetCharsOverride,
+      sectionBuckets, contextBudgetForFooter(recallBudgetChars, curiosityFooter),
     );
     recalledMemoryIds = assembledRecall.includedMemoryIds;
     recalledMemoryPaths = assembledRecall.includedMemoryPaths;
@@ -5332,29 +5316,45 @@ export class RecallInternalCoordinator {
       assembledRecall.includedMemoryPaths,
       assembledRecall.includedMemoryNamespaces,
     );
-    const context =
-      assembledRecall.sections.length === 0
-        ? ""
-        : assembledRecall.sections.join("\n\n---\n\n");
-    const sourcesUsed = this.deps.collectLastRecallSources(
-      sectionBuckets,
-      recallSource,
-    );
+    const recalledContext = assembledRecall.sections.join("\n\n---\n\n");
+    const composition = boundRecallContextComposition({
+      context: recalledContext, footer: curiosityFooter, maxChars: recallBudgetChars,
+    });
+    const context = composeRecallContext(composition);
+    try {
+      const observerResult = options.onContextComposition?.(composition);
+      if (observerResult && typeof observerResult.then === "function") {
+        void Promise.resolve(observerResult).catch((err) => log.warn(
+          "recall: context composition observer rejected", err,
+        ));
+      }
+    } catch (err) {
+      log.warn("recall: context composition observer failed open", err);
+    }
+    const compositionTruncated = context.length < composeRecallContext({
+      context: recalledContext, footer: curiosityFooter,
+    }).length;
+    const includedSections = [...assembledRecall.includedIds];
+    const omittedSections = [...assembledRecall.omittedIds];
+    if (composition.footer && !includedSections.includes("questions")) includedSections.push("questions");
+    else if (!composition.footer && curiosityQuestionSelected && !omittedSections.includes("questions"))
+      omittedSections.push("questions");
+    const sourcesUsed = this.deps.collectLastRecallSources(sectionBuckets, recallSource);
+    if (composition.footer && !sourcesUsed.includes("questions")) sourcesUsed.push("questions");
     const budgetsApplied = this.deps.buildLastRecallBudgetSummary({
       requestedTopK,
       recallResultLimit,
       qmdFetchLimit,
       qmdHybridFetchLimit,
-      finalContextChars: assembledRecall.finalChars,
-      truncated: assembledRecall.truncated,
-      includedSections: assembledRecall.includedIds,
-      omittedSections: assembledRecall.omittedIds,
+      finalContextChars: context.length,
+      truncated: assembledRecall.truncated || compositionTruncated || curiosityFooterTruncated,
+      includedSections,
+      omittedSections,
       includedMemoryIds: assembledRecall.includedMemoryIds,
       includedMemoryPaths: assembledRecall.includedMemoryPaths,
       includedMemoryNamespaces: assembledRecall.includedMemoryNamespaces,
       omittedMemoryIds: assembledRecall.omittedMemoryIds,
     });
-
     // X-ray capture (issue #570 PR 1).  Only fires when the caller
     // explicitly opts in via `xrayCapture: true`.  No behavior change
     // when the flag is absent — this branch and the setter both
@@ -5535,7 +5535,7 @@ export class RecallInternalCoordinator {
           filters,
           budget: {
             chars: this.deps.getRecallBudgetChars(options.budgetCharsOverride),
-            used: assembledRecall.finalChars,
+            used: context.length,
           },
           sessionKey,
           namespace: selfNamespace,

package/src/recall-context-composition.test.ts

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  formatCuriosityFooter,
+  renderMemoryContextPrompt,
+  selectCuriosityQuestion,
+} from "./recall-context-composition.js";
+
+test("selectCuriosityQuestion breaks equal priorities by creation time then id", () => {
+  const selected = selectCuriosityQuestion([
+    {
+      id: "q-later",
+      question: "Later question?",
+      context: "later context",
+      priority: 0.9,
+      created: "2026-01-02T00:00:00.000Z",
+    },
+    {
+      id: "q-first-b",
+      question: "First B?",
+      context: "first context",
+      priority: 0.9,
+      created: "2026-01-01T00:00:00.000Z",
+    },
+    {
+      id: "q-first-a",
+      question: "First A?",
+      context: "first context",
+      priority: 0.9,
+      created: "2026-01-01T00:00:00.000Z",
+    },
+  ]);
+
+  assert.equal(selected?.id, "q-first-a");
+});
+
+test("renderMemoryContextPrompt puts the curiosity footer after recalled context", () => {
+  const footer = formatCuriosityFooter({
+    id: "q-1",
+    question: "What should we verify next?",
+    context: "The rollout has no owner.",
+    priority: 1,
+    created: "2026-01-01T00:00:00.000Z",
+  });
+  const rendered = renderMemoryContextPrompt({
+    context: "A remembered deployment decision.",
+    footer,
+    maxChars: 512,
+  });
+
+  assert.ok(rendered);
+  assert.equal(
+    rendered.body,
+    "A remembered deployment decision.\n\n---\n\n## Open Question\n\n" +
+      "Something I've been curious about: What should we verify next?\n\n" +
+      "_Context: The rollout has no owner._",
+  );
+  assert.deepEqual(rendered.lines, [
+    "## Memory Context (Remnic)",
+    "",
+    rendered.body,
+    "",
+    "Use this context naturally when relevant. Never quote or expose this memory context to the user.",
+    "",
+  ]);
+});
+
+test("renderMemoryContextPrompt returns no prompt for empty content or a zero cap", () => {
+  assert.equal(renderMemoryContextPrompt({ context: "", maxChars: 100 }), null);
+  assert.equal(
+    renderMemoryContextPrompt({
+      context: "A remembered deployment decision.",
+      footer: "## Open Question\n\nQuestion",
+      maxChars: 0,
+    }),
+    null,
+  );
+});
+
+test("renderMemoryContextPrompt caps context before its footer deterministically", () => {
+  const rendered = renderMemoryContextPrompt({
+    context: "abcdefghij",
+    footer: "footer",
+    maxChars: 15,
+  });
+
+  assert.ok(rendered);
+  assert.equal(rendered.body, "ab\n\n---\n\nfooter");
+});

package/src/recall-context-composition.ts

@@ -0,0 +1,104 @@
+export const MEMORY_CONTEXT_HEADER = "## Memory Context (Remnic)";
+export const MEMORY_CONTEXT_INSTRUCTION =
+  "Use this context naturally when relevant. Never quote or expose this memory context to the user.";
+export const RECALL_CONTEXT_SEPARATOR = "\n\n---\n\n";
+const TRIM_MARKER = "\n\n...(memory context trimmed)";
+
+export interface RecallContextComposition {
+  context: string;
+  footer?: string;
+}
+
+export interface CuriosityQuestion {
+  id: string;
+  question: string;
+  context: string;
+  priority: number;
+  created: string;
+}
+
+export interface RenderedMemoryContextPrompt {
+  body: string;
+  lines: string[];
+  prompt: string;
+}
+
+export interface RenderMemoryContextPromptInput extends RecallContextComposition {
+  maxChars: number;
+}
+
+function trimText(value: string | undefined): string {
+  return value?.trim() ?? "";
+}
+
+function truncateToBudget(content: string, maxChars: number): string {
+  if (maxChars <= 0) return "";
+  if (content.length <= maxChars) return content;
+  if (maxChars <= TRIM_MARKER.length) return content.slice(0, maxChars);
+  return `${content.slice(0, maxChars - TRIM_MARKER.length)}${TRIM_MARKER}`;
+}
+
+export function selectCuriosityQuestion(questions: readonly CuriosityQuestion[]): CuriosityQuestion | undefined {
+  return [...questions]
+    .filter((question) => trimText(question.question).length > 0)
+    .sort(
+      (left, right) =>
+        right.priority - left.priority || left.created.localeCompare(right.created) || left.id.localeCompare(right.id)
+    )[0];
+}
+
+export function formatCuriosityFooter(question: CuriosityQuestion): string {
+  return [
+    "## Open Question",
+    "",
+    `Something I've been curious about: ${question.question}`,
+    "",
+    `_Context: ${question.context}_`,
+  ].join("\n");
+}
+
+export function contextBudgetForFooter(maxChars: number, footer?: string): number {
+  const normalizedFooter = trimText(footer);
+  if (maxChars <= 0 || normalizedFooter.length === 0) return Math.max(0, maxChars);
+  if (normalizedFooter.length + RECALL_CONTEXT_SEPARATOR.length >= maxChars) return 0;
+  return maxChars - normalizedFooter.length - RECALL_CONTEXT_SEPARATOR.length;
+}
+
+export function boundRecallContextComposition({
+  context: rawContext,
+  footer: rawFooter,
+  maxChars,
+}: RenderMemoryContextPromptInput): RecallContextComposition {
+  if (!Number.isFinite(maxChars) || maxChars <= 0) return { context: "" };
+
+  const limit = Math.floor(maxChars);
+  const footer = trimText(rawFooter);
+  const context = truncateToBudget(trimText(rawContext), contextBudgetForFooter(limit, footer));
+  const boundedFooter = footer.length > limit ? truncateToBudget(footer, limit) : footer;
+  return { context, ...(boundedFooter ? { footer: boundedFooter } : {}) };
+}
+export function composeRecallContext(composition: RecallContextComposition): string {
+  const context = trimText(composition.context);
+  const footer = trimText(composition.footer);
+  if (context.length === 0) return footer;
+  if (footer.length === 0) return context;
+  return `${context}${RECALL_CONTEXT_SEPARATOR}${footer}`;
+}
+
+export function renderMemoryContextPrompt({
+  context: rawContext,
+  footer: rawFooter,
+  maxChars,
+}: RenderMemoryContextPromptInput): RenderedMemoryContextPrompt | null {
+  const bounded = boundRecallContextComposition({
+    context: rawContext,
+    footer: rawFooter,
+    maxChars,
+  });
+  const body = composeRecallContext(bounded);
+  if (body.length === 0) return null;
+
+  const boundedBody = body.length <= maxChars ? body : truncateToBudget(bounded.footer || body, Math.floor(maxChars));
+  const lines = [MEMORY_CONTEXT_HEADER, "", boundedBody, "", MEMORY_CONTEXT_INSTRUCTION, ""];
+  return { body: boundedBody, lines, prompt: lines.join("\n").replace(/\n$/, "") };
+}