@shadowforge0/aquifer-memory 1.0.2 → 1.2.1

package/consumers/miranda/daily-entries.js

@@ -0,0 +1,224 @@
+'use strict';
+
+const crypto = require('crypto');
+const { parseHandoffSection } = require('./prompts/summary');
+
+// ---------------------------------------------------------------------------
+// Miranda daily log — writes to host-owned `miranda.daily_entries` table.
+//
+// Self-contained DAL: the SQL lives here instead of in session-dal so the
+// plugin doesn't pull in OpenClaw host code. The host injects a pg.Pool.
+//
+// Table layout (matches live miranda.daily_entries):
+//   id, event_at, source, tag, text, agent_id, session_id, metadata, dedupe_key
+// ---------------------------------------------------------------------------
+
+const TABLE = 'miranda.daily_entries';
+const UPSERT_TAGS = new Set(['[FOCUS]', '[TODO]', '[STATS]', '[HIGHLIGHT]', '[SYSTEM]', '[HANDOFF]']);
+
+function taipeiDateString(now) {
+    if (!now) now = new Date();
+    return new Intl.DateTimeFormat('sv-SE', {
+        timeZone: 'Asia/Taipei',
+        year: 'numeric', month: '2-digit', day: '2-digit',
+    }).format(now);
+}
+
+function textHash6(text) {
+    const normalized = (text || '').normalize('NFKC').replace(/\s+/g, ' ').trim().toLowerCase();
+    if (!normalized) return 'empty';
+    return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 6);
+}
+
+async function insertDailyEntry(pool, { eventAt, source, tag, text, agentId, sessionId, metadata, dedupeKey }) {
+    const shouldUpsert = dedupeKey && UPSERT_TAGS.has(tag);
+    const sql = shouldUpsert
+        ? `INSERT INTO ${TABLE}
+             (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
+             text = EXCLUDED.text,
+             event_at = EXCLUDED.event_at,
+             metadata = EXCLUDED.metadata
+           RETURNING id, event_at, source, tag, text`
+        : `INSERT INTO ${TABLE}
+             (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
+           RETURNING id, event_at, source, tag, text`;
+    const result = await pool.query(sql, [
+        eventAt,
+        source,
+        tag || null,
+        text,
+        agentId || 'main',
+        sessionId || null,
+        metadata ? JSON.stringify(metadata) : '{}',
+        dedupeKey || null,
+    ]);
+    return result.rows[0] || null;
+}
+
+async function getDailyEntries(pool, date, agentId) {
+    const result = await pool.query(
+        `SELECT * FROM ${TABLE}
+         WHERE (event_at AT TIME ZONE 'Asia/Taipei')::date = $1
+           AND ($2::text IS NULL OR agent_id = $2)
+         ORDER BY event_at ASC`,
+        [date, agentId || null],
+    );
+    return result.rows;
+}
+
+// ---------------------------------------------------------------------------
+
+async function fetchDailyContext(pool, date, agentId) {
+    const rows = await getDailyEntries(pool, date, agentId);
+    if (!rows || rows.length === 0) return '';
+
+    let currentFocus = '';
+    let currentTodo = '';
+    const entries = [];
+
+    for (const row of rows) {
+        if (row.tag === '[FOCUS]') currentFocus = row.text;
+        else if (row.tag === '[TODO]') currentTodo = row.text;
+        else if (!row.tag || row.tag === '[CLI]') {
+            const time = new Date(row.event_at).toLocaleTimeString('sv-SE', {
+                timeZone: 'Asia/Taipei', hour: '2-digit', minute: '2-digit',
+            });
+            entries.push(`- (${time}) ${row.text}`);
+        }
+    }
+
+    const recentEntries = entries.slice(-20);
+    const parts = [];
+    if (currentFocus) parts.push(`當前焦點: ${currentFocus}`);
+    if (currentTodo) parts.push(`當前待辦:\n${currentTodo}`);
+    if (recentEntries.length > 0) parts.push(`今日紀錄:\n${recentEntries.join('\n')}`);
+
+    let text = parts.join('\n\n');
+    if (text.length > 3000) text = text.slice(0, 3000) + '\n...(truncated)';
+    return text;
+}
+
+async function writeDailyEntries({
+    sections, recap, pool, sessionId, agentId, logger = console,
+    source = 'afterburn', tag = null, now, renderDailyLog,
+}) {
+    if (!now) now = new Date();
+    // Daily entries are work logs — always attribute to main
+    if (agentId === 'cc') agentId = 'main';
+    const date = taipeiDateString(now);
+    let inserted = 0;
+    let focusUpdated = false;
+    let todoUpdated = false;
+
+    // Session bullets
+    if (sections?.session_entries) {
+        const entryLines = sections.session_entries.split('\n');
+        const bullets = entryLines.filter(l => l.trim().startsWith('- ')).map(l => l.trim().slice(2));
+        for (const bullet of bullets) {
+            const timeMatch = bullet.match(/^\((\d{2}:\d{2})\)\s*(.*)/);
+            const text = timeMatch ? timeMatch[2] : bullet;
+            const eventAt = now.toISOString();
+            const row = await insertDailyEntry(pool, {
+                eventAt, source, tag, text,
+                agentId, sessionId, metadata: {},
+                dedupeKey: `daily:${date}:${textHash6(text)}`,
+            });
+            if (row) inserted++;
+        }
+        if (logger.info) logger.info(`[miranda] wrote ${inserted} daily entries`);
+    }
+
+    // Focus
+    if (recap?.focus_decision === 'update' && recap.focus) {
+        await insertDailyEntry(pool, {
+            eventAt: now.toISOString(), source, tag: '[FOCUS]',
+            text: recap.focus, agentId, sessionId,
+            metadata: { proposed_by: source },
+            dedupeKey: `daily:${date}:focus:${source}`,
+        });
+        focusUpdated = true;
+        if (logger.info) logger.info(`[miranda] focus updated: ${recap.focus.slice(0, 60)}`);
+    }
+
+    // TODO
+    if (recap?.todo_new?.length > 0 || recap?.todo_done?.length > 0) {
+        const todayEntries = await getDailyEntries(pool, date, agentId);
+        let currentItems = [];
+        for (const row of todayEntries) {
+            if (row.tag === '[TODO]') {
+                currentItems = row.text.split('\n').map(s => s.replace(/^[-•]\s*/, '').trim()).filter(Boolean);
+            }
+        }
+        if (recap.todo_done?.length > 0) {
+            for (const done of recap.todo_done) {
+                const dl = done.toLowerCase();
+                currentItems = currentItems.filter(item => {
+                    const il = item.toLowerCase();
+                    return il !== dl && !il.includes(dl) && !dl.includes(il);
+                });
+            }
+        }
+        if (recap.todo_new?.length > 0) {
+            for (const n of recap.todo_new) {
+                if (!currentItems.some(i => i.toLowerCase() === n.toLowerCase())) currentItems.push(n);
+            }
+        }
+        await insertDailyEntry(pool, {
+            eventAt: now.toISOString(), source, tag: '[TODO]',
+            text: currentItems.map(i => `- ${i}`).join('\n') || '（全部完成）',
+            agentId, sessionId,
+            metadata: { proposed_by: source, todo_new: recap.todo_new, todo_done: recap.todo_done },
+            dedupeKey: `daily:${date}:todo:${source}`,
+        });
+        todoUpdated = true;
+        if (logger.info) logger.info(`[miranda] todo updated: ${currentItems.length} items`);
+    }
+
+    // Handoff
+    if (sections?.handoff) {
+        const handoff = parseHandoffSection(sections.handoff);
+        if (handoff) {
+            let handoffText;
+            switch (handoff.status) {
+                case 'completed': handoffText = `上一段已完成 ${handoff.lastStep}`; break;
+                case 'blocked': handoffText = `上一段卡在 ${handoff.lastStep}`; break;
+                default: handoffText = `上一段停在 ${handoff.lastStep}`;
+            }
+            if (handoff.next && handoff.next !== '無') handoffText += `，下一步建議 ${handoff.next}`;
+            if (handoff.decided) handoffText += `，已決定 ${handoff.decided}`;
+            if (handoff.blocker && handoff.status !== 'blocked') handoffText += `，卡在 ${handoff.blocker}`;
+            handoffText += '。';
+
+            await insertDailyEntry(pool, {
+                eventAt: now.toISOString(), source, tag: '[HANDOFF]',
+                text: handoffText, agentId, sessionId,
+                metadata: { ...handoff, proposed_by: source },
+                dedupeKey: `daily:${date}:handoff:${source}`,
+            });
+            if (logger.info) logger.info(`[miranda] handoff written: ${handoffText.slice(0, 80)}`);
+        }
+    }
+
+    // Optional custom renderer (persona can plug in a markdown writer)
+    if (renderDailyLog) {
+        try { await renderDailyLog(date, agentId); }
+        catch (err) { if (logger.info) logger.info(`[miranda] renderDailyLog failed: ${err.message}`); }
+    }
+
+    return { inserted, focusUpdated, todoUpdated };
+}
+
+module.exports = {
+    taipeiDateString,
+    textHash6,
+    insertDailyEntry,
+    getDailyEntries,
+    fetchDailyContext,
+    writeDailyEntries,
+    TABLE,
+    UPSERT_TAGS,
+};

