@remnic/core 9.69.45 → 9.69.47

package/src/memory-age.test.ts

@@ -0,0 +1,106 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  applyRecencyBoost,
+  assessMtimeTrust,
+  collectMtimeFallbackContext,
+  resolveMemoryAge,
+  utcDayKey,
+} from "./memory-age.js";
+
+const DAY_MS = 86_400_000;
+const NOW = Date.parse("2026-08-25T12:00:00.000Z");
+
+function spreadDays(count: number, startMs = NOW): number[] {
+  return Array.from({ length: count }, (_unused, i) => startMs + i * DAY_MS);
+}
+
+test("resolveMemoryAge: content dates win over a fresh mtime (#2976)", () => {
+  const created = new Date(NOW - 40 * DAY_MS).toISOString();
+  const resolved = resolveMemoryAge({ created });
+  assert.equal(resolved.source, "content");
+  assert.equal(resolved.referenceMs, Date.parse(created), "ages by the content date, not the fresh mtime");
+});
+
+test("resolveMemoryAge: created wins over updated; updated backs a missing created", () => {
+  const created = new Date(NOW - 90 * DAY_MS).toISOString();
+  const updated = new Date(NOW - 1 * DAY_MS).toISOString();
+  assert.equal(resolveMemoryAge({ created, updated }).referenceMs, Date.parse(created));
+  assert.equal(resolveMemoryAge({ created: undefined, updated }).referenceMs, Date.parse(updated));
+});
+
+test("resolveMemoryAge: unparsable content dates never produce a reference", () => {
+  for (const bad of ["not-a-date", "", "2026-13-45"] as const) {
+    const resolved = resolveMemoryAge({ created: bad, updated: bad });
+    assert.equal(resolved.referenceMs, null, `unparsable date ${JSON.stringify(bad)} must not resolve`);
+    assert.equal(resolved.source, "unknown");
+  }
+});
+
+test("resolveMemoryAge: mtime backs age only when trusted and no content date exists", () => {
+  const mtimeMs = NOW - 2 * DAY_MS;
+  const trusted = assessMtimeTrust([mtimeMs, NOW - 9 * DAY_MS]);
+  assert.equal(resolveMemoryAge({}, mtimeMs, trusted).source, "mtime");
+  assert.equal(resolveMemoryAge({ created: "garbage" }, mtimeMs, trusted).source, "mtime");
+  assert.equal(resolveMemoryAge({ created: new Date(NOW).toISOString() }, mtimeMs, trusted).source, "content");
+  const distrusted = assessMtimeTrust([mtimeMs, mtimeMs, NOW - 9 * DAY_MS, NOW - 11 * DAY_MS]);
+  assert.equal(distrusted.bulkTouchDays.has(utcDayKey(mtimeMs)), true, "two of four same-day files cluster");
+  const refused = resolveMemoryAge({}, mtimeMs, distrusted);
+  assert.equal(refused.source, "unknown", "an untrusted mtime is unknown age, never fresh");
+  assert.equal(refused.referenceMs, null);
+});
+
+test("assessMtimeTrust: the measured distill-kura shape (50 of 214 files on one day) is a bulk touch", () => {
+  const bulkDay = NOW - 400 * DAY_MS;
+  const sample = [...Array<number>(50).fill(bulkDay), ...spreadDays(164, NOW - 200 * DAY_MS)];
+  const trust = assessMtimeTrust(sample);
+  assert.equal(trust.bulkTouchDays.size, 1);
+  assert.equal(trust.bulkTouchDays.has(utcDayKey(bulkDay)), true);
+  assert.equal(trust.isTrusted(bulkDay), false);
+  assert.equal(trust.isTrusted(sample[sample.length - 1]!), true);
+});
+
+test("assessMtimeTrust: the 20% boundary is inclusive", () => {
+  // 43 of 214 = 20.09% -> flagged; 42 of 214 = 19.6% -> not flagged.
+  const flagged = assessMtimeTrust([...Array<number>(43).fill(NOW), ...spreadDays(171, NOW - 400 * DAY_MS)]);
+  assert.equal(flagged.bulkTouchDays.has(utcDayKey(NOW)), true, "43/214 on one day is >= 20%");
+  const clear = assessMtimeTrust([...Array<number>(42).fill(NOW), ...spreadDays(172, NOW - 400 * DAY_MS)]);
+  assert.equal(clear.bulkTouchDays.has(utcDayKey(NOW)), false, "42/214 on one day is < 20%");
+});
+
+test("assessMtimeTrust: a single file never forms a cluster (min 2)", () => {
+  const trust = assessMtimeTrust([NOW]);
+  assert.equal(trust.bulkTouchDays.size, 0);
+  assert.equal(trust.isTrusted(NOW), true);
+  const pair = assessMtimeTrust([NOW, NOW]);
+  assert.equal(pair.bulkTouchDays.size, 1, "two files on one day meet the min-2 rule");
+});
+
+test("applyRecencyBoost: exact blend, unknown age untouched, weight 0 untouched, future clamped", () => {
+  const memory = {
+    path: "facts/a.md",
+    frontmatter: { created: new Date(NOW - 14 * DAY_MS).toISOString() },
+  };
+  const expected = 1 * 0.5 + Math.pow(0.5, 14 / 7) * 0.5;
+  assert.ok(Math.abs(applyRecencyBoost(1, memory, 0.5, NOW) - expected) < 1e-12);
+  // Unknown age (no dates, no trusted mtime) leaves the score alone.
+  assert.equal(applyRecencyBoost(0.7, { path: "facts/b.md", frontmatter: {} }, 0.5, NOW), 0.7);
+  assert.equal(applyRecencyBoost(0.7, memory, 0, NOW), 0.7);
+  // A corrupt future date clamps to age zero instead of boosting past 1.
+  const future = {
+    path: "facts/c.md",
+    frontmatter: { created: new Date(NOW + 30 * DAY_MS).toISOString() },
+  };
+  assert.equal(applyRecencyBoost(1, future, 0.5, NOW), 1);
+});
+
+test("collectMtimeFallbackContext: fully dated memories skip it entirely (no stats)", async () => {
+  // The paths do not exist: any stat would surface below as a null mtime
+  // instead of the documented null short-circuit.
+  const context = await collectMtimeFallbackContext([
+    { path: "/nonexistent/facts/a.md", created: new Date(NOW).toISOString() },
+    { path: "/nonexistent/facts/b.md", updated: new Date(NOW).toISOString() },
+  ]);
+  assert.equal(context, null);
+});

