@remnic/core 9.46.1 → 9.46.2

package/src/access-service.ts

@@ -107,8 +107,9 @@ import {
   defaultNamespaceAtFlatRoot,
   mergeMemorySearchDefaultFallback,
   resolveMemorySearchDefaultFallback,
-  runMemorySearchFanout,
+  memorySearchThroughScope,
 } from "./access-memory-search-fanout.js";
+import { isSearchExcludedPath } from "./orchestration/generic-recall-paths.js";
 import {
   buildQualityScore,
   buildProposedActions,
@@ -4711,47 +4712,45 @@ export class EngramAccessService {
     namespace?: string;
     maxResults?: number;
     collection?: string;
+    mode?: "search" | "hybrid" | "bm25" | "vector";
     principal?: string;
   }): Promise<{ query: string; results: Array<{ path: string; score: number; snippet: string }>; count: number }> {
-    const { query, namespace, maxResults, principal } = request;
-    const collection = request.collection?.trim();
-    if (request.collection !== undefined && !collection) {
-      throw new EngramAccessInputError("collection must be a non-empty string");
-    }
-
-    let results: Array<{ path: string; score: number; snippet?: string }>;
-    if (!resolveNamespaceCapabilities(this.orchestrator.config).namespaces) {
-      this.resolveReadableNamespace(namespace, principal);
-      results = collection === "global"
-        ? await this.orchestrator.qmd.searchGlobal(query, maxResults)
-        : await this.orchestrator.qmd.search(query, collection, maxResults);
-    } else {
-      const readableNamespaces = await this.resolveReadableNamespacesForSearch(namespace, principal);
-      const namespaces = this.resolveMemorySearchNamespacesForCollection(
-        collection,
-        readableNamespaces,
-        namespace?.trim() ? undefined : principal,
-      );
-      results = await runMemorySearchFanout({
-        query,
-        namespaces,
-        maxResults,
-        principal,
-        requestedNamespace: namespace,
-        collection,
-        search: (params) => this.orchestrator.searchAcrossNamespaces(params),
-      });
-    }
-
-    return {
-      query,
-      results: results.map((r) => ({
-        path: r.path,
-        score: r.score,
-        snippet: (r.snippet ?? "").slice(0, 800),
-      })),
-      count: results.length,
-    };
+    const { qmd, config } = this.orchestrator;
+    return memorySearchThroughScope(
+      {
+        namespacesEnabled: resolveNamespaceCapabilities(config).namespaces,
+        // `0` is preserved, never coerced: a zero limit is a runtime
+        // compatibility guarantee (AGENTS.md guardrail 4), and it means the
+        // same thing here as an explicit `maxResults: 0` from the caller - an
+        // empty result with no backend call. Anything non-numeric falls back
+        // to the documented default.
+        defaultBudget: typeof config.qmdMaxResults === "number" ? config.qmdMaxResults : 10,
+        // Search-specific: artifacts and the other dedicated surfaces stay
+        // out, but ARCHIVED memories remain findable - explicit search is one
+        // of the surfaces the lifecycle reserves them for.
+        isExcluded: (memoryPath) =>
+          isSearchExcludedPath(
+            memoryPath,
+            // The caller's own collection disambiguates a prefix that is also
+            // a memory category name (`collection: "facts"`).
+            { ...config, requestedCollection: request.collection?.trim() || undefined },
+            "qmd",
+          ),
+        authorizeFlatCorpus: (namespace, principal) => {
+          this.resolveReadableNamespace(namespace, principal);
+        },
+        authorizeNamespaces: async (namespace, principal, collection) =>
+          this.resolveMemorySearchNamespacesForCollection(
+            collection,
+            await this.resolveReadableNamespacesForSearch(namespace, principal),
+            namespace?.trim() ? undefined : principal,
+          ),
+        searchAcrossNamespaces: (params) => this.orchestrator.searchAcrossNamespaces(params),
+        searchGlobal: (query, maxResults) => qmd.searchGlobal(query, maxResults),
+        search: (query, collection, maxResults) => qmd.search(query, collection, maxResults),
+      },
+      request,
+    );
   }
 
   async memoryProfile(namespace?: string, principal?: string): Promise<Record<string, unknown>> {

package/src/access-surface-catalog.ts

@@ -177,6 +177,7 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "GET", pathname: "/engram/v1/adapters", operation: "adapters_status" },
   { method: "POST", pathname: "/engram/v1/recall", operation: "recall" },
   { method: "POST", pathname: "/engram/v1/external-wikis/search", operation: "external_wiki_search" },
