@shadowforge0/aquifer-memory 1.5.12 → 1.6.0

package/core/finalization-review.js

@@ -0,0 +1,319 @@
+'use strict';
+
+const TYPE_LABELS = {
+  state: '狀態',
+  decision: '決策',
+  fact: '事實',
+  preference: '偏好',
+  constraint: '限制',
+  entity_note: '註記',
+  open_loop: '未完成',
+  conclusion: '判斷',
+};
+
+const SESSION_START_TYPE_PRIORITY = {
+  state: 0,
+  open_loop: 1,
+  constraint: 2,
+  preference: 3,
+  decision: 4,
+  fact: 5,
+  conclusion: 6,
+  entity_note: 7,
+};
+
+const AUTHORITY_PRIORITY = {
+  user_explicit: 0,
+  executable_evidence: 1,
+  manual: 2,
+  system: 3,
+  verified_summary: 4,
+  llm_inference: 5,
+  raw_transcript: 6,
+};
+
+const MEMORY_KEYS = [
+  'summary',
+  'title',
+  'decision',
+  'item',
+  'conclusion',
+  'statement',
+  'fact',
+  'preference',
+  'constraint',
+  'state',
+  'note',
+  'text',
+  'value',
+];
+
+const STRUCTURED_FIELDS = [
+  ['states', 'state'],
+  ['state', 'state'],
+  ['decisions', 'decision'],
+  ['important_facts', 'fact'],
+  ['facts', 'fact'],
+  ['preferences', 'preference'],
+  ['constraints', 'constraint'],
+  ['conclusions', 'conclusion'],
+  ['entity_notes', 'entity_note'],
+  ['open_loops', 'open_loop'],
+];
+
+const DEFAULT_OMIT = [
+  '整段逐字稿、工具輸出、debug 訊息',
+  'DB row id、hash、message count 這類 audit 欄位',
+  '已作廢、隔離、錯誤或 superseded 的記憶',
+];
+
+function normalizeText(value) {
+  return String(value || '').trim().replace(/\s+/g, ' ');
+}
+
+function sanitizeHumanText(value) {
+  return normalizeText(value)
+    .replace(/\bDB Write Plan\b/g, 'DB 寫入計畫')
+    .replace(/\bLegacy Continuity Text\b/g, '舊 handoff 包裝文字')
+    .replace(/\bStructured Summary\b/g, 'structured summary 原始欄位')
+    .replace(/\braw JSON\b/gi, '原始 JSON');
+}
+
+function stripTerminalPunctuation(value) {
+  return normalizeText(value).replace(/[。.!?！？]+$/g, '');
+}
+
+function comparable(value) {
+  return stripTerminalPunctuation(value).toLowerCase();
+}
+
+function firstText(value) {
+  if (typeof value === 'string') return normalizeText(value);
+  if (!value || typeof value !== 'object') return '';
+  for (const key of MEMORY_KEYS) {
+    const text = normalizeText(value[key]);
+    if (text) return text;
+  }
+  const payload = value.payload && typeof value.payload === 'object' ? value.payload : null;
+  if (payload) return firstText(payload);
+  return '';
+}
+
+function memoryTypeOf(value) {
+  if (!value || typeof value !== 'object') return 'memory';
+  return value.memoryType || value.memory_type || value.type || 'memory';
+}
+
+function labelFor(type) {
+  return TYPE_LABELS[type] || TYPE_LABELS[String(type || '').toLowerCase()] || '記憶';
+}
+
+function pushUnique(out, text) {
+  const normalized = sanitizeHumanText(text);
+  if (!normalized) return;
+  const key = comparable(normalized);
+  if (!key || out.some(item => comparable(item) === key)) return;
+  out.push(normalized);
+}
+
+function asLine(type, text, suffix = '') {
+  const body = normalizeText(text);
+  if (!body) return '';
+  return `${labelFor(type)}：${body}${suffix}`;
+}
+
+function truncate(text, max = 220) {
+  const normalized = sanitizeHumanText(text);
+  if (normalized.length <= max) return normalized;
+  return `${normalized.slice(0, max - 1)}...`;
+}
+
+function addStructuredItems(out, structuredSummary = {}, filter = null) {
+  for (const [field, type] of STRUCTURED_FIELDS) {
+    if (filter && !filter(type)) continue;
+    const items = Array.isArray(structuredSummary[field]) ? structuredSummary[field] : [];
+    for (const item of items) {
+      const text = firstText(item);
+      if (!text) continue;
+      const owner = type === 'open_loop' && item && typeof item === 'object' && normalizeText(item.owner)
+        ? `（owner: ${normalizeText(item.owner)}）`
+        : '';
+      pushUnique(out, asLine(type, text, owner));
+    }
+  }
+}
+
+function promotedMemoryLines(memoryResults = []) {
+  const lines = [];
+  for (const result of memoryResults || []) {
+    if (!result || result.action !== 'promote') continue;
+    const memory = result.memory || result.record || result.candidate || {};
+    const type = memoryTypeOf(memory);
+    if (type === 'open_loop') continue;
+    pushUnique(lines, asLine(type, firstText(memory)));
+  }
+  return lines;
+}
+
+function openLoopLines(memoryResults = [], structuredSummary = {}) {
+  const lines = [];
+  for (const result of memoryResults || []) {
+    if (!result || result.action !== 'promote') continue;
+    const memory = result.memory || result.record || result.candidate || {};
+    const type = memoryTypeOf(memory);
+    if (type !== 'open_loop') continue;
+    const owner = normalizeText(memory.owner || memory.payload?.owner);
+    pushUnique(lines, asLine(type, firstText(memory), owner ? `（owner: ${owner}）` : ''));
+  }
+  if (lines.length === 0) {
+    addStructuredItems(lines, structuredSummary, type => type === 'open_loop');
+  }
+  return lines;
+}
+
+function inactiveLines(memoryResults = [], extraInactive = []) {
+  const lines = [];
+  for (const result of memoryResults || []) {
+    if (!result || result.action === 'promote') continue;
+    const candidate = result.candidate || result.memory || result.record || {};
+    const text = firstText(candidate);
+    const reason = normalizeText(result.reason);
+    const action = normalizeText(result.action || 'skipped');
+    if (text || reason) {
+      pushUnique(lines, `${action}：${text || '未命名候選'}${reason ? `（${reason}）` : ''}`);
+    }
+  }
+  for (const item of extraInactive || []) {
+    const text = firstText(item);
+    const status = normalizeText(item.status || item.action || 'inactive');
+    const reason = normalizeText(item.reason || item.obsoleteReason || item.obsolete_reason);
+    if (text || reason) {
+      pushUnique(lines, `${status}：${text || '未命名記憶'}${reason ? `（${reason}）` : ''}`);
+    }
+  }
+  return lines;
+}
+
+function linesOrNone(lines) {
+  if (!lines || lines.length === 0) return '無';
+  return lines.map(line => `- ${line}`).join('\n');
+}
+
+function buildAuditLines(input = {}) {
+  const finalization = input.finalization || {};
+  const memoryResult = input.memoryResult || {};
+  const audit = input.audit || {};
+  const pairs = [
+    ['sessionId', audit.sessionId || input.sessionId],
+    ['finalizationId', audit.finalizationId || finalization.id],
+    ['handoffId', audit.handoffId || input.handoffId],
+    ['transcriptHash', audit.transcriptHash || input.transcriptHash],
+    ['promoted', memoryResult.promoted],
+    ['quarantined', memoryResult.quarantined],
+    ['skipped', memoryResult.skipped],
+    ['policyVersion', audit.policyVersion || input.policyVersion],
+    ['schemaVersion', audit.schemaVersion || input.schemaVersion],
+  ].filter(([, value]) => value !== undefined && value !== null && value !== '');
+  return pairs.map(([key, value]) => `${key}: ${value}`);
+}
+
+function collectRemembered(input = {}) {
+  const structuredSummary = input.structuredSummary || input.summary?.structuredSummary || {};
+  const memoryResults = input.memoryResults || [];
+  const lines = promotedMemoryLines(memoryResults);
+  if (lines.length === 0) {
+    addStructuredItems(lines, structuredSummary, type => type !== 'open_loop');
+  }
+  return lines;
+}
+
+function buildCarryForwardLines(input = {}) {
+  const lines = [];
+  for (const line of input.openLoops || openLoopLines(input.memoryResults, input.structuredSummary || input.summary?.structuredSummary || {})) {
+    pushUnique(lines, line);
+  }
+  const next = normalizeText(input.next || input.metadata?.handoff?.next);
+  if (next && next !== '無') pushUnique(lines, `下一步：${next}`);
+  return lines;
+}
+
+function buildFinalizationReview(input = {}, opts = {}) {
+  const summary = input.summary || {};
+  const structuredSummary = input.structuredSummary || summary.structuredSummary || {};
+  const summaryText = input.summaryText || summary.summaryText || input.overview || '';
+  const statusLine = truncate(input.currentStatus || summaryText || input.title || '已完成本段 finalization。');
+  const remembered = collectRemembered({ ...input, structuredSummary });
+  const openLoops = openLoopLines(input.memoryResults || [], structuredSummary);
+  const inactive = inactiveLines(input.memoryResults || [], input.inactive || []);
+  const carryForward = buildCarryForwardLines({ ...input, structuredSummary, openLoops });
+  const omit = [];
+  for (const item of opts.omit || input.omit || DEFAULT_OMIT) pushUnique(omit, item);
+  const heading = opts.preview ? '準備整理進 DB：' : '已整理進 DB：';
+  const lines = [
+    heading,
+    `目前狀態：\n${linesOrNone([statusLine])}`,
+    `已記住：\n${linesOrNone(remembered)}`,
+    `未完成：\n${linesOrNone(openLoops)}`,
+    `已作廢或隔離：\n${linesOrNone(inactive)}`,
+    `下一段只需要帶：\n${linesOrNone(carryForward)}`,
+    `不要帶：\n${linesOrNone(omit)}`,
+  ];
+  if (opts.includeAudit === true) {
+    lines.push(`Audit：\n${linesOrNone(buildAuditLines(input))}`);
+  }
+  return `${lines.join('\n\n')}\n`;
+}
+
+function buildSessionStartContext(records = [], opts = {}) {
+  const asOf = opts.asOf ? Date.parse(opts.asOf) : null;
+  const limit = Math.max(1, Math.min(50, opts.limit || 12));
+  const maxChars = Math.max(120, opts.maxChars || 1800);
+  const active = [];
+  for (const [index, record] of (records || []).entries()) {
+    const status = record.status || 'candidate';
+    const visible = record.visibleInBootstrap ?? record.visible_in_bootstrap;
+    if (status !== 'active' || visible !== true) continue;
+    if (Number.isFinite(asOf)) {
+      const validFrom = Date.parse(record.validFrom || record.valid_from || '');
+      const validTo = Date.parse(record.validTo || record.valid_to || '');
+      const staleAfter = Date.parse(record.staleAfter || record.stale_after || '');
+      if (Number.isFinite(validFrom) && validFrom > asOf) continue;
+      if (Number.isFinite(validTo) && validTo <= asOf) continue;
+      if (Number.isFinite(staleAfter) && staleAfter <= asOf) continue;
+    }
+    active.push({ record, index });
+  }
+
+  active.sort((a, b) => {
+    const aType = SESSION_START_TYPE_PRIORITY[memoryTypeOf(a.record)] ?? 99;
+    const bType = SESSION_START_TYPE_PRIORITY[memoryTypeOf(b.record)] ?? 99;
+    if (aType !== bType) return aType - bType;
+
+    const aAuth = AUTHORITY_PRIORITY[a.record.authority] ?? 99;
+    const bAuth = AUTHORITY_PRIORITY[b.record.authority] ?? 99;
+    if (aAuth !== bAuth) return aAuth - bAuth;
+
+    const aAccepted = Date.parse(a.record.acceptedAt || a.record.accepted_at || '') || 0;
+    const bAccepted = Date.parse(b.record.acceptedAt || b.record.accepted_at || '') || 0;
+    if (aAccepted !== bAccepted) return bAccepted - aAccepted;
+    return a.index - b.index;
+  });
+
+  const lines = [];
+  for (const { record } of active.slice(0, limit)) {
+    const type = memoryTypeOf(record);
+    pushUnique(lines, asLine(type, firstText(record)));
+  }
+  let selected = lines;
+  let text = `下一段只需要帶：\n${linesOrNone(selected)}\n`;
+  while (text.length > maxChars && selected.length > 1) {
+    selected = selected.slice(0, -1);
+    text = `下一段只需要帶：\n${linesOrNone(selected)}\n`;
+  }
+  return text;
+}
+
+module.exports = {
+  buildFinalizationReview,
+  buildSessionStartContext,
+};

