@shadowforge0/aquifer-memory 0.2.0 → 0.3.1

package/README.md

@@ -4,9 +4,9 @@
 
 **PG-native long-term memory for AI agents**
 
-*Turn-level embedding, hybrid RRF ranking, optional knowledge graph — all on PostgreSQL + pgvector.*
+*Turn-level embedding, hybrid RRF ranking, trust scoring, entity intersection, knowledge graph — all on PostgreSQL + pgvector.*
 
-[![npm version](https://img.shields.io/npm/v/aquifer-memory)](https://www.npmjs.com/package/aquifer-memory)
+[![npm version](https://img.shields.io/npm/v/@shadowforge0/aquifer-memory)](https://www.npmjs.com/package/@shadowforge0/aquifer-memory)
 [![PostgreSQL 15+](https://img.shields.io/badge/PostgreSQL-15%2B-336791)](https://www.postgresql.org/)
 [![pgvector](https://img.shields.io/badge/pgvector-0.7%2B-blue)](https://github.com/pgvector/pgvector)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
@@ -59,13 +59,13 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 ### Install
 
 ```bash
-npm install aquifer-memory
+npm install @shadowforge0/aquifer-memory
 ```
 
 ### Initialize
 
 ```javascript
-const { createAquifer } = require('aquifer-memory');
+const { createAquifer } = require('@shadowforge0/aquifer-memory');
 
 const aquifer = createAquifer({
   schema: 'memory',                    // PG schema name (default: 'aquifer')
@@ -132,12 +132,13 @@ const results = await aquifer.recall('auth middleware decision', {
     │  + pgvector     │    │ API  │
     └────────────────┘    └──────┘
 
-    ┌─────────────────────────────┐
-    │         schema/             │
-    │  001-base.sql (sessions,    │
-    │    summaries, turns, FTS)   │
-    │  002-entities.sql (KG)      │
-    └─────────────────────────────┘
+    ┌──────────────────────────────────┐
+    │         schema/                  │
+    │  001-base.sql (sessions,         │
+    │    summaries, turns, FTS)        │
+    │  002-entities.sql (KG)           │
+    │  003-trust-feedback.sql (trust)  │
+    └──────────────────────────────────┘
 ```
 
 ### File Reference
@@ -148,12 +149,13 @@ const results = await aquifer.recall('auth middleware decision', {
 | `core/aquifer.js` | Main facade: `migrate()`, `ingest()`, `recall()`, `enrich()` |
 | `core/storage.js` | Session/summary/turn CRUD, FTS search, embedding search |
 | `core/entity.js` | Entity upsert, mention tracking, relation graph, normalization |
-| `core/hybrid-rank.js` | 3-way RRF fusion, time decay, entity boost scoring |
+| `core/hybrid-rank.js` | 3-way RRF fusion, time decay, trust multiplier, entity boost, open-loop boost |
 | `pipeline/summarize.js` | LLM-powered session summarization with structured output |
 | `pipeline/embed.js` | Embedding client (any OpenAI-compatible API) |
 | `pipeline/extract-entities.js` | LLM-powered entity extraction (12 types) |
 | `schema/001-base.sql` | DDL: sessions, summaries, turn_embeddings, FTS indexes |
 | `schema/002-entities.sql` | DDL: entities, mentions, relations, entity_sessions |
+| `schema/003-trust-feedback.sql` | DDL: trust_score column, session_feedback audit trail |
 
 ---
 
@@ -173,6 +175,38 @@ Query ──┬── FTS (BM25)              ──┐
 - **Reciprocal Rank Fusion** — merges all three ranked lists (K=60)
 - **Time decay** — sigmoid decay with configurable midpoint and steepness
 - **Entity boost** — sessions mentioning query-relevant entities get a score boost
+- **Trust scoring** — multiplicative trust multiplier from explicit feedback (helpful/unhelpful)
+- **Open-loop boost** — sessions with unresolved items get a mild recency boost
+
+### Entity Intersection
+
+When you know which entities you're looking for, pass them explicitly:
+
+```javascript
+const results = await aquifer.recall('auth decision', {
+  entities: ['auth-middleware', 'legal-compliance'],
+  entityMode: 'all',  // only sessions containing BOTH entities
+});
+```
+
+- `entityMode: 'any'` (default) — boost sessions matching any queried entity
+- `entityMode: 'all'` — hard filter: only return sessions containing every specified entity
+
+### Trust Scoring & Feedback
+
+Sessions accumulate trust through explicit feedback. Low-trust memories are suppressed in rankings regardless of relevance.
+
+```javascript
+// After a recall result was useful
+await aquifer.feedback('session-id', { verdict: 'helpful' });
+
+// After a recall result was irrelevant
+await aquifer.feedback('session-id', { verdict: 'unhelpful' });
+```
+
+- Asymmetric: helpful +0.05, unhelpful −0.10 (bad memories sink faster)
+- Multiplicative in ranking: trust=0.5 is neutral, trust=0 halves the score, trust=1.0 gives 50% boost
+- Full audit trail in `session_feedback` table
 
 ### Turn-Level Embeddings
 
@@ -253,15 +287,31 @@ Hybrid search across sessions.
 ```javascript
 const results = await aquifer.recall('search query', {
   agentId: 'main',
-  tenantId: 'default',
   limit: 10,                    // max results
-  ftsLimit: 20,                 // FTS candidate pool
-  embLimit: 20,                 // embedding candidate pool
-  turnLimit: 20,                // turn embedding candidate pool
-  midpointDays: 45,             // time decay midpoint
-  entityBoostWeight: 0.18,      // entity boost factor
+  entities: ['postgres', 'migration'],  // optional: explicit entity names
+  entityMode: 'all',            // 'any' (default) or 'all'
+  weights: {                    // optional: override ranking weights
+    rrf: 0.65,
+    timeDecay: 0.25,
+    access: 0.10,
+    entityBoost: 0.18,
+    openLoop: 0.08,
+  },
 });
-// Returns: [{ session_id, score, title, overview, started_at, ... }]
+// Returns: [{ sessionId, score, trustScore, summaryText, matchedTurnText, _debug, ... }]
+```
+
+#### `aquifer.feedback(sessionId, options)`
+
+Records explicit trust feedback on a session.
+
+```javascript
+await aquifer.feedback('session-id', {
+  verdict: 'helpful',   // or 'unhelpful'
+  agentId: 'main',      // optional
+  note: 'reason',       // optional
+});
+// Returns: { trustBefore, trustAfter, verdict }
 ```
 
 #### `aquifer.enrich(sessionId, options)`
@@ -335,6 +385,14 @@ Key indexes: GIN on messages, GiST on `tsvector`, ivfflat on embeddings, B-tree
 
 Key indexes: trigram on entity names, GiST on embeddings, composite on tenant/agent.
 
+### 003-trust-feedback.sql
+
+| Table | Purpose |
+|-------|---------|
+| `session_feedback` | Explicit feedback audit trail (helpful/unhelpful verdicts, trust deltas) |
+
+Also adds `trust_score` column to `session_summaries` (default 0.5, range 0–1).
+
 ---
 
 ## Dependencies

package/core/aquifer.js

@@ -94,6 +94,14 @@ function createAquifer(config) {
 
   // Track if migrate was called
   let migrated = false;
+  let migratePromise = null;
+
+  async function ensureMigrated() {
+    if (migrated) return;
+    if (migratePromise) return migratePromise;
+    migratePromise = aquifer.migrate().finally(() => { migratePromise = null; });
+    return migratePromise;
+  }
 
   // --- Helper: embed search on summaries ---
   async function embeddingSearchSummaries(queryVec, opts) {
@@ -127,6 +135,7 @@ function createAquifer(config) {
       `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
@@ -158,6 +167,10 @@ function createAquifer(config) {
         await pool.query(entitySql);
       }
 
+      // 3. Trust + feedback (always, not gated by entities)
+      const trustSql = loadSql('003-trust-feedback.sql', schema);
+      await pool.query(trustSql);
+
       migrated = true;
     },
 
@@ -191,6 +204,7 @@ function createAquifer(config) {
     async commit(sessionId, messages, opts = {}) {
       if (!sessionId) throw new Error('sessionId is required');
       if (!messages || !Array.isArray(messages)) throw new Error('messages must be an array');
+      await ensureMigrated();
 
       const agentId = opts.agentId || 'agent';
       const source = opts.source || 'api';
@@ -235,6 +249,7 @@ function createAquifer(config) {
     // --- enrichment ---
 
     async enrich(sessionId, opts = {}) {
+      await ensureMigrated();
       const agentId = opts.agentId || 'agent';
       const skipSummary = opts.skipSummary || false;
       const skipTurnEmbed = opts.skipTurnEmbed || false;
@@ -461,8 +476,17 @@ function createAquifer(config) {
         dateTo,
         limit = 5,
         weights: overrideWeights,
+        entities: explicitEntities,
+        entityMode = 'any',
       } = opts;
 
+      // Validate before touching DB
+      if (explicitEntities && explicitEntities.length > 0 && !entitiesEnabled) {
+        throw new Error('Entities are not enabled');
+      }
+
+      await ensureMigrated();
+
       const fetchLimit = limit * 4;
 
       // 1. Embed query
@@ -470,35 +494,62 @@ function createAquifer(config) {
       const queryVec = queryVecResult[0];
       if (!queryVec || !queryVec.length) return []; // m3: guard empty array too
 
-      // 2. Run 3 search paths in parallel
-      const [ftsRows, embRows, turnResult] = await Promise.all([
-        storage.searchSessions(pool, query, {
-          schema, tenantId, agentId, source, dateFrom, dateTo, limit: fetchLimit,
-        }).catch(() => []),
-        embeddingSearchSummaries(queryVec, {
-          agentId, source, dateFrom, dateTo, limit: fetchLimit,
-        }).catch(() => []),
-        storage.searchTurnEmbeddings(pool, {
-          schema, tenantId, queryVec, dateFrom, dateTo, agentId, source, limit: fetchLimit,
-        }).catch(() => ({ rows: [] })),
-      ]);
+      // 2. Entity intersection pre-filter (when entityMode === 'all')
+      let candidateSessionIds = null; // null = no filter
+      let entityScoreBySession = new Map();
 
-      const turnRows = turnResult.rows || [];
+      if (explicitEntities && explicitEntities.length > 0) {
 
-      if (ftsRows.length === 0 && embRows.length === 0 && turnRows.length === 0) {
-        return [];
-      }
+        const resolved = await entity.resolveEntities(pool, {
+          schema, tenantId, names: explicitEntities, agentId,
+        });
 
-      // 3. Entity boost (if enabled)
-      let entityScoreBySession = new Map();
-      if (entitiesEnabled) {
+        if (resolved.length === 0) return [];
+
+        // Guard: if 'all' mode but fewer entities resolved than requested,
+        // return [] — partial resolution would silently weaken the AND constraint
+        if (entityMode === 'all' && resolved.length < new Set(explicitEntities.map(n => entity.normalizeEntityName(n))).size) {
+          return [];
+        }
+
+        const entityIds = resolved.map(r => r.entityId);
+
+        if (entityMode === 'all') {
+          // Hard filter: only sessions with ALL entities
+          const intersectionRows = await entity.getSessionsByEntityIntersection(pool, {
+            schema, entityIds, tenantId, agentId, source, dateFrom, dateTo, limit: fetchLimit,
+          });
+
+          if (intersectionRows.length === 0) return [];
+
+          candidateSessionIds = new Set(intersectionRows.map(r => r.session_id));
+          for (const row of intersectionRows) {
+            entityScoreBySession.set(row.session_id, 1.0);
+          }
+        } else {
+          // 'any' mode with explicit entities: use resolved IDs for boost
+          const esResult = await pool.query(
+            `SELECT es.session_row_id, s.session_id, COUNT(*) AS entity_count
+            FROM ${qi(schema)}.entity_sessions es
+            JOIN ${qi(schema)}.sessions s ON s.id = es.session_row_id
+            WHERE es.entity_id = ANY($1)
+            GROUP BY es.session_row_id, s.session_id`,
+            [entityIds]
+          );
+
+          const maxCount = Math.max(1, ...esResult.rows.map(r => parseInt(r.entity_count)));
+          for (const row of esResult.rows) {
+            entityScoreBySession.set(row.session_id, parseInt(row.entity_count) / maxCount);
+          }
+        }
+      } else if (entitiesEnabled) {
+        // No explicit entities: existing query-text-based entity boost
         try {
           const matchedEntities = await entity.searchEntities(pool, {
             schema, tenantId, query, agentId, limit: 10,
           });
 
           if (matchedEntities.length > 0) {
-            // M1 fix: single JOIN instead of N+1
             const entityIds = matchedEntities.map(e => e.id);
             const esResult = await pool.query(
               `SELECT es.session_row_id, s.session_id, COUNT(*) AS entity_count
@@ -517,7 +568,47 @@ function createAquifer(config) {
         } catch (_) { /* entity search failure non-fatal */ }
       }
 
-      // 4. Run external source searches (parallel + timeout)
+      // 3. Run 3 search paths in parallel
+      const [ftsRows, embRows, turnResult] = await Promise.all([
+        storage.searchSessions(pool, query, {
+          schema, tenantId, agentId, source, dateFrom, dateTo, limit: fetchLimit,
+        }).catch(() => []),
+        embeddingSearchSummaries(queryVec, {
+          agentId, source, dateFrom, dateTo, limit: fetchLimit,
+        }).catch(() => []),
+        storage.searchTurnEmbeddings(pool, {
+          schema, tenantId, queryVec, dateFrom, dateTo, agentId, source, limit: fetchLimit,
+        }).catch(() => ({ rows: [] })),
+      ]);
+
+      const turnRows = turnResult.rows || [];
+
+      // 3b. Apply candidate filter (entityMode 'all')
+      const filterFn = candidateSessionIds
+        ? (rows) => rows.filter(r => candidateSessionIds.has(r.session_id || String(r.id)))
+        : (rows) => rows;
+
+      const filteredFts = filterFn(ftsRows);
+      const filteredEmb = filterFn(embRows);
+      const filteredTurn = filterFn(turnRows);
+
+      if (filteredFts.length === 0 && filteredEmb.length === 0 && filteredTurn.length === 0) {
+        return [];
+      }
+
+      // 4. Open-loop set extraction
+      const openLoopSet = new Set();
+      for (const r of [...filteredFts, ...filteredEmb, ...filteredTurn]) {
+        const sid = r.session_id || String(r.id);
+        const ss = typeof r.structured_summary === 'string'
+          ? (() => { try { return JSON.parse(r.structured_summary); } catch (_) { return null; } })()
+          : r.structured_summary;
+        if (ss && Array.isArray(ss.open_loops) && ss.open_loops.length > 0) {
+          openLoopSet.add(sid);
+        }
+      }
+
+      // 5. Run external source searches (parallel + timeout)
       const EXTERNAL_TIMEOUT = 10000;
       const externalRows = [];
       const externalPromises = [];
@@ -540,18 +631,21 @@ function createAquifer(config) {
       }
       if (externalPromises.length > 0) await Promise.all(externalPromises);
 
-      // 5. Hybrid rank — external results as separate embedding-like signal
+      // 6. Hybrid rank
       const mergedWeights = { ...rankWeights, ...overrideWeights };
       const ranked = hybridRank(
-        ftsRows,
-        [...embRows, ...externalRows],
-        limit,
-        mergedWeights,
-        turnRows,
-        entityScoreBySession,
+        filteredFts,
+        [...filteredEmb, ...filterFn(externalRows)],
+        filteredTurn,
+        {
+          limit,
+          weights: mergedWeights,
+          entityScoreBySession,
+          openLoopSet,
+        },
       );
 
-      // 6. Record access
+      // 7. Record access
       const sessionRowIds = ranked
         .map(r => r.id || r.session_row_id)
         .filter(Boolean);
@@ -562,7 +656,7 @@ function createAquifer(config) {
         } catch (_) { /* access recording non-fatal */ }
       }
 
-      // 7. Format results
+      // 8. Format results
       return ranked.map(r => ({
         sessionId: r.session_id,
         agentId: r.agent_id,
@@ -574,15 +668,41 @@ function createAquifer(config) {
         matchedTurnText: r.matched_turn_text || null,
         matchedTurnIndex: r.matched_turn_index || null,
         score: r._score,
+        trustScore: r._trustScore ?? 0.5,
         _debug: {
           rrf: r._rrf,
           timeDecay: r._timeDecay,
           access: r._access,
           entityScore: r._entityScore,
+          trustScore: r._trustScore,
+          trustMultiplier: r._trustMultiplier,
+          openLoopBoost: r._openLoopBoost,
         },
       }));
     },
 
+    // --- feedback ---
+
+    async feedback(sessionId, opts = {}) {
+      const agentId = opts.agentId || 'agent';
+      const verdict = opts.verdict;
+      if (!verdict) throw new Error('opts.verdict is required ("helpful" or "unhelpful")');
+      await ensureMigrated();
+
+      const session = await storage.getSession(pool, sessionId, agentId, {}, { schema, tenantId });
+      if (!session) throw new Error(`Session not found: ${sessionId} (agentId=${agentId})`);
+
+      return storage.recordFeedback(pool, {
+        schema,
+        tenantId,
+        sessionRowId: session.id,
+        sessionId,
+        agentId,
+        verdict,
+        note: opts.note || null,
+      });
+    },
+
     // --- admin ---
 
     async getSession(sessionId, opts = {}) {

package/core/entity.js

@@ -344,6 +344,120 @@ async function getEntityRelations(pool, {
   return result.rows;
 }
 
+// ---------------------------------------------------------------------------
+// resolveEntities — map raw names to entity IDs with dedup
+// ---------------------------------------------------------------------------
+
+async function resolveEntities(pool, {
+  schema,
+  tenantId,
+  names,
+  agentId = null,
+  threshold = 0.1,
+}) {
+  if (!names || names.length === 0) return [];
+
+  const seen = new Map();
+  const results = [];
+
+  for (const rawName of names) {
+    const normQ = normalizeEntityName(rawName);
+    if (!normQ || seen.has(normQ)) continue;
+    seen.set(normQ, true);
+
+    const escaped = _escapeIlike(normQ);
+    const result = await pool.query(
+      `SELECT id, name, normalized_name
+      FROM ${qi(schema)}.entities
+      WHERE status = 'active'
+        AND tenant_id = $1
+        AND (
+          similarity(normalized_name, $2) >= $3
+          OR normalized_name = $2
+          OR $2 = ANY(aliases)
+        )
+        AND ($4::text IS NULL OR agent_id = $4)
+      ORDER BY similarity(normalized_name, $2) DESC, frequency DESC
+      LIMIT 1`,
+      [tenantId, normQ, threshold, agentId || null]
+    );
+
+    if (result.rows[0]) {
+      const row = result.rows[0];
+      if (!results.some(r => r.entityId === row.id)) {
+        results.push({
+          entityId: row.id,
+          name: row.name,
+          normalizedName: row.normalized_name,
+          inputName: rawName,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// getSessionsByEntityIntersection — sessions containing ALL specified entities
+// ---------------------------------------------------------------------------
+
+async function getSessionsByEntityIntersection(pool, {
+  schema,
+  entityIds,
+  tenantId,
+  agentId = null,
+  source = null,
+  dateFrom = null,
+  dateTo = null,
+  limit = 100,
+}) {
+  if (!entityIds || entityIds.length === 0) return [];
+
+  const where = ['s.tenant_id = $2'];
+  const params = [entityIds, tenantId];
+
+  if (agentId) {
+    params.push(agentId);
+    where.push(`s.agent_id = $${params.length}`);
+  }
+  if (source) {
+    params.push(source);
+    where.push(`s.source = $${params.length}`);
+  }
+  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`);
+  }
+
+  params.push(entityIds.length);
+  const havingPos = params.length;
+
+  params.push(Math.max(1, Math.min(500, limit)));
+  const limitPos = params.length;
+
+  const result = await pool.query(
+    `SELECT es.session_row_id, s.session_id,
+            COUNT(DISTINCT es.entity_id) AS matched_count,
+            SUM(es.mention_count) AS mention_weight
+    FROM ${qi(schema)}.entity_sessions es
+    JOIN ${qi(schema)}.sessions s ON s.id = es.session_row_id
+    WHERE es.entity_id = ANY($1)
+      AND ${where.join(' AND ')}
+    GROUP BY es.session_row_id, s.session_id
+    HAVING COUNT(DISTINCT es.entity_id) >= $${havingPos}
+    ORDER BY matched_count DESC, mention_weight DESC
+    LIMIT $${limitPos}`,
+    params
+  );
+
+  return result.rows;
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
@@ -357,4 +471,6 @@ module.exports = {
   upsertEntitySession,
   searchEntities,
   getEntityRelations,
+  resolveEntities,
+  getSessionsByEntityIntersection,
 };

package/core/hybrid-rank.js

@@ -62,6 +62,14 @@ function accessScore(accessCount, lastAccessedAt) {
 
 // ---------------------------------------------------------------------------
 // hybridRank — combine all signals into final ranked list
+//
+// Scoring order:
+//   1. rawBase = rrf * normRrf + timeDecay * td + access * as
+//   2. base = min(1, rawBase)
+//   3. trustMultiplier = 0.5 + (trust_score ?? 0.5)        [0.5–1.5]
+//   4. trustedBase = base * trustMultiplier
+//   5. withOpenLoop = min(1, trustedBase + openLoop boost)
+//   6. finalScore = min(1, withOpenLoop + entityBoost * entitySc * (1 - withOpenLoop))
 // ---------------------------------------------------------------------------
 
 const DEFAULT_WEIGHTS = {
@@ -69,16 +77,17 @@ const DEFAULT_WEIGHTS = {
   timeDecay: 0.25,
   access: 0.10,
   entityBoost: 0.18,
+  openLoop: 0.08,
 };
 
-function hybridRank(
-  ftsResults,
-  embResults,
-  limit = 5,
-  weights = {},
-  turnResults = [],
-  entityScoreBySession = new Map(),
-) {
+function hybridRank(ftsResults, embResults, turnResults, opts = {}) {
+  const {
+    limit = 5,
+    weights = {},
+    entityScoreBySession = new Map(),
+    openLoopSet = new Set(),
+  } = opts;
+
   const w = { ...DEFAULT_WEIGHTS, ...weights };
 
   // Build allResults map: session_id → result object
@@ -139,11 +148,22 @@ function hybridRank(
     );
     const as = 1 - Math.exp(-accessEff / 5);
 
+    // Step 1–2: base score
     const rawBase = w.rrf * normRrf + w.timeDecay * td + w.access * as;
-    const base = Math.min(1, rawBase); // m7: clamp to prevent negative entity boost
+    const base = Math.min(1, rawBase);
+
+    // Step 3–4: trust multiplier (read from result row)
+    const trustSc = result.trust_score ?? 0.5;
+    const trustMultiplier = 0.5 + trustSc;
+    const trustedBase = Math.min(1, base * trustMultiplier);
+
+    // Step 5: open-loop boost
+    const olBoost = openLoopSet.has(sessionId) ? w.openLoop : 0;
+    const withOpenLoop = Math.min(1, trustedBase + olBoost);
 
+    // Step 6: entity boost
     const entitySc = entityScoreBySession.get(sessionId) || 0;
-    const finalScore = Math.min(1, base + w.entityBoost * entitySc * (1 - base));
+    const finalScore = Math.min(1, withOpenLoop + w.entityBoost * entitySc * (1 - withOpenLoop));
 
     scored.push({
       ...result,
@@ -152,6 +172,9 @@ function hybridRank(
       _timeDecay: td,
       _access: as,
       _entityScore: entitySc,
+      _trustScore: trustSc,
+      _trustMultiplier: trustMultiplier,
+      _openLoopBoost: olBoost,
     });
   }
 

package/core/storage.js

@@ -350,6 +350,7 @@ async function searchSessions(pool, query, {
       ss.structured_summary,
       ss.access_count,
       ss.last_accessed_at,
+      ss.trust_score,
       ts_headline('simple', COALESCE(ss.summary_text, ''), plainto_tsquery('simple', $1)) AS summary_snippet,
       ts_rank(ss.search_tsv, plainto_tsquery('simple', $1)) AS fts_rank
     FROM ${qi(schema)}.sessions s
@@ -513,6 +514,7 @@ async function searchTurnEmbeddings(pool, {
       SELECT DISTINCT ON (t.session_row_id)
         s.session_id, s.id AS session_row_id, s.agent_id, s.source, s.started_at,
         ss.summary_text, ss.structured_summary, ss.access_count, ss.last_accessed_at,
+        COALESCE(ss.trust_score, 0.5) AS trust_score,
         t.content_text AS matched_turn_text, t.turn_index AS matched_turn_index,
         (t.embedding <=> $${vecPos}::vector) AS turn_distance
       FROM ${qi(schema)}.turn_embeddings t
@@ -529,6 +531,68 @@ async function searchTurnEmbeddings(pool, {
   return { rows: result.rows.slice(0, limit) };
 }
 
+// ---------------------------------------------------------------------------
+// recordFeedback — explicit trust feedback with audit trail
+// ---------------------------------------------------------------------------
+
+const TRUST_UP = 0.05;
+const TRUST_DOWN = 0.10;
+
+async function recordFeedback(pool, {
+  schema,
+  tenantId,
+  sessionRowId,
+  sessionId,
+  agentId,
+  verdict,
+  note,
+}) {
+  if (verdict !== 'helpful' && verdict !== 'unhelpful') {
+    throw new Error(`Invalid verdict: "${verdict}". Must be "helpful" or "unhelpful".`);
+  }
+
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    const current = await client.query(
+      `SELECT trust_score FROM ${qi(schema)}.session_summaries
+      WHERE session_row_id = $1 FOR UPDATE`,
+      [sessionRowId]
+    );
+    if (!current.rows[0]) {
+      throw new Error(`Session not enriched: no summary for session_row_id=${sessionRowId}`);
+    }
+
+    const trustBefore = parseFloat(current.rows[0].trust_score);
+    const trustAfter = verdict === 'helpful'
+      ? Math.min(1.0, trustBefore + TRUST_UP)
+      : Math.max(0.0, trustBefore - TRUST_DOWN);
+
+    await client.query(
+      `UPDATE ${qi(schema)}.session_summaries
+      SET trust_score = $1, updated_at = now()
+      WHERE session_row_id = $2`,
+      [trustAfter, sessionRowId]
+    );
+
+    await client.query(
+      `INSERT INTO ${qi(schema)}.session_feedback
+        (session_row_id, tenant_id, agent_id, session_id, verdict, note, trust_before, trust_after)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
+      [sessionRowId, tenantId, agentId, sessionId, verdict, note || null, trustBefore, trustAfter]
+    );
+
+    await client.query('COMMIT');
+    return { trustBefore, trustAfter, verdict };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
@@ -547,4 +611,5 @@ module.exports = {
   extractUserTurns,
   upsertTurnEmbeddings,
   searchTurnEmbeddings,
+  recordFeedback,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "PG-native long-term memory for AI agents. Turn-level embedding, hybrid RRF ranking, optional knowledge graph. Includes CLI, MCP server, and OpenClaw plugin.",
   "main": "index.js",
   "files": [
@@ -15,6 +15,8 @@
   },
   "exports": {
     ".": "./index.js",
+    "./core/*": "./core/*.js",
+    "./pipeline/*": "./pipeline/*.js",
     "./consumers/mcp": "./consumers/mcp.js",
     "./consumers/openclaw-plugin": "./consumers/openclaw-plugin.js",
     "./consumers/shared/config": "./consumers/shared/config.js",

package/schema/003-trust-feedback.sql

@@ -0,0 +1,29 @@
+-- Aquifer trust feedback extension
+-- Requires: 001-base.sql applied first
+-- Usage: replace ${schema} with actual schema name
+
+-- =========================================================================
+-- Trust score: per-session summary quality metric
+-- =========================================================================
+ALTER TABLE ${schema}.session_summaries
+  ADD COLUMN IF NOT EXISTS trust_score REAL NOT NULL DEFAULT 0.5
+  CHECK (trust_score >= 0 AND trust_score <= 1);
+
+-- =========================================================================
+-- Session feedback: audit trail for user feedback on session summaries
+-- =========================================================================
+CREATE TABLE IF NOT EXISTS ${schema}.session_feedback (
+  id             BIGSERIAL    PRIMARY KEY,
+  session_row_id BIGINT       NOT NULL REFERENCES ${schema}.sessions(id) ON DELETE CASCADE,
+  tenant_id      TEXT         NOT NULL DEFAULT 'default',
+  agent_id       TEXT         NOT NULL DEFAULT 'agent',
+  session_id     TEXT         NOT NULL,
+  verdict        TEXT         NOT NULL CHECK (verdict IN ('helpful', 'unhelpful')),
+  note           TEXT,
+  trust_before   REAL         NOT NULL,
+  trust_after    REAL         NOT NULL,
+  created_at     TIMESTAMPTZ  NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_feedback_session
+  ON ${schema}.session_feedback (session_row_id, created_at DESC);