@remnic/core 9.69.10 → 9.69.11

package/dist/write-envelope.d.ts

@@ -1,10 +1,11 @@
-import { y as MemoryCategory, N as MemorySubject } from './types-eM7QIcX2.js';
+import { y as MemoryCategory, N as MemorySubject } from './types-CLRTESSD.js';
 import './message-parts/index.js';
 import './bounded-jsonl-state.js';
 import './operator-doctor-types.js';
 import './external-wiki-config.js';
 import './contradiction-config.js';
 import './graph-path-scoring-config.js';
+import './deep-recall-config.js';
 import './causal-trajectory.js';
 import './objective-state.js';
 import './active-context-config.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.69.10",
+  "version": "9.69.11",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -3227,7 +3227,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.69.10"
+    "@remnic/coding-graph": "^9.69.11"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/access-boundary.ts

@@ -83,6 +83,7 @@ export const OPERATION_NAMES = [
   "meetings_list",
   "meetings_get",
   "meetings_build",
+  "deep_recall",
   "standup",
   "action_confidence",
   "chatgpt_memory_inspector",

package/src/access-http.ts

@@ -25,7 +25,7 @@ import {
 } from "./access-http-offline-stream.js";
 import { nonEmptyQueryParam, optionalNamespaceKindQueryParam, optionalQueryString, positiveIntQueryParam } from "./access-http-query.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
-import { respondWearablesErrorGlue } from "./wearables/http-glue.js"; import { respondMeetingsList, respondMeetingsGet, respondMeetingsBuild } from "./meetings/http-glue.js"; import { respondLocationStatus, respondLocationCheck, respondLocationSync, respondLocationBackfill, respondLocationDay } from "./location/http-glue.js"; import { respondStandup } from "./standup/http-glue.js";
+import { respondWearablesErrorGlue } from "./wearables/http-glue.js"; import { respondMeetingsList, respondMeetingsGet, respondMeetingsBuild } from "./meetings/http-glue.js"; import { respondLocationStatus, respondLocationCheck, respondLocationSync, respondLocationBackfill, respondLocationDay } from "./location/http-glue.js"; import { respondStandup } from "./standup/http-glue.js"; import { respondDeepRecall } from "./deep-recall-http-glue.js";
 import { EngramMcpServer, MCP_SUPPORTED_PROTOCOL_VERSIONS } from "./access-mcp.js";
 import { handleMcpGetSse } from "./access-mcp-sse.js";
 import { validateRequest, type SchemaName, type SchemaTypeFor } from "./access-schema.js";
@@ -1752,10 +1752,10 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
       this.enforceTokenOp("meetings_build"); await respondMeetingsBuild(req, res, this.respondJson.bind(this), this.readJsonBody.bind(this), this.service, { enforceQuota: () => this.ensureWriteRateLimitAvailable(req), recordHit: () => this.recordWriteRateLimitHit(req) }, (ns, sk) => this.wearablesScope(req, ns, sk)); return; }
     const meetingGetEngram = /^\/engram\/v1\/meetings\/([^/]+)$/.exec(pathname);
     if (req.method === "GET" && meetingGetEngram) { this.enforceTokenOp("meetings_get"); await respondMeetingsGet(res, this.respondJson.bind(this), this.service, meetingGetEngram[1] ?? "", this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)); return; }
