@shadowforge0/aquifer-memory 1.3.0 → 1.5.8

package/consumers/default/index.js

@@ -222,26 +222,39 @@ function createPersona(personaOpts = {}) {
       if ((ctx?.sessionKey || '').includes('subagent')) return null;
       return {
         name: 'session_recall',
-        description: 'Search stored sessions by keyword.',
+        description: 'Search stored sessions by keyword or natural language. Use entities when the user names specific people, projects, files, tools, or concepts; use entity_mode="all" when every named entity must co-occur (default "any" boosts). Use mode to force fts/vector/hybrid (default hybrid).',
         parameters: {
           type: 'object',
           properties: {
-            query: { type: 'string' },
+            query: { type: 'string', minLength: 1, description: 'Non-empty keyword or natural-language query' },
             limit: { type: 'number' },
             agent_id: { type: 'string' },
+            source: { type: 'string' },
             date_from: { type: 'string' },
             date_to: { type: 'string' },
+            entities: { type: 'array', items: { type: 'string' }, description: 'Named entities (person/project/tool/file)' },
+            entity_mode: { type: 'string', enum: ['any', 'all'], description: '"any" boosts; "all" hard-filters to sessions containing every entity' },
+            mode: { type: 'string', enum: ['fts', 'hybrid', 'vector'], description: 'Recall strategy, default hybrid' },
           },
         },
         async execute(_toolCallId, params) {
           try {
             const limit = Math.max(1, Math.min(20, parseInt(params?.limit ?? 5, 10) || 5));
-            const results = await aquifer.recall(String(params?.query || ''), {
+            const recallOpts = {
               agentId: params?.agent_id || ctx?.agentId || undefined,
+              source: params?.source || undefined,
               dateFrom: params?.date_from || undefined,
               dateTo: params?.date_to || undefined,
               limit,
-            });
+            };
+            if (Array.isArray(params?.entities) && params.entities.length > 0) {
+              recallOpts.entities = params.entities;
+              recallOpts.entityMode = params?.entity_mode || 'any';
+            }
+            if (params?.mode === 'fts' || params?.mode === 'hybrid' || params?.mode === 'vector') {
+              recallOpts.mode = params.mode;
+            }
+            const results = await aquifer.recall(String(params?.query || ''), recallOpts);
             const lines = results.map((r, i) =>
               `${i+1}. ${r.structuredSummary?.title || r.summaryText?.slice(0, 80) || '(untitled)'}`
             );

package/consumers/mcp.js

@@ -225,6 +225,27 @@ async function main() {
   process.on('SIGINT', cleanup);
   process.on('SIGTERM', cleanup);
 
+  // Startup handshake: instantiate aquifer + drive init() before MCP transport
+  // so schema state is resolved before the first tool call. apply-mode failure
+  // is fatal (exit non-zero) — an MCP instance with pending DDL would serve
+  // tool traffic against a stale schema and surface confusing errors later.
+  const aquifer = getAquifer();
+  const envelope = await aquifer.init();
+  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} ` +
+      `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`
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
 

package/consumers/miranda/index.js

@@ -275,13 +275,16 @@ function registerRecallTool(api, opts = {}) {
         if ((ctx?.sessionKey || '').includes('subagent')) return null;
         return {
             name: 'session_recall',
-            description: '搜尋歷史 session 的摘要和對話記錄。可按關鍵字、日期範圍、agent 搜尋。',
+            description: '搜尋歷史 session 的摘要和對話記錄。當問題明確提到具體人名、專案、工具、檔名時，傳 entities；只想保留全部命中的 session 用 entity_mode="all"，否則 "any" 是 boost。mode 可選 "fts"/"vector"/"hybrid"，default hybrid。',
             parameters: {
                 type: 'object',
                 properties: {
-                    query: { type: 'string', description: '搜尋關鍵字（可空，空時按時間排序）' },
+                    query: { type: 'string', description: '搜尋關鍵字或自然語言描述（必填非空）', minLength: 1 },
                     date_from: { type: 'string' }, date_to: { type: 'string' },
                     agent_id: { type: 'string' }, source: { type: 'string' },
+                    entities: { type: 'array', items: { type: 'string' }, description: '具名 entity 清單（人/專案/工具/檔名）' },
+                    entity_mode: { type: 'string', enum: ['any', 'all'], description: '"any" boost / "all" 硬過濾必含全部 entity' },
+                    mode: { type: 'string', enum: ['fts', 'hybrid', 'vector'], description: 'recall 模式，default hybrid' },
                     detail: { type: 'string' },
                     limit: { type: 'number' },
                 },
@@ -289,13 +292,21 @@ function registerRecallTool(api, opts = {}) {
             async execute(_toolCallId, params) {
                 try {
                     const limit = Math.max(1, Math.min(20, parseInt(params?.limit ?? 5, 10) || 5));
-                    const results = await aquifer.recall(String(params?.query || ''), {
+                    const recallOpts = {
                         agentId: params?.agent_id || ctx?.agentId || undefined,
                         source: params?.source || undefined,
                         dateFrom: params?.date_from || undefined,
                         dateTo: params?.date_to || undefined,
                         limit,
-                    });
+                    };
+                    if (Array.isArray(params?.entities) && params.entities.length > 0) {
+                        recallOpts.entities = params.entities;
+                        recallOpts.entityMode = params?.entity_mode || 'any';
+                    }
+                    if (params?.mode === 'fts' || params?.mode === 'hybrid' || params?.mode === 'vector') {
+                        recallOpts.mode = params.mode;
+                    }
+                    const results = await aquifer.recall(String(params?.query || ''), recallOpts);
                     const text = mirandaRecallFormat.formatRecallResults(results.map(r => ({
                         sessionId: r.sessionId, agentId: r.agentId, source: r.source,
                         startedAt: r.startedAt, summaryText: r.summaryText,

package/consumers/miranda/recall-format.js

@@ -3,7 +3,7 @@
 // Miranda zh-TW recall formatter — overrides the shared default renderers
 // to produce narrative-style output instead of score-flavored markdown.
 
-const { createRecallFormatter, truncate, formatDateIso } = require('../shared/recall-format');
+const { createRecallFormatter, truncate, formatDateIso, formatRelativeZhTw } = require('../shared/recall-format');
 
 function formatTopicLines(topics) {
     if (!Array.isArray(topics) || topics.length === 0) return '- 無';
@@ -32,10 +32,12 @@ function coalesceTitle(structuredSummary, summaryText) {
 const mirandaRenderers = {
     empty: () => '找不到符合條件的 session。',
     header: () => null,
-    title: (r, i) => {
+    title: (r, i, ctx) => {
         const ss = r.structuredSummary || {};
         const title = coalesceTitle(ss, r.summaryText);
-        const date = formatDateIso(r.startedAt);
+        const iso = formatDateIso(r.startedAt);
+        const rel = formatRelativeZhTw(r.startedAt, ctx?.now);
+        const date = rel ? `${rel}（${iso}）` : iso;
         const agent = r.agentId || r.agent_id || 'main';
         return `### ${i + 1}. ${title}\n**Agent**: ${agent} | **Date**: ${date}`;
     },

package/consumers/shared/config.js

@@ -42,6 +42,12 @@ const DEFAULTS = {
     timeoutMs: 2000,
     maxRetries: 1,
   },
+  migrations: {
+    mode: 'apply',         // 'apply' | 'check' | 'off'
+    lockTimeoutMs: 30000,
+    startupTimeoutMs: 60000,
+    onEvent: null,         // (event) => void, optional observability hook
+  },
 };
 
 // ---------------------------------------------------------------------------
@@ -77,6 +83,8 @@ const ENV_MAP = [
   ['AQUIFER_RERANK_TOP_K',     'rerank.topK',       Number],
   ['AQUIFER_RERANK_MAX_CHARS', 'rerank.maxChars',   Number],
   ['AQUIFER_RERANK_TIMEOUT_MS','rerank.timeoutMs',   Number],
+  ['AQUIFER_MIGRATIONS_MODE',           'migrations.mode'],
+  ['AQUIFER_MIGRATION_LOCK_TIMEOUT_MS', 'migrations.lockTimeoutMs',   Number],
 ];
 
 // ---------------------------------------------------------------------------

package/consumers/shared/factory.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const { Pool } = require('pg');
-const { createAquifer, createEmbedder, createReranker } = require('../../index');
+const { createAquifer, createEmbedder } = require('../../index');
 const { loadConfig } = require('./config');
 const { createLlmFn } = require('./llm');
 
@@ -90,6 +90,7 @@ function createAquiferFromConfig(overrides) {
     entities: config.entities,
     rank: config.rank,
     rerank: rerankOpts,
+    migrations: config.migrations,
   });
 
   return aquifer;

package/consumers/shared/llm.js

@@ -31,7 +31,7 @@ function httpRequest(url, options, body) {
         }
         try {
           finish(resolve, JSON.parse(raw));
-        } catch (e) {
+        } catch {
           finish(reject, new Error(`Invalid JSON from LLM (${raw.length} bytes)`));
         }
       });