package/consumers/miranda/index.js

@@ -0,0 +1,353 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Miranda persona layer.
+//
+// This is a PERSONA, not a host adapter. It wraps a host (OpenClaw gateway,
+// Claude Code afterburn) with Miranda's six-section prompt, zh-TW daily log,
+// workspace file artifacts, and consolidation lifecycle — but leaves the
+// actual hook plumbing (before_reset, before_prompt_build, MCP tool registry)
+// to the host.
+//
+// Entry points:
+//   mountOnOpenClaw(api, opts)     — gateway plugin wiring
+//   mountOnClaudeCode(cc, opts)    — CC afterburn wiring (see consumers/claude-code.js)
+//   buildPostProcess(opts)         — low-level: returns the enrich postProcess
+//                                    fn; host calls it directly if neither
+//                                    mount helper fits.
+// ---------------------------------------------------------------------------
+
+const { runIngest } = require('../shared/ingest');
+const { parseEntitySection } = require('../shared/entity-parser');
+
+const instance = require('./instance');
+const { callLlm, resolveModel, loadConfig } = require('./llm');
+const summary = require('./prompts/summary');
+const dailyEntries = require('./daily-entries');
+const workspaceFiles = require('./workspace-files');
+const contextInject = require('./context-inject');
+const mirandaRecallFormat = require('./recall-format');
+
+// ---------------------------------------------------------------------------
+// summaryFn / entityParseFn factories — shared by gateway + CC
+// ---------------------------------------------------------------------------
+
+function buildSummaryFn({ agentId, now, dailyContext, runtime = 'gateway', logger = console }) {
+    return async function summaryFn(_normalized) {
+        // _normalized is the cleaned messages from Aquifer; Miranda wants the
+        // reconstructed conversation text for the six-section prompt.
+        const conversationText = extractConversationText(_normalized);
+        if (!conversationText) throw new Error('empty conversation text');
+
+        const prompt = summary.buildSummaryPrompt({ conversationText, agentId, now, dailyContext });
+        if (logger.info) logger.info(`[miranda] calling LLM (${runtime})`);
+        const output = await callLlm(prompt, { runtime });
+        if (!output) throw new Error('LLM returned empty');
+
+        const sections = summary.parseSummaryOutput(output);
+        const recap = summary.parseRecapLines(sections.recap || '');
+        const workingFacts = summary.parseWorkingFacts(sections.working_facts || '');
+        if (!recap.title) throw new Error('LLM recap missing title');
+
+        return {
+            summaryText: recap.overview || '',
+            structuredSummary: { ...recap, raw_sections: sections },
+            entityRaw: sections.entities || null,
+            extra: { sections, recap, workingFacts },
+        };
+    };
+}
+
+function buildEntityParseFn() {
+    return function entityParseFn(text) {
+        const parsed = parseEntitySection(text);
+        return parsed.entities;  // already has { name, normalizedName, aliases, type }
+    };
+}
+
+function extractConversationText(normalized) {
+    if (!Array.isArray(normalized)) return '';
+    return normalized
+        .filter(m => m.role === 'user' || m.role === 'assistant')
+        .map(m => `[${m.role}] ${typeof m.content === 'string' ? m.content : ''}`)
+        .join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// buildPostProcess — produce the enrich postProcess hook for Miranda
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {object} opts
+ * @param {object} opts.aquifer — Aquifer instance
+ * @param {object} opts.pool    — pg.Pool (used for daily-entries DAL)
+ * @param {string} opts.agentId
+ * @param {string} [opts.workspaceDir] — if set, writes emotional-state.md and recap JSON files
+ * @param {string} [opts.source='afterburn']
+ * @param {string|null} [opts.tag=null] — daily-entry tag (e.g. '[CLI]' for CC runs)
+ * @param {Date}  [opts.now]
+ * @param {object} [opts.logger]
+ * @param {boolean} [opts.consolidate=true]
+ */
+function buildPostProcess({
+    aquifer, pool, agentId, workspaceDir = null,
+    source = 'afterburn', tag = null, now = null,
+    logger = console, consolidate = true,
+} = {}) {
+    if (!aquifer) throw new Error('buildPostProcess: aquifer is required');
+    if (!pool) throw new Error('buildPostProcess: pool is required');
+    if (!agentId) throw new Error('buildPostProcess: agentId is required');
+
+    return async function postProcess(ctx) {
+        const _now = now || new Date();
+        const recap = ctx.extra?.recap || null;
+        const sections = ctx.extra?.sections || null;
+        const workingFacts = ctx.extra?.workingFacts || [];
+        const sessionId = ctx.session.sessionId;
+
+        // 1. Workspace files (optional — only if persona has a workspace dir)
+        if (workspaceDir && (sections || recap)) {
+            try {
+                await workspaceFiles.writeWorkspaceFiles(sections || {}, recap, workspaceDir, {
+                    sessionId,
+                    agentId,
+                    conversationText: extractConversationText(ctx.normalized || []),
+                }, logger);
+            } catch (err) {
+                if (logger.warn) logger.warn(`[miranda] workspace files failed: ${err.message}`);
+            }
+        }
+
+        // 2. Daily entries
+        if (sections || recap) {
+            try {
+                await dailyEntries.writeDailyEntries({
+                    sections: sections || {}, recap, pool, sessionId, agentId, logger,
+                    source, tag, now: _now,
+                });
+            } catch (err) {
+                if (logger.warn) logger.warn(`[miranda] daily entries failed: ${err.message}`);
+            }
+        }
+
+        // 3. Fact candidates — write to aquifer.${schema}.facts via consolidate 'create'
+        //    (We only CREATE here; candidate-lifecycle decisions come from the
+        //    consolidation step below.)
+        if (consolidate && workingFacts.length > 0) {
+            try {
+                const { normalizeEntityName } = require('../../index');
+                const actions = workingFacts.map(f => ({
+                    action: 'create',
+                    subject: f.subject,
+                    statement: f.statement,
+                    importance: 6,
+                }));
+                await aquifer.consolidate(sessionId, {
+                    agentId,
+                    actions,
+                    normalizeSubject: normalizeEntityName,
+                    recapOverview: recap?.overview || '',
+                });
+            } catch (err) {
+                if (logger.warn) logger.warn(`[miranda] fact candidates failed: ${err.message}`);
+            }
+        }
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Mount helpers — afterburn / context-inject / session_recall tool.
+// Each is independently mountable so different OpenClaw extensions can claim
+// the hooks they care about. mountOnOpenClaw() is the all-in-one convenience.
+// ---------------------------------------------------------------------------
+
+function resolveCommon(opts) {
+    if (!opts.pool) throw new Error('Miranda: pool is required');
+    if (!opts.embedFn) throw new Error('Miranda: embedFn is required');
+    return {
+        pool: opts.pool,
+        embedFn: opts.embedFn,
+        defaultAgentId: opts.agentId || 'main',
+        workspaceDir: opts.workspaceDir || null,
+        minUserMessages: opts.minUserMessages || 3,
+        aquifer: instance.getAquifer({
+            pool: opts.pool, embedFn: opts.embedFn, llmFn: opts.llmFn, rerankKey: opts.rerankKey,
+        }),
+    };
+}
+
+/**
+ * Register Miranda's afterburn hook (before_reset) on the OpenClaw api.
+ * Runs commit + enrich with Miranda's summaryFn and postProcess.
+ */
+function registerAfterburn(api, opts = {}) {
+    const { pool, aquifer, defaultAgentId, workspaceDir, minUserMessages } = resolveCommon(opts);
+    const recentlyProcessed = new Map();
+    const inFlight = new Set();
+
+    api.on('before_reset', (event, ctx) => {
+        const sessionId = ctx?.sessionId || event?.sessionId;
+        const agentId = ctx?.agentId || defaultAgentId;
+        const sessionKey = ctx?.sessionKey || null;
+
+        if (!sessionId) return;
+        if ((sessionKey || '').includes('subagent')) return;
+        if ((sessionKey || '').includes(':cron:')) return;
+
+        const rawEntries = Array.isArray(event?.messages) ? event.messages : [];
+        if (rawEntries.length < 3) {
+            api.logger.info(`[miranda] skip ${sessionId}: only ${rawEntries.length} msgs`);
+            return;
+        }
+
+        (async () => {
+            try {
+                const now = new Date();
+                const date = dailyEntries.taipeiDateString(now);
+                let dailyContext = '';
+                try { dailyContext = await dailyEntries.fetchDailyContext(pool, date, agentId); } catch { /* best-effort */ }
+
+                await runIngest({
+                    aquifer,
+                    sessionId,
+                    agentId,
+                    source: 'openclaw',
+                    sessionKey,
+                    adapter: 'gateway',
+                    rawEntries,
+                    minUserMessages,
+                    dedupMap: recentlyProcessed,
+                    inFlight,
+                    summaryFn: buildSummaryFn({ agentId, now, dailyContext, runtime: 'gateway', logger: api.logger }),
+                    entityParseFn: buildEntityParseFn(),
+                    postProcess: buildPostProcess({
+                        aquifer, pool, agentId, workspaceDir,
+                        source: 'afterburn', now, logger: api.logger,
+                    }),
+                    logger: api.logger,
+                });
+            } catch (err) {
+                api.logger.warn(`[miranda] capture failed ${sessionId}: ${err.message}`);
+            }
+        })();
+    });
+
+    api.logger.info('[miranda] registerAfterburn: before_reset hooked');
+    return { aquifer };
+}
+
+/**
+ * Register the before_prompt_build Miranda context injection.
+ * Separate from afterburn so the Driftwood ext can install it while the
+ * afterburn ext owns the before_reset hook.
+ */
+function registerContextInject(api, opts = {}) {
+    const { pool, aquifer, defaultAgentId } = resolveCommon(opts);
+
+    api.on('before_prompt_build', async (event, ctx) => {
+        try {
+            const agentId = ctx?.agentId || defaultAgentId;
+            if ((ctx?.sessionKey || '').includes('subagent')) return;
+
+            const context = await contextInject.computeInjection({
+                aquifer, pool, agentId, includeBootstrap: true,
+            });
+            if (context && context.split('\n').length > 3) {
+                api.logger.info(`[miranda] injecting context: ${context.length} chars, agent=${agentId}`);
+                return { prependSystemContext: context };
+            }
+        } catch (err) {
+            api.logger.warn(`[miranda] context injection failed: ${err.message}`);
+        }
+    });
+
+    api.logger.info('[miranda] registerContextInject: before_prompt_build hooked');
+    return { aquifer };
+}
+
+/**
+ * Register the zh-TW session_recall tool.
+ */
+function registerRecallTool(api, opts = {}) {
+    const { aquifer } = resolveCommon(opts);
+
+    api.registerTool((ctx) => {
+        if ((ctx?.sessionKey || '').includes('subagent')) return null;
+        return {
+            name: 'session_recall',
+            description: '搜尋歷史 session 的摘要和對話記錄。可按關鍵字、日期範圍、agent 搜尋。',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: '搜尋關鍵字（可空，空時按時間排序）' },
+                    date_from: { type: 'string' }, date_to: { type: 'string' },
+                    agent_id: { type: 'string' }, source: { type: 'string' },
+                    detail: { type: 'string' },
+                    limit: { type: 'number' },
+                },
+            },
+            async execute(_toolCallId, params) {
+                try {
+                    const limit = Math.max(1, Math.min(20, parseInt(params?.limit ?? 5, 10) || 5));
+                    const results = await aquifer.recall(String(params?.query || ''), {
+                        agentId: params?.agent_id || ctx?.agentId || undefined,
+                        source: params?.source || undefined,
+                        dateFrom: params?.date_from || undefined,
+                        dateTo: params?.date_to || undefined,
+                        limit,
+                    });
+                    const text = mirandaRecallFormat.formatRecallResults(results.map(r => ({
+                        sessionId: r.sessionId, agentId: r.agentId, source: r.source,
+                        startedAt: r.startedAt, summaryText: r.summaryText,
+                        structuredSummary: r.structuredSummary,
+                        matchedTurnText: r.matchedTurnText,
+                    })));
+                    return { content: [{ type: 'text', text }] };
+                } catch (err) {
+                    return { content: [{ type: 'text', text: `session_recall 錯誤：${err.message}` }], isError: true };
+                }
+            },
+        };
+    }, { name: 'session_recall' });
+
+    api.logger.info('[miranda] registerRecallTool: session_recall tool registered');
+    return { aquifer };
+}
+
+/**
+ * Convenience: register all three on the same api. Equivalent to calling
+ * registerAfterburn + registerContextInject + registerRecallTool.
+ */
+function mountOnOpenClaw(api, opts = {}) {
+    const r1 = registerAfterburn(api, opts);
+    registerContextInject(api, opts);
+    registerRecallTool(api, opts);
+    return r1;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+    // Persona entry points
+    mountOnOpenClaw,
+    registerAfterburn,
+    registerContextInject,
+    registerRecallTool,
+    buildPostProcess,
+    buildSummaryFn,
+    buildEntityParseFn,
+
+    // Individual modules for advanced wiring
+    instance,
+    llm: { callLlm, resolveModel, loadConfig },
+    summary,
+    dailyEntries,
+    workspaceFiles,
+    contextInject,
+    recallFormat: mirandaRecallFormat,
+
+    // Helpers re-exported for convenience
+    extractConversationText,
+};

