@shadowforge0/aquifer-memory 1.3.0 → 1.5.9

package/core/insights.js

@@ -0,0 +1,499 @@
+'use strict';
+
+// aquifer.insights.* — higher-order observations distilled from sessions.
+//
+// Insight types: preference / pattern / frustration / workflow.
+// Recall blends semantic similarity (vector), importance, and recency
+// (linear decay over recencyWindowDays, default 90).
+//
+// Lifecycle is EXPLICIT — no read-time "auto-stale". Statuses:
+//   'active'     — returned by recall by default
+//   'stale'      — set via markStale(id); recall excludes unless includeStale
+//   'superseded' — set via supersede(oldId, newId); excluded unless includeStale
+// The scripts/extract-insights-from-recent-sessions.js cron job is the
+// only thing that typically calls supersede() (when a newer extraction run
+// fully covers the old evidence).
+
+const crypto = require('crypto');
+const { ok, err } = require('./errors');
+const { normalizeEntityName } = require('./entity');
+
+const VALID_TYPES = new Set(['preference', 'pattern', 'frustration', 'workflow']);
+
+const DEFAULT_RECALL_WEIGHTS = Object.freeze({
+  semantic: 0.65,
+  importance: 0.25,
+  recency: 0.10,
+});
+
+// Recency linear decay horizon — an insight is treated as "fully recent" at
+// creation (age=0) and "zero recency" at age >= recencyWindowDays. Beyond,
+// recency contribution is clamped to 0 rather than going negative. Configurable
+// via createAquifer({ insights: { recencyWindowDays } }).
+const DEFAULT_RECENCY_WINDOW_DAYS = 90;
+
+const LEADING_PUNCT_RE = /^[\s\-_.,;:!?'"()\[\]{}@#]+/;
+const TRAILING_PUNCT_RE = /[\s\-_.,;:!?'"()\[\]{}@#]+$/;
+
+function _normalizeText(input) {
+  if (typeof input !== 'string' || !input) return '';
+  let s = input.normalize('NFKC');
+  s = s.toLowerCase();
+  s = s.replace(/\s+/g, ' ');
+  s = s.replace(LEADING_PUNCT_RE, '');
+  s = s.replace(TRAILING_PUNCT_RE, '');
+  return s;
+}
+
+function normalizeCanonicalClaim(text) {
+  return _normalizeText(text);
+}
+
+function normalizeBody(text) {
+  return _normalizeText(text);
+}
+
+function normalizeEntitySet(entities) {
+  if (!entities || !Array.isArray(entities)) return '';
+  const { normalizeEntityName } = require('./entity');
+  const normalized = entities
+    .map(e => normalizeEntityName(e))
+    .filter(Boolean);
+  const deduped = [...new Set(normalized)];
+  deduped.sort();
+  return deduped.join('|');
+}
+
+function defaultCanonicalKey({ tenantId, agentId, type, canonicalClaim, entities }) {
+  const normClaim = normalizeCanonicalClaim(canonicalClaim);
+  const normEntities = normalizeEntitySet(entities);
+  const input = `${tenantId || ''}|${agentId || ''}|${type || ''}|${normClaim}|${normEntities}`;
+  return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+function defaultIdempotencyKey({
+  tenantId, agentId, type, title, body, sourceSessionIds, evidenceWindow,
+}) {
+  const sorted = (sourceSessionIds || []).slice().sort().join('|');
+  const winFrom = evidenceWindow && evidenceWindow.from ? new Date(evidenceWindow.from).toISOString() : '';
+  const winTo = evidenceWindow && evidenceWindow.to ? new Date(evidenceWindow.to).toISOString() : '';
+  // Hash must include body + window so legitimate revisions (same sessions but
+  // tightened body, or extended window) get a new key and replace the old row
+  // via supersede, not get swallowed as a duplicate.
+  return crypto.createHash('sha256')
+    .update(`${tenantId}|${agentId}|${type}|${title}|${body || ''}|${sorted}|${winFrom}|${winTo}`)
+    .digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Canonical identity helpers (Phase 2 C1)
+//
+// Two-layer identity:
+//   canonical_key_v2 — "which claim is this" (type + canonicalClaim + entitySet)
+//   idempotency_key  — "which revision of that claim" (legacy, unchanged)
+//
+// canonicalClaim is produced by the extractor LLM (a normalized declarative
+// claim without rhetoric/examples/time words). Title/body/sessions/window
+// are revision-level and stay out of canonical_key_v2.
+// ---------------------------------------------------------------------------
+
+function normalizeCanonicalClaim(text) {
+  if (typeof text !== 'string') return '';
+
+  let s = text.normalize('NFKC');
+  s = s.toLowerCase();
+  s = s.replace(/\s+/g, ' ');
+  s = s.trim();
+  s = s.replace(/^[\s\-_.,;:!?'"()\[\]{}]+/, '');
+  s = s.replace(/[\s\-_.,;:!?'"()\[\]{}]+$/, '');
+
+  return s;
+}
+
+function normalizeBody(text) {
+  return normalizeCanonicalClaim(text);
+}
+
+function normalizeEntitySet(entities) {
+  if (!Array.isArray(entities) || entities.length === 0) return '';
+
+  return [...new Set(
+    entities
+      .map(entity => normalizeEntityName(entity))
+      .filter(Boolean)
+  )]
+    .sort()
+    .join('|');
+}
+
+function defaultCanonicalKey({ tenantId, agentId, type, canonicalClaim, entities }) {
+  return crypto.createHash('sha256')
+    .update(`${tenantId ?? ''}|${agentId ?? ''}|${type ?? ''}|${normalizeCanonicalClaim(canonicalClaim)}|${normalizeEntitySet(entities)}`)
+    .digest('hex');
+}
+
+// Parse the upper bound of a tstzrange returned by node-postgres as a raw
+// string (default mapping when range types aren't explicitly parsed). Accepts
+// the forms `[lower,upper)` / `(lower,upper]` / infinity sentinels.
+function parseUpperFromRange(raw) {
+  if (!raw || typeof raw !== 'string') return null;
+  const m = raw.match(/^[[(]([^,]*),([^)\]]*)[\])]$/);
+  if (!m) return null;
+  const upper = m[2].trim().replace(/^"|"$/g, '');
+  if (!upper || upper === 'infinity') return null;
+  const d = new Date(upper);
+  return Number.isFinite(d.getTime()) ? d : null;
+}
+
+// Revision-level idempotency key: same claim (canonicalKeyV2) + same body +
+// same source sessions + same evidence window = duplicate. Body tightening or
+// window extension produces a new revision (old one is superseded).
+function revisionIdempotencyKey({ canonicalKeyV2, body, sourceSessionIds, fromIso, toIso }) {
+  const sorted = (sourceSessionIds || []).slice().sort().join('|');
+  return crypto.createHash('sha256')
+    .update(`${canonicalKeyV2}|${normalizeBody(body)}|${sorted}|${fromIso || ''}|${toIso || ''}`)
+    .digest('hex');
+}
+
+function vecToPgLiteral(v) {
+  if (!Array.isArray(v) || v.length === 0) return null;
+  return `[${v.join(',')}]`;
+}
+
+function mapRow(row) {
+  if (!row) return null;
+  return {
+    id: Number(row.id),
+    tenantId: row.tenant_id,
+    agentId: row.agent_id,
+    insightType: row.insight_type,
+    title: row.title,
+    body: row.body,
+    sourceSessionIds: row.source_session_ids || [],
+    evidenceWindow: row.evidence_window,  // raw tstzrange string from PG
+    importance: (row.importance !== null && row.importance !== undefined) ? Number(row.importance) : null,
+    status: row.status,
+    supersededBy: (row.superseded_by !== null && row.superseded_by !== undefined) ? Number(row.superseded_by) : null,
+    idempotencyKey: row.idempotency_key || null,
+    canonicalKeyV2: row.canonical_key_v2 || null,
+    metadata: row.metadata || {},
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    score: (row._score !== null && row._score !== undefined) ? Number(row._score) : undefined,
+    semanticScore: (row._semantic_score !== null && row._semantic_score !== undefined) ? Number(row._semantic_score) : undefined,
+  };
+}
+
+function createInsights({ pool, schema, defaultTenantId, embedFn, recallWeights, recencyWindowDays }) {
+  if (!pool) throw new Error('createInsights: pool is required');
+  if (!schema) throw new Error('createInsights: schema is required');
+
+  const weights = { ...DEFAULT_RECALL_WEIGHTS, ...(recallWeights || {}) };
+  const recencyWindow = Number.isFinite(recencyWindowDays) && recencyWindowDays > 0
+    ? recencyWindowDays : DEFAULT_RECENCY_WINDOW_DAYS;
+  const tbl = `${schema}.insights`;
+
+  // -------------------------------------------------------------------------
+  // commitInsight
+  // -------------------------------------------------------------------------
+  async function commitInsight(input = {}) {
+    try {
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const agentId = input.agentId;
+      if (!agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      const type = input.type;
+      if (!VALID_TYPES.has(type)) return err('AQ_INVALID_INPUT', `type must be one of ${[...VALID_TYPES].join('|')}`);
+      const title = typeof input.title === 'string' ? input.title.trim() : '';
+      if (!title) return err('AQ_INVALID_INPUT', 'title must be non-empty string');
+      const body = typeof input.body === 'string' ? input.body.trim() : '';
+      if (!body) return err('AQ_INVALID_INPUT', 'body must be non-empty string');
+      const sourceSessionIds = Array.isArray(input.sourceSessionIds) ? input.sourceSessionIds : [];
+      if (!sourceSessionIds.length) return err('AQ_INVALID_INPUT', 'sourceSessionIds must contain at least one id');
+      const win = input.evidenceWindow || {};
+      if (!win.from || !win.to) return err('AQ_INVALID_INPUT', 'evidenceWindow.from and .to are required');
+      const fromIso = new Date(win.from).toISOString();
+      const toIso = new Date(win.to).toISOString();
+      if (!Number.isFinite(new Date(fromIso).getTime()) || !Number.isFinite(new Date(toIso).getTime())) {
+        return err('AQ_INVALID_INPUT', 'evidenceWindow.from / .to must parse to timestamps');
+      }
+      const importance = (input.importance !== null && input.importance !== undefined) ? Number(input.importance) : 0.5;
+      if (!Number.isFinite(importance) || importance < 0 || importance > 1) {
+        return err('AQ_INVALID_INPUT', 'importance must be in [0,1]');
+      }
+      let metadata = input.metadata && typeof input.metadata === 'object' ? input.metadata : {};
+
+      // ---------------------------------------------------------------------
+      // Phase 2 C1: two-layer identity.
+      //   canonicalKeyV2 = "which claim" (type + canonicalClaim + entitySet)
+      //   idempotencyKey = "which revision of that claim"
+      // canonicalClaim comes from the extractor LLM; when absent we fall back
+      // to title and flag dedupQuality so callers know the dedupe is weak.
+      // ---------------------------------------------------------------------
+      const canonicalClaim = typeof input.canonicalClaim === 'string' ? input.canonicalClaim : '';
+      const entities = Array.isArray(input.entities) ? input.entities : [];
+      const canonicalKeyV2 = input.canonicalKey
+        || defaultCanonicalKey({
+          tenantId, agentId, type,
+          canonicalClaim: canonicalClaim || title,
+          entities,
+        });
+
+      if (!input.canonicalClaim && !input.canonicalKey) {
+        metadata = { ...metadata, dedupQuality: 'title_fallback' };
+      }
+
+      const idempotencyKey = input.idempotencyKey
+        || revisionIdempotencyKey({
+          canonicalKeyV2, body, sourceSessionIds, fromIso, toIso,
+        });
+
+      // Step A — revision dedupe. Exact same claim/body/sessions/window.
+      const existing = await pool.query(
+        `SELECT * FROM ${tbl} WHERE idempotency_key = $1 LIMIT 1`,
+        [idempotencyKey]
+      );
+      if (existing.rowCount > 0) return ok({ insight: mapRow(existing.rows[0]), duplicate: true });
+
+      // Step B — canonical lookup: is this claim already active? If so, decide
+      // between stale replay (incoming window older than active) vs revision
+      // (incoming same or newer, body/window differ enough that Step A missed).
+      const canonLookup = await pool.query(
+        `SELECT * FROM ${tbl}
+          WHERE tenant_id = $1
+            AND agent_id = $2
+            AND insight_type = $3
+            AND canonical_key_v2 = $4
+            AND status = 'active'
+          ORDER BY created_at DESC
+          LIMIT 1`,
+        [tenantId, agentId, type, canonicalKeyV2]
+      );
+
+      let toSupersede = null;
+      if (canonLookup.rowCount > 0) {
+        const activeRow = canonLookup.rows[0];
+        const activeUpper = parseUpperFromRange(activeRow.evidence_window);
+        // Rule 4 — stale replay: incoming evidence is older than what's
+        // already active. Keep the active row, tell caller it's a duplicate.
+        if (activeUpper && new Date(toIso).getTime() < activeUpper.getTime()) {
+          return ok({ insight: mapRow(activeRow), duplicate: true });
+        }
+        // Rule 2/3 — revision: different revision key, incoming window is not
+        // stale. Insert new and mark the previous active row as superseded.
+        toSupersede = Number(activeRow.id);
+      }
+
+      // Optional embedding.
+      let embedding = null;
+      if (embedFn) {
+        try {
+          const v = await embedFn([`${title}\n\n${body}`]);
+          if (Array.isArray(v) && Array.isArray(v[0])) embedding = vecToPgLiteral(v[0]);
+        } catch {
+          // Embed failure is non-fatal — insight saved without semantic recall path.
+        }
+      }
+
+      const evidenceRange = `[${fromIso},${toIso})`;
+      const inserted = await pool.query(
+        `INSERT INTO ${tbl}
+          (tenant_id, agent_id, insight_type, title, body, source_session_ids,
+           evidence_window, embedding, importance, status, idempotency_key,
+           canonical_key_v2, metadata)
+         VALUES ($1,$2,$3,$4,$5,$6, $7::tstzrange, $8::vector, $9, 'active', $10, $11, $12::jsonb)
+         RETURNING *`,
+        [tenantId, agentId, type, title, body, sourceSessionIds,
+         evidenceRange, embedding, importance, idempotencyKey,
+         canonicalKeyV2, JSON.stringify(metadata)]
+      );
+      const newRow = inserted.rows[0];
+
+      // Best-effort supersede of the prior active revision. Insights are
+      // eventually consistent — if the old row was already superseded by a
+      // racing writer, log and continue without failing the new insert.
+      if (toSupersede && Number(newRow.id) !== toSupersede) {
+        try {
+          await pool.query(
+            `UPDATE ${tbl}
+                SET status = 'superseded', superseded_by = $2, updated_at = now()
+              WHERE id = $1 AND status = 'active'`,
+            [toSupersede, Number(newRow.id)]
+          );
+        } catch {
+          // swallow — new row is already persisted
+        }
+      }
+
+      return ok({ insight: mapRow(newRow), duplicate: false });
+    } catch (e) {
+      if (/duplicate key/.test(e.message)) return err('AQ_CONFLICT', e.message);
+      return err('AQ_INTERNAL', e.message);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // recallInsights
+  // -------------------------------------------------------------------------
+  async function recallInsights(query, input = {}) {
+    try {
+      const tenantId = input.tenantId || defaultTenantId || 'default';
+      const agentId = input.agentId;
+      if (!agentId) return err('AQ_INVALID_INPUT', 'agentId is required');
+      const type = input.type || null;
+      if (type && !VALID_TYPES.has(type)) {
+        return err('AQ_INVALID_INPUT', `type must be one of ${[...VALID_TYPES].join('|')}`);
+      }
+      const limit = Math.max(1, Math.min(50, Number(input.limit) || 5));
+      const minImportance = (input.minImportance !== null && input.minImportance !== undefined) ? Number(input.minImportance) : 0;
+      const includeStale = input.includeStale === true;
+
+      const where = ['tenant_id = $1', 'agent_id = $2', 'importance >= $3'];
+      const params = [tenantId, agentId, minImportance];
+      if (!includeStale) where.push(`status = 'active'`);
+      if (type) {
+        params.push(type);
+        where.push(`insight_type = $${params.length}`);
+      }
+
+      // Empty query → blend importance × recency (linear decay over
+      // recencyWindow days), no semantic component. Falls back to created_at
+      // DESC as tiebreak so identical blended scores remain deterministic.
+      if (!query || typeof query !== 'string' || !query.trim()) {
+        params.push(recencyWindow);
+        const winPos = params.length;
+        params.push(weights.importance);
+        const wImpPos = params.length;
+        params.push(weights.recency);
+        const wRecPos = params.length;
+        params.push(limit);
+        const r = await pool.query(
+          `SELECT *,
+            (
+              $${wImpPos}::real * importance +
+              $${wRecPos}::real * GREATEST(0, 1.0 - (extract(epoch FROM (now() - created_at)) / 86400.0) / $${winPos}::real)
+            ) AS _score
+           FROM ${tbl}
+           WHERE ${where.join(' AND ')}
+           ORDER BY _score DESC, created_at DESC
+           LIMIT $${params.length}`,
+          params
+        );
+        return ok({ rows: r.rows.map(mapRow) });
+      }
+
+      // Vector recall: requires embedFn.
+      if (!embedFn) return err('AQ_DEPENDENCY', 'recallInsights with query requires embedFn');
+      let queryVec;
+      try {
+        const v = await embedFn([query]);
+        queryVec = vecToPgLiteral(v[0]);
+      } catch (e) {
+        return err('AQ_DEPENDENCY', `embedFn failed: ${e.message}`);
+      }
+      if (!queryVec) return err('AQ_DEPENDENCY', 'embedFn returned empty vector');
+
+      params.push(queryVec);
+      const vecPos = params.length;
+      params.push(weights.semantic);
+      const wSemPos = params.length;
+      params.push(weights.importance);
+      const wImpPos = params.length;
+      params.push(weights.recency);
+      const wRecPos = params.length;
+      params.push(limit);
+      const limitPos = params.length;
+
+      params.push(recencyWindow);
+      const winPos = params.length;
+      const r = await pool.query(
+        `WITH scored AS (
+          SELECT *,
+            1.0 - (embedding <=> $${vecPos}::vector) AS _semantic_score,
+            extract(epoch FROM (now() - created_at)) / 86400.0 AS _age_days
+          FROM ${tbl}
+          WHERE embedding IS NOT NULL
+            AND ${where.join(' AND ')}
+        )
+        SELECT *,
+          (
+            $${wSemPos}::real * GREATEST(0, _semantic_score) +
+            $${wImpPos}::real * importance +
+            $${wRecPos}::real * GREATEST(0, 1.0 - _age_days / $${winPos}::real)
+          ) AS _score
+        FROM scored
+        ORDER BY _score DESC
+        LIMIT $${limitPos}`,
+        params
+      );
+      return ok({ rows: r.rows.map(mapRow) });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // markStale / supersede — explicit lifecycle (callers / scripts use these).
+  // -------------------------------------------------------------------------
+  async function markStale(insightId) {
+    try {
+      const id = Number(insightId);
+      if (!Number.isInteger(id) || id <= 0) return err('AQ_INVALID_INPUT', 'insightId must be positive integer');
+      const r = await pool.query(
+        `UPDATE ${tbl} SET status='stale', updated_at=now()
+         WHERE id=$1 AND status <> 'stale' RETURNING id, status`,
+        [id]
+      );
+      if (r.rowCount === 0) return err('AQ_NOT_FOUND', `insight ${id} not found or already stale`);
+      return ok({ id: Number(r.rows[0].id), status: r.rows[0].status });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message);
+    }
+  }
+
+  async function supersede(oldId, newId) {
+    try {
+      const o = Number(oldId), n = Number(newId);
+      if (!Number.isInteger(o) || !Number.isInteger(n)) return err('AQ_INVALID_INPUT', 'oldId/newId must be integers');
+      if (o === n) return err('AQ_INVALID_INPUT', 'oldId and newId must differ (no self-supersede)');
+      // Verify both exist and share tenant + agent. FK alone would allow a
+      // caller with a cross-tenant id to form an illegal supersession chain.
+      const vr = await pool.query(
+        `SELECT id, tenant_id, agent_id FROM ${tbl} WHERE id = ANY($1)`,
+        [[o, n]]
+      );
+      if (vr.rowCount < 2) return err('AQ_NOT_FOUND', `insight ${o} or ${n} not found`);
+      const oldRow = vr.rows.find(r => Number(r.id) === o);
+      const newRow = vr.rows.find(r => Number(r.id) === n);
+      if (!oldRow || !newRow) return err('AQ_NOT_FOUND', `insight ${o} or ${n} not found`);
+      if (oldRow.tenant_id !== newRow.tenant_id || oldRow.agent_id !== newRow.agent_id) {
+        return err('AQ_CONFLICT', `supersede crosses tenant/agent: old=${oldRow.tenant_id}/${oldRow.agent_id}, new=${newRow.tenant_id}/${newRow.agent_id}`);
+      }
+      const r = await pool.query(
+        `UPDATE ${tbl} SET status='superseded', superseded_by=$2, updated_at=now()
+         WHERE id=$1 AND status <> 'superseded' RETURNING id, status, superseded_by`,
+        [o, n]
+      );
+      if (r.rowCount === 0) return err('AQ_NOT_FOUND', `insight ${o} not found or already superseded`);
+      return ok({ id: Number(r.rows[0].id), status: r.rows[0].status, supersededBy: Number(r.rows[0].superseded_by) });
+    } catch (e) {
+      return err('AQ_INTERNAL', e.message);
+    }
+  }
+
+  return {
+    commitInsight,
+    recallInsights,
+    markStale,
+    supersede,
+    _internal: { defaultIdempotencyKey, vecToPgLiteral, mapRow, weights },
+  };
+}
+
+module.exports = {
+  createInsights,
+  defaultIdempotencyKey,
+  defaultCanonicalKey,
+  normalizeCanonicalClaim,
+  normalizeBody,
+  normalizeEntitySet,
+};

package/core/mcp-manifest.js

@@ -20,7 +20,7 @@ const MCP_SERVER_NAME = 'aquifer-memory';
 const MCP_TOOL_MANIFEST = Object.freeze([
   {
     name: 'session_recall',
-    description: 'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
+    description: 'Search stored sessions by keyword or natural language. Use entities when the user names specific people, projects, files, tools, or concepts; entityMode="all" hard-filters to sessions containing every entity (default "any" boosts). Use mode to force fts/vector/hybrid (default hybrid). Use dateFrom/dateTo for time-bounded recall.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,

package/core/storage.js

@@ -59,7 +59,7 @@ async function upsertSession(pool, {
       (tenant_id, session_id, session_key, agent_id, source, messages,
        msg_count, user_count, assistant_count, model, tokens_in, tokens_out,
        started_at, ended_at, last_message_at, processing_status)
-    VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,now(),$14,'pending')
+    VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,COALESCE($13,now()),COALESCE($14,now()),$14,'pending')
     ON CONFLICT (tenant_id, agent_id, session_id) DO UPDATE SET
       session_key = EXCLUDED.session_key,
       source = COALESCE(EXCLUDED.source, ${qi(schema)}.sessions.source),
@@ -71,7 +71,7 @@ async function upsertSession(pool, {
       tokens_in = EXCLUDED.tokens_in,
       tokens_out = EXCLUDED.tokens_out,
       started_at = COALESCE(EXCLUDED.started_at, ${qi(schema)}.sessions.started_at),
-      ended_at = now(),
+      ended_at = COALESCE(EXCLUDED.last_message_at, ${qi(schema)}.sessions.ended_at),
       last_message_at = COALESCE(EXCLUDED.last_message_at, ${qi(schema)}.sessions.last_message_at),
       processing_status = 'pending',
       processing_error = NULL
@@ -223,9 +223,13 @@ async function searchSessions(pool, query, {
   dateFrom,
   dateTo,
   limit = 20,
+  ftsConfig = 'simple',
 } = {}) {
   const clampedLimit = Math.max(1, Math.min(100, limit));
 
+  // Whitelist tsconfig to prevent injection
+  const cfg = (ftsConfig === 'zhcfg' || ftsConfig === 'simple') ? ftsConfig : 'simple';
+
   // Normalize agentId/agentIds
   const agentIds = rawAgentIds && rawAgentIds.length > 0
     ? rawAgentIds
@@ -237,7 +241,7 @@ async function searchSessions(pool, query, {
   // Primary: trigram ILIKE on search_text (works for CJK + Latin)
   // Fallback: tsvector FTS (for installations without search_text populated)
   const where = [
-    `(ss.search_text ILIKE '%' || $1 || '%' OR ss.search_tsv @@ plainto_tsquery('simple', $2))`,
+    `(ss.search_text ILIKE '%' || $1 || '%' OR ss.search_tsv @@ plainto_tsquery('${cfg}', $2))`,
     `s.tenant_id = $3`,
   ];
   const params = [likeQuery, query, tenantId];
@@ -276,10 +280,15 @@ async function searchSessions(pool, query, {
       ss.trust_score,
       CASE WHEN ss.search_text IS NOT NULL
         THEN similarity(ss.search_text, $2)
-        ELSE ts_rank(ss.search_tsv, plainto_tsquery('simple', $2))
+        ELSE ts_rank(ss.search_tsv, plainto_tsquery('${cfg}', $2))
       END AS fts_rank
     FROM ${qi(schema)}.sessions s
-    LEFT JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
+    -- INNER JOIN: the WHERE clause references ss.search_text / ss.search_tsv,
+    -- which a LEFT JOIN would leave NULL for unenriched sessions — filtering
+    -- them out. Be explicit: FTS recall is a SUMMARIZED-sessions search. Raw
+    -- unenriched sessions don't participate. Named searchSessions for historic
+    -- reasons; semantically it is search-over-enriched-sessions.
+    JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
     WHERE ${where.join(' AND ')}
     ORDER BY
       COALESCE(ss.search_text ILIKE '%' || $1 || '%', FALSE) DESC,
@@ -512,6 +521,73 @@ async function searchTurnEmbeddings(pool, {
   return { rows: fallback.rows };
 }
 
+// ---------------------------------------------------------------------------
+// searchSummaryEmbeddings — pgvector cosine search on session_summaries.embedding
+// ---------------------------------------------------------------------------
+
+async function searchSummaryEmbeddings(pool, {
+  schema,
+  tenantId,
+  queryVec,
+  agentId,
+  agentIds: rawAgentIds,
+  source,
+  dateFrom,
+  dateTo,
+  candidateSessionIds,
+  limit = 15,
+} = {}) {
+  const where = ['s.tenant_id = $1'];
+  const params = [tenantId];
+
+  params.push(`[${queryVec.join(',')}]`);
+  const vecPos = params.length;
+
+  const agentIds = rawAgentIds && rawAgentIds.length > 0
+    ? rawAgentIds
+    : (agentId ? [agentId] : null);
+
+  if (dateFrom) {
+    params.push(dateFrom);
+    where.push(`s.started_at::date >= $${params.length}::date`);
+  }
+  if (dateTo) {
+    params.push(dateTo);
+    where.push(`s.started_at::date <= $${params.length}::date`);
+  }
+  if (agentIds) {
+    params.push(agentIds);
+    where.push(`s.agent_id = ANY($${params.length})`);
+  }
+  if (source) {
+    params.push(source);
+    where.push(`s.source = $${params.length}`);
+  }
+  if (candidateSessionIds && candidateSessionIds.length > 0) {
+    params.push(candidateSessionIds);
+    where.push(`s.session_id = ANY($${params.length})`);
+  }
+
+  params.push(limit);
+
+  const result = await pool.query(
+    `SELECT
+      s.id, s.session_id, s.agent_id, s.source, s.started_at, s.last_message_at,
+      ss.summary_text, ss.structured_summary, ss.access_count, ss.last_accessed_at,
+      ss.trust_score,
+      (ss.embedding <=> $${vecPos}::vector) AS distance
+    FROM ${qi(schema)}.session_summaries ss
+    JOIN ${qi(schema)}.sessions s ON s.id = ss.session_row_id
+    WHERE ss.embedding IS NOT NULL
+      AND ${where.join(' AND ')}
+    ORDER BY distance ASC
+    LIMIT $${params.length}`,
+    params
+  );
+
+  return { rows: result.rows };
+}
+
 // ---------------------------------------------------------------------------
 // recordFeedback — explicit trust feedback with audit trail
 // ---------------------------------------------------------------------------
@@ -605,5 +681,6 @@ module.exports = {
   extractUserTurns,
   upsertTurnEmbeddings,
   searchTurnEmbeddings,
+  searchSummaryEmbeddings,
   recordFeedback,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "1.3.0",
+  "version": "1.5.9",
   "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": [