package/consumers/shared/recall-format.js

@@ -18,6 +18,25 @@ function formatDateIso(value) {
     return Number.isNaN(d.getTime()) ? 'unknown' : d.toISOString().slice(0, 10);
 }
 
+// Humanize a past timestamp into zh-TW relative form (e.g. "3 天前", "昨天").
+// Bucketed on raw ms-diff — good enough for model intuition, not calendar-precise.
+// Returns null for invalid / future timestamps so callers can fall back.
+function formatRelativeZhTw(value, now) {
+    if (!value) return null;
+    const t = new Date(value).getTime();
+    if (Number.isNaN(t)) return null;
+    const nowMs = typeof now === 'number' ? now : Date.now();
+    const diffMs = nowMs - t;
+    if (diffMs < 0) return null;
+    const day = 86400000;
+    if (diffMs < day) return '今天';
+    if (diffMs < 2 * day) return '昨天';
+    if (diffMs < 7 * day) return `${Math.floor(diffMs / day)} 天前`;
+    if (diffMs < 30 * day) return `${Math.floor(diffMs / (7 * day))} 週前`;
+    if (diffMs < 365 * day) return `${Math.floor(diffMs / (30 * day))} 個月前`;
+    return `${Math.floor(diffMs / (365 * day))} 年前`;
+}
+
 // Default English renderers --------------------------------------------------
 
 const defaultRenderers = {
@@ -63,7 +82,7 @@ function createRecallFormatter(overrides = {}) {
 
     return function format(results, opts = {}) {
         const safeResults = Array.isArray(results) ? results : [];
-        const ctx = { query: opts.query || null, results: safeResults };
+        const ctx = { query: opts.query || null, results: safeResults, now: opts.now };
 
         if (safeResults.length === 0) {
             return r.empty(ctx);
@@ -106,5 +125,6 @@ module.exports = {
     formatRecallResults,
     truncate,
     formatDateIso,
+    formatRelativeZhTw,
     defaultRenderers,
 };