@shadowforge0/aquifer-memory 1.2.1 → 1.5.8

package/README.md

@@ -333,18 +333,17 @@ Built-in entity extraction and relationship tracking:
 
 ## Benchmark: LongMemEval
 
-We tested Aquifer's retrieval pipeline on [LongMemEval_S](https://github.com/xiaowu0162/LongMemEval) — 470 questions across 19,195 sessions (98,845 turn embeddings).
+We tested Aquifer's retrieval pipeline on [LongMemEval_S](https://github.com/xiaowu0162/LongMemEval) — 470 questions across 19,195 sessions with 98,795 turn embeddings. Per-question haystack scoping (matching the official protocol), bge-m3 embeddings via OpenRouter.
 
-**Setup:** Per-question haystack scoping (matching official methodology), bge-m3 embeddings via OpenRouter, turn-level user-only embedding.
+| Pipeline | R@1 | R@3 | R@5 | R@10 |
+|----------|-----|-----|-----|------|
+| Turn-only (cosine) | 89.5% | 96.6% | 98.1% | 98.9% |
+| Three-way hybrid (FTS + session_emb + turn_emb → RRF) | 79.2% | 94.0% | 97.7% | 98.9% |
+| **Hybrid + Cohere Rerank v3.5 (top-30)** | **96.0%** | **98.5%** | **99.3%** | **99.8%** |
 
-| Metric | Aquifer (bge-m3) |
-|--------|-----------------|
-| R@1 | 89.6% |
-| R@3 | 96.6% |
-| R@5 | 98.1% |
-| R@10 | 98.9% |
+Measured 2026-04-19 on Aquifer 1.2.1.
 
-**Key finding:** Turn-level embedding is the main driver — going from session-level (R@1=26.8%) to turn-level (R@1=89.6%) is a 3x improvement.
+**Key findings.** Turn-level embedding alone beats session-level (26.8% → 89.5% R@1, a 3× improvement). Hybrid fusion adds robustness at R@3-R@10 but trades R@1 because FTS + session-level signals spread the top candidate across adjacent sessions. Re-ranking the hybrid top-30 with a cross-encoder (Cohere Rerank v3.5) wins back the top-1 precision and then some — +16.9pt R@1 over hybrid baseline, and 6.5pt above pure turn-level cosine. That's the production pipeline Aquifer ships by default when a reranker is configured.
 
 ### Multi-Tenant
 

package/consumers/cli.js

@@ -43,7 +43,7 @@ function parsePositiveInt(value, fallback) {
 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', 'entities', 'entity-mode', 'session-id', 'verdict', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars']);
+  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', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars', 'out']);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
     if (argv[i].startsWith('--')) {
@@ -360,6 +360,16 @@ Options:
     return;
   }
 
