@shadowforge0/aquifer-memory 1.0.3 → 1.2.1

package/consumers/default/index.js

@@ -0,0 +1,282 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Aquifer default persona — parameterized, host-agnostic.
+//
+// Entry point:
+//   const persona = require('@shadowforge0/aquifer-memory/consumers/default')
+//     .createPersona({
+//       agentName: 'Dobby',
+//       observedOwner: 'evan',
+//       schema: 'jenny',
+//       scope: 'jenny',
+//       dailyTable: 'jenny.daily_entries',  // or null to skip daily writes
+//       language: 'zh-TW',                   // or 'en'
+//       briefingIntro: '你是 Dobby。以下是現況...',  // optional context-inject preamble
+//     });
+//
+// Returns a persona module with the same shape as consumers/miranda — host
+// can do `AQUIFER_PERSONA=<host-path>` where <host-path>/index.js does:
+//   module.exports = require('@shadowforge0/aquifer-memory/consumers/default')
+//     .createPersona({ ... });
+//
+// This is intentionally a minimal persona: summary + optional daily_entries,
+// no workspace-files, no consolidation, no Miranda-specific scaffolding.
+// Host can extend by composing with Aquifer primitives from consumers/shared.
+// ---------------------------------------------------------------------------
+
+const { createAquifer } = require('../../index');
+const { runIngest } = require('../shared/ingest');
+const { parseEntitySection } = require('../shared/entity-parser');
+
+const summaryModule = require('./prompts/summary');
+const dailyEntriesModule = require('./daily-entries');
+
+function createPersona(personaOpts = {}) {
+  const persona = {
+    agentName: personaOpts.agentName || 'Assistant',
+    observedOwner: personaOpts.observedOwner || null,
+    schema: personaOpts.schema || 'aquifer',
+    scope: personaOpts.scope || 'default',
+    dailyTable: personaOpts.dailyTable || null,
+    language: personaOpts.language || 'en',
+    briefingIntro: personaOpts.briefingIntro || null,
+    skipEntities: personaOpts.skipEntities === true,
+  };
+
+  // ------- primitives -------
+
+  let _instance = null;
+  function getAquifer({ pool, embedFn, llmFn, rerankKey } = {}) {
+    if (_instance) return _instance;
+    // v1.2.0: all four are optional. If omitted, Aquifer core falls back to
+    // DATABASE_URL + EMBED_PROVIDER + AQUIFER_LLM_PROVIDER env.
+    const cfg = {
+      schema: persona.schema,
+      tenantId: 'default',
+      entities: { enabled: !persona.skipEntities, scope: persona.scope },
+    };
+    if (pool !== undefined) cfg.db = pool;
+    if (embedFn) cfg.embed = { fn: embedFn };
+    if (llmFn) cfg.llm = { fn: llmFn };
+    if (rerankKey) cfg.rerank = { provider: 'openrouter', openrouterApiKey: rerankKey, topK: 20, maxChars: 1600 };
+    _instance = createAquifer(cfg);
+    return _instance;
+  }
+  function resetAquifer() { _instance = null; }
+
+  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');
+  }
+
+  function buildSummaryFn({ agentId, now, dailyContext, llmFn, logger = console }) {
+    if (typeof llmFn !== 'function') {
+      throw new Error('default persona buildSummaryFn: llmFn is required');
+    }
+    return async function summaryFn(normalized) {
+      const conversationText = extractConversationText(normalized);
+      if (!conversationText) throw new Error('empty conversation text');
+      const prompt = summaryModule.buildSummaryPrompt({ conversationText, agentId, now, dailyContext, persona });
+      if (logger.info) logger.info(`[default-persona] calling LLM for ${agentId}`);
+      const output = await llmFn(prompt);
+      if (!output) throw new Error('LLM returned empty');
+      const sections = summaryModule.parseSummaryOutput(output);
+      const recap = summaryModule.parseRecapLines(sections.recap || '');
+      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 },
+      };
+    };
+  }
+
+  function buildEntityParseFn() {
+    return (text) => {
+      const parsed = parseEntitySection(text);
+      return parsed.entities;
+    };
+  }
+
+  function buildPostProcess({ pool, agentId, now = null, source = 'afterburn', tag = null, logger = console } = {}) {
+    return async function postProcess(ctx) {
+      const _now = now || new Date();
+      const recap = ctx.extra?.recap || null;
+      const sections = ctx.extra?.sections || null;
+      const sessionId = ctx.session.sessionId;
+
+      if (persona.dailyTable && (sections || recap)) {
+        try {
+          await dailyEntriesModule.writeDailyEntries({
+            sections: sections || {}, recap, pool, sessionId, agentId, logger,
+            source, tag, now: _now, dailyTable: persona.dailyTable,
+          });
+        } catch (err) {
+          if (logger.warn) logger.warn(`[default-persona] daily entries failed: ${err.message}`);
+        }
+      }
+    };
+  }
+
+  // ------- OpenClaw mount -------
+
+  function resolveCommon(opts) {
+    // v1.2.0: all four are env-driven by default. Host may override any of
+    // them via opts. Aquifer core throws with clear guidance if the required
+    // env vars are missing, so we do not pre-validate here.
+    const aquifer = getAquifer(opts);
+    const pool = opts.pool || aquifer.getPool();
+    const llmFn = opts.llmFn || aquifer.getLlmFn();
+    const embedFn = opts.embedFn || aquifer.getEmbedFn();
+    return {
+      pool,
+      embedFn,
+      llmFn,
+      defaultAgentId: opts.agentId || 'main',
+      minUserMessages: opts.minUserMessages || 3,
+      aquifer,
+    };
+  }
+
+  function registerAfterburn(api, opts = {}) {
+    const { pool, llmFn, aquifer, defaultAgentId, 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(`[default-persona] skip ${sessionId}: only ${rawEntries.length} msgs`);
+        return;
+      }
+
+      (async () => {
+        try {
+          const now = new Date();
+          const date = dailyEntriesModule.taipeiDateString(now);
+          let dailyContext = '';
+          try { dailyContext = await dailyEntriesModule.fetchDailyContext(pool, date, agentId, persona.dailyTable); } catch {/* best effort */}
+          await runIngest({
+            aquifer,
+            sessionId,
+            agentId,
+            source: 'openclaw',
+            sessionKey,
+            adapter: 'gateway',
+            rawEntries,
+            minUserMessages,
+            dedupMap: recentlyProcessed,
+            inFlight,
+            summaryFn: buildSummaryFn({ agentId, now, dailyContext, llmFn, logger: api.logger }),
+            entityParseFn: persona.skipEntities ? null : buildEntityParseFn(),
+            postProcess: buildPostProcess({ pool, agentId, now, logger: api.logger }),
+            logger: api.logger,
+          });
+        } catch (err) {
+          api.logger.warn(`[default-persona] capture failed ${sessionId}: ${err.message}`);
+        }
+      })();
+    });
+
+    api.logger.info('[default-persona] registerAfterburn: before_reset hooked');
+    return { aquifer };
+  }
+
+  function registerContextInject(api, opts = {}) {
+    const { aquifer, defaultAgentId } = resolveCommon(opts);
+    if (!persona.briefingIntro) {
+      api.logger.info('[default-persona] context inject skipped (no briefingIntro configured)');
+      return { aquifer };
+    }
+    api.on('before_prompt_build', async (_event, ctx) => {
+      try {
+        const agentId = ctx?.agentId || defaultAgentId;
+        if ((ctx?.sessionKey || '').includes('subagent')) return;
+        const recalled = await aquifer.bootstrap({ agentId, limit: 5, maxChars: 2000, format: 'text' });
+        const context = persona.briefingIntro + (recalled ? `\n\n${recalled}` : '');
+        if (context.length > 0) return { prependSystemContext: context };
+      } catch (err) {
+        api.logger.warn(`[default-persona] context injection failed: ${err.message}`);
+      }
+    });
+    api.logger.info('[default-persona] registerContextInject: before_prompt_build hooked');
+    return { aquifer };
+  }
+
+  function registerRecallTool(api, opts = {}) {
+    const { aquifer } = resolveCommon(opts);
+    api.registerTool((ctx) => {
+      if ((ctx?.sessionKey || '').includes('subagent')) return null;
+      return {
+        name: 'session_recall',
+        description: 'Search stored sessions by keyword.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string' },
+            limit: { type: 'number' },
+            agent_id: { type: 'string' },
+            date_from: { type: 'string' },
+            date_to: { type: 'string' },
+          },
+        },
+        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,
+              dateFrom: params?.date_from || undefined,
+              dateTo: params?.date_to || undefined,
+              limit,
+            });
+            const lines = results.map((r, i) =>
+              `${i+1}. ${r.structuredSummary?.title || r.summaryText?.slice(0, 80) || '(untitled)'}`
+            );
+            return { content: [{ type: 'text', text: lines.join('\n') || 'No matching sessions.' }] };
+          } catch (err) {
+            return { content: [{ type: 'text', text: `session_recall error: ${err.message}` }], isError: true };
+          }
+        },
+      };
+    }, { name: 'session_recall' });
+    api.logger.info('[default-persona] registerRecallTool: session_recall registered');
+    return { aquifer };
+  }
+
+  function mountOnOpenClaw(api, opts = {}) {
+    const r = registerAfterburn(api, opts);
+    registerContextInject(api, opts);
+    registerRecallTool(api, opts);
+    return r;
+  }
+
+  return {
+    persona,
+    mountOnOpenClaw,
+    registerAfterburn,
+    registerContextInject,
+    registerRecallTool,
+    buildPostProcess,
+    buildSummaryFn,
+    buildEntityParseFn,
+    extractConversationText,
+    instance: { getAquifer, resetAquifer },
+    summary: summaryModule,
+    dailyEntries: dailyEntriesModule,
+  };
+}
+
+module.exports = { createPersona };

