forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/memory/router.js

@@ -29,11 +29,16 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const projectMemory = require('../project-memory');
+const {
+  assertBackend,
+  createMemoryBackendRegistry,
+} = require('../../packages/memory');
 
 /** Supported PUBLIC backends, default first. */
 const MEMORY_BACKENDS = ['local', 'graphiti'];
 const DEFAULT_MEMORY_BACKEND = 'local';
 const ENV_VAR = 'FORGE_MEMORY_BACKEND';
+const registeredMemoryBackends = new Map();
 
 /** Default recall cap — newest-N, so `recall` with no query never dumps the whole store. */
 const DEFAULT_RECALL_LIMIT = 20;
@@ -126,7 +131,7 @@ function resolveMemoryBackend({
   if (!value) return DEFAULT_MEMORY_BACKEND;
 
   const normalized = value.toLowerCase();
-  if (MEMORY_BACKENDS.includes(normalized)) return normalized;
+  if (MEMORY_BACKENDS.includes(normalized) || registeredMemoryBackends.has(normalized)) return normalized;
 
   warn(
     `Unknown memory backend "${value}" from ${source}; `
@@ -135,6 +140,22 @@ function resolveMemoryBackend({
   return DEFAULT_MEMORY_BACKEND;
 }
 
+function registerMemoryBackend(name, adapter) {
+  const normalized = typeof name === 'string' ? name.trim().toLowerCase() : '';
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(normalized) || MEMORY_BACKENDS.includes(normalized)) {
+    throw new TypeError('custom memory backend must have a unique lowercase name');
+  }
+  if (registeredMemoryBackends.has(normalized)) {
+    throw new Error(`custom memory backend "${normalized}" is already registered`);
+  }
+  assertBackend(adapter, normalized);
+  registeredMemoryBackends.set(normalized, adapter);
+}
+
+function unregisterMemoryBackend(name) {
+  registeredMemoryBackends.delete(String(name || '').trim().toLowerCase());
+}
+
 /**
  * Strict validation for the resolved backend. Unlike `resolveMemoryBackend`
  * (which soft-falls-back), this THROWS a clear, actionable error when the
@@ -145,6 +166,17 @@ function resolveMemoryBackend({
  */
 function assertMemoryConfigValid({ deps = {}, env = process.env, projectRoot, config } = {}) {
   const memory = config || readMemoryConfig(projectRoot);
+  const signal = collectBackendSignal({ deps, env, projectRoot, config: memory });
+  const requested = signal.value?.toLowerCase();
+  if (requested && !MEMORY_BACKENDS.includes(requested) && !registeredMemoryBackends.has(requested)) {
+    const error = new Error(
+      `memory backend "${signal.value}" from ${signal.source} is not registered. `
+      + `Available backends: ${[...MEMORY_BACKENDS, ...registeredMemoryBackends.keys()]
+        .sort((left, right) => left.localeCompare(right)).join(', ')}.`,
+    );
+    error.backend = signal.value;
+    throw error;
+  }
   const backend = resolveMemoryBackend({ deps, env, projectRoot, config: memory, warn: () => {} });
 
   if (backend !== 'graphiti') {
@@ -182,19 +214,32 @@ function assertMemoryConfigValid({ deps = {}, env = process.env, projectRoot, co
  * never-hang guarantee — the emitter, not this seam, owns preventing that.
  *
  * @param {object} [emitter] - optional `{ emit(entry) }` injected by callers.
- * @param {object} entry - the persisted local entry.
+ * @param {Function} entryProvider - returns the persisted local entry.
  */
-function fireAndForgetGraphitiEmit(emitter, entry) {
-  if (!emitter || typeof emitter.emit !== 'function') return;
-  try {
-    // Do not await: fire-and-forget. If it returns a promise, swallow rejection.
-    const maybePromise = emitter.emit(entry);
-    if (maybePromise && typeof maybePromise.then === 'function') {
-      maybePromise.then(() => {}, () => {});
-    }
-  } catch {
-    // Hard fallback: the local write already succeeded. Never surface emit errors.
-  }
+// The implementation now lives in the adapter below so synchronous failures can
+// be represented in the operation receipt while rejected promises stay consumed.
+
+function graphitiAdapter(emitter, entryProvider) {
+  const unavailable = () => [];
+  const freeze = (value, seen = new WeakSet()) => {
+    if (!value || typeof value !== 'object' || seen.has(value)) return value;
+    seen.add(value);
+    for (const child of Object.values(value)) freeze(child, seen);
+    return Object.freeze(value);
+  };
+  return {
+    add() {
+      if (!emitter || typeof emitter.emit !== 'function') return;
+      const maybePromise = emitter.emit(freeze(structuredClone(entryProvider())));
+      if (maybePromise && typeof maybePromise.then === 'function') {
+        maybePromise.then(() => {}, () => {});
+      }
+    },
+    recall: unavailable,
+    search: unavailable,
+    capture: unavailable,
+    digest: unavailable,
+  };
 }
 
 /**
@@ -242,6 +287,21 @@ function legacyJsonlPath(projectRoot) {
   return path.join(projectRoot, ...LEGACY_JSONL_RELATIVE);
 }
 
+function legacyTags(parsed) {
+  const tags = Array.isArray(parsed.tags)
+    ? parsed.tags.filter(tag => typeof tag === 'string')
+    : [];
+  if (
+    typeof parsed.type === 'string'
+    && /^[a-z0-9][a-z0-9-]{0,63}$/i.test(parsed.type)
+    && !tags.some(tag => tag.startsWith('type:'))
+  ) {
+    tags.push(`type:${parsed.type.toLowerCase()}`);
+  }
+  if (!tags.some(tag => tag.startsWith('trust:'))) tags.push('trust:suggested');
+  return tags;
+}
+
 // A STABLE key for a legacy record that lacks an `id`, derived from its content — so a
 // re-run (or a failed rename) upserts the same row instead of double-inserting under a
 // fresh random UUID.
@@ -292,7 +352,7 @@ function migrateJsonlNotesOnce(projectRoot, options = {}) {
       key: typeof parsed.id === 'string' && parsed.id ? parsed.id : legacyContentKey(parsed),
       value: parsed.note,
       sourceAgent: IMPORT_SOURCE_AGENT,
-      tags: Array.isArray(parsed.tags) ? parsed.tags.filter(tag => typeof tag === 'string') : [],
+      tags: legacyTags(parsed),
     };
     if (typeof parsed.timestamp === 'string' && parsed.timestamp && !Number.isNaN(Date.parse(parsed.timestamp))) {
       entry.timestamp = parsed.timestamp;
@@ -321,20 +381,38 @@ function migrateJsonlNotesOnce(projectRoot, options = {}) {
  * @param {object} [options] - { tags, deps, env, config, graphitiEmitter, store }
  * @returns {{ id: string, note: string, timestamp: string, tags: string[] }}
  */
-function append(projectRoot, note, options = {}) {
+function appendWithReceipt(projectRoot, note, options = {}) {
   migrateJsonlNotesOnce(projectRoot, options);
   const backend = resolveMemoryBackend({ ...options, projectRoot });
-  const written = projectMemory.write(projectRoot, {
-    key: crypto.randomUUID(),
-    value: note,
-    sourceAgent: REMEMBER_SOURCE_AGENT,
-    tags: Array.isArray(options.tags) ? options.tags : [],
-  }, options);
-  const entry = toNote(written);
+  let entry;
+  const local = {
+    add() {
+      const written = projectMemory.write(projectRoot, {
+        key: crypto.randomUUID(),
+        value: note,
+        sourceAgent: REMEMBER_SOURCE_AGENT,
+        tags: Array.isArray(options.tags) ? options.tags : [],
+      }, options);
+      entry = toNote(written);
+      return entry;
+    },
+    recall: () => [],
+    search: () => [],
+    capture: () => null,
+    digest: () => null,
+  };
+  const registry = createMemoryBackendRegistry({ local });
   if (backend === 'graphiti') {
-    fireAndForgetGraphitiEmit(options.graphitiEmitter, entry);
+    registry.register('graphiti', graphitiAdapter(options.graphitiEmitter, () => entry));
+  } else if (backend !== 'local') {
+    registry.register(backend, registeredMemoryBackends.get(backend));
   }
-  return entry;
+  registry.select(backend);
+  return registry.add(note);
+}
+
+function append(projectRoot, note, options = {}) {
+  return appendWithReceipt(projectRoot, note, options).value;
 }
 
 /**
@@ -348,7 +426,7 @@ function append(projectRoot, note, options = {}) {
  * widens it to every stored memory.
  *
  * @param {string} projectRoot
- * @param {object} [selection] - { query, limit, all }
+ * @param {object} [selection] - { query, limit, all, kind }
  * @param {object} [options] - forwarded to the project-memory read paths (e.g. a store).
  * @returns {{ notes: object[], total: number, capped: boolean, query: string, limit: number, scope: string }}
  */
@@ -358,15 +436,16 @@ function recall(projectRoot, selection = {}, options = {}) {
   const limit = Number.isInteger(requested) && requested > 0 ? requested : DEFAULT_RECALL_LIMIT;
   const query = String(selection.query || '').trim();
   const includeAll = Boolean(selection.all);
+  const kind = typeof selection.kind === 'string' ? selection.kind.trim() : '';
+  const agents = includeAll ? undefined : HUMAN_MEMORY_AGENTS;
+  const readOptions = { ...options, agents, kind };
 
   if (query) {
-    const notes = projectMemory.searchRanked(projectRoot, query, limit, options).map(toNote);
+    const notes = projectMemory.searchRanked(projectRoot, query, limit, readOptions).map(toNote);
     // BM25 returns at most `limit`; a full result set signals there may be more.
     return { notes, total: notes.length, capped: notes.length >= limit, query, limit, scope: 'all' };
   }
 
-  const agents = includeAll ? undefined : HUMAN_MEMORY_AGENTS;
-  const readOptions = { ...options, agents };
   const notes = projectMemory.recent(projectRoot, limit, readOptions).map(toNote);
   const total = projectMemory.count(projectRoot, readOptions);
   return { notes, total, capped: total > notes.length, query: '', limit, scope: includeAll ? 'all' : 'remembered' };
@@ -380,8 +459,11 @@ module.exports = {
   readMemoryConfig,
   resolveMemoryBackend,
   assertMemoryConfigValid,
+  registerMemoryBackend,
+  unregisterMemoryBackend,
   migrateJsonlNotesOnce,
   toNote,
   append,
+  appendWithReceipt,
   recall,
 };

package/lib/memory/usage-evidence.js

@@ -0,0 +1,4 @@
+'use strict';
+
+// Compatibility shim: the durable usage contract belongs to @forge/memory.
+module.exports = require('../../packages/memory');

package/lib/memory-digest.js

@@ -22,11 +22,14 @@
 const { applyBudget, buildSection, estimateTokens } = require('./orientation');
 const { fenceUntrusted } = require('./untrusted-content');
 const { collectInbox, inboxSection } = require('./inbox');
+const { memoryTrustStatus } = require('./memory-recall');
 
 const DEFAULT_DIGEST_BUDGET_TOKENS = 400;
 const DEFAULT_NOTE_LIMIT = 5;
 const DEFAULT_ISSUE_LIMIT = 5;
 const DIGEST_HEADER = 'Forge memory (auto-injected at session start):';
+const READ_ATTENTION_HEADER = 'Forge path memory (untrusted context; not authority):';
+const SESSION_SUMMARY_REMINDER = 'Before ending this session, persist only durable learnings with `forge remember --session-summary --what <text> --why <text> --learned <text>`.';
 
 /** Run an async producer, returning `fallback` on any throw/rejection (never propagates). */
 async function safe(producer, fallback) {
@@ -103,7 +106,13 @@ async function collectDigestData(projectRoot, opts = {}) {
 /** `- [date ]note` for a recall note. */
 function formatNoteLine(note) {
   const date = typeof note.timestamp === 'string' && note.timestamp ? `${note.timestamp.slice(0, 10)} ` : '';
-  return `- ${date}${note.note}`;
+  const trust = memoryTrustStatus({
+    tags: note.tags,
+    sourceAgent: note.sourceAgent,
+    value: note.machine ? {} : note.note,
+  });
+  const sourceAgent = note.sourceAgent || 'unknown';
+  return `- [source=${sourceAgent} trust=${trust} updated=${date.trim() || 'unknown'}] ${note.note}`;
 }
 
 /** `- [label] title` for an issue row (title/id defensively resolved). */
@@ -112,18 +121,39 @@ function formatIssueLine(label, issue) {
   return `- [${label}] ${title}`;
 }
 
-/** Build the notes section, or null when there are no notes. */
-function notesSection(notes) {
-  if (!notes.length) return null;
-  return buildSection({
-    id: 'digest_notes',
-    title: 'Remembered notes',
-    content: notes.map(formatNoteLine).join('\n'),
-    priority: 10,
-    preserve: false,
-    // Untrusted: a planted note is DATA, not instructions. Fenced after truncation.
-    untrustedSource: 'memory',
-  });
+/** Build separate confirmed/suggested note sections, skipping entries too large to fit. */
+function notesSections(notes, budgetTokens) {
+  const eligible = notes
+    .map(note => ({ note, line: formatNoteLine(note) }))
+    .filter(entry => estimateTokens(entry.line) <= budgetTokens);
+  const groups = [
+    { id: 'digest_notes', title: 'Confirmed memory', trust: 'confirmed', priority: 10 },
+    {
+      id: 'digest_suggested_memory',
+      title: 'Suggested memory — verify before relying',
+      trust: 'suggested',
+      priority: 11,
+    },
+  ];
+  return groups.map(group => {
+    const content = eligible
+      .filter(({ note }) => memoryTrustStatus({
+        tags: note.tags,
+        sourceAgent: note.sourceAgent,
+        value: note.machine ? {} : note.note,
+      }) === group.trust)
+      .map(entry => entry.line)
+      .join('\n');
+    if (!content) return null;
+    return buildSection({
+      id: group.id,
+      title: group.title,
+      content,
+      priority: group.priority,
+      preserve: false,
+      untrustedSource: 'memory',
+    });
+  }).filter(Boolean);
 }
 
 /**
@@ -148,6 +178,59 @@ function issuesSection(ready, claimed) {
   });
 }
 
+function sessionSummarySection(claimed) {
+  if (!claimed.length) return null;
+  return buildSection({
+    id: 'session_summary_nudge',
+    title: 'Session learning reminder',
+    content: SESSION_SUMMARY_REMINDER,
+    priority: 1,
+    preserve: true,
+  });
+}
+
+function normalizePath(value) {
+  return String(value || '').replaceAll('\\', '/').replace(/^\.\//, '').toLowerCase();
+}
+
+function notePaths(note) {
+  const explicit = [note?.path, ...(Array.isArray(note?.paths) ? note.paths : [])];
+  const tagged = (Array.isArray(note?.tags) ? note.tags : [])
+    .filter(tag => typeof tag === 'string' && tag.startsWith('path:'))
+    .map(tag => tag.slice('path:'.length));
+  return [...explicit, ...tagged].map(normalizePath).filter(Boolean);
+}
+
+function matchesPath(targetPath, candidatePath) {
+  const target = normalizePath(targetPath);
+  const candidate = normalizePath(candidatePath);
+  return target === candidate || target.endsWith(`/${candidate}`);
+}
+
+function buildReadAttentionDigest(targetPath, notes = [], options = {}) {
+  const budgetTokens = options.budgetTokens || 160;
+  const matched = (Array.isArray(notes) ? notes : []).filter(note =>
+    notePaths(note).some(candidate => matchesPath(targetPath, candidate)));
+  if (!matched.length) return { text: '', empty: true, tokens: 0 };
+
+  const lines = matched.map(formatNoteLine);
+  const section = buildSection({
+    id: 'read_attention',
+    title: 'Path-matched memory',
+    content: lines.join('\n'),
+    priority: 1,
+    preserve: false,
+    untrustedSource: 'path-memory',
+  });
+  const budgeted = applyBudget([section], Math.max(1, budgetTokens - estimateTokens(READ_ATTENTION_HEADER) - 20));
+  const content = budgeted.sections[0]?.content;
+  if (!content) return { text: '', empty: true, tokens: 0 };
+  const text = `${READ_ATTENTION_HEADER}\n\n${fenceUntrusted(content, { source: 'path-memory' })}`;
+  const tokens = estimateTokens(text);
+  if (tokens > budgetTokens) return { text: '', empty: true, tokens: 0 };
+  return { text, empty: false, tokens };
+}
+
 /**
  * Assemble the bounded digest text. PURE. Never exceeds `budgetTokens` (delegated to
  * applyBudget). Empty inputs → { text: '', empty: true } so the caller injects nothing.
@@ -161,13 +244,18 @@ function buildMemoryDigest(data = {}, options = {}) {
   const ready = Array.isArray(data.ready) ? data.ready : [];
   const claimed = Array.isArray(data.claimed) ? data.claimed : [];
   const inbox = Array.isArray(data.inbox) ? data.inbox : [];
+  const budgetTokens = options.budgetTokens || DEFAULT_DIGEST_BUDGET_TOKENS;
 
   // Inbox (priority 5) is a THIRD section beside notes + issues; a fresh human directive
   // outranks stale notes (10) and the agent's own issue list (20) under budget pressure.
-  const sections = [inboxSection(inbox), notesSection(notes), issuesSection(ready, claimed)].filter(Boolean);
+  const sections = [
+    sessionSummarySection(claimed),
+    inboxSection(inbox),
+    ...notesSections(notes, budgetTokens),
+    issuesSection(ready, claimed),
+  ].filter(Boolean);
   if (!sections.length) return { text: '', empty: true, tokens: 0 };
 
-  const budgetTokens = options.budgetTokens || DEFAULT_DIGEST_BUDGET_TOKENS;
   const budgeted = applyBudget(sections, budgetTokens);
   const body = budgeted.sections
     .filter(section => section.content)
@@ -185,7 +273,10 @@ function buildMemoryDigest(data = {}, options = {}) {
 module.exports = {
   DEFAULT_DIGEST_BUDGET_TOKENS,
   DIGEST_HEADER,
+  READ_ATTENTION_HEADER,
+  SESSION_SUMMARY_REMINDER,
   buildMemoryDigest,
+  buildReadAttentionDigest,
   collectDigestData,
   extractIssues,
   // exported for focused reuse / tests

package/lib/memory-recall-events.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+const { spawn } = require('node:child_process');
+
+const { resolveKernelDatabasePath } = require('./kernel/cli-broker-factory');
+const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
+const projectMemory = require('./project-memory');
+
+const EVENT_TYPE = 'memory.recall.observed';
+const OUTCOMES = new Set(['selected', 'empty', 'filtered', 'unsupported', 'timeout', 'error']);
+const MAX_COUNT = 1_000_000;
+const MAX_SELECTED_IDS = 20;
+const MAX_MIX_KEYS = 10;
+const EVENT_WRITER = "const { recordMemoryRecallPayload } = require(process.argv[1]); recordMemoryRecallPayload(process.argv[2], JSON.parse(process.argv[3])).catch(() => {});";
+
+function boundedInteger(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(MAX_COUNT, Math.max(0, Math.trunc(value)));
+}
+
+function boundedString(value, maxLength) {
+  return String(value ?? '').slice(0, maxLength);
+}
+
+function boundedMix(mix) {
+  if (!mix || typeof mix !== 'object' || Array.isArray(mix)) return {};
+  return Object.fromEntries(
+    Object.entries(mix)
+      .slice(0, MAX_MIX_KEYS)
+      .map(([label, count]) => [boundedString(label, 64), boundedInteger(count)])
+      .filter(([label, count]) => label && count > 0)
+  );
+}
+
+function buildRecallEventPayload(observation = {}) {
+  const selectedIds = Array.isArray(observation.selectedIds)
+    ? observation.selectedIds
+      .slice(0, MAX_SELECTED_IDS)
+      .map(id => boundedString(id, 128))
+      .filter(Boolean)
+    : [];
+  return {
+    outcome: OUTCOMES.has(observation.outcome) ? observation.outcome : 'error',
+    counts: {
+      candidates: boundedInteger(observation.candidateCount),
+      eligible: boundedInteger(observation.eligibleCount),
+      selected: selectedIds.length,
+    },
+    selected_ids: selectedIds,
+    source_mix: boundedMix(observation.sourceMix),
+    trust_mix: boundedMix(observation.trustMix),
+    token_estimate: boundedInteger(observation.tokenEstimate),
+    elapsed_ms: boundedInteger(observation.elapsedMs),
+    harness: boundedString(observation.harness || 'unknown', 32),
+  };
+}
+
+function normalizeRecallEventPayload(payload = {}) {
+  return buildRecallEventPayload({
+    outcome: payload.outcome,
+    candidateCount: payload.counts?.candidates,
+    eligibleCount: payload.counts?.eligible,
+    selectedIds: payload.selected_ids,
+    sourceMix: payload.source_mix,
+    trustMix: payload.trust_mix,
+    tokenEstimate: payload.token_estimate,
+    elapsedMs: payload.elapsed_ms,
+    harness: payload.harness,
+  });
+}
+
+async function recordMemoryRecallEvent(projectRoot, observation = {}, options = {}) {
+  return recordMemoryRecallPayload(projectRoot, buildRecallEventPayload(observation), options);
+}
+
+async function recordMemoryRecallPayload(projectRoot, payload, options = {}) {
+  let store = options.store;
+  let ownsStore = false;
+  try {
+    const safePayload = normalizeRecallEventPayload(payload);
+    const projectId = options.projectId || projectMemory.resolveProjectId(projectRoot, options);
+    if (!store) {
+      store = createBuiltinSQLiteDriver({
+        databasePath: resolveKernelDatabasePath({
+          projectRoot,
+          gitCommonDir: options.gitCommonDir,
+          databasePath: options.databasePath,
+        }),
+      });
+      ownsStore = true;
+    }
+    const id = (options.randomUUID || randomUUID)();
+    const createdAt = options.now || new Date().toISOString();
+    await store.insertKernelEvent({
+      id,
+      entity_type: 'project',
+      entity_id: projectId,
+      event_type: EVENT_TYPE,
+      idempotency_key: id,
+      expected_revision: 0,
+      actor: 'forge',
+      origin: 'hook',
+      payload: safePayload,
+      created_at: createdAt,
+    });
+    return { recorded: true, eventId: id };
+  } catch (error) {
+    return {
+      recorded: false,
+      reason: error && error.message ? error.message : 'telemetry unavailable',
+    };
+  } finally {
+    if (ownsStore && store && typeof store.close === 'function') {
+      try {
+        store.close();
+      } catch {
+        // Best-effort evidence must never block recall.
+      }
+    }
+  }
+}
+
+function launchMemoryRecallEvent(projectRoot, observation = {}, options = {}) {
+  try {
+    const child = (options.spawn || spawn)(
+      process.execPath,
+      ['-e', EVENT_WRITER, __filename, projectRoot, JSON.stringify(buildRecallEventPayload(observation))],
+      { detached: true, stdio: 'ignore', windowsHide: true },
+    );
+    if (child && typeof child.on === 'function') child.on('error', () => {});
+    if (child && typeof child.unref === 'function') child.unref();
+    return { launched: true };
+  } catch {
+    return { launched: false };
+  }
+}
+
+module.exports = {
+  EVENT_TYPE,
+  buildRecallEventPayload,
+  launchMemoryRecallEvent,
+  recordMemoryRecallEvent,
+  recordMemoryRecallPayload,
+};

package/lib/memory-recall.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { fenceUntrusted } = require('./untrusted-content');
+
 /**
  * @module memory-recall
  *
@@ -50,6 +52,50 @@ function estimateTokens(text) {
   return Math.ceil(String(text || '').length / 4);
 }
 
+function normalizeMemoryType(entry) {
+  const tags = Array.isArray(entry?.tags) ? entry.tags : [];
+  const tagged = tags.find(tag => /^type:[a-z0-9][a-z0-9-]{0,63}$/i.test(tag));
+  if (tagged) return tagged.slice('type:'.length).toLowerCase();
+  const category = entry?.value && typeof entry.value === 'object'
+    ? entry.value.category
+    : null;
+  if (typeof category === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/i.test(category)) {
+    return category.toLowerCase();
+  }
+  return entry?.value && typeof entry.value === 'object' ? 'machine-record' : 'note';
+}
+
+function memoryTrustStatus(entry) {
+  const tags = Array.isArray(entry?.tags) ? entry.tags : [];
+  const normalizedTags = tags.map(tag => String(tag).toLowerCase());
+  if (normalizedTags.includes('trust:confirmed')) return 'confirmed';
+  if (normalizedTags.some(tag => tag.startsWith('trust:')
+    || tag === 'forge:auto-capture')) return 'suggested';
+  if (entry?.sourceAgent === 'forge remember (imported)') return 'suggested';
+  if (entry?.value && typeof entry.value === 'object') return 'suggested';
+  if (entry?.sourceAgent === 'forge remember' && typeof entry.value === 'string') return 'confirmed';
+  return 'suggested';
+}
+
+function normalizeRecallHit(entry, projectId) {
+  if (!entry) return null;
+  if (entry.memory_id) return entry;
+  const sourceRefs = Array.isArray(entry.beadsRefs) ? entry.beadsRefs : [];
+  return {
+    memory_id: entry.key,
+    type: normalizeMemoryType(entry),
+    content: typeof entry.value === 'string' ? entry.value : JSON.stringify(entry.value),
+    scope: !entry.scope || entry.scope === 'project' ? projectId : entry.scope,
+    trust_status: memoryTrustStatus(entry),
+    provenance: {
+      source_agent: entry.sourceAgent || '',
+      source_refs: sourceRefs,
+    },
+    updated_at: entry.timestamp,
+    score: entry.score,
+  };
+}
+
 /**
  * Parse the JSON payload Claude Code delivers on a UserPromptSubmit hook's stdin. Never
  * throws — any malformed input yields an empty prompt so the hook fails open.
@@ -99,7 +145,7 @@ function meaningfulTokens(query) {
  *
  * @param {object} args
  * @param {string} args.query — the submitted prompt
- * @param {Array<{key:string, value:string, score:number}>} args.hits — bm25-ordered
+ * @param {Array<{memory_id:string, content:string, score:number}>} args.hits — bm25-ordered
  *   (best/lowest score first), already relevance-only (token-AND matched)
  * @param {number} [args.scoreFloor] — keep only hits with score <= floor (more negative =
  *   stronger). Omit/null to rely on the FTS match alone. The VALUE is corpus-dependent and
@@ -116,28 +162,40 @@ function selectInjection({ query, hits, scoreFloor = null, tokenBudget = DEFAULT
 
   const exclude = new Set(excludeKeys || []);
   const lines = [];
+  const entries = [];
   const injectedKeys = [];
+  const usedSections = new Set();
   let spent = 0;
 
   for (const hit of hits || []) {
-    if (!hit || typeof hit.key !== 'string') continue;
-    if (exclude.has(hit.key)) continue;
+    const memoryId = hit?.memory_id ?? hit?.key;
+    if (typeof memoryId !== 'string') continue;
+    if (exclude.has(memoryId)) continue;
     // Relevance floor: below the bar contributes nothing. bm25 is more-negative-is-better.
     if (typeof scoreFloor === 'number' && !(typeof hit.score === 'number' && hit.score <= scoreFloor)) {
       continue;
     }
-    const body = String(hit.value == null ? '' : hit.value);
-    const cost = estimateTokens(body);
+    const body = String((hit.content ?? hit.value) == null ? '' : (hit.content ?? hit.value));
+    const trust = hit.trust_status === 'confirmed' ? 'confirmed' : 'suggested';
+    const source = String(hit.provenance?.source_agent || hit.sourceAgent || 'unknown').slice(0, 80);
+    const updated = String(hit.updated_at || hit.timestamp || 'unknown').slice(0, 40);
+    const labeled = `[trust=${trust} source=${source} updated=${updated}] ${body}`;
+    const line = fenceUntrusted(labeled, { source: 'memory' });
+    const heading = trust === 'confirmed'
+      ? 'Confirmed memory (project-local; provenance shown)'
+      : 'Suggested memory — verify before relying';
+    const cost = estimateTokens(line) + (usedSections.has(trust) ? 0 : estimateTokens(`${heading}\n`));
     if (spent + cost > tokenBudget) {
-      // Budget exhausted; stop rather than skip-and-continue so the strongest fit.
-      break;
+      continue;
     }
-    lines.push(body);
-    injectedKeys.push(hit.key);
+    lines.push(line);
+    entries.push({ trust, line });
+    injectedKeys.push(memoryId);
+    usedSections.add(trust);
     spent += cost;
   }
 
-  return { lines, injectedKeys };
+  return { lines, entries, injectedKeys };
 }
 
 module.exports = {
@@ -145,6 +203,9 @@ module.exports = {
   DEFAULT_TOKEN_BUDGET,
   DEFAULT_SCORE_FLOOR,
   estimateTokens,
+  memoryTrustStatus,
+  normalizeMemoryType,
+  normalizeRecallHit,
   parseHookInput,
   meaningfulTokens,
   selectInjection,