@fyso/awareness-framework 0.2.0 → 0.3.1

package/package.json

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

package/src/cli.js

@@ -3,9 +3,21 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import {
+  activeMemoryCandidates,
+  isPrunedMemoryText,
+  memoryCandidateExists,
+  memoryCandidateTextExists,
+  repeatedMemoryCandidateSuggestions,
+} from './memory-candidates.js';
+import { normalizeSearchText, recallTermGroups } from './text.js';
 
 const VALID_STATES = new Set(['started', 'in-progress', 'paused', 'blocked', 'waiting', 'done', 'in-review', 'ready']);
 const DEFAULT_STATE = 'in-progress';
+const STATE_ALIASES = {
+  in_progress: 'in-progress',
+  in_review: 'in-review',
+};
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const repoRoot = path.resolve(__dirname, '..');
 
@@ -18,7 +30,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 +54,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 +130,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]
@@ -124,6 +154,9 @@ Scope options:
   --channel NAME              Store state under <folder>/channels/<safe-name>.
   --user ID                   Select a user memory file for user commands.
 
+State values:
+  ${[...VALID_STATES].join(', ')}
+
 The CLI maintains private files under ~/.agents by default. It does not post to Jira, GitHub, or any external system.`);
 }
 
@@ -146,7 +179,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({
@@ -191,7 +224,7 @@ function statusCommand(ctx, opts) {
   for (const warning of warnings) {
     out(ctx, `- ${warning}`);
   }
-  return warnings.length ? 1 : 0;
+  return 0;
 }
 
 function checkCommand(ctx, opts) {
@@ -312,7 +345,7 @@ function handoffCommand(ctx, opts) {
     }
   }
 
-  return warnings.length ? 1 : 0;
+  return 0;
 }
 
 function evaluateCommand(ctx, opts) {
@@ -335,7 +368,220 @@ function evaluateCommand(ctx, opts) {
 
   ensureDir(path.dirname(evaluationPath));
   fs.writeFileSync(evaluationPath, content);
+  const candidates = recordEvaluationMemoryCandidates(home, today);
+  const candidateSummary = candidates.length ? `${candidates.length} recorded` : 'none';
   out(ctx, `Evaluation written: ${evaluationPath}`);
+  out(ctx, `Memory candidates: ${candidateSummary}`);
+  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');
+  const activeCandidates = activeMemoryCandidates(content)
+    .map((candidate) => candidate.line)
+    .join('\n');
+  out(ctx, 'Promotion Candidates');
+  out(ctx, activeCandidates || '- 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');
+  if (isPrunedMemoryText(content, text)) {
+    throw new Error(`Cannot promote pruned or revised memory: ${text}`);
+  }
+  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})`);
+  const candidateSummary = evaluation.candidates ? `${evaluation.candidates.length} (from evaluation diagnostics)` : 'not changed';
+  out(ctx, `Auto-generated candidates: ${candidateSummary}`);
+  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;
 }
 
@@ -544,6 +790,10 @@ 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) {
+    const candidateSummary = evaluation.candidates.length ? `${evaluation.candidates.length} recorded` : 'none';
+    out(ctx, `Memory candidates: ${candidateSummary}`);
+  }
   out(ctx, warnings.length ? `Warnings: ${warnings.length}` : 'Warnings: none');
   return 0;
 }
@@ -573,6 +823,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`),
     }));
@@ -581,7 +832,8 @@ function scheduleInstallCommand(ctx, opts) {
     if (opts.load) {
       const result = loadLaunchAgent(file, label);
       if (result.status !== 0) {
-        throw new Error(`launchctl failed for ${file}: ${result.stderr || result.stdout || `exit ${result.status}`}`);
+        const failure = result.stderr || result.stdout || `exit ${result.status}`;
+        throw new Error(`launchctl failed for ${file}: ${failure}`);
       }
       loaded.push(file);
     }
@@ -615,7 +867,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) {
@@ -731,7 +984,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">
@@ -739,6 +1001,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}
@@ -845,7 +1112,8 @@ 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;
+  const warningsMarkdown = warnings.length ? warnings.map((warning) => `- ${warning}`).join('\n') : '- None.';
 
   return `# Awareness Evaluation - ${today.date}
 