-    const meetingGetRemnic = /^\/remnic\/v1\/meetings\/([^/]+)$/.exec(pathname);
-    if (req.method === "GET" && meetingGetRemnic) { this.enforceTokenOp("meetings_get"); await respondMeetingsGet(res, this.respondJson.bind(this), this.service, meetingGetRemnic[1] ?? "", this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)); return; }
-    // Location sync surfaces (issue #2047): thin branches; bodies + boundary
-    // dispatch live in location/http-glue.ts.
+    const meetingGetRemnic = /^\/remnic\/v1\/meetings\/([^/]+)$/.exec(pathname); if (req.method === "GET" && meetingGetRemnic) { this.enforceTokenOp("meetings_get"); await respondMeetingsGet(res, this.respondJson.bind(this), this.service, meetingGetRemnic[1] ?? "", this.wearablesScope(req, parsed.searchParams.get("namespace") ?? undefined, parsed.searchParams.get("sessionKey") ?? undefined)); return; }
+    if (req.method === "POST" && (pathname === "/engram/v1/recall/deep" || pathname === "/remnic/v1/recall/deep")) {
+      this.enforceTokenOp("deep_recall"); await respondDeepRecall(req, res, this.respondJson.bind(this), this.readJsonBody.bind(this), this.service, (ns, sk) => this.wearablesScope(req, ns ?? parsed.searchParams.get("namespace") ?? undefined, sk ?? parsed.searchParams.get("sessionKey") ?? undefined)); return; }
+    // Location sync surfaces (issue #2047): thin branches; bodies + boundary dispatch live in location/http-glue.ts.
     if (req.method === "GET" && (pathname === "/engram/v1/location/status" || pathname === "/remnic/v1/location/status")) {
       this.enforceTokenOp("location_status"); await respondLocationStatus(res, this.respondJson.bind(this), this.service); return; }
     if (req.method === "GET" && (pathname === "/engram/v1/location/check" || pathname === "/remnic/v1/location/check")) {

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

@@ -82,6 +82,7 @@ const TOOL_OUTPUT_SCHEMAS: Readonly<Record<string, Record<string, unknown>>> = {
     skipped: T_NUMBER,
     removed: T_ARRAY,
   }),
+  deep_recall: objectSchema({ ok: T_BOOLEAN, error: T_NULLABLE_STRING, entries: T_ARRAY, trace: T_ARRAY, rendered: T_STRING }, ["entries", "trace"]),
   standup: objectSchema({ date: T_STRING, yesterday: T_STRING, today: T_STRING, highlights: T_ARRAY, priorities: T_ARRAY, blockers: T_ARRAY, activityGrid: T_STRING, markdown: T_STRING }),
   action_confidence: objectSchema({
     schemaVersion: T_NUMBER,

package/src/access-mcp.ts

@@ -51,7 +51,7 @@ import {
   withToolAliases,
 } from "./access-mcp-tool-names.js";
 import { MCP_READ_ONLY_TOOL_SUFFIXES } from "./mcp-read-only-tools.js";
-import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js";
+import { MEETINGS_MCP_TOOLS } from "./meetings/mcp-tools.js"; import { DEEP_RECALL_MCP_TOOLS } from "./deep-recall-mcp-tools.js";
 import { WEARABLES_MCP_TOOLS } from "./wearables/mcp-tools.js";
 import { WHO_KNOWS_MCP_TOOLS } from "./who-knows.js"; import { LOCATION_MCP_TOOLS } from "./location/mcp-tools.js"; import { STANDUP_MCP_TOOLS } from "./standup/mcp-tools.js";
 import { PROMOTION_CANDIDATES_MCP_TOOLS } from "./memory-subject.js";
@@ -246,7 +246,7 @@ export const MCP_MIGRATED_OPERATIONS: Readonly<Record<string, OperationName>> =
   "engram.console_state": "console_state",
   "engram.dreams_status": "dreams_status",
   "engram.dreams_run": "dreams_run",
-  ...SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS, ...MCP_ADMIN_OPS_MIGRATED_OPERATIONS,
+  ...SUPPORT_PASSPORT_MCP_MIGRATED_OPERATIONS, ...MCP_ADMIN_OPS_MIGRATED_OPERATIONS, "engram.deep_recall": "deep_recall",
   "engram.memory_chat": "chat_message",
 };
 
@@ -687,7 +687,7 @@ export class EngramMcpServer {
           additionalProperties: false,
         },
       },
