@shadowforge0/aquifer-memory 1.0.3 → 1.2.1

package/schema/004-facts.sql

@@ -0,0 +1,67 @@
+-- Aquifer facts / consolidation extension
+-- Requires: 001-base.sql applied first
+-- Usage: replace ${schema} with actual schema name
+--
+-- Facts store long-lived subject/statement pairs with a lifecycle:
+--   candidate → active → (stale | archived | superseded)
+-- Consumers write candidates during enrich (via writeFactCandidates).
+-- consolidate() then promotes / updates / confirms / archives them.
+
+-- =========================================================================
+-- Facts: long-lived current-state statements per (subject, agent)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.facts (
+  id                 BIGSERIAL    PRIMARY KEY,
+  tenant_id          TEXT         NOT NULL DEFAULT 'default',
+  subject_key        TEXT         NOT NULL,
+  subject_label      TEXT         NOT NULL,
+  statement          TEXT         NOT NULL,
+  status             TEXT         NOT NULL DEFAULT 'candidate'
+                       CHECK (status IN ('candidate','active','stale','archived','superseded')),
+  importance         SMALLINT     NOT NULL DEFAULT 5,
+  source_session_id  TEXT,
+  agent_id           TEXT         NOT NULL DEFAULT 'main',
+  evidence           JSONB        NOT NULL DEFAULT '[]'::jsonb,
+  superseded_by      BIGINT       REFERENCES ${schema}.facts(id) ON DELETE SET NULL,
+  first_seen_at      TIMESTAMPTZ  NOT NULL DEFAULT now(),
+  last_confirmed_at  TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+-- Migration: add tenant_id if upgrading from a legacy facts table (no tenant column).
+ALTER TABLE ${schema}.facts ADD COLUMN IF NOT EXISTS tenant_id TEXT NOT NULL DEFAULT 'default';
+
+-- At most one active fact per (tenant, subject, agent)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_facts_active_subject
+  ON ${schema}.facts (tenant_id, subject_key, agent_id)
+  WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_facts_active_agent
+  ON ${schema}.facts (tenant_id, agent_id, importance DESC, last_confirmed_at DESC)
+  WHERE status = 'active';
+
+CREATE INDEX IF NOT EXISTS idx_facts_status_created
+  ON ${schema}.facts (tenant_id, status, first_seen_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_facts_subject
+  ON ${schema}.facts (tenant_id, subject_key);
+
+CREATE INDEX IF NOT EXISTS idx_facts_source_session
+  ON ${schema}.facts (source_session_id)
+  WHERE source_session_id IS NOT NULL;
+
+COMMENT ON TABLE ${schema}.facts IS 'Fact candidates and active facts per (tenant, subject, agent) with consolidation lifecycle';
+
+-- =========================================================================
+-- Fact ↔ Entity join (optional, only when entities enabled)
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.fact_entities (
+  id         BIGSERIAL    PRIMARY KEY,
+  fact_id    BIGINT       NOT NULL REFERENCES ${schema}.facts(id) ON DELETE CASCADE,
+  entity_id  BIGINT       NOT NULL,
+  UNIQUE (fact_id, entity_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_fact_entities_entity_id
+  ON ${schema}.fact_entities (entity_id);
+
+COMMENT ON TABLE ${schema}.fact_entities IS 'Join table linking facts to entities (FK to entities is soft — entities table is optional)';

package/scripts/diagnose-fts-zh.js

@@ -1,161 +1,195 @@
 'use strict';
 
 /**
- * FTS 中文診斷：檢查 'simple' tokenizer 在實際中文資料上的表現
+ * Aquifer FTS 中文診斷
  *
- * 測試項目：
- * 1. FTS tokenization — 實際 token 長什麼樣
- * 2. FTS recall — 常見中文查詢的命中率
- * 3. FTS vs vector — FTS 有沒有在幫忙還是在拖後腿
+ * 測 aquifer 實際搜尋主路徑（trigram ILIKE on search_text + similarity ranking）
+ * vs fallback 路徑（tsvector @@ plainto_tsquery('simple', q)）對中文 query 的表現。
+ *
+ * env:
+ *   DATABASE_URL       — required
+ *   AQUIFER_SCHEMA     — default 'public'
+ *   DIAGNOSE_QUERIES   — comma-separated, overrides built-in set
  */
 
 const { Pool } = require('pg');
 
-const DB_URL = process.env.DATABASE_URL || 'postgresql://burk:790476@localhost:5432/openclaw_db';
-const SCHEMA = process.env.AQUIFER_SCHEMA || 'miranda';
+const DB_URL = process.env.DATABASE_URL;
+if (!DB_URL) {
+  console.error('DATABASE_URL is required');
+  process.exit(2);
+}
+const SCHEMA = process.env.AQUIFER_SCHEMA || 'public';
+
+const DEFAULT_QUERIES = [
+  // latin
+  'afterburn', 'bootstrap', 'session', 'recall', 'entity', 'OpenCode', 'Jenny', 'Aquifer',
+  // CJK short tokens — 最容易暴露 tokenizer 問題
+  '記憶', '時區', '去重', '架構', '修復',
+  // CJK phrase
+  '消化模式', 'daily entries',
+];
+const QUERIES = process.env.DIAGNOSE_QUERIES
+  ? process.env.DIAGNOSE_QUERIES.split(',').map(s => s.trim()).filter(Boolean)
+  : DEFAULT_QUERIES;
 
 const pool = new Pool({ connectionString: DB_URL });
+const qi = (s) => `"${s.replace(/"/g, '""')}"`;
 
-async function run() {
-  const qi = (s) => `"${s}"`;
-
-  console.log('=== FTS 中文診斷 ===\n');
-
-  // 1. 看 token 分佈
-  console.log('--- 1. Token 分析 ---');
-  const tokenSample = await pool.query(`
-    SELECT ss.session_id,
-           array_length(tsvector_to_array(ss.search_tsv), 1) as token_count,
-           left(ss.summary_text, 80) as preview
-    FROM ${qi(SCHEMA)}.session_summaries ss
-    WHERE ss.search_tsv IS NOT NULL
-    ORDER BY ss.updated_at DESC
-    LIMIT 10
-  `);
-
-  let totalTokens = 0;
-  let sessionCount = 0;
-  for (const r of tokenSample.rows) {
-    totalTokens += r.token_count || 0;
-    sessionCount++;
-    console.log(`  ${r.session_id?.slice(0, 8)} | ${r.token_count || 0} tokens | ${r.preview}`);
-  }
-  console.log(`  avg: ${sessionCount ? Math.round(totalTokens / sessionCount) : 0} tokens/session\n`);
+function pct(n, d) {
+  if (d === 0) return n === 0 ? '—' : '∞%';
+  return `${Math.round((n / d) * 100)}%`;
+}
 
-  // 2. 看一個 session 的實際 token
-  console.log('--- 2. Token 範例（最近 session）---');
+async function main() {
+  console.log(`=== Aquifer FTS 中文診斷 (schema=${SCHEMA}) ===\n`);
+
+  // -------------------------------------------------------------------------
+  // 0. 覆蓋率：search_text NULL 率 → 看 fallback 觸發比例
+  // -------------------------------------------------------------------------
+  const cov = await pool.query(`
+    SELECT
+      COUNT(*)                                          AS total,
+      COUNT(*) FILTER (WHERE search_text IS NOT NULL)   AS with_text,
+      COUNT(*) FILTER (WHERE search_tsv  IS NOT NULL)   AS with_tsv,
+      COUNT(*) FILTER (WHERE search_text IS NULL
+                         AND search_tsv  IS NOT NULL)   AS tsv_only
+    FROM ${qi(SCHEMA)}.session_summaries
+  `);
+  const c = cov.rows[0];
+  console.log('--- 0. 搜尋欄位覆蓋率 ---');
+  console.log(`  total rows       : ${c.total}`);
+  console.log(`  has search_text  : ${c.with_text} (${pct(c.with_text, c.total)})`);
+  console.log(`  has search_tsv   : ${c.with_tsv} (${pct(c.with_tsv, c.total)})`);
+  console.log(`  tsv-only (NULL search_text, falls back to FTS): ${c.tsv_only} (${pct(c.tsv_only, c.total)})\n`);
+
+  // -------------------------------------------------------------------------
+  // 1. Token 範例（tsvector lexeme 粒度觀察）
+  // -------------------------------------------------------------------------
+  console.log('--- 1. tsvector lexeme 粒度範例（最近 1 筆）---');
   const tokenDetail = await pool.query(`
-    SELECT ss.session_id,
-           array_to_string(tsvector_to_array(ss.search_tsv), ' | ') as tokens
-    FROM ${qi(SCHEMA)}.session_summaries ss
-    WHERE ss.search_tsv IS NOT NULL
-    ORDER BY ss.updated_at DESC
+    SELECT session_id,
+           array_length(tsvector_to_array(search_tsv), 1) AS token_count,
+           array_to_string(tsvector_to_array(search_tsv), ' | ') AS tokens
+    FROM ${qi(SCHEMA)}.session_summaries
+    WHERE search_tsv IS NOT NULL
+    ORDER BY updated_at DESC
     LIMIT 1
   `);
   if (tokenDetail.rows[0]) {
-    console.log(`  session: ${tokenDetail.rows[0].session_id?.slice(0, 8)}`);
-    const tokens = tokenDetail.rows[0].tokens || '';
-    // 分類 token
-    const all = tokens.split(' | ');
+    const r = tokenDetail.rows[0];
+    const all = (r.tokens || '').split(' | ').filter(Boolean);
     const cjk = all.filter(t => /[\u4e00-\u9fff]/.test(t));
     const latin = all.filter(t => /^[a-z0-9]/.test(t));
-    const other = all.filter(t => !(/[\u4e00-\u9fff]/.test(t)) && !(/^[a-z0-9]/.test(t)));
-    console.log(`  total: ${all.length} | latin: ${latin.length} | cjk: ${cjk.length} | other: ${other.length}`);
-    console.log(`  CJK tokens (前 20): ${cjk.slice(0, 20).join(' | ')}`);
-    console.log(`  Latin tokens (前 20): ${latin.slice(0, 20).join(' | ')}\n`);
+    console.log(`  session: ${String(r.session_id).slice(0, 8)} | total tokens: ${r.token_count || 0}`);
+    console.log(`  latin: ${latin.length} | cjk-containing: ${cjk.length}`);
+    console.log(`  CJK lexemes (前 15): ${cjk.slice(0, 15).join(' | ')}`);
+    console.log(`  → CJK lexeme 若是 phrase 級（整句無空白），簡 tokenizer 對中文短 query 會 miss\n`);
+  } else {
+    console.log('  (no rows)\n');
   }
 
-  // 3. 中文查詢命中率測試
-  console.log('--- 3. 中文查詢 FTS 命中率 ---');
-  const testQueries = [
-    'afterburn',
-    'bootstrap',
-    'session',
-    'recall',
-    '記憶',
-    '修復',
-    '架構',
-    '時區',
-    '去重',
-    'daily entries',
-    'OpenCode',
-    'entity',
-    'Jenny',
-    'Aquifer',
-    '消化模式',
-  ];
-
-  // 總 session 數
-  const totalResult = await pool.query(`
-    SELECT COUNT(*) as cnt FROM ${qi(SCHEMA)}.session_summaries WHERE search_tsv IS NOT NULL
-  `);
-  const totalSessions = parseInt(totalResult.rows[0].cnt);
-  console.log(`  total sessions with FTS index: ${totalSessions}\n`);
-
-  for (const q of testQueries) {
-    const ftsResult = await pool.query(`
-      SELECT COUNT(*) as cnt
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      WHERE ss.search_tsv @@ plainto_tsquery('simple', $1)
-    `, [q]);
-    const ftsHits = parseInt(ftsResult.rows[0].cnt);
-
-    // 同時看 summary_text ILIKE 能找到幾筆（ground truth）
-    const ilikeResult = await pool.query(`
-      SELECT COUNT(*) as cnt
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      WHERE ss.summary_text ILIKE $1
-         OR ss.structured_summary::text ILIKE $1
-    `, [`%${q}%`]);
-    const ilikeHits = parseInt(ilikeResult.rows[0].cnt);
-
-    const ftsRecall = ilikeHits > 0 ? Math.round(ftsHits / ilikeHits * 100) : (ftsHits === 0 ? 100 : 0);
-    const status = ftsHits === ilikeHits ? '✓' : (ftsHits < ilikeHits ? '✗ MISS' : '?');
-    console.log(`  "${q}" | FTS: ${ftsHits} | ILIKE: ${ilikeHits} | recall: ${ftsRecall}% | ${status}`);
-  }
-
-  // 4. FTS 對 RRF 的貢獻度
-  console.log('\n--- 4. FTS 在 hybrid search 中的貢獻度 ---');
-  // 跑幾個查詢，看 FTS 跟 vector 的 session 重疊率
-  const overlapQueries = ['afterburn', 'bootstrap', '記憶', 'recall', 'entity'];
-  for (const q of overlapQueries) {
-    const ftsResult = await pool.query(`
-      SELECT ss.session_id
-      FROM ${qi(SCHEMA)}.session_summaries ss
-      JOIN ${qi(SCHEMA)}.sessions s ON s.id = ss.session_row_id
-      WHERE ss.search_tsv @@ plainto_tsquery('simple', $1)
-        AND s.processing_status = 'succeeded'
-      ORDER BY ts_rank(ss.search_tsv, plainto_tsquery('simple', $1)) DESC
-      LIMIT 10
-    `, [q]);
-    const ftsIds = new Set(ftsResult.rows.map(r => r.session_id));
-
-    // vector search (if embedding available)
-    const embResult = await pool.query(`
-      SELECT ss.session_id
-      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 s.processing_status = 'succeeded'
-      ORDER BY ss.embedding <=> (
-        SELECT ss2.embedding FROM ${qi(SCHEMA)}.session_summaries ss2
-        WHERE ss2.search_tsv @@ plainto_tsquery('simple', $1)
-        ORDER BY ts_rank(ss2.search_tsv, plainto_tsquery('simple', $1)) DESC
-        LIMIT 1
+  // -------------------------------------------------------------------------
+  // 2. 主路徑 vs fallback：binary match 比對
+  //
+  // Ground truth = search_text ILIKE '%q%'（所有源欄位拼出的純文字 superset）
+  // 主路徑        = search_text ILIKE（GIN trgm 加速，語意等價 ILIKE）
+  // Fallback     = search_tsv @@ plainto_tsquery('simple', q)
+  // -------------------------------------------------------------------------
+  console.log('--- 2. 主路徑（trigram）vs fallback（tsvector）binary match ---');
+  console.log('  query               | truth | trgm  | tsv   | trgm% | tsv%  | tsv-extra');
+  console.log('  ' + '-'.repeat(82));
+
+  const rowCount = await pool.query(
+    `SELECT COUNT(*) AS n FROM ${qi(SCHEMA)}.session_summaries WHERE search_text IS NOT NULL`
+  );
+  const withTextN = parseInt(rowCount.rows[0].n, 10);
+  console.log(`  (ground truth 基數：含 search_text 的 row ${withTextN})`);
+
+  const summary = [];
+  for (const q of QUERIES) {
+    const r = await pool.query(
+      `
+      WITH base AS (
+        SELECT search_text,
+               search_tsv,
+               (search_text ILIKE '%' || $1 || '%')                                 AS trgm_hit,
+               (search_tsv  @@ plainto_tsquery('simple', $2))                       AS tsv_hit
+        FROM ${qi(SCHEMA)}.session_summaries
+        WHERE search_text IS NOT NULL
       )
-      LIMIT 10
-    `, [q]);
-    const embIds = new Set(embResult.rows.map(r => r.session_id));
-
-    const overlap = [...ftsIds].filter(id => embIds.has(id)).length;
-    const ftsOnly = [...ftsIds].filter(id => !embIds.has(id)).length;
-    const embOnly = [...embIds].filter(id => !ftsIds.has(id)).length;
-
-    console.log(`  "${q}" | FTS top10: ${ftsIds.size} | Vec top10: ${embIds.size} | overlap: ${overlap} | FTS-only: ${ftsOnly} | Vec-only: ${embOnly}`);
+      SELECT
+        COUNT(*) FILTER (WHERE trgm_hit)                         AS truth,
+        COUNT(*) FILTER (WHERE trgm_hit)                         AS trgm,
+        COUNT(*) FILTER (WHERE tsv_hit)                          AS tsv,
+        COUNT(*) FILTER (WHERE tsv_hit AND NOT trgm_hit)         AS tsv_extra
+      FROM base
+      `,
+      [q.replace(/[%_\\]/g, '\\$&'), q]
+    );
+    const { truth, trgm, tsv, tsv_extra } = r.rows[0];
+    const T = parseInt(truth, 10);
+    const A = parseInt(trgm, 10);
+    const B = parseInt(tsv, 10);
+    const E = parseInt(tsv_extra, 10);
+    summary.push({ q, T, A, B, E });
+    console.log(
+      `  ${q.padEnd(19)} | ${String(T).padStart(5)} | ${String(A).padStart(5)} | ${String(B).padStart(5)} | ${pct(A, T).padStart(5)} | ${pct(B, T).padStart(5)} | ${String(E).padStart(5)}`
+    );
+  }
+  console.log('  (tsv-extra = tsvector 命中但 trigram 沒命中 → 通常是 0，代表 tsv 對整體搜尋無額外貢獻)\n');
+
+  // -------------------------------------------------------------------------
+  // 3. Ranking 品質對比：舊 ranking (similarity only) vs 新 ranking (substr-hit first)
+  // -------------------------------------------------------------------------
+  console.log('--- 3. Ranking 品質對比：top-5 substring-hit 命中率 ---');
+  console.log('  query               | truth | old (sim only) | new (hit+sim)');
+  console.log('  ' + '-'.repeat(70));
+  for (const q of QUERIES) {
+    const like = q.replace(/[%_\\]/g, '\\$&');
+    const truthR = await pool.query(
+      `SELECT COUNT(*) AS n
+         FROM ${qi(SCHEMA)}.session_summaries
+         WHERE search_text ILIKE '%' || $1 || '%'`,
+      [like]
+    );
+    const T = parseInt(truthR.rows[0].n, 10);
+
+    const oldR = await pool.query(
+      `
+      SELECT (search_text ILIKE '%' || $1 || '%') AS substr_hit
+      FROM ${qi(SCHEMA)}.session_summaries
+      WHERE search_text IS NOT NULL
+      ORDER BY similarity(search_text, $2) DESC
+      LIMIT 5
+      `,
+      [like, q]
+    );
+    const oldHits = oldR.rows.filter(x => x.substr_hit).length;
+
+    const newR = await pool.query(
+      `
+      SELECT (search_text ILIKE '%' || $1 || '%') AS substr_hit
+      FROM ${qi(SCHEMA)}.session_summaries
+      WHERE search_text IS NOT NULL
+      ORDER BY
+        (search_text ILIKE '%' || $1 || '%') DESC,
+        similarity(search_text, $2) DESC
+      LIMIT 5
+      `,
+      [like, q]
+    );
+    const newHits = newR.rows.filter(x => x.substr_hit).length;
+
+    const expected = Math.min(5, T);
+    console.log(
+      `  ${q.padEnd(19)} | ${String(T).padStart(5)} | ${String(oldHits).padStart(3)}/5 → ${String(expected).padStart(1)}/5 ${oldHits < expected ? '✗' : '✓'}      | ${String(newHits).padStart(3)}/5 ${newHits < expected ? '✗' : '✓'}`
+    );
   }
+  console.log('  (truth = 含該字串的 row 數；ideal top-5 substr-hit = min(truth, 5))');
 
   await pool.end();
   console.log('\n=== 完成 ===');
 }
 
-run().catch(err => { console.error(err); process.exit(1); });
+main().catch(err => { console.error(err); process.exit(1); });

package/scripts/diagnose-vector.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * Aquifer vector recall 診斷
+ *
+ * 驗 summary-vector + turn-vector 兩路 infrastructure：
+ *   - embedding coverage
+ *   - vector dim 是否一致（summary vs turn）
+ *   - self-retrieval sanity（拿自己 embedding 當 query，top-1 distance 應 ≈ 0）
+ *
+ * env:
+ *   DATABASE_URL       — required
+ *   AQUIFER_SCHEMA     — default 'public'
+ */
+
+const { Pool } = require('pg');
+
+const DB_URL = process.env.DATABASE_URL;
+if (!DB_URL) {
+  console.error('DATABASE_URL is required');
+  process.exit(2);
+}
+const SCHEMA = process.env.AQUIFER_SCHEMA || 'public';
+
+const pool = new Pool({ connectionString: DB_URL });
+const qi = (s) => `"${s.replace(/"/g, '""')}"`;
+const pct = (n, d) => (d === 0 ? (n === 0 ? '—' : '∞%') : `${Math.round((n / d) * 100)}%`);
+const clean = (s) => (s ? String(s).replace(/\s+/g, ' ').slice(0, 70) : '');
+
+async function main() {
+  console.log(`=== Aquifer vector recall 診斷 (schema=${SCHEMA}) ===\n`);
+
+  // -------------------------------------------------------------------------
+  // 1. Summary embedding coverage + dim
+  // -------------------------------------------------------------------------
+  const s = (await pool.query(`
+    SELECT
+      COUNT(*)                                                      AS total,
+      COUNT(*) FILTER (WHERE embedding IS NOT NULL)                 AS with_emb,
+      MIN(vector_dims(embedding))                                   AS min_dim,
+      MAX(vector_dims(embedding))                                   AS max_dim
+    FROM ${qi(SCHEMA)}.session_summaries
+  `)).rows[0];
+  console.log('--- 1. session_summaries.embedding ---');
+  console.log(`  total ${s.total} | with_emb ${s.with_emb} (${pct(s.with_emb, s.total)})`);
+  const summaryDim = s.min_dim;
+  console.log(`  dim min=${s.min_dim} max=${s.max_dim}${s.min_dim !== s.max_dim ? ' ⚠ 不一致' : ''}\n`);
+
+  // -------------------------------------------------------------------------
+  // 2. Turn embedding coverage + dim
+  // -------------------------------------------------------------------------
+  const t = (await pool.query(`
+    SELECT
+      COUNT(*)                                                      AS total,
+      COUNT(DISTINCT session_row_id)                                AS distinct_sessions,
+      MIN(vector_dims(embedding))                                   AS min_dim,
+      MAX(vector_dims(embedding))                                   AS max_dim
+    FROM ${qi(SCHEMA)}.turn_embeddings
+  `)).rows[0];
+  console.log('--- 2. turn_embeddings.embedding ---');
+  console.log(`  total turns ${t.total} | distinct sessions ${t.distinct_sessions}`);
+  console.log(`  dim min=${t.min_dim} max=${t.max_dim}${t.min_dim !== t.max_dim ? ' ⚠ 不一致' : ''}`);
+  const turnDim = t.min_dim;
+  if (turnDim && summaryDim && turnDim !== summaryDim) {
+    console.log(`  ⚠ summary dim ${summaryDim} != turn dim ${turnDim} → query embedding 只會對得上其中一條`);
+  }
+  console.log();
+
+  // -------------------------------------------------------------------------
+  // 3. 缺 turn 但有 summary 的 session 比例
+  // -------------------------------------------------------------------------
+  const gap = (await pool.query(`
+    SELECT
+      COUNT(DISTINCT ss.session_row_id)                         AS with_summary_emb,
+      COUNT(DISTINCT te.session_row_id)                         AS with_turn_emb,
+      COUNT(DISTINCT ss.session_row_id) FILTER (
+        WHERE te.session_row_id IS NULL
+      )                                                         AS summary_no_turn
+    FROM ${qi(SCHEMA)}.session_summaries ss
+    LEFT JOIN ${qi(SCHEMA)}.turn_embeddings te
+           ON te.session_row_id = ss.session_row_id
+    WHERE ss.embedding IS NOT NULL
+  `)).rows[0];
+  console.log('--- 3. 兩路覆蓋差 ---');
+  console.log(`  sessions with summary emb : ${gap.with_summary_emb}`);
+  console.log(`  sessions with turn emb    : ${gap.with_turn_emb}`);
+  console.log(`  summary-only (no turns)   : ${gap.summary_no_turn} (${pct(gap.summary_no_turn, gap.with_summary_emb)})`);
+  console.log('  (summary-only 是常見的—某些 session 沒有合適的 user turn 可 embed)\n');
+
+  // -------------------------------------------------------------------------
+  // 4. Self-retrieval sanity: summary vector
+  //    拿最近一筆 summary.embedding 當 query，top-1 應該是自己且 distance ≈ 0
+  // -------------------------------------------------------------------------
+  console.log('--- 4. Summary vector self-retrieval sanity ---');
+  const seedS = (await pool.query(`
+    SELECT s.session_id, ss.summary_text, ss.embedding
+    FROM ${qi(SCHEMA)}.session_summaries ss
+    JOIN ${qi(SCHEMA)}.sessions s ON s.id = ss.session_row_id
+    WHERE ss.embedding IS NOT NULL
+    ORDER BY ss.updated_at DESC
+    LIMIT 1
+  `)).rows[0];
+
+  if (!seedS) {
+    console.log('  (no summary with embedding)\n');
+  } else {
+    const r = await pool.query(`
+      SELECT s.session_id,
+             (ss.embedding <=> $1::vector) AS distance,
+             ss.summary_text
+      FROM ${qi(SCHEMA)}.session_summaries ss
+      JOIN ${qi(SCHEMA)}.sessions s ON s.id = ss.session_row_id
+      WHERE ss.embedding IS NOT NULL
+      ORDER BY ss.embedding <=> $1::vector ASC
+      LIMIT 5
+    `, [seedS.embedding]);
+    console.log(`  seed  : ${String(seedS.session_id).slice(0, 8)} | ${clean(seedS.summary_text)}`);
+    for (const row of r.rows) {
+      const mark = String(row.session_id) === String(seedS.session_id) ? ' ← self' : '';
+      console.log(`  [${Number(row.distance).toFixed(4)}] ${String(row.session_id).slice(0, 8)} | ${clean(row.summary_text)}${mark}`);
+    }
+    const top = r.rows[0];
+    const selfOK = top && String(top.session_id) === String(seedS.session_id) && Number(top.distance) < 0.001;
+    console.log(`  → self top-1 @ distance≈0: ${selfOK ? 'YES ✓' : 'NO ✗'}\n`);
+  }
+
+  // -------------------------------------------------------------------------
+  // 5. Self-retrieval sanity: turn vector
+  // -------------------------------------------------------------------------
+  console.log('--- 5. Turn vector self-retrieval sanity ---');
+  const seedT = (await pool.query(`
+    SELECT te.session_row_id, te.turn_index, te.content_text, te.embedding,
+           s.session_id
+    FROM ${qi(SCHEMA)}.turn_embeddings te
+    JOIN ${qi(SCHEMA)}.sessions s ON s.id = te.session_row_id
+    ORDER BY te.created_at DESC
+    LIMIT 1
+  `)).rows[0];
+
+  if (!seedT) {
+    console.log('  (no turn embeddings)\n');
+  } else {
+    const r = await pool.query(`
+      SELECT s.session_id, te.turn_index, te.content_text,
+             (te.embedding <=> $1::vector) AS distance
+      FROM ${qi(SCHEMA)}.turn_embeddings te
+      JOIN ${qi(SCHEMA)}.sessions s ON s.id = te.session_row_id
+      ORDER BY te.embedding <=> $1::vector ASC
+      LIMIT 5
+    `, [seedT.embedding]);
+    console.log(`  seed  : ${String(seedT.session_id).slice(0, 8)} turn=${seedT.turn_index} | ${clean(seedT.content_text)}`);
+    for (const row of r.rows) {
+      const self = String(row.session_id) === String(seedT.session_id) && row.turn_index === seedT.turn_index;
+      console.log(`  [${Number(row.distance).toFixed(4)}] ${String(row.session_id).slice(0, 8)} turn=${row.turn_index} | ${clean(row.content_text)}${self ? ' ← self' : ''}`);
+    }
+    const top = r.rows[0];
+    const selfOK = top && Number(top.distance) < 0.001;
+    console.log(`  → self top-1 @ distance≈0: ${selfOK ? 'YES ✓' : 'NO ✗'}\n`);
+  }
+
+  // -------------------------------------------------------------------------
+  // 6. 跨路比較：用同一筆 summary embedding 去 turn table 找鄰居
+  //    只在 dim 一致時做；看 summary 代表 vs 其最近 turn 的距離分佈
+  // -------------------------------------------------------------------------
+  if (summaryDim && turnDim && summaryDim === turnDim && seedS) {
+    console.log('--- 6. Cross-path：summary emb → turn search (dim 相同才跑) ---');
+    const r = await pool.query(`
+      SELECT DISTINCT ON (te.session_row_id)
+             s.session_id, te.turn_index,
+             (te.embedding <=> $1::vector) AS distance,
+             te.content_text
+      FROM ${qi(SCHEMA)}.turn_embeddings te
+      JOIN ${qi(SCHEMA)}.sessions s ON s.id = te.session_row_id
+      ORDER BY te.session_row_id, te.embedding <=> $1::vector ASC
+    `, [seedS.embedding]);
+    r.rows.sort((a, b) => Number(a.distance) - Number(b.distance));
+    for (const row of r.rows.slice(0, 5)) {
+      const mark = String(row.session_id) === String(seedS.session_id) ? ' ← same session' : '';
+      console.log(`  [${Number(row.distance).toFixed(4)}] ${String(row.session_id).slice(0, 8)} turn=${row.turn_index} | ${clean(row.content_text)}${mark}`);
+    }
+    console.log('  (不要求 top-1 是 seed session，兩路語意不同；只看距離是否合理 ≪ 1)\n');
+  }
+
+  await pool.end();
+  console.log('=== 完成 ===');
+}
+
+main().catch(err => { console.error(err); process.exit(1); });

package/scripts/install-openclaw.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Aquifer — Install drop-in OpenClaw extension
+#
+# Usage:
+#   bash scripts/install-openclaw.sh [OPENCLAW_HOME]
+#
+# Default OPENCLAW_HOME: $HOME/.openclaw
+#
+# What it does:
+#   1. Creates / overwrites $OPENCLAW_HOME/extensions/aquifer-memory/
+#      as a symlink to <this_package>/consumers/openclaw-ext/
+#   2. Prints follow-up instructions: set the .env keys, restart the gateway.
+#
+# Idempotent; safe to re-run.
+
+set -euo pipefail
+
+OPENCLAW_HOME="${1:-${OPENCLAW_HOME:-$HOME/.openclaw}}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PKG_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+EXT_SRC="$PKG_ROOT/consumers/openclaw-ext"
+EXT_DEST="$OPENCLAW_HOME/extensions/aquifer-memory"
+
+if [[ ! -d "$EXT_SRC" ]]; then
+  echo "error: $EXT_SRC not found (expected inside the Aquifer package)" >&2
+  exit 1
+fi
+
+if [[ ! -d "$OPENCLAW_HOME" ]]; then
+  echo "error: OPENCLAW_HOME=$OPENCLAW_HOME not found" >&2
+  exit 1
+fi
+
+mkdir -p "$OPENCLAW_HOME/extensions"
+
+if [[ -L "$EXT_DEST" || -e "$EXT_DEST" ]]; then
+  echo "note: $EXT_DEST already exists — replacing"
+  rm -rf "$EXT_DEST"
+fi
+
+ln -s "$EXT_SRC" "$EXT_DEST"
+echo "ok: linked $EXT_DEST → $EXT_SRC"
+
+cat <<'EOF'
+
+Next steps:
+  1. Edit $OPENCLAW_HOME/.env and set:
+       DATABASE_URL=postgresql://user:pass@host:5432/db
+       EMBED_PROVIDER=ollama           # or openai
+       AQUIFER_LLM_PROVIDER=minimax    # or openai / openrouter / opencode
+       MINIMAX_API_KEY=...             # (or the key for your chosen provider)
+       # Optional:
+       AQUIFER_SCHEMA=my_namespace
+       AQUIFER_PERSONA=/path/to/host-local/persona-module
+  2. Restart OpenClaw:
+       systemctl --user restart openclaw-gateway
+  3. Verify:
+       journalctl --user -u openclaw-gateway -f | grep aquifer-memory
+EOF

package/scripts/smoke.mjs

@@ -99,8 +99,8 @@ try {
   const { Pool } = require('pg');
   const pool = new Pool({ connectionString: config.db.url });
   const schema = config.schema || 'aquifer';
-  await pool.query(`DELETE FROM ${schema}.turn_embeddings WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [SESSION_ID]);
-  await pool.query(`DELETE FROM ${schema}.session_summaries WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [SESSION_ID]);
+  await pool.query(`DELETE FROM ${schema}.turn_embeddings WHERE session_id = $1`, [SESSION_ID]);
+  await pool.query(`DELETE FROM ${schema}.session_summaries WHERE session_id = $1`, [SESSION_ID]);
   await pool.query(`DELETE FROM ${schema}.sessions WHERE session_id = $1`, [SESSION_ID]);
   await pool.end();
   console.log('   OK');