@remnic/core 9.69.42 → 9.69.43

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

@@ -0,0 +1,85 @@
+/**
+ * Recall-navigation command group (issue #1956) — extracted from cli.ts so
+ * the surface file stays at its structural ceiling (same seam as
+ * deep-recall-commands.ts). `remnic navigate expand|traverse <memoryId>`
+ * runs through EngramAccessService.recallNavigate — the same single
+ * implementation MCP and HTTP call, sharing one renderer.
+ */
+
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import { EngramAccessService } from "../access-service.js";
+
+function parseLimit(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 < 1) {
+    throw new Error(`--limit must be a positive integer; got ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+
+export function registerRecallNavigationCommands(cmd: CliCommand, orchestrator: Orchestrator): void {
+  const run = async (args: unknown[], action: "expand" | "traverse") => {
+    const memoryId = String(args[0] ?? "");
+    const options = (args[args.length - 1] ?? {}) as Record<string, unknown>;
+    const sessionKey = typeof options.sessionKey === "string" ? options.sessionKey : "";
+    if (memoryId.length === 0 || sessionKey.length === 0) {
+      console.error("usage: navigate <expand|traverse> <memoryId> --session-key <key> [--namespace <ns>]");
+      process.exitCode = 1;
+      return;
+    }
+    let limit: number | undefined;
+    try {
+      limit = action === "traverse" ? parseLimit(options.limit) : undefined;
+    } 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.recallNavigate({
+        action,
+        memoryId,
+        sessionKey,
+        ...(action === "expand" && typeof options.disclosure === "string"
+          ? { disclosure: options.disclosure as "chunk" | "section" | "raw" }
+          : {}),
+        ...(action === "traverse" && typeof options.relation === "string" ? { relation: options.relation } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+        ...(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;
+    }
+  };
+
+  cmd
+    .command("navigate expand <memoryId>")
+    .description("Re-render a served memory at deeper disclosure (issue #1956)")
+    .option("--session-key <key>", "Session key whose recent recalls authorize the id (required)")
+    .option("--disclosure <level>", "Target depth: section or raw (default raw)")
+    .option("--namespace <ns>", "Namespace to scope the read to")
+    .option("--json", "JSON output (items + budget + disclosure spend)")
+    .action(async (...args: unknown[]) => run(args, "expand"));
+
+  cmd
+    .command("navigate traverse <memoryId>")
+    .description("Follow typed links from a served memory; neighbors as chunk summaries (issue #1956)")
+    .option("--session-key <key>", "Session key whose recent recalls authorize the id (required)")
+    .option("--relation <type>", "Optional relation filter (supports, contradicts, elaborates, ...)")
+    .option("--limit <n>", "Optional cap on returned neighbors")
+    .option("--namespace <ns>", "Namespace to scope the read to")
+    .option("--json", "JSON output (items + budget + disclosure spend)")
+    .action(async (...args: unknown[]) => run(args, "traverse"));
+}

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 { registerDeepRecallCommands } from "./cli/deep-recall-commands.js";
+import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js"; import { registerRecallNavigationCommands } from "./cli/recall-navigation-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); registerDeepRecallCommands(cmd, orchestrator); registerTimelineCommands(cmd, orchestrator);
+      registerCreationLedgerCommands(cmd, orchestrator); registerMeetingsCommands(cmd, orchestrator); registerOkfCommands(cmd, orchestrator); registerDeepRecallCommands(cmd, orchestrator); registerTimelineCommands(cmd, orchestrator); registerRecallNavigationCommands(cmd, orchestrator);
 
       cmd
         .command("trust-zone-promote")

package/src/config.ts

@@ -50,6 +50,7 @@ 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 { parseRecallNavigationConfig } from "./recall-navigation-config.js";
 import { parseContradictionLocalizationConfig, parseContradictionScanConfig } from "./contradiction-config.js";
 import { parseGraphPathScoringConfig } from "./graph-path-scoring-config.js";
 import { parseWritePathDedupConfig } from "./dedup/novelty-gate.js";
@@ -630,6 +631,7 @@ const MEMORY_OS_PRESETS: Record<MemoryOsPresetName, Record<string, unknown>> = {
     // memory on a conservative preset must set `procedural.enabled: true`
     // explicitly.
     procedural: { enabled: false },
+    recallNavigation: { enabled: false },
   },
   balanced: {
     maxMemoryTokens: 2000,
@@ -1820,6 +1822,8 @@ export function parseConfig(
     driftDetection: parseDriftDetectionConfig(cfg.driftDetection),
     // Budgeted deep-recall surface (issue #2332)
     deepRecall: parseDeepRecallConfig(cfg.deepRecall),
+    // Session-scoped recall navigation (issue #1956)
+    recallNavigation: parseRecallNavigationConfig(cfg.recallNavigation),
     dependencyPropagation: parseDependencyPropagationConfig(cfg),
     // Temporal Supersession (issue #375)
     temporalSupersessionEnabled: cfg.temporalSupersessionEnabled !== false, // On by default

package/src/deep-recall-config.ts

@@ -11,6 +11,7 @@
  */
 
 import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import { EngramAccessInputError } from "./access-errors.js";
 
 export interface DeepRecallConfig {
   /** Master switch for the deep-recall surface. Default false. */
@@ -113,3 +114,34 @@ export function parseDeepRecallMaxSteps(raw: unknown): number | undefined {
   }
   throw new Error(`maxSteps must be a non-negative integer; got ${JSON.stringify(raw)}`);
 }
+
+/**
+ * Resolve the effective per-invocation config from a caller-requested
+ * `maxSteps` override (§33 semantics, extracted from the access service so
+ * the god file stays under its ratchet cap):
+ * - undefined request keeps the parsed config untouched;
+ * - `deepRecall.maxSteps: 0` is a documented disable value — any positive
+ *   override is a refusal, not a ceiling comparison;
+ * - otherwise the override must not exceed the configured ceiling.
+ */
+export function resolveEffectiveDeepRecallConfig(
+  cfg: DeepRecallConfig,
+  requestedSteps: number | undefined,
+): DeepRecallConfig {
+  if (requestedSteps === undefined) return cfg;
+  if (typeof requestedSteps !== "number" || !Number.isInteger(requestedSteps) || requestedSteps < 0) {
+    throw new EngramAccessInputError("deepRecall: maxSteps must be a non-negative integer");
+  }
+  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}`
+    );
+  }
+  return { ...cfg, maxSteps: requestedSteps };
+}

