@shadowforge0/aquifer-memory 1.5.9 → 1.6.0

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,
@@ -46,13 +46,45 @@ const MCP_TOOL_MANIFEST = Object.freeze([
           enum: ['fts', 'hybrid', 'vector'],
           description: 'Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)',
         },
+        explain: {
+          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: 'Record trust feedback on a recalled session. Helpful sessions 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,
@@ -65,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).',
@@ -85,6 +133,19 @@ const MCP_TOOL_MANIFEST = Object.freeze([
       },
     },
   },
+  {
+    name: 'feedback_stats',
+    description: 'Return trust feedback statistics: total feedback count, helpful/unhelpful breakdown, trust score distribution, and coverage (how many sessions have been rated).',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        agentId: { type: 'string', description: 'Filter by agent ID' },
+        dateFrom: { type: 'string', description: 'Start date YYYY-MM-DD for feedback window' },
+        dateTo: { type: 'string', description: 'End date YYYY-MM-DD for feedback window' },
+      },
+    },
+  },
   {
     name: 'session_bootstrap',
     description: 'Load recent session context for a new conversation. Returns summaries, open items, and decisions from recent sessions. Call this at the start of a conversation for continuity; use session_recall for keyword search.',
@@ -96,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,
+};