@shadowforge0/aquifer-memory 1.3.0 → 1.5.9

package/README.md

@@ -132,6 +132,8 @@ Need LLM summarization, the knowledge graph, OpenAI embeddings, or the reranker?
 | `AQUIFER_RERANK_PROVIDER` | No | Reranker provider: `tei`, `jina`, `openrouter` | `tei` |
 | `AQUIFER_RERANK_BASE_URL` | No | Reranker endpoint | `http://localhost:8080` |
 | `AQUIFER_AGENT_ID` | No | Default agent ID | `main` |
+| `AQUIFER_MIGRATIONS_MODE` | No | Startup handshake mode: `apply` (default), `check`, `off` | `apply` |
+| `AQUIFER_MIGRATION_LOCK_TIMEOUT_MS` | No | Advisory-lock wait before `AQ_MIGRATION_LOCK_TIMEOUT` (default 30000) | `30000` |
 
 Full env-to-config mapping is in [consumers/shared/config.js](consumers/shared/config.js).
 
@@ -377,9 +379,36 @@ Returns an Aquifer instance. Config:
 }
 ```
 
+#### `aquifer.init()`
+
+Startup handshake — resolves pending migrations and returns a StartupEnvelope. Hosts should `await` this before accepting traffic. In `apply` mode a `ready=false` envelope is the signal to abort startup.
+
+```javascript
+const envelope = await aquifer.init();
+// {
+//   ready:             true,
+//   memoryMode:        'rw',        // 'rw' | 'ro' | 'off'
+//   migrationMode:     'apply',     // 'apply' | 'check' | 'off'
+//   pendingMigrations: [],          // migration ids still outstanding
+//   appliedMigrations: ['001-base', '003-trust-feedback', '004-completion', '006-insights'],
+//   error:             null,        // { code, message } on failure
+//   durationMs:        1035,
+// }
+```
+
+The MCP consumer (`consumers/mcp.js`) already wires `aquifer.init()` before `server.connect()` and exits non-zero if `ready=false` under `apply` mode.
+
+#### `aquifer.listPendingMigrations()` / `aquifer.getMigrationStatus()`
+
+Returns `{ required, applied, pending, lastRunAt }` via a `pg_tables` signature probe. No DDL runs. Use it from a health check or from a consumer that wants to surface drift before calling `init()`.
+
 #### `aquifer.migrate()`
 
-Runs SQL migrations (idempotent). Creates tables, indexes, triggers, and extensions.
+Runs SQL migrations (idempotent). Creates tables, indexes, triggers, and extensions. Uses `pg_try_advisory_lock` with a 250 ms poll and a `lockTimeoutMs` deadline (30 s default); on exhaustion throws with `code: 'AQ_MIGRATION_LOCK_TIMEOUT'`. On success returns `{ ok: true, durationMs, notices, ddlExecuted }`; on failure throws an error whose `err.notices` / `err.failedAt` describe the stage that blew up. Most callers should go through `aquifer.init()` instead.
+
+#### `aquifer.ensureMigrated()`
+
+Lazy idempotent wrapper — fires `migrate()` once on first call, no-ops afterwards. Honors `migrations.mode`: `check` only probes, `off` marks the instance migrated without touching the DB.
 
 #### `aquifer.commit(sessionId, messages, opts)`
 
@@ -463,6 +492,26 @@ const result = await aquifer.bootstrap({
 
 Cross-session dedup on open loops and decisions, sentinel filtering (removes 無/none/n/a), and maxChars truncation.
 
+#### `aquifer.insights.commitInsight(opts)` / `recallInsights(query, opts)` / `markStale(id)` / `supersede(oldId, newId)`
+
+Higher-order reflections distilled from session windows (preferences, patterns, frustrations, workflows). Split into two identities: a **canonical key** that describes what the insight is *about* (stable across rewordings), and an **idempotency key** that describes which revision of that claim was written.
+
+```javascript
+await aquifer.insights.commitInsight({
+  agentId:        'main',
+  type:           'preference',
+  canonicalClaim: 'mk prefers checking context before coding',  // required — short declarative claim
+  title:          'Context-first discipline',                    // best-effort display
+  body:           '…',
+  entities:       ['mk', 'claude code'],
+  sourceSessionIds: ['sess-a', 'sess-b'],
+  evidenceWindow:  { from: isoString, to: isoString },
+  importance:     0.9,
+});
+```
+
+Write rules: **duplicate** (same idempotency key → return existing), **revision** (same canonical key + newer evidence → INSERT + inline supersede of prior active), **back-fill revision** (same canonical key + older evidence → INSERT without supersede), **stale replay** (same canonical + same body → return existing). Old pre-1.5.6 rows are not retrofitted; their `canonical_key_v2` stays `NULL` and they age out naturally.
+
 #### `aquifer.close()`
 
 Closes the PostgreSQL connection pool (only if Aquifer created it).
@@ -498,9 +547,19 @@ createAquifer({
     access: 0.10,              // access frequency weight
     entityBoost: 0.18,         // entity match boost
   },
+  migrations: {
+    mode: 'apply',             // 'apply' | 'check' | 'off'
+    lockTimeoutMs: 30000,      // abort init() if advisory lock held this long
+    startupTimeoutMs: 60000,   // overall init() deadline (plan probe + DDL combined)
+    onEvent: null,             // (e) => void — lifecycle hook, see below
+  },
 });
 ```
 