package/src/memory-age.ts

@@ -0,0 +1,196 @@
+/**
+ * Shared memory-age resolution (issue #2976).
+ *
+ * "Age is not mtime" (distill-kura `weave.py` `age_days`): `cp -r`, a
+ * restore, a checkout, or a bulk import resets file mtimes, so any freshness
+ * mechanism keyed on mtime either switches itself off or boosts everything
+ * equally. Remnic therefore resolves a memory's age from dates written
+ * INSIDE the memory first:
+ *
+ *   1. frontmatter `created` — the recall ranking reference before #2976,
+ *      kept first so every dated memory scores exactly as it did;
+ *   2. frontmatter `updated` — the content-revision date;
+ *   3. file mtime — only when no content date exists AND the caller's trust
+ *      assessment accepts it (see `assessMtimeTrust`);
+ *   4. otherwise UNKNOWN: no reference instant, and downstream scoring must
+ *      treat unknown age as never-fresh (no recency boost), never as
+ *      "just written".
+ *
+ * Bi-temporal `valid_at`/`observedAt` are deliberately NOT in the ladder:
+ * they date when the fact was true, not when the memory was written, so a
+ * fresh correction about an old event would be misaged by them.
+ *
+ * Bulk-touch heuristic (distill-kura measured 50/214 files sharing one
+ * bulk-touch day, mtime understating true age by a median of 11 days, worst
+ * case 425): a UTC calendar day shared by >= max(BULK_TOUCH_MIN_FILES,
+ * BULK_TOUCH_STORE_FRACTION of the sampled files) is a bulk-touch day, and
+ * mtimes falling on a bulk-touch day are untrusted — those ages are unknown,
+ * not fresh. The sample is the scored result set of the calling pipeline
+ * (bounded I/O), which observes a bulk-touched store as a same-day cluster.
+ */
+
+import { stat } from "node:fs/promises";
+
+/** Minimum files sharing one calendar day before that day is bulk-touched. */
+export const BULK_TOUCH_MIN_FILES = 2;
+/** Fraction of the sampled files on one day that marks a bulk touch. */
+export const BULK_TOUCH_STORE_FRACTION = 0.2;
+
+/** Recency half-life (days) used by `applyRecencyBoost`. */
+export const RECENCY_HALF_LIFE_DAYS = 7;
+
+/** How the resolved age reference was obtained. */
+export type MemoryAgeSource = "content" | "mtime" | "unknown";
+
+export interface ResolvedMemoryAge {
+  /** Reference instant for age computations, or null when age is unknown. */
+  referenceMs: number | null;
+  source: MemoryAgeSource;
+}
+
+/** Content dates written inside the memory (frontmatter). */
+export interface MemoryAgeDates {
+  created?: string | null;
+  updated?: string | null;
+}
+
+/** Minimal memory shape the resolver needs; `path` keys the mtime fallback. */
+export interface MemoryAgeSubject extends MemoryAgeDates {
+  path: string;
+}
+
+/** MemoryFile slice `applyRecencyBoost` reads; dates live in frontmatter. */
+export interface RecencyBoostSubject {
+  path: string;
+  frontmatter: MemoryAgeDates;
+}
+
+/** Result of assessing a sample of mtimes for bulk-touch clustering. */
+export interface MtimeTrust {
+  /** UTC day keys ("YYYY-MM-DD") whose mtime counts mark a bulk touch. */
+  bulkTouchDays: ReadonlySet<string>;
+  isTrusted(mtimeMs: number): boolean;
+}
+
+/** Per-recall mtime fallback context (null when no scored memory needs it). */
+export interface MtimeFallbackContext {
+  mtimeMsByPath: Map<string, number | null>;
+  trust: MtimeTrust;
+}
+
+function finiteMs(value: string | null | undefined): number | null {
+  if (typeof value !== "string") return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/**
+ * Resolve the reference instant for a memory's age. Content dates win over
+ * mtime; an mtime is consulted only when no content date parses and the
+ * trust assessment (when provided) accepts it; otherwise age is unknown.
+ */
+export function resolveMemoryAge(
+  subject: MemoryAgeDates,
+  mtimeMs?: number | null,
+  trust?: MtimeTrust | null,
+): ResolvedMemoryAge {
+  const contentMs = finiteMs(subject.created) ?? finiteMs(subject.updated);
+  if (contentMs !== null) return { referenceMs: contentMs, source: "content" };
+  if (
+    typeof mtimeMs === "number" &&
+    Number.isFinite(mtimeMs) &&
+    trust?.isTrusted(mtimeMs) !== false
+  ) {
+    return { referenceMs: mtimeMs, source: "mtime" };
+  }
+  return { referenceMs: null, source: "unknown" };
+}
+
+/** UTC calendar-day key ("YYYY-MM-DD") for a millisecond instant. */
+export function utcDayKey(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+/**
+ * Assess a sample of mtimes: days shared by >= max(BULK_TOUCH_MIN_FILES,
+ * BULK_TOUCH_STORE_FRACTION of the sample) are bulk-touch days, and their
+ * mtimes are untrusted for age. An empty or scattered sample trusts nothing
+ * less than it did before — only clustering changes anything.
+ */
+export function assessMtimeTrust(sampleMtimesMs: readonly number[]): MtimeTrust {
+  const counts = new Map<string, number>();
+  for (const ms of sampleMtimesMs) {
+    if (!Number.isFinite(ms)) continue;
+    const key = utcDayKey(ms);
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const threshold = Math.max(
+    BULK_TOUCH_MIN_FILES,
+    sampleMtimesMs.length * BULK_TOUCH_STORE_FRACTION,
+  );
+  const bulkTouchDays = new Set<string>();
+  for (const [day, count] of counts) {
+    if (count >= threshold) bulkTouchDays.add(day);
+  }
+  return {
+    bulkTouchDays,
+    isTrusted: (mtimeMs: number) => Number.isFinite(mtimeMs) && !bulkTouchDays.has(utcDayKey(mtimeMs)),
+  };
+}
+
+/**
+ * Build the mtime fallback context for a recall boost pass. Returns null —
+ * with zero stat calls — when every scored memory already has a content
+ * date, so the common path pays nothing. Otherwise stats the scored files
+ * (bounded by the result count) and assesses their mtimes for bulk-touch
+ * clustering. Unreadable files map to null mtimes (unknown age, never fresh).
+ */
+export async function collectMtimeFallbackContext(
+  memories: ReadonlyArray<MemoryAgeSubject>,
+): Promise<MtimeFallbackContext | null> {
+  const needsFallback = memories.some(
+    (m) => finiteMs(m.created) === null && finiteMs(m.updated) === null,
+  );
+  if (!needsFallback) return null;
+  const stats = await Promise.all(
+    memories.map(async (m) => {
+      try {
+        return (await stat(m.path)).mtimeMs;
+      } catch {
+        return null;
+      }
+    }),
+  );
+  const mtimeMsByPath = new Map<string, number | null>(
+    memories.map((m, i) => [m.path, stats[i] ?? null]),
+  );
+  const trust = assessMtimeTrust(
+    stats.filter((ms): ms is number => ms !== null && Number.isFinite(ms)),
+  );
+  return { mtimeMsByPath, trust };
+}
+
+/**
+ * Apply the exponential recency blend to one score. Age resolves per
+ * `resolveMemoryAge`; unknown age leaves the score untouched (never fresh).
+ * A future reference instant clamps to age zero rather than boosting above
+ * the recency ceiling (corrupt dates are not super-fresh).
+ */
+export function applyRecencyBoost(
+  score: number,
+  memory: RecencyBoostSubject,
+  recencyWeight: number,
+  nowMs: number,
+  fallback?: MtimeFallbackContext | null,
+): number {
+  if (recencyWeight <= 0) return score;
+  const resolved = resolveMemoryAge(
+    memory.frontmatter,
+    fallback?.mtimeMsByPath.get(memory.path) ?? null,
+    fallback?.trust,
+  );
+  if (resolved.referenceMs === null) return score;
+  const ageDays = Math.max(0, (nowMs - resolved.referenceMs) / 86_400_000);
+  const recencyScore = Math.pow(0.5, ageDays / RECENCY_HALF_LIFE_DAYS);
+  return score * (1 - recencyWeight) + recencyScore * recencyWeight;
+}

package/src/memory-browse-http-glue.ts

@@ -0,0 +1,93 @@
+/**
+ * Memory-store browse HTTP glue (issue #2978) — route bodies live here so
+ * access-http.ts stays at its structural ceiling (same seam as
+ * recall-navigation-http-glue.ts).
+ *
+ * Each route carries its literal `enforceTokenOp("<op>")` boundary-dispatch
+ * marker so `access-surface-catalog.test.ts` can prove dispatch statically.
+ * Input errors map to 400; everything else rethrows to the global 500
+ * handler. Namespace 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 client-supplied input.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { EngramAccessInputError } from "./access-errors.js";
+import type { EngramAccessService } from "./access-service.js";
+import type { BrowseVerb } from "./memory-browse.js";
+
+type RespondJson = (res: ServerResponse, status: number, payload: unknown) => void;
+type ReadJsonBody = (req: IncomingMessage) => Promise<unknown>;
+
+type ScopeFor = (
+  bodyNamespace?: string,
+) => { namespace?: string; authenticatedPrincipal?: string };
+
+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)) {
+    throw new EngramAccessInputError("depth must be an integer");
+  }
+  return parsed;
+}
+
+async function respondBrowse(
+  req: IncomingMessage,
+  res: ServerResponse,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+  verb: BrowseVerb,
+): Promise<void> {
+  const body = (await readJsonBody(req)) as Record<string, unknown>;
+  const scope = scopeFor(optStr(body.namespace));
+  const depth = verb === "tree" ? optInt(body.depth) : undefined;
+  const result = await service.memoryStoreBrowse({
+    verb,
+    ...(optStr(body.path) !== undefined ? { path: optStr(body.path) } : {}),
+    ...(depth !== undefined ? { depth } : {}),
+    ...(verb === "find" && optStr(body.pattern) !== undefined ? { pattern: optStr(body.pattern) } : {}),
+    namespace: scope.namespace,
+    authenticatedPrincipal: scope.authenticatedPrincipal,
+  });
+  const { rendered: _rendered, ...payload } = result;
+  respondJson(res, 200, payload);
+}
+
+export async function maybeRespondMemoryBrowse(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathname: string,
+  method: string | undefined,
+  enforceTokenOp: (op: "memory_ls" | "memory_tree" | "memory_find") => void,
+  respondJson: RespondJson,
+  readJsonBody: ReadJsonBody,
+  service: EngramAccessService,
+  scopeFor: ScopeFor,
+): Promise<boolean> {
+  if (method === "POST" && (pathname === "/engram/v1/memory/ls" || pathname === "/remnic/v1/memory/ls")) {
+    enforceTokenOp("memory_ls");
+    await respondBrowse(req, res, respondJson, readJsonBody, service, scopeFor, "ls");
+    return true;
+  }
+  if (method === "POST" && (pathname === "/engram/v1/memory/tree" || pathname === "/remnic/v1/memory/tree")) {
+    enforceTokenOp("memory_tree");
+    await respondBrowse(req, res, respondJson, readJsonBody, service, scopeFor, "tree");
+    return true;
+  }
+  if (method === "POST" && (pathname === "/engram/v1/memory/find" || pathname === "/remnic/v1/memory/find")) {
+    enforceTokenOp("memory_find");
+    await respondBrowse(req, res, respondJson, readJsonBody, service, scopeFor, "find");
+    return true;
+  }
+  return false;
+}

package/src/memory-browse-mcp-tools.ts

@@ -0,0 +1,57 @@
+/**
+ * Memory-store browse MCP tool definitions (issue #2978) — extracted from
+ * access-mcp.ts so the surface file stays at its structural ceiling (same
+ * seam as recall-navigation-mcp-tools.ts). Spread back into `this.tools`
+ * (`...MEMORY_BROWSE_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.
+ *
+ * Always listed: browse is a pure read over the caller's resolved
+ * namespace, so there is no gating flag (unlike recallNavigation).
+ */
+
+import type { McpTool } from "./access-mcp.js";
+
+export const MEMORY_BROWSE_MCP_TOOLS: McpTool[] = [
+  {
+    name: "engram.memory_ls",
+    description:
+      "List what exists at one store path in your namespace: category directories with memory counts, memory files with a one-line description. Answers \"is there anything here at all?\" without a search query. Derived stores (artifacts/, meetings records, wearables, state/) are invisible by design.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Store path to list, relative to the namespace root (\"\" or \"/\" = root). Default root." },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "engram.memory_tree",
+    description:
+      "Depth-limited tree under one store path (depth 1 acts like ls). Deterministic sorted output, entry-capped so a large store cannot flood the response.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Store path to expand, relative to the namespace root (default root)." },
+        depth: { type: "integer", minimum: 1, maximum: 4, description: "Expansion depth, 1-4. Default 1." },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "engram.memory_find",
+    description:
+      "Deterministic name/path lookup over your namespace's store: `*` glob (e.g. \"facts/2026-08-*/*.md\") or substring. Use memory_search for semantic matching; use this when you know (part of) the name.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        pattern: { type: "string", description: "Glob with `*` wildcards or substring to match against path and filename. Required." },
+        namespace: { type: "string", description: "Caller namespace to scope this operation to." },
+      },
+      required: ["pattern"],
+      additionalProperties: false,
+    },
+  },
+];

