@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/consumers/openclaw-install.js

@@ -0,0 +1,326 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { version: packageVersion } = require('../package.json');
+
+const OPENCLAW_PLUGIN_ID = 'aquifer-memory';
+
+function nowStamp() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function uniqueBackupPath(filePath) {
+  const base = `${filePath}.bak-${nowStamp()}`;
+  if (!fs.existsSync(base)) return base;
+  for (let i = 1; i < 1000; i += 1) {
+    const candidate = `${base}-${i}`;
+    if (!fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Could not allocate unique backup path for ${filePath}`);
+}
+
+function valueFlag(flags = {}, name, fallback = null) {
+  const value = flags[name];
+  if (value === undefined || value === null || value === true || value === '') return fallback;
+  return String(value);
+}
+
+function resolveOpenClawHome(flags = {}, env = process.env) {
+  return path.resolve(valueFlag(flags, 'openclaw-home', env.OPENCLAW_HOME || path.join(os.homedir(), '.openclaw')));
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function writeJsonWithBackup(filePath, value, opts = {}) {
+  if (opts.dryRun) return null;
+  const backupPath = uniqueBackupPath(filePath);
+  if (fs.existsSync(filePath)) fs.copyFileSync(filePath, backupPath);
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  return backupPath;
+}
+
+function samePath(a, b) {
+  return path.resolve(a) === path.resolve(b);
+}
+
+function ensureOpenClawHome(openclawHome) {
+  if (!fs.existsSync(openclawHome) || !fs.statSync(openclawHome).isDirectory()) {
+    throw new Error(`OPENCLAW_HOME not found: ${openclawHome}`);
+  }
+}
+
+function ensureExtensionLink({ openclawHome, packageRoot, dryRun = false, force = false }) {
+  const source = path.join(packageRoot, 'consumers', 'openclaw-ext');
+  const dest = path.join(openclawHome, 'extensions', 'aquifer-memory');
+  if (!fs.existsSync(source)) throw new Error(`OpenClaw extension source not found: ${source}`);
+
+  const result = {
+    source,
+    dest,
+    action: 'link',
+    backupPath: null,
+  };
+
+  if (fs.existsSync(dest)) {
+    const stat = fs.lstatSync(dest);
+    if (stat.isSymbolicLink()) {
+      const target = fs.readlinkSync(dest);
+      const resolvedTarget = path.resolve(path.dirname(dest), target);
+      if (samePath(resolvedTarget, source)) {
+        return { ...result, action: 'already-linked' };
+      }
+    }
+
+    if (!force) {
+      throw new Error(`${dest} already exists; rerun with --force to move it aside and relink`);
+    }
+
+    result.backupPath = `${dest}.bak-${nowStamp()}`;
+    result.action = 'replace-link';
+    if (!dryRun) fs.renameSync(dest, result.backupPath);
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.symlinkSync(source, dest, 'dir');
+  }
+  return result;
+}
+
+function normalizeMcpServer(existing = {}, packageRoot) {
+  return {
+    ...existing,
+    command: 'node',
+    args: [path.join(packageRoot, 'consumers', 'mcp.js')],
+    env: {
+      ...(existing.env && typeof existing.env === 'object' ? existing.env : {}),
+    },
+  };
+}
+
+function ensureMcpConfig({ openclawHome, packageRoot, dryRun = false }) {
+  const configPath = path.join(openclawHome, 'openclaw.json');
+  const mcpPath = path.join(packageRoot, 'consumers', 'mcp.js');
+  const result = {
+    configPath,
+    mcpPath,
+    action: 'skipped',
+    backupPath: null,
+    previousArgs: null,
+    nextArgs: [mcpPath],
+  };
+
+  if (!fs.existsSync(configPath)) {
+    return { ...result, reason: 'openclaw.json not found' };
+  }
+
+  const config = readJson(configPath);
+  const existing = config.mcp?.servers?.aquifer || {};
+  result.previousArgs = Array.isArray(existing.args) ? existing.args : null;
+
+  const nextServer = normalizeMcpServer(existing, packageRoot);
+  const previousText = JSON.stringify(existing);
+  const nextText = JSON.stringify(nextServer);
+  if (previousText === nextText) {
+    return { ...result, action: 'already-configured' };
+  }
+
+  config.mcp = config.mcp && typeof config.mcp === 'object' ? config.mcp : {};
+  config.mcp.servers = config.mcp.servers && typeof config.mcp.servers === 'object'
+    ? config.mcp.servers
+    : {};
+  config.mcp.servers.aquifer = nextServer;
+  result.action = 'write-config';
+  result.backupPath = writeJsonWithBackup(configPath, config, { dryRun });
+  return result;
+}
+
+function normalizePluginEntry(existing = {}) {
+  const entry = existing && typeof existing === 'object' ? existing : {};
+  return {
+    ...entry,
+    enabled: true,
+    config: entry.config && typeof entry.config === 'object' ? entry.config : {},
+  };
+}
+
+function ensurePluginConfig({ openclawHome, extensionPath, dryRun = false }) {
+  const configPath = path.join(openclawHome, 'openclaw.json');
+  const result = {
+    configPath,
+    pluginId: OPENCLAW_PLUGIN_ID,
+    extensionPath,
+    action: 'skipped',
+    backupPath: null,
+    previousLoadPaths: null,
+    nextLoadPaths: null,
+  };
+
+  if (!fs.existsSync(configPath)) {
+    return { ...result, reason: 'openclaw.json not found' };
+  }
+
+  const config = readJson(configPath);
+  const plugins = config.plugins && typeof config.plugins === 'object' ? config.plugins : {};
+  const load = plugins.load && typeof plugins.load === 'object' ? plugins.load : {};
+  const previousLoadPaths = Array.isArray(load.paths) ? load.paths : [];
+  const nextLoadPaths = previousLoadPaths.includes(extensionPath)
+    ? previousLoadPaths
+    : [...previousLoadPaths, extensionPath];
+  const entries = plugins.entries && typeof plugins.entries === 'object' ? plugins.entries : {};
+  const previousEntry = entries[OPENCLAW_PLUGIN_ID];
+  const nextEntry = normalizePluginEntry(previousEntry);
+  const previousAllow = Array.isArray(plugins.allow) ? plugins.allow : null;
+  const nextAllow = previousAllow && !previousAllow.includes(OPENCLAW_PLUGIN_ID)
+    ? [...previousAllow, OPENCLAW_PLUGIN_ID]
+    : previousAllow;
+
+  result.previousLoadPaths = previousLoadPaths;
+  result.nextLoadPaths = nextLoadPaths;
+
+  const unchanged = JSON.stringify(previousLoadPaths) === JSON.stringify(nextLoadPaths)
+    && JSON.stringify(previousEntry) === JSON.stringify(nextEntry)
+    && JSON.stringify(previousAllow) === JSON.stringify(nextAllow);
+  if (unchanged) {
+    return { ...result, action: 'already-configured' };
+  }
+
+  config.plugins = {
+    ...plugins,
+    entries: {
+      ...entries,
+      [OPENCLAW_PLUGIN_ID]: nextEntry,
+    },
+    load: {
+      ...load,
+      paths: nextLoadPaths,
+    },
+  };
+  if (nextAllow) config.plugins.allow = nextAllow;
+
+  result.action = 'write-config';
+  result.backupPath = writeJsonWithBackup(configPath, config, { dryRun });
+  return result;
+}
+
+function inspectInstalledPackage(openclawHome) {
+  const packagePath = path.join(openclawHome, 'node_modules', '@shadowforge0', 'aquifer-memory', 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return { packagePath, installed: false, version: null };
+  }
+  const pkg = readJson(packagePath);
+  return { packagePath, installed: true, version: pkg.version || null };
+}
+
+function buildInstallReport(args = {}, opts = {}) {
+  const flags = args.flags || {};
+  const env = opts.env || process.env;
+  const openclawHome = resolveOpenClawHome(flags, env);
+  const packageRoot = opts.packageRoot || path.resolve(__dirname, '..');
+  const dryRun = flags['dry-run'] === true;
+  const force = flags.force === true;
+  const linkCurrentPackage = flags['link-current-package'] === true;
+  const skipExtension = flags['skip-extension'] === true;
+  const skipMcp = flags['skip-mcp'] === true;
+
+  ensureOpenClawHome(openclawHome);
+
+  const installedPackage = inspectInstalledPackage(openclawHome);
+  const expectedPackageRoot = path.join(openclawHome, 'node_modules', '@shadowforge0', 'aquifer-memory');
+  const targetPackageRoot = linkCurrentPackage || !installedPackage.installed
+    ? packageRoot
+    : expectedPackageRoot;
+  const report = {
+    ok: true,
+    dryRun,
+    openclawHome,
+    packageRoot,
+    targetPackageRoot,
+    linkCurrentPackage,
+    packageVersion,
+    expectedPackageRoot,
+    installedPackage,
+    extension: skipExtension ? { action: 'skipped', reason: '--skip-extension' } : null,
+    plugin: skipExtension ? { action: 'skipped', reason: '--skip-extension' } : null,
+    mcp: skipMcp ? { action: 'skipped', reason: '--skip-mcp' } : null,
+    warnings: [],
+  };
+
+  if (installedPackage.installed && installedPackage.version && installedPackage.version !== packageVersion) {
+    report.warnings.push(
+      `OpenClaw node_modules has @shadowforge0/aquifer-memory ${installedPackage.version}; installer package is ${packageVersion}.`
+    );
+  }
+  if (!samePath(targetPackageRoot, expectedPackageRoot)) {
+    report.warnings.push(
+      `MCP will point outside OpenClaw node_modules: ${targetPackageRoot}. For a durable package install, run npm install --prefix "${openclawHome}" @shadowforge0/aquifer-memory@${packageVersion}.`
+    );
+  }
+  if (!samePath(packageRoot, expectedPackageRoot) && samePath(targetPackageRoot, expectedPackageRoot)) {
+    report.warnings.push(
+      `Installer is running from ${packageRoot}, but durable OpenClaw wiring targets ${expectedPackageRoot}. Use --link-current-package only for source-checkout development.`
+    );
+  }
+
+  if (!skipExtension) {
+    report.extension = ensureExtensionLink({ openclawHome, packageRoot: targetPackageRoot, dryRun, force });
+    report.plugin = ensurePluginConfig({
+      openclawHome,
+      extensionPath: report.extension.dest,
+      dryRun,
+    });
+  }
+
+  if (!skipMcp) {
+    report.mcp = ensureMcpConfig({ openclawHome, packageRoot: targetPackageRoot, dryRun });
+  }
+
+  return report;
+}
+
+function formatInstallReport(report) {
+  const lines = [];
+  lines.push(`Aquifer package: ${report.packageVersion} at ${report.packageRoot}`);
+  if (report.installedPackage.installed) {
+    lines.push(`OpenClaw package: ${report.installedPackage.version} at ${report.installedPackage.packagePath}`);
+  } else {
+    lines.push(`OpenClaw package: not installed at ${report.installedPackage.packagePath}`);
+  }
+  lines.push(`Extension: ${report.extension.action}${report.extension.dest ? ` (${report.extension.dest})` : ''}`);
+  if (report.extension.backupPath) lines.push(`Extension backup: ${report.extension.backupPath}`);
+  lines.push(`Plugin config: ${report.plugin.action}${report.plugin.configPath ? ` (${report.plugin.configPath})` : ''}`);
+  if (report.plugin.backupPath) lines.push(`Plugin config backup: ${report.plugin.backupPath}`);
+  if (report.plugin.reason) lines.push(`Plugin config note: ${report.plugin.reason}`);
+  lines.push(`MCP config: ${report.mcp.action}${report.mcp.configPath ? ` (${report.mcp.configPath})` : ''}`);
+  if (report.mcp.backupPath) lines.push(`MCP config backup: ${report.mcp.backupPath}`);
+  if (report.mcp.reason) lines.push(`MCP config note: ${report.mcp.reason}`);
+  for (const warning of report.warnings) lines.push(`Warning: ${warning}`);
+  if (report.dryRun) lines.push('Dry run: no files were changed.');
+  return lines.join('\n');
+}
+
+async function cmdInstallOpenClaw(args = {}, opts = {}) {
+  const report = buildInstallReport(args, opts);
+  if (args.flags?.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatInstallReport(report));
+  }
+  return report;
+}
+
+module.exports = {
+  buildInstallReport,
+  cmdInstallOpenClaw,
+  ensureExtensionLink,
+  ensurePluginConfig,
+  ensureMcpConfig,
+  formatInstallReport,
+  inspectInstalledPackage,
+  normalizeMcpServer,
+  resolveOpenClawHome,
+};

package/consumers/openclaw-plugin.js

@@ -4,12 +4,14 @@
  * Aquifer Memory — OpenClaw Host Adapter
  *
  * Ingest adapter: auto-captures sessions on before_reset.
- * Tool adapter: exposes session_recall/session_feedback via OpenClaw registerTool().
+ * Tool adapter: exposes product status and recall/feedback tools via OpenClaw
+ * registerTool().
  *
  * Status: COMPATIBILITY ONLY. The official tool delivery path is mcp.servers.aquifer
  * (see consumers/mcp.js). registerTool() exposure has OpenClaw upstream limitations
- * that prevent reliable tool visibility. This plugin is retained for before_reset
- * session capture; tool registration code is kept for future upstream fixes.
+ * that can affect tool visibility on some hosts. This plugin is retained for
+ * before_reset session capture; tool registration follows the same product
+ * status surface as the CLI and MCP server.
  *
  * Install: add to openclaw.json plugins or extensions directory.
  * Config via plugin config, environment variables, or aquifer.config.json.
@@ -18,6 +20,8 @@
 const { createAquiferFromConfig } = require('./shared/factory');
 const { runIngest } = require('./shared/ingest');
 const { formatRecallResults: sharedFormatRecallResults } = require('./shared/recall-format');
+const { registerOpenClawProductStatusTools } = require('./shared/openclaw-product-tools');
+const { buildCompatibilityRecallRequest, runCompatibilityRecall } = require('./shared/compat-recall');
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -33,6 +37,43 @@ function coerceRawEntries(messages) {
   });
 }
 
+function normalizeTimestamp(value) {
+  if (value === null || value === undefined || value === '') return null;
+
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return Number.isFinite(time) ? value.toISOString() : null;
+  }
+
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) return null;
+    const millis = Math.abs(value) < 1e12 ? value * 1000 : value;
+    const date = new Date(millis);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed) return null;
+    if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) {
+      return normalizeTimestamp(Number(trimmed));
+    }
+    const parsed = Date.parse(trimmed);
+    if (!Number.isFinite(parsed)) return null;
+    return new Date(parsed).toISOString();
+  }
+
+  return null;
+}
+
+function selectTimestamp(...values) {
+  for (const value of values) {
+    const ts = normalizeTimestamp(value);
+    if (ts) return ts;
+  }
+  return null;
+}
+
 function normalizeEntries(rawEntries) {
   const normalized = [];
   let userCount = 0, assistantCount = 0;
@@ -43,7 +84,7 @@ function normalizeEntries(rawEntries) {
     if (!entry) continue;
     const msg = entry.message || entry;
     if (!msg || !msg.role) continue;
-    if (!['user', 'assistant', 'system'].includes(msg.role)) continue;
+    if (!['user', 'assistant'].includes(msg.role)) continue;
 
     let content = '';
     if (typeof msg.content === 'string') {
@@ -55,7 +96,7 @@ function normalizeEntries(rawEntries) {
         .join('\n');
     }
 
-    const ts = entry.timestamp || msg.timestamp || null;
+    const ts = selectTimestamp(entry.timestamp, msg.timestamp);
     if (ts && !startedAt) startedAt = ts;
     if (ts) lastMessageAt = ts;
 
@@ -117,18 +158,62 @@ module.exports = buildPlugin();
 // contract; OpenClaw reads { id, name, register } only.
 module.exports.normalizeEntries = normalizeEntries;
 module.exports.coerceRawEntries = coerceRawEntries;
+module.exports.normalizeTimestamp = normalizeTimestamp;
+
+function runPersonaMount(api, persona, pluginConfig) {
+  if (!api || typeof api.registerTool !== 'function') {
+    return {
+      mounted: persona.mountOnOpenClaw(api, pluginConfig) || {},
+      registeredTools: new Set(),
+    };
+  }
+
+  const registeredTools = new Set();
+  const originalRegisterTool = api.registerTool;
+  api.registerTool = function trackedRegisterTool(factory, opts) {
+    if (opts?.name) registeredTools.add(opts.name);
+    return originalRegisterTool.call(this, factory, opts);
+  };
+
+  try {
+    return {
+      mounted: persona.mountOnOpenClaw(api, pluginConfig) || {},
+      registeredTools,
+    };
+  } finally {
+    api.registerTool = originalRegisterTool;
+  }
+}
+
+function registerProductStatusAfterPersona(api, pluginConfig, mounted, registeredTools) {
+  if (registeredTools.has('memory_stats') && registeredTools.has('memory_pending')) return true;
+
+  let aquifer = mounted.aquifer || null;
+  if (!aquifer) {
+    try {
+      aquifer = createAquiferFromConfig(pluginConfig);
+    } catch (err) {
+      api.logger.warn(`[aquifer-memory] product status tools unavailable after persona mount: ${err.message}`);
+      return false;
+    }
+  }
+
+  registerOpenClawProductStatusTools(api, aquifer, { skipTools: registeredTools });
+  return true;
+}
 
 function register(api) {
     const pluginConfig = api.pluginConfig || {};
 
     // v1.2.0: delegate to a persona layer if one is configured, otherwise
-    // run the generic default path (before_reset + session_recall + feedback).
+    // run the generic default path.
     const personaPath = pluginConfig.persona || process.env.AQUIFER_PERSONA;
     if (personaPath) {
       try {
         const persona = require(personaPath);
         if (persona && typeof persona.mountOnOpenClaw === 'function') {
-          persona.mountOnOpenClaw(api, pluginConfig);
+          const { mounted, registeredTools } = runPersonaMount(api, persona, pluginConfig);
+          registerProductStatusAfterPersona(api, pluginConfig, mounted, registeredTools);
           api.logger.info(`[aquifer-memory] registered via persona: ${personaPath}`);
           return;
         }
@@ -194,6 +279,10 @@ function register(api) {
       })();
     });
 
+    // --- product status tools ---
+
+    registerOpenClawProductStatusTools(api, aquifer);
+
     // --- session_recall tool ---
 
     api.registerTool((ctx) => {
@@ -211,31 +300,23 @@ function register(api) {
             source: { type: 'string', description: 'Filter by source' },
             dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
             dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+            host: { type: 'string', description: 'Audit boundary host filter' },
+            sessionId: { type: 'string', description: 'Audit boundary session id filter' },
             entities: { type: 'array', items: { type: 'string' }, description: 'Entity names to match' },
             entityMode: { type: 'string', enum: ['any', 'all'], description: '"any" (default, boost) or "all" (only sessions with every entity)' },
             mode: { type: 'string', enum: ['fts', 'hybrid', 'vector'], description: 'Recall mode: "fts" (keyword only), "hybrid" (default), "vector" (vector only)' },
             explain: { type: 'boolean', description: 'Include per-result score breakdown (diagnostic)' },
+            activeScopeKey: { type: 'string', description: 'Active curated memory scope key' },
+            activeScopePath: { type: 'array', items: { type: 'string' }, description: 'Ordered curated scope path' },
           },
           required: ['query'],
         },
         async execute(_toolCallId, params) {
           try {
-            const limit = Math.max(1, Math.min(20, parseInt(params?.limit ?? 5, 10) || 5));
-            const recallOpts = {
-              limit,
-              agentId: params.agentId || undefined,
-              source: params.source || undefined,
-              dateFrom: params.dateFrom || undefined,
-              dateTo: params.dateTo || undefined,
-            };
-            if (Array.isArray(params.entities) && params.entities.length > 0) {
-              recallOpts.entities = params.entities;
-              recallOpts.entityMode = params.entityMode || 'any';
-            }
-            if (params.mode) recallOpts.mode = params.mode;
-
-            const results = await aquifer.recall(params.query, recallOpts);
-            const text = formatRecallResults(results, { showScore: true, showExplain: !!params.explain });
+            const request = buildCompatibilityRecallRequest(aquifer, params, ctx || {});
+            const results = await runCompatibilityRecall(aquifer, params.query, request);
+            const formatted = formatRecallResults(results, { showScore: true, showExplain: !!params.explain });
+            const text = [request.laneHeader, '', formatted].join('\n');
             return { content: [{ type: 'text', text }] };
           } catch (err) {
             return {
@@ -325,5 +406,5 @@ function register(api) {
       };
     }, { name: 'feedback_stats' });
 
-  api.logger.info('[aquifer-memory] registered (before_reset + session_recall + session_feedback + feedback_stats)');
+  api.logger.info('[aquifer-memory] registered (before_reset + memory_stats + memory_pending + session_recall + session_feedback + feedback_stats)');
 }

package/consumers/shared/compat-recall.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const VALID_RECALL_MODES = new Set(['fts', 'hybrid', 'vector']);
+
+function getConfig(aquifer) {
+  return aquifer && typeof aquifer.getConfig === 'function' ? (aquifer.getConfig() || {}) : {};
+}
+
+function memoryServingMode(aquifer) {
+  const config = getConfig(aquifer);
+  return config.memoryServingMode || config.serving?.mode || 'legacy';
+}
+
+function firstDefined(...values) {
+  return values.find(value => value !== undefined && value !== null && value !== '');
+}
+
+function clampLimit(value, fallback = 5) {
+  return Math.max(1, Math.min(20, parseInt(value ?? fallback, 10) || fallback));
+}
+
+function parseScopePath(value) {
+  if (Array.isArray(value)) return value.map(item => String(item || '').trim()).filter(Boolean);
+  if (typeof value !== 'string') return undefined;
+  const parts = value.split(',').map(item => item.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : undefined;
+}
+
+function hasLegacyBoundary(opts = {}) {
+  return Boolean(opts.agentId || opts.source || opts.dateFrom || opts.dateTo || opts.host || opts.sessionId);
+}
+
+function buildCompatibilityRecallRequest(aquifer, params = {}, ctx = {}) {
+  const limit = clampLimit(params.limit);
+  const mode = memoryServingMode(aquifer);
+  const recallOpts = { limit };
+  const requestedMode = params.mode;
+  if (VALID_RECALL_MODES.has(requestedMode)) recallOpts.mode = requestedMode;
+
+  if (mode === 'curated') {
+    const activeScopeKey = firstDefined(params.activeScopeKey, params.active_scope_key);
+    const activeScopePath = firstDefined(params.activeScopePath, params.active_scope_path);
+    if (activeScopeKey) recallOpts.activeScopeKey = activeScopeKey;
+    const scopePath = parseScopePath(activeScopePath);
+    if (scopePath) recallOpts.activeScopePath = scopePath;
+    return {
+      mode,
+      method: 'recall',
+      recallOpts,
+      laneHeader: 'Current memory recall (curated lane).',
+      hasBoundary: true,
+    };
+  }
+
+  const agentId = firstDefined(params.agentId, params.agent_id, ctx.agentId);
+  if (agentId) recallOpts.agentId = agentId;
+  const source = firstDefined(params.source);
+  if (source) recallOpts.source = source;
+  const dateFrom = firstDefined(params.dateFrom, params.date_from);
+  if (dateFrom) recallOpts.dateFrom = dateFrom;
+  const dateTo = firstDefined(params.dateTo, params.date_to);
+  if (dateTo) recallOpts.dateTo = dateTo;
+  const host = firstDefined(params.host);
+  if (host) recallOpts.host = host;
+  const sessionId = firstDefined(params.sessionId, params.session_id);
+  if (sessionId) recallOpts.sessionId = sessionId;
+
+  const entities = Array.isArray(params.entities)
+    ? params.entities.map(item => String(item || '').trim()).filter(Boolean)
+    : [];
+  if (entities.length > 0) {
+    recallOpts.entities = entities;
+    recallOpts.entityMode = firstDefined(params.entityMode, params.entity_mode) || 'any';
+  }
+
+  return {
+    mode,
+    method: 'evidenceRecall',
+    recallOpts,
+    laneHeader: 'Historical/session recall (legacy evidence lane; not current memory).',
+    hasBoundary: hasLegacyBoundary(recallOpts),
+  };
+}
+
+async function runCompatibilityRecall(aquifer, query, request = {}) {
+  if (request.method === 'evidenceRecall') {
+    if (!request.hasBoundary) {
+      throw new Error('legacy session_recall requires a boundary filter (agentId, source, dateFrom/dateTo, host, or sessionId). Use MCP memory_recall for current memory.');
+    }
+    if (aquifer && typeof aquifer.evidenceRecall === 'function') {
+      return aquifer.evidenceRecall(query, request.recallOpts);
+    }
+  }
+  return aquifer.recall(query, request.recallOpts);
+}
+
+module.exports = {
+  buildCompatibilityRecallRequest,
+  runCompatibilityRecall,
+  memoryServingMode,
+};

package/consumers/shared/config.js

@@ -55,6 +55,7 @@ const DEFAULTS = {
     servingMode: 'legacy',   // 'legacy' | 'curated'
     activeScopeKey: null,
     activeScopePath: null,
+    allowedScopeKeys: null,
   },
   codex: {
     checkpoint: {
@@ -120,6 +121,7 @@ const ENV_MAP = [
   ['AQUIFER_MEMORY_SERVING_MODE', 'memory.servingMode'],
   ['AQUIFER_MEMORY_ACTIVE_SCOPE_KEY', 'memory.activeScopeKey'],
   ['AQUIFER_MEMORY_ACTIVE_SCOPE_PATH', 'memory.activeScopePath'],
+  ['AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS', 'memory.allowedScopeKeys'],
   ['AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MS', 'codex.checkpoint.checkIntervalMs', Number],
   ['AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES', 'codex.checkpoint.checkIntervalMinutes', Number],
   ['AQUIFER_CODEX_CHECKPOINT_EVERY_MESSAGES', 'codex.checkpoint.everyMessages', Number],