package/src/index.ts

@@ -1451,5 +1451,4 @@ export * from "./maintenance/atomic-file.js";
 // Privacy-safe action-to-outcome trajectory eval (issue #2345)
 export * from "./eval-trajectory.js";
 export { MemoryControllerCoordinator, chooseAction, computeEvidenceReportHash, controllerConfigHash, evaluateActiveGates, hashControllerState, verifyEvidenceReport } from "./memory-controller.js";
-export type { ActiveContextAdapter, ActiveContextMessage, ActiveContextPlan, MemoryControllerActionFamily, MemoryControllerChoice, MemoryControllerConfig, MemoryControllerDeps, MemoryControllerEvent, MemoryControllerEvidence, MemoryControllerEvidenceReport, MemoryControllerExecutors, MemoryControllerMode, MemoryControllerPairedSeedEvidence, MemoryControllerReceipt, MemoryControllerRecorder, MemoryControllerReportReader, MemoryControllerRunResult, MemoryControllerState } from "./memory-controller.js";
-export * from "./recall-navigate.js";
+export type { ActiveContextAdapter, ActiveContextMessage, ActiveContextPlan, MemoryControllerActionFamily, MemoryControllerChoice, MemoryControllerConfig, MemoryControllerDeps, MemoryControllerEvent, MemoryControllerEvidence, MemoryControllerEvidenceReport, MemoryControllerExecutors, MemoryControllerMode, MemoryControllerPairedSeedEvidence, MemoryControllerReceipt, MemoryControllerRecorder, MemoryControllerReportReader, MemoryControllerRunResult, MemoryControllerState } from "./memory-controller.js"; export * from "./recall-navigate.js"; export * from "./recall-navigation.js"; export * from "./recall-navigation-config.js";

