total-recall-brain 3.1.0

package/src/core/notifications.mjs

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { logger } from './logger.mjs';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Sends a macOS desktop notification using terminal-notifier if available,
+ * falling back to osascript.
+ *
+ * @param {string} title - The notification title
+ * @param {string} message - The notification message content
+ * @param {object} [options] - Additional parameters
+ * @param {string} [options.open] - Absolute path or URL to open on clicking "Open" or "Show"
+ * @param {string} [options.sound] - macOS sound name (e.g., 'Glass', 'Hero', 'Sosumi', 'default')
+ * @param {string} [options.subtitle] - Subtitle text to show
+ * @param {string} [options.group] - Group ID to allow notification replacement rather than stacking
+ */
+export async function sendSystemNotification(title, message, options = {}) {
+  // Bypassed in tests
+  const isTest = process.env.VITEST || process.env._TR_TEST_AGENT_DIR || process.env.NODE_ENV === 'test';
+  if (isTest) {
+    logger.debug('notifications: bypassing system notification in test environment');
+    return;
+  }
+
+  const {
+    open,
+    sound = 'default',
+    subtitle = 'Total Recall',
+    group = 'total-recall-system'
+  } = options;
+
+  // Sanitize inputs to prevent unexpected arguments/escaping issues
+  const cleanMessage = String(message).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 200);
+  const cleanTitle = String(title).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 100);
+  const cleanSubtitle = subtitle ? String(subtitle).replace(/[^ -~]/g, '').replace(/["'`$\\]/g, '').slice(0, 100) : '';
+
+  try {
+    // 1. Try terminal-notifier first (supports click actions, custom sounds, subtitles, grouping)
+    const args = [
+      '-title', cleanTitle,
+      '-message', cleanMessage,
+      '-group', group,
+    ];
+    if (cleanSubtitle) {
+      args.push('-subtitle', cleanSubtitle);
+    }
+    if (open) {
+      // Ensure file url is correct format or HTTP(S) URL
+      const openTarget = (open.startsWith('/') || open.startsWith('~')) ? `file://${open}` : open;
+      args.push('-open', openTarget);
+      args.push('-actions', 'Open');
+    }
+    if (sound && sound !== 'default') {
+      args.push('-sound', sound);
+    }
+
+    await execFileAsync('terminal-notifier', args, { timeout: 3000 });
+    logger.debug('notifications: successfully sent notification via terminal-notifier', { title, message });
+  } catch (err) {
+    // 2. Fall back to plain AppleScript display notification if terminal-notifier fails
+    try {
+      const appleScriptParts = [
+        `display notification "${cleanMessage.replace(/"/g, '\\"')}"`,
+        `with title "${cleanTitle.replace(/"/g, '\\"')}"`
+      ];
+      if (sound && sound !== 'default') {
+        appleScriptParts.push(`sound name "${sound}"`);
+      }
+      await execFileAsync('osascript', ['-e', appleScriptParts.join(' ')], { timeout: 3000 });
+      logger.debug('notifications: successfully sent fallback osascript notification', { title, message });
+    } catch (fallbackErr) {
+      logger.debug('notifications: both terminal-notifier and osascript failed', { err: fallbackErr.message });
+    }
+  }
+}

package/src/core/operation-validator.mjs

@@ -0,0 +1,272 @@
+import fs from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import crypto from 'node:crypto';
+import {
+  SSSS_SCHEMAS,
+  OperationEnvelopeSchema,
+  PatchEnvelopeSchema,
+  EventEnvelopeSchema,
+} from './schema.mjs';
+import { atomicWrite, safeStringify } from './vault.mjs';
+import { logger } from './logger.mjs';
+
+const APPEND_TYPES = new Set(['conversation', 'run']);
+const PROTOCOL_PATHS = [
+  'references/ssss-spec.md',
+  'references/admin-protocol-evolution-policy.md',
+  'references/user-local-optimizer-boundary-policy.md',
+];
+const PROTOCOL_PATH_PREFIXES = ['fixtures/'];
+const idempotencyCache = new Map();
+const IDEMPOTENCY_TTL_MS = 10 * 60 * 1000;
+const warmedVaults = new Set();
+
+function cacheKey(wid, key) { return `${wid}:${key}`; }
+
+function pruneExpired() {
+  const now = Date.now();
+  for (const [k, v] of idempotencyCache) {
+    if (now - v.ts > IDEMPOTENCY_TTL_MS) idempotencyCache.delete(k);
+  }
+}
+
+export function warmIdempotencyCache(vaultRoot, eventLogDir) {
+  const vaultKey = path.resolve(vaultRoot);
+  if (warmedVaults.has(vaultKey)) return;
+  warmedVaults.add(vaultKey);
+
+  const auditDir = eventLogDir || path.join(vaultRoot, '.events');
+  const auditFile = path.join(auditDir, 'audit.jsonl');
+  if (!fs.existsSync(auditFile)) return;
+
+  try {
+    const lines = fs.readFileSync(auditFile, 'utf8').split('\n');
+    const now = Date.now();
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const record = JSON.parse(line);
+        if (record.event_type !== 'audit' || !record.payload) continue;
+        const ts = Date.parse(record.ts);
+        if (isNaN(ts) || now - ts > IDEMPOTENCY_TTL_MS) continue;
+
+        const ck = cacheKey(record.payload.workspace_id, record.payload.idempotency_key);
+        const response = {
+          success: true,
+          type: record.payload.envelope_type,
+          operation_id: record.correlation_id,
+          path: record.subject,
+          committed_at: record.ts,
+          validation: {
+            valid: true,
+            type: record.payload.resolved_type,
+            errors: [],
+            warnings: []
+          }
+        };
+        idempotencyCache.set(ck, { response, ts });
+      } catch { /* skip corrupt lines */ }
+    }
+  } catch (err) {
+    logger.error('operation-validator', `Failed to warm idempotency cache: ${err.message}`);
+  }
+}
+
+function isProtocolPath(fp) {
+  for (const p of PROTOCOL_PATHS) if (fp === p || fp.endsWith(`/${p}`)) return true;
+  for (const prefix of PROTOCOL_PATH_PREFIXES) if (fp.startsWith(prefix) || fp.includes(`/${prefix}`)) return true;
+  if (fp.endsWith('schema.mjs') || fp.endsWith('schema.spec.mjs')) return true;
+  return false;
+}
+
+function buildRepair(zodError) {
+  return { field_errors: (zodError.issues || []).map(i => ({ field: i.path.join('.') || '(root)', issue: i.message })) };
+}
+
+function resolveVfsPath(vaultRoot, vfsPath) {
+  const cleaned = vfsPath.replace(/^\/+/, '');
+  const resolved = path.resolve(vaultRoot, cleaned);
+  if (!resolved.startsWith(path.resolve(vaultRoot))) throw new Error(`Path traversal: ${vfsPath}`);
+  return resolved;
+}
+
+function makeErrorResponse(type, opId, p, errors) {
+  return { success: false, type, operation_id: opId, path: p, committed_at: null, validation: { valid: false, errors, warnings: [] } };
+}
+
+/**
+ * Process an SSSS operation through the full §6.3 pipeline.
+ * @param {object} envelope - The operation envelope.
+ * @param {string} vaultRoot - Absolute path to the vault directory.
+ * @param {object} [options] - { agentRole, leaseStore, eventLogDir }
+ * @returns {object} OperationResponse (§6.4).
+ */
+export function processOperation(envelope, vaultRoot, options = {}) {
+  const { agentRole = 'admin', leaseStore, eventLogDir } = options;
+  const operationId = crypto.randomUUID();
+  const warnings = [];
+
+  // Stage 1: Envelope Validation
+  const schemaMap = { operation: OperationEnvelopeSchema, patch: PatchEnvelopeSchema, event: EventEnvelopeSchema };
+  const envSchema = schemaMap[envelope.type];
+  if (!envSchema) return makeErrorResponse(envelope.type || 'unknown', operationId, envelope.path || '', [`Unknown envelope type: ${envelope.type}`]);
+  const envResult = envSchema.safeParse(envelope);
+  if (!envResult.success) return { ...makeErrorResponse(envelope.type, operationId, envelope.path || '', envResult.error.issues.map(i => `${i.path.join('.')}: ${i.message}`)), repair: buildRepair(envResult.error) };
+
+  // Warm idempotency cache from audit logs if not already done
+  warmIdempotencyCache(vaultRoot, eventLogDir);
+
+  // Stage 2: Idempotency
+  pruneExpired();
+  const ck = cacheKey(envelope.workspace_id, envelope.idempotency_key);
+  const cached = idempotencyCache.get(ck);
+  if (cached) return { ...cached.response, replay: cached.response };
+
+  // Stage 3: Authorization
+  if (isProtocolPath(envelope.path) && agentRole !== 'admin') return makeErrorResponse(envelope.type, operationId, envelope.path, [`Protocol path '${envelope.path}' requires admin role.`]);
+
+  // Stage 4: Lease Check
+  if (leaseStore) {
+    const lc = checkLease(envelope, leaseStore);
+    if (!lc.ok) return makeErrorResponse(envelope.type, operationId, envelope.path, [lc.error]);
+  }
+
+  // Stage 5: Content Validation
+  let resolvedType = null;
+  const errors = [];
+
+  if (envelope.type === 'operation' || envelope.type === 'patch') {
+    try {
+      let fmData;
+      if (envelope.type === 'operation') {
+        fmData = matter(envelope.content).data;
+      } else {
+        const absPath = resolveVfsPath(vaultRoot, envelope.path);
+        if (!fs.existsSync(absPath)) { errors.push(`Target file does not exist for patch: ${envelope.path}`); }
+        else {
+          const { data, content: body } = matter(fs.readFileSync(absPath, 'utf8'));
+          fmData = { ...data, ...envelope.patches };
+          if (envelope.patches.__body__ !== undefined && APPEND_TYPES.has(data.type)) {
+            const eb = body.trim(), nb = String(envelope.patches.__body__).trim();
+            if (eb && !nb.startsWith(eb)) errors.push(`Append-type '${data.type}' does not allow rewriting existing records.`);
+          }
+        }
+      }
+      if (fmData && errors.length === 0) {
+        resolvedType = fmData.type;
+        if (!resolvedType) errors.push('Missing required frontmatter field: type');
+        else if (!SSSS_SCHEMAS[resolvedType]) errors.push(`Unknown SSSS type: '${resolvedType}'.`);
+        else {
+          const r = SSSS_SCHEMAS[resolvedType].safeParse(fmData);
+          if (!r.success) r.error.issues.forEach(i => errors.push(`${i.path.join('.')}: ${i.message}`));
+          if (envelope.type === 'operation' && APPEND_TYPES.has(resolvedType)) {
+            const ap = resolveVfsPath(vaultRoot, envelope.path);
+            if (fs.existsSync(ap)) {
+              const eb = matter(fs.readFileSync(ap, 'utf8')).content.trim();
+              const nb = matter(envelope.content).content.trim();
+              if (eb && !nb.startsWith(eb)) errors.push(`Append-type '${resolvedType}' does not allow rewriting existing records.`);
+            }
+          }
+          if (agentRole === 'optimizer' && resolvedType === 'memory') {
+            if (fmData.priority === 'absolute') warnings.push('Optimizer writing Tier 1 (priority: absolute) node.');
+            if (fmData.immutable === true) warnings.push('Optimizer writing immutable node.');
+          }
+          if (resolvedType === 'schema-proposal' && fmData.status === 'accepted') {
+            if (agentRole !== 'admin') errors.push('Only admin may accept schema-proposals.');
+            if (!fmData.reviewed_by) errors.push('Accepted schema-proposals must have reviewed_by.');
+          }
+        }
+      }
+    } catch (err) { errors.push(`Content parsing error: ${err.message}`); }
+  }
+  if (envelope.type === 'event') { try { JSON.parse(envelope.content); } catch { errors.push('Event content must be valid JSON.'); } }
+
+  const isValid = errors.length === 0;
+  if (envelope.dry_run || !isValid) {
+    const resp = { success: isValid, type: envelope.type, operation_id: operationId, path: envelope.path, committed_at: null, dry_run: !!envelope.dry_run, validation: { valid: isValid, type: resolvedType, errors, warnings } };
+    if (!isValid) resp.repair = { field_errors: errors.map(e => ({ field: e.split(': ')[0] || '(unknown)', issue: e })) };
+    return resp;
+  }
+
+  // Stage 6: Commit
+  const committedAt = new Date().toISOString();
+  try {
+    const absPath = resolveVfsPath(vaultRoot, envelope.path);
+    const dir = path.dirname(absPath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    if (envelope.type === 'operation') {
+      let contentToWrite = envelope.content;
+      try {
+        const parsed = matter(contentToWrite);
+        if (parsed.data && parsed.data.type === 'memory') {
+          parsed.data.updated = committedAt;
+          parsed.data.last_accessed = committedAt;
+          contentToWrite = safeStringify(parsed.content, parsed.data);
+        }
+      } catch {
+        // Fallback to raw content if parsing fails
+      }
+      atomicWrite(absPath, contentToWrite);
+    }
+    else if (envelope.type === 'patch') {
+      const { data, content: body } = matter(fs.readFileSync(absPath, 'utf8'));
+      const merged = { ...data };
+      for (const [k, v] of Object.entries(envelope.patches)) { if (k !== '__body__') merged[k] = v; }
+      if (merged.type === 'memory') {
+        merged.updated = committedAt;
+        merged.last_accessed = committedAt;
+      }
+      const newBody = envelope.patches.__body__ !== undefined ? (APPEND_TYPES.has(data.type) ? body + '\n' + envelope.patches.__body__ : envelope.patches.__body__) : body;
+      atomicWrite(absPath, safeStringify(newBody, merged));
+    } else if (envelope.type === 'event') {
+      const logDir = eventLogDir || path.join(vaultRoot, '.events');
+      if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+      fs.appendFileSync(path.join(logDir, `${envelope.workspace_id}.jsonl`), JSON.stringify({ event_id: operationId, event_type: 'operation-audit', ts: committedAt, path: envelope.path, content: envelope.content, idempotency_key: envelope.idempotency_key }) + '\n');
+    }
+  } catch (err) {
+    logger.error('operation-validator', `Commit failed: ${err.message}`);
+    return makeErrorResponse(envelope.type, operationId, envelope.path, [`Commit failed: ${err.message}`]);
+  }
+
+  // Stage 7: Audit
+  try {
+    const auditDir = eventLogDir || path.join(vaultRoot, '.events');
+    if (!fs.existsSync(auditDir)) fs.mkdirSync(auditDir, { recursive: true });
+    fs.appendFileSync(path.join(auditDir, 'audit.jsonl'), JSON.stringify({ event_id: crypto.randomUUID(), event_type: 'audit', correlation_id: operationId, ts: committedAt, subject: envelope.path, payload: { envelope_type: envelope.type, idempotency_key: envelope.idempotency_key, workspace_id: envelope.workspace_id, agent_role: agentRole, resolved_type: resolvedType } }) + '\n');
+  } catch (err) { logger.error('operation-validator', `Audit failed: ${err.message}`); }
+
+  const response = { success: true, type: envelope.type, operation_id: operationId, path: envelope.path, committed_at: committedAt, validation: { valid: true, type: resolvedType, errors: [], warnings } };
+  idempotencyCache.set(ck, { response, ts: Date.now() });
+  return response;
+}
+
+function checkLease(envelope, leaseStore) {
+  const lp = path.join(leaseStore, envelope.workspace_id, `${envelope.path.replace(/\//g, '__')}.lease.json`);
+  if (!fs.existsSync(lp)) return { ok: true };
+  try {
+    const lease = JSON.parse(fs.readFileSync(lp, 'utf8'));
+    if (new Date(lease.expires_at) < new Date()) { fs.unlinkSync(lp); return { ok: true }; }
+    if (!envelope.lease_id) return { ok: false, error: `Path '${envelope.path}' is leased (${lease.lease_id}). Supply lease_id.` };
+    if (envelope.lease_id !== lease.lease_id) return { ok: false, error: `Lease mismatch: got '${envelope.lease_id}', expected '${lease.lease_id}'.` };
+    return { ok: true };
+  } catch { try { fs.unlinkSync(lp); } catch { } return { ok: true }; }
+}
+
+export function acquireLease(workspaceId, vfsPath, leaseStore, ttlMs = 30000) {
+  const dir = path.join(leaseStore, workspaceId);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const lp = path.join(dir, `${vfsPath.replace(/\//g, '__')}.lease.json`);
+  if (fs.existsSync(lp)) { try { const e = JSON.parse(fs.readFileSync(lp, 'utf8')); if (new Date(e.expires_at) >= new Date()) return { error: `Path '${vfsPath}' already leased.` }; } catch { } }
+  const leaseId = crypto.randomUUID();
+  const expiresAt = new Date(Date.now() + ttlMs).toISOString();
+  fs.writeFileSync(lp, JSON.stringify({ lease_id: leaseId, path: vfsPath, workspace_id: workspaceId, expires_at: expiresAt }, null, 2));
+  return { lease_id: leaseId, expires_at: expiresAt };
+}
+
+export function releaseLease(workspaceId, vfsPath, leaseId, leaseStore) {
+  const lp = path.join(leaseStore, workspaceId, `${vfsPath.replace(/\//g, '__')}.lease.json`);
+  if (!fs.existsSync(lp)) return { released: true };
+  try { const e = JSON.parse(fs.readFileSync(lp, 'utf8')); if (e.lease_id !== leaseId) return { error: 'Lease ID mismatch.' }; fs.unlinkSync(lp); return { released: true }; }
+  catch (err) { return { error: err.message }; }
+}

package/src/core/optimizer.mjs

@@ -0,0 +1,330 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import matter from 'gray-matter';
+import { loadNodes, writeNode } from './vault.mjs';
+import { logger } from './logger.mjs';
+import { brainDir } from './config.mjs';
+
+/**
+ * Total Recall Optimizer
+ * Instead of mutating memory directly, the optimizer generates Proposals.
+ * Proposals must pass a local evaluation gate before being accepted.
+ */
+
+export function createProposal(category, summary, targetPath = null, rationale = '') {
+  const proposalId = `prop_${crypto.randomBytes(6).toString('hex')}`;
+  return {
+    type: 'proposal',
+    proposal_id: proposalId,
+    category,
+    status: 'draft',
+    target_path: targetPath,
+    summary,
+    rationale,
+    proposed_by: 'kernel_optimizer_v1',
+    proposed_at: new Date().toISOString(),
+  };
+}
+
+/**
+ * Scans the vault for duplicate or contradictory memories and generates a cleanup proposal.
+ */
+export async function generateMemoryCleanupProposals(vaultDir) {
+  const nodes = loadNodes(vaultDir);
+  const proposals = [];
+  
+  // Simple heuristic: find nodes with the same predicate and object but different subjects, or duplicate subjects.
+  // In a real system, we would use local LLM / embeddings to find semantic duplicates.
+  const conceptMap = new Map();
+  
+  for (const node of nodes) {
+    if (node.type !== 'memory') continue;
+    const key = `${node.predicate}:${node.object}`;
+    if (!conceptMap.has(key)) {
+      conceptMap.set(key, []);
+    }
+    conceptMap.get(key).push(node);
+  }
+  
+  for (const [key, similarNodes] of conceptMap.entries()) {
+    if (similarNodes.length > 1) {
+      const paths = similarNodes.map(n => n.slug).join(', ');
+      const proposal = createProposal(
+        'memory-cleanup',
+        `Merge similar memory nodes for concept [${key}]`,
+        paths,
+        `Detected ${similarNodes.length} nodes with identical predicate:object signatures. Merging them will reduce fragmentation.`
+      );
+      proposals.push(proposal);
+    }
+  }
+  
+  return proposals;
+}
+
+/**
+ * Scans skill execution logs (if available) and proposes improvements.
+ */
+/**
+ * Scan skill files for quality issues and propose improvements.
+ * Looks at skill files that haven't been updated in >30 days and
+ * checks for common issues: missing examples, vague instructions, outdated commands.
+ */
+export async function generateSkillImprovementProposals(vaultDir) {
+  const agentDir = path.join(path.dirname(vaultDir));
+  const skillsDir = path.join(agentDir, 'skills');
+  const proposals = [];
+
+  if (!fs.existsSync(skillsDir)) return proposals;
+
+  const now = Date.now();
+  const staleCutoff = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+  try {
+    const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => path.join(skillsDir, d.name, 'SKILL.md'))
+      .filter(p => fs.existsSync(p));
+
+    for (const skillFile of skillDirs) {
+      const stat = fs.statSync(skillFile);
+      const ageMs = now - stat.mtimeMs;
+      if (ageMs < staleCutoff) continue;
+
+      const raw = fs.readFileSync(skillFile, 'utf8');
+      const hasExamples = /##\s*example/i.test(raw);
+      const hasCaution = /caution|warning|never|must not/i.test(raw);
+      const lineCount = raw.split('\n').length;
+
+      const issues = [];
+      if (!hasExamples) issues.push('No examples section');
+      if (!hasCaution) issues.push('No caution/constraint section');
+      if (lineCount < 20) issues.push('Very short — may lack detail');
+
+      if (issues.length > 0) {
+        const skillName = path.basename(path.dirname(skillFile));
+        proposals.push(createProposal(
+          'skill-improvement',
+          `Improve skill: ${skillName} (${issues.join(', ')})`,
+          skillFile,
+          `Skill file is ${Math.floor(ageMs / 86400000)} days old. Issues: ${issues.join('; ')}`,
+        ));
+      }
+    }
+  } catch (err) {
+    logger.debug('optimizer: generateSkillImprovementProposals failed to read skillsDir', { err: err.message });
+  }
+
+  return proposals;
+}
+
+/**
+ * Scan the task queue for stuck or stalled workflows.
+ * Tasks that have been 'in-progress' for >1 hour are considered stalled.
+ */
+export async function generateWorkflowRepairProposals(vaultDir) {
+  const queueDir = path.join(brainDir, 'scheduler', 'queue');
+  const proposals = [];
+
+  if (!fs.existsSync(queueDir)) return proposals;
+
+  const now = Date.now();
+  const stalledCutoff = 60 * 60 * 1000; // 1 hour
+
+  try {
+    const files = fs.readdirSync(queueDir).filter(f => f.endsWith('.md'));
+    for (const file of files) {
+      const raw = fs.readFileSync(path.join(queueDir, file), 'utf8');
+      const { data } = matter(raw);
+      if (data.status !== 'in-progress') continue;
+
+      const updatedAt = new Date(data.updated_at || data.created || 0).getTime();
+      if (now - updatedAt < stalledCutoff) continue;
+
+      proposals.push(createProposal(
+        'workflow-repair',
+        `Stalled task: ${data.slug || file}`,
+        path.join(queueDir, file),
+        `Task has been in-progress for ${Math.floor((now - updatedAt) / 60000)} minutes. May need retry or cancellation.`,
+      ));
+    }
+  } catch (err) {
+    logger.debug('optimizer: generateWorkflowRepairProposals failed to read queueDir', { err: err.message });
+  }
+
+  return proposals;
+}
+
+/**
+ * Analyze the vault's model usage patterns and propose routing improvements.
+ * Flags cases where high-priority tasks were sent to the local LLM
+ * that should have used a frontier model.
+ */
+export async function generateModelRoutingProposals(vaultDir) {
+  const proposals = [];
+  const nodes = loadNodes(vaultDir);
+
+  // Find high-importance facts with low confidence — likely needed frontier model
+  const underconfident = nodes.filter(n =>
+    n.status === 'active' &&
+    n.category === 'facts' &&
+    n.importance >= 4 &&
+    n.confidence < 0.6 &&
+    n.source?.agent === 'fact-seeker',
+  );
+
+  for (const node of underconfident.slice(0, 5)) {
+    proposals.push(createProposal(
+      'model-routing',
+      `Re-research with frontier model: "${node.title}"`,
+      node.slug,
+      `High-importance fact (importance: ${node.importance}) has low confidence (${node.confidence}). Originally researched by local model. Frontier model may produce better synthesis.`,
+    ));
+  }
+
+  return proposals;
+}
+
+export async function generateStaleKnowledgeRefreshProposals(vaultDir) {
+  const nodes = loadNodes(vaultDir);
+  const proposals = [];
+  
+  const now = Date.now();
+  const ONE_MONTH_MS = 30 * 24 * 60 * 60 * 1000;
+  
+  for (const node of nodes) {
+    if (node.type === 'memory' && node.last_accessed) {
+      const lastAccessed = new Date(node.last_accessed).getTime();
+      if (now - lastAccessed > ONE_MONTH_MS && node.importance > 3) {
+        proposals.push(createProposal(
+          'stale-knowledge-refresh',
+          `Refresh stale high-importance memory: ${node.title}`,
+          node.slug,
+          `Node has not been accessed in over 30 days but maintains high importance. Requires verification against current state.`
+        ));
+      }
+    }
+  }
+  
+  return proposals;
+}
+
+/**
+ * Local Eval Gate for Proposal Promotion
+ * Uses the local runtime to evaluate the validity of a proposal.
+ */
+export async function evaluateProposalGate(proposal, runtimeConfig) {
+  // In a production scenario, this calls the local LLM runtime to grade the proposal.
+  // For now, we simulate the evaluation gate based on deterministic rules or simple heuristics.
+  if (proposal.category === 'memory-cleanup' && proposal.rationale.includes('identical predicate:object')) {
+    proposal.status = 'accepted';
+    proposal.reviewed_at = new Date().toISOString();
+    proposal.reviewed_by = 'local_eval_gate';
+    return true;
+  }
+  
+  if (proposal.category === 'stale-knowledge-refresh') {
+    proposal.status = 'accepted';
+    proposal.reviewed_at = new Date().toISOString();
+    proposal.reviewed_by = 'local_eval_gate';
+    return true;
+  }
+  
+  proposal.status = 'rejected';
+  proposal.rejection_reason = 'Failed to meet minimum evaluation threshold for automatic promotion.';
+  proposal.reviewed_at = new Date().toISOString();
+  proposal.reviewed_by = 'local_eval_gate';
+  return false;
+}
+
+// ─── Smart Decay ────────────────────────────────────────────────────────────────
+
+const DECAY_SYSTEM = `You are a Memory Retention Analyst for a sovereign AI memory system.
+
+Given a memory node that has not been accessed recently, evaluate whether it should be:
+1. RETAINED — still relevant and valuable
+2. ARCHIVED — no longer active but worth keeping as historical record
+3. DECAYED — safe to archive with low confidence flag
+
+Output valid JSON:
+{
+  "verdict": "RETAINED" | "ARCHIVED" | "DECAYED",
+  "confidence_adjustment": -0.2 to 0.0,
+  "reasoning": "string"
+}
+
+Criteria:
+- RETAINED: Foundational principles, architectural decisions, active rules
+- ARCHIVED: Historical context, superseded patterns, solved problems
+- DECAYED: Temporary workarounds, version-specific hacks, stale configs
+
+Output ONLY valid JSON.`;
+
+/**
+ * LLM-powered Smart Decay — evaluates each node individually rather than
+ * applying blind half-life. Produces decay proposals for the optimizer gate.
+ *
+ * @param {string} vaultDir
+ * @param {object} runtimeConfig
+ * @param {number} [ageThresholdDays=60]  Minimum age before considering decay
+ * @returns {object[]} decay proposals
+ */
+export async function runSmartDecay(vaultDir, runtimeConfig, ageThresholdDays = 60) {
+  const { callLocalRuntime } = await import('./runtime.mjs');
+  const nodes = loadNodes(vaultDir);
+  const now = Date.now();
+  const ageThresholdMs = ageThresholdDays * 24 * 60 * 60 * 1000;
+  const proposals = [];
+
+  // Candidates: active, not absolute priority, not accessed recently
+  const candidates = nodes.filter(n => {
+    if (n.status !== 'active') return false;
+    if (n.priority === 'absolute') return false;
+    if (n.importance >= 5) return false;
+    const lastAccessed = new Date(n.last_accessed || n.updated || 0).getTime();
+    return (now - lastAccessed) > ageThresholdMs;
+  });
+
+  // Process up to 5 candidates per run to avoid excessive LLM calls
+  const batch = candidates.slice(0, 5);
+
+  for (const node of batch) {
+    const ageDays = Math.floor((now - new Date(node.last_accessed || node.updated || 0).getTime()) / (1000 * 60 * 60 * 24));
+
+    const prompt = [
+      `## Memory Node: ${node.slug}`,
+      `Title: "${node.title}"`,
+      `Category: ${node.category} | Importance: ${node.importance} | Age: ${ageDays} days`,
+      `Tags: ${(node.tags || []).join(', ')}`,
+      '',
+      '## Body',
+      (node.body || '').slice(0, 800),
+      '',
+      `This node has not been accessed in ${ageDays} days. Should it be retained, archived, or decayed?`,
+    ].join('\n');
+
+    try {
+      const rawResponse = await callLocalRuntime(prompt, DECAY_SYSTEM, runtimeConfig);
+      const jsonMatch = rawResponse.match(/\{[\s\S]*\}/);
+      if (!jsonMatch) continue;
+
+      const result = JSON.parse(jsonMatch[0]);
+      const verdict = result.verdict || 'RETAINED';
+
+      if (verdict !== 'RETAINED') {
+        proposals.push(createProposal(
+          'smart-decay',
+          `Smart Decay [${verdict}]: "${node.title}"`,
+          node.slug,
+          `Age: ${ageDays} days. Reasoning: ${result.reasoning || 'No reasoning provided.'} Confidence adjustment: ${result.confidence_adjustment || 0}`,
+        ));
+      }
+    } catch {
+      // Skip failed evaluations silently
+    }
+  }
+
+  return proposals;
+}
+