@shadowforge0/aquifer-memory 0.9.0 → 1.0.0

package/consumers/cli.js

@@ -16,6 +16,26 @@
 
 const { createAquiferFromConfig } = require('./shared/factory');
 
+function formatDate(value, fallback) {
+  if (!value) return fallback;
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? fallback : parsed.toISOString().slice(0, 10);
+}
+
+function quoteIdentifier(identifier) {
+  if (!/^[a-zA-Z_]\w{0,62}$/.test(identifier)) {
+    throw new Error(`Invalid schema name: "${identifier}"`);
+  }
+  return `"${identifier}"`;
+}
+
+function parsePositiveInt(value, fallback) {
+  if (value === undefined || value === null || value === true) return fallback;
+  const parsed = parseInt(value, 10);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(1, parsed);
+}
+
 // ---------------------------------------------------------------------------
 // Argument parser (minimal, no deps)
 // ---------------------------------------------------------------------------
@@ -23,7 +43,7 @@ const { createAquiferFromConfig } = require('./shared/factory');
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   // Flags that take a value (not boolean)
-  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency', 'entities', 'entity-mode', 'session-id', 'verdict', 'note']);
+  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency', 'entities', 'entity-mode', 'session-id', 'verdict', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars']);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
     if (argv[i].startsWith('--')) {
@@ -57,7 +77,7 @@ async function cmdRecall(aquifer, args) {
   }
 
   const recallOpts = {
-    limit: parseInt(args.flags.limit || '5', 10),
+    limit: parsePositiveInt(args.flags.limit, 5),
     agentId: args.flags['agent-id'] || undefined,
     source: args.flags.source || undefined,
     dateFrom: args.flags['date-from'] || undefined,
@@ -83,7 +103,7 @@ async function cmdRecall(aquifer, args) {
     const r = results[i];
     const ss = r.structuredSummary || {};
     const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = r.startedAt ? new Date(r.startedAt).toISOString().slice(0, 10) : '?';
+    const date = formatDate(r.startedAt, '?');
     console.log(`${i + 1}. [${r.score?.toFixed(3)}] ${title} (${date}, ${r.agentId})`);
     if (ss.overview) console.log(`   ${ss.overview.slice(0, 200)}`);
     if (r.matchedTurnText) console.log(`   > ${r.matchedTurnText.slice(0, 150)}`);
@@ -114,7 +134,7 @@ async function cmdFeedback(aquifer, args) {
 }
 
 async function cmdBackfill(aquifer, args) {
-  const limit = parseInt(args.flags.limit || '100', 10);
+  const limit = parsePositiveInt(args.flags.limit, 100);
   const dryRun = !!args.flags['dry-run'];
   const skipSummary = !!args.flags['skip-summary'];
   const skipTurnEmbed = !!args.flags['skip-turn-embed'];
@@ -160,7 +180,7 @@ async function cmdStats(aquifer, args) {
     console.log(`Summaries: ${stats.summaries}`);
     console.log(`Turn embeddings: ${stats.turnEmbeddings}`);
     console.log(`Entities: ${stats.entities}`);
-    if (stats.earliest) console.log(`Range: ${new Date(stats.earliest).toISOString().slice(0, 10)} — ${new Date(stats.latest).toISOString().slice(0, 10)}`);
+    if (stats.earliest) console.log(`Range: ${formatDate(stats.earliest, '?')} — ${formatDate(stats.latest, '?')}`);
   }
 }
 
@@ -211,20 +231,54 @@ async function cmdQuickstart(aquifer) {
   const { loadConfig } = require('./shared/config');
   const config = loadConfig();
   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)`, [sessionId]);
-  await pool.query(`DELETE FROM ${schema}.session_summaries WHERE session_id IN (SELECT id FROM ${schema}.sessions WHERE session_id = $1)`, [sessionId]);
-  await pool.query(`DELETE FROM ${schema}.sessions WHERE session_id = $1`, [sessionId]);
-  await pool.end();
+  const schema = quoteIdentifier(config.schema || 'aquifer');
+  const tenantId = config.tenantId || 'default';
+  try {
+    await pool.query('BEGIN');
+    await pool.query(
+      `DELETE FROM ${schema}.sessions WHERE tenant_id = $1 AND agent_id = $2 AND session_id = $3`,
+      [tenantId, 'quickstart', sessionId]
+    );
+    await pool.query('COMMIT');
+  } catch (err) {
+    await pool.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    await pool.end();
+  }
   console.log('     OK\n');
 
   console.log('✓ Aquifer is working. You can now start the MCP server:');
   console.log('  npx aquifer mcp');
 }
 
+async function cmdBootstrap(aquifer, args) {
+  const result = await aquifer.bootstrap({
+    agentId: args.flags['agent-id'] || undefined,
+    source: args.flags.source || undefined,
+    limit: parsePositiveInt(args.flags.limit, 5),
+    lookbackDays: parsePositiveInt(args.flags['lookback-days'], 14),
+    maxChars: parsePositiveInt(args.flags['max-chars'], 4000),
+    format: args.flags.json ? 'structured' : 'text',
+  });
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    if (result.text) {
+      console.log(result.text);
+    } else {
+      // structured without text — format it
+      const { formatBootstrapText } = require('../core/aquifer');
+      const { text } = formatBootstrapText(result, result.meta?.maxChars || 4000);
+      console.log(text);
+    }
+  }
+}
+
 async function cmdExport(aquifer, args) {
   const output = args.flags.output || null;
-  const limit = parseInt(args.flags.limit || '1000', 10);
+  const limit = parsePositiveInt(args.flags.limit, 1000);
 
   const rows = await aquifer.exportSessions({
     agentId: args.flags['agent-id'],
@@ -267,6 +321,8 @@ Commands:
   backfill                    Enrich pending sessions
   stats                       Show database statistics
   export                      Export sessions as JSONL
+  bootstrap                   Show recent session context (for new session start)
+  ingest-opencode             Import sessions from OpenCode's local SQLite DB
   mcp                         Start MCP server
 
 Options:
@@ -283,7 +339,12 @@ Options:
   --json                      JSON output
   --dry-run                   Preview only (backfill)
   --output PATH               Output file (export)
-  --config PATH               Config file path`);
+  --config PATH               Config file path
+  --lookback-days N           How far back in days (bootstrap, default: 14)
+  --max-chars N               Max output characters (bootstrap, default: 4000)
+  --db PATH                   OpenCode SQLite path (ingest-opencode)
+  --since YYYY-MM-DD          Only ingest sessions after date (ingest-opencode)
+  --min-messages N            Min user messages to ingest (ingest-opencode, default: 3)`);
     process.exit(0);
   }
 
@@ -331,6 +392,14 @@ Options:
       case 'export':
         await cmdExport(aquifer, args);
         break;
+      case 'bootstrap':
+        await cmdBootstrap(aquifer, args);
+        break;
+      case 'ingest-opencode': {
+        const { ingestOpenCode } = require('./opencode');
+        await ingestOpenCode(aquifer, args);
+        break;
+      }
       default:
         console.error(`Unknown command: ${command}. Run 'aquifer --help' for usage.`);
         process.exit(1);

package/consumers/mcp.js

@@ -38,9 +38,11 @@ function formatResults(results, query) {
     const r = results[i];
     const ss = r.structuredSummary || {};
     const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = r.startedAt
-      ? new Date(r.startedAt).toISOString().slice(0, 10)
-      : 'unknown';
+    let date = 'unknown';
+    if (r.startedAt) {
+      const parsed = new Date(r.startedAt);
+      if (!isNaN(parsed.getTime())) date = parsed.toISOString().slice(0, 10);
+    }
 
     lines.push(`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`);
     if (ss.overview || r.summaryText) {
@@ -65,9 +67,11 @@ async function main() {
     ({ StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js'));
     ({ z } = require('zod'));
   } catch (e) {
+    const missingDep = e && (e.code === 'MODULE_NOT_FOUND' || /Cannot find module|^missing\b/i.test(e.message || ''));
+    if (!missingDep) throw e;
     process.stderr.write(
       'aquifer mcp requires @modelcontextprotocol/sdk and zod.\n' +
-      'These should be installed automatically. Try: npm install\n'
+      'Install: npm install @modelcontextprotocol/sdk zod\n'
     );
     process.exit(1);
   }
@@ -204,6 +208,35 @@ async function main() {
     }
   );
 
+  server.tool(
+    'session_bootstrap',
+    'Load recent session context for a new conversation. Returns summaries, open items, and decisions from recent sessions. Call this at the start of a conversation for continuity; use session_recall for keyword search.',
+    {
+      agentId: z.string().optional().describe('Filter by agent ID'),
+      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)'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const result = await aquifer.bootstrap({
+          agentId: params.agentId,
+          limit: params.limit,
+          lookbackDays: params.lookbackDays,
+          maxChars: params.maxChars,
+          format: 'text',
+        });
+        return { content: [{ type: 'text', text: result.text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `session_bootstrap error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   // Graceful shutdown
   const cleanup = async () => {
     if (_aquifer) await _aquifer.close().catch(() => {});

package/consumers/openclaw-plugin.js

@@ -79,15 +79,19 @@ function normalizeEntries(rawEntries) {
   };
 }
 
+function formatDate(value) {
+  if (!value) return 'unknown';
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? 'unknown' : parsed.toISOString().slice(0, 10);
+}
+
 function formatRecallResults(results) {
   if (results.length === 0) return 'No matching sessions found.';
 
   return results.map((r, i) => {
     const ss = r.structuredSummary || {};
     const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = r.startedAt
-      ? new Date(r.startedAt).toISOString().slice(0, 10)
-      : 'unknown';
+    const date = formatDate(r.startedAt);
 
     const lines = [`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`];
     if (ss.overview || r.summaryText) {

package/consumers/opencode.js

@@ -0,0 +1,345 @@
+'use strict';
+
+/**
+ * Aquifer — OpenCode Ingest Consumer
+ *
+ * Reads session history from OpenCode's local SQLite database and commits
+ * conversations into Aquifer for long-term memory (embedding + recall).
+ *
+ * OpenCode stores sessions in ~/.local/share/opencode/opencode.db (SQLite)
+ * with a Drizzle-managed schema: session → message → part.
+ *
+ * Usage (via CLI):
+ *   aquifer ingest-opencode [options]
+ *
+ * Options:
+ *   --db PATH           OpenCode SQLite path (default: ~/.local/share/opencode/opencode.db)
+ *   --agent-id ID       Aquifer agent ID to store under (default: "opencode")
+ *   --limit N           Max sessions to ingest per run (default: 50)
+ *   --since YYYY-MM-DD  Only ingest sessions updated after this date
+ *   --min-messages N    Min user messages to ingest (default: 3)
+ *   --dry-run           Show what would be ingested without committing
+ *   --enrich            Run enrich (summary + embedding) after commit
+ *   --json              JSON output
+ *   --session-id ID     Ingest a single OpenCode session by ID
+ */
+
+const path = require('path');
+const os = require('os');
+const { createAquiferFromConfig } = require('./shared/factory');
+
+// ---------------------------------------------------------------------------
+// SQLite access — use Node 22+ built-in or fall back to better-sqlite3
+// ---------------------------------------------------------------------------
+
+function openSqlite(dbPath) {
+  // Try node:sqlite (Node 22+)
+  try {
+    const { DatabaseSync } = require('node:sqlite');
+    return new DatabaseSync(dbPath, { open: true, readOnly: true });
+  } catch (_) {
+    // not available
+  }
+
+  // Try better-sqlite3
+  try {
+    const Database = require('better-sqlite3');
+    return new Database(dbPath, { readonly: true });
+  } catch (_) {
+    // not available
+  }
+
+  throw new Error(
+    'No SQLite driver found. Upgrade to Node 22+ or install better-sqlite3:\n' +
+    '  npm install better-sqlite3'
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Read sessions from OpenCode SQLite
+// ---------------------------------------------------------------------------
+
+function getOpenCodeSessions(db, { limit = 50, since = null, sessionId = null } = {}) {
+  if (sessionId) {
+    const row = db.prepare(
+      'SELECT id, title, directory, time_created, time_updated FROM session WHERE id = ?'
+    ).get(sessionId);
+    return row ? [row] : [];
+  }
+
+  let sql = `
+    SELECT id, title, directory, time_created, time_updated
+    FROM session
+    WHERE 1=1
+  `;
+  const params = [];
+
+  if (since) {
+    sql += ' AND time_updated >= ?';
+    params.push(new Date(since).getTime());
+  }
+
+  sql += ' ORDER BY time_updated DESC LIMIT ?';
+  params.push(limit);
+
+  return db.prepare(sql).all(...params);
+}
+
+function getSessionConversation(db, sessionId) {
+  // Get messages ordered by creation time
+  const messages = db.prepare(`
+    SELECT id, data, time_created
+    FROM message
+    WHERE session_id = ?
+    ORDER BY time_created ASC
+  `).all(sessionId);
+
+  // Get all parts for this session, grouped by message
+  const parts = db.prepare(`
+    SELECT id, message_id, data, time_created
+    FROM part
+    WHERE session_id = ?
+    ORDER BY time_created ASC
+  `).all(sessionId);
+
+  const partsByMsg = new Map();
+  for (const p of parts) {
+    const msgId = p.message_id;
+    if (!partsByMsg.has(msgId)) partsByMsg.set(msgId, []);
+    partsByMsg.get(msgId).push(p);
+  }
+
+  return { messages, partsByMsg };
+}
+
+// ---------------------------------------------------------------------------
+// Normalize OpenCode conversation → Aquifer messages format
+// ---------------------------------------------------------------------------
+
+function normalizeConversation(messages, partsByMsg) {
+  const normalized = [];
+  let model = null;
+  let tokensIn = 0, tokensOut = 0;
+  let startedAt = null, lastMessageAt = null;
+
+  for (const msg of messages) {
+    const msgData = JSON.parse(msg.data);
+    const role = msgData.role;
+    if (!role || !['user', 'assistant'].includes(role)) continue;
+
+    // Extract model info
+    if (!model) {
+      if (msgData.model?.modelID) model = msgData.model.modelID;
+      else if (msgData.modelID) model = msgData.modelID;
+      else if (msgData.providerID && msgData.modelID) model = `${msgData.providerID}/${msgData.modelID}`;
+    }
+
+    // Accumulate tokens
+    if (msgData.tokens) {
+      tokensIn += msgData.tokens.input || 0;
+      tokensOut += msgData.tokens.output || 0;
+    }
+
+    // Timestamp (ms → ISO)
+    const ts = msg.time_created ? new Date(msg.time_created).toISOString() : null;
+    if (ts && !startedAt) startedAt = ts;
+    if (ts) lastMessageAt = ts;
+
+    // Build content from parts
+    const msgParts = partsByMsg.get(msg.id) || [];
+    const textParts = [];
+
+    for (const part of msgParts) {
+      let partData;
+      try { partData = JSON.parse(part.data); } catch { continue; }
+
+      if (partData.type === 'text' && partData.text) {
+        textParts.push(partData.text);
+      } else if (partData.type === 'tool' && partData.state?.output) {
+        // Include tool results as context (truncated)
+        const toolName = partData.tool || 'tool';
+        const output = partData.state.output;
+        const truncated = output.length > 500 ? output.slice(0, 500) + '...' : output;
+        textParts.push(`[${toolName}]: ${truncated}`);
+      }
+    }
+
+    const content = textParts.join('\n').trim();
+    if (!content) continue;
+
+    // Merge consecutive same-role messages (OpenCode splits assistant into steps)
+    const last = normalized[normalized.length - 1];
+    if (last && last.role === role) {
+      last.content += '\n\n' + content;
+      last.timestamp = ts || last.timestamp;
+    } else {
+      normalized.push({ role, content, timestamp: ts });
+    }
+  }
+
+  return {
+    messages: normalized,
+    userCount: normalized.filter(m => m.role === 'user').length,
+    assistantCount: normalized.filter(m => m.role === 'assistant').length,
+    model,
+    tokensIn,
+    tokensOut,
+    startedAt,
+    lastMessageAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Ingest command
+// ---------------------------------------------------------------------------
+
+async function ingestOpenCode(aquifer, args) {
+  const defaultDb = path.join(os.homedir(), '.local/share/opencode/opencode.db');
+  const dbPath = args.flags.db || defaultDb;
+  const agentId = args.flags['agent-id'] || 'opencode';
+  const limit = Math.max(1, parseInt(args.flags.limit || '50', 10) || 50);
+  const since = args.flags.since || null;
+  const dryRun = !!args.flags['dry-run'];
+  const doEnrich = !!args.flags.enrich;
+  const jsonOutput = !!args.flags.json;
+  const sessionId = args.flags['session-id'] || null;
+  const minUserMessages = parseInt(args.flags['min-messages'] || '3', 10);
+
+  // Open OpenCode DB
+  let db;
+  try {
+    db = openSqlite(dbPath);
+  } catch (err) {
+    console.error(`Cannot open OpenCode database: ${err.message}`);
+    console.error(`Expected at: ${dbPath}`);
+    process.exit(1);
+  }
+
+  // Check which sessions are already in Aquifer
+  const existingSet = new Set();
+  try {
+    const existing = await aquifer.exportSessions({ source: 'opencode', limit: 10000 });
+    for (const row of existing) existingSet.add(row.session_id);
+  } catch (_) {
+    // exportSessions may not exist in all versions
+  }
+
+  // Get OpenCode sessions
+  const sessions = getOpenCodeSessions(db, { limit, since, sessionId });
+
+  const results = [];
+  let committed = 0, skipped = 0, failed = 0;
+
+  for (const session of sessions) {
+    const sid = session.id;
+
+    // Skip already ingested (unless explicitly requested by session-id)
+    if (!sessionId && existingSet.has(sid)) {
+      skipped++;
+      if (jsonOutput) results.push({ sessionId: sid, status: 'exists' });
+      continue;
+    }
+
+    // Read conversation
+    const { messages, partsByMsg } = getSessionConversation(db, sid);
+    const norm = normalizeConversation(messages, partsByMsg);
+
+    if (norm.userCount < minUserMessages) {
+      skipped++;
+      if (jsonOutput) results.push({ sessionId: sid, status: 'too_short', userMessages: norm.userCount });
+      else if (!jsonOutput && !dryRun) {
+        console.log(`  [skip] ${sid} — ${norm.userCount} user msg(s)`);
+      }
+      continue;
+    }
+
+    const info = {
+      sessionId: sid,
+      title: session.title,
+      messages: norm.messages.length,
+      userMessages: norm.userCount,
+      model: norm.model,
+    };
+
+    if (dryRun) {
+      info.status = 'dry-run';
+      if (jsonOutput) {
+        results.push(info);
+      } else {
+        console.log(`  [dry-run] ${sid} "${session.title}" — ${norm.messages.length} msgs (${norm.userCount} user)`);
+      }
+      continue;
+    }
+
+    // Commit to Aquifer
+    try {
+      await aquifer.commit(sid, norm.messages, {
+        agentId,
+        source: 'opencode',
+        model: norm.model,
+        tokensIn: norm.tokensIn,
+        tokensOut: norm.tokensOut,
+        startedAt: norm.startedAt,
+        lastMessageAt: norm.lastMessageAt,
+      });
+      committed++;
+      info.status = 'committed';
+
+      // Enrich if requested
+      if (doEnrich) {
+        try {
+          const enrichResult = await aquifer.enrich(sid, { agentId });
+          info.status = 'enriched';
+          info.turnsEmbedded = enrichResult.turnsEmbedded;
+          info.entitiesFound = enrichResult.entitiesFound;
+        } catch (enrichErr) {
+          info.enrichError = enrichErr.message;
+        }
+      }
+
+      if (jsonOutput) {
+        results.push(info);
+      } else {
+        const enrichNote = info.turnsEmbedded != null ? ` (${info.turnsEmbedded} turns, ${info.entitiesFound} entities)` : '';
+        console.log(`  [${committed}] ${sid} "${session.title}"${enrichNote}`);
+      }
+    } catch (err) {
+      failed++;
+      info.status = 'error';
+      info.error = err.message;
+      if (jsonOutput) {
+        results.push(info);
+      } else {
+        console.error(`  [error] ${sid}: ${err.message}`);
+      }
+    }
+  }
+
+  // Close SQLite
+  db.close();
+
+  // Summary
+  if (jsonOutput) {
+    console.log(JSON.stringify({ committed, skipped, failed, total: sessions.length, sessions: results }, null, 2));
+  } else {
+    console.log(`\nDone. committed=${committed} skipped=${skipped} failed=${failed} total=${sessions.length}`);
+    if (committed > 0 && !doEnrich) {
+      console.log('Tip: run "aquifer backfill" to enrich committed sessions.');
+    }
+  }
+
+  if (failed > 0) process.exitCode = 2;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  ingestOpenCode,
+  // Exposed for testing
+  openSqlite,
+  getOpenCodeSessions,
+  getSessionConversation,
+  normalizeConversation,
+};

package/core/aquifer.js

@@ -583,7 +583,22 @@ function createAquifer(config) {
         weights: overrideWeights,
         entities: explicitEntities,
         entityMode = 'any',
+        strictSearchErrors = false,
       } = opts;
+      const searchErrors = [];
+
+      function recordSearchError(pathName, err) {
+        searchErrors.push({
+          path: pathName,
+          message: err && err.message ? err.message : String(err),
+        });
+      }
+
+      function maybeThrowSearchErrors() {
+        if (!strictSearchErrors || searchErrors.length === 0) return;
+        const details = searchErrors.map(e => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`Recall search failed: ${details}`);
+      }
 
       // Normalize agentId/agentIds into a single resolved value
       // agentIds takes precedence; agentId is sugar for agentIds: [agentId]
@@ -692,17 +707,26 @@ function createAquifer(config) {
         runFts
           ? storage.searchSessions(pool, query, {
               schema, tenantId, agentIds: resolvedAgentIds, source, dateFrom, dateTo, limit: fetchLimit, ftsConfig,
-            }).catch(() => [])
+            }).catch((err) => {
+              recordSearchError('fts', err);
+              return [];
+            })
           : Promise.resolve([]),
         runVector
           ? embeddingSearchSummaries(queryVec, {
               agentIds: resolvedAgentIds, source, dateFrom, dateTo, limit: fetchLimit,
-            }).catch(() => [])
+            }).catch((err) => {
+              recordSearchError('summary-vector', err);
+              return [];
+            })
           : Promise.resolve([]),
         runVector
           ? storage.searchTurnEmbeddings(pool, {
               schema, tenantId, queryVec, dateFrom, dateTo, agentIds: resolvedAgentIds, source, limit: fetchLimit,
-            }).catch(() => ({ rows: [] }))
+            }).catch((err) => {
+              recordSearchError('turn-vector', err);
+              return { rows: [] };
+            })
           : Promise.resolve({ rows: [] }),
       ]);
 
@@ -718,6 +742,7 @@ function createAquifer(config) {
       const filteredTurn = filterFn(turnRows);
 
       if (filteredFts.length === 0 && filteredEmb.length === 0 && filteredTurn.length === 0) {
+        maybeThrowSearchErrors();
         return [];
       }
 
@@ -737,7 +762,7 @@ function createAquifer(config) {
       const EXTERNAL_TIMEOUT = 10000;
       const externalRows = [];
       const externalPromises = [];
-      for (const [, sourceConfig] of sources) {
+      for (const [name, sourceConfig] of sources) {
         if (typeof sourceConfig.search === 'function') {
           const w = sourceConfig.weight !== null && sourceConfig.weight !== undefined ? sourceConfig.weight : 1.0;
           externalPromises.push(
@@ -750,7 +775,9 @@ function createAquifer(config) {
                   if (r && r.session_id) externalRows.push({ ...r, _externalWeight: w });
                 }
               }
-            }).catch(() => { /* external source failure/timeout non-fatal */ })
+            }).catch((err) => {
+              recordSearchError(`external:${name}`, err);
+            })
           );
         }
       }
@@ -835,6 +862,7 @@ function createAquifer(config) {
           hybridScore: r._hybridScore ?? r._score,
           rerankScore: r._rerankScore ?? null,
           rerankFallback: r._rerankFallback || false,
+          searchErrors: searchErrors.slice(),
         },
       }));
     },
