@remnic/core 9.25.4 → 9.25.6

package/src/access-http.ts

@@ -38,7 +38,7 @@ import {
 import { expandTildePath } from "./utils/path.js";
 import { projectTagProjectId } from "./coding/coding-namespace.js";
 import { getOperation, type OperationName } from "./access-boundary.js";
-import { probeOperationAuthorization } from "./access-authorization-probe.js";
+import { authorizationProbeNamespaces, probeOperationAuthorization } from "./access-authorization-probe.js";
 import { resolveQueryNamespaceWritablePreflight } from "./access-namespace-preflight.js";
 import {
   assertOperationAllowed,
@@ -892,11 +892,11 @@ export class EngramAccessHttpServer {
 
     if (req.method === "GET" && pathname === "/engram/v1/authorization") {
       res.setHeader("cache-control", "no-store");
-      this.respondJson(
-        res,
-        200,
-        probeOperationAuthorization(tokenCapabilityStore.getStore(), parsed.searchParams.getAll("op")),
-      );
+      const probe = probeOperationAuthorization(tokenCapabilityStore.getStore(), parsed.searchParams.getAll("op"));
+      const namespaceParam = parsed.searchParams.get("namespace") ?? undefined;
+      for (const namespace of authorizationProbeNamespaces(probe.operations, namespaceParam))
+        this.resolveNamespace(req, namespace);
+      this.respondJson(res, 200, probe);
       return;
     }
 

package/src/access-mcp-output-schemas.ts

@@ -31,6 +31,7 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
     query: T_STRING,
     namespace: T_STRING,
     context: T_STRING,
+    contextComposition: objectSchema({ context: T_STRING, footer: T_STRING }),
     count: T_NUMBER,
     memoryIds: T_ARRAY,
     results: T_ARRAY,

package/src/access-recall-response.ts

@@ -16,6 +16,11 @@ import { decideDisclosureEscalation } from "./recall-disclosure-escalation.js";
 import { type TagMatchMode, applyTagFilter, normalizeTags, parseTagMatch } from "./recall-tag-filter.js";
 import type { RecallDisclosure, RecallPlanMode } from "./types.js";
 import { displaySafeBudgetsApplied, displaySafeRecallSnapshot } from "./orchestration/recall-result-formatter.js";
+import {
+  boundRecallContextComposition,
+  composeRecallContext,
+  type RecallContextComposition,
+} from "./recall-context-composition.js";
 
 /**
  * Build the recall response from the completed pipeline (issue #1906 review
@@ -29,6 +34,7 @@ export async function assembleRecallResponse(
   params: {
   request: EngramAccessRecallRequest;
   context: string;
+  contextComposition?: RecallContextComposition;
   query: string;
   mode: RecallPlanMode | undefined;
   namespace: string;
@@ -47,6 +53,7 @@ export async function assembleRecallResponse(
   const {
     request,
     context,
+    contextComposition,
     query,
     mode,
     namespace,
@@ -191,7 +198,8 @@ export async function assembleRecallResponse(
       err instanceof Error ? err.message : String(err),
     );
   }
-  let effectiveContext = context;
+  let effectiveComposition: RecallContextComposition = contextComposition ?? { context };
+  let effectiveContext = composeRecallContext(effectiveComposition);
   if (filterTags && filterTags.length > 0) {
     const beforeIds = results.map((r) => r.id);
     const { results: admitted } = applyTagFilter(results, {
@@ -213,20 +221,16 @@ export async function assembleRecallResponse(
     const admittedIds = new Set(results.map((r) => r.id));
     const droppedAny = beforeIds.some((id) => !admittedIds.has(id));
     if (droppedAny) {
-      effectiveContext = results
-        .map((r) => {
-          const content =
-            typeof (r as { content?: unknown }).content === "string"
-              ? ((r as { content?: string }).content ?? "")
-              : "";
-          const preview =
-            typeof (r as { preview?: unknown }).preview === "string"
-              ? ((r as { preview?: string }).preview ?? "")
-              : "";
-          return content || preview;
-        })
+      const filteredContext = results
+        .map((result) => result.content || result.preview)
         .filter((s) => s.length > 0)
         .join("\n\n");
+      effectiveComposition = boundRecallContextComposition({
+        context: filteredContext,
+        footer: effectiveComposition.footer,
+        maxChars: deps.orchestrator.config.recallBudgetChars,
+      });
+      effectiveContext = composeRecallContext(effectiveComposition);
     }
   }
   const filteredMemoryIds = filterTags && filterTags.length > 0
@@ -289,6 +293,7 @@ export async function assembleRecallResponse(
       sessionKey: request.sessionKey,
       namespace: effectiveNamespace,
       context: effectiveContext,
+      contextComposition: effectiveComposition,
       count: filterTags && filterTags.length > 0
         ? results.length
         : (snapshot?.memoryIds.length ?? results.length),

package/src/access-recall-surface.ts

@@ -27,6 +27,7 @@ import type { Orchestrator, RecallInvocationOptions } from "./orchestrator.js";
 import { decideDisclosureEscalation } from "./recall-disclosure-escalation.js";
 import { assembleRecallResponse } from "./access-recall-response.js";
 import type { LastRecallSnapshot } from "./recall-state.js";
+import type { RecallContextComposition } from "./recall-context-composition.js";
 import { type TagMatchMode, applyTagFilter, normalizeTags, parseTagMatch } from "./recall-tag-filter.js";
 import { type RecallXraySnapshot, estimateRecallTokens } from "./recall-xray.js";
 import { SecureStoreLockedError } from "./secure-store/index.js";
@@ -852,10 +853,14 @@ export class AccessRecallSurface {
       }
       asOf = request.asOf;
     }
+    let contextComposition: RecallContextComposition | undefined;
     const recallOptions: RecallInvocationOptions = {
       namespace: namespaceOverride,
       topK,
       mode,
+      onContextComposition: (composition) => {
+        contextComposition = composition;
+      },
       ...(authenticatedPrincipal ? { principalOverride: authenticatedPrincipal } : {}),
       ...(asOf !== undefined ? { asOf } : {}),
       ...(request.includeLowConfidence === true ? { includeLowConfidence: true } : {}),
@@ -892,10 +897,15 @@ export class AccessRecallSurface {
     // construction — so ANY failure after the reserve releases the exact
     // budget entry (by token, review #4) instead of leaking it.
     try {
-      const context = await this.deps.orchestrator.recall(query, request.sessionKey, recallOptions);
+      const context = await this.deps.orchestrator.recall(
+        query,
+        request.sessionKey,
+        recallOptions,
+      );
       const assembled = await assembleRecallResponse(this.deps, {
         request,
         context,
+        contextComposition,
         query,
         mode,
         namespace,

package/src/access-service.ts

@@ -170,6 +170,7 @@ import {
   type ScopeInspection,
 } from "./admin/admin-surfaces.js";
 import type { LastRecallSnapshot } from "./recall-state.js";
+import type { RecallContextComposition } from "./recall-context-composition.js";
 import type {
   GraphRecallSnapshot,
   IntentDebugSnapshot,
@@ -453,6 +454,8 @@ export interface EngramAccessRecallResponse {
   sessionKey?: string;
   namespace: string;
   context: string;
+  /** Request-local split used by adapters that must re-render a tighter prompt budget. */
+  contextComposition?: RecallContextComposition;
   count: number;
   memoryIds: string[];
   results: EngramAccessMemorySummary[];

package/src/index.ts

@@ -471,7 +471,7 @@ export {
 } from "./resolve-auth-token.js";
 export type { ResolveSecretRefFn } from "./resolve-auth-token.js";
 export type { SecretRef, AgentAccessAuthToken } from "./types.js";
-
+export * from "./recall-context-composition.js";
 // Recall X-ray CLI helpers (issue #570).  Exported so the standalone
 // `@remnic/cli` binary can wire the `remnic xray` command without
 // reimporting core-internal modules by relative path (CLAUDE.md rule 26).

package/src/orchestration/orchestrator-helpers.ts

@@ -27,6 +27,7 @@ import type { GraphRecallRankedResult, GraphRecallShadowComparison } from "./gra
 import { parseQmdExplain } from "../qmd.js";
 import type { GraphRecallExpandedEntry } from "../recall-state.js";
 import type { RecallXrayServedBy } from "../recall-xray.js";
+import type { RecallContextComposition } from "../recall-context-composition.js";
 import { type BufferTurn, type MemoryActionEvent, type MemoryFile, type MemoryFrontmatter, type MemoryIntent, type PluginConfig, type QmdSearchResult, type RecallPlanMode, confidenceTier } from "../types.js";
 import { categoryDirName } from "../utils/category-dir.js";
 import { parseFlexibleIsoTimestamp } from "../utils/iso-timestamp.js";
@@ -256,6 +257,7 @@ export interface RecallInvocationOptions {
    * absent, so existing timing consumers are unaffected.
    */
   queueWaitMs?: number;
+  onContextComposition?: (composition: RecallContextComposition) => void | PromiseLike<void>;
 }
 
 export type QueryAwarePrefilter = {

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$/, "") };
+}