+  // mcp-contract: write canonical MCP tool manifest to disk. No Aquifer
+  // instance needed — manifest is static. Default path /tmp/aquifer-mcp-contract.json.
+  if (command === 'mcp-contract') {
+    const { writeMcpManifestFile } = require('../index');
+    const outPath = args.flags.out || '/tmp/aquifer-mcp-contract.json';
+    const written = writeMcpManifestFile(outPath);
+    console.log(`Wrote MCP manifest to ${written}`);
+    return;
+  }
+
   // All other commands need an Aquifer instance
   const configOverrides = {};
   if (args.flags.config) {

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/profile.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://aquifer.dev/schema/consumer-profile.v1.json",
+  "consumer_profile_id": "miranda",
+  "version": 1,
+  "description": "Miranda persona consumer profile — canonical shape for session state, handoff, decision log, timeline categories, and default artifact producers. Reference implementation shipped inside Aquifer; production deployments may register additional versions with schema changes.",
+  "defaults": {
+    "tenant_id": "default",
+    "agent_id": "main",
+    "time_zone": "Asia/Taipei"
+  },
+  "schemas": {
+    "default.session_state.v1": {
+      "kind": "default",
+      "target": "sessionState",
+      "description": "What Miranda is currently focused on — goal + active threads + affect tag.",
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "goal": { "type": ["string", "null"] },
+          "active_work": { "type": "array", "items": { "type": "string" } },
+          "blockers": { "type": "array", "items": { "type": "string" } },
+          "affect": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "mood": { "type": ["string", "null"] },
+              "energy": { "enum": ["low", "medium", "high", null] },
+              "confidence": { "enum": ["low", "medium", "high", null] },
+              "notes": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "required": ["goal", "active_work", "blockers", "affect"]
+      }
+    },
+    "default.session_handoff.v1": {
+      "kind": "default",
+      "target": "sessionHandoff",
+      "description": "Session-end baton: what was the last step, where to pick up, what still blocks.",
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "last_step": { "type": "string" },
+          "status": { "enum": ["in_progress", "completed", "blocked"] },
+          "next": { "type": ["string", "null"] },
+          "blockers": { "type": "array", "items": { "type": "string" } },
+          "decided": { "type": "array", "items": { "type": "string" } },
+          "open_loops": { "type": "array", "items": { "type": "string" } }
+        },
+        "required": ["last_step", "status", "next", "blockers", "decided", "open_loops"]
+      }
+    },
+    "default.decision_log.v1": {
+      "kind": "default",
+      "target": "decisionLog",
+      "description": "Committed / proposed / reversed decisions with optional fact linkage.",
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "decision": { "type": "string" },
+          "reason": { "type": ["string", "null"] },
+          "status": { "enum": ["proposed", "committed", "reversed"] },
+          "related_fact_ids": {
+            "type": "array",
+            "items": { "type": "integer" }
+          }
+        },
+        "required": ["decision", "reason", "status"]
+      }
+    },
+    "default.timeline.v1": {
+      "kind": "default",
+      "target": "timeline",
+      "description": "Miranda daily timeline category vocabulary. Categories map to existing daily-log sections (focus/todo/mood/handoff) plus organisational tags Miranda uses in weekly/monthly rollups.",
+      "category_vocabulary": [
+        "cli",
+        "focus",
+        "todo",
+        "handoff",
+        "narrative",
+        "organized",
+        "weekly",
+        "monthly",
+        "stats",
+        "health",
+        "garmin",
+        "note"
+      ],
+      "json_schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "occurred_at": { "type": "string", "format": "date-time" },
+          "source": { "type": "string" },
+          "session_ref": { "type": ["string", "null"] },
+          "category": { "type": "string" },
+          "text": { "type": "string" },
+          "metadata": { "type": "object" }
+        },
+        "required": ["occurred_at", "source", "session_ref", "category", "text", "metadata"]
+      }
+    }
+  },
+  "artifacts": {
+    "producers": [
+      {
+        "producer_id": "miranda.workspace.daily-log",
+        "type": "daily-log",
+        "trigger_phase": "timeline_write",
+        "format": "markdown",
+        "destination": "workspace://memory/{date}.md",
+        "description": "Renders the day's timeline events + state snapshot + handoff to a single markdown file under the Miranda workspace. Source of truth remains the DB; the .md is a rendered view."
+      },
+      {
+        "producer_id": "miranda.workspace.weekly-log",
+        "type": "weekly-log",
+        "trigger_phase": "artifact_dispatch",
+        "format": "markdown",
+        "destination": "workspace://memory/weekly/{week_start}.md",
+        "description": "Weekly rollup. Timeline events tagged [WEEKLY] plus cross-session narratives. Rendered from DB via rollupWeekly() helper."
+      },
+      {
+        "producer_id": "miranda.workspace.monthly-log",
+        "type": "monthly-log",
+        "trigger_phase": "artifact_dispatch",
+        "format": "markdown",
+        "destination": "workspace://memory/monthly/{month}.md",
+        "description": "Monthly rollup. Aggregates weekly entries + narrative supersede chain."
+      }
+    ]
+  },
+  "extraction_hints": {
+    "entities": {
+      "include_types": ["person", "project", "tool", "topic"],
+      "exclude_patterns": ["^/tmp/", "^/home/mingko/\\.", "^node_modules/"]
+    },
+    "facts": {
+      "prefer_subjects": ["MK", "Miranda", "Aquifer", "OpenClaw", "Jenny", "Evan", "Ivan"],
+      "avoid_ephemeral": true
+    }
+  }
+}

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/miranda/render-daily-md.js