package/core/mcp-manifest.js

@@ -20,7 +20,7 @@ const MCP_SERVER_NAME = 'aquifer-memory';
 const MCP_TOOL_MANIFEST = Object.freeze([
   {
     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; entityMode="all" hard-filters to sessions containing every entity (default "any" boosts). Use mode to force fts/vector/hybrid (default hybrid). Use dateFrom/dateTo for time-bounded recall.',
+    description: 'Search Aquifer memory. When memory serving mode is curated, this searches active curated memory only; use evidence_recall for legacy session/evidence lookup. Use entities/date filters where supported by the active serving mode.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -50,13 +50,41 @@ const MCP_TOOL_MANIFEST = Object.freeze([
           type: 'boolean',
           description: 'Include per-result score breakdown (rrf, timeDecay, entity, trust, rerank). Diagnostic use only.',
         },
+        activeScopeKey: { type: 'string', description: 'Active curated memory scope key, e.g. project:aquifer' },
+        activeScopePath: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Ordered curated scope path from global to active scope',
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'evidence_recall',
+    description: 'Explicit legacy/evidence search over stored sessions and summaries. This is for audit/debug/distillation and must not implicitly feed bootstrap.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        query: { type: 'string', minLength: 1, description: 'Evidence search query (keyword or natural language)' },
+        limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Max results (default 5)' },
+        agentId: { type: 'string', description: 'Filter by agent ID' },
+        source: { type: 'string', description: 'Filter by source (e.g., gateway, cc)' },
+        dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD' },
+        dateTo: { type: 'string', description: 'End date YYYY-MM-DD' },
+        entities: { type: 'array', items: { type: 'string' }, description: 'Entity names to match' },
+        entityMode: { type: 'string', enum: ['any', 'all'], description: '"any" (default, boost) or "all" hard filter' },
+        mode: { type: 'string', enum: ['fts', 'hybrid', 'vector'], description: 'Legacy evidence recall mode' },
+        explain: { type: 'boolean', description: 'Include diagnostic score breakdown.' },
+        allowUnsafeDebug: { type: 'boolean', description: 'Allow broad evidence/debug search without an audit boundary.' },
       },
       required: ['query'],
     },
   },
   {
     name: 'session_feedback',
-    description: '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.',
+    description: 'After using legacy session_recall or bootstrap, mark the recalled session helpful or unhelpful. This only targets legacy session trust, not curated memory rows.',
     inputSchema: {
       type: 'object',
       additionalProperties: false,
@@ -69,6 +97,22 @@ const MCP_TOOL_MANIFEST = Object.freeze([
       required: ['sessionId', 'verdict'],
     },
   },
+  {
+    name: 'memory_feedback',
+    description: 'Record append-only feedback on a curated memory row. This affects curated ranking/review priority only and does not mutate memory truth.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        memoryId: { type: 'string', minLength: 1, description: 'Curated memory record ID to give feedback on' },
+        canonicalKey: { type: 'string', minLength: 1, description: 'Canonical key of the active curated memory record' },
+        feedbackType: { type: 'string', enum: ['helpful', 'confirm', 'irrelevant', 'scope_mismatch', 'stale', 'incorrect'], description: 'Curated memory feedback event type' },
+        note: { type: 'string', description: 'Optional reason' },
+        agentId: { type: 'string', description: 'Optional actor/agent label for audit metadata' },
+      },
+      required: ['feedbackType'],
+    },
+  },
   {
     name: 'memory_stats',
     description: 'Return storage statistics for the Aquifer memory store (session counts by status, summaries, turn embeddings, entities, date range).',
@@ -113,6 +157,12 @@ const MCP_TOOL_MANIFEST = Object.freeze([
         limit: { type: 'integer', minimum: 1, maximum: 20, description: 'Max sessions (default 5)' },
         lookbackDays: { type: 'integer', minimum: 1, maximum: 90, description: 'How far back in days (default 14)' },
         maxChars: { type: 'integer', minimum: 500, maximum: 12000, description: 'Max output characters (default 4000)' },
+        activeScopeKey: { type: 'string', description: 'Active curated memory scope key, e.g. project:aquifer' },
+        activeScopePath: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Ordered curated scope path from global to active scope',
+        },
       },
     },
   },

