@shadowforge0/aquifer-memory 1.5.9 → 1.6.0

package/consumers/default/daily-entries.js

@@ -9,7 +9,7 @@
 //   CREATE TABLE jenny.daily_entries (LIKE miranda.daily_entries INCLUDING ALL);
 
 const crypto = require('crypto');
-const { parseHandoffSection } = require('../miranda/prompts/summary');
+const { parseHandoffSection } = require('../shared/summary-parser');
 
 const UPSERT_TAGS = new Set(['[FOCUS]', '[TODO]', '[STATS]', '[HIGHLIGHT]', '[SYSTEM]', '[HANDOFF]']);
 
@@ -27,10 +27,27 @@ function textHash6(text) {
   return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 6);
 }
 
+function quoteIdentifier(identifier) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(identifier)) {
+    throw new Error(`Invalid dailyTable identifier: ${identifier}`);
+  }
+  return `"${identifier}"`;
+}
+
+function quoteTableName(tableName) {
+  if (typeof tableName !== 'string') throw new Error('dailyTable must be a string');
+  const parts = tableName.split('.');
+  if (parts.length < 1 || parts.length > 2 || parts.some(part => !part)) {
+    throw new Error(`Invalid dailyTable name: ${tableName}`);
+  }
+  return parts.map(quoteIdentifier).join('.');
+}
+
 async function insertDailyEntry(pool, tableName, { eventAt, source, tag, text, agentId, sessionId, metadata, dedupeKey }) {
+  const tableSql = quoteTableName(tableName);
   const shouldUpsert = dedupeKey && UPSERT_TAGS.has(tag);
   const sql = shouldUpsert
-    ? `INSERT INTO ${tableName}
+    ? `INSERT INTO ${tableSql}
          (event_at, source, tag, text, agent_id, session_id, metadata, dedupe_key)
        VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
        ON CONFLICT (dedupe_key) DO UPDATE SET
@@ -38,7 +55,7 @@ async function insertDailyEntry(pool, tableName, { eventAt, source, tag, text, a
          event_at = EXCLUDED.event_at,
          metadata = EXCLUDED.metadata
        RETURNING id, event_at, source, tag, text`
-    : `INSERT INTO ${tableName}
+    : `INSERT INTO ${tableSql}
          (event_at, source, tag, text, agent_id, session_id, metadata, dedupe_key)
        VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
        ON CONFLICT (dedupe_key) DO NOTHING
@@ -53,8 +70,9 @@ async function insertDailyEntry(pool, tableName, { eventAt, source, tag, text, a
 }
 
 async function getDailyEntries(pool, tableName, date, agentId) {
+  const tableSql = quoteTableName(tableName);
   const result = await pool.query(
-    `SELECT * FROM ${tableName}
+    `SELECT * FROM ${tableSql}
       WHERE (event_at AT TIME ZONE 'Asia/Taipei')::date = $1
         AND ($2::text IS NULL OR agent_id = $2)
       ORDER BY event_at ASC`,
@@ -191,6 +209,7 @@ async function writeDailyEntries({
 
 module.exports = {
   taipeiDateString, textHash6,
+  quoteIdentifier, quoteTableName,
   insertDailyEntry, getDailyEntries, fetchDailyContext, writeDailyEntries,
   UPSERT_TAGS,
 };

package/consumers/default/index.js

@@ -15,7 +15,7 @@
 //       briefingIntro: '你是 Dobby。以下是現況...',  // optional context-inject preamble
 //     });
 //
-// Returns a persona module with the same shape as consumers/miranda — host
+// Returns a persona module with the standard persona adapter shape — host
 // can do `AQUIFER_PERSONA=<host-path>` where <host-path>/index.js does:
 //   module.exports = require('@shadowforge0/aquifer-memory/consumers/default')
 //     .createPersona({ ... });
@@ -222,7 +222,7 @@ function createPersona(personaOpts = {}) {
       if ((ctx?.sessionKey || '').includes('subagent')) return null;
       return {
         name: 'session_recall',
-        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).',
+        description: 'Search Aquifer memory by keyword or natural language. In curated serving mode this searches active curated memory; legacy/evidence lookup is exposed by the MCP stdio evidence_recall tool. 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: {

package/consumers/default/prompts/summary.js

@@ -139,15 +139,15 @@ TODO_DONE: 已完成待辦（需匹配既有）
 }
 
 // ---------------------------------------------------------------------------
-// parseSummaryOutput / parseRecapLines — delegate to miranda's parsers.
-// The output format is intentionally the same, so parsers work for both.
+// parseSummaryOutput / parseRecapLines — shared parser used by all personas.
+// The output format is intentionally stable so downstream daily entries work.
 // ---------------------------------------------------------------------------
 
-const mirandaSummary = require('../../miranda/prompts/summary');
+const summaryParser = require('../../shared/summary-parser');
 
 module.exports = {
   buildSummaryPrompt,
-  parseSummaryOutput: mirandaSummary.parseSummaryOutput,
-  parseRecapLines: mirandaSummary.parseRecapLines,
-  parseWorkingFacts: mirandaSummary.parseWorkingFacts,
+  parseSummaryOutput: summaryParser.parseSummaryOutput,
+  parseRecapLines: summaryParser.parseRecapLines,
+  parseWorkingFacts: summaryParser.parseWorkingFacts,
 };

package/consumers/mcp.js

@@ -7,7 +7,8 @@
  * This is the primary integration surface for Aquifer. Agent hosts (Claude Code,
  * Codex, OpenCode, etc.) should integrate through this MCP server.
  *
- * Tools: session_recall, session_feedback, memory_stats, memory_pending
+ * Tools: session_recall, evidence_recall, session_feedback, memory_feedback,
+ * feedback_stats, session_bootstrap, memory_stats, memory_pending
  *
  * Usage:
  *   npx aquifer mcp
@@ -18,6 +19,7 @@
  */
 
 const { createAquiferFromConfig } = require('./shared/factory');
+const { version: packageVersion } = require('../package.json');
 
 let _aquifer = null;
 
@@ -32,8 +34,8 @@ function getAquifer() {
 
 const { formatRecallResults } = require('./shared/recall-format');
 
-function formatResults(results, query) {
-  return formatRecallResults(results, { query, showScore: true });
+function formatResults(results, query, explain) {
+  return formatRecallResults(results, { query, showScore: true, showExplain: !!explain });
 }
 
 // ---------------------------------------------------------------------------
@@ -58,12 +60,12 @@ async function main() {
 
   const server = new McpServer({
     name: 'aquifer-memory',
-    version: '0.9.0',
+    version: packageVersion,
   });
 
   server.tool(
     'session_recall',
-    'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
+    'Search Aquifer memory. In curated serving mode this searches active curated memory only; use evidence_recall for legacy session/evidence lookup.',
     {
       query: z.string().min(1).describe('Search query (keyword or natural language)'),
       limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
@@ -74,6 +76,9 @@ async function main() {
       entities: z.array(z.string()).optional().describe('Entity names to match'),
       entityMode: z.enum(['any', 'all']).optional().describe('"any" (default, boost) or "all" (only sessions with every entity)'),
       mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)'),
+      explain: z.boolean().optional().describe('Include per-result score breakdown (diagnostic)'),
+      activeScopeKey: z.string().optional().describe('Active curated memory scope key'),
+      activeScopePath: z.array(z.string()).optional().describe('Ordered curated scope path'),
     },
     async (params) => {
       try {
@@ -85,6 +90,8 @@ async function main() {
           source: params.source || undefined,
           dateFrom: params.dateFrom || undefined,
           dateTo: params.dateTo || undefined,
+          activeScopeKey: params.activeScopeKey || undefined,
+          activeScopePath: params.activeScopePath || undefined,
         };
         if (params.entities && params.entities.length > 0) {
           recallOpts.entities = params.entities;
@@ -93,7 +100,7 @@ async function main() {
         if (params.mode) recallOpts.mode = params.mode;
 
         const results = await aquifer.recall(params.query, recallOpts);
-        const text = formatResults(results, params.query);
+        const text = formatResults(results, params.query, params.explain);
         return { content: [{ type: 'text', text }] };
       } catch (err) {
         return {
@@ -104,9 +111,55 @@ async function main() {
     }
   );
 
+  server.tool(
+    'evidence_recall',
+    'Explicit legacy/evidence search over stored sessions and summaries. Use for audit/debug/distillation; it does not feed bootstrap implicitly.',
+    {
+      query: z.string().min(1).describe('Evidence search query (keyword or natural language)'),
+      limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
+      agentId: z.string().optional().describe('Filter by agent ID'),
+      source: z.string().optional().describe('Filter by source (e.g., gateway, cc)'),
+      dateFrom: z.string().optional().describe('Start date YYYY-MM-DD'),
+      dateTo: z.string().optional().describe('End date YYYY-MM-DD'),
+      entities: z.array(z.string()).optional().describe('Entity names to match'),
+      entityMode: z.enum(['any', 'all']).optional().describe('"any" (default, boost) or "all" (only sessions with every entity)'),
+      mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Legacy evidence recall mode'),
+      explain: z.boolean().optional().describe('Include per-result score breakdown (diagnostic)'),
+      allowUnsafeDebug: z.boolean().optional().describe('Allow broad evidence/debug search without an audit boundary'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const limit = params.limit || 5;
+        const recallOpts = {
+          limit,
+          agentId: params.agentId || undefined,
+          source: params.source || undefined,
+          dateFrom: params.dateFrom || undefined,
+          dateTo: params.dateTo || undefined,
+        };
+        if (params.entities && params.entities.length > 0) {
+          recallOpts.entities = params.entities;
+          recallOpts.entityMode = params.entityMode || 'any';
+        }
+        if (params.mode) recallOpts.mode = params.mode;
+        if (params.allowUnsafeDebug) recallOpts.allowUnsafeDebug = true;
+
+        const results = await aquifer.evidenceRecall(params.query, recallOpts);
+        const text = formatResults(results, params.query, params.explain);
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `evidence_recall error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     'session_feedback',
-    'Record trust feedback on a recalled session. Helpful sessions rank higher in future recalls.',
+    'After using legacy session_recall or bootstrap, mark the recalled session helpful or unhelpful. This only targets legacy session trust, not curated memory rows.',
     {
       sessionId: z.string().min(1).describe('Session ID to give feedback on'),
       verdict: z.enum(['helpful', 'unhelpful']).describe('Was the recalled session useful?'),
@@ -133,6 +186,73 @@ async function main() {
     }
   );
 
+  server.tool(
+    'memory_feedback',
+    'Record append-only feedback on a curated memory row. This affects curated ranking/review priority only and does not mutate memory truth.',
+    {
+      memoryId: z.string().min(1).optional().describe('Curated memory record ID to give feedback on'),
+      canonicalKey: z.string().min(1).optional().describe('Canonical key of the active curated memory record'),
+      feedbackType: z.enum(['helpful', 'confirm', 'irrelevant', 'scope_mismatch', 'stale', 'incorrect']).describe('Curated memory feedback event type'),
+      note: z.string().optional().describe('Optional reason'),
+      agentId: z.string().optional().describe('Optional actor/agent label for audit metadata'),
+    },
+    async (params) => {
+      try {
+        if (!params.memoryId && !params.canonicalKey) {
+          throw new Error('memory_feedback requires memoryId or canonicalKey');
+        }
+        const aquifer = getAquifer();
+        const result = await aquifer.memoryFeedback({
+          memoryId: params.memoryId || undefined,
+          canonicalKey: params.canonicalKey || undefined,
+        }, {
+          feedbackType: params.feedbackType,
+          note: params.note || undefined,
+          agentId: params.agentId || undefined,
+        });
+        return {
+          content: [{ type: 'text', text: `Memory feedback: ${result.feedbackType}` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `memory_feedback error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    'feedback_stats',
+    'Return trust feedback statistics: total feedback count, helpful/unhelpful breakdown, trust score distribution, and coverage.',
+    {
+      agentId: z.string().optional().describe('Filter by agent ID'),
+      dateFrom: z.string().optional().describe('Start date YYYY-MM-DD'),
+      dateTo: z.string().optional().describe('End date YYYY-MM-DD'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const stats = await aquifer.feedbackStats({
+          agentId: params.agentId || undefined,
+          dateFrom: params.dateFrom || undefined,
+          dateTo: params.dateTo || undefined,
+        });
+        const lines = [
+          `Feedback: ${stats.totalFeedback} total (${stats.helpfulCount} helpful, ${stats.unhelpfulCount} unhelpful)`,
+          `Coverage: ${stats.feedbackSessions}/${stats.totalSessions} sessions rated`,
+          `Trust score: avg=${stats.trustScoreAvg} min=${stats.trustScoreMin} max=${stats.trustScoreMax}`,
+        ];
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `feedback_stats error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     'memory_stats',
     'Return storage statistics for the Aquifer memory store (session counts by status, summaries, turn embeddings, entities, date range).',
@@ -196,6 +316,8 @@ async function main() {
       limit: z.number().int().min(1).max(20).optional().describe('Max sessions (default 5)'),
       lookbackDays: z.number().int().min(1).max(90).optional().describe('How far back in days (default 14)'),
       maxChars: z.number().int().min(500).max(12000).optional().describe('Max output characters (default 4000)'),
+      activeScopeKey: z.string().optional().describe('Active curated memory scope key'),
+      activeScopePath: z.array(z.string()).optional().describe('Ordered curated scope path'),
     },
     async (params) => {
       try {
@@ -205,6 +327,8 @@ async function main() {
           limit: params.limit,
           lookbackDays: params.lookbackDays,
           maxChars: params.maxChars,
+          activeScopeKey: params.activeScopeKey || undefined,
+          activeScopePath: params.activeScopePath || undefined,
           format: 'text',
         });
         return { content: [{ type: 'text', text: result.text }] };

package/consumers/openclaw-ext/index.js

@@ -4,7 +4,6 @@
 //
 // Host layout:
 //   $OPENCLAW_HOME/extensions/aquifer-memory/  ← symlink to this directory
-//   (or run `bash scripts/install-openclaw.sh $OPENCLAW_HOME` from the tarball)
 //
 // Behavior:
 //   - Loads $OPENCLAW_HOME/.env so DATABASE_URL / EMBED_PROVIDER /

package/consumers/openclaw-plugin.js

@@ -201,7 +201,7 @@ function register(api) {
 
       return {
         name: 'session_recall',
-        description: 'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
+        description: 'Search Aquifer memory by keyword. In curated serving mode this searches active curated memory; legacy/evidence lookup is exposed by the MCP stdio evidence_recall tool. Supports entity intersection for precise multi-entity queries.',
         parameters: {
           type: 'object',
           properties: {
@@ -214,6 +214,7 @@ function register(api) {
             entities: { type: 'array', items: { type: 'string' }, description: 'Entity names to match' },
             entityMode: { type: 'string', enum: ['any', 'all'], description: '"any" (default, boost) or "all" (only sessions with every entity)' },
             mode: { type: 'string', enum: ['fts', 'hybrid', 'vector'], description: 'Recall mode: "fts" (keyword only), "hybrid" (default), "vector" (vector only)' },
+            explain: { type: 'boolean', description: 'Include per-result score breakdown (diagnostic)' },
           },
           required: ['query'],
         },
@@ -234,7 +235,7 @@ function register(api) {
             if (params.mode) recallOpts.mode = params.mode;
 
             const results = await aquifer.recall(params.query, recallOpts);
-            const text = formatRecallResults(results);
+            const text = formatRecallResults(results, { showScore: true, showExplain: !!params.explain });
             return { content: [{ type: 'text', text }] };
           } catch (err) {
             return {
@@ -253,7 +254,7 @@ function register(api) {
 
       return {
         name: 'session_feedback',
-        description: 'Record trust feedback on a recalled session. Helpful sessions rank higher in future recalls.',
+        description: 'After using session_recall, mark the result helpful if it directly informed your answer, or unhelpful if it was irrelevant/outdated. Include a short note. Sessions with more helpful feedback rank higher in future recalls.',
         parameters: {
           type: 'object',
           properties: {
@@ -285,5 +286,44 @@ function register(api) {
       };
     }, { name: 'session_feedback' });
 
-  api.logger.info('[aquifer-memory] registered (before_reset + session_recall + session_feedback)');
+    // --- feedback_stats tool ---
+
+    api.registerTool((ctx) => {
+      if ((ctx?.sessionKey || '').includes('subagent')) return null;
+
+      return {
+        name: 'feedback_stats',
+        description: 'Return trust feedback statistics: total feedback count, helpful/unhelpful breakdown, trust score distribution, and coverage.',
+        parameters: {
+          type: 'object',
+          properties: {
+            agentId: { type: 'string', description: 'Filter by agent ID' },
+            dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
+            dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+          },
+        },
+        async execute(_toolCallId, params) {
+          try {
+            const stats = await aquifer.feedbackStats({
+              agentId: params.agentId || undefined,
+              dateFrom: params.dateFrom || undefined,
+              dateTo: params.dateTo || undefined,
+            });
+            const lines = [
+              `Feedback: ${stats.totalFeedback} total (${stats.helpfulCount} helpful, ${stats.unhelpfulCount} unhelpful)`,
+              `Coverage: ${stats.feedbackSessions}/${stats.totalSessions} sessions rated`,
+              `Trust score: avg=${stats.trustScoreAvg} min=${stats.trustScoreMin} max=${stats.trustScoreMax}`,
+            ];
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+          } catch (err) {
+            return {
+              content: [{ type: 'text', text: `feedback_stats error: ${err.message}` }],
+              isError: true,
+            };
+          }
+        },
+      };
+    }, { name: 'feedback_stats' });
+
+  api.logger.info('[aquifer-memory] registered (before_reset + session_recall + session_feedback + feedback_stats)');
 }

package/consumers/shared/config.js

@@ -30,7 +30,21 @@ const DEFAULTS = {
     temperature: 0,
   },
   entities: { enabled: false, mergeCall: true, scope: 'default' },
+  insights: {
+    recallWeights: null,
+    recencyWindowDays: null,
+    dedup: {
+      mode: 'off',
+      cosineThreshold: 0.88,
+      closeBandFrom: 0.85,
+    },
+  },
   rank: { rrf: 0.65, timeDecay: 0.25, access: 0.10, entityBoost: 0.18 },
+  memory: {
+    servingMode: 'legacy',   // 'legacy' | 'curated'
+    activeScopeKey: null,
+    activeScopePath: null,
+  },
   rerank: {
     enabled: false,
     provider: null,    // 'tei' | 'jina' | 'openrouter' | 'custom'
@@ -75,6 +89,12 @@ const ENV_MAP = [
   ['AQUIFER_LLM_TEMPERATURE',   'llm.temperature',   Number],
   ['AQUIFER_ENTITIES_ENABLED',  'entities.enabled',  Boolean],
   ['AQUIFER_ENTITY_SCOPE',     'entities.scope'],
+  ['AQUIFER_INSIGHTS_DEDUP_MODE',             'insights.dedup.mode'],
+  ['AQUIFER_INSIGHTS_DEDUP_COSINE',           'insights.dedup.cosineThreshold', Number],
+  ['AQUIFER_INSIGHTS_DEDUP_CLOSE_BAND_FROM',  'insights.dedup.closeBandFrom',   Number],
+  ['AQUIFER_MEMORY_SERVING_MODE', 'memory.servingMode'],
+  ['AQUIFER_MEMORY_ACTIVE_SCOPE_KEY', 'memory.activeScopeKey'],
+  ['AQUIFER_MEMORY_ACTIVE_SCOPE_PATH', 'memory.activeScopePath'],
   ['AQUIFER_RERANK_ENABLED',   'rerank.enabled',    Boolean],
   ['AQUIFER_RERANK_PROVIDER',  'rerank.provider'],
   ['AQUIFER_RERANK_BASE_URL',  'rerank.baseUrl'],
@@ -165,6 +185,14 @@ function loadConfig(opts = {}) {
     config = deepMerge(config, opts.overrides);
   }
 
+  // insights.dedup shorthand: true → enforce, false → off
+  if (config.insights && typeof config.insights.dedup === 'boolean') {
+    config.insights.dedup = {
+      ...DEFAULTS.insights.dedup,
+      mode: config.insights.dedup ? 'enforce' : 'off',
+    };
+  }
+
   return config;
 }
 

package/consumers/shared/factory.js

@@ -91,6 +91,8 @@ function createAquiferFromConfig(overrides) {
     rank: config.rank,
     rerank: rerankOpts,
     migrations: config.migrations,
+    insights: config.insights,
+    memory: config.memory,
   });
 
   return aquifer;

package/consumers/shared/ingest.js

@@ -37,7 +37,7 @@ function evictStale(dedupMap, now = Date.now()) {
  * @param {string} [opts.source] — caller-provided source tag (e.g. 'openclaw', 'cc', 'opencode')
  * @param {string} [opts.sessionKey] — passed through to commit()
  * @param {any[]} opts.rawEntries — host-native session entries
- * @param {'gateway'|'cc'|'claude-code'|'preNormalized'} [opts.adapter]
+ * @param {'gateway'|'cc'|'claude-code'|'codex'|'preNormalized'} [opts.adapter]
  *        'preNormalized' means rawEntries already matches normalizeMessages output
  *        (used by OpenCode which reads SQLite directly).
  * @param {object} [opts.preNormalized] — { messages, userCount, ... } ready to commit,

package/consumers/shared/normalize.js

@@ -5,7 +5,7 @@
 // session-level metadata. Wraps pipeline/normalize so consumers don't each
 // reinvent their own role/content extraction.
 //
-// Supported adapters: 'gateway' | 'cc' (alias of 'claude-code'). The OpenCode
+// Supported adapters: 'gateway' | 'cc' (alias of 'claude-code') | 'codex'. The OpenCode
 // consumer reads from SQLite and constructs the output shape directly; it is
 // not expected to route through here.
 //
@@ -21,13 +21,14 @@ const ADAPTER_ALIASES = {
     'cc': 'claude-code',
     'claude-code': 'claude-code',
     'gateway': 'gateway',
+    'codex': 'codex',
 };
 
 function resolveAdapter(adapter) {
     if (!adapter) return null;  // auto-detect
     const name = ADAPTER_ALIASES[adapter];
     if (!name) {
-        throw new Error(`Unknown adapter: "${adapter}". Supported: gateway, cc (alias claude-code).`);
+        throw new Error(`Unknown adapter: "${adapter}". Supported: gateway, cc (alias claude-code), codex.`);
     }
     return name;
 }
@@ -39,6 +40,16 @@ function extractRawMeta(rawEntries) {
 
     for (const entry of rawEntries || []) {
         if (!entry || typeof entry !== 'object') continue;
+
+        if (entry.type === 'turn_context' && entry.payload?.model && !model) {
+            model = entry.payload.model;
+        }
+        if (entry.type === 'event_msg' && entry.payload?.type === 'token_count') {
+            const usage = entry.payload?.info?.last_token_usage || {};
+            tokensIn += usage.input_tokens || usage.input || 0;
+            tokensOut += usage.output_tokens || usage.output || 0;
+        }
+
         const msg = entry.message || entry;
         if (msg && typeof msg === 'object') {
             if (msg.model && !model) model = msg.model;
@@ -57,7 +68,7 @@ function extractRawMeta(rawEntries) {
  *
  * @param {any[]} rawEntries
  * @param {object} [opts]
- * @param {'gateway'|'cc'|'claude-code'} [opts.adapter] — host adapter; auto-detected if omitted
+ * @param {'gateway'|'cc'|'claude-code'|'codex'} [opts.adapter] — host adapter; auto-detected if omitted
  * @returns {{
  *   messages: {role:string,content:string,timestamp:string|null}[],
  *   userCount: number, assistantCount: number,

package/consumers/shared/recall-format.js

@@ -18,6 +18,24 @@ function formatDateIso(value) {
     return Number.isNaN(d.getTime()) ? 'unknown' : d.toISOString().slice(0, 10);
 }
 
+function isCuratedMemoryResult(result) {
+    return Boolean(result && (
+        result.memoryType || result.memory_type ||
+        result.canonicalKey || result.canonical_key ||
+        result.scopeKey || result.scope_key
+    ));
+}
+
+function curatedTitle(result) {
+    const type = result.memoryType || result.memory_type || 'memory';
+    const title = result.title || result.summary || result.canonicalKey || result.canonical_key || type;
+    return truncate(title, 80);
+}
+
+function resultDate(result) {
+    return result.startedAt || result.acceptedAt || result.accepted_at || result.observedAt || result.observed_at || null;
+}
+
 // 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.
@@ -48,6 +66,11 @@ const defaultRenderers = {
         return query ? `No results found for "${query}".` : 'No matching sessions found.';
     },
     title(result, index) {
+        if (isCuratedMemoryResult(result)) {
+            const date = formatDateIso(resultDate(result));
+            const scope = result.scopeKey || result.scope_key || 'scope:unknown';
+            return `### ${index + 1}. ${curatedTitle(result)} (${date}, ${scope})`;
+        }
         const ss = result.structuredSummary || {};
         const title = ss.title || truncate(result.summaryText, 60) || '(untitled)';
         const date = formatDateIso(result.startedAt);
@@ -55,6 +78,10 @@ const defaultRenderers = {
         return `### ${index + 1}. ${title} (${date}, ${agent})`;
     },
     body(result) {
+        if (isCuratedMemoryResult(result)) {
+            const text = result.summary || result.title || result.canonicalKey || result.canonical_key || '';
+            return text ? truncate(text, 300) : null;
+        }
         const ss = result.structuredSummary || {};
         const text = ss.overview || result.summaryText || '';
         return text ? truncate(text, 300) : null;
@@ -66,6 +93,30 @@ const defaultRenderers = {
         if (!showScore) return null;
         return `Score: ${typeof result.score === 'number' ? result.score.toFixed(3) : '?'}`;
     },
+    explain(result, { showExplain }) {
+        if (!showExplain) return null;
+        const d = result._debug;
+        if (!d) return null;
+        const f = (v) => typeof v === 'number' ? v.toFixed(3) : '?';
+        const parts = [
+            `rrf=${f(d.rrf)}`,
+            `td=${f(d.timeDecay)}`,
+            `access=${f(d.access)}`,
+            `entity=${f(d.entityScore)}`,
+            `trust=${f(d.trustScore)}(\u00d7${f(d.trustMultiplier)})`,
+            `ol=${f(d.openLoopBoost)}`,
+            `\u2192 hybrid=${f(d.hybridScore)}`,
+        ];
+        if (d.rerankApplied) {
+            parts.push(`rerank=${f(d.rerankScore)}(${d.rerankReason || '?'})`);
+        } else {
+            parts.push(`[rerank: off (${d.rerankReason || '?'})]`);
+        }
+        if (Array.isArray(d.searchErrors) && d.searchErrors.length > 0) {
+            parts.push(`errors: ${d.searchErrors.map(e => (e && e.path) || '?').join(',')}`);
+        }
+        return `  ${parts.join(' ')}`;
+    },
     separator() {
         return '';
     },
@@ -102,6 +153,8 @@ function createRecallFormatter(overrides = {}) {
             if (matched) lines.push(matched);
             const score = r.score(res, { showScore: !!opts.showScore, ...ctx });
             if (score) lines.push(score);
+            const explain = r.explain(res, { showExplain: !!opts.showExplain, ...ctx });
+            if (explain) lines.push(explain);
             const sep = r.separator(i, ctx);
             if (sep !== null && sep !== undefined) lines.push(sep);
         }