-      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS, ...PROMOTION_CANDIDATES_MCP_TOOLS, ...LOCATION_MCP_TOOLS, ...STANDUP_MCP_TOOLS,
+      ...WEARABLES_MCP_TOOLS, ...MEETINGS_MCP_TOOLS, ...WHO_KNOWS_MCP_TOOLS, ...PROMOTION_CANDIDATES_MCP_TOOLS, ...LOCATION_MCP_TOOLS, ...STANDUP_MCP_TOOLS, ...DEEP_RECALL_MCP_TOOLS,
       ...(service.supportPassportEnabled ? SUPPORT_PASSPORT_MCP_TOOLS : []),
       {
         name: "engram.action_confidence",

package/src/access-operations-batch.ts

@@ -187,6 +187,8 @@ defineOperation({ name: "transcript_memories", description: "Transcript memories
 defineOperation({ name: "meetings_list", description: "List stored meeting records (all days, or one day).", schema: strictSchema({ date: S.str, namespace: S.str, sessionKey: S.str }), handler: async (input, ctx) => { const d = optStr(input.date); return { result: await ctx.service.meetingsList(d && d.length > 0 ? d : undefined, { authenticatedPrincipal: ctx.authenticatedPrincipal, namespace: optStr(input.namespace), sessionKey: optStr(input.sessionKey) }) }; } });
 defineOperation({ name: "meetings_get", description: "Get a stored meeting record by id.", schema: strictSchema({ id: S.str, namespace: S.str, sessionKey: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.meetingsGet(reqStr(input.id, "id"), { authenticatedPrincipal: ctx.authenticatedPrincipal, namespace: optStr(input.namespace), sessionKey: optStr(input.sessionKey) }) }) });
 defineOperation({ name: "meetings_build", description: "Detect + fuse + store a day's meetings.", schema: strictSchema({ date: S.str, namespace: S.str, sessionKey: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.meetingsBuild(reqStr(input.date, "date"), { authenticatedPrincipal: ctx.authenticatedPrincipal, namespace: optStr(input.namespace), sessionKey: optStr(input.sessionKey) }) }) });
+// === DEEP RECALL (issue #2332) — budgeted REFINE/EXPAND/STOP retrieval ===
+defineOperation({ name: "deep_recall", description: "Budgeted multi-hop deep recall over the anchor graph.", schema: strictSchema({ query: S.str, maxSteps: S.flexNum, namespace: S.str, sessionKey: S.str }), handler: async (input, ctx) => { const q = defStr(input.query, ""); if (q.trim().length === 0) throw new EngramAccessInputError("deep_recall: query is required"); return { result: await ctx.service.deepRecall({ query: q, maxSteps: typeof input.maxSteps === "number" ? input.maxSteps : typeof input.maxSteps === "string" && Number.isFinite(Number(input.maxSteps)) ? Number(input.maxSteps) : undefined, authenticatedPrincipal: ctx.authenticatedPrincipal, namespace: optStr(input.namespace), sessionKey: optStr(input.sessionKey) }) }; } });
 
 // === ACTION CONFIDENCE + INSPECTOR + CAPSULE ===
 defineOperation({ name: "action_confidence", description: "Action confidence.", schema: strictSchema({ intendedAction: S.str, confidence: S.num, risk: S.str, contextReadiness: S.str, currentContextScopes: S.strArr, userRules: z.array(z.unknown()).optional(), retrievedMemories: z.array(z.unknown()).optional() }), handler: async (input, ctx) => { const req: Record<string, unknown> = {}; if (input.intendedAction !== undefined) req.intendedAction = optStr(input.intendedAction); if (input.confidence !== undefined) req.confidence = optNum(input.confidence); if (input.risk !== undefined) req.risk = optStr(input.risk) as "low" | "medium" | "high" | "irreversible" | "restricted" | undefined; if (input.contextReadiness !== undefined) req.contextReadiness = optStr(input.contextReadiness) as "none" | "partial" | "sufficient" | undefined; if (input.currentContextScopes !== undefined) req.currentContextScopes = optStrArr(input.currentContextScopes); if (input.userRules !== undefined) req.userRules = input.userRules; if (input.retrievedMemories !== undefined) req.retrievedMemories = input.retrievedMemories; return { result: await ctx.service.actionConfidence(req) }; } });
@@ -278,7 +280,7 @@ defineOperation({ name: "memory_identity", description: "Memory identity.", sche
 defineOperation({ name: "work_task", description: "Manage work task.", schema: strictSchema({ action: S.str, id: S.str, title: S.str, description: S.str, status: S.str, priority: S.str, owner: S.str, assignee: S.str, projectId: S.str, tags: S.strArr, dueAt: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.workTask({ action: (optStr(input.action) as "update" | "list" | "get" | "create" | "delete" | "transition") ?? "list", id: optStr(input.id), title: optStr(input.title), description: optStr(input.description), status: optStr(input.status), priority: optStr(input.priority), owner: optStr(input.owner), assignee: optStr(input.assignee), projectId: optStr(input.projectId), tags: optStrArr(input.tags), dueAt: optStr(input.dueAt) }) }) });
 defineOperation({ name: "work_project", description: "Manage work project.", schema: strictSchema({ action: S.str, id: S.str, name: S.str, description: S.str, status: S.str, owner: S.str, tags: S.strArr, taskId: S.str, projectId: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.workProject({ action: (optStr(input.action) as "update" | "list" | "get" | "create" | "delete" | "link_task") ?? "list", id: optStr(input.id), name: optStr(input.name), description: optStr(input.description), status: optStr(input.status), owner: optStr(input.owner), tags: optStrArr(input.tags), taskId: optStr(input.taskId), projectId: optStr(input.projectId) }) }) });
 defineOperation({ name: "work_board", description: "Manage work board.", schema: strictSchema({ action: S.str, projectId: S.str, snapshotJson: S.str, linkToMemory: S.bool }), handler: async (input, ctx) => ({ result: await ctx.service.workBoard({ action: (optStr(input.action) as "export_markdown" | "export_snapshot" | "import_snapshot") ?? "export_markdown", projectId: optStr(input.projectId) ?? "", snapshotJson: optStr(input.snapshotJson) ?? "", linkToMemory: input.linkToMemory === true }) }) });
-defineOperation({ name: "shared_context_write_output", description: "Write shared output.", schema: strictSchema({ agentId: S.str, title: S.str, content: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.sharedContextWriteOutput({ agentId: optStr(input.agentId) ?? "", title: optStr(input.title) ?? "", content: optStr(input.content) ?? "" }) }) });
+defineOperation({ name: "shared_context_write_output", description: "Write shared output.", schema: strictSchema({ agentId: S.str, title: S.str, content: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.sharedContextWriteOutput({ agentId: optStr(input.agentId) ?? "", title: optStr(input.title) ?? "", content: optStr(input.content) ?? "", principal: ctx.authenticatedPrincipal }) }) });
 defineOperation({ name: "shared_feedback_record", description: "Record shared feedback.", schema: strictSchema({ agent: S.str, decision: S.str, reason: S.str, date: S.str, learning: S.str, outcome: S.str, severity: S.str, confidence: S.num, workflow: S.str, tags: S.strArr, evidenceWindowStart: S.str, evidenceWindowEnd: S.str, refs: S.strArr }), handler: async (input, ctx) => { const sv = optStr(input.severity); return { result: await ctx.service.sharedFeedbackRecord({ agent: optStr(input.agent) ?? "", decision: (optStr(input.decision) as "rejected" | "approved" | "approved_with_feedback") ?? "approved", reason: optStr(input.reason) ?? "", date: optStr(input.date), learning: optStr(input.learning), outcome: optStr(input.outcome), severity: sv === "low" || sv === "medium" || sv === "high" ? sv as "low" | "medium" | "high" : undefined, confidence: optNum(input.confidence), workflow: optStr(input.workflow), tags: optStrArr(input.tags), evidenceWindowStart: optStr(input.evidenceWindowStart), evidenceWindowEnd: optStr(input.evidenceWindowEnd), refs: optStrArr(input.refs) }) }; } });
 defineOperation({ name: "shared_priorities_append", description: "Append priorities.", schema: strictSchema({ agentId: S.str, text: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.sharedPrioritiesAppend({ agentId: optStr(input.agentId) ?? "", text: optStr(input.text) ?? "" }) }) });
 defineOperation({ name: "shared_context_cross_signals_run", description: "Run cross signals.", fleetWide: true, schema: strictSchema({ date: S.str }), handler: async (input, ctx) => ({ result: await ctx.service.sharedContextCrossSignalsRun({ date: optStr(input.date) }) }) });

package/src/access-schema.ts

@@ -241,6 +241,18 @@ export const observeRequestSchema = z.object({
   projectTag: projectTagSchema,
 });
 
+// ---------------------------------------------------------------------------
+// Deep recall (issue #2332)
+// ---------------------------------------------------------------------------
+
+export const deepRecallRequestSchema = z.object({
+  query: z.string().trim().min(1, "query is required").max(2000),
+  /** Optional policy-step ceiling; validated against the configured maximum in the service. */
+  maxSteps: z.union([z.number().int().min(0), z.string()]).optional(),
+  namespace: namespaceSchema,
+  sessionKey: z.string().optional(),
+});
+
 // ---------------------------------------------------------------------------
 // Memory store / suggestion submit
 // ---------------------------------------------------------------------------

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