@@ -861,7 +1129,7 @@ function buildEvaluation(home, today) {
 
 ## Warnings
 
-${warnings.length ? warnings.map((warning) => `- ${warning}`).join('\n') : '- None.'}
+${warningsMarkdown}
 
 ## Proposed Changes
 
@@ -870,6 +1138,87 @@ ${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', {
+    dedupeByText: true,
+  }));
+}
+
+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', opts = {}) {
+  const file = longTermMemoryPath(home);
+  let content = fs.readFileSync(file, 'utf8');
+  if (memoryCandidateExists(content, text, evidence)) return false;
+  if (isPrunedMemoryText(content, text)) return false;
+  if (opts.dedupeByText && memoryCandidateTextExists(content, text)) 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 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));
@@ -900,7 +1249,7 @@ function parseWorklogEntries(worklog) {
     const headingText = heading[0];
     const headingParts = headingText.replace(/^#{2,3} \d{2}:\d{2} - /, '').split(' - ');
     const headingTask = headingParts.length > 1 && isTaskId(headingParts[0]) ? headingParts[0] : null;
-    const jiraTask = block.match(/^- Jira:\s+(.+)$/m)?.[1]?.trim();
+    const jiraTask = metadataValue(block, 'Jira');
     return {
       block,
       task: headingTask || jiraTask || null,
@@ -955,7 +1304,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) {
@@ -971,12 +1320,13 @@ function replaceSection(content, section, body) {
 function appendToSection(content, section, addition) {
   const current = extractSection(content, section);
   const cleaned = current.replace(/^- None yet\.\n?/m, '').trimEnd();
-  return replaceSection(content, section, `${cleaned ? `${cleaned}\n\n` : ''}${addition.trimEnd()}\n`);
+  const prefix = cleaned ? `${cleaned}\n\n` : '';
+  return replaceSection(content, section, `${prefix}${addition.trimEnd()}\n`);
 }
 
 function extractSection(content, section) {
   const pattern = new RegExp(`(?:^|\\n)## ${escapeRegExp(section)}\\n\\n?([\\s\\S]*?)(?=\\n## |$)`);
-  const match = content.match(pattern);
+  const match = pattern.exec(content);
   return match ? match[1] : '';
 }
 
@@ -988,12 +1338,18 @@ function replaceMetadata(content, key, value) {
   return content.replace(/^# .+$/m, (heading) => `${heading}\n\n- ${key}: ${value}`);
 }
 
+function metadataValue(content, key) {
+  const prefix = `- ${key}:`;
+  const line = content.split('\n').find((candidate) => candidate.startsWith(prefix));
+  return line?.slice(prefix.length).trim() || null;
+}
+
 function currentContext(home) {
   const file = awarenessPath(home);
   if (!fs.existsSync(file)) return 'Not specified';
   const focus = extractSection(fs.readFileSync(file, 'utf8'), 'Current Focus');
-  const repo = focus.match(/^- Repository:\s+(.+)$/m)?.[1] || 'Not specified';
-  const branch = focus.match(/^- Branch:\s+(.+)$/m)?.[1] || 'Not specified';
+  const repo = metadataValue(focus, 'Repository') || 'Not specified';
+  const branch = metadataValue(focus, 'Branch') || 'Not specified';
   return `${repo} / ${branch}`;
 }
 
@@ -1171,10 +1527,11 @@ function initialUserMemory(user, timestamp) {
 }
 
 function normalizeState(state) {
-  if (!VALID_STATES.has(state)) {
+  const normalized = STATE_ALIASES[state] || String(state).replaceAll('_', '-');
+  if (!VALID_STATES.has(normalized)) {
     throw new Error(`Invalid state: ${state}. Valid states: ${[...VALID_STATES].join(', ')}`);
   }
-  return state;
+  return normalized;
 }
 
 function expandTargets(value, allowed) {
@@ -1191,11 +1548,15 @@ function expandTargets(value, allowed) {
 
 function required(opts, key) {
   if (!opts[key] || opts[key] === true) {
-    throw new Error(`Missing required option: --${key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}`);
+    throw new Error(`Missing required option: --${optionName(key)}`);
   }
   return opts[key];
 }
 
+function optionName(key) {
+  return key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
 function agentsHome(ctx, opts) {
   const raw = opts.home
     || opts.agentFolder
@@ -1277,6 +1638,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 termGroups = recallTermGroups(query);
+  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 = normalizeSearchText(line);
+      const score = termGroups.filter((terms) => terms.some((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`);
 }