@remnic/core 9.69.10 → 9.69.12

package/src/access-service.ts

@@ -33,6 +33,7 @@ import { readAggregateExtractionWatermark } from "./orchestration/extraction-wat
 import { ReplicaDivergenceMonitor } from "./replica-divergence.js";
 import type { ResolveSecretRefFn } from "./resolve-auth-token.js";
 import { buildAccessWriteRequestFingerprint, buildObserveRequestFingerprint } from "./write-envelope.js";
+import { UNATTRIBUTED_ACCESS_WRITE_ORIGIN } from "./shared-context/envelope-io.js";
 export type { EngramAccessHealthResponse, EngramAccessQmdCollectionState, EngramAccessQmdHealthResponse };
 import { AccessAuditAdapter, type AccessAuditConfig, type AccessAuditResult } from "./access-audit.js";
 import {
@@ -168,6 +169,15 @@ import {
   redactSensitive,
 } from "./admin/admin-surfaces.js";
 import { FileCalendarSource, buildBriefing, parseBriefingFocus, parseBriefingWindow } from "./briefing.js";
+import {
+  type DeepRecallResult,
+  runBudgetedDeepRecall,
+} from "./deep-recall.js";
+import { callDeepRecallPolicyLlm } from "./deep-recall-policy-llm.js";
+import { createDeepRecallSeedSearch } from "./deep-recall-seeds.js";
+import { renderDeepRecallResult } from "./deep-recall-renderer.js";
+import { readProjectedHarmonicGraph } from "./harmonic-retrieval.js";
+import { stripAttributesSuffix } from "./structured-attributes.js";
 import {
   type GraphSnapshotNodeMetadata,
   type GraphSnapshotRequest,
@@ -2684,6 +2694,133 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     return toRecallExplainJson(snapshot);
   }
 
+  /**
+   * Budgeted REFINE/EXPAND/STOP deep recall (issue #2332). Deep surface
+   * only — never called from the recall hot path. Single implementation
+   * for MCP, HTTP, and CLI (rule 22: one renderer, one service method).
+   */
+  async deepRecall(request: {
+    query: string;
+    namespace?: string;
+    sessionKey?: string;
+    authenticatedPrincipal?: string;
+    maxSteps?: number;
+  }): Promise<DeepRecallResult & { rendered: string }> {
+    const cfg = this.orchestrator.config.deepRecall;
+    if (!cfg.enabled) {
+      return {
+        ok: false,
+        error: "disabled",
+        entries: [],
+        trace: [],
+        rendered: "deep recall is disabled; set deepRecall.enabled",
+      };
+    }
+    const query = typeof request.query === "string" ? request.query.trim() : "";
+    if (query.length === 0) {
+      throw new EngramAccessInputError("deepRecall: query is required");
+    }
+    let effective = cfg;
+    const requestedSteps = request.maxSteps;
+    if (requestedSteps !== undefined) {
+      if (typeof requestedSteps !== "number" || !Number.isInteger(requestedSteps) || requestedSteps < 0) {
+        throw new EngramAccessInputError("deepRecall: maxSteps must be a non-negative integer");
+      }
+      // `deepRecall.maxSteps: 0` is a documented disable value (§33): the
+      // policy loop is off, so ANY positive override is a refusal rather than
+      // a ceiling comparison. The zero case resolves first, so the ceiling
+      // threshold below only runs while the loop is enabled.
+      if (cfg.maxSteps <= 0) {
+        if (requestedSteps > 0) {
+          throw new EngramAccessInputError(
+            "deepRecall: the policy loop is disabled (deepRecall.maxSteps=0); maxSteps must be 0",
+          );
+        }
+      } else if (requestedSteps > cfg.maxSteps) {
+        throw new EngramAccessInputError(
+          `deepRecall: maxSteps ${requestedSteps} exceeds the configured ceiling ${cfg.maxSteps}`,
+        );
+      }
+      effective = { ...cfg, maxSteps: requestedSteps };
+    }
+    const principal =
+      request.authenticatedPrincipal?.trim() || resolvePrincipal(request.sessionKey, this.orchestrator.config);
+    // Read path resolves through the SAME namespace layer as memoryGet (§30):
+    // one resolved namespace, one storage instance, for seeds and expansions.
+    const resolvedNamespace = this.resolveReadableNamespace(request.namespace, principal);
+    const storage = await this.orchestrator.getStorage(resolvedNamespace);
+    const config = this.orchestrator.config;
+    // `abstractionNodeStoreDir` names the DEFAULT namespace's graph store and
+    // takes precedence over `storage.dir` inside the store resolver, so only a
+    // default-namespace read may pass it. This is the rule the harmonic WRITE
+    // path already applies (persistConstructedHarmonicRecords: the override
+    // goes to the base namespace only); passing it here made every non-default
+    // namespace load the DEFAULT namespace's nodes and anchors, missing its own
+    // anchor expansions and exposing foreign graph metadata on an id collision.
+    const graphStoreDir =
+      resolvedNamespace === config.defaultNamespace ? config.abstractionNodeStoreDir : undefined;
+    // Seeds route through the namespace search router (never the base
+    // `config.qmdCollection`, which is the DEFAULT namespace's collection):
+    // a non-default caller must search its own suffixed collection or deep
+    // recall silently misses its corpus and returns foreign doc ids. Hit ->
+    // memory-id resolution is per hit through the shared QMD result resolver
+    // (which also decodes the raw collection-qualified path forms the
+    // namespaces-disabled fanout returns), so no invocation pre-scans the
+    // namespace corpus.
+    const result = await runBudgetedDeepRecall(
+      {
+        config: effective,
+        searchSeed: createDeepRecallSeedSearch({
+          namespace: resolvedNamespace,
+          storage,
+          router: this.orchestrator,
+          resolver: this.orchestrator.qmdResultResolver,
+        }),
+        // Nodes and anchors are projected against the namespace's CURRENT
+        // active memories through the SAME helper searchHarmonicRetrieval
+        // uses. A raw read still carries the stored title, summary, and
+        // anchor value of a memory that was later rejected or quarantined,
+        // and the deep-recall state prompt hands those to the policy LLM long
+        // before `loadMemory(...).active` can exclude the memory itself.
+        loadGraph: async () =>
+          readProjectedHarmonicGraph({
+            memoryDir: storage.dir,
+            abstractionNodeStoreDir: graphStoreDir,
+            anchorsEnabled: true,
+          }),
+        loadMemory: async (memoryId) => {
+          const memory = await storage.getMemoryById(memoryId);
+          // Same private-record exclusion memoryGet applies (#2332): a
+          // support-passport private record is reported as absent (null),
+          // never as content — deep recall must not become the read surface
+          // that answers what every other surface denies.
+          if (!memory || isSupportPassportPrivateMemory(memory)) return null;
+          return {
+            memoryId,
+            content: memory.frontmatter.structuredAttributes
+              ? stripAttributesSuffix(memory.content)
+              : memory.content,
+            // Enumerate the active set — never an exclusion list (§41).
+            active: inferMemoryStatus(
+              memory.frontmatter,
+              toMemoryPathRel(storage.dir, memory.path)
+            ) === "active",
+          };
+        },
+        callPolicy: (statePrompt, timeoutMs) =>
+          callDeepRecallPolicyLlm({
+            statePrompt,
+            config,
+            localLlm: this.orchestrator.localLlm ?? null,
+            fallbackLlm: this.orchestrator.fastGatewayLlm ?? null,
+            timeoutMs,
+          }),
+      },
+      query,
+    );
+    return { ...result, rendered: renderDeepRecallResult(result) };
+  }
+
   async recallXray(request: {
     query: string;
     sessionKey?: string;
@@ -4430,15 +4567,35 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
     agentId: string;
     title: string;
     content: string;
+    /** Authenticated principal resolved by the surface, never client-supplied. */
+    principal?: string;
   }): Promise<unknown> {
     if (!this.orchestrator.sharedContext) {
       return { enabled: false, reason: "Shared context is disabled. Enable `sharedContextEnabled: true`." };
     }
-    const fp = await this.orchestrator.sharedContext.writeAgentOutput({
-      agentId: request.agentId,
-      title: request.title,
-      content: request.content,
-    });
+    let fp: string;
+    try {
+      fp = await this.orchestrator.sharedContext.writeAgentOutput({
+        agentId: request.agentId,
+        title: request.title,
+        content: request.content,
+        // The origin is server-owned in BOTH cases (issue #1957 review
+        // round 4): the authenticated principal when one resolved, and a
+        // reserved unattributed token otherwise — a principal-less
+        // authenticated request must never stamp the client's `agentId`
+        // as audit metadata. The client label survives only as the
+        // producer, which feeds grouping and display, never authority.
+        ...(request.principal
+          ? { authenticatedIdentity: request.principal }
+          : { unattributedOrigin: UNATTRIBUTED_ACCESS_WRITE_ORIGIN }),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.startsWith("shared-context write origin mismatch")) {
+        throw new EngramAccessInputError(message);
+      }
+      throw error;
+    }
     return { written: true, path: fp };
   }
 

package/src/access-surface-catalog.ts

@@ -71,6 +71,7 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "meetings_list", operation: "meetings_list" },
   { tool: "meetings_get", operation: "meetings_get" },
   { tool: "meetings_build", operation: "meetings_build" },
+  { tool: "deep_recall", operation: "deep_recall" },
   { tool: "standup", operation: "standup" },
   { tool: "action_confidence", operation: "action_confidence" },
   { tool: "chatgpt_memory_inspector", operation: "chatgpt_memory_inspector" },
@@ -235,6 +236,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "GET", pathname: "/engram/v1/meetings", operation: "meetings_list" },
   { method: "POST", pathname: "/engram/v1/meetings/build", operation: "meetings_build" },
   { method: "GET", pathname: "/engram/v1/meetings/:id", operation: "meetings_get" },
