@shadowforge0/aquifer-memory 0.2.0

package/consumers/mcp.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Aquifer MCP Server — session_recall tool via Model Context Protocol.
+ *
+ * Usage:
+ *   npx aquifer mcp
+ *   node consumers/mcp.js
+ *
+ * Config via environment variables (see consumers/shared/config.js).
+ * Requires: DATABASE_URL + AQUIFER_EMBED_BASE_URL + AQUIFER_EMBED_MODEL
+ */
+
+const { createAquiferFromConfig } = require('./shared/factory');
+
+let _aquifer = null;
+
+function getAquifer() {
+  if (!_aquifer) _aquifer = createAquiferFromConfig();
+  return _aquifer;
+}
+
+// ---------------------------------------------------------------------------
+// Format recall results as readable text
+// ---------------------------------------------------------------------------
+
+function formatResults(results, query) {
+  if (results.length === 0) return `No results found for "${query}".`;
+
+  const lines = [`Found ${results.length} result(s) for "${query}":\n`];
+  for (let i = 0; i < results.length; i++) {
+    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';
+
+    lines.push(`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`);
+    if (ss.overview || r.summaryText) {
+      lines.push((ss.overview || r.summaryText).slice(0, 300));
+    }
+    if (r.matchedTurnText) {
+      lines.push(`Matched turn: ${r.matchedTurnText.slice(0, 200)}`);
+    }
+    lines.push(`Score: ${r.score?.toFixed(3) || '?'}\n`);
+  }
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Start MCP server
+// ---------------------------------------------------------------------------
+
+async function main() {
+  let McpServer, StdioServerTransport, z;
+  try {
+    ({ McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js'));
+    ({ StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js'));
+    ({ z } = require('zod'));
+  } catch (e) {
+    process.stderr.write(
+      'aquifer mcp requires @modelcontextprotocol/sdk and zod.\n' +
+      'Install: npm install @modelcontextprotocol/sdk zod\n'
+    );
+    process.exit(1);
+  }
+
+  const server = new McpServer({
+    name: 'aquifer-memory',
+    version: '0.2.0',
+  });
+
+  server.tool(
+    'session_recall',
+    'Search stored sessions by keyword, returning ranked summaries and matched conversation turns.',
+    {
+      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)'),
+      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'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const limit = params.limit || 5;
+
+        const results = await aquifer.recall(params.query, {
+          limit,
+          agentId: params.agentId || undefined,
+          source: params.source || undefined,
+          dateFrom: params.dateFrom || undefined,
+          dateTo: params.dateTo || undefined,
+        });
+
+        const text = formatResults(results, params.query);
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `session_recall error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // Graceful shutdown
+  const cleanup = async () => {
+    if (_aquifer?._pool) await _aquifer._pool.end().catch(() => {});
+    process.exit(0);
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Clean up pool when transport closes (stdin EOF)
+  transport.onclose = async () => {
+    if (_aquifer?._pool) await _aquifer._pool.end().catch(() => {});
+  };
+}
+
+// Only execute when run directly, not when required as a module
+if (require.main === module) {
+  main().catch(err => {
+    process.stderr.write(`aquifer-mcp error: ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { main };

package/consumers/openclaw-plugin.js

@@ -0,0 +1,235 @@
+'use strict';
+
+/**
+ * Aquifer Memory — OpenClaw Plugin
+ *
+ * Auto-captures sessions on before_reset and provides session_recall tool.
+ * Install: add to openclaw.json plugins or extensions directory.
+ *
+ * Config via plugin config, environment variables, or aquifer.config.json.
+ */
+
+const { createAquiferFromConfig } = require('./shared/factory');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function coerceRawEntries(messages) {
+  if (!Array.isArray(messages)) return [];
+  return messages.flatMap((item) => {
+    if (!item || typeof item !== 'object') return [];
+    if (item.role) return [item];
+    if (item.message?.role) return [item.message];
+    return [];
+  });
+}
+
+function normalizeEntries(rawEntries) {
+  const normalized = [];
+  let userCount = 0, assistantCount = 0;
+  let model = null, tokensIn = 0, tokensOut = 0;
+  let startedAt = null, lastMessageAt = null;
+
+  for (const entry of rawEntries) {
+    const msg = entry.message || entry;
+    if (!msg || !msg.role) continue;
+    if (!['user', 'assistant', 'system'].includes(msg.role)) continue;
+
+    let content = '';
+    if (typeof msg.content === 'string') {
+      content = msg.content;
+    } else if (Array.isArray(msg.content)) {
+      content = msg.content
+        .filter(c => c.type === 'text')
+        .map(c => c.text || '')
+        .join('\n');
+    }
+
+    const ts = entry.timestamp || msg.timestamp || null;
+    if (ts && !startedAt) startedAt = ts;
+    if (ts) lastMessageAt = ts;
+
+    if (msg.role === 'user') userCount++;
+    if (msg.role === 'assistant') assistantCount++;
+    if (msg.model && !model) model = msg.model;
+    if (msg.usage) {
+      tokensIn += msg.usage.input_tokens || msg.usage.input || 0;
+      tokensOut += msg.usage.output_tokens || msg.usage.output || 0;
+    }
+
+    normalized.push({ role: msg.role, content, timestamp: ts });
+  }
+
+  return {
+    messages: normalized,
+    userCount,
+    assistantCount,
+    model,
+    tokensIn,
+    tokensOut,
+    startedAt,
+    lastMessageAt,
+  };
+}
+
+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 lines = [`### ${i + 1}. ${title} (${date}, ${r.agentId || 'default'})`];
+    if (ss.overview || r.summaryText) {
+      lines.push((ss.overview || r.summaryText).slice(0, 300));
+    }
+    if (r.matchedTurnText) {
+      lines.push(`Matched: ${r.matchedTurnText.slice(0, 200)}`);
+    }
+    return lines.join('\n');
+  }).join('\n\n');
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  id: 'aquifer-memory',
+  name: 'Aquifer Memory',
+
+  register(api) {
+    const pluginConfig = api.pluginConfig || {};
+    let aquifer;
+
+    try {
+      aquifer = createAquiferFromConfig(pluginConfig);
+    } catch (err) {
+      api.logger.warn(`[aquifer-memory] disabled: ${err.message}`);
+      return;
+    }
+
+    const minUserMessages = pluginConfig.minUserMessages || 3;
+    const recentlyProcessed = new Map();
+    const inFlight = new Set();
+
+    // --- before_reset: auto-capture sessions ---
+
+    api.on('before_reset', (event, ctx) => {
+      const sessionId = ctx?.sessionId || event?.sessionId;
+      const agentId = ctx?.agentId || pluginConfig.agentId || 'main';
+      const sessionKey = ctx?.sessionKey || null;
+
+      if (!sessionId) return;
+      if ((sessionKey || '').includes('subagent')) return;
+      if ((sessionKey || '').includes(':cron:')) return;
+
+      const dedupKey = `${agentId}:${sessionId}`;
+      if (recentlyProcessed.has(dedupKey) || inFlight.has(dedupKey)) return;
+
+      const rawEntries = coerceRawEntries(event?.messages || []);
+      if (rawEntries.length < 3) {
+        api.logger.info(`[aquifer-memory] skip: ${sessionId} only ${rawEntries.length} msgs`);
+        return;
+      }
+
+      inFlight.add(dedupKey);
+      api.logger.info(`[aquifer-memory] capturing ${sessionId} (${rawEntries.length} entries)`);
+
+      (async () => {
+        try {
+          const norm = normalizeEntries(rawEntries);
+          if (norm.userCount === 0) {
+            api.logger.info(`[aquifer-memory] skip: no user messages in ${sessionId}`);
+            return;
+          }
+
+          // Commit
+          await aquifer.commit(sessionId, norm.messages, {
+            agentId,
+            source: 'openclaw',
+            sessionKey,
+            model: norm.model,
+            tokensIn: norm.tokensIn,
+            tokensOut: norm.tokensOut,
+            startedAt: norm.startedAt,
+            lastMessageAt: norm.lastMessageAt,
+          });
+          api.logger.info(`[aquifer-memory] committed ${sessionId}`);
+
+          // Enrich (if enough messages)
+          if (norm.userCount >= minUserMessages) {
+            try {
+              const result = await aquifer.enrich(sessionId, { agentId });
+              api.logger.info(`[aquifer-memory] enriched ${sessionId} (${result.turnsEmbedded} turns, ${result.entitiesFound} entities)`);
+            } catch (enrichErr) {
+              api.logger.warn(`[aquifer-memory] enrich failed for ${sessionId}: ${enrichErr.message}`);
+            }
+          }
+
+          recentlyProcessed.set(dedupKey, Date.now());
+        } catch (err) {
+          api.logger.warn(`[aquifer-memory] capture failed for ${sessionId}: ${err.message}`);
+        } finally {
+          inFlight.delete(dedupKey);
+          // Evict old entries
+          if (recentlyProcessed.size > 200) {
+            const cutoff = Date.now() - 30 * 60 * 1000;
+            for (const [k, ts] of recentlyProcessed) {
+              if (ts < cutoff) recentlyProcessed.delete(k);
+            }
+          }
+        }
+      })();
+    });
+
+    // --- session_recall tool ---
+
+    api.registerTool((ctx) => {
+      if ((ctx?.sessionKey || '').includes('subagent')) return null;
+
+      return {
+        name: 'session_recall',
+        description: 'Search stored sessions by keyword, returning ranked summaries and matched conversation turns.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Search query' },
+            limit: { type: 'number', description: 'Max results (default 5, max 20)' },
+            agentId: { type: 'string', description: 'Filter by agent ID' },
+            source: { type: 'string', description: 'Filter by source' },
+            dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
+            dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+          },
+          required: ['query'],
+        },
+        async execute(_toolCallId, params) {
+          try {
+            const limit = Math.max(1, Math.min(20, parseInt(params?.limit ?? 5, 10) || 5));
+            const results = await aquifer.recall(params.query, {
+              limit,
+              agentId: params.agentId || undefined,
+              source: params.source || undefined,
+              dateFrom: params.dateFrom || undefined,
+              dateTo: params.dateTo || undefined,
+            });
+
+            const text = formatRecallResults(results);
+            return { content: [{ type: 'text', text }] };
+          } catch (err) {
+            return {
+              content: [{ type: 'text', text: `session_recall error: ${err.message}` }],
+              isError: true,
+            };
+          }
+        },
+      };
+    }, { name: 'session_recall' });
+
+    api.logger.info('[aquifer-memory] registered (before_reset + session_recall)');
+  },
+};

package/consumers/shared/config.js

@@ -0,0 +1,143 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULTS = {
+  db: { url: null, max: 10, idleTimeoutMs: 30000 },
+  schema: 'aquifer',
+  tenantId: 'default',
+  defaults: { agentId: null, source: 'api' },
+  embed: {
+    baseUrl: null,
+    model: null,
+    apiKey: null,
+    dim: null,
+    timeoutMs: 120000,
+    maxRetries: 3,
+    chunkSize: 32,
+  },
+  llm: {
+    baseUrl: null,
+    model: null,
+    apiKey: null,
+    timeoutMs: 60000,
+    maxRetries: 3,
+    temperature: 0,
+  },
+  entities: { enabled: false, mergeCall: true },
+  rank: { rrf: 0.65, timeDecay: 0.25, access: 0.10, entityBoost: 0.18 },
+};
+
+// ---------------------------------------------------------------------------
+// Env var mapping: ENV_NAME → config path
+// ---------------------------------------------------------------------------
+
+const ENV_MAP = [
+  ['DATABASE_URL',              'db.url'],
+  ['AQUIFER_DB_URL',            'db.url'],
+  ['AQUIFER_DB_MAX',            'db.max',            Number],
+  ['AQUIFER_SCHEMA',            'schema'],
+  ['AQUIFER_TENANT_ID',         'tenantId'],
+  ['AQUIFER_AGENT_ID',          'defaults.agentId'],
+  ['AQUIFER_SOURCE',            'defaults.source'],
+  ['AQUIFER_EMBED_BASE_URL',    'embed.baseUrl'],
+  ['AQUIFER_EMBED_MODEL',       'embed.model'],
+  ['AQUIFER_EMBED_API_KEY',     'embed.apiKey'],
+  ['AQUIFER_EMBED_DIM',         'embed.dim',         Number],
+  ['AQUIFER_EMBED_TIMEOUT_MS',  'embed.timeoutMs',   Number],
+  ['AQUIFER_EMBED_CHUNK_SIZE',  'embed.chunkSize',   Number],
+  ['AQUIFER_LLM_BASE_URL',      'llm.baseUrl'],
+  ['AQUIFER_LLM_MODEL',         'llm.model'],
+  ['AQUIFER_LLM_API_KEY',       'llm.apiKey'],
+  ['AQUIFER_LLM_TIMEOUT_MS',    'llm.timeoutMs',     Number],
+  ['AQUIFER_LLM_TEMPERATURE',   'llm.temperature',   Number],
+  ['AQUIFER_ENTITIES_ENABLED',  'entities.enabled',  Boolean],
+];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function deepMerge(target, source) {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (source[key] !== undefined && source[key] !== null
+        && typeof source[key] === 'object' && !Array.isArray(source[key])
+        && typeof result[key] === 'object' && result[key] !== null) {
+      result[key] = deepMerge(result[key], source[key]);
+    } else if (source[key] !== undefined) {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+function setPath(obj, dotPath, value) {
+  const parts = dotPath.split('.');
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!cur[parts[i]] || typeof cur[parts[i]] !== 'object') cur[parts[i]] = {};
+    cur = cur[parts[i]];
+  }
+  cur[parts[parts.length - 1]] = value;
+}
+
+function coerceEnvValue(raw, type) {
+  if (type === Number) return Number(raw);
+  if (type === Boolean) return raw === 'true' || raw === '1' || raw === 'yes';
+  return raw;
+}
+
+// ---------------------------------------------------------------------------
+// loadConfig
+// ---------------------------------------------------------------------------
+
+function loadConfig(opts = {}) {
+  const env = opts.env || process.env;
+  let config = JSON.parse(JSON.stringify(DEFAULTS));
+
+  // 1. Config file
+  const configPath = opts.configPath || env.AQUIFER_CONFIG || null;
+  const candidates = configPath
+    ? [configPath]
+    : [
+        path.join(opts.cwd || process.cwd(), 'aquifer.config.json'),
+        path.join(opts.cwd || process.cwd(), 'aquifer.config.js'),
+      ];
+
+  for (const candidate of candidates) {
+    try {
+      if (candidate.endsWith('.json')) {
+        const raw = fs.readFileSync(candidate, 'utf8');
+        config = deepMerge(config, JSON.parse(raw));
+      } else if (candidate.endsWith('.js') || candidate.endsWith('.cjs')) {
+        config = deepMerge(config, require(candidate));
+      }
+      break;
+    } catch (e) {
+      if (e.code !== 'ENOENT' && e.code !== 'MODULE_NOT_FOUND') throw e;
+    }
+  }
+
+  // 2. Environment variables
+  for (const [envName, configPath, type] of ENV_MAP) {
+    const val = env[envName];
+    if (val !== undefined && val !== '') {
+      setPath(config, configPath, type ? coerceEnvValue(val, type) : val);
+    }
+  }
+
+  // 3. Programmatic overrides
+  if (opts.overrides) {
+    config = deepMerge(config, opts.overrides);
+  }
+
+  return config;
+}
+
+module.exports = { loadConfig, DEFAULTS };

package/consumers/shared/factory.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { Pool } = require('pg');
+const { createAquifer, createEmbedder } = require('../../index');
+const { loadConfig } = require('./config');
+const { createLlmFn } = require('./llm');
+
+// ---------------------------------------------------------------------------
+// createAquiferFromConfig
+// ---------------------------------------------------------------------------
+
+function createAquiferFromConfig(overrides) {
+  const config = loadConfig({ overrides });
+
+  if (!config.db.url) {
+    throw new Error('Database URL is required (set DATABASE_URL or AQUIFER_DB_URL)');
+  }
+
+  // Pool
+  const pool = new Pool({
+    connectionString: config.db.url,
+    max: config.db.max || 10,
+    idleTimeoutMillis: config.db.idleTimeoutMs || 30000,
+  });
+
+  // Embed function (optional — lazy validation in core)
+  let embedFn = null;
+  if (config.embed && config.embed.baseUrl && config.embed.model) {
+    // Detect provider from baseUrl
+    const isOllama = config.embed.baseUrl.includes('11434') || config.embed.baseUrl.includes('ollama');
+    const embedder = isOllama
+      ? createEmbedder({
+          provider: 'ollama',
+          ollamaUrl: config.embed.baseUrl.replace(/\/v1\/?$/, ''),
+          model: config.embed.model,
+          chunkSize: config.embed.chunkSize || 32,
+          timeout: config.embed.timeoutMs || 120000,
+          maxRetries: config.embed.maxRetries || 3,
+          initialBackoffMs: 2000,
+        })
+      : createEmbedder({
+          provider: 'openai',
+          openaiApiKey: config.embed.apiKey || '',
+          openaiModel: config.embed.model,
+          openaiDimensions: config.embed.dim || undefined,
+          chunkSize: config.embed.chunkSize || 100,
+          timeout: config.embed.timeoutMs || 120000,
+          maxRetries: config.embed.maxRetries || 3,
+          initialBackoffMs: 2000,
+        });
+    embedFn = (texts) => embedder.embedBatch(texts);
+  }
+
+  // LLM function (optional)
+  let llmFn = null;
+  if (config.llm && config.llm.baseUrl && config.llm.model) {
+    llmFn = createLlmFn(config.llm);
+  }
+
+  const aquifer = createAquifer({
+    db: pool,
+    schema: config.schema,
+    tenantId: config.tenantId,
+    embed: embedFn ? { fn: embedFn, dim: config.embed.dim || null } : null,
+    llm: llmFn ? { fn: llmFn } : null,
+    entities: config.entities,
+    rank: config.rank,
+  });
+
+  // Attach pool for lifecycle management
+  aquifer._pool = pool;
+  aquifer._config = config;
+
+  return aquifer;
+}
+
+module.exports = { createAquiferFromConfig };