@jacfrost/autopm 0.0.1

package/src/autopm/memory-commands.js

@@ -0,0 +1,1079 @@
+import path from 'node:path';
+
+import { showAutoPmCommandTui } from './command-tui.js';
+import { runAutoPmMemoryOperation } from './memory/operations.js';
+import { canonicalAutoPmMemoryPaths } from './memory/paths.js';
+import { openAutoPmMemoryStore } from './memory/store.js';
+import { initializeAutoPmMemoryWorkspace } from './memory/status.js';
+import {
+  buildAutoPmSummaryTrees,
+  rebuildAutoPmSummaryTreeWikiProjections,
+} from './memory/tree.js';
+
+export const AUTOPM_MEMORY_COMMAND_NAME = 'memory';
+
+const SUPPORTED_SUBCOMMANDS = new Set([
+  'help',
+  'init',
+  'status',
+  'ingest',
+  'recall',
+  'search',
+  'get',
+  'candidates',
+  'review',
+  'accept',
+  'reject',
+  'forget',
+  'supersede',
+  'rebuild-wiki',
+  'rebuild-summaries',
+  'scheduler',
+  'doctor',
+  'open-vault',
+]);
+
+const SCHEDULER_ACTIONS = new Set(['status', 'start', 'stop', 'pause', 'resume', 'tick', 'diagnostics', 'one-shot', 'recover']);
+const SUBCOMMAND_OPERATION = Object.freeze({
+  status: 'status',
+  ingest: 'ingest',
+  recall: 'recall',
+  search: 'search',
+  get: 'get',
+  candidates: 'candidates',
+  review: 'candidates',
+  accept: 'accept',
+  reject: 'reject',
+  forget: 'forget',
+  supersede: 'accept',
+  scheduler: 'scheduler',
+  doctor: 'doctor',
+});
+
+const SECRET_PATTERNS = Object.freeze([
+  /Bearer\s+[A-Za-z0-9._~+/=-]+/gi,
+  /sk-[A-Za-z0-9_-]{16,}/g,
+  /\b([A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API[-_]?KEY|AUTHORIZATION|CREDENTIAL)[A-Z0-9_]*)\s*[:=]\s*([^\s,;"'`]+|["'`][^"'`]*["'`])/gi,
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function nowIso(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value : new Date().toISOString();
+}
+
+function uniqueStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .map((value) => String(value ?? '').trim())
+    .filter((value) => value.length > 0))];
+}
+
+function redactText(value) {
+  let text = String(value ?? '');
+  for (const pattern of SECRET_PATTERNS) {
+    text = text.replace(pattern, (...args) => {
+      if (args.length > 3 && typeof args[1] === 'string') return `${args[1]}=[REDACTED]`;
+      if (/^Bearer/i.test(args[0])) return 'Bearer [REDACTED]';
+      return '[REDACTED]';
+    });
+  }
+  return text;
+}
+
+function safeFlagName(value) {
+  const name = String(value ?? '').split('=')[0];
+  if (!/^--[A-Za-z][A-Za-z0-9-]{0,63}$/.test(name)) return '--[redacted]';
+  if (/(?:token|secret|password|passwd|api[-_]?key|authorization|credential)/i.test(name)) return '--[redacted]';
+  return name;
+}
+
+function tokenizeArgs(args = '') {
+  const input = String(args ?? '');
+  const tokens = [];
+  let current = '';
+  let quote = null;
+  let hasCurrent = false;
+  let escaping = false;
+
+  for (const char of input) {
+    if (escaping) {
+      current += char;
+      hasCurrent = true;
+      escaping = false;
+      continue;
+    }
+    if (char === '\\') {
+      escaping = true;
+      hasCurrent = true;
+      continue;
+    }
+    if (quote !== null) {
+      if (char === quote) {
+        quote = null;
+        hasCurrent = true;
+      } else {
+        current += char;
+        hasCurrent = true;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      hasCurrent = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (hasCurrent) {
+        tokens.push(current);
+        current = '';
+        hasCurrent = false;
+      }
+      continue;
+    }
+    current += char;
+    hasCurrent = true;
+  }
+
+  if (escaping) current += '\\';
+  if (quote !== null) return { ok: false, error: 'Memory command arguments contain an unterminated quoted string.' };
+  if (hasCurrent) tokens.push(current);
+  return { ok: true, tokens };
+}
+
+function readFlagValue(tokens, index, flag, errors) {
+  const value = tokens[index + 1];
+  if (typeof value !== 'string' || value.trim() === '' || value.startsWith('--')) {
+    errors.push(`Flag ${flag} requires a non-empty value.`);
+    return { value: null, nextIndex: index };
+  }
+  return { value, nextIndex: index + 1 };
+}
+
+function valueAfterEquals(token, flag, errors) {
+  const value = token.slice(`${flag}=`.length).trim();
+  if (value === '') {
+    errors.push(`Flag ${flag} requires a non-empty value.`);
+    return null;
+  }
+  return value;
+}
+
+function positiveInteger(value, flag, errors) {
+  if (!/^\d+$/.test(String(value ?? '').trim())) {
+    errors.push(`Flag ${flag} requires a positive integer value.`);
+    return null;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    errors.push(`Flag ${flag} requires a positive integer value.`);
+    return null;
+  }
+  return parsed;
+}
+
+function parseBooleanFlag(token) {
+  if (!token.includes('=')) return true;
+  const value = token.slice(token.indexOf('=') + 1).trim().toLowerCase();
+  return ['1', 'true', 'yes', 'on'].includes(value);
+}
+
+function operationForSubcommand(subcommand) {
+  return SUBCOMMAND_OPERATION[subcommand] ?? null;
+}
+
+function addFlagValue(parsed, key, value) {
+  if (value !== null && value !== undefined && String(value).trim() !== '') parsed.payload[key] = value;
+}
+
+function pushFlagValue(parsed, key, value) {
+  if (value === null || value === undefined || String(value).trim() === '') return;
+  const existing = Array.isArray(parsed.payload[key]) ? parsed.payload[key] : [];
+  parsed.payload[key] = [...existing, value];
+}
+
+function applyFlag(parsed, tokens, index) {
+  const token = tokens[index];
+  const errors = parsed.errors;
+  const readValue = (flag) => token.startsWith(`${flag}=`)
+    ? { value: valueAfterEquals(token, flag, errors), nextIndex: index }
+    : readFlagValue(tokens, index, flag, errors);
+  const readInteger = (flag, key) => {
+    const read = readValue(flag);
+    const parsedInteger = read.value === null ? null : positiveInteger(read.value, flag, errors);
+    if (parsedInteger !== null) parsed.payload[key] = parsedInteger;
+    return read.nextIndex;
+  };
+
+  if (token === '--json') {
+    parsed.json = true;
+    return index;
+  }
+  if (token === '--repair') {
+    parsed.repair = true;
+    return index;
+  }
+  if (token === '--force-rebuild') {
+    parsed.payload.forceRebuild = true;
+    return index;
+  }
+  if (token === '--force-fallback' || token === '--force-fallback-index') {
+    parsed.payload.forceFallback = true;
+    parsed.payload.forceFallbackIndex = true;
+    return index;
+  }
+  if (token === '--write-diagnostics') {
+    parsed.payload.writeDiagnostics = true;
+    return index;
+  }
+  if (token === '--no-write-diagnostics') {
+    parsed.payload.writeDiagnostics = false;
+    return index;
+  }
+  if (token === '--evidence-only' || token === '--drilldown') {
+    parsed.payload.evidenceOnly = true;
+    parsed.payload.drilldown = true;
+    return index;
+  }
+  if (token === '--hard-delete') {
+    parsed.payload.hardDelete = true;
+    return index;
+  }
+  if (token === '--confirm-hard-delete') {
+    parsed.payload.confirmHardDelete = true;
+    return index;
+  }
+  if (token === '--allow-when-stopped') {
+    parsed.payload.allowWhenStopped = true;
+    return index;
+  }
+  if (token.startsWith('--allow-when-stopped=')) {
+    parsed.payload.allowWhenStopped = parseBooleanFlag(token);
+    return index;
+  }
+
+  const valueFlags = [
+    ['--project-root', 'projectRoot'],
+    ['--generated-at', 'generatedAt'],
+    ['--query', 'query'],
+    ['--record-type', 'recordType'],
+    ['--record-id', 'recordId'],
+    ['--artifact-path', 'artifactPath'],
+    ['--candidate-id', 'candidateId'],
+    ['--memory-id', 'memoryId'],
+    ['--accepted-memory-id', 'acceptedMemoryId'],
+    ['--reviewer', 'reviewer'],
+    ['--actor', 'actor'],
+    ['--reason', 'reason'],
+    ['--scheduler-action', 'action'],
+    ['--action', 'action'],
+  ];
+  for (const [flag, key] of valueFlags) {
+    if (token === flag || token.startsWith(`${flag}=`)) {
+      const read = readValue(flag);
+      addFlagValue(parsed, key, read.value);
+      return read.nextIndex;
+    }
+  }
+
+  const listFlags = [
+    ['--tag', 'tags'],
+    ['--supersedes-memory-id', 'supersedesMemoryIds'],
+    ['--supersedes', 'supersedesMemoryIds'],
+    ['--source-path', 'sourcePaths'],
+    ['--scope', 'scopes'],
+    ['--status', 'statuses'],
+    ['--actions', 'actions'],
+    ['--scheduler-action-id', 'actions'],
+  ];
+  for (const [flag, key] of listFlags) {
+    if (token === flag || token.startsWith(`${flag}=`)) {
+      const read = readValue(flag);
+      if (key === 'actions' && typeof read.value === 'string' && read.value.includes(',')) {
+        read.value.split(',').map((value) => value.trim()).filter(Boolean).forEach((value) => pushFlagValue(parsed, key, value));
+      } else {
+        pushFlagValue(parsed, key, read.value);
+      }
+      return read.nextIndex;
+    }
+  }
+
+  const integerFlags = [
+    ['--limit', 'limit'],
+    ['--token-budget', 'tokenBudget'],
+    ['--max-text-chars', 'maxTextChars'],
+    ['--source-seal-threshold', 'sourceSealThreshold'],
+    ['--max-topics', 'maxTopics'],
+    ['--max-global-inputs', 'maxGlobalInputs'],
+  ];
+  for (const [flag, key] of integerFlags) {
+    if (token === flag || token.startsWith(`${flag}=`)) return readInteger(flag, key);
+  }
+
+  errors.push(`Unsupported flag: ${safeFlagName(token)}.`);
+  return index;
+}
+
+function applyPositional(parsed, token) {
+  const value = redactText(token);
+  switch (parsed.subcommand) {
+    case 'recall':
+    case 'search':
+      parsed.positionals.push(value);
+      break;
+    case 'get':
+      if (!parsed.payload.recordType) parsed.payload.recordType = value;
+      else if (!parsed.payload.recordId) parsed.payload.recordId = value;
+      else parsed.errors.push('Unexpected extra /memory get argument.');
+      break;
+    case 'accept':
+    case 'reject':
+    case 'supersede':
+      if (!parsed.payload.candidateId) parsed.payload.candidateId = value;
+      else parsed.errors.push(`Unexpected extra /memory ${parsed.subcommand} argument.`);
+      break;
+    case 'forget':
+      if (!parsed.payload.memoryId) parsed.payload.memoryId = value;
+      else parsed.errors.push('Unexpected extra /memory forget argument.');
+      break;
+    case 'ingest':
+      pushFlagValue(parsed, 'sourcePaths', value);
+      break;
+    case 'candidates':
+    case 'review':
+      pushFlagValue(parsed, 'statuses', value);
+      break;
+    case 'scheduler':
+      if (!parsed.payload.action && SCHEDULER_ACTIONS.has(value)) parsed.payload.action = value;
+      else if (parsed.payload.action && !value.startsWith('--')) pushFlagValue(parsed, 'actions', value);
+      else parsed.errors.push('Unsupported /memory scheduler action.');
+      break;
+    case 'rebuild-wiki':
+      pushFlagValue(parsed, 'scopes', value);
+      break;
+    case 'open-vault':
+      if (!parsed.payload.target) parsed.payload.target = value;
+      else parsed.errors.push('Unexpected extra /memory open-vault argument.');
+      break;
+    default:
+      parsed.errors.push(`/${AUTOPM_MEMORY_COMMAND_NAME} ${parsed.subcommand} does not accept positional argument: [redacted].`);
+  }
+}
+
+function finalizeParsed(parsed) {
+  if ((parsed.subcommand === 'recall' || parsed.subcommand === 'search') && parsed.payload.query === undefined && parsed.positionals.length > 0) {
+    parsed.payload.query = parsed.positionals.join(' ');
+  }
+  if (parsed.subcommand === 'scheduler') parsed.payload.action ??= 'status';
+  if (parsed.subcommand === 'supersede') {
+    parsed.payload.reason ??= 'supersede via /memory supersede';
+    if (!Array.isArray(parsed.payload.supersedesMemoryIds) || parsed.payload.supersedesMemoryIds.length === 0) {
+      parsed.errors.push('/memory supersede requires at least one --supersedes-memory-id value.');
+    }
+  }
+  if ((parsed.subcommand === 'accept' || parsed.subcommand === 'reject' || parsed.subcommand === 'supersede') && !parsed.payload.candidateId) {
+    parsed.errors.push(`/memory ${parsed.subcommand} requires a candidate id.`);
+  }
+  if (parsed.subcommand === 'forget' && !parsed.payload.memoryId && !parsed.payload.acceptedMemoryId) {
+    parsed.errors.push('/memory forget requires a memory id.');
+  }
+  if (parsed.subcommand === 'get' && !parsed.payload.artifactPath && (!parsed.payload.recordType || !parsed.payload.recordId)) {
+    parsed.errors.push('/memory get requires <recordType> <recordId> or --artifact-path.');
+  }
+  parsed.payload = Object.fromEntries(Object.entries(parsed.payload).filter(([, value]) => value !== undefined));
+  return parsed;
+}
+
+export function memoryCommandUsageText() {
+  return [
+    'Usage:',
+    '  /memory status|doctor                                — inspect memory substrate diagnostics',
+    '  /memory recall [query] [--token-budget <n>]           — recall bounded active accepted memory',
+    '  /memory search [query] [--record-type <type>]         — search memory index/evidence',
+    '  /memory review                                       — interactively accept, reject, or skip candidates',
+    '  /memory forget <memoryId> [--reason <text>]           — remove accepted memory from active recall',
+    '  /memory open-vault                                   — return the local memory wiki vault path',
+    '  /memory ingest [--source-path <path>]                 — ingest configured or explicit memory sources',
+    '  /memory candidates [--status pending]                 — list reviewable memory candidates',
+    '  /memory get <recordType> <recordId>                   — fetch a memory record',
+    '  /memory accept <candidateId> [--tag <tag>]            — accept a candidate into active memory',
+    '  /memory reject <candidateId> [--reason <text>]        — reject a candidate with audit diagnostics',
+    '  /memory supersede <candidateId> --supersedes-memory-id <id> — accept while superseding active memory',
+    '  /memory rebuild-wiki [--scope <scope>]                — refresh wiki projections for summary trees',
+    '  /memory rebuild-summaries [--force-rebuild]           — build source/topic/global summary trees',
+    '  /memory scheduler status|start|stop|pause|resume|tick — control local memory maintenance',
+    '  /memory init [--repair]                               — repair local AutoPM memory workspace',
+  ].join('\n');
+}
+
+export function parseMemoryCommandArgs(args = '') {
+  const tokenized = tokenizeArgs(args);
+  if (!tokenized.ok) {
+    return {
+      ok: false,
+      subcommand: 'status',
+      operation: 'status',
+      json: false,
+      payload: {},
+      errors: [tokenized.error],
+      help: false,
+    };
+  }
+
+  const tokens = tokenized.tokens;
+  const parsed = {
+    ok: true,
+    subcommand: 'status',
+    operation: 'status',
+    json: false,
+    help: false,
+    repair: false,
+    payload: {},
+    positionals: [],
+    errors: [],
+  };
+
+  let index = 0;
+  while (index < tokens.length && tokens[index] === '--json') {
+    parsed.json = true;
+    index += 1;
+  }
+
+  const first = tokens[index];
+  if (first === 'help' || first === '-h' || first === '--help') {
+    parsed.help = true;
+    parsed.subcommand = 'help';
+    parsed.operation = null;
+    return finalizeParsed(parsed);
+  }
+  if (typeof first === 'string' && !first.startsWith('--')) {
+    const normalized = first.trim().toLowerCase().replaceAll('_', '-');
+    if (!SUPPORTED_SUBCOMMANDS.has(normalized)) {
+      parsed.errors.push('Unsupported /memory subcommand: [redacted].');
+    } else {
+      parsed.subcommand = normalized;
+      parsed.operation = operationForSubcommand(normalized);
+    }
+    index += 1;
+  }
+
+  for (; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.startsWith('--')) {
+      index = applyFlag(parsed, tokens, index);
+    } else {
+      applyPositional(parsed, token);
+    }
+  }
+
+  const finalized = finalizeParsed(parsed);
+  finalized.ok = finalized.errors.length === 0;
+  return finalized;
+}
+
+function severityFromEnvelope(envelope) {
+  if (envelope?.status === 'error' || (Array.isArray(envelope?.errorCodes) && envelope.errorCodes.length > 0)) return 'error';
+  if (['warn', 'missing', 'partial', 'blocked'].includes(envelope?.status)) return 'warning';
+  return 'info';
+}
+
+function normalizeDiagnostics(records, severity) {
+  if (!Array.isArray(records)) return [];
+  return records
+    .filter((record) => isPlainObject(record) && typeof record.code === 'string' && record.code.length > 0)
+    .map((record) => ({
+      code: record.code,
+      severity: record.severity ?? severity,
+      message: redactText(record.message ?? record.code),
+      details: isPlainObject(record.details) ? record.details : {},
+    }));
+}
+
+function envelopeFromResult({ subcommand, operation, result, generatedAt, json = false, nextAction = null, coreResult = null }) {
+  const normalized = isPlainObject(result) ? result : {};
+  const diagnostics = normalizeDiagnostics(normalized.diagnostics, 'info');
+  const warnings = normalizeDiagnostics(normalized.warnings, 'warning');
+  const errors = normalizeDiagnostics(normalized.errors, 'error');
+  const warningCodes = uniqueStrings([
+    ...(Array.isArray(normalized.warningCodes) ? normalized.warningCodes : []),
+    ...warnings.map((warning) => warning.code),
+    ...diagnostics.filter((diagnostic) => diagnostic.severity === 'warning').map((diagnostic) => diagnostic.code),
+  ]);
+  const errorCodes = uniqueStrings([
+    ...(Array.isArray(normalized.errorCodes) ? normalized.errorCodes : []),
+    ...errors.map((error) => error.code),
+    ...diagnostics.filter((diagnostic) => diagnostic.severity === 'error').map((diagnostic) => diagnostic.code),
+  ]);
+  const status = normalized.status ?? normalized.operationStatus ?? (errorCodes.length > 0 ? 'error' : warningCodes.length > 0 ? 'warn' : 'ok');
+  const envelope = {
+    command: AUTOPM_MEMORY_COMMAND_NAME,
+    subcommand,
+    operation,
+    implemented: true,
+    status,
+    ok: normalized.ok !== false && status !== 'error' && status !== 'blocked',
+    generatedAt: normalized.generatedAt ?? generatedAt,
+    durableStateChanged: normalized.durableStateChanged === true,
+    behaviorChanged: normalized.behaviorChanged === true,
+    artifactPathsRead: uniqueStrings(normalized.artifactPathsRead),
+    artifactPathsWritten: uniqueStrings(normalized.artifactPathsWritten),
+    warningCodes,
+    errorCodes,
+    warnings,
+    errors,
+    diagnostics,
+    safeNextActions: uniqueStrings(normalized.safeNextActions),
+    nextAction: nextAction ?? normalized.nextAction ?? (Array.isArray(normalized.safeNextActions) ? normalized.safeNextActions[0] : null),
+    summary: normalized.summary ?? null,
+    result: normalized.result ?? null,
+  };
+  if (json === true) envelope.json = true;
+  if (coreResult !== null) envelope.coreResult = coreResult;
+  return envelope;
+}
+
+function argumentFailureEnvelope(parsed, generatedAt = new Date().toISOString()) {
+  const errors = parsed.errors.map((message) => ({
+    code: 'AUTOPM_MEMORY_COMMAND_ARGUMENT_INVALID',
+    severity: 'error',
+    message: redactText(message),
+    details: { subcommand: parsed.subcommand },
+  }));
+  return {
+    command: AUTOPM_MEMORY_COMMAND_NAME,
+    subcommand: parsed.subcommand,
+    operation: parsed.operation,
+    implemented: true,
+    status: 'error',
+    ok: false,
+    generatedAt,
+    durableStateChanged: false,
+    behaviorChanged: false,
+    artifactPathsRead: [],
+    artifactPathsWritten: [],
+    warningCodes: [],
+    errorCodes: ['AUTOPM_MEMORY_COMMAND_ARGUMENT_INVALID'],
+    warnings: [],
+    errors,
+    diagnostics: errors,
+    safeNextActions: ['/memory help'],
+    nextAction: memoryCommandUsageText(),
+  };
+}
+
+function failureEnvelope({ subcommand, operation, generatedAt, error }) {
+  const code = error?.name === 'AbortError' ? 'AUTOPM_MEMORY_COMMAND_ABORTED' : 'AUTOPM_MEMORY_COMMAND_FAILED';
+  const diagnostic = {
+    code,
+    severity: 'error',
+    message: `AutoPM memory command ${subcommand} failed.`,
+    details: { reason: redactText(error instanceof Error ? error.message : String(error)) },
+  };
+  return {
+    command: AUTOPM_MEMORY_COMMAND_NAME,
+    subcommand,
+    operation,
+    implemented: true,
+    status: 'error',
+    ok: false,
+    generatedAt,
+    durableStateChanged: false,
+    behaviorChanged: false,
+    artifactPathsRead: [],
+    artifactPathsWritten: [],
+    warningCodes: [],
+    errorCodes: [code],
+    warnings: [],
+    errors: [diagnostic],
+    diagnostics: [diagnostic],
+    safeNextActions: [`/memory ${subcommand}`, '/memory doctor'],
+    nextAction: `Inspect /memory doctor diagnostics, then retry /memory ${subcommand}.`,
+  };
+}
+
+function compactMemoryCommandText(envelope) {
+  const list = (values) => Array.isArray(values) && values.length > 0 ? values.join(', ') : 'none';
+  return [
+    `AutoPM memory ${envelope.subcommand}: ${envelope.status}`,
+    `operation: ${envelope.operation ?? 'none'}`,
+    `durableStateChanged: ${envelope.durableStateChanged === true ? 'true' : 'false'}`,
+    `behaviorChanged: ${envelope.behaviorChanged === true ? 'true' : 'false'}`,
+    `artifactPathsRead: ${list(envelope.artifactPathsRead)}`,
+    `artifactPathsWritten: ${list(envelope.artifactPathsWritten)}`,
+    `warnings: ${list(envelope.warningCodes)}`,
+    `errors: ${list(envelope.errorCodes)}`,
+    `nextAction: ${envelope.nextAction ?? 'none'}`,
+  ].join('\n');
+}
+
+function candidateOptionLabel(candidate, index) {
+  const kind = String(candidate?.kind ?? 'candidate').replaceAll('_', ' ');
+  const confidence = Number.isFinite(candidate?.confidence) ? ` ${Math.round(candidate.confidence * 100)}%` : '';
+  const text = String(candidate?.text ?? '').replace(/\s+/g, ' ').trim();
+  const preview = text.length > 72 ? `${text.slice(0, 72).trim()}…` : text;
+  return `${index + 1}. ${kind}${confidence} — ${preview}`;
+}
+
+function nativeMemoryReviewItems(candidates) {
+  const items = [];
+  for (const [index, candidate] of candidates.entries()) {
+    const label = candidateOptionLabel(candidate, index);
+    const candidateId = String(candidate?.candidateId ?? '');
+    if (candidateId === '') continue;
+    const description = [
+      label,
+      `id: ${candidateId}`,
+      String(candidate?.text ?? '').replace(/\s+/g, ' ').trim(),
+    ].filter(Boolean).join('\n');
+    items.push({
+      label: `Accept ${label}`,
+      description,
+      value: `accept:${candidateId}`,
+      args: `accept ${candidateId}`,
+    });
+    items.push({
+      label: `Reject ${label}`,
+      description,
+      value: `reject:${candidateId}`,
+      args: `reject ${candidateId}`,
+    });
+    items.push({
+      label: `Skip ${label}`,
+      description,
+      value: `skip:${candidateId}`,
+      args: `skip ${candidateId}`,
+    });
+  }
+  items.push({
+    label: 'Done reviewing',
+    description: 'Close memory review without changing more candidates.',
+    value: 'done',
+    args: 'done',
+  });
+  return items;
+}
+
+function normalizeNativeMemoryReviewChoice(choice, candidates) {
+  if (!choice || choice.action === 'cancel') return { action: 'done' };
+  if (['accept', 'reject', 'skip', 'done'].includes(choice.action)) {
+    return {
+      action: choice.action,
+      candidateId: choice.candidateId ?? null,
+      reason: choice.reason,
+    };
+  }
+  const raw = typeof choice.value === 'string' && choice.value.trim() !== ''
+    ? choice.value.trim()
+    : typeof choice.args === 'string'
+      ? choice.args.trim().replace(/\s+/, ':')
+      : '';
+  if (raw === 'done') return { action: 'done' };
+  const [action, candidateId] = raw.split(':');
+  if (['accept', 'reject', 'skip'].includes(action) && candidateId) {
+    return { action, candidateId };
+  }
+  const fallback = Array.isArray(candidates) ? candidates[0] : null;
+  if (choice.action === 'run' && fallback?.candidateId) return { action: 'accept', candidateId: fallback.candidateId };
+  return { action: 'done' };
+}
+
+async function runNativeMemoryReviewChoice({ ctx, candidates }) {
+  if (typeof ctx?.ui?.custom !== 'function') return null;
+  const choice = await showAutoPmCommandTui(ctx, {
+    title: 'AutoPM memory review',
+    items: nativeMemoryReviewItems(candidates),
+    searchable: true,
+    footer: 'Enter to choose · Type to search · Esc to close',
+  });
+  return normalizeNativeMemoryReviewChoice(choice, candidates);
+}
+
+function memoryReviewSummaryText(result) {
+  const accepted = result.acceptedCandidateIds.length;
+  const rejected = result.rejectedCandidateIds.length;
+  const skipped = result.skippedCandidateIds.length;
+  const lines = [
+    'AutoPM memory review finished',
+    `accepted: ${accepted}`,
+    `rejected: ${rejected}`,
+    `skipped: ${skipped}`,
+  ];
+  if (result.remainingCandidateCount > 0) lines.push(`remaining: ${result.remainingCandidateCount}`);
+  return lines.join('\n');
+}
+
+async function runInteractiveMemoryReview({ parsed, projectRoot, generatedAt, runOperation, sqliteModule, ctx }) {
+  if (typeof ctx?.ui?.select !== 'function') {
+    return envelopeFromResult({
+      subcommand: 'review',
+      operation: 'candidates',
+      generatedAt,
+      result: {
+        ok: false,
+        status: 'error',
+        generatedAt,
+        durableStateChanged: false,
+        behaviorChanged: false,
+        artifactPathsRead: [],
+        artifactPathsWritten: [],
+        warningCodes: [],
+        errorCodes: ['AUTOPM_MEMORY_REVIEW_UI_UNAVAILABLE'],
+        warnings: [],
+        errors: [{
+          code: 'AUTOPM_MEMORY_REVIEW_UI_UNAVAILABLE',
+          severity: 'error',
+          message: 'Interactive memory review requires Pi ctx.ui.select support.',
+          details: {},
+        }],
+        safeNextActions: ['/memory candidates'],
+      },
+      nextAction: '/memory candidates',
+    });
+  }
+
+  const acceptedCandidateIds = [];
+  const rejectedCandidateIds = [];
+  const skippedCandidateIds = [];
+  const artifactPathsRead = [];
+  const artifactPathsWritten = [];
+  const warningCodes = [];
+  const errorCodes = [];
+  const diagnostics = [];
+  let remainingCandidateCount = 0;
+
+  while (true) {
+    const candidatesEnvelope = await runCoreCommand({
+      parsed: {
+        ...parsed,
+        subcommand: 'candidates',
+        operation: 'candidates',
+        payload: {
+          statuses: parsed.payload.statuses ?? ['pending', 'proposed'],
+          limit: parsed.payload.limit ?? 25,
+          maxTextChars: parsed.payload.maxTextChars ?? 180,
+        },
+      },
+      projectRoot,
+      generatedAt,
+      runOperation,
+      sqliteModule,
+    });
+    artifactPathsRead.push(...candidatesEnvelope.artifactPathsRead);
+    warningCodes.push(...candidatesEnvelope.warningCodes);
+    errorCodes.push(...candidatesEnvelope.errorCodes);
+    diagnostics.push(...candidatesEnvelope.diagnostics);
+
+    const candidates = Array.isArray(candidatesEnvelope.result?.candidates) ? candidatesEnvelope.result.candidates : [];
+    remainingCandidateCount = Number.isInteger(candidatesEnvelope.summary?.totalCandidateCount) ? candidatesEnvelope.summary.totalCandidateCount : candidates.length;
+    if (candidates.length === 0) break;
+
+    const nativeChoice = await runNativeMemoryReviewChoice({ ctx, candidates });
+    let candidate;
+    let action;
+    let explicitReason;
+    if (nativeChoice) {
+      if (nativeChoice.action === 'done') break;
+      action = nativeChoice.action === 'accept' ? 'Accept into memory' : nativeChoice.action === 'reject' ? 'Reject' : 'Skip for now';
+      explicitReason = nativeChoice.reason;
+      candidate = candidates.find((item) => item?.candidateId === nativeChoice.candidateId);
+    } else {
+      const labels = candidates.map(candidateOptionLabel);
+      const doneLabel = 'Done reviewing';
+      const selected = await ctx.ui.select('Review memory candidate', [...labels, doneLabel]);
+      if (!selected || selected === doneLabel) break;
+      const selectedIndex = labels.indexOf(selected);
+      candidate = candidates[selectedIndex];
+      if (!candidate?.candidateId) break;
+
+      const detail = [
+        `${String(candidate.kind ?? 'candidate').replaceAll('_', ' ')} (${candidate.confidence ?? 'unknown'})`,
+        '',
+        candidate.text,
+        '',
+        `id: ${candidate.candidateId}`,
+      ].join('\n');
+      action = await ctx.ui.select(detail, ['Accept into memory', 'Reject', 'Skip for now', 'Done reviewing']);
+      if (!action || action === 'Done reviewing') break;
+    }
+    if (!candidate?.candidateId) break;
+    if (action === 'Skip for now') {
+      skippedCandidateIds.push(candidate.candidateId);
+      continue;
+    }
+
+    const defaultReason = action === 'Accept into memory'
+      ? 'Durable memory candidate confirmed during interactive review.'
+      : 'Not durable or not useful for future recall.';
+    let reason = defaultReason;
+    if (typeof explicitReason === 'string' && explicitReason.trim() !== '') {
+      reason = explicitReason;
+    } else if (!nativeChoice && typeof ctx.ui.input === 'function') {
+      reason = await ctx.ui.input(action === 'Accept into memory' ? 'Reason for accepting memory' : 'Reason for rejecting memory', defaultReason);
+    }
+    const reviewPayload = {
+      candidateId: candidate.candidateId,
+      reviewer: 'operator',
+      reason: typeof reason === 'string' && reason.trim() !== '' ? reason.trim() : defaultReason,
+    };
+    if (action === 'Accept into memory') reviewPayload.tags = ['interactive-review', candidate.kind].filter(Boolean);
+
+    const reviewEnvelope = await runCoreCommand({
+      parsed: {
+        ...parsed,
+        subcommand: action === 'Accept into memory' ? 'accept' : 'reject',
+        operation: action === 'Accept into memory' ? 'accept' : 'reject',
+        payload: reviewPayload,
+      },
+      projectRoot,
+      generatedAt,
+      runOperation,
+      sqliteModule,
+    });
+    artifactPathsRead.push(...reviewEnvelope.artifactPathsRead);
+    artifactPathsWritten.push(...reviewEnvelope.artifactPathsWritten);
+    warningCodes.push(...reviewEnvelope.warningCodes);
+    errorCodes.push(...reviewEnvelope.errorCodes);
+    diagnostics.push(...reviewEnvelope.diagnostics);
+    if (reviewEnvelope.status === 'error') break;
+    if (action === 'Accept into memory') acceptedCandidateIds.push(candidate.candidateId);
+    else rejectedCandidateIds.push(candidate.candidateId);
+  }
+
+  const result = {
+    ok: errorCodes.length === 0,
+    status: errorCodes.length > 0 ? 'error' : 'ok',
+    generatedAt,
+    acceptedCandidateIds,
+    rejectedCandidateIds,
+    skippedCandidateIds,
+    remainingCandidateCount,
+    durableStateChanged: acceptedCandidateIds.length > 0 || rejectedCandidateIds.length > 0,
+    behaviorChanged: acceptedCandidateIds.length > 0,
+    artifactPathsRead: uniqueStrings(artifactPathsRead),
+    artifactPathsWritten: uniqueStrings(artifactPathsWritten),
+    warningCodes: uniqueStrings(warningCodes),
+    errorCodes: uniqueStrings(errorCodes),
+    warnings: diagnostics.filter((item) => item.severity === 'warning'),
+    errors: diagnostics.filter((item) => item.severity === 'error'),
+    diagnostics,
+    safeNextActions: ['/memory recall "product setup"', '/memory rebuild-summaries', '/memory rebuild-wiki'],
+    summary: { accepted: acceptedCandidateIds.length, rejected: rejectedCandidateIds.length, skipped: skippedCandidateIds.length, remaining: remainingCandidateCount },
+    result: { acceptedCandidateIds, rejectedCandidateIds, skippedCandidateIds, remainingCandidateCount },
+  };
+  return envelopeFromResult({ subcommand: 'review', operation: 'review', result, generatedAt, nextAction: '/memory recall "product setup"' });
+}
+
+async function withCommandStore({ projectRoot, sqliteModule }, callback) {
+  const store = await openAutoPmMemoryStore({ projectRoot, sqliteModule, initialize: false });
+  try {
+    return callback(store);
+  } finally {
+    store.close();
+  }
+}
+
+async function runInitCommand({ projectRoot, generatedAt, sqliteModule }) {
+  const result = await initializeAutoPmMemoryWorkspace({ projectRoot, sqliteModule, generatedAt });
+  return envelopeFromResult({
+    subcommand: 'init',
+    operation: 'init',
+    result: {
+      ...result,
+      status: result.status?.status ?? (result.ok === true ? 'ok' : 'error'),
+      summary: {
+        initialized: result.status?.initialized === true,
+        wikiPath: result.paths?.wikiDir ?? null,
+        statusPath: result.statusProjection?.relativePath ?? null,
+      },
+      artifactPathsWritten: uniqueStrings([
+        result.statusProjection?.relativePath,
+        ...(Array.isArray(result.wiki?.artifactPathsWritten) ? result.wiki.artifactPathsWritten : []),
+      ]),
+      warningCodes: result.status?.warningCodes ?? [],
+      errorCodes: result.status?.errorCodes ?? [],
+      warnings: result.status?.warnings ?? [],
+      errors: result.status?.errors ?? [],
+      durableStateChanged: true,
+      behaviorChanged: false,
+    },
+    generatedAt,
+    nextAction: '/memory status',
+    coreResult: result,
+  });
+}
+
+function runOpenVaultCommand({ projectRoot, generatedAt }) {
+  const paths = canonicalAutoPmMemoryPaths(projectRoot);
+  return envelopeFromResult({
+    subcommand: 'open-vault',
+    operation: 'open-vault',
+    generatedAt,
+    result: {
+      ok: true,
+      status: 'ok',
+      generatedAt,
+      durableStateChanged: false,
+      behaviorChanged: false,
+      artifactPathsRead: [],
+      artifactPathsWritten: [],
+      warningCodes: [],
+      errorCodes: [],
+      safeNextActions: [`open ${paths.wikiDirPath}`],
+      summary: { wikiDir: paths.wikiDir, wikiDirPath: paths.wikiDirPath },
+      result: { wikiDir: paths.wikiDir, wikiDirPath: paths.wikiDirPath, relativePath: paths.wikiDir },
+    },
+    nextAction: `Open ${paths.wikiDirPath}`,
+  });
+}
+
+async function runRebuildWikiCommand({ projectRoot, generatedAt, payload, sqliteModule }) {
+  const result = await withCommandStore({ projectRoot, sqliteModule }, (store) => rebuildAutoPmSummaryTreeWikiProjections({
+    store,
+    projectRoot,
+    generatedAt,
+    scopes: payload.scopes ?? [],
+  }));
+  return envelopeFromResult({ subcommand: 'rebuild-wiki', operation: 'rebuild-wiki', result, generatedAt, coreResult: result });
+}
+
+async function runRebuildSummariesCommand({ projectRoot, generatedAt, payload, sqliteModule }) {
+  const result = await withCommandStore({ projectRoot, sqliteModule }, (store) => buildAutoPmSummaryTrees({
+    ...payload,
+    store,
+    projectRoot,
+    generatedAt,
+    trigger: payload.trigger ?? 'memory-command',
+  }));
+  return envelopeFromResult({ subcommand: 'rebuild-summaries', operation: 'rebuild-summaries', result, generatedAt, coreResult: result });
+}
+
+async function runCoreCommand({ parsed, projectRoot, generatedAt, runOperation, sqliteModule }) {
+  const operation = operationForSubcommand(parsed.subcommand);
+  const payload = { ...parsed.payload };
+  delete payload.projectRoot;
+  delete payload.generatedAt;
+  const result = await runOperation({ operation, payload, projectRoot, generatedAt, sqliteModule });
+  return envelopeFromResult({ subcommand: parsed.subcommand, operation, result, generatedAt, json: parsed.json, coreResult: result });
+}
+
+export async function executeMemoryCommand(args = '', options = {}) {
+  const parsed = parseMemoryCommandArgs(args);
+  const projectRoot = path.resolve(parsed.payload.projectRoot ?? options.projectRoot ?? process.cwd());
+  const generatedAt = nowIso(parsed.payload.generatedAt ?? options.generatedAt);
+  const runOperation = typeof options.runOperation === 'function' ? options.runOperation : runAutoPmMemoryOperation;
+  const sqliteModule = options.sqliteModule;
+
+  if (parsed.help) {
+    return {
+      command: AUTOPM_MEMORY_COMMAND_NAME,
+      subcommand: 'help',
+      operation: null,
+      implemented: true,
+      status: 'ok',
+      ok: true,
+      generatedAt,
+      durableStateChanged: false,
+      behaviorChanged: false,
+      artifactPathsRead: [],
+      artifactPathsWritten: [],
+      warningCodes: [],
+      errorCodes: [],
+      warnings: [],
+      errors: [],
+      diagnostics: [],
+      safeNextActions: ['/memory status'],
+      nextAction: memoryCommandUsageText(),
+      usage: memoryCommandUsageText(),
+    };
+  }
+
+  if (!parsed.ok) return argumentFailureEnvelope(parsed, generatedAt);
+
+  try {
+    if (options.signal?.aborted) throw Object.assign(new Error('Memory command aborted before execution.'), { name: 'AbortError' });
+    if (parsed.subcommand === 'init') return runInitCommand({ projectRoot, generatedAt, sqliteModule });
+    if (parsed.subcommand === 'open-vault') return runOpenVaultCommand({ projectRoot, generatedAt });
+    if (parsed.subcommand === 'rebuild-wiki') return runRebuildWikiCommand({ projectRoot, generatedAt, payload: parsed.payload, sqliteModule });
+    if (parsed.subcommand === 'rebuild-summaries') return runRebuildSummariesCommand({ projectRoot, generatedAt, payload: parsed.payload, sqliteModule });
+    const envelope = await runCoreCommand({ parsed, projectRoot, generatedAt, runOperation, sqliteModule });
+    if (options.signal?.aborted) throw Object.assign(new Error('Memory command aborted after execution.'), { name: 'AbortError' });
+    return envelope;
+  } catch (error) {
+    return failureEnvelope({ subcommand: parsed.subcommand, operation: parsed.operation, generatedAt, error });
+  }
+}
+
+export function createAutoPmMemoryCommandHandler({ projectRoot, runOperation, notify = true, sqliteModule } = {}) {
+  return async function handleAutoPmMemoryCommand(args = '', ctx = {}) {
+    const resolvedProjectRoot = typeof projectRoot === 'function'
+      ? projectRoot(ctx)
+      : (typeof projectRoot === 'string' && projectRoot.trim() !== '' ? projectRoot : ctx?.cwd ?? process.cwd());
+    const parsed = parseMemoryCommandArgs(args);
+    const generatedAt = nowIso(parsed.payload.generatedAt);
+    let result;
+    if (parsed.ok && parsed.subcommand === 'review' && parsed.json !== true) {
+      result = await runInteractiveMemoryReview({
+        parsed,
+        projectRoot: path.resolve(parsed.payload.projectRoot ?? resolvedProjectRoot),
+        generatedAt,
+        runOperation: typeof runOperation === 'function' ? runOperation : runAutoPmMemoryOperation,
+        sqliteModule,
+        ctx,
+      });
+    } else {
+      result = await executeMemoryCommand(args, {
+        projectRoot: resolvedProjectRoot,
+        runOperation,
+        sqliteModule,
+        signal: ctx?.signal,
+      });
+    }
+    if (notify !== false && typeof ctx?.ui?.notify === 'function') {
+      const text = result.subcommand === 'review' && parsed.json !== true
+        ? memoryReviewSummaryText({
+          acceptedCandidateIds: result.result?.acceptedCandidateIds ?? [],
+          rejectedCandidateIds: result.result?.rejectedCandidateIds ?? [],
+          skippedCandidateIds: result.result?.skippedCandidateIds ?? [],
+          remainingCandidateCount: result.result?.remainingCandidateCount ?? 0,
+        })
+        : result.json === true ? JSON.stringify(result, null, 2) : compactMemoryCommandText(result);
+      try {
+        ctx.ui.notify(text, severityFromEnvelope(result));
+      } catch {
+        // Optional UI notification failures must not fail command execution.
+      }
+    }
+    return result;
+  };
+}
+
+export function memoryCommandCompletions(prefix = '') {
+  const trimmed = String(prefix ?? '').trim().toLowerCase();
+  const completions = [
+    'status',
+    'doctor',
+    'ingest --source-path ',
+    'recall ',
+    'search ',
+    'get accepted_memory ',
+    'candidates',
+    'review',
+    'accept ',
+    'reject ',
+    'forget ',
+    'supersede --supersedes-memory-id ',
+    'rebuild-wiki',
+    'rebuild-summaries',
+    'scheduler status',
+    'scheduler start',
+    'scheduler stop',
+    'scheduler pause',
+    'scheduler resume',
+    'scheduler tick',
+    'open-vault',
+  ];
+  return completions
+    .filter((value) => value.startsWith(trimmed))
+    .map((value) => ({ value, label: value, description: 'AutoPM memory command' }));
+}