package/consumers/miranda/instance.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// Miranda Aquifer instance factory — produces a singleton bound to the
+// miranda schema + entity scope + rerank config. Host supplies the pg.Pool
+// and embed function (they're host-specific wiring: OpenClaw has its own
+// pg + embed libs; CC uses the same).
+
+const { createAquifer } = require('../../index');
+const { callLlm } = require('./llm');
+
+let _instance = null;
+
+/**
+ * @param {object} opts
+ * @param {object} opts.pool — pg.Pool from the host
+ * @param {function} opts.embedFn — async (texts: string[]) => number[][]
+ * @param {function} [opts.llmFn] — defaults to Miranda's MiniMax wrapper
+ * @param {string} [opts.rerankKey] — OpenRouter API key; falls back to
+ *   process.env.OPENROUTER_API_KEY / AQUIFER_RERANK_API_KEY
+ * @returns {object} Aquifer instance
+ */
+function getAquifer(opts = {}) {
+    if (_instance) return _instance;
+    if (!opts.pool) throw new Error('Miranda: pool is required');
+    if (!opts.embedFn) throw new Error('Miranda: embedFn is required');
+
+    const rerankKey = opts.rerankKey
+        || process.env.OPENROUTER_API_KEY
+        || process.env.AQUIFER_RERANK_API_KEY;
+
+    _instance = createAquifer({
+        schema: 'miranda',
+        db: opts.pool,
+        tenantId: 'default',
+        embed: { fn: opts.embedFn },
+        llm: { fn: opts.llmFn || callLlm },
+        entities: { enabled: true, mergeCall: true, scope: 'miranda' },
+        facts: { enabled: true },
+        rerank: rerankKey ? {
+            provider: 'openrouter',
+            openrouterApiKey: rerankKey,
+            model: 'cohere/rerank-v3.5',
+            topK: 20,
+            maxChars: 1600,
+            timeout: 5000,
+            maxRetries: 1,
+        } : null,
+    });
+
+    return _instance;
+}
+
+function resetAquifer() { _instance = null; }
+
+module.exports = { getAquifer, resetAquifer };