feat(memory): add operator retrieval plugin

packages/memory/src/operator-memory-plugin.ts

@@ -1,5 +1,7 @@
 import type { Insight, InsightSearchResult, MemoryAdapter } from './types.js';
 
+const STARTUP_CONTEXT_CANDIDATE_LIMIT = 64;
+
 /** Immutable server-derived boundary; callers never choose an adapter namespace. */
 export interface OperatorMemoryScope {
   readonly tenantId: string;
@@ -38,8 +40,44 @@ export interface OperatorMemoryPlugin {
 }
 
 function scopedUserId(scope: OperatorMemoryScope, namespace: string): string {
+  const normalizedScope = normalizeScope(scope);
   // JSON tuple encoding avoids delimiter collisions between independently scoped IDs.
-  return JSON.stringify([namespace, scope.tenantId, scope.ownerId, scope.sessionId]);
+  return JSON.stringify([
+    namespace,
+    normalizedScope.tenantId,
+    normalizedScope.ownerId,
+    normalizedScope.sessionId,
+  ]);
+}
+
+function normalizeScope(scope: OperatorMemoryScope): OperatorMemoryScope {
+  if (typeof scope !== 'object' || scope === null) {
+    throw new Error('Operator memory scope is required');
+  }
+  return Object.freeze({
+    tenantId: requiredScopeId(scope.tenantId, 'tenant ID'),
+    ownerId: requiredScopeId(scope.ownerId, 'owner ID'),
+    sessionId: requiredScopeId(scope.sessionId, 'session ID'),
+  });
+}
+
+function requiredScopeId(value: unknown, field: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`Operator memory ${field} is required`);
+  }
+  return value.trim();
+}
+
+function compareStartupContext(left: OperatorMemoryResult, right: OperatorMemoryResult): number {
+  return (
+    startupSourcePriority(left.provenance.source) - startupSourcePriority(right.provenance.source)
+  );
+}
+
+function startupSourcePriority(source: string): number {
+  if (source === 'project') return 0;
+  if (source === 'flat-file') return 1;
+  return 2;
 }
 
 function normalizeConfig(config: OperatorMemoryConfig): OperatorMemoryConfig {
@@ -82,7 +120,7 @@ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): Operat
     ).map(mapResult);
   return {
     async capture(scope, input) {
-      return config.adapter.storeInsight({
+      return pluginConfig.adapter.storeInsight({
         userId: scopedUserId(scope, pluginConfig.namespace),
         content: pluginConfig.redact(input.content),
         source: input.source,
@@ -106,7 +144,11 @@ export function createOperatorMemoryPlugin(config: OperatorMemoryConfig): Operat
       };
     },
     async startupContext(scope) {
-      return search(scope, '*', pluginConfig.maxStartupContext);
+      const maxStartupContext = pluginConfig.maxStartupContext ?? 8;
+      // Prioritize authoritative sources within a bounded candidate window.
+      const candidateLimit = Math.max(maxStartupContext, STARTUP_CONTEXT_CANDIDATE_LIMIT);
+      const context = await search(scope, '*', candidateLimit);
+      return [...context].sort(compareStartupContext).slice(0, maxStartupContext);
     },
   };
 }