+  { method: "POST", pathname: "/engram/v1/recall/deep", operation: "deep_recall" },
   { method: "GET", pathname: "/engram/v1/standup", operation: "standup" },
   { method: "POST", pathname: "/engram/v1/observe", operation: "observe" },
   { method: "POST", pathname: "/engram/v1/lcm/search", operation: "lcm_search" },

package/src/cli/deep-recall-commands.ts

@@ -0,0 +1,60 @@
+/**
+ * Deep-recall command group (issue #2332) — extracted from cli.ts so the
+ * surface file stays at its structural ceiling (same seam as
+ * meetings-commands.ts). `engram deep-recall <query>` runs the budgeted
+ * REFINE/EXPAND/STOP loop through EngramAccessService — the same single
+ * implementation MCP and HTTP call.
+ */
+
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import { EngramAccessService } from "../access-service.js";
+
+function parseMaxSteps(raw: unknown): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const value = typeof raw === "string" ? Number(raw) : raw;
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new Error(`--max-steps must be a non-negative integer; got ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+
+export function registerDeepRecallCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
+  cmd
+    .command("deep-recall <query>")
+    .description("Budgeted multi-hop retrieval over the anchor graph (slow, thorough; issue #2332)")
+    .option("--max-steps <n>", "Policy-step ceiling (cannot exceed the configured deepRecall.maxSteps)")
+    .option("--namespace <ns>", "Namespace to scope the retrieval to")
+    .option("--json", "JSON output (full entries + trace)")
+    .action(async (...args: unknown[]) => {
+      const query = String(args[0] ?? "");
+      const options = (args[args.length - 1] ?? {}) as Record<string, unknown>;
+      let maxSteps: number | undefined;
+      try {
+        maxSteps = parseMaxSteps(options.maxSteps);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+        return;
+      }
+      const service = new EngramAccessService(orchestrator);
+      try {
+        const result = await service.deepRecall({
+          query,
+          ...(maxSteps !== undefined ? { maxSteps } : {}),
+          ...(typeof options.namespace === "string" && options.namespace.length > 0
+            ? { namespace: options.namespace }
+            : {}),
+        });
+        if (options.json === true) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log(result.rendered);
+        }
+        if (!result.ok) process.exitCode = 1;
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+      }
+    });
+}

package/src/cli.ts

@@ -14,7 +14,7 @@ import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
-import { registerMeetingsCommands } from "./cli/meetings-commands.js";
+import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js";
 import { registerExportOkfCommand, registerOkfCommands } from "./cli/okf-commands.js";
 import { registerSkillsCommands } from "./cli/skills-commands.js";
 import { registerResearchStatusCommands } from "./cli/research-status-commands.js";
@@ -6230,7 +6230,7 @@ export function registerCli(
 
       registerResearchStatusCommands(cmd, orchestrator);
 
-      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator);
+      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator); registerDeepRecallCommands(cmd, orchestrator);
 
       cmd
         .command("trust-zone-promote")

package/src/config.test.ts

@@ -2656,3 +2656,22 @@ test("parseConfig rejects array contradictionLocalization values", () => {
     /contradictionLocalization must be an object/,
   );
 });
+
+test("parseConfig coerces string-typed sharedContextAllowBindingAuthority from the CLI", () => {
+  // `--config sharedContextAllowBindingAuthority=true` arrives as a string, so a
+  // strict `=== true` silently left the feature off for anyone who enabled it.
+  for (const enabled of ["true", "1", "yes", "on", true]) {
+    assert.equal(
+      parseConfig({ sharedContextAllowBindingAuthority: enabled }).sharedContextAllowBindingAuthority,
+      true,
+      `${JSON.stringify(enabled)} must enable binding authority`,
+    );
+  }
+  for (const disabled of ["false", "0", "no", "off", false, undefined, "", "garbage"]) {
+    assert.equal(
+      parseConfig({ sharedContextAllowBindingAuthority: disabled }).sharedContextAllowBindingAuthority,
+      false,
+      `${JSON.stringify(disabled)} must leave binding authority off`,
+    );
+  }
+});

package/src/config.ts

@@ -46,6 +46,7 @@ import { parseProceduralMaintenanceConfig } from "./procedural/maintenance-confi
 import { parseActiveContextFields } from "./active-context-config.js";
 import { parseSkillProjectionConfig } from "./procedural/skill-projection.js";
 import { parseDriftDetectionConfig } from "./preferences/drift-config.js";
+import { parseDeepRecallConfig } from "./deep-recall-config.js";
 import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { parseWritePathDedupConfig } from "./dedup/novelty-gate.js";
@@ -1793,6 +1794,8 @@ export function parseConfig(
     contradictionScan: parseContradictionScanConfig(cfg.contradictionScan),
     // Preference drift detection (issue #2371)
     driftDetection: parseDriftDetectionConfig(cfg.driftDetection),
+    // Budgeted deep-recall surface (issue #2332)
+    deepRecall: parseDeepRecallConfig(cfg.deepRecall),
     dependencyPropagation: parseDependencyPropagationConfig(cfg),
     // Temporal Supersession (issue #375)
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false, // On by default
@@ -3026,6 +3029,10 @@ export function parseConfig(
 
     // v4.0 shared-context (default off)
     sharedContextEnabled: cfg.sharedContextEnabled === true,
+    // CLI values arrive as strings (`--config sharedContextAllowBindingAuthority=true`),
+    // so a strict `=== true` silently keeps the feature off. Default stays false.
+    sharedContextAllowBindingAuthority:
+      coerceBool(cfg.sharedContextAllowBindingAuthority, "sharedContextAllowBindingAuthority") ?? false,
     sharedContextDir:
       typeof cfg.sharedContextDir === "string" && cfg.sharedContextDir.length > 0 ? cfg.sharedContextDir : undefined,
     sharedContextMaxInjectChars:

package/src/deep-recall-config.ts

@@ -0,0 +1,83 @@
+/**
+ * Deep-recall config (issue #2332) — the `deepRecall` block.
+ *
+ * Parsed the same way `driftDetection` and `contradictionScan` are:
+ * shape-validated, string-coercion safe (§24), and honoring documented
+ * zero/no-op values (§33) rather than clamping them to something non-zero.
+ * `maxSteps: 0` disables the policy loop (seed-only retrieval);
+ * `maxResults: 0` returns an empty entry list; `maxExpandPerStep: 0`
+ * lets the policy pick EXPAND but select nothing. Millisecond fields
+ * of `0` mean "no timeout on that axis".
+ */
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+
+export interface DeepRecallConfig {
+  /** Master switch for the deep-recall surface. Default false. */
+  enabled: boolean;
+  /** Policy iterations; 0 disables the loop (seed-only). Default 4. */
+  maxSteps: number;
+  /** Per-step cap on frontier nodes pulled into the working set. Default 3. */
+  maxExpandPerStep: number;
+  /** Final working-set cap returned to the caller. Default 12. */
+  maxResults: number;
+  /** Per policy-call timeout in ms; 0 = none. Default 10000. */
+  stepTimeoutMs: number;
+  /** Whole-invocation wall-clock timeout in ms; 0 = none. Default 45000. */
+  totalTimeoutMs: number;
+}
+
+export interface DeepRecallSettings {
+  deepRecall: DeepRecallConfig;
+}
+
+export const DEEP_RECALL_CONFIG_DEFAULTS: DeepRecallConfig = {
+  enabled: false,
+  maxSteps: 4,
+  maxExpandPerStep: 3,
+  maxResults: 12,
+  stepTimeoutMs: 10000,
+  totalTimeoutMs: 45000,
+};
+
+function parseFlag(src: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceBool(value);
+  if (coerced === undefined) {
+    throw new Error(`deepRecall.${key} must be a boolean (or "true"/"false"/"1"/"0"); got ${JSON.stringify(value)}`);
+  }
+  return coerced;
+}
+
+function parseCount(src: Record<string, unknown>, key: string, fallback: number): number {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced)) {
+    throw new Error(`deepRecall.${key} must be a finite number; got ${JSON.stringify(value)}`);
+  }
+  if (!Number.isInteger(coerced)) {
+    throw new Error(`deepRecall.${key} must be an integer; got ${JSON.stringify(value)}`);
+  }
+  if (coerced < 0) {
+    throw new Error(`deepRecall.${key} must not be negative; got ${JSON.stringify(value)}`);
+  }
+  return coerced;
+}
+
+export function parseDeepRecallConfig(raw: unknown): DeepRecallConfig {
+  if (raw === undefined || raw === null) return { ...DEEP_RECALL_CONFIG_DEFAULTS };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`deepRecall must be an object; got ${JSON.stringify(raw)}`);
+  }
+  const src = raw as Record<string, unknown>;
+  return {
+    enabled: parseFlag(src, "enabled", DEEP_RECALL_CONFIG_DEFAULTS.enabled),
+    maxSteps: parseCount(src, "maxSteps", DEEP_RECALL_CONFIG_DEFAULTS.maxSteps),
+    maxExpandPerStep: parseCount(src, "maxExpandPerStep", DEEP_RECALL_CONFIG_DEFAULTS.maxExpandPerStep),
+    maxResults: parseCount(src, "maxResults", DEEP_RECALL_CONFIG_DEFAULTS.maxResults),
+    stepTimeoutMs: parseCount(src, "stepTimeoutMs", DEEP_RECALL_CONFIG_DEFAULTS.stepTimeoutMs),
+    totalTimeoutMs: parseCount(src, "totalTimeoutMs", DEEP_RECALL_CONFIG_DEFAULTS.totalTimeoutMs),
+  };
+}

package/src/deep-recall-http-glue.ts

@@ -0,0 +1,75 @@
+/**
+ * Deep-recall HTTP glue (issue #2332) — route body lives here so
+ * access-http.ts stays at its structural ceiling (same seam as
+ * meetings/http-glue.ts and location/http-glue.ts).
+ *
+ * Input errors map to 400; everything else rethrows so backend faults keep
+ * flowing to the global 500 handler. `deepRecall.enabled` gating lives in
+ * EngramAccessService — this module only translates transport shape.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { deepRecallRequestSchema } from "./access-schema.js";
+import { EngramAccessInputError } from "./access-errors.js";
+import type { EngramAccessService } from "./access-service.js";
+
+type RespondJson = (res: ServerResponse, status: number, payload: unknown) => void;
+type ReadJsonBody = (req: IncomingMessage) => Promise<unknown>;
+
+function coerceMaxSteps(raw: unknown): number | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const value = typeof raw === "string" ? Number(raw) : raw;
+  if (typeof value !== "number" || !Number.isFinite(value) || !Number.isInteger(value) || value < 0) {
+    throw new EngramAccessInputError("maxSteps must be a non-negative integer");
+  }
+  return value;
+}
+
+export async function respondDeepRecall(
+  req: IncomingMessage,
+  res: ServerResponse,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  /**
+   * Resolve the caller scope for a body-supplied namespace/sessionKey. The
+   * body `namespace` is user-controlled, so it MUST flow through the SAME
+   * effective-namespace allow-list gate as the query-string value (issue
+   * #1850 finding 2 / #2332 review): a scoped bearer that passes an allowed
+   * `?namespace=` while setting a different `namespace` in the body would
+   * otherwise read another tenant. access-http supplies the gate and applies
+   * the query-string fallback, so this module never selects a namespace of
+   * its own. Throws 403 when the effective namespace is not permitted.
+   *
+   * `authenticatedPrincipal` is the identity the transport authenticated, and
+   * it MUST reach the service: authorization and the audit trail derive from
+   * the presenting principal, never from the client-supplied `sessionKey`.
+   * Dropping it let a crafted key matching another principal rule read that
+   * principal's namespaces, and made a legitimate namespace-enabled request
+   * with no session key fail as unauthenticated.
+   */
+  scopeFor: (
+    bodyNamespace?: string,
+    bodySessionKey?: string,
+  ) => { namespace?: string; sessionKey?: string; authenticatedPrincipal?: string },
+): Promise<void> {
+  const parsed = deepRecallRequestSchema.safeParse(await readJsonBody(req));
+  if (!parsed.success) {
+    respondJson(
+      res,
+      400,
+      { error: "invalid_request", detail: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ") },
+    );
+    return;
+  }
+  const maxSteps = coerceMaxSteps(parsed.data.maxSteps);
+  const scope = scopeFor(parsed.data.namespace, parsed.data.sessionKey);
+  const result = await service.deepRecall({
+    query: parsed.data.query,
+    ...(maxSteps !== undefined ? { maxSteps } : {}),
+    namespace: scope.namespace,
+    sessionKey: scope.sessionKey,
+    authenticatedPrincipal: scope.authenticatedPrincipal,
+  });
+  respondJson(res, 200, result);
+}

package/src/deep-recall-mcp-tools.ts

@@ -0,0 +1,33 @@
+/**
+ * Deep-recall MCP tool definition (issue #2332) — extracted from
+ * access-mcp.ts so the surface file stays at its structural ceiling.
+ * Spread back into `this.tools` (`...DEEP_RECALL_MCP_TOOLS`); the
+ * migrated-operation mapping spreads into MCP_MIGRATED_OPERATIONS.
+ * The `remnic.` canonical alias is minted by withToolAliases at
+ * tools/list time (same as meetings).
+ */
+
+import type { McpTool } from "./access-mcp.js";
+
+export const DEEP_RECALL_MCP_TOOLS: McpTool[] = [
+  {
+    name: "engram.deep_recall",
+    description:
+      "Budgeted REFINE/EXPAND/STOP multi-hop retrieval over the cue-anchor graph (issue #2332). Slow and thorough (seconds; several LLM calls) — opt in when a question warrants deep search, not for routine recall. Returns ranked entries plus a per-step trace. Typed error when deepRecall.enabled is off.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The question to retrieve for. Required." },
+        maxSteps: {
+          type: "integer",
+          minimum: 0,
+          description: "Optional policy-step ceiling; cannot exceed the configured deepRecall.maxSteps.",
+        },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+        sessionKey: { type: "string", description: "Session key for principal/namespace resolution." },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+];

package/src/deep-recall-policy-llm.ts

@@ -0,0 +1,65 @@
+/**
+ * Policy-call LLM routing for deep recall (issue #2332).
+ *
+ * Mirrors `extraction-judge.ts` `callJudgeLlm` exactly: local client first
+ * (json_object response format) unless modelSource is "gateway", then the
+ * fallback client with the shared background-task chain options. Never a
+ * raw OpenAI client. Returns null when both legs fail — the loop treats
+ * that as a stop, never a crash.
+ */
+
+import { gatewayTaskChainOptions, type FallbackLlmClient } from "./fallback-llm.js";
+import type { LocalLlmClient } from "./local-llm.js";
+import type { PluginConfig } from "./types.js";
+
+export const DEEP_RECALL_POLICY_SYSTEM_PROMPT =
+  "You are the retrieval policy for a long-term memory system. Given the question, the current working set of retrieved memories, and the frontier of anchor-linked candidates, choose exactly one action: REFINE (rewrite the query), EXPAND (follow named frontier nodes), or STOP. Respond with JSON only.";
+
+export async function callDeepRecallPolicyLlm(input: {
+  statePrompt: string;
+  config: PluginConfig;
+  localLlm: LocalLlmClient | null;
+  fallbackLlm: FallbackLlmClient | null;
+  timeoutMs: number;
+}): Promise<string | null> {
+  const messages: Array<{ role: "system" | "user"; content: string }> = [
+    { role: "system", content: DEEP_RECALL_POLICY_SYSTEM_PROMPT },
+    { role: "user", content: input.statePrompt },
+  ];
+  const timeout = input.timeoutMs > 0 ? input.timeoutMs : undefined;
+  const skipLocal = input.config.modelSource === "gateway";
+  const gatewayChain = gatewayTaskChainOptions(input.config);
+
+  if (input.localLlm && !skipLocal) {
+    try {
+      const result = await input.localLlm.chatCompletion(messages, {
+        temperature: 0.1,
+        maxTokens: 1024,
+        ...(timeout ? { timeoutMs: timeout } : {}),
+        responseFormat: { type: "json_object" },
+        operation: "deep-recall-policy",
+      });
+      if (result?.content) return result.content;
+    } catch {
+      // fall through to the gateway leg
+    }
+  }
+
+  if (input.fallbackLlm) {
+    try {
+      const result = await input.fallbackLlm.chatCompletion(
+        messages as Array<{ role: "system" | "user" | "assistant"; content: string }>,
+        {
+          temperature: 0.1,
+          maxTokens: 1024,
+          ...(timeout ? { timeoutMs: timeout } : {}),
+          ...gatewayChain,
+        },
+      );
+      if (result?.content) return result.content;
+    } catch {
+      // both legs failed — caller treats null as a stop
+    }
+  }
+  return null;
+}

package/src/deep-recall-renderer.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared markdown renderer for deep recall (issue #2332).
+ *
+ * Rule 22 (AGENTS.md): never fork formatting — CLI text output, MCP text
+ * output, and any later surface all render through this one module.
+ * Deterministic: entries in result order, trace in step order.
+ */
+
+import type { DeepRecallResult } from "./deep-recall.js";
+
+export function renderDeepRecallResult(result: DeepRecallResult): string {
+  if (!result.ok) {
+    return [`# Deep recall`, ``, `- error: ${result.error ?? "unknown"}`, ``].join("\n");
+  }
+  const lines: string[] = ["# Deep recall", ""];
+  if (result.entries.length === 0) {
+    lines.push("No memories retrieved.", "");
+  } else {
+    lines.push("## Memories", "");
+    for (const [index, entry] of result.entries.entries()) {
+      const via = entry.viaAnchor ? ` via anchor "${entry.viaAnchor}"` : "";
+      lines.push(
+        `${index + 1}. **${entry.memoryId}** (score ${entry.score.toFixed(3)}, origin ${entry.origin}${via})`,
+      );
+      lines.push(`   ${entry.content.replace(/\s+/g, " ").trim().slice(0, 400)}`);
+    }
+    lines.push("");
+  }
+  lines.push("## Trace", "");
+  if (result.trace.length === 0) {
+    lines.push("(empty)");
+  } else {
+    for (const step of result.trace) {
+      lines.push(
+        `- step ${step.step}: ${step.action} — ${step.detail} (workingSet=${step.workingSetSize}, frontier=${step.frontierSize}, ${step.durationMs}ms)`,
+      );
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}