package/core/memory-bootstrap.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const TYPE_PRIORITY = {
+  constraint: 0,
+  preference: 1,
+  state: 2,
+  open_loop: 3,
+  decision: 4,
+  fact: 5,
+  conclusion: 6,
+  entity_note: 7,
+};
+
+const AUTHORITY_PRIORITY = {
+  user_explicit: 0,
+  executable_evidence: 1,
+  manual: 2,
+  system: 3,
+  verified_summary: 4,
+  llm_inference: 5,
+  raw_transcript: 6,
+};
+
+function recordId(record) {
+  return String(record.memoryId || record.memory_id || record.id || record.canonicalKey || record.canonical_key);
+}
+
+function scopeKey(record) {
+  return record.scopeKey || record.scope_key || record.scope || '';
+}
+
+function inheritanceMode(record) {
+  return record.inheritanceMode || record.inheritance_mode || record.scope_inheritance_mode || 'defaultable';
+}
+
+function canonicalKey(record) {
+  return record.canonicalKey || record.canonical_key || recordId(record);
+}
+
+function parseTime(value) {
+  const t = Date.parse(value || '');
+  return Number.isFinite(t) ? t : null;
+}
+
+function isWithinTime(record, asOf) {
+  if (!asOf) return true;
+  const at = Date.parse(asOf);
+  if (!Number.isFinite(at)) return true;
+  const validFrom = parseTime(record.validFrom || record.valid_from);
+  const validTo = parseTime(record.validTo || record.valid_to);
+  const staleAfter = parseTime(record.staleAfter || record.stale_after);
+  if (validFrom !== null && validFrom > at) return false;
+  if (validTo !== null && validTo <= at) return false;
+  if (staleAfter !== null && staleAfter <= at) return false;
+  return true;
+}
+
+function isActiveBootstrap(record, opts = {}) {
+  return (record.status || 'candidate') === 'active'
+    && (record.visibleInBootstrap ?? record.visible_in_bootstrap) === true
+    && isWithinTime(record, opts.asOf);
+}
+
+function resolveApplicableRecords(records = [], opts = {}) {
+  const activeScopePath = opts.activeScopePath || (opts.activeScopeKey ? [opts.activeScopeKey] : ['global']);
+  const activeScope = opts.activeScopeKey || activeScopePath[activeScopePath.length - 1] || null;
+  const position = new Map(activeScopePath.map((key, idx) => [key, idx]));
+  const additive = [];
+  const winners = new Map();
+
+  for (const record of records) {
+    const recScope = scopeKey(record);
+    const mode = inheritanceMode(record);
+    const isExact = activeScope && recScope === activeScope;
+    const isInPath = position.has(recScope);
+    if (mode === 'non_inheritable' && !isExact) continue;
+    if (mode !== 'non_inheritable' && activeScopePath.length > 0 && !isInPath) continue;
+
+    if (mode === 'additive') {
+      additive.push(record);
+      continue;
+    }
+
+    const key = canonicalKey(record);
+    const existing = winners.get(key);
+    if (!existing) {
+      winners.set(key, record);
+      continue;
+    }
+
+    const currentPos = position.get(recScope) ?? -1;
+    const existingPos = position.get(scopeKey(existing)) ?? -1;
+    if (currentPos > existingPos) winners.set(key, record);
+  }
+
+  return [...winners.values(), ...additive];
+}
+
+function sortForBootstrap(a, b) {
+  const aType = TYPE_PRIORITY[a.memoryType || a.memory_type] ?? 99;
+  const bType = TYPE_PRIORITY[b.memoryType || b.memory_type] ?? 99;
+  if (aType !== bType) return aType - bType;
+
+  const aAuth = AUTHORITY_PRIORITY[a.authority] ?? 99;
+  const bAuth = AUTHORITY_PRIORITY[b.authority] ?? 99;
+  if (aAuth !== bAuth) return aAuth - bAuth;
+
+  const aAccepted = Date.parse(a.acceptedAt || a.accepted_at || '') || 0;
+  const bAccepted = Date.parse(b.acceptedAt || b.accepted_at || '') || 0;
+  if (aAccepted !== bAccepted) return bAccepted - aAccepted;
+
+  return canonicalKey(a).localeCompare(canonicalKey(b));
+}
+
+function lineFor(record) {
+  const type = record.memoryType || record.memory_type || 'memory';
+  const text = record.summary || record.title || '';
+  return `- ${type}: ${String(text).trim()}`;
+}
+
+function buildText(records, meta) {
+  const lines = records.map(lineFor);
+  return [
+    `<memory-bootstrap memories="${records.length}" overflow="${meta.overflow}" degraded="${meta.degraded}">`,
+    ...lines,
+    '</memory-bootstrap>',
+  ].join('\n');
+}
+
+function buildMemoryBootstrap(records = [], opts = {}) {
+  const maxChars = Math.max(120, opts.maxChars || 4000);
+  const active = resolveApplicableRecords(
+    records.filter(record => isActiveBootstrap(record, opts)),
+    opts,
+  ).sort(sortForBootstrap);
+
+  const meta = {
+    overflow: false,
+    degraded: false,
+    maxChars,
+    count: active.length,
+  };
+
+  let selected = active.slice();
+  let text = buildText(selected, meta);
+  while (text.length > maxChars && selected.length > 1) {
+    selected = selected.slice(0, -1);
+    meta.overflow = true;
+    meta.degraded = true;
+    text = buildText(selected, meta);
+  }
+
+  if (text.length > maxChars) {
+    meta.overflow = true;
+    meta.degraded = true;
+  }
+
+  const structured = {
+    memories: selected,
+    meta: { ...meta, count: selected.length },
+  };
+
+  if (opts.format === 'text') return { ...structured, text };
+  if (opts.format === 'both' || opts.format === undefined) return { ...structured, text };
+  return structured;
+}
+
+function createMemoryBootstrap({ records }) {
+  async function bootstrap(opts = {}) {
+    const rows = await records.listActive({
+      tenantId: opts.tenantId,
+      scopeId: opts.scopeId,
+      scopeKeys: opts.activeScopePath || (opts.activeScopeKey ? [opts.activeScopeKey] : undefined),
+      visibleInBootstrap: true,
+      asOf: opts.asOf,
+      limit: opts.limit || 50,
+    });
+    return buildMemoryBootstrap(rows, opts);
+  }
+
+  return { bootstrap };
+}
+
+module.exports = {
+  buildMemoryBootstrap,
+  resolveApplicableRecords,
+  createMemoryBootstrap,
+};