@fyso/awareness-framework 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyso/awareness-framework",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Methodology and helper CLI for agent awareness, initialization, daily worklogs, handoffs, and evaluation loops.",
   "type": "module",
   "author": "Fyso",

package/src/cli.js

@@ -18,7 +18,7 @@ export function runCli(argv, options = {}) {
 
   try {
     const parsed = parseArgs(argv);
-    const [command, subcommand] = parsed.positionals;
+    const [command, subcommand, ...positionRest] = parsed.positionals;
 
     if (!command || command === 'help' || parsed.opts.help) {
       printHelp(ctx);
@@ -42,6 +42,16 @@ export function runCli(argv, options = {}) {
         return handoffCommand(ctx, parsed.opts);
       case 'evaluate':
         return evaluateCommand(ctx, parsed.opts);
+      case 'memory':
+        return memoryCommand(ctx, subcommand, parsed.opts);
+      case 'remember':
+        return rememberCommand(ctx, parsed.opts);
+      case 'recall':
+        return recallCommand(ctx, [subcommand, ...positionRest].filter(Boolean).join(' '), parsed.opts);
+      case 'forget':
+        return forgetCommand(ctx, parsed.opts);
+      case 'improve':
+        return improveCommand(ctx, parsed.opts);
       case 'hook':
         return hookCommand(ctx, subcommand, parsed.opts);
       case 'schedule':
@@ -108,6 +118,14 @@ Usage:
   awareness log --task ID --summary TEXT --changes TEXT [--context TEXT] [--state STATE] [--evidence TEXT] [--next TEXT] [--home PATH]
   awareness handoff [--home PATH]
   awareness evaluate [--home PATH] [--force] [--print]
+  awareness memory candidates [--home PATH]
+  awareness memory review [--min-count N] [--home PATH]
+  awareness memory note --text TEXT [--evidence TEXT] [--home PATH]
+  awareness memory promote --kind preference|pattern|project|review --text TEXT --evidence TEXT [--home PATH]
+  awareness remember --text TEXT --evidence TEXT [--home PATH]
+  awareness recall QUERY [--limit N] [--home PATH]
+  awareness forget --text TEXT --reason TEXT --evidence TEXT [--home PATH]
+  awareness improve [--force] [--min-count N] [--home PATH]
   awareness hook run --event EVENT [--tool TOOL] [--quiet] [--home PATH]
   awareness hook install --tool codex|claude|opencode|all [--command CMD] [--home PATH] [--user-home PATH] [--config-home PATH] [--overwrite]
   awareness schedule run --cadence hourly|daily [--home PATH]
@@ -146,7 +164,7 @@ function initCommand(ctx, opts) {
   writeIfMissing(path.join(home, 'memory', 'personality.md'), readTemplate('personality.md'), created, existing);
   writeIfMissing(path.join(home, 'memory', 'preferences.md'), privateMemorySeed('Preferences'), created, existing);
   writeIfMissing(path.join(home, 'memory', 'patterns.md'), privateMemorySeed('Patterns'), created, existing);
-  writeIfMissing(path.join(home, 'memory', 'long-term.md'), readTemplate('memory-long-term.md'), created, existing);
+  writeIfMissing(longTermMemoryPath(home), readTemplate('memory-long-term.md'), created, existing);
 
   if (opts.wrappers) {
     writeWrappers({
@@ -335,7 +353,212 @@ function evaluateCommand(ctx, opts) {
 
   ensureDir(path.dirname(evaluationPath));
   fs.writeFileSync(evaluationPath, content);
+  const candidates = recordEvaluationMemoryCandidates(home, today);
   out(ctx, `Evaluation written: ${evaluationPath}`);
+  out(ctx, `Memory candidates: ${candidates.length ? `${candidates.length} recorded` : 'none'}`);
+  return 0;
+}
+
+function memoryCommand(ctx, subcommand, opts) {
+  const home = agentsHome(ctx, opts);
+  ensurePrivateState(home, ctx);
+
+  switch (subcommand) {
+    case 'candidates':
+    case undefined:
+      return memoryCandidatesCommand(ctx, home);
+    case 'review':
+      return memoryReviewCommand(ctx, home, opts);
+    case 'note':
+      return memoryNoteCommand(ctx, home, opts);
+    case 'promote':
+      return memoryPromoteCommand(ctx, home, opts);
+    default:
+      err(ctx, `Unknown memory command: ${subcommand}`);
+      err(ctx, 'Use: candidates, review, note, or promote.');
+      return 1;
+  }
+}
+
+function memoryCandidatesCommand(ctx, home) {
+  const content = fs.readFileSync(longTermMemoryPath(home), 'utf8');
+  out(ctx, 'Promotion Candidates');
+  out(ctx, extractSection(content, 'Promotion Candidates').trim() || '- None yet.');
+  return 0;
+}
+
+function memoryReviewCommand(ctx, home, opts) {
+  const minCount = Number.parseInt(opts.minCount || '2', 10);
+  if (!Number.isInteger(minCount) || minCount < 2) {
+    throw new Error('Invalid --min-count. Use an integer >= 2.');
+  }
+
+  const content = fs.readFileSync(longTermMemoryPath(home), 'utf8');
+  const suggestions = repeatedMemoryCandidateSuggestions(content, minCount);
+  out(ctx, 'Memory Review');
+
+  if (!suggestions.length) {
+    out(ctx, `- No repeated candidates found with min-count ${minCount}.`);
+    return 0;
+  }
+
+  for (const suggestion of suggestions) {
+    out(ctx, `- Suggested pattern (${suggestion.count} observations): ${suggestion.text}`);
+    out(ctx, `  Evidence: ${suggestion.evidence}`);
+    out(ctx, `  Promote: awareness memory promote --kind pattern --text "${shellQuoteText(suggestion.text)}" --evidence "${shellQuoteText(suggestion.evidence)}"`);
+  }
+  return 0;
+}
+
+function memoryNoteCommand(ctx, home, opts) {
+  const text = required(opts, 'text');
+  const evidence = opts.evidence || 'Manual observation';
+  const today = todayParts(ctx);
+  const added = appendMemoryCandidate(home, today, text, evidence);
+  out(ctx, added ? `Memory candidate recorded: ${text}` : `Memory candidate already exists: ${text}`);
+  return 0;
+}
+
+function memoryPromoteCommand(ctx, home, opts) {
+  const kind = required(opts, 'kind');
+  const text = required(opts, 'text');
+  const evidence = required(opts, 'evidence');
+  const section = memoryPromotionSection(kind);
+  const today = todayParts(ctx);
+  const file = longTermMemoryPath(home);
+  let content = fs.readFileSync(file, 'utf8');
+  content = replaceMetadata(content, 'Updated', formatTimestamp(today));
+  content = appendToSection(content, section, `- ${today.date}: ${text} (evidence: ${evidence})\n`);
+  fs.writeFileSync(file, content);
+  appendMemoryEvent(home, today, {
+    type: 'memory.promoted',
+    kind,
+    section,
+    text,
+    evidence,
+  });
+  out(ctx, `Memory promoted to ${section}: ${text}`);
+  return 0;
+}
+
+function memoryPromotionSection(kind) {
+  const sections = {
+    preference: 'Preferences',
+    pattern: 'Patterns',
+    project: 'Project Conventions',
+    review: 'Review Guidance',
+  };
+  if (!sections[kind]) {
+    throw new Error(`Invalid memory kind: ${kind}. Valid kinds: ${Object.keys(sections).join(', ')}`);
+  }
+  return sections[kind];
+}
+
+function rememberCommand(ctx, opts) {
+  const home = agentsHome(ctx, opts);
+  ensurePrivateState(home, ctx);
+  const text = required(opts, 'text');
+  const evidence = required(opts, 'evidence');
+  const today = todayParts(ctx);
+  const added = appendMemoryCandidate(home, today, text, evidence, 'remember');
+  out(ctx, added ? `Remembered candidate: ${text}` : `Memory candidate already exists: ${text}`);
+  return 0;
+}
+
+function recallCommand(ctx, query, opts) {
+  const home = agentsHome(ctx, opts);
+  ensurePrivateState(home, ctx);
+  const search = opts.query || query;
+  if (!search || search === true) {
+    throw new Error('Missing recall query. Use: awareness recall QUERY');
+  }
+  const limit = Number.parseInt(opts.limit || '10', 10);
+  if (!Number.isInteger(limit) || limit < 1) {
+    throw new Error('Invalid --limit. Use an integer >= 1.');
+  }
+
+  const results = recallMatches(home, search, limit);
+  out(ctx, `Recall Results (${results.length})`);
+  if (!results.length) {
+    out(ctx, '- No matches.');
+    return 0;
+  }
+
+  for (const result of results) {
+    out(ctx, `- ${displayPath(home, result.file)}:${result.line}: ${result.text}`);
+  }
+  return 0;
+}
+
+function forgetCommand(ctx, opts) {
+  const home = agentsHome(ctx, opts);
+  ensurePrivateState(home, ctx);
+  const text = required(opts, 'text');
+  const reason = required(opts, 'reason');
+  const evidence = required(opts, 'evidence');
+  const today = todayParts(ctx);
+  const file = longTermMemoryPath(home);
+  let content = fs.readFileSync(file, 'utf8');
+  content = replaceMetadata(content, 'Updated', formatTimestamp(today));
+  content = appendToSection(content, 'Pruned Or Revised', `- ${today.date}: ${text} (reason: ${reason}; evidence: ${evidence})\n`);
+  fs.writeFileSync(file, content);
+  appendMemoryEvent(home, today, {
+    type: 'memory.pruned',
+    text,
+    reason,
+    evidence,
+  });
+  out(ctx, `Memory pruned or revised: ${text}`);
+  return 0;
+}
+
+function improveCommand(ctx, opts) {
+  const home = agentsHome(ctx, opts);
+  ensurePrivateState(home, ctx);
+  const today = todayParts(ctx);
+  const evaluationPath = path.join(home, 'evaluations', `${today.date}.md`);
+  const force = Boolean(opts.force);
+  const minCount = Number.parseInt(opts.minCount || '2', 10);
+
+  if (!Number.isInteger(minCount) || minCount < 2) {
+    throw new Error('Invalid --min-count. Use an integer >= 2.');
+  }
+
+  let evaluation;
+  if (force && fs.existsSync(evaluationPath)) {
+    fs.writeFileSync(evaluationPath, buildEvaluation(home, today));
+    const candidates = recordEvaluationMemoryCandidates(home, today);
+    evaluation = { file: evaluationPath, status: 'rewritten', candidates };
+  } else {
+    evaluation = writeEvaluationIfMissing(home, today);
+  }
+
+  if (evaluation.status === 'written' || evaluation.status === 'rewritten') {
+    appendMemoryEvent(home, today, {
+      type: 'evaluation.created',
+      file: evaluation.file,
+      status: evaluation.status,
+    });
+  }
+
+  const content = fs.readFileSync(longTermMemoryPath(home), 'utf8');
+  const suggestions = repeatedMemoryCandidateSuggestions(content, minCount);
+  for (const suggestion of suggestions) {
+    appendMemoryEvent(home, today, {
+      type: 'pattern.suggested',
+      text: suggestion.text,
+      count: suggestion.count,
+      evidence: suggestion.evidence,
+    });
+  }
+
+  out(ctx, `Evaluation: ${evaluation.status} (${evaluation.file})`);
+  out(ctx, `Memory candidates: ${evaluation.candidates ? evaluation.candidates.length : 'not changed'}`);
+  out(ctx, `Pattern suggestions: ${suggestions.length}`);
+  for (const suggestion of suggestions) {
+    out(ctx, `- ${suggestion.text} (${suggestion.count} observations)`);
+    out(ctx, `  Promote: awareness memory promote --kind pattern --text "${shellQuoteText(suggestion.text)}" --evidence "${shellQuoteText(suggestion.evidence)}"`);
+  }
   return 0;
 }
 
@@ -434,6 +657,11 @@ function hookCommand(ctx, subcommand, opts) {
   }
 }
 
+// Events whose stdout the host agent injects into its context. For these we
+// always emit the Current Focus so the agent actually loads the protocol state,
+// even under --quiet (which only suppresses diagnostic noise, not the payload).
+const CONTEXT_INJECTION_EVENTS = new Set(['session-start', 'post-compact']);
+
 function hookRunCommand(ctx, opts) {
   const home = agentsHome(ctx, opts);
   const today = todayParts(ctx);
@@ -455,9 +683,27 @@ function hookRunCommand(ctx, opts) {
     out(ctx, warnings.length ? `Warnings: ${warnings.length}` : 'Warnings: none');
   }
 
+  if (CONTEXT_INJECTION_EVENTS.has(event)) {
+    emitFocusContext(ctx, home);
+  }
+
   return 0;
 }
 
+// Print the Current Focus as injectable context for the host agent. Framed as
+// an instruction so the agent treats it as actionable, not background noise.
+function emitFocusContext(ctx, home) {
+  const currentPath = awarenessPath(home);
+  if (!fs.existsSync(currentPath)) return;
+  const focus = extractSection(fs.readFileSync(currentPath, 'utf8'), 'Current Focus').trim();
+  if (!focus) return;
+  out(ctx, '[awareness] Load this before doing work — current focus:');
+  out(ctx, '');
+  out(ctx, focus);
+  out(ctx, '');
+  out(ctx, 'Follow the awareness protocol; run `awareness handoff` before yielding control.');
+}
+
 function hookInstallCommand(ctx, opts) {
   const tool = opts.tool || 'all';
   const userHome = userHomePath(ctx, opts);
@@ -521,6 +767,7 @@ function scheduleRunCommand(ctx, opts) {
   out(ctx, `Schedule run complete: ${cadence}`);
   out(ctx, `Runtime log: ${eventFile}`);
   if (evaluation) out(ctx, `Evaluation: ${evaluation.status} (${evaluation.file})`);
+  if (evaluation?.candidates) out(ctx, `Memory candidates: ${evaluation.candidates.length ? `${evaluation.candidates.length} recorded` : 'none'}`);
   out(ctx, warnings.length ? `Warnings: ${warnings.length}` : 'Warnings: none');
   return 0;
 }
@@ -550,6 +797,7 @@ function scheduleInstallCommand(ctx, opts) {
       label,
       args,
       interval,
+      environmentPath: launchAgentPath(command),
       stdoutPath: path.join(launchdLogDir, `${target}.out.log`),
       stderrPath: path.join(launchdLogDir, `${target}.err.log`),
     }));
@@ -592,7 +840,8 @@ function writeEvaluationIfMissing(home, today) {
 
   ensureDir(path.dirname(evaluationPath));
   fs.writeFileSync(evaluationPath, buildEvaluation(home, today));
-  return { file: evaluationPath, status: 'written' };
+  const candidates = recordEvaluationMemoryCandidates(home, today);
+  return { file: evaluationPath, status: 'written', candidates };
 }
 
 function installCodexHooks(userHome, command, home) {
@@ -708,7 +957,16 @@ export const AwarenessFramework = async () => ({
 `;
 }
 
-function launchAgentPlist({ label, args, interval, stdoutPath, stderrPath }) {
+function launchAgentPath(command) {
+  const defaultPath = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+  if (path.isAbsolute(command)) {
+    const commandDir = path.dirname(command);
+    return [commandDir, ...defaultPath.filter((dir) => dir !== commandDir)].join(':');
+  }
+  return defaultPath.join(':');
+}
+
+function launchAgentPlist({ label, args, interval, environmentPath, stdoutPath, stderrPath }) {
   const argItems = args.map((arg) => `    <string>${escapeXml(arg)}</string>`).join('\n');
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -716,6 +974,11 @@ function launchAgentPlist({ label, args, interval, stdoutPath, stderrPath }) {
 <dict>
   <key>Label</key>
   <string>${escapeXml(label)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${escapeXml(environmentPath)}</string>
+  </dict>
   <key>ProgramArguments</key>
   <array>
 ${argItems}
@@ -822,7 +1085,7 @@ function buildEvaluation(home, today) {
   const traceability = !entries.length ? 0 : assignedEntries / entries.length >= 0.8 ? 2 : 1;
   const handoff = /- Next:\s+(?!The next concrete action)\S+/.test(extractSection(current, 'Current Focus')) ? 2 : current ? 1 : 0;
   const noise = current.split('\n').length <= 180 && !/YYYY-MM-DD|branch-name/.test(current) ? 2 : 1;
-  const reporting = extractSection(current, 'End-of-Day Candidates').trim() ? 2 : entries.length ? 1 : 0;
+  const reporting = sectionHasMeaningfulContent(extractSection(current, 'End-of-Day Candidates')) ? 2 : entries.length ? 1 : 0;
 
   return `# Awareness Evaluation - ${today.date}
 
@@ -847,6 +1110,135 @@ ${warnings.length ? warnings.map((warning) => `- ${warning}`).join('\n') : '- No
 `;
 }
 
+function recordEvaluationMemoryCandidates(home, today) {
+  const candidates = buildEvaluationMemoryCandidates(home, today);
+  return candidates.filter((candidate) => appendMemoryCandidate(home, today, candidate.text, candidate.evidence, 'evaluation'));
+}
+
+function buildEvaluationMemoryCandidates(home, today) {
+  const currentPath = awarenessPath(home);
+  const worklogPath = path.join(home, 'worklog', `${today.date}.md`);
+  const current = fs.existsSync(currentPath) ? fs.readFileSync(currentPath, 'utf8') : '';
+  const worklog = fs.existsSync(worklogPath) ? fs.readFileSync(worklogPath, 'utf8') : '';
+  const warnings = collectWarnings(home, today);
+  const entries = parseWorklogEntries(worklog);
+  const assignedEntries = entries.filter((entry) => entry.task && entry.task !== 'Unassigned').length;
+  const candidates = warnings.map((warning) => ({
+    text: `Review recurring awareness warning: ${warning}`,
+    evidence: `daily evaluation ${today.date}`,
+  }));
+
+  if (entries.length && assignedEntries / entries.length < 0.8) {
+    candidates.push({
+      text: `Improve task traceability: ${assignedEntries}/${entries.length} worklog entries had explicit task IDs.`,
+      evidence: `worklog/${today.date}.md`,
+    });
+  }
+
+  if (current && !/- Next:\s+(?!The next concrete action)\S+/.test(extractSection(current, 'Current Focus'))) {
+    candidates.push({
+      text: 'Tighten handoff habit: Current Focus should keep a concrete Next action before yielding control.',
+      evidence: awarenessPath(home),
+    });
+  }
+
+  if (current && (current.split('\n').length > 180 || /YYYY-MM-DD|branch-name/.test(current))) {
+    candidates.push({
+      text: 'Review awareness noise: current board is too long or still contains template placeholders.',
+      evidence: awarenessPath(home),
+    });
+  }
+
+  if (!sectionHasMeaningfulContent(extractSection(current, 'End-of-Day Candidates')) && entries.length) {
+    candidates.push({
+      text: 'Improve reporting readiness: capture end-of-day candidates while work is fresh.',
+      evidence: awarenessPath(home),
+    });
+  }
+
+  return candidates;
+}
+
+function appendMemoryCandidate(home, today, text, evidence, source = 'memory.note') {
+  const file = longTermMemoryPath(home);
+  let content = fs.readFileSync(file, 'utf8');
+  if (memoryCandidateExists(content, text, evidence)) return false;
+
+  content = replaceMetadata(content, 'Updated', formatTimestamp(today));
+  content = appendToSection(content, 'Promotion Candidates', `- ${today.date}: ${text} (evidence: ${evidence})\n`);
+  fs.writeFileSync(file, content);
+  appendMemoryEvent(home, today, {
+    type: 'memory.candidate.created',
+    source,
+    text,
+    evidence,
+  });
+  return true;
+}
+
+function memoryCandidateExists(content, text, evidence) {
+  const candidates = extractSection(content, 'Promotion Candidates');
+  return candidates.split('\n').some((line) => line.includes(`: ${text} (evidence: ${evidence})`));
+}
+
+function repeatedMemoryCandidateSuggestions(content, minCount) {
+  const grouped = new Map();
+  const prunedTexts = prunedMemoryCandidateTexts(content);
+  for (const candidate of parseMemoryCandidates(content)) {
+    const key = normalizeMemoryCandidateText(candidate.text);
+    if (prunedTexts.has(key)) continue;
+    const group = grouped.get(key) || { text: candidate.text, count: 0, evidence: [] };
+    group.count += 1;
+    group.evidence.push(candidate.evidence);
+    grouped.set(key, group);
+  }
+
+  return [...grouped.values()]
+    .filter((group) => group.count >= minCount)
+    .map((group) => ({
+      text: group.text,
+      count: group.count,
+      evidence: [...new Set(group.evidence)].join('; '),
+    }))
+    .sort((left, right) => right.count - left.count || left.text.localeCompare(right.text));
+}
+
+function parseMemoryCandidates(content) {
+  return extractSection(content, 'Promotion Candidates')
+    .split('\n')
+    .map((line) => line.trim())
+    .map((line) => line.match(/^- \d{4}-\d{2}-\d{2}: (.+) \(evidence: (.+)\)$/))
+    .filter(Boolean)
+    .map((match) => ({
+      text: match[1],
+      evidence: match[2],
+    }));
+}
+
+function prunedMemoryCandidateTexts(content) {
+  return new Set(extractSection(content, 'Pruned Or Revised')
+    .split('\n')
+    .map((line) => line.trim())
+    .map((line) => line.match(/^- \d{4}-\d{2}-\d{2}: (.+) \(reason: .+; evidence: .+\)$/))
+    .filter(Boolean)
+    .map((match) => normalizeMemoryCandidateText(match[1])));
+}
+
+function normalizeMemoryCandidateText(text) {
+  return text.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function shellQuoteText(text) {
+  return text.replace(/["\\$`]/g, '\\$&');
+}
+
+function sectionHasMeaningfulContent(section) {
+  return section
+    .split('\n')
+    .map((line) => line.trim())
+    .some((line) => line && line !== '- None.' && line !== '- None yet.');
+}
+
 function appendWorklog(home, today, entry) {
   const worklogPath = path.join(home, 'worklog', `${today.date}.md`);
   ensureDir(path.dirname(worklogPath));
@@ -932,7 +1324,7 @@ function ensurePrivateState(home, ctx) {
   if (!fs.existsSync(awarenessPath(home))) fs.writeFileSync(awarenessPath(home), initialAwareness(today));
   if (!fs.existsSync(path.join(home, 'worklog', `${today.date}.md`))) fs.writeFileSync(path.join(home, 'worklog', `${today.date}.md`), dailyWorklog(today.date));
   if (!fs.existsSync(personalityPath(home))) fs.writeFileSync(personalityPath(home), readTemplate('personality.md'));
-  if (!fs.existsSync(path.join(home, 'memory', 'long-term.md'))) fs.writeFileSync(path.join(home, 'memory', 'long-term.md'), readTemplate('memory-long-term.md'));
+  if (!fs.existsSync(longTermMemoryPath(home))) fs.writeFileSync(longTermMemoryPath(home), readTemplate('memory-long-term.md'));
 }
 
 function replaceSection(content, section, body) {
@@ -1254,6 +1646,86 @@ function personalityPath(home) {
   return path.join(home, 'memory', 'personality.md');
 }
 
+function longTermMemoryPath(home) {
+  return path.join(home, 'memory', 'long-term.md');
+}
+
+function memoryEventPath(home) {
+  return path.join(home, 'memory', 'events.jsonl');
+}
+
+function appendMemoryEvent(home, today, event) {
+  const file = memoryEventPath(home);
+  ensureDir(path.dirname(file));
+  fs.appendFileSync(file, `${JSON.stringify({
+    timestamp: formatTimestamp(today),
+    ...event,
+  })}\n`);
+  return file;
+}
+
+function readMemoryEvents(home) {
+  const file = memoryEventPath(home);
+  if (!fs.existsSync(file)) return [];
+  return fs.readFileSync(file, 'utf8')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}
+
+function collectRecallSources(home) {
+  return [
+    ...markdownFilesRecursive(path.join(home, 'memory')),
+    memoryEventPath(home),
+    ...markdownFiles(path.join(home, 'worklog')),
+    ...markdownFiles(path.join(home, 'evaluations')),
+  ].filter((file, index, files) => fs.existsSync(file) && files.indexOf(file) === index);
+}
+
+function markdownFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => path.join(dir, name));
+}
+
+function markdownFilesRecursive(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .flatMap((entry) => {
+      const file = path.join(dir, entry.name);
+      if (entry.isDirectory()) return markdownFilesRecursive(file);
+      if (entry.isFile() && entry.name.endsWith('.md')) return [file];
+      return [];
+    });
+}
+
+function recallMatches(home, query, limit) {
+  const terms = [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))];
+  const results = [];
+  for (const file of collectRecallSources(home)) {
+    const content = fs.readFileSync(file, 'utf8');
+    const lines = content.split('\n');
+    lines.forEach((line, index) => {
+      const haystack = line.toLowerCase();
+      const score = terms.filter((term) => haystack.includes(term)).length;
+      if (score > 0) {
+        results.push({
+          file,
+          line: index + 1,
+          score,
+          text: line.trim(),
+        });
+      }
+    });
+  }
+  results.sort((left, right) => right.score - left.score || left.file.localeCompare(right.file) || left.line - right.line);
+  return results.slice(0, limit);
+}
+
 function userMemoryPath(home, userSlug) {
   return path.join(home, 'memory', 'users', `${userSlug}.md`);
 }

package/templates/agent-instructions.md

@@ -6,7 +6,7 @@ You operate in a multi-task, multi-agent environment. Before doing work, load th
 
 - Awareness board: `~/.agents/awareness/current.md`
 - Daily worklog: `~/.agents/worklog/YYYY-MM-DD.md`
-- Optional durable memory: `~/.agents/memory/`
+- Durable memory and review candidates: `~/.agents/memory/`
 - Optional narrow user memory: `~/.agents/memory/users/<user>.md` or scoped channel equivalent
 - Optional evaluation notes: `~/.agents/evaluations/YYYY-MM-DD.md`
 - Runtime hook and scheduler events: `~/.agents/runtime/`
@@ -20,18 +20,27 @@ You operate in a multi-task, multi-agent environment. Before doing work, load th
 5. When concrete progress happens, append to the daily worklog.
 6. When state changes, update the awareness board.
 7. Before handoff, run `awareness handoff` if available; otherwise make the awareness board reflect the exact current state and append a final worklog entry.
-8. At end of day, prepare a task-grouped summary for human review.
-9. Treat hook and scheduler runtime events as diagnostics only; they do not replace task worklog entries.
-10. For multi-user channels, keep context scoped by channel and store only narrow user facts in `memory/users/<user>.md`.
+8. When evaluation or handoff exposes repeated friction, review memory candidates with `awareness memory candidates` or `awareness memory review`.
+9. At end of day, prepare a task-grouped summary for human review, including memory candidates and pattern suggestions.
+10. Treat hook and scheduler runtime events as diagnostics only; they do not replace task worklog entries.
+11. For multi-user channels, keep context scoped by channel and store only narrow user facts in `memory/users/<user>.md`.
 
 ## Rules
 
 - Keep the worklog append-only.
 - Do not invent task IDs.
 - Record evidence: paths, commands, test results, commits, PRs, deployments, blockers.
-- Prefer CLI maintenance commands (`awareness focus`, `awareness log`, `awareness handoff`, `awareness evaluate`) when available.
+- Prefer CLI maintenance commands (`awareness focus`, `awareness log`, `awareness handoff`, `awareness evaluate`, `awareness memory candidates`, `awareness memory review`) when available.
+- Let evaluations and schedules record promotion candidates, but promote durable memory only with explicit evidence through `awareness memory promote`.
+- Promote repeated candidates as `pattern` only after `awareness memory review` or equivalent evidence shows repetition.
+- Promote direct user preferences promptly when they affect future collaboration.
 - Use `awareness user note` only for short, evidence-backed participant facts such as nicknames, repeated questions, topics, or explicit preferences.
-- Use `awareness hook run` and `awareness schedule run` only for low-noise maintenance; do not let them post externally or promote long-term memory silently.
+- Use `awareness hook run` and `awareness schedule run` only for low-noise maintenance; do not let them post externally or silently promote long-term memory.
 - Keep private state out of version control.
 - Ask before posting worklogs, comments, status changes, or summaries to external systems.
 - Propose framework improvements through reviewed changes, not hidden local edits.
+
+- Use `awareness remember` for explicit observations that should enter memory review.
+- Use `awareness recall QUERY` before repeating uncertain or previously solved work.
+- Use `awareness forget --text TEXT --reason REASON --evidence EVIDENCE` when memory is stale, wrong, or superseded.
+- Use `awareness improve` after material work or process friction to run evaluation plus memory review.

package/templates/cli-wrapper.md

@@ -6,6 +6,6 @@ Read and follow the canonical private protocol at:
 
 If your CLI does not expand `@` imports automatically, open that file explicitly before starting work.
 
-Treat imported awareness files as session-start snapshots. If the Awareness CLI is available, run `awareness status` or `awareness check` at session start, `awareness refresh` when parallel work may have changed state, and `awareness handoff` before returning control.
+Treat imported awareness files as session-start snapshots. If the Awareness CLI is available, run `awareness status` or `awareness check` at session start, `awareness refresh` when parallel work may have changed state, `awareness memory review` when evaluating repeated candidates, and `awareness handoff` before returning control.
 
 Keep this wrapper small. The framework should live in versioned methodology docs, and live operational state should stay private.

package/templates/end-of-day-summary.md

@@ -25,3 +25,11 @@
 ## Methodology Observations
 
 - Anything that made the awareness or worklog process better or worse
+
+## Memory Review
+
+- New promotion candidates:
+- Repeated candidates or suggested patterns:
+- Promotions made:
+- Needs user confirmation:
+- Candidates to prune or leave short-term: