@shadowforge0/aquifer-memory 0.9.0 → 0.9.1

package/consumers/cli.js

@@ -16,6 +16,26 @@
 
 const { createAquiferFromConfig } = require('./shared/factory');
 
+function formatDate(value, fallback) {
+  if (!value) return fallback;
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? fallback : parsed.toISOString().slice(0, 10);
+}
+
+function quoteIdentifier(identifier) {
+  if (!/^[a-zA-Z_]\w{0,62}$/.test(identifier)) {
+    throw new Error(`Invalid schema name: "${identifier}"`);
+  }
+  return `"${identifier}"`;
+}
+
+function parsePositiveInt(value, fallback) {
+  if (value === undefined || value === null || value === true) return fallback;
+  const parsed = parseInt(value, 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(1, parsed);
+}
+
 // ---------------------------------------------------------------------------
 // Argument parser (minimal, no deps)
 // ---------------------------------------------------------------------------
@@ -57,7 +77,7 @@ async function cmdRecall(aquifer, args) {
   }
 
   const recallOpts = {
-    limit: parseInt(args.flags.limit || '5', 10),
+    limit: parsePositiveInt(args.flags.limit, 5),
     agentId: args.flags['agent-id'] || undefined,
     source: args.flags.source || undefined,
     dateFrom: args.flags['date-from'] || undefined,
@@ -83,7 +103,7 @@ async function cmdRecall(aquifer, args) {
     const r = results[i];
     const ss = r.structuredSummary || {};
     const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = r.startedAt ? new Date(r.startedAt).toISOString().slice(0, 10) : '?';
+    const date = formatDate(r.startedAt, '?');
     console.log(`${i + 1}. [${r.score?.toFixed(3)}] ${title} (${date}, ${r.agentId})`);
     if (ss.overview) console.log(`   ${ss.overview.slice(0, 200)}`);
     if (r.matchedTurnText) console.log(`   > ${r.matchedTurnText.slice(0, 150)}`);
@@ -114,7 +134,7 @@ async function cmdFeedback(aquifer, args) {
 }
 
 async function cmdBackfill(aquifer, args) {
-  const limit = parseInt(args.flags.limit || '100', 10);
+  const limit = parsePositiveInt(args.flags.limit, 100);
   const dryRun = !!args.flags['dry-run'];
   const skipSummary = !!args.flags['skip-summary'];
   const skipTurnEmbed = !!args.flags['skip-turn-embed'];
@@ -160,7 +180,7 @@ async function cmdStats(aquifer, args) {
     console.log(`Summaries: ${stats.summaries}`);
     console.log(`Turn embeddings: ${stats.turnEmbeddings}`);
     console.log(`Entities: ${stats.entities}`);
-    if (stats.earliest) console.log(`Range: ${new Date(stats.earliest).toISOString().slice(0, 10)} — ${new Date(stats.latest).toISOString().slice(0, 10)}`);
+    if (stats.earliest) console.log(`Range: ${formatDate(stats.earliest, '?')} — ${formatDate(stats.latest, '?')}`);
   }
 }
 
@@ -211,11 +231,21 @@ async function cmdQuickstart(aquifer) {
   const { loadConfig } = require('./shared/config');
   const config = loadConfig();
   const pool = new Pool({ connectionString: config.db.url });
-  const schema = config.schema || 'aquifer';
-  await pool.query(`DELETE FROM ${schema}.turn_embeddings WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [sessionId]);
-  await pool.query(`DELETE FROM ${schema}.session_summaries WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [sessionId]);
-  await pool.query(`DELETE FROM ${schema}.sessions WHERE session_id = $1`, [sessionId]);
-  await pool.end();
+  const schema = quoteIdentifier(config.schema || 'aquifer');
+  const tenantId = config.tenantId || 'default';
+  try {
+    await pool.query('BEGIN');
+    await pool.query(
+      `DELETE FROM ${schema}.sessions WHERE tenant_id = $1 AND agent_id = $2 AND session_id = $3`,
+      [tenantId, 'quickstart', sessionId]
+    );
+    await pool.query('COMMIT');
+  } catch (err) {
+    await pool.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    await pool.end();
+  }
   console.log('     OK\n');
 
   console.log('✓ Aquifer is working. You can now start the MCP server:');
@@ -224,7 +254,7 @@ async function cmdQuickstart(aquifer) {
 
 async function cmdExport(aquifer, args) {
   const output = args.flags.output || null;
-  const limit = parseInt(args.flags.limit || '1000', 10);
+  const limit = parsePositiveInt(args.flags.limit, 1000);
 
   const rows = await aquifer.exportSessions({
     agentId: args.flags['agent-id'],

package/consumers/mcp.js

@@ -38,9 +38,11 @@ function formatResults(results, query) {
     const r = results[i];
     const ss = r.structuredSummary || {};
     const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = r.startedAt
-      ? new Date(r.startedAt).toISOString().slice(0, 10)
-      : 'unknown';
+    let date = 'unknown';
+    if (r.startedAt) {
+      const parsed = new Date(r.startedAt);
+      if (!isNaN(parsed.getTime())) date = parsed.toISOString().slice(0, 10);
+    }
 
     lines.push(`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`);
     if (ss.overview || r.summaryText) {
@@ -65,9 +67,11 @@ async function main() {
     ({ StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js'));
     ({ z } = require('zod'));
   } catch (e) {
+    const missingDep = e && (e.code === 'MODULE_NOT_FOUND' || /Cannot find module|^missing\b/i.test(e.message || ''));
+    if (!missingDep) throw e;
     process.stderr.write(
       'aquifer mcp requires @modelcontextprotocol/sdk and zod.\n' +
-      'These should be installed automatically. Try: npm install\n'
+      'Install: npm install @modelcontextprotocol/sdk zod\n'
     );
     process.exit(1);
   }

package/consumers/openclaw-plugin.js

@@ -79,15 +79,19 @@ function normalizeEntries(rawEntries) {
   };
 }
 
+function formatDate(value) {
+  if (!value) return 'unknown';
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? 'unknown' : parsed.toISOString().slice(0, 10);
+}
+
 function formatRecallResults(results) {
   if (results.length === 0) return 'No matching sessions found.';
 
   return results.map((r, i) => {
     const ss = r.structuredSummary || {};
     const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = r.startedAt
-      ? new Date(r.startedAt).toISOString().slice(0, 10)
-      : 'unknown';
+    const date = formatDate(r.startedAt);
 
     const lines = [`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`];
     if (ss.overview || r.summaryText) {

package/core/aquifer.js

@@ -583,7 +583,22 @@ function createAquifer(config) {
         weights: overrideWeights,
         entities: explicitEntities,
         entityMode = 'any',
+        strictSearchErrors = false,
       } = opts;
+      const searchErrors = [];
+
+      function recordSearchError(pathName, err) {
+        searchErrors.push({
+          path: pathName,
+          message: err && err.message ? err.message : String(err),
+        });
+      }
+
+      function maybeThrowSearchErrors() {
+        if (!strictSearchErrors || searchErrors.length === 0) return;
+        const details = searchErrors.map(e => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`Recall search failed: ${details}`);
+      }
 
       // Normalize agentId/agentIds into a single resolved value
       // agentIds takes precedence; agentId is sugar for agentIds: [agentId]
@@ -692,17 +707,26 @@ function createAquifer(config) {
         runFts
           ? storage.searchSessions(pool, query, {
               schema, tenantId, agentIds: resolvedAgentIds, source, dateFrom, dateTo, limit: fetchLimit, ftsConfig,
-            }).catch(() => [])
+            }).catch((err) => {
+              recordSearchError('fts', err);
+              return [];
+            })
           : Promise.resolve([]),
         runVector
           ? embeddingSearchSummaries(queryVec, {
               agentIds: resolvedAgentIds, source, dateFrom, dateTo, limit: fetchLimit,
-            }).catch(() => [])
+            }).catch((err) => {
+              recordSearchError('summary-vector', err);
+              return [];
+            })
           : Promise.resolve([]),
         runVector
           ? storage.searchTurnEmbeddings(pool, {
               schema, tenantId, queryVec, dateFrom, dateTo, agentIds: resolvedAgentIds, source, limit: fetchLimit,
-            }).catch(() => ({ rows: [] }))
+            }).catch((err) => {
+              recordSearchError('turn-vector', err);
+              return { rows: [] };
+            })
           : Promise.resolve({ rows: [] }),
       ]);
 
@@ -718,6 +742,7 @@ function createAquifer(config) {
       const filteredTurn = filterFn(turnRows);
 
       if (filteredFts.length === 0 && filteredEmb.length === 0 && filteredTurn.length === 0) {
+        maybeThrowSearchErrors();
         return [];
       }
 
@@ -737,7 +762,7 @@ function createAquifer(config) {
       const EXTERNAL_TIMEOUT = 10000;
       const externalRows = [];
       const externalPromises = [];
-      for (const [, sourceConfig] of sources) {
+      for (const [name, sourceConfig] of sources) {
         if (typeof sourceConfig.search === 'function') {
           const w = sourceConfig.weight !== null && sourceConfig.weight !== undefined ? sourceConfig.weight : 1.0;
           externalPromises.push(
@@ -750,7 +775,9 @@ function createAquifer(config) {
                   if (r && r.session_id) externalRows.push({ ...r, _externalWeight: w });
                 }
               }
-            }).catch(() => { /* external source failure/timeout non-fatal */ })
+            }).catch((err) => {
+              recordSearchError(`external:${name}`, err);
+            })
           );
         }
       }
@@ -835,6 +862,7 @@ function createAquifer(config) {
           hybridScore: r._hybridScore ?? r._score,
           rerankScore: r._rerankScore ?? null,
           rerankFallback: r._rerankFallback || false,
+          searchErrors: searchErrors.slice(),
         },
       }));
     },

package/core/hybrid-rank.js

@@ -36,12 +36,12 @@ function rrfFusion(ftsResults = [], embResults = [], turnResults = [], K = 60) {
 // timeDecay — sigmoid decay based on age in days
 // ---------------------------------------------------------------------------
 
-function timeDecay(startedAt, midpointDays = 45, steepness = 0.05) {
+function timeDecay(startedAt, midpointDays = 45, steepness = 0.05, nowMs = Date.now()) {
   if (!startedAt) return 0.5;
   const dt = typeof startedAt === 'string' ? new Date(startedAt) : startedAt;
   if (isNaN(dt.getTime())) return 0.5;
 
-  const ageDays = (Date.now() - dt.getTime()) / (1000 * 60 * 60 * 24);
+  const ageDays = (nowMs - dt.getTime()) / (1000 * 60 * 60 * 24);
   return 1 / (1 + Math.exp(steepness * (ageDays - midpointDays)));
 }
 
@@ -49,14 +49,14 @@ function timeDecay(startedAt, midpointDays = 45, steepness = 0.05) {
 // accessScore — exponential decay on access recency (30-day half-life)
 // ---------------------------------------------------------------------------
 
-function accessScore(accessCount, lastAccessedAt) {
+function accessScore(accessCount, lastAccessedAt, nowMs = Date.now()) {
   if (!accessCount || accessCount <= 0) return 0;
   if (!lastAccessedAt) return 0;
 
   const dt = typeof lastAccessedAt === 'string' ? new Date(lastAccessedAt) : lastAccessedAt;
   if (isNaN(dt.getTime())) return 0;
 
-  const daysSince = (Date.now() - dt.getTime()) / (1000 * 60 * 60 * 24);
+  const daysSince = (nowMs - dt.getTime()) / (1000 * 60 * 60 * 24);
   return accessCount * Math.exp(-0.693 * daysSince / 30);
 }
 
@@ -89,6 +89,7 @@ function hybridRank(ftsResults, embResults, turnResults, opts = {}) {
   } = opts;
 
   const w = { ...DEFAULT_WEIGHTS, ...weights };
+  const nowMs = opts.nowMs ?? Date.now();
 
   // Build allResults map: session_id → result object
   const allResults = new Map();
@@ -140,11 +141,12 @@ function hybridRank(ftsResults, embResults, turnResults, opts = {}) {
     const rawRrf = rrfScores.get(sessionId) || 0;
     const normRrf = maxRrf > 0 ? rawRrf / maxRrf : 0;
 
-    const td = timeDecay(result.started_at);
+    const td = timeDecay(result.started_at, 45, 0.05, nowMs);
 
     const accessEff = accessScore(
       result.access_count || 0,
       result.last_accessed_at,
+      nowMs,
     );
     const as = 1 - Math.exp(-accessEff / 5);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. MCP server, CLI, and library API.",
   "main": "index.js",
   "files": [