package/src/memory-browse-operations.ts

@@ -0,0 +1,88 @@
+/**
+ * Memory-store browse boundary operations (issue #2978).
+ *
+ * `memory_ls` / `memory_tree` / `memory_find` route MCP, HTTP, and CLI
+ * dispatch through the shared validation + error-mapping layer
+ * (access-boundary.ts) to the single `EngramAccessService.memoryStoreBrowse`
+ * implementation. Sibling module so access-operations-batch.ts stays at its
+ * ceiling seam (same layout as recall-navigation-operations.ts).
+ */
+
+import { z } from "zod";
+
+import { defineOperation } from "./access-boundary.js";
+import { EngramAccessInputError } from "./access-errors.js";
+import type { BrowseVerb, MemoryStoreBrowseRequest } from "./memory-browse.js";
+
+function strictSchema<T extends z.ZodRawShape>(shape: T): z.ZodType<Record<string, unknown>> {
+  return z.preprocess(
+    (data) => {
+      if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+        return Object.fromEntries(Object.entries(data as Record<string, unknown>).filter(([, value]) => value !== null));
+      }
+      return data;
+    },
+    z.object(shape).passthrough(),
+  ) as unknown as z.ZodType<Record<string, unknown>>;
+}
+
+function optStr(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function optInt(value: unknown): number | undefined {
+  if (typeof value === "number") return value;
+  if (typeof value === "string" && Number.isFinite(Number(value))) return Number(value);
+  return undefined;
+}
+
+function reqStr(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new EngramAccessInputError(`${field} is required`);
+  }
+  return value;
+}
+
+const verbShape = {
+  namespace: z.string().optional(),
+} as const;
+
+function browseRequest(verb: BrowseVerb, input: Record<string, unknown>): MemoryStoreBrowseRequest {
+  return {
+    verb,
+    ...(optStr(input.path) !== undefined ? { path: optStr(input.path) } : {}),
+    ...(optInt(input.depth) !== undefined ? { depth: optInt(input.depth) } : {}),
+    ...(optStr(input.pattern) !== undefined ? { pattern: optStr(input.pattern) } : {}),
+    namespace: optStr(input.namespace),
+  };
+}
+
+defineOperation({
+  name: "memory_ls",
+  description: "List the children of one store path in the caller's namespace: category dirs with counts, memory files with a one-line description.",
+  schema: strictSchema({ ...verbShape, path: z.string().optional() }),
+  handler: async (input, ctx) => ({
+    result: await ctx.service.memoryStoreBrowse({ ...browseRequest("ls", input), authenticatedPrincipal: ctx.authenticatedPrincipal }),
+  }),
+});
+
+defineOperation({
+  name: "memory_tree",
+  description: "Depth-limited tree of store paths under one directory, one-line descriptions, entry-capped.",
+  schema: strictSchema({ ...verbShape, path: z.string().optional(), depth: z.union([z.number(), z.string()]).optional() }),
+  handler: async (input, ctx) => ({
+    result: await ctx.service.memoryStoreBrowse({ ...browseRequest("tree", input), authenticatedPrincipal: ctx.authenticatedPrincipal }),
+  }),
+});
+
+defineOperation({
+  name: "memory_find",
+  description: "Deterministic name/path match (`*` glob or substring) over the caller's namespace store; semantic search stays memory_search.",
+  schema: strictSchema({ ...verbShape, pattern: z.string() }),
+  handler: async (input, ctx) => ({
+    result: await ctx.service.memoryStoreBrowse({
+      ...browseRequest("find", { ...input, pattern: reqStr(input.pattern, "pattern") }),
+      authenticatedPrincipal: ctx.authenticatedPrincipal,
+    }),
+  }),
+});