@shadowforge0/aquifer-memory 1.9.0 → 1.9.1

package/consumers/mcp.js

@@ -21,6 +21,12 @@
 
 const { createAquiferFromConfig } = require('./shared/factory');
 const { version: packageVersion } = require('../package.json');
+const {
+  formatMemoryStatsInterface,
+  formatPendingRowsInterface,
+  formatPendingWorkInterface,
+} = require('../core/interface');
+const { MCP_TOOL_MANIFEST } = require('../core/mcp-manifest');
 
 let _aquifer = null;
 
@@ -29,6 +35,19 @@ function getAquifer() {
   return _aquifer;
 }
 
+function manifestToolDescription(name, fallback) {
+  return MCP_TOOL_MANIFEST.find(tool => tool.name === name)?.description || fallback;
+}
+
+function pendingSessionOpts(params = {}) {
+  return {
+    limit: params.limit ?? 20,
+    source: params.source || undefined,
+    agentId: params.agentId || undefined,
+    status: params.status || undefined,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Format recall results as readable text
 // ---------------------------------------------------------------------------
@@ -65,6 +84,10 @@ function historicalRecallLaneHeader() {
   return 'Serving lane: explicit historical/session recall';
 }
 
+function countEnvelopeList(value) {
+  return Array.isArray(value) ? value.length : 0;
+}
+
 // ---------------------------------------------------------------------------
 // Start MCP server
 // ---------------------------------------------------------------------------
@@ -137,6 +160,8 @@ async function main() {
       source: z.string().optional().describe('Filter by source (e.g., gateway, cc)'),
       dateFrom: z.string().optional().describe('Start date YYYY-MM-DD'),
       dateTo: z.string().optional().describe('End date YYYY-MM-DD'),
+      host: z.string().optional().describe('Audit boundary host filter'),
+      sessionId: z.string().optional().describe('Audit boundary session ID filter'),
       entities: z.array(z.string()).optional().describe('Entity names to match'),
       entityMode: z.enum(['any', 'all']).optional().describe('"any" (default, boost) or "all" (only sessions with every entity)'),
       mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)'),
@@ -151,6 +176,8 @@ async function main() {
           source: params.source || undefined,
           dateFrom: params.dateFrom || undefined,
           dateTo: params.dateTo || undefined,
+          host: params.host || undefined,
+          sessionId: params.sessionId || undefined,
         };
         if (params.entities && params.entities.length > 0) {
           recallOpts.entities = params.entities;
@@ -374,45 +401,16 @@ async function main() {
 
   server.tool(
     'memory_stats',
-    'Return storage statistics for the Aquifer memory store, serving mode, current-memory record coverage, and session date range.',
-    {},
-    async () => {
+    manifestToolDescription('memory_stats', 'Return Aquifer product status.'),
+    {
+      diagnostics: z.boolean().optional().describe('Include raw storage counters and serving diagnostics. Default false.'),
+    },
+    async (params = {}) => {
       try {
         const aquifer = getAquifer();
         const stats = await aquifer.getStats();
-        const lines = [
-          `Backend: ${stats.backendKind || 'unknown'} (${stats.backendProfile || 'unknown'})`,
-          `Serving mode: ${stats.serving?.mode || 'legacy'}`,
-          `Active scope: ${stats.serving?.activeScopePath?.join(' > ') || stats.serving?.activeScopeKey || 'none'}`,
-          `Sessions: ${stats.sessionTotal} total`,
-        ];
-        for (const [status, count] of Object.entries(stats.sessions)) {
-          lines.push(`  ${status}: ${count}`);
-        }
-        if (stats.pendingSessions?.available) {
-          lines.push(`Actionable pending/failed: ${stats.pendingSessions.total}`);
-        }
-        lines.push(`Summaries: ${stats.summaries}`);
-        lines.push(`Turn embeddings: ${stats.turnEmbeddings}`);
-        lines.push(`Entities: ${stats.entities}`);
-        if (stats.memoryRecords) {
-          lines.push(`Memory records: ${stats.memoryRecords.total} total (${stats.memoryRecords.active} active, ${stats.memoryRecords.visibleInRecall} recall-visible, ${stats.memoryRecords.visibleInBootstrap} bootstrap-visible)`);
-          if (stats.memoryRecords.latest) lines.push(`Memory record range: ${new Date(stats.memoryRecords.earliest).toISOString().slice(0, 10)} → ${new Date(stats.memoryRecords.latest).toISOString().slice(0, 10)}`);
-        }
-        if (stats.sessionFinalizations?.available) {
-          const statusText = Object.entries(stats.sessionFinalizations.statuses || {})
-            .map(([status, count]) => `${status}: ${count}`)
-            .join(', ') || 'none';
-          lines.push(`Session finalizations: ${stats.sessionFinalizations.total} total (${statusText})`);
-          if (stats.sessionFinalizations.latestFinalizedAt) {
-            lines.push(`Latest finalization: ${new Date(stats.sessionFinalizations.latestFinalizedAt).toISOString().slice(0, 10)}`);
-          }
-        }
-        if (stats.earliest) lines.push(`Date range: ${new Date(stats.earliest).toISOString().slice(0, 10)} → ${new Date(stats.latest).toISOString().slice(0, 10)}`);
-        if ((stats.serving?.mode || 'legacy') !== 'curated') {
-          lines.push('Warning: legacy serving returns session/evidence material; configure curated serving with an active scope for current-memory answers.');
-        }
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
+        const text = formatMemoryStatsInterface(stats, { diagnostics: params.diagnostics === true });
+        return { content: [{ type: 'text', text }] };
       } catch (err) {
         return {
           content: [{ type: 'text', text: `memory_stats error: ${err.message}` }],
@@ -424,22 +422,31 @@ async function main() {
 
   server.tool(
     'memory_pending',
-    'List sessions with pending or failed processing status.',
+    manifestToolDescription('memory_pending', 'Return saved-content preparation status.'),
     {
       limit: z.number().int().min(1).max(200).optional().describe('Max results (default 20)'),
+      source: z.string().optional().describe('Filter by source'),
+      agentId: z.string().optional().describe('Filter by agent ID'),
+      status: z.enum(['pending', 'failed']).optional().describe('Filter by processing status'),
+      diagnostics: z.boolean().optional().describe('Include source/agent/status buckets, guidance, and samples. Default false.'),
     },
     async (params) => {
       try {
         const aquifer = getAquifer();
-        const rows = await aquifer.getPendingSessions({ limit: params.limit ?? 20 });
-        if (rows.length === 0) {
-          return { content: [{ type: 'text', text: 'No pending or failed sessions.' }] };
-        }
-        const lines = [`${rows.length} pending/failed session(s):\n`];
-        for (const row of rows) {
-          lines.push(`${row.session_id}  [${row.processing_status}]  agent=${row.agent_id}`);
+        const queryOpts = pendingSessionOpts(params);
+        const report = typeof aquifer.getPendingWork === 'function'
+          ? await aquifer.getPendingWork(queryOpts)
+          : null;
+        if (report) {
+          const text = formatPendingWorkInterface(report, {
+            diagnostics: params.diagnostics === true,
+            includePlan: false,
+          });
+          return { content: [{ type: 'text', text }] };
         }
-        return { content: [{ type: 'text', text: lines.join('\n') }] };
+        const rows = await aquifer.getPendingSessions(queryOpts);
+        const text = formatPendingRowsInterface(rows, { diagnostics: params.diagnostics === true });
+        return { content: [{ type: 'text', text }] };
       } catch (err) {
         return {
           content: [{ type: 'text', text: `memory_pending error: ${err.message}` }],
@@ -499,16 +506,16 @@ async function main() {
   if (!envelope.ready) {
     const err = envelope.error || { code: 'AQ_MIGRATION_NOT_READY', message: 'aquifer.init() did not reach ready state' };
     process.stderr.write(
-      `[aquifer-mcp] startup aborted: migrationMode=${envelope.migrationMode} ` +
-      `memoryMode=${envelope.memoryMode} pending=${envelope.pendingMigrations.length} ` +
+      `[aquifer-mcp] startup aborted: migrationMode=${envelope.migrationMode || 'unknown'} ` +
+      `memoryMode=${envelope.memoryMode || 'unknown'} pending=${countEnvelopeList(envelope.pendingMigrations)} ` +
       `error=${err.code || 'unknown'}: ${err.message}\n`
     );
     await aquifer.close().catch(() => {});
     process.exit(1);
   }
   process.stderr.write(
-    `[aquifer-mcp] init ok: mode=${envelope.migrationMode} applied=${envelope.appliedMigrations.length} ` +
-    `pending=${envelope.pendingMigrations.length} durationMs=${envelope.durationMs}\n`
+    `[aquifer-mcp] init ok: mode=${envelope.migrationMode || 'unknown'} applied=${countEnvelopeList(envelope.appliedMigrations)} ` +
+    `pending=${countEnvelopeList(envelope.pendingMigrations)} durationMs=${envelope.durationMs ?? 0}\n`
   );
 
   const transport = new StdioServerTransport();

package/consumers/openclaw-ext/index.js

@@ -13,7 +13,7 @@
 //   - Delegates to consumers/openclaw-plugin.js. If AQUIFER_PERSONA is set
 //     (pluginConfig.persona or env), the plugin loads the persona module
 //     and hands off mountOnOpenClaw(api); otherwise the default generic
-//     path runs (before_reset capture + session_recall + session_feedback).
+//     path runs (before_reset capture + product status, recall, and feedback tools).
 //
 // Host-specific customization goes in a persona module, not here.
 

package/consumers/openclaw-ext/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "aquifer-memory",
   "name": "Aquifer Memory",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "description": "Session ingest + recall + feedback. Reads DATABASE_URL / EMBED_PROVIDER / AQUIFER_LLM_PROVIDER from host env; delegates to AQUIFER_PERSONA module if set.",
   "main": "index.js",
   "hooks": ["before_reset"],

package/consumers/openclaw-ext/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aquifer-openclaw-ext",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "private": true,
   "main": "index.js",
   "description": "Drop-in OpenClaw extension for Aquifer Memory. Symlink into $OPENCLAW_HOME/extensions/aquifer-memory/ — no host-side boilerplate required.",

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
@@ -80,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') {
@@ -156,17 +160,60 @@ 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;
         }
@@ -232,6 +279,10 @@ function register(api) {
       })();
     });
 
+    // --- product status tools ---
+
+    registerOpenClawProductStatusTools(api, aquifer);
+
     // --- session_recall tool ---
 
     api.registerTool((ctx) => {
@@ -249,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 {
@@ -363,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/openclaw-product-tools.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const {
+  formatMemoryStatsInterface,
+  formatPendingRowsInterface,
+  formatPendingWorkInterface,
+} = require('../../core/interface');
+const { MCP_TOOL_MANIFEST } = require('../../core/mcp-manifest');
+
+function manifestToolDescription(name, fallback) {
+  return MCP_TOOL_MANIFEST.find(tool => tool.name === name)?.description || fallback;
+}
+
+function clampLimit(value, fallback = 20, max = 200) {
+  const parsed = parseInt(value ?? fallback, 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(1, Math.min(max, parsed));
+}
+
+function pendingSessionOpts(params = {}) {
+  return {
+    limit: clampLimit(params.limit, 20, 200),
+    source: params.source || undefined,
+    agentId: params.agentId || params.agent_id || undefined,
+    status: params.status || undefined,
+  };
+}
+
+function normalizeSkipTools(value) {
+  if (!value) return new Set();
+  if (value instanceof Set) return value;
+  if (Array.isArray(value)) return new Set(value);
+  return new Set();
+}
+
+function registerOpenClawProductStatusTools(api, aquifer, opts = {}) {
+  if (!api || typeof api.registerTool !== 'function') {
+    throw new Error('OpenClaw-compatible api.registerTool is required');
+  }
+  if (!aquifer) {
+    throw new Error('aquifer instance is required');
+  }
+  const skipTools = normalizeSkipTools(opts.skipTools);
+
+  if (!skipTools.has('memory_stats')) {
+    api.registerTool((ctx) => {
+      if ((ctx?.sessionKey || '').includes('subagent')) return null;
+
+      return {
+        name: 'memory_stats',
+        description: manifestToolDescription('memory_stats', 'Return Aquifer product status.'),
+        parameters: {
+          type: 'object',
+          properties: {
+            diagnostics: { type: 'boolean', description: 'Include raw storage counters and serving diagnostics. Default false.' },
+          },
+        },
+        async execute(_toolCallId, params = {}) {
+          try {
+            const stats = await aquifer.getStats();
+            const text = formatMemoryStatsInterface(stats, { diagnostics: params.diagnostics === true });
+            return { content: [{ type: 'text', text }] };
+          } catch (err) {
+            return {
+              content: [{ type: 'text', text: `memory_stats error: ${err.message}` }],
+              isError: true,
+            };
+          }
+        },
+      };
+    }, { name: 'memory_stats' });
+  }
+
+  if (!skipTools.has('memory_pending')) {
+    api.registerTool((ctx) => {
+      if ((ctx?.sessionKey || '').includes('subagent')) return null;
+
+      return {
+        name: 'memory_pending',
+        description: manifestToolDescription('memory_pending', 'Return saved-content preparation status.'),
+        parameters: {
+          type: 'object',
+          properties: {
+            limit: { type: 'number', description: 'Max results (default 20)' },
+            source: { type: 'string', description: 'Filter by source' },
+            agentId: { type: 'string', description: 'Filter by agent ID' },
+            agent_id: { type: 'string', description: 'Filter by agent ID' },
+            status: { type: 'string', enum: ['pending', 'failed'], description: 'Filter by processing status' },
+            diagnostics: { type: 'boolean', description: 'Include source/agent/status buckets, guidance, and samples. Default false.' },
+          },
+        },
+        async execute(_toolCallId, params = {}) {
+          try {
+            const opts = pendingSessionOpts(params);
+            const report = typeof aquifer.getPendingWork === 'function'
+              ? await aquifer.getPendingWork(opts)
+              : null;
+            const text = report
+              ? formatPendingWorkInterface(report, {
+                  diagnostics: params.diagnostics === true,
+                  includePlan: false,
+                })
+              : formatPendingRowsInterface(
+                  typeof aquifer.getPendingSessions === 'function'
+                    ? await aquifer.getPendingSessions(opts)
+                    : [],
+                  { diagnostics: params.diagnostics === true }
+                );
+            return { content: [{ type: 'text', text }] };
+          } catch (err) {
+            return {
+              content: [{ type: 'text', text: `memory_pending error: ${err.message}` }],
+              isError: true,
+            };
+          }
+        },
+      };
+    }, { name: 'memory_pending' });
+  }
+
+  return { aquifer, productStatusToolsRegistered: true };
+}
+
+module.exports = {
+  clampLimit,
+  manifestToolDescription,
+  normalizeSkipTools,
+  pendingSessionOpts,
+  registerOpenClawProductStatusTools,
+};

package/consumers/shared/recall-format.js

@@ -2,8 +2,8 @@
 
 // ---------------------------------------------------------------------------
 // Shared recall formatter — turns aquifer.recall() rows into human-readable
-// text. The default is English and markdown-ish; consumers with a persona
-// (Miranda: zh-TW narrative) can override individual renderers.
+// text. The default is English and markdown-ish; persona adapters can override
+// individual renderers.
 // ---------------------------------------------------------------------------
 
 function truncate(s, n) {