@shadowforge0/aquifer-memory 1.5.12 → 1.7.0

package/consumers/default/daily-entries.js

@@ -9,7 +9,7 @@
 //   CREATE TABLE jenny.daily_entries (LIKE miranda.daily_entries INCLUDING ALL);
 
 const crypto = require('crypto');
-const { parseHandoffSection } = require('../miranda/prompts/summary');
+const { parseHandoffSection } = require('../shared/summary-parser');
 
 const UPSERT_TAGS = new Set(['[FOCUS]', '[TODO]', '[STATS]', '[HIGHLIGHT]', '[SYSTEM]', '[HANDOFF]']);
 
@@ -27,10 +27,27 @@ function textHash6(text) {
   return crypto.createHash('sha256').update(normalized).digest('hex').slice(0, 6);
 }
 
+function quoteIdentifier(identifier) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(identifier)) {
+    throw new Error(`Invalid dailyTable identifier: ${identifier}`);
+  }
+  return `"${identifier}"`;
+}
+
+function quoteTableName(tableName) {
+  if (typeof tableName !== 'string') throw new Error('dailyTable must be a string');
+  const parts = tableName.split('.');
+  if (parts.length < 1 || parts.length > 2 || parts.some(part => !part)) {
+    throw new Error(`Invalid dailyTable name: ${tableName}`);
+  }
+  return parts.map(quoteIdentifier).join('.');
+}
+
 async function insertDailyEntry(pool, tableName, { eventAt, source, tag, text, agentId, sessionId, metadata, dedupeKey }) {
+  const tableSql = quoteTableName(tableName);
   const shouldUpsert = dedupeKey && UPSERT_TAGS.has(tag);
   const sql = shouldUpsert
-    ? `INSERT INTO ${tableName}
+    ? `INSERT INTO ${tableSql}
          (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
@@ -38,7 +55,7 @@ async function insertDailyEntry(pool, tableName, { eventAt, source, tag, text, a
          event_at = EXCLUDED.event_at,
          metadata = EXCLUDED.metadata
        RETURNING id, event_at, source, tag, text`
-    : `INSERT INTO ${tableName}
+    : `INSERT INTO ${tableSql}
          (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
@@ -53,8 +70,9 @@ async function insertDailyEntry(pool, tableName, { eventAt, source, tag, text, a
 }
 
 async function getDailyEntries(pool, tableName, date, agentId) {
+  const tableSql = quoteTableName(tableName);
   const result = await pool.query(
-    `SELECT * FROM ${tableName}
+    `SELECT * FROM ${tableSql}
       WHERE (event_at AT TIME ZONE 'Asia/Taipei')::date = $1
         AND ($2::text IS NULL OR agent_id = $2)
       ORDER BY event_at ASC`,
@@ -191,6 +209,7 @@ async function writeDailyEntries({
 
 module.exports = {
   taipeiDateString, textHash6,
+  quoteIdentifier, quoteTableName,
   insertDailyEntry, getDailyEntries, fetchDailyContext, writeDailyEntries,
   UPSERT_TAGS,
 };

package/consumers/default/index.js

@@ -15,7 +15,7 @@
 //       briefingIntro: '你是 Dobby。以下是現況...',  // optional context-inject preamble
 //     });
 //
-// Returns a persona module with the same shape as consumers/miranda — host
+// Returns a persona module with the standard persona adapter shape — host
 // can do `AQUIFER_PERSONA=<host-path>` where <host-path>/index.js does:
 //   module.exports = require('@shadowforge0/aquifer-memory/consumers/default')
 //     .createPersona({ ... });
@@ -222,7 +222,7 @@ function createPersona(personaOpts = {}) {
       if ((ctx?.sessionKey || '').includes('subagent')) return null;
       return {
         name: 'session_recall',
-        description: 'Search stored sessions by keyword or natural language. Use entities when the user names specific people, projects, files, tools, or concepts; use entity_mode="all" when every named entity must co-occur (default "any" boosts). Use mode to force fts/vector/hybrid (default hybrid).',
+        description: 'Search Aquifer memory by keyword or natural language. In curated serving mode this searches active curated memory; legacy/evidence lookup is exposed by the MCP stdio evidence_recall tool. Use entities when the user names specific people, projects, files, tools, or concepts; use entity_mode="all" when every named entity must co-occur (default "any" boosts). Use mode to force fts/vector/hybrid (default hybrid).',
         parameters: {
           type: 'object',
           properties: {

package/consumers/default/prompts/summary.js

@@ -139,15 +139,15 @@ TODO_DONE: 已完成待辦（需匹配既有）
 }
 
 // ---------------------------------------------------------------------------
-// parseSummaryOutput / parseRecapLines — delegate to miranda's parsers.
-// The output format is intentionally the same, so parsers work for both.
+// parseSummaryOutput / parseRecapLines — shared parser used by all personas.
+// The output format is intentionally stable so downstream daily entries work.
 // ---------------------------------------------------------------------------
 
-const mirandaSummary = require('../../miranda/prompts/summary');
+const summaryParser = require('../../shared/summary-parser');
 
 module.exports = {
   buildSummaryPrompt,
-  parseSummaryOutput: mirandaSummary.parseSummaryOutput,
-  parseRecapLines: mirandaSummary.parseRecapLines,
-  parseWorkingFacts: mirandaSummary.parseWorkingFacts,
+  parseSummaryOutput: summaryParser.parseSummaryOutput,
+  parseRecapLines: summaryParser.parseRecapLines,
+  parseWorkingFacts: summaryParser.parseWorkingFacts,
 };

package/consumers/mcp.js

@@ -7,8 +7,8 @@
  * This is the primary integration surface for Aquifer. Agent hosts (Claude Code,
  * Codex, OpenCode, etc.) should integrate through this MCP server.
  *
- * Tools: session_recall, session_feedback, feedback_stats,
- * session_bootstrap, memory_stats, memory_pending
+ * Tools: session_recall, evidence_recall, session_feedback, memory_feedback,
+ * feedback_stats, session_bootstrap, memory_stats, memory_pending
  *
  * Usage:
  *   npx aquifer mcp
@@ -19,6 +19,7 @@
  */
 
 const { createAquiferFromConfig } = require('./shared/factory');
+const { version: packageVersion } = require('../package.json');
 
 let _aquifer = null;
 
@@ -59,12 +60,12 @@ async function main() {
 
   const server = new McpServer({
     name: 'aquifer-memory',
-    version: '0.9.0',
+    version: packageVersion,
   });
 
   server.tool(
     'session_recall',
-    'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
+    'Search Aquifer memory. In curated serving mode this searches active curated memory only; use evidence_recall for legacy session/evidence lookup.',
     {
       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)'),
@@ -76,6 +77,8 @@ async function main() {
       entityMode: z.enum(['any', 'all']).optional().describe('"any" (default, boost) or "all" (only sessions with every entity)'),
       mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)'),
       explain: z.boolean().optional().describe('Include per-result score breakdown (diagnostic)'),
+      activeScopeKey: z.string().optional().describe('Active curated memory scope key'),
+      activeScopePath: z.array(z.string()).optional().describe('Ordered curated scope path'),
     },
     async (params) => {
       try {
@@ -87,6 +90,8 @@ async function main() {
           source: params.source || undefined,
           dateFrom: params.dateFrom || undefined,
           dateTo: params.dateTo || undefined,
+          activeScopeKey: params.activeScopeKey || undefined,
+          activeScopePath: params.activeScopePath || undefined,
         };
         if (params.entities && params.entities.length > 0) {
           recallOpts.entities = params.entities;
@@ -106,9 +111,55 @@ async function main() {
     }
   );
 
+  server.tool(
+    'evidence_recall',
+    'Explicit legacy/evidence search over stored sessions and summaries. Use for audit/debug/distillation; it does not feed bootstrap implicitly.',
+    {
+      query: z.string().min(1).describe('Evidence 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'),
+      entities: z.array(z.string()).optional().describe('Entity names to match'),
+      entityMode: z.enum(['any', 'all']).optional().describe('"any" (default, boost) or "all" (only sessions with every entity)'),
+      mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Legacy evidence recall mode'),
+      explain: z.boolean().optional().describe('Include per-result score breakdown (diagnostic)'),
+      allowUnsafeDebug: z.boolean().optional().describe('Allow broad evidence/debug search without an audit boundary'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const limit = params.limit || 5;
+        const recallOpts = {
+          limit,
+          agentId: params.agentId || undefined,
+          source: params.source || undefined,
+          dateFrom: params.dateFrom || undefined,
+          dateTo: params.dateTo || undefined,
+        };
+        if (params.entities && params.entities.length > 0) {
+          recallOpts.entities = params.entities;
+          recallOpts.entityMode = params.entityMode || 'any';
+        }
+        if (params.mode) recallOpts.mode = params.mode;
+        if (params.allowUnsafeDebug) recallOpts.allowUnsafeDebug = true;
+
+        const results = await aquifer.evidenceRecall(params.query, recallOpts);
+        const text = formatResults(results, params.query, params.explain);
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `evidence_recall error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     'session_feedback',
-    'After using session_recall, mark the result helpful if it directly informed your answer, or unhelpful if it was irrelevant/outdated. Include a short note. Sessions with more helpful feedback rank higher in future recalls.',
+    'After using legacy session_recall or bootstrap, mark the recalled session helpful or unhelpful. This only targets legacy session trust, not curated memory rows.',
     {
       sessionId: z.string().min(1).describe('Session ID to give feedback on'),
       verdict: z.enum(['helpful', 'unhelpful']).describe('Was the recalled session useful?'),
@@ -135,6 +186,42 @@ async function main() {
     }
   );
 
+  server.tool(
+    'memory_feedback',
+    'Record append-only feedback on a curated memory row. This affects curated ranking/review priority only and does not mutate memory truth.',
+    {
+      memoryId: z.string().min(1).optional().describe('Curated memory record ID to give feedback on'),
+      canonicalKey: z.string().min(1).optional().describe('Canonical key of the active curated memory record'),
+      feedbackType: z.enum(['helpful', 'confirm', 'irrelevant', 'scope_mismatch', 'stale', 'incorrect']).describe('Curated memory feedback event type'),
+      note: z.string().optional().describe('Optional reason'),
+      agentId: z.string().optional().describe('Optional actor/agent label for audit metadata'),
+    },
+    async (params) => {
+      try {
+        if (!params.memoryId && !params.canonicalKey) {
+          throw new Error('memory_feedback requires memoryId or canonicalKey');
+        }
+        const aquifer = getAquifer();
+        const result = await aquifer.memoryFeedback({
+          memoryId: params.memoryId || undefined,
+          canonicalKey: params.canonicalKey || undefined,
+        }, {
+          feedbackType: params.feedbackType,
+          note: params.note || undefined,
+          agentId: params.agentId || undefined,
+        });
+        return {
+          content: [{ type: 'text', text: `Memory feedback: ${result.feedbackType}` }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `memory_feedback error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     'feedback_stats',
     'Return trust feedback statistics: total feedback count, helpful/unhelpful breakdown, trust score distribution, and coverage.',
@@ -229,6 +316,8 @@ async function main() {
       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)'),
+      activeScopeKey: z.string().optional().describe('Active curated memory scope key'),
+      activeScopePath: z.array(z.string()).optional().describe('Ordered curated scope path'),
     },
     async (params) => {
       try {
@@ -238,6 +327,8 @@ async function main() {
           limit: params.limit,
           lookbackDays: params.lookbackDays,
           maxChars: params.maxChars,
+          activeScopeKey: params.activeScopeKey || undefined,
+          activeScopePath: params.activeScopePath || undefined,
           format: 'text',
         });
         return { content: [{ type: 'text', text: result.text }] };

package/consumers/openclaw-ext/index.js

@@ -4,7 +4,6 @@
 //
 // Host layout:
 //   $OPENCLAW_HOME/extensions/aquifer-memory/  ← symlink to this directory
-//   (or run `bash scripts/install-openclaw.sh $OPENCLAW_HOME` from the tarball)
 //
 // Behavior:
 //   - Loads $OPENCLAW_HOME/.env so DATABASE_URL / EMBED_PROVIDER /

package/consumers/openclaw-plugin.js

@@ -201,7 +201,7 @@ function register(api) {
 
       return {
         name: 'session_recall',
-        description: 'Search stored sessions by keyword. Supports entity intersection for precise multi-entity queries.',
+        description: 'Search Aquifer memory by keyword. In curated serving mode this searches active curated memory; legacy/evidence lookup is exposed by the MCP stdio evidence_recall tool. Supports entity intersection for precise multi-entity queries.',
         parameters: {
           type: 'object',
           properties: {

package/consumers/shared/config.js

@@ -40,6 +40,11 @@ const DEFAULTS = {
     },
   },
   rank: { rrf: 0.65, timeDecay: 0.25, access: 0.10, entityBoost: 0.18 },
+  memory: {
+    servingMode: 'legacy',   // 'legacy' | 'curated'
+    activeScopeKey: null,
+    activeScopePath: null,
+  },
   rerank: {
     enabled: false,
     provider: null,    // 'tei' | 'jina' | 'openrouter' | 'custom'
@@ -87,6 +92,9 @@ const ENV_MAP = [
   ['AQUIFER_INSIGHTS_DEDUP_MODE',             'insights.dedup.mode'],
   ['AQUIFER_INSIGHTS_DEDUP_COSINE',           'insights.dedup.cosineThreshold', Number],
   ['AQUIFER_INSIGHTS_DEDUP_CLOSE_BAND_FROM',  'insights.dedup.closeBandFrom',   Number],
+  ['AQUIFER_MEMORY_SERVING_MODE', 'memory.servingMode'],
+  ['AQUIFER_MEMORY_ACTIVE_SCOPE_KEY', 'memory.activeScopeKey'],
+  ['AQUIFER_MEMORY_ACTIVE_SCOPE_PATH', 'memory.activeScopePath'],
   ['AQUIFER_RERANK_ENABLED',   'rerank.enabled',    Boolean],
   ['AQUIFER_RERANK_PROVIDER',  'rerank.provider'],
   ['AQUIFER_RERANK_BASE_URL',  'rerank.baseUrl'],

package/consumers/shared/factory.js

@@ -92,6 +92,7 @@ function createAquiferFromConfig(overrides) {
     rerank: rerankOpts,
     migrations: config.migrations,
     insights: config.insights,
+    memory: config.memory,
   });
 
   return aquifer;

package/consumers/shared/ingest.js

@@ -37,7 +37,7 @@ function evictStale(dedupMap, now = Date.now()) {
  * @param {string} [opts.source] — caller-provided source tag (e.g. 'openclaw', 'cc', 'opencode')
  * @param {string} [opts.sessionKey] — passed through to commit()
  * @param {any[]} opts.rawEntries — host-native session entries
- * @param {'gateway'|'cc'|'claude-code'|'preNormalized'} [opts.adapter]
+ * @param {'gateway'|'cc'|'claude-code'|'codex'|'preNormalized'} [opts.adapter]
  *        'preNormalized' means rawEntries already matches normalizeMessages output
  *        (used by OpenCode which reads SQLite directly).
  * @param {object} [opts.preNormalized] — { messages, userCount, ... } ready to commit,

package/consumers/shared/normalize.js

@@ -5,7 +5,7 @@
 // session-level metadata. Wraps pipeline/normalize so consumers don't each
 // reinvent their own role/content extraction.
 //
-// Supported adapters: 'gateway' | 'cc' (alias of 'claude-code'). The OpenCode
+// Supported adapters: 'gateway' | 'cc' (alias of 'claude-code') | 'codex'. The OpenCode
 // consumer reads from SQLite and constructs the output shape directly; it is
 // not expected to route through here.
 //
@@ -21,13 +21,14 @@ const ADAPTER_ALIASES = {
     'cc': 'claude-code',
     'claude-code': 'claude-code',
     'gateway': 'gateway',
+    'codex': 'codex',
 };
 
 function resolveAdapter(adapter) {
     if (!adapter) return null;  // auto-detect
     const name = ADAPTER_ALIASES[adapter];
     if (!name) {
-        throw new Error(`Unknown adapter: "${adapter}". Supported: gateway, cc (alias claude-code).`);
+        throw new Error(`Unknown adapter: "${adapter}". Supported: gateway, cc (alias claude-code), codex.`);
     }
     return name;
 }
@@ -39,6 +40,16 @@ function extractRawMeta(rawEntries) {
 
     for (const entry of rawEntries || []) {
         if (!entry || typeof entry !== 'object') continue;
+
+        if (entry.type === 'turn_context' && entry.payload?.model && !model) {
+            model = entry.payload.model;
+        }
+        if (entry.type === 'event_msg' && entry.payload?.type === 'token_count') {
+            const usage = entry.payload?.info?.last_token_usage || {};
+            tokensIn += usage.input_tokens || usage.input || 0;
+            tokensOut += usage.output_tokens || usage.output || 0;
+        }
+
         const msg = entry.message || entry;
         if (msg && typeof msg === 'object') {
             if (msg.model && !model) model = msg.model;
@@ -57,7 +68,7 @@ function extractRawMeta(rawEntries) {
  *
  * @param {any[]} rawEntries
  * @param {object} [opts]
- * @param {'gateway'|'cc'|'claude-code'} [opts.adapter] — host adapter; auto-detected if omitted
+ * @param {'gateway'|'cc'|'claude-code'|'codex'} [opts.adapter] — host adapter; auto-detected if omitted
  * @returns {{
  *   messages: {role:string,content:string,timestamp:string|null}[],
  *   userCount: number, assistantCount: number,

package/consumers/shared/recall-format.js

@@ -18,6 +18,24 @@ function formatDateIso(value) {
     return Number.isNaN(d.getTime()) ? 'unknown' : d.toISOString().slice(0, 10);
 }
 
+function isCuratedMemoryResult(result) {
+    return Boolean(result && (
+        result.memoryType || result.memory_type ||
+        result.canonicalKey || result.canonical_key ||
+        result.scopeKey || result.scope_key
+    ));
+}
+
+function curatedTitle(result) {
+    const type = result.memoryType || result.memory_type || 'memory';
+    const title = result.title || result.summary || result.canonicalKey || result.canonical_key || type;
+    return truncate(title, 80);
+}
+
+function resultDate(result) {
+    return result.startedAt || result.acceptedAt || result.accepted_at || result.observedAt || result.observed_at || null;
+}
+
 // Humanize a past timestamp into zh-TW relative form (e.g. "3 天前", "昨天").
 // Bucketed on raw ms-diff — good enough for model intuition, not calendar-precise.
 // Returns null for invalid / future timestamps so callers can fall back.
@@ -48,6 +66,11 @@ const defaultRenderers = {
         return query ? `No results found for "${query}".` : 'No matching sessions found.';
     },
     title(result, index) {
+        if (isCuratedMemoryResult(result)) {
+            const date = formatDateIso(resultDate(result));
+            const scope = result.scopeKey || result.scope_key || 'scope:unknown';
+            return `### ${index + 1}. ${curatedTitle(result)} (${date}, ${scope})`;
+        }
         const ss = result.structuredSummary || {};
         const title = ss.title || truncate(result.summaryText, 60) || '(untitled)';
         const date = formatDateIso(result.startedAt);
@@ -55,6 +78,10 @@ const defaultRenderers = {
         return `### ${index + 1}. ${title} (${date}, ${agent})`;
     },
     body(result) {
+        if (isCuratedMemoryResult(result)) {
+            const text = result.summary || result.title || result.canonicalKey || result.canonical_key || '';
+            return text ? truncate(text, 300) : null;
+        }
         const ss = result.structuredSummary || {};
         const text = ss.overview || result.summaryText || '';
         return text ? truncate(text, 300) : null;

package/consumers/shared/summary-parser.js

@@ -0,0 +1,151 @@
+'use strict';
+
+const DEFAULT_SUMMARY_MARKERS = [
+  '===SESSION_ENTRIES===',
+  '===EMOTIONAL_STATE===',
+  '===RECAP===',
+  '===ENTITIES===',
+  '===WORKING_FACTS===',
+  '===HANDOFF===',
+];
+const SUMMARY_MARKERS = DEFAULT_SUMMARY_MARKERS;
+
+function parseSummaryOutput(output, markers = DEFAULT_SUMMARY_MARKERS) {
+  const sections = {};
+  for (let i = 0; i < markers.length; i++) {
+    const start = output.indexOf(markers[i]);
+    if (start === -1) continue;
+    const contentStart = start + markers[i].length;
+    let end = output.length;
+    for (let j = i + 1; j < markers.length; j++) {
+      const candidate = output.indexOf(markers[j], contentStart);
+      if (candidate !== -1) { end = candidate; break; }
+    }
+    const key = markers[i].replace(/===/g, '').toLowerCase();
+    sections[key] = (end > contentStart ? output.slice(contentStart, end) : output.slice(contentStart)).trim();
+  }
+  return sections;
+}
+
+function normalizeOpenOwner(raw) {
+  const owner = (raw || 'unknown').trim().toLowerCase();
+  if (['mk', 'agent', 'unknown'].includes(owner)) return owner;
+  if (/^[a-z][a-z0-9_-]{0,63}$/.test(owner)) return owner;
+  return 'unknown';
+}
+
+function parseRecapLines(text) {
+  const recap = {
+    title: '', overview: '', topics: [], decisions: [], actions_completed: [],
+    open_loops: [], files_mentioned: [], important_facts: [], reusable_patterns: [],
+    focus_decision: 'keep', focus: '', todo_new: [], todo_done: [],
+  };
+
+  for (const line of (text || '').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(/^([A-Z_]+):\s*(.*)/);
+    if (!match) continue;
+    const [, tag, value] = match;
+
+    switch (tag) {
+      case 'TITLE': recap.title = value; break;
+      case 'OVERVIEW': recap.overview = value; break;
+      case 'TOPIC': {
+        const p = value.split('|').map(s => s.trim());
+        if (p[0]) recap.topics.push({ name: p[0], summary: p[1] || '' });
+        break;
+      }
+      case 'DECISION': {
+        const p = value.split('|').map(s => s.trim());
+        if (p[0]) recap.decisions.push({ decision: p[0], reason: p[1] || '' });
+        break;
+      }
+      case 'ACTION': {
+        const p = value.split('|').map(s => s.trim());
+        if (p[0]) recap.actions_completed.push({
+          action: p[0],
+          status: (p[1] || 'done').toLowerCase() === 'partial' ? 'partial' : 'done',
+        });
+        break;
+      }
+      case 'OPEN': {
+        const p = value.split('|').map(s => s.trim());
+        if (p[0]) recap.open_loops.push({
+          item: p[0],
+          owner: normalizeOpenOwner(p[1]),
+        });
+        break;
+      }
+      case 'FACT': if (value) recap.important_facts.push(value); break;
+      case 'PATTERN': {
+        const p = value.split('|').map(s => s.trim());
+        if (p[0] && p[1]) recap.reusable_patterns.push({
+          pattern: p[0], trigger: p[1], action: p[2] || '',
+          durability: (p[3] || 'derived').toLowerCase() === 'invariant' ? 'invariant' : 'derived',
+        });
+        break;
+      }
+      case 'FOCUS_DECISION':
+        recap.focus_decision = value.toLowerCase().trim() === 'update' ? 'update' : 'keep';
+        break;
+      case 'FOCUS': recap.focus = value; break;
+      case 'TODO_NEW': if (value) recap.todo_new.push(value); break;
+      case 'TODO_DONE': if (value) recap.todo_done.push(value); break;
+    }
+  }
+  return recap;
+}
+
+function parseWorkingFacts(text) {
+  if (!text || typeof text !== 'string') return [];
+  const facts = [];
+  for (const line of text.split('\n')) {
+    const m = line.trim().match(/^WFACT:\s*(.+?)\s*\|\s*(.+)/);
+    if (!m) continue;
+    const subject = m[1].trim().slice(0, 100);
+    const statement = m[2].trim().slice(0, 500);
+    if (!subject || !statement) continue;
+    facts.push({ subject, statement });
+    if (facts.length >= 5) break;
+  }
+  return facts;
+}
+
+const VALID_HANDOFF_STATUS = new Set(['in_progress', 'interrupted', 'completed', 'blocked']);
+const VALID_STOP_REASON = new Set(['natural', 'interrupted', 'blocked', 'context_full']);
+
+function normalizeEnum(raw, validSet) {
+  const v = raw.trim().toLowerCase().replace(/-/g, '_').replace(/\s+/g, '_');
+  return validSet.has(v) ? v : null;
+}
+
+function parseHandoffSection(text) {
+  if (!text || typeof text !== 'string') return null;
+  const handoff = { status: 'completed', lastStep: '', next: '', stopReason: 'natural', decided: '', blocker: '' };
+  for (const line of text.split('\n')) {
+    const m = line.trim().match(/^([A-Z_]+):\s*(.*)/);
+    if (!m) continue;
+    const [, tag, value] = m;
+    switch (tag) {
+      case 'STATUS': handoff.status = normalizeEnum(value, VALID_HANDOFF_STATUS) || 'completed'; break;
+      case 'LAST_STEP': handoff.lastStep = value.trim().slice(0, 200); break;
+      case 'NEXT': handoff.next = value.trim().slice(0, 200); break;
+      case 'STOP_REASON': handoff.stopReason = normalizeEnum(value, VALID_STOP_REASON) || 'natural'; break;
+      case 'DECIDED': handoff.decided = value.trim().slice(0, 200); break;
+      case 'BLOCKER': handoff.blocker = value.trim().slice(0, 200); break;
+    }
+  }
+  if (!handoff.lastStep || !handoff.next) return null;
+  return handoff;
+}
+
+module.exports = {
+  DEFAULT_SUMMARY_MARKERS,
+  SUMMARY_MARKERS,
+  parseSummaryOutput,
+  parseRecapLines,
+  parseWorkingFacts,
+  parseHandoffSection,
+  normalizeOpenOwner,
+};