@@ -0,0 +1,186 @@
+'use strict';
+
+// Miranda daily log renderer — reference implementation for the artifact
+// capability (spec §12).
+//
+// Pulls the canonical state for a date from Aquifer (timeline events + latest
+// state + active narrative + latest handoff) and renders it into a single
+// markdown file. Pure logic — does not write to disk; returns the rendered
+// string plus an artifact record declaration the caller can persist via
+// aq.artifacts.record().
+//
+// Shape deliberately mirrors the historical Miranda daily-log format so the
+// downstream consumers (CC, Discord pushes, weekly rollup) see no regression
+// during the cutover from render-daily-log.js to this reference impl.
+
+const crypto = require('crypto');
+
+function startOfDayIso(dateStr) {
+  return `${dateStr}T00:00:00Z`;
+}
+
+function endOfDayIso(dateStr) {
+  return `${dateStr}T23:59:59.999Z`;
+}
+
+function ensureDate(input) {
+  if (!input) throw new Error('date (YYYY-MM-DD) is required');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(input)) {
+    throw new Error(`date must match YYYY-MM-DD, got: ${input}`);
+  }
+  return input;
+}
+
+function renderSection(title, lines) {
+  if (!lines || lines.length === 0) return null;
+  return `## ${title}\n\n${lines.join('\n')}\n`;
+}
+
+function formatTimelineLine(evt) {
+  const ts = new Date(evt.occurredAt).toISOString().slice(11, 16);
+  const src = evt.sessionRef ? ` (${evt.sessionRef})` : '';
+  return `- \`${ts}\`${src} ${evt.text}`;
+}
+
+function formatHandoff(payload) {
+  if (!payload) return null;
+  const lines = [];
+  if (payload.last_step) lines.push(`**Last step.** ${payload.last_step}`);
+  if (payload.status) lines.push(`**Status.** ${payload.status}`);
+  if (payload.next) lines.push(`**Next.** ${payload.next}`);
+  if (Array.isArray(payload.blockers) && payload.blockers.length > 0) {
+    lines.push(`**Blockers.**`);
+    for (const b of payload.blockers) lines.push(`- ${b}`);
+  }
+  if (Array.isArray(payload.open_loops) && payload.open_loops.length > 0) {
+    lines.push(`**Open loops.**`);
+    for (const l of payload.open_loops) lines.push(`- ${l}`);
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : null;
+}
+
+function formatState(state) {
+  if (!state) return null;
+  const lines = [];
+  if (state.goal) lines.push(`**Goal.** ${state.goal}`);
+  if (Array.isArray(state.active_work) && state.active_work.length > 0) {
+    lines.push(`**Active work.**`);
+    for (const w of state.active_work) lines.push(`- ${w}`);
+  }
+  if (state.affect && typeof state.affect === 'object') {
+    const bits = [];
+    if (state.affect.mood) bits.push(`mood: ${state.affect.mood}`);
+    if (state.affect.energy) bits.push(`energy: ${state.affect.energy}`);
+    if (state.affect.confidence) bits.push(`confidence: ${state.affect.confidence}`);
+    if (bits.length > 0) lines.push(`**Affect.** ${bits.join(', ')}`);
+  }
+  return lines.length > 0 ? lines.join('\n') + '\n' : null;
+}
+
+// -------------------------------------------------------------------------
+// Public entry
+// -------------------------------------------------------------------------
+//
+// renderDailyMd({ aquifer, date, agentId, tenantId?, categories? }) returns:
+//   {
+//     markdown: string,
+//     artifact: { producerId, type, format, destination, payload,
+//                 idempotencyKey }  // ready for aq.artifacts.record()
+//   }
+//
+// The caller decides whether to persist the artifact record and where the
+// rendered file lands. Aquifer itself doesn't touch disk.
+
+async function renderDailyMd({
+  aquifer, date, agentId, tenantId, categories,
+  destinationTemplate = 'workspace://memory/{date}.md',
+  producerId = 'miranda.workspace.daily-log',
+}) {
+  if (!aquifer) throw new Error('aquifer instance is required');
+  if (!agentId) throw new Error('agentId is required');
+  const day = ensureDate(date);
+
+  const since = startOfDayIso(day);
+  const until = endOfDayIso(day);
+
+  const timelineResult = await aquifer.timeline.list({
+    tenantId, agentId, categories, since, until, limit: 500,
+  });
+  if (!timelineResult.ok) throw new Error(`timeline.list failed: ${timelineResult.error.message}`);
+
+  const stateResult = await aquifer.state.getLatest({ tenantId, agentId });
+  if (!stateResult.ok) throw new Error(`state.getLatest failed: ${stateResult.error.message}`);
+
+  const handoffResult = await aquifer.handoff.getLatest({ tenantId, agentId });
+  if (!handoffResult.ok) throw new Error(`handoff.getLatest failed: ${handoffResult.error.message}`);
+
+  const narrativeResult = await aquifer.narratives.getLatest({ tenantId, agentId });
+  if (!narrativeResult.ok) throw new Error(`narratives.getLatest failed: ${narrativeResult.error.message}`);
+
+  const events = (timelineResult.data.rows || []).slice().sort((a, b) =>
+    new Date(a.occurredAt).getTime() - new Date(b.occurredAt).getTime());
+
+  // Group timeline by category.
+  const grouped = new Map();
+  for (const evt of events) {
+    if (!grouped.has(evt.category)) grouped.set(evt.category, []);
+    grouped.get(evt.category).push(evt);
+  }
+
+  const sections = [];
+  sections.push(`# ${day}\n`);
+  const stateBlock = formatState(stateResult.data.state);
+  if (stateBlock) sections.push(`## State\n\n${stateBlock}`);
+
+  if (narrativeResult.data.narrative) {
+    sections.push(`## Narrative\n\n${narrativeResult.data.narrative.text}\n`);
+  }
+
+  const categoryOrder = ['focus', 'todo', 'mood', 'handoff', 'narrative',
+    'organized', 'note', 'stats', 'health', 'garmin', 'weekly', 'monthly', 'cli'];
+  const emitted = new Set();
+  for (const cat of categoryOrder) {
+    if (!grouped.has(cat)) continue;
+    const lines = grouped.get(cat).map(formatTimelineLine);
+    const sec = renderSection(cat.charAt(0).toUpperCase() + cat.slice(1), lines);
+    if (sec) sections.push(sec);
+    emitted.add(cat);
+  }
+  for (const [cat, evts] of grouped) {
+    if (emitted.has(cat)) continue;
+    const lines = evts.map(formatTimelineLine);
+    const sec = renderSection(cat, lines);
+    if (sec) sections.push(sec);
+  }
+
+  const handoffBlock = formatHandoff(handoffResult.data.handoff);
+  if (handoffBlock) sections.push(`## Handoff\n\n${handoffBlock}`);
+
+  const markdown = sections.join('\n').replace(/\n{3,}/g, '\n\n').trim() + '\n';
+
+  const destination = destinationTemplate.replace('{date}', day);
+  const idempotencyKey = crypto.createHash('sha256')
+    .update(`miranda:daily:${tenantId || 'default'}:${agentId}:${day}`)
+    .digest('hex');
+
+  return {
+    markdown,
+    artifact: {
+      producerId,
+      type: 'daily-log',
+      format: 'markdown',
+      destination,
+      triggerPhase: 'artifact_dispatch',
+      payload: {
+        date: day,
+        event_count: events.length,
+        has_state: !!stateResult.data.state,
+        has_handoff: !!handoffResult.data.handoff,
+        has_narrative: !!narrativeResult.data.narrative,
+      },
+      idempotencyKey,
+    },
+  };
+}
+
+module.exports = { renderDailyMd };

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,
 };