+### Startup observability
+
+Set `migrations.onEvent` to observe the lifecycle without parsing logs. Event names: `init_started`, `check_completed`, `apply_started`, `apply_succeeded`, `apply_failed`. Each payload carries `schema`, `mode`, the plan, `ddlExecuted`, `durationMs`, and on failure the `error` / `failedAt` / `notices`. No listener → zero cost.
+
 ### Entity Scope
 
 `entities.scope` defines the namespace for entity identity. The unique constraint is `(tenant_id, normalized_name, entity_scope)` — the same entity name in different scopes creates separate entities. This decouples entity identity from `agentId`, allowing multiple agents to share an entity namespace.
@@ -542,6 +601,22 @@ Key indexes: trigram on entity names, GiST on embeddings, unique on `(tenant_id,
 
 Also adds `trust_score` column to `session_summaries` (default 0.5, range 0–1).
 
+### 005-entity-state-history.sql *(entities enabled)*
+
+| Table | Purpose |
+|-------|---------|
+| `entity_state_history` | Temporal state-change log with partial `UNIQUE (tenant, agent, entity, attribute) WHERE valid_to IS NULL` to enforce at-most-one-current. Out-of-order backfill is supported via predecessor/successor overlap checks |
+
+Opt-in pipeline (`createAquifer({stateChanges: {enabled, whitelist, confidenceThreshold, timeoutMs, ...}})`) extracts temporal state transitions from session text during `enrich()`; off by default to control LLM cost.
+
+### 006-insights.sql
+
+| Table | Purpose |
+|-------|---------|
+| `insights` | Higher-order reflections with TSTZRANGE evidence window, importance, GIN on source_session_ids, HNSW on 1024-dim embedding, and a non-unique partial index on `canonical_key_v2` for the canonical/revision dedup contract |
+
+Key indexes: `idx_insights_canonical_v2_active` (partial on active rows with canonical key set), `idx_insights_idempotency_key` (unique on revision key).
+
 ---
 
 ## Troubleshooting
@@ -556,6 +631,10 @@ Also adds `trust_score` column to `session_summaries` (default 0.5, range 0–1)
 
 **Embedding provider connection refused** — Verify your `AQUIFER_EMBED_BASE_URL` is reachable. For local Ollama, make sure the server is running and the model is pulled (`ollama pull bge-m3`).
 
+**`AQ_MIGRATION_LOCK_TIMEOUT` on startup** — another process holds the migration advisory lock for `aquifer:<schema>`. Either it is a concurrent `aquifer.init()` racing yours (expected; one will win, the other re-runs and finds `pending=[]`) or a crashed worker left the lock held. Raise `migrations.lockTimeoutMs`, or drop the stale backend via `SELECT pg_terminate_backend(pid) FROM pg_locks WHERE locktype='advisory'` after you have confirmed which pid is dead.
+
+**MCP process exits non-zero at startup** — expected when `migrations.mode=apply` and `aquifer.init()` returns `ready=false`. Read the `[aquifer-mcp] startup aborted` line on stderr for the `error.code` / `failedAt`. If you need the old lazy-migrate-on-first-tool-call behaviour instead, set `AQUIFER_MIGRATIONS_MODE=check` (and run `migrate()` out of band) or `=off`.
+
 ---
 
 ## Dependencies

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