+  { method: "POST", pathname: "/engram/v1/memories/search", operation: "memory_search" },
   { method: "POST", pathname: "/engram/v1/coding-context", operation: "set_coding_context" },
   { method: "POST", pathname: "/engram/v1/capsules/export", operation: "capsule_export" },
   { method: "POST", pathname: "/engram/v1/capsules/import", operation: "capsule_import" },

package/src/orchestration/generic-recall-paths.ts

@@ -13,6 +13,12 @@ export interface GenericRecallPathPolicy {
   readonly memoryDir?: string;
   readonly qmdCollection?: string;
   readonly qmdColdCollection?: string;
+  /**
+   * The collection THIS request named, when it named one. A caller may select
+   * a custom collection whose name is also a memory category, which the
+   * configured names alone cannot disambiguate.
+   */
+  readonly requestedCollection?: string;
 }
 
 type GenericRecallPathSource = "filesystem" | "qmd";
@@ -94,17 +100,122 @@ function isExternalWikiQmdPath(
   return isExternalWikiCollectionName(collection);
 }
 
+/**
+ * Paths an EXPLICIT ranked search must not return.
+ *
+ * Narrower than {@link isGenericRecallExcludedPath} on purpose. Recall
+ * injection also drops archived memories because they are cold by definition,
+ * but archive is explicitly reserved for "explicit read or search surfaces"
+ * (docs/architecture/memory-lifecycle.md) — hiding it from `memory_search`
+ * would remove the only way to find it. Everything else stays excluded: those
+ * paths flow through their own dedicated surfaces, never a generic search.
+ */
+export function isSearchExcludedPath(
+  filePath: string,
+  policy: GenericRecallPathPolicy = {},
+  source: GenericRecallPathSource = "filesystem",
+): boolean {
+  if (isExternalWikiQmdPath(filePath, source)) return true;
+  // A QMD transport hands back collection-qualified paths
+  // (`qmd://<collection>/activity/<date>.md`, or `<collection>/activity/…`),
+  // and the collection is not always one this policy knows: a caller may name
+  // a custom one, and global search spans every collection. The activity
+  // predicate is ROOT-AWARE — it matches only the top-level
+  // `activity/<date>.md` so a nested ordinary memory stays recallable — so an
+  // un-stripped prefix reads as a nested path and the digest would be served.
+  //
+  // Both spellings are therefore tested. Widening is safe in this direction
+  // and only here: a leading segment is dropped ONLY to re-test the dedicated
+  // surface shapes, never to decide anything else, and a segment that names a
+  // memory CATEGORY (`facts/proj/activity/…`) is never treated as a
+  // collection, so ordinary nested memories stay searchable.
+  for (const candidate of collectionSpellings(filePath, policy, source)) {
+    if (
+      isArtifactMemoryPath(candidate) ||
+      isNamespacedActivityDigestPath(candidate, policy.memoryDir) ||
+      isMeetingRecordPath(candidate)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * The activity check, applied against the NAMESPACE root a hit came from.
+ *
+ * `isActivityDigestPath` is root-aware — the digest must sit directly under
+ * the root it is given — but a namespaced search rewrites hits to absolute
+ * paths beneath `…/namespaces/<ns>/`, and only the global `memoryDir` is
+ * available here. Measured against that root, a real digest at
+ * `<memoryDir>/namespaces/team/activity/<date>.md` reads as nested and is
+ * served. Re-measuring against the namespace's own root closes that.
+ */
+function isNamespacedActivityDigestPath(candidate: string, memoryDir?: string): boolean {
+  if (isActivityDigestPath(candidate, memoryDir)) return true;
+  if (memoryDir === undefined || memoryDir.length === 0) return false;
+  const relative = path.relative(memoryDir, path.resolve(memoryDir, candidate));
+  const namespaced = /^namespaces[\\/]([^\\/]+)[\\/](.*)$/.exec(relative);
+  if (namespaced === null) return false;
+  return isActivityDigestPath(namespaced[2] ?? "", memoryDir);
+}
+
+/** A path as given, plus its form with a leading COLLECTION segment removed. */
+function collectionSpellings(
+  filePath: string,
+  policy: GenericRecallPathPolicy,
+  source: GenericRecallPathSource,
+): string[] {
+  if (path.isAbsolute(filePath)) return [filePath];
+  // A `qmd://<collection>/<path>` URI states its collection UNAMBIGUOUSLY in
+  // the authority, so the leading segment of its normalized form is never a
+  // memory category — strip it outright rather than guessing.
+  if (source === "qmd" && filePath.startsWith("qmd://")) {
+    const normalized = path.posix.normalize(normalizeQmdUriPath(filePath, source).replace(/\\/g, "/"));
+    const slashIndex = normalized.indexOf("/");
+    return slashIndex <= 0 || slashIndex >= normalized.length - 1
+      ? [normalized]
+      : [normalized, normalized.slice(slashIndex + 1)];
+  }
+  const normalized = path.posix.normalize(
+    normalizeQmdUriPath(filePath, source).replace(/\\/g, "/"),
+  );
+  const stripped = stripQmdCollectionPrefix(filePath, policy, source);
+  const spellings = [stripped];
+  // If the AUTHORITATIVE strip already fired — the prefix matched a configured
+  // collection — stop. Removing a second segment would take a real directory
+  // with it: `memories/projects/activity/<date>.md` would become
+  // `activity/<date>.md` and an ordinary nested memory would read as a
+  // top-level digest, vanishing from search AND recall.
+  if (stripped !== normalized) return spellings;
+  const slashIndex = stripped.indexOf("/");
+  if (slashIndex <= 0 || slashIndex >= stripped.length - 1) return spellings;
+  const prefix = stripped.slice(0, slashIndex);
+  // The CALLER's own collection is authoritative: a request for
+  // `collection: "facts"` means that segment is the collection, whatever it is
+  // also the name of. Otherwise a category-shaped prefix stays part of the
+  // path, so an ordinary `facts/proj/activity/<date>.md` memory is searchable.
+  const requested = policy.requestedCollection;
+  if (
+    prefix !== requested &&
+    (Object.hasOwn(CATEGORY_MEMORY_ROOTS, prefix) || Object.hasOwn(RESERVED_ARCHIVE_ROOTS, prefix))
+  ) {
+    return spellings;
+  }
+  spellings.push(stripped.slice(slashIndex + 1));
+  return spellings;
+}
+
 export function isGenericRecallExcludedPath(
   filePath: string,
   policy: GenericRecallPathPolicy = {},
   source: GenericRecallPathSource = "filesystem",
 ): boolean {
   return (
-    isExternalWikiQmdPath(filePath, source) ||
-    isArtifactMemoryPath(filePath) ||
-    isActivityDigestPath(filePath, policy.memoryDir) ||
-    isTopLevelArchivePath(filePath, policy, source) ||
-    isMeetingRecordPath(filePath)
+    isSearchExcludedPath(filePath, policy, source) ||
+    // Recall-only: archived memories are cold, but an explicit search is one
+    // of the surfaces they remain reachable through.
+    isTopLevelArchivePath(filePath, policy, source)
   );
 }