@@ -1008,13 +1036,164 @@ function createAquifer(config) {
       );
       return result.rows;
     },
+
+    async bootstrap(opts = {}) {
+      await ensureMigrated();
+
+      const agentId = opts.agentId || null;
+      const source = opts.source || null;
+      const limit = Math.max(1, Math.min(20, opts.limit || 5));
+      const lookbackDays = opts.lookbackDays || 14;
+      const maxChars = opts.maxChars || 4000;
+      const format = opts.format || 'structured';
+
+      const where = [`s.tenant_id = $1`, `s.processing_status = 'succeeded'`];
+      const params = [tenantId];
+
+      if (agentId) {
+        params.push(agentId);
+        where.push(`s.agent_id = $${params.length}`);
+      }
+      if (source) {
+        params.push(source);
+        where.push(`s.source = $${params.length}`);
+      }
+
+      params.push(lookbackDays);
+      where.push(`s.started_at > now() - ($${params.length} || ' days')::interval`);
+
+      params.push(limit);
+
+      const result = await pool.query(
+        `SELECT s.session_id, s.agent_id, s.source, s.started_at, s.msg_count,
+                ss.summary_text, ss.structured_summary
+         FROM ${qi(schema)}.sessions s
+         JOIN ${qi(schema)}.session_summaries ss ON ss.session_row_id = s.id
+         WHERE ${where.join(' AND ')}
+         ORDER BY s.started_at DESC
+         LIMIT $${params.length}`,
+        params
+      );
+
+      const sessions = result.rows.map(r => {
+        const ss = r.structured_summary || {};
+        const hasSS = ss.title || ss.overview;
+        return {
+          sessionId: r.session_id,
+          agentId: r.agent_id,
+          source: r.source,
+          startedAt: r.started_at,
+          title: ss.title || (hasSS ? null : (r.summary_text || '').slice(0, 60).trim() || null),
+          overview: ss.overview || (hasSS ? null : (r.summary_text || '').slice(0, 200).trim() || null),
+          topics: Array.isArray(ss.topics) ? ss.topics : [],
+          decisions: Array.isArray(ss.decisions) ? ss.decisions : [],
+          openLoops: Array.isArray(ss.open_loops) ? ss.open_loops : [],
+          importantFacts: Array.isArray(ss.important_facts) ? ss.important_facts : [],
+        };
+      });
+
+      // Cross-session open loops merge + dedup + sentinel filter
+      const SENTINELS = new Set(['無', 'none', 'n/a', 'na', 'done', '']);
+      const seenLoops = new Set();
+      const openLoops = [];
+      for (const s of sessions) {
+        for (const loop of s.openLoops) {
+          const raw = typeof loop === 'string' ? loop : (loop.item || '');
+          const normalized = raw.trim().replace(/\s+/g, ' ').toLowerCase();
+          if (SENTINELS.has(normalized) || !normalized || seenLoops.has(normalized)) continue;
+          seenLoops.add(normalized);
+          openLoops.push({ item: raw.trim(), fromSession: s.sessionId, latestStartedAt: s.startedAt });
+        }
+      }
+
+      // Cross-session recent decisions dedup
+      const seenDecisions = new Set();
+      const recentDecisions = [];
+      for (const s of sessions) {
+        for (const d of s.decisions) {
+          const key = typeof d === 'string' ? d : (d.decision || '');
+          const normalized = key.trim().replace(/\s+/g, ' ').toLowerCase();
+          if (!normalized || seenDecisions.has(normalized)) continue;
+          seenDecisions.add(normalized);
+          recentDecisions.push({ decision: key.trim(), reason: d.reason || null, fromSession: s.sessionId });
+        }
+      }
+
+      const structured = {
+        sessions,
+        openLoops,
+        recentDecisions,
+        meta: { lookbackDays, count: sessions.length, maxChars, truncated: false },
+      };
+
+      if (format === 'text' || format === 'both') {
+        const textResult = formatBootstrapText(structured, maxChars);
+        structured.text = textResult.text;
+        structured.meta.truncated = textResult.truncated;
+      }
+
+      return structured;
+    },
   };
 
   return aquifer;
 }
 
+// ---------------------------------------------------------------------------
+// formatBootstrapText — pure function, builds <session-bootstrap> XML block
+// ---------------------------------------------------------------------------
+
+function formatBootstrapText(data, maxChars) {
+  if (!data.sessions || data.sessions.length === 0) {
+    return { text: 'No recent sessions found.', truncated: false };
+  }
+
+  let truncated = false;
+  const parts = [];
+
+  // Build session lines (newest first, truncate from oldest if over budget)
+  const sessionLines = [];
+  for (const s of data.sessions) {
+    const date = s.startedAt ? new Date(s.startedAt).toISOString().slice(0, 10) : '?';
+    const title = s.title || '(untitled)';
+    const overview = s.overview ? s.overview.slice(0, 200) : '';
+    let line = `- ${date} | ${title}`;
+    if (overview) line += ` — ${overview}`;
+    const decisions = s.decisions
+      .map(d => typeof d === 'string' ? d : d.decision)
+      .filter(Boolean);
+    if (decisions.length > 0) line += `\n  Decisions: ${decisions.join('; ')}`;
+    sessionLines.push(line);
+  }
+
+  // Fit within maxChars by removing oldest sessions
+  let bodyLines = [...sessionLines];
+  const footer = [];
+  if (data.openLoops.length > 0) {
+    footer.push(`Open items: ${data.openLoops.map(l => l.item).join(', ')}`);
+  }
+  if (data.recentDecisions.length > 0) {
+    footer.push(`Recent decisions: ${data.recentDecisions.map(d => d.decision).join(', ')}`);
+  }
+
+  const buildText = (lines) => {
+    const body = ['Recent sessions:', ...lines].join('\n');
+    const full = footer.length > 0 ? body + '\n' + footer.join('\n') : body;
+    return `<session-bootstrap sessions="${lines.length}" open_loops="${data.openLoops.length}">\n${full}\n</session-bootstrap>`;
+  };
+
+  let text = buildText(bodyLines);
+  while (text.length > maxChars && bodyLines.length > 1) {
+    bodyLines.pop();  // remove oldest
+    truncated = true;
+    text = buildText(bodyLines);
+  }
+
+  return { text, truncated };
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
 
-module.exports = { createAquifer };
+module.exports = { createAquifer, formatBootstrapText };

package/core/hybrid-rank.js

@@ -36,12 +36,12 @@ function rrfFusion(ftsResults = [], embResults = [], turnResults = [], K = 60) {
 // timeDecay — sigmoid decay based on age in days
 // ---------------------------------------------------------------------------
 
-function timeDecay(startedAt, midpointDays = 45, steepness = 0.05) {
+function timeDecay(startedAt, midpointDays = 45, steepness = 0.05, nowMs = Date.now()) {
   if (!startedAt) return 0.5;
   const dt = typeof startedAt === 'string' ? new Date(startedAt) : startedAt;
   if (isNaN(dt.getTime())) return 0.5;
 
-  const ageDays = (Date.now() - dt.getTime()) / (1000 * 60 * 60 * 24);
+  const ageDays = (nowMs - dt.getTime()) / (1000 * 60 * 60 * 24);
   return 1 / (1 + Math.exp(steepness * (ageDays - midpointDays)));
 }
 
@@ -49,14 +49,14 @@ function timeDecay(startedAt, midpointDays = 45, steepness = 0.05) {
 // accessScore — exponential decay on access recency (30-day half-life)
 // ---------------------------------------------------------------------------
 
-function accessScore(accessCount, lastAccessedAt) {
+function accessScore(accessCount, lastAccessedAt, nowMs = Date.now()) {
   if (!accessCount || accessCount <= 0) return 0;
   if (!lastAccessedAt) return 0;
 
   const dt = typeof lastAccessedAt === 'string' ? new Date(lastAccessedAt) : lastAccessedAt;
   if (isNaN(dt.getTime())) return 0;
 
-  const daysSince = (Date.now() - dt.getTime()) / (1000 * 60 * 60 * 24);
+  const daysSince = (nowMs - dt.getTime()) / (1000 * 60 * 60 * 24);
   return accessCount * Math.exp(-0.693 * daysSince / 30);
 }
 
@@ -89,6 +89,7 @@ function hybridRank(ftsResults, embResults, turnResults, opts = {}) {
   } = opts;
 
   const w = { ...DEFAULT_WEIGHTS, ...weights };
+  const nowMs = opts.nowMs ?? Date.now();
 
   // Build allResults map: session_id → result object
   const allResults = new Map();
@@ -140,11 +141,12 @@ function hybridRank(ftsResults, embResults, turnResults, opts = {}) {
     const rawRrf = rrfScores.get(sessionId) || 0;
     const normRrf = maxRrf > 0 ? rawRrf / maxRrf : 0;
 
-    const td = timeDecay(result.started_at);
+    const td = timeDecay(result.started_at, 45, 0.05, nowMs);
 
     const accessEff = accessScore(
       result.access_count || 0,
       result.last_accessed_at,
+      nowMs,
     );
     const as = 1 - Math.exp(-accessEff / 5);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shadowforge0/aquifer-memory",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "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": [
@@ -21,6 +21,7 @@
     "./pipeline/*": "./pipeline/*.js",
     "./consumers/mcp": "./consumers/mcp.js",
     "./consumers/openclaw-plugin": "./consumers/openclaw-plugin.js",
+    "./consumers/opencode": "./consumers/opencode.js",
     "./consumers/shared/config": "./consumers/shared/config.js",
     "./consumers/shared/factory": "./consumers/shared/factory.js"
   },