package/consumers/default/prompts/summary.js

@@ -0,0 +1,153 @@
+'use strict';
+
+// Aquifer default persona — minimal summary prompt.
+//
+// Parameterized via personaOpts:
+//   agentName       — human name/role the prompt addresses (default 'Assistant')
+//   observedOwner   — if set, the prompt asks for a short observation about
+//                     that person (matches Miranda's "對 MK 的觀察" slot).
+//                     null → the section is omitted entirely.
+//   language        — 'en' | 'zh-TW' (default 'en')
+//
+// Output format mirrors Miranda's RECAP fields so downstream daily-entries
+// parsing works uniformly across personas.
+
+function buildSummaryPrompt({ conversationText, agentId, now, dailyContext, persona = {} }) {
+  const { agentName = 'Assistant', observedOwner = null, language = 'en' } = persona;
+  if (!now) now = new Date();
+  const iso = now.toISOString();
+  const date = iso.slice(0, 10);
+  const time = iso.slice(11, 16);
+
+  if (language === 'zh-TW') return buildZhTw({ conversationText, agentId, agentName, observedOwner, date, time, dailyContext });
+  return buildEn({ conversationText, agentId, agentName, observedOwner, date, time, dailyContext });
+}
+
+function buildEn({ conversationText, agentId, agentName, observedOwner, date, time, dailyContext }) {
+  const ownerList = [observedOwner, 'agent', 'unknown'].filter(Boolean).join(', ');
+  const observationSection = observedOwner ? `
+## Observation of ${observedOwner}
+
+(1-2 sentences about ${observedOwner}'s state/energy/mood as perceived in this session)
+` : '';
+
+  return `You are processing a completed chat session for agent "${agentId}" (${agentName}).
+Current time: ${date} ${time}
+
+${dailyContext ? `## Today's daily log so far:\n\n${dailyContext}\n\n---\n\n` : ''}## Conversation transcript:
+
+${conversationText}
+
+---
+
+Generate THREE sections separated by the exact markers shown below. Output content ONLY after each marker.
+
+===SESSION_ENTRIES===
+Bullet points for today's log. Each line: "- (HH:MM) key point".
+Summarize at OUTCOME level — one bullet per topic, merged across steps.
+Skip greetings and trivial exchanges.
+If a topic already exists in "Today's daily log so far", skip it.
+
+===EMOTIONAL_STATE===
+---
+updated: ${date}T${time}
+session_mood: (one word)
+---
+
+## Session state
+
+(2-3 sentences about the agent's state after this session)
+${observationSection}
+===RECAP===
+Output each field on its own tagged line.
+
+TITLE: one-line headline
+OVERVIEW: 80-200 char dense summary
+TOPIC: topic name | 1-3 sentence summary
+DECISION: what was decided | reason
+ACTION: completed thing | done
+ACTION: partially done thing | partial
+OPEN: unresolved item | ${ownerList.split(',')[0].trim()}
+FACT: important fact
+TODO_NEW: newly created action item
+TODO_DONE: previously listed TODO that was completed
+
+Rules:
+- One tag per line. Multiple items = multiple lines with same tag.
+- TITLE and OVERVIEW are required.
+- OPEN owner enum: ${ownerList}
+- ACTION status: done or partial
+- Skip any section not applicable.
+- Do NOT output JSON.
+`;
+}
+
+function buildZhTw({ conversationText, agentId, agentName, observedOwner, date, time, dailyContext }) {
+  const ownerList = [observedOwner, 'agent', 'unknown'].filter(Boolean).join(', ');
+  const observationSection = observedOwner ? `
+## 對 ${observedOwner} 的觀察
+
+(1-2 句關於 ${observedOwner} 在此 session 中觀察到的狀態 / 精神 / 情緒)
+` : '';
+
+  return `你正在處理 agent "${agentId}" (${agentName}) 的一段對話。
+目前時間: ${date} ${time}
+
+${dailyContext ? `## 今日日誌:\n\n${dailyContext}\n\n---\n\n` : ''}## 對話內容:
+
+${conversationText}
+
+---
+
+輸出下列三段，以下列 marker 嚴格分隔。每段只輸出 marker 後的內容。使用繁體中文。
+
+===SESSION_ENTRIES===
+每行: "- (HH:MM) key point"。以結果層級合併步驟，不逐步記錄。
+略過寒暄與瑣碎交換。
+若某主題已在「今日日誌」中出現，略過。
+
+===EMOTIONAL_STATE===
+---
+updated: ${date}T${time}
+session_mood: (one word)
+---
+
+## 情緒狀態
+
+(2-3 句關於 agent 在此 session 後的狀態)
+${observationSection}
+===RECAP===
+
+TITLE: 一句話標題
+OVERVIEW: 80-200 字密集摘要
+TOPIC: 主題名 | 1-3 句 summary
+DECISION: 做了什麼決定 | 原因
+ACTION: 已完成 | done
+ACTION: 部分完成 | partial
+OPEN: 未完成事項 | ${ownerList.split(',')[0].trim()}
+FACT: 重要事實
+TODO_NEW: 新增待辦
+TODO_DONE: 已完成待辦（需匹配既有）
+
+規則:
+- 一行一個 tag。多項就多行相同 tag。
+- TITLE 跟 OVERVIEW 必填。
+- OPEN owner: ${ownerList}
+- ACTION 狀態: done 或 partial
+- 不輸出 JSON。
+`;
+}
+
+// ---------------------------------------------------------------------------
+// parseSummaryOutput / parseRecapLines — delegate to miranda's parsers.
+// The output format is intentionally the same, so parsers work for both.
+// ---------------------------------------------------------------------------
+
+const mirandaSummary = require('../../miranda/prompts/summary');
+
+module.exports = {
+  buildSummaryPrompt,
+  parseSummaryOutput: mirandaSummary.parseSummaryOutput,
+  parseRecapLines: mirandaSummary.parseRecapLines,
+  parseWorkingFacts: mirandaSummary.parseWorkingFacts,
+};

package/consumers/mcp.js

@@ -30,30 +30,10 @@ function getAquifer() {
 // 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)';
-    let date = 'unknown';
-    if (r.startedAt) {
-      const parsed = new Date(r.startedAt);
-      if (!isNaN(parsed.getTime())) date = parsed.toISOString().slice(0, 10);
-    }
+const { formatRecallResults } = require('./shared/recall-format');
 
-    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');
+function formatResults(results, query) {
+  return formatRecallResults(results, { query, showScore: true });
 }
 
 // ---------------------------------------------------------------------------

package/consumers/miranda/context-inject.js

@@ -0,0 +1,119 @@
+'use strict';
+
+const { getDailyEntries } = require('./daily-entries');
+
+// ---------------------------------------------------------------------------
+// buildSessionContext — pure function, testable.
+// Emits the Miranda persona briefing that gets prepended to the system
+// prompt. Style: 散文段落, 結論收尾, 不給 bullet/table/headers.
+// ---------------------------------------------------------------------------
+
+const TODO_CAP = 5;
+
+function buildSessionContext({ today, agentId, focusText, todoItems, moodLine, handoffText, cliEntries }) {
+    const parts = [];
+    parts.push('你是 Miranda。以下是你已經知道的現況，直接用來回應，不需要讀檔或搜尋。像做 briefing——帶現況也帶判斷和建議。用散文段落，最後一句必須是結論或建議，不能是問句。若草稿有 bullet、標題、表格或問句收尾，改寫再送出。');
+    parts.push('回答任何關於過去做過什麼、討論過什麼、決策過什麼的問題時，第一步用 session_recall MCP tool 查，不要用 grep、讀 log、翻檔案。工具在手上就用。');
+
+    if (focusText) parts.push(`現在的焦點是${focusText}。`);
+    if (handoffText) parts.push(`上一段的交接：${handoffText}`);
+
+    const items = (todoItems || []).slice(0, TODO_CAP);
+    if (items.length > 0) parts.push(`手上還有${items.join('、')}。`);
+
+    if (moodLine) parts.push(`整體狀態${moodLine}。`);
+
+    const cli = (cliEntries || []).slice(-15);
+    if (cli.length > 0) parts.push(`今天已經做過的事（不要重複）：${cli.join('；')}`);
+
+    if (parts.length <= 2) return '';
+    return `<session-context date="${today}" agent="${agentId}">\n${parts.join('\n')}\n</session-context>`;
+}
+
+// ---------------------------------------------------------------------------
+// extractFocusTodoMood — pull state rows (focus/todo/mood/handoff) + cli log
+// ---------------------------------------------------------------------------
+
+function extractFocusTodoMood(todayEntries, yesterdayEntries) {
+    const allEntries = [...(todayEntries || []), ...(yesterdayEntries || [])]
+        .sort((a, b) => new Date(b.event_at) - new Date(a.event_at));
+
+    const preferCli = (tag) => {
+        const cli = allEntries.find(e => e.tag === tag && e.source === 'cli');
+        return cli || allEntries.find(e => e.tag === tag);
+    };
+    const focusEntry = preferCli('[FOCUS]');
+    const todoEntry = preferCli('[TODO]');
+    const moodEntry = allEntries.find(e => e.tag === '[MOOD]');
+    const handoffEntry = preferCli('[HANDOFF]');
+
+    const focusText = focusEntry
+        ? focusEntry.text.split('\n').map(l => l.trim().replace(/^-\s*/, '')).filter(Boolean).join(', ')
+        : '';
+
+    const todoItems = todoEntry
+        ? todoEntry.text.split('\n').map(l => l.trim().replace(/^-\s*/, '')).filter(Boolean)
+        : [];
+
+    const moodLine = moodEntry ? moodEntry.text.trim() : '';
+
+    let handoffText = '';
+    if (handoffEntry) {
+        const meta = handoffEntry.metadata || {};
+        const isTrivial = (meta.status === 'completed' && meta.next === '無')
+            || handoffEntry.text.trim().startsWith('上一段已完成 簡短交談');
+        if (!isTrivial) {
+            handoffText = handoffEntry.text.trim();
+        }
+    }
+
+    const stateTags = new Set(['[FOCUS]', '[TODO]', '[MOOD]', '[HANDOFF]', '[HIGHLIGHT]', '[NARRATIVE]']);
+    const logEntries = (todayEntries || [])
+        .filter(e => !stateTags.has(e.tag))
+        .sort((a, b) => new Date(a.event_at) - new Date(b.event_at))
+        .map(e => e.text.trim())
+        .filter(Boolean);
+
+    return { focusText, todoItems, moodLine, handoffText, cliEntries: logEntries };
+}
+
+// ---------------------------------------------------------------------------
+// computeInjection — gateway/CC shared: queries daily_entries + aquifer.bootstrap
+// and returns a ready-to-prepend context string. No host-specific wiring.
+// ---------------------------------------------------------------------------
+
+function dateTaipei(d) {
+    return new Intl.DateTimeFormat('sv-SE', {
+        timeZone: 'Asia/Taipei', year: 'numeric', month: '2-digit', day: '2-digit',
+    }).format(d);
+}
+
+async function computeInjection({ aquifer, pool, agentId, now, includeBootstrap = true }) {
+    if (!now) now = new Date();
+    const today = dateTaipei(now);
+    const yesterday = dateTaipei(new Date(now.getTime() - 86400000));
+
+    const [todayEntries, yesterdayEntries] = await Promise.all([
+        getDailyEntries(pool, today, agentId),
+        getDailyEntries(pool, yesterday, agentId),
+    ]);
+
+    const state = extractFocusTodoMood(todayEntries, yesterdayEntries);
+    const context = buildSessionContext({ today, agentId, ...state });
+
+    let bootstrapText = '';
+    if (includeBootstrap && aquifer) {
+        try {
+            const bs = await aquifer.bootstrap({ agentId, limit: 5, maxChars: 2000, format: 'text' });
+            if (bs.text && bs.sessions && bs.sessions.length > 0) bootstrapText = '\n' + bs.text;
+        } catch { /* best-effort */ }
+    }
+
+    return context + bootstrapText;
+}
+
+module.exports = {
+    buildSessionContext,
+    extractFocusTodoMood,
+    computeInjection,
+};