@shadowforge0/aquifer-memory 0.3.0 → 0.4.0

package/consumers/cli.js

@@ -23,7 +23,7 @@ const { loadConfig } = require('./shared/config');
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   // Flags that take a value (not boolean)
-  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency']);
+  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency', 'entities', 'entity-mode', 'session-id', 'verdict', 'note']);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
     if (argv[i].startsWith('--')) {
@@ -56,13 +56,18 @@ async function cmdRecall(aquifer, args) {
     process.exit(1);
   }
 
-  const results = await aquifer.recall(query, {
+  const recallOpts = {
     limit: parseInt(args.flags.limit || '5', 10),
     agentId: args.flags['agent-id'] || undefined,
     source: args.flags.source || undefined,
     dateFrom: args.flags['date-from'] || undefined,
     dateTo: args.flags['date-to'] || undefined,
-  });
+  };
+  if (args.flags.entities) {
+    recallOpts.entities = args.flags.entities.split(',').map(s => s.trim()).filter(Boolean);
+    recallOpts.entityMode = args.flags['entity-mode'] || 'any';
+  }
+  const results = await aquifer.recall(query, recallOpts);
 
   if (args.flags.json) {
     console.log(JSON.stringify(results, null, 2));
@@ -86,6 +91,28 @@ async function cmdRecall(aquifer, args) {
   }
 }
 
+async function cmdFeedback(aquifer, args) {
+  const sessionId = args.flags['session-id'] || args._[1];
+  const verdict = args.flags.verdict;
+
+  if (!sessionId || !verdict) {
+    console.error('Usage: aquifer feedback --session-id ID --verdict helpful|unhelpful [--note TEXT] [--agent-id ID]');
+    process.exit(1);
+  }
+
+  const result = await aquifer.feedback(sessionId, {
+    verdict,
+    agentId: args.flags['agent-id'] || undefined,
+    note: args.flags.note || undefined,
+  });
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`Feedback: ${result.verdict} (trust ${result.trustBefore.toFixed(2)} → ${result.trustAfter.toFixed(2)})`);
+  }
+}
+
 async function cmdBackfill(aquifer, args) {
   const limit = parseInt(args.flags.limit || '100', 10);
   const dryRun = !!args.flags['dry-run'];
@@ -243,6 +270,7 @@ async function main() {
 Commands:
   migrate                     Run database migrations
   recall <query>              Search sessions (requires embed config)
+  feedback                    Record trust feedback on a session
   backfill                    Enrich pending sessions
   stats                       Show database statistics
   export                      Export sessions as JSONL
@@ -254,6 +282,11 @@ Options:
   --source NAME               Filter by source
   --date-from YYYY-MM-DD      Start date
   --date-to YYYY-MM-DD        End date
+  --entities A,B,C            Entity names (comma-separated, recall)
+  --entity-mode any|all       Entity match mode (recall, default: any)
+  --session-id ID             Session ID (feedback)
+  --verdict helpful|unhelpful Feedback verdict (feedback)
+  --note TEXT                 Feedback note (feedback)
   --json                      JSON output
   --dry-run                   Preview only (backfill)
   --output PATH               Output file (export)
@@ -290,6 +323,9 @@ Options:
       case 'recall':
         await cmdRecall(aquifer, args);
         break;
+      case 'feedback':
+        await cmdFeedback(aquifer, args);
+        break;
       case 'backfill':
         await cmdBackfill(aquifer, args);
         break;

package/consumers/mcp.js

@@ -69,12 +69,12 @@ async function main() {
 
   const server = new McpServer({
     name: 'aquifer-memory',
-    version: '0.2.0',
+    version: '0.3.1',
   });
 
   server.tool(
     'session_recall',
-    'Search stored sessions by keyword, returning ranked summaries and matched conversation turns.',
+    'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
     {
       query: z.string().min(1).describe('Search query (keyword or natural language)'),
       limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
@@ -82,20 +82,26 @@ 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'),
+      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)'),
     },
     async (params) => {
       try {
         const aquifer = getAquifer();
         const limit = params.limit || 5;
-
-        const results = await aquifer.recall(params.query, {
+        const recallOpts = {
           limit,
           agentId: params.agentId || undefined,
           source: params.source || undefined,
           dateFrom: params.dateFrom || undefined,
           dateTo: params.dateTo || undefined,
-        });
+        };
+        if (params.entities && params.entities.length > 0) {
+          recallOpts.entities = params.entities;
+          recallOpts.entityMode = params.entityMode || 'any';
+        }
 
+        const results = await aquifer.recall(params.query, recallOpts);
         const text = formatResults(results, params.query);
         return { content: [{ type: 'text', text }] };
       } catch (err) {
@@ -107,6 +113,33 @@ async function main() {
     }
   );
 
+  server.tool(
+    'session_feedback',
+    'Record trust feedback on a recalled session. Helpful sessions rank higher in future recalls.',
+    {
+      sessionId: z.string().min(1).describe('Session ID to give feedback on'),
+      verdict: z.enum(['helpful', 'unhelpful']).describe('Was the recalled session useful?'),
+      note: z.string().optional().describe('Optional reason'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const result = await aquifer.feedback(params.sessionId, {
+          verdict: params.verdict,
+          note: params.note || undefined,
+        });
+        return {
+          content: [{ type: 'text', text: `Feedback: ${result.verdict} (trust ${result.trustBefore.toFixed(2)} → ${result.trustAfter.toFixed(2)})` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `session_feedback error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   // Graceful shutdown
   const cleanup = async () => {
     if (_aquifer?._pool) await _aquifer._pool.end().catch(() => {});

package/consumers/openclaw-plugin.js

@@ -189,12 +189,14 @@ module.exports = {
 
     // --- session_recall tool ---
 
+    // --- session_recall tool ---
+
     api.registerTool((ctx) => {
       if ((ctx?.sessionKey || '').includes('subagent')) return null;
 
       return {
         name: 'session_recall',
-        description: 'Search stored sessions by keyword, returning ranked summaries and matched conversation turns.',
+        description: 'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
         parameters: {
           type: 'object',
           properties: {
@@ -204,20 +206,27 @@ module.exports = {
             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' },
+            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)' },
           },
           required: ['query'],
         },
         async execute(_toolCallId, params) {
           try {
             const limit = Math.max(1, Math.min(20, parseInt(params?.limit ?? 5, 10) || 5));
-            const results = await aquifer.recall(params.query, {
+            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';
+            }
 
+            const results = await aquifer.recall(params.query, recallOpts);
             const text = formatRecallResults(results);
             return { content: [{ type: 'text', text }] };
           } catch (err) {
@@ -230,6 +239,42 @@ module.exports = {
       };
     }, { name: 'session_recall' });
 
-    api.logger.info('[aquifer-memory] registered (before_reset + session_recall)');
+    // --- session_feedback tool ---
+
+    api.registerTool((ctx) => {
+      if ((ctx?.sessionKey || '').includes('subagent')) return null;
+
+      return {
+        name: 'session_feedback',
+        description: 'Record trust feedback on a recalled session. Helpful sessions rank higher in future recalls.',
+        parameters: {
+          type: 'object',
+          properties: {
+            sessionId: { type: 'string', description: 'Session ID to give feedback on' },
+            verdict: { type: 'string', enum: ['helpful', 'unhelpful'], description: 'Was the recalled session useful?' },
+            note: { type: 'string', description: 'Optional reason' },
+          },
+          required: ['sessionId', 'verdict'],
+        },
+        async execute(_toolCallId, params) {
+          try {
+            const result = await aquifer.feedback(params.sessionId, {
+              verdict: params.verdict,
+              note: params.note || undefined,
+            });
+            return {
+              content: [{ type: 'text', text: `Feedback: ${result.verdict} (trust ${result.trustBefore.toFixed(2)} → ${result.trustAfter.toFixed(2)})` }],
+            };
+          } catch (err) {
+            return {
+              content: [{ type: 'text', text: `session_feedback error: ${err.message}` }],
+              isError: true,
+            };
+          }
+        },
+      };
+    }, { name: 'session_feedback' });
+
+    api.logger.info('[aquifer-memory] registered (before_reset + session_recall + session_feedback)');
   },
 };

package/core/aquifer.js

@@ -94,6 +94,14 @@ function createAquifer(config) {
 
   // Track if migrate was called
   let migrated = false;
+  let migratePromise = null;
+
+  async function ensureMigrated() {
+    if (migrated) return;
+    if (migratePromise) return migratePromise;
+    migratePromise = aquifer.migrate().finally(() => { migratePromise = null; });
+    return migratePromise;
+  }
 
   // --- Helper: embed search on summaries ---
   async function embeddingSearchSummaries(queryVec, opts) {
@@ -196,6 +204,7 @@ function createAquifer(config) {
     async commit(sessionId, messages, opts = {}) {
       if (!sessionId) throw new Error('sessionId is required');
       if (!messages || !Array.isArray(messages)) throw new Error('messages must be an array');
+      await ensureMigrated();
 
       const agentId = opts.agentId || 'agent';
       const source = opts.source || 'api';
@@ -240,6 +249,7 @@ function createAquifer(config) {
     // --- enrichment ---
 
     async enrich(sessionId, opts = {}) {
+      await ensureMigrated();
       const agentId = opts.agentId || 'agent';
       const skipSummary = opts.skipSummary || false;
       const skipTurnEmbed = opts.skipTurnEmbed || false;
@@ -470,6 +480,13 @@ function createAquifer(config) {
         entityMode = 'any',
       } = opts;
 
+      // Validate before touching DB
+      if (explicitEntities && explicitEntities.length > 0 && !entitiesEnabled) {
+        throw new Error('Entities are not enabled');
+      }
+
+      await ensureMigrated();
+
       const fetchLimit = limit * 4;
 
       // 1. Embed query
@@ -482,7 +499,6 @@ function createAquifer(config) {
       let entityScoreBySession = new Map();
 
       if (explicitEntities && explicitEntities.length > 0) {
-        if (!entitiesEnabled) throw new Error('Entities are not enabled');
 
         const resolved = await entity.resolveEntities(pool, {
           schema, tenantId, names: explicitEntities, agentId,
@@ -671,6 +687,7 @@ function createAquifer(config) {
       const agentId = opts.agentId || 'agent';
       const verdict = opts.verdict;
       if (!verdict) throw new Error('opts.verdict is required ("helpful" or "unhelpful")');
+      await ensureMigrated();
 
       const session = await storage.getSession(pool, sessionId, agentId, {}, { schema, tenantId });
       if (!session) throw new Error(`Session not found: ${sessionId} (agentId=${agentId})`);

package/package.json

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