package/src/mcp-read-only-tools.ts

@@ -28,6 +28,8 @@ export const MCP_READ_ONLY_TOOL_SUFFIXES: Readonly<Record<string, true>> = {
   meetings_list: true,
   meetings_get: true,
   deep_recall: true,
+  memory_expand: true,
+  memory_traverse: true,
   standup: true,
   action_confidence: true,
   capsule_list: true,

package/src/orchestration/recall-internal.ts

@@ -43,6 +43,7 @@ import { buildProcedureRecallSection, mergeProcedureInjections } from "../proced
 import { canRecallToolScopedMemory } from "../tool-scoped-memory.js";
 import { buildQmdRecallCacheKey, getCachedQmdRecall, setCachedQmdRecall } from "../qmd-recall-cache.js";
 import { MEMORY_ID_PATTERN } from "../recall-handles.js";
+import { shouldRecordRecallAuthorityHistory } from "../recall-navigation-config.js";
 import {
   boundRecallContextComposition, composeRecallContext, contextBudgetForFooter,
   formatCuriosityFooter, renderAuthorityBoundContent, selectCuriosityQuestion,
@@ -5256,10 +5257,9 @@ export class RecallInternalCoordinator {
         }),
         "last recall record",
       );
-      // Issue #1582 — record the admitted memory-id set for handle resolution.
-      // Only when handles are enabled: if injection is off, no handle is ever
-      // rendered, so there is nothing to resolve and we skip the write.
-      if (this.deps.config.recallMemoryHandles && recalledMemoryIds.length > 0) {
+      // Record admitted ids when handles render OR navigation needs authority.
+      // Handles-off + navigation-on is the shipped default; skip only when both are off.
+      if (shouldRecordRecallAuthorityHistory(this.deps.config) && recalledMemoryIds.length > 0) {
         // Only handle-eligible ids aid resolution; filter out non-memory .md
         // basenames (entity reconstructions) so the resolver never records a
         // citation target that cannot be loaded.

package/src/recall-navigation-config.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Recall-navigation config parse (issue #1956 / PR #2937).
+ *
+ * Unknown keys fail closed. Default parse keeps navigation on and display
+ * handles off, and that pair still records authority history.
+ */
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { parseConfig } from "./config.js";
+import {
+  parseRecallNavigationConfig,
+  RECALL_NAVIGATION_CONFIG_DEFAULTS,
+  shouldRecordRecallAuthorityHistory,
+} from "./recall-navigation-config.js";
+
+test("parseRecallNavigationConfig rejects unknown keys instead of ignoring them", () => {
+  assert.throws(
+    () => parseRecallNavigationConfig({ windowSnapshot: 5 }),
+    /recallNavigation contains unknown key "windowSnapshot"/,
+  );
+  assert.throws(
+    () => parseConfig({ recallNavigation: { maxNeighbour: 4 } }),
+    /unknown key "maxNeighbour"/,
+  );
+  assert.deepEqual(parseRecallNavigationConfig({}), RECALL_NAVIGATION_CONFIG_DEFAULTS);
+});
+
+test("default config records authority history with handles off and navigation on", async () => {
+  const memoryDir = await mkdtemp(path.join(tmpdir(), "remnic-nav-defaults-"));
+  try {
+    const config = parseConfig({ memoryDir });
+    assert.equal(config.recallMemoryHandles, false);
+    assert.equal(config.recallNavigation.enabled, true);
+    assert.equal(shouldRecordRecallAuthorityHistory(config), true);
+    assert.equal(
+      shouldRecordRecallAuthorityHistory({
+        recallMemoryHandles: false,
+        recallNavigation: { enabled: false },
+      }),
+      false,
+    );
+    assert.equal(
+      shouldRecordRecallAuthorityHistory({
+        recallMemoryHandles: true,
+        recallNavigation: { enabled: false },
+      }),
+      true,
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/recall-navigation-config.ts

@@ -0,0 +1,107 @@
+/**
+ * Recall-navigation config (issue #1956) — the `recallNavigation` block.
+ *
+ * Parsed the same way `deepRecall` is: shape-validated, string-coercion
+ * safe (§24), no silent clamping of documented values (§33). Navigation is
+ * a read-only surface over already-served recall results, so it defaults
+ * ON; the `conservative` preset pins `enabled: false`.
+ */
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+
+export interface RecallNavigationConfig {
+  /** Master switch. Default true (read-only, additive surface). */
+  enabled: boolean;
+  /**
+   * How many of the session's most recent recall snapshots an expandable
+   * or traversable id may come from. Default 3.
+   */
+  windowSnapshots: number;
+  /** Ceiling for a traverse/entity-neighbor limit override. Default 10. */
+  maxNeighbors: number;
+}
+
+export interface RecallNavigationSettings {
+  recallNavigation: RecallNavigationConfig;
+}
+
+export const DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS = 3;
+
+export const RECALL_NAVIGATION_CONFIG_DEFAULTS: RecallNavigationConfig = {
+  enabled: true,
+  windowSnapshots: DEFAULT_NAVIGATION_WINDOW_SNAPSHOTS,
+  maxNeighbors: 10,
+};
+
+/** Record served ids when display handles or navigation authority needs them. */
+export function shouldRecordRecallAuthorityHistory(config: {
+  recallMemoryHandles?: boolean;
+  recallNavigation?: { enabled?: boolean };
+}): boolean {
+  return config.recallMemoryHandles === true || config.recallNavigation?.enabled === true;
+}
+
+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(
+      `recallNavigation.${key} must be a boolean (or "true"/"false"/"1"/"0"); got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+function parseBoundedInt(
+  src: Record<string, unknown>,
+  key: string,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const value = src[key];
+  if (value === undefined || value === null) return fallback;
+  const coerced = coerceNumber(value);
+  if (coerced === undefined || !Number.isFinite(coerced) || !Number.isInteger(coerced)) {
+    throw new Error(
+      `recallNavigation.${key} must be an integer between ${min} and ${max}; got ${JSON.stringify(value)}`,
+    );
+  }
+  if (coerced < min || coerced > max) {
+    throw new Error(
+      `recallNavigation.${key} must be an integer between ${min} and ${max}; got ${JSON.stringify(value)}`,
+    );
+  }
+  return coerced;
+}
+
+export function parseRecallNavigationConfig(raw: unknown): RecallNavigationConfig {
+  if (raw === undefined || raw === null) return { ...RECALL_NAVIGATION_CONFIG_DEFAULTS };
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`recallNavigation must be an object; got ${JSON.stringify(raw)}`);
+  }
+  const src = raw as Record<string, unknown>;
+  const { enabled: _enabled, windowSnapshots: _windowSnapshots, maxNeighbors: _maxNeighbors, ...unknown } = src;
+  const unknownKey = Object.keys(unknown)[0];
+  if (unknownKey !== undefined) {
+    throw new Error(`recallNavigation contains unknown key ${JSON.stringify(unknownKey)}`);
+  }
+  return {
+    enabled: parseFlag(src, "enabled", RECALL_NAVIGATION_CONFIG_DEFAULTS.enabled),
+    windowSnapshots: parseBoundedInt(
+      src,
+      "windowSnapshots",
+      RECALL_NAVIGATION_CONFIG_DEFAULTS.windowSnapshots,
+      1,
+      50,
+    ),
+    maxNeighbors: parseBoundedInt(
+      src,
+      "maxNeighbors",
+      RECALL_NAVIGATION_CONFIG_DEFAULTS.maxNeighbors,
+      1,
+      50,
+    ),
+  };
+}

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

@@ -0,0 +1,141 @@
+/**
+ * Recall-navigation HTTP glue (issue #1956) — route body lives here so
+ * access-http.ts stays at its structural ceiling (same seam as
+ * deep-recall-http-glue.ts).
+ *
+ * Input errors map to 400; everything else rethrows to the global 500
+ * handler. Config gating (`recallNavigation.enabled`) lives in the service
+ * and returns a typed `error: "disabled"` refusal — this module only
+ * translates transport shape. Namespace/sessionKey resolution flows through
+ * the caller-supplied `scopeFor` gate so a body-supplied namespace passes
+ * the SAME effective-namespace allow-list as the query string (issue #1850
+ * finding 2), and `authenticatedPrincipal` reaches the service so
+ * authorization derives from the presenting principal, never the
+ * client-supplied sessionKey.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { EngramAccessInputError } from "./access-errors.js";
+import type { EngramAccessService } from "./access-service.js";
+import type { NavigationAction } from "./recall-navigation.js";
+
+type RespondJson = (res: ServerResponse, status: number, payload: unknown) => void;
+type ReadJsonBody = (req: IncomingMessage) => Promise<unknown>;
+
+type ScopeFor = (
+  bodyNamespace?: string,
+  bodySessionKey?: string,
+) => { namespace?: string; sessionKey?: string; authenticatedPrincipal?: string };
+
+const VALID_RELATIONS = [
+  "supports",
+  "contradicts",
+  "elaborates",
+  "causes",
+  "caused_by",
+  "supersedes",
+  "follows",
+  "references",
+  "related",
+] as const;
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function optInt(value: unknown): number | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const parsed = typeof value === "string" ? Number(value) : value;
+  if (typeof parsed !== "number" || !Number.isInteger(parsed) || parsed < 1) {
+    throw new EngramAccessInputError("limit must be a positive integer");
+  }
+  return parsed;
+}
+
+async function respondNavigation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+  action: Extract<NavigationAction, "expand" | "traverse">,
+): Promise<void> {
+  const body = (await readJsonBody(req)) as Record<string, unknown>;
+  const memoryId = optStr(body.memoryId);
+  if (memoryId === undefined || memoryId.trim().length === 0) {
+    respondJson(res, 400, { error: "invalid_request", detail: "memoryId is required" });
+    return;
+  }
+  const sessionKey = optStr(body.sessionKey);
+  if (sessionKey === undefined || sessionKey.trim().length === 0) {
+    respondJson(res, 400, { error: "invalid_request", detail: "sessionKey is required" });
+    return;
+  }
+  let disclosure: "chunk" | "section" | "raw" | undefined;
+  let relation: string | undefined;
+  if (action === "expand") {
+    const raw = optStr(body.disclosure);
+    if (raw !== undefined && raw !== "chunk" && raw !== "section" && raw !== "raw") {
+      respondJson(res, 400, { error: "invalid_request", detail: "disclosure must be one of chunk, section, raw" });
+      return;
+    }
+    disclosure = raw;
+  } else {
+    relation = optStr(body.relation);
+    if (relation !== undefined && !(VALID_RELATIONS as readonly string[]).includes(relation)) {
+      respondJson(
+        res,
+        400,
+        { error: "invalid_request", detail: `relation must be one of ${VALID_RELATIONS.join(", ")}` },
+      );
+      return;
+    }
+  }
+  let limit: number | undefined;
+  try {
+    limit = optInt(body.limit);
+  } catch (err) {
+    respondJson(res, 400, { error: "invalid_request", detail: err instanceof Error ? err.message : String(err) });
+    return;
+  }
+  const scope = scopeFor(optStr(body.namespace), sessionKey);
+  const result = await service.recallNavigate({
+    action,
+    memoryId,
+    sessionKey: scope.sessionKey ?? sessionKey,
+    ...(disclosure !== undefined ? { disclosure } : {}),
+    ...(relation !== undefined ? { relation } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+    namespace: scope.namespace,
+    authenticatedPrincipal: scope.authenticatedPrincipal,
+  });
+  const { rendered: _rendered, ...payload } = result;
+  respondJson(res, 200, payload);
+}
+
+export async function maybeRespondRecallNavigation(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathname: string,
+  method: string | undefined,
+  enforceTokenOp: (op: "memory_expand" | "memory_traverse") => void,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+): Promise<boolean> {
+  if (method === "POST" && (pathname === "/engram/v1/memory/expand" || pathname === "/remnic/v1/memory/expand")) {
+    enforceTokenOp("memory_expand");
+    await respondNavigation(req, res, respondJson, readJsonBody, service, scopeFor, "expand");
+    return true;
+  }
+  if (method === "POST" && (pathname === "/engram/v1/memory/traverse" || pathname === "/remnic/v1/memory/traverse")) {
+    enforceTokenOp("memory_traverse");
+    await respondNavigation(req, res, respondJson, readJsonBody, service, scopeFor, "traverse");
+    return true;
+  }
+  return false;
+}
+

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

@@ -0,0 +1,60 @@
+/**
+ * Recall-navigation MCP tool definitions (issue #1956) — extracted from
+ * access-mcp.ts so the surface file stays at its structural ceiling (same
+ * seam as deep-recall-mcp-tools.ts). Spread back into `this.tools`
+ * (`...RECALL_NAVIGATION_MCP_TOOLS`); the migrated-operation mapping lives
+ * in access-mcp.ts's MCP_MIGRATED_OPERATIONS. The `remnic.` canonical alias
+ * is minted by withToolAliases at tools/list time.
+ *
+ * Gating: spread is conditional on `service.recallNavigationEnabled !== false`
+ * — the flag defaults TRUE, so the check treats an absent property (older
+ * service shape / test stub) as enabled and removes the tools from listing
+ * ONLY on an explicit false. Disabled config therefore yields tools absent
+ * from tools/list, not present-but-erroring.
+ */
+
+import type { McpTool } from "./access-mcp.js";
+
+export const RECALL_NAVIGATION_MCP_TOOLS: McpTool[] = [
+  {
+    name: "engram.memory_expand",
+    description:
+      "Re-render one memory a recall already served to this session at a deeper disclosure level (section or raw). Cheap follow-up — no fresh search. The id must come from this session's recent recall results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "Memory id (or [m:xxxx] handle) served by a recent recall. Required." },
+        sessionKey: { type: "string", description: "Session key whose recent recalls authorize the id. Required." },
+        disclosure: {
+          type: "string",
+          enum: ["section", "raw"],
+          description: "Target depth; must be deeper than the chunk preview already served. Default raw.",
+        },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["memoryId", "sessionKey"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "engram.memory_traverse",
+    description:
+      "Follow typed links (supports/contradicts/elaborates/causes/caused_by/supersedes/follows/references/related) from a memory a recall already served to this session. Neighbors return as chunk-level summaries, optionally filtered by relation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "Memory id (or [m:xxxx] handle) served by a recent recall. Required." },
+        sessionKey: { type: "string", description: "Session key whose recent recalls authorize the id. Required." },
+        relation: {
+          type: "string",
+          enum: ["supports", "contradicts", "elaborates", "causes", "caused_by", "supersedes", "follows", "references", "related"],
+          description: "Optional relation filter; omitted means every known relation.",
+        },
+        limit: { type: "integer", minimum: 1, description: "Optional cap on returned neighbors (ceiling: recallNavigation.maxNeighbors)." },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["memoryId", "sessionKey"],
+      additionalProperties: false,
+    },
+  },
+];