@shadowforge0/aquifer-memory 0.9.1 → 1.0.0

package/consumers/cli.js

@@ -43,7 +43,7 @@ function parsePositiveInt(value, fallback) {
 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('--')) {
@@ -252,6 +252,30 @@ async function cmdQuickstart(aquifer) {
   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 = parsePositiveInt(args.flags.limit, 1000);
@@ -297,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:
@@ -313,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);
   }
 
@@ -361,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

@@ -208,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/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

@@ -1036,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/package.json

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