@jacfrost/autopm 0.0.1

package/src/autopm/memory/operations.js

@@ -0,0 +1,931 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+import {
+  forgetAcceptedMemory,
+  reviewMemoryCandidate,
+} from './accepted-memory.js';
+import {
+  generateMemoryCandidates,
+} from './candidates.js';
+import {
+  AUTOPM_MEMORY_SCHEMA_VERSION,
+  memoryDiagnostic,
+  redactMemoryText,
+  redactMemoryValue,
+  validateAcceptedMemoryEnvelope,
+} from './contracts.js';
+import {
+  drilldownAutoPmMemoryEvidence,
+  fetchAutoPmMemoryArtifact,
+  getAutoPmMemoryRecord,
+} from './get.js';
+import {
+  ingestAutoPmMemorySources,
+} from './ingest.js';
+import {
+  AUTOPM_MEMORY_DB_PATH,
+} from './paths.js';
+import {
+  AUTOPM_MEMORY_LAST_RECALL_PATH,
+  recallAutoPmMemory,
+} from './recall.js';
+import {
+  getAutoPmMemorySchedulerDiagnostics,
+  pauseAutoPmMemoryScheduler,
+  recoverAutoPmMemorySchedulerOnRestart,
+  resumeAutoPmMemoryScheduler,
+  runAutoPmMemorySchedulerOneShot,
+  startAutoPmMemoryScheduler,
+  stopAutoPmMemoryScheduler,
+  tickAutoPmMemoryScheduler,
+} from './scheduler.js';
+import {
+  ensureAutoPmMemorySearchIndex,
+  searchAutoPmMemory,
+} from './search.js';
+import {
+  doctorAutoPmMemorySubstrate,
+} from './doctor.js';
+import {
+  inspectAutoPmMemorySubstrate,
+} from './status.js';
+import {
+  openAutoPmMemoryStore,
+} from './store.js';
+
+export const AUTOPM_MEMORY_OPERATION_VERSION = 1;
+
+export const AUTOPM_MEMORY_OPERATION_NAMES = Object.freeze([
+  'status',
+  'recall',
+  'search',
+  'get',
+  'remember',
+  'ingest',
+  'capture',
+  'candidates',
+  'accept',
+  'reject',
+  'forget',
+  'rebuild',
+  'scheduler',
+  'doctor',
+]);
+
+const DEFAULT_CANDIDATE_LIMIT = 50;
+const MAX_CANDIDATE_LIMIT = 200;
+const DEFAULT_CANDIDATE_STATUSES = Object.freeze(['pending', 'proposed']);
+const DEFAULT_REMEMBER_CONFIDENCE = 0.74;
+const VALID_REMEMBER_KINDS = new Set([
+  'fact',
+  'product_fact',
+  'preference',
+  'anti_preference',
+  'decision',
+  'runbook',
+  'pattern',
+  'gotcha',
+  'warning',
+  'open_question',
+  'follow_up',
+  'summary',
+]);
+
+function nowIso(value = undefined) {
+  return typeof value === 'string' && value.length > 0 ? value : new Date().toISOString();
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function diagnostic({ severity = 'info', code, message, path: diagnosticPath = '$', details = {} }) {
+  return memoryDiagnostic({ severity, code, message, path: diagnosticPath, details });
+}
+
+function uniqueStrings(values) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .map((value) => String(value ?? '').trim())
+    .filter((value) => value.length > 0))];
+}
+
+function normalizeText(value) {
+  return redactMemoryText(String(value ?? '')).replace(/\s+/g, ' ').trim();
+}
+
+function stableHash(value, length = 24) {
+  return crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, length);
+}
+
+function normalizedRememberKind(value) {
+  const kind = String(value ?? 'fact').trim().toLowerCase();
+  return VALID_REMEMBER_KINDS.has(kind) ? kind : 'fact';
+}
+
+function normalizedRememberConfidence(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_REMEMBER_CONFIDENCE;
+  return Math.max(0, Math.min(1, parsed));
+}
+
+function freezeArray(values) {
+  return Object.freeze([...values]);
+}
+
+function normalizeOperationName(operation) {
+  const normalized = String(operation ?? '').trim().toLowerCase().replaceAll('_', '-');
+  const aliases = new Map([
+    ['list-candidates', 'candidates'],
+    ['candidate-list', 'candidates'],
+    ['review-queue', 'candidates'],
+    ['review-candidates', 'candidates'],
+    ['candidate-capture', 'capture'],
+    ['memory-capture', 'capture'],
+    ['recall-memory', 'recall'],
+    ['search-memory', 'search'],
+    ['get-memory', 'get'],
+    ['memory-get', 'get'],
+    ['direct-remember', 'remember'],
+    ['remember-memory', 'remember'],
+    ['memory-remember', 'remember'],
+    ['memory-status', 'status'],
+    ['memory-doctor', 'doctor'],
+    ['doctor-memory', 'doctor'],
+    ['memory-ingest', 'ingest'],
+    ['memory-rebuild', 'rebuild'],
+    ['memory-scheduler', 'scheduler'],
+  ]);
+  return aliases.get(normalized) ?? normalized;
+}
+
+function normalizeLimit(value, fallback = DEFAULT_CANDIDATE_LIMIT, max = MAX_CANDIDATE_LIMIT) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.max(1, Math.min(max, Math.trunc(parsed)));
+}
+
+function normalizeStringList(value, fallback = []) {
+  if (value === undefined || value === null) return [...fallback];
+  const values = Array.isArray(value) ? value : [value];
+  return uniqueStrings(values).map((item) => item.toLowerCase());
+}
+
+function diagnosticsFromResult(result) {
+  if (!result || typeof result !== 'object') return [];
+  return [
+    ...(Array.isArray(result.diagnostics) ? result.diagnostics : []),
+    ...(Array.isArray(result.warnings) ? result.warnings : []),
+    ...(Array.isArray(result.errors) ? result.errors : []),
+    ...(Array.isArray(result.disabledActions) ? result.disabledActions : []),
+    ...(Array.isArray(result.schemaDiagnostics) ? result.schemaDiagnostics : []),
+    ...(Array.isArray(result.pathDiagnostics) ? result.pathDiagnostics : []),
+    ...(Array.isArray(result.redactionDiagnostics) ? result.redactionDiagnostics : []),
+  ];
+}
+
+function warningCodesFrom(diagnostics, result = {}) {
+  return uniqueStrings([
+    ...(Array.isArray(result.warningCodes) ? result.warningCodes : []),
+    ...diagnostics.filter((item) => item?.severity === 'warning').map((item) => item.code),
+  ]);
+}
+
+function errorCodesFrom(diagnostics, result = {}) {
+  return uniqueStrings([
+    ...(Array.isArray(result.errorCodes) ? result.errorCodes : []),
+    ...diagnostics.filter((item) => item?.severity === 'error').map((item) => item.code),
+  ]);
+}
+
+function operationStatusValue(result) {
+  if (typeof result?.status === 'string') return result.status;
+  if (typeof result?.phase === 'string') return result.phase;
+  if (typeof result?.status?.status === 'string') return result.status.status;
+  if (typeof result?.mode === 'string') return result.mode;
+  return null;
+}
+
+function normalizedEnvelopeStatus({ result, warningCodes, errorCodes }) {
+  const operationStatus = operationStatusValue(result);
+  if (errorCodes.length > 0 || result?.ok === false) {
+    if (operationStatus === 'missing' || operationStatus === 'partial' || operationStatus === 'blocked') return operationStatus;
+    return 'error';
+  }
+  if (operationStatus === 'missing' || operationStatus === 'partial' || operationStatus === 'blocked') return operationStatus;
+  if (warningCodes.length > 0 || operationStatus === 'warn') return 'warn';
+  return 'ok';
+}
+
+function resultOk(result, status) {
+  if (typeof result?.ok === 'boolean') return result.ok;
+  return status !== 'error' && status !== 'blocked';
+}
+
+function defaultSafeNextActions(operation, status) {
+  const suffix = status === 'error' || status === 'blocked' ? '' : '';
+  const actions = {
+    status: ['/memory status', '/memory doctor'],
+    recall: ['/memory recall', '/memory get <recordType> <recordId>'],
+    search: ['/memory search <query>', '/memory get <recordType> <recordId>'],
+    get: ['/memory get <recordType> <recordId>', '/memory search <query>'],
+    remember: ['/memory recall', '/memory forget <memoryId>'],
+    ingest: ['/memory ingest', '/memory status'],
+    capture: ['/memory candidates', '/memory accept <candidateId>'],
+    candidates: ['/memory candidates', '/memory accept <candidateId>', '/memory reject <candidateId>'],
+    accept: ['/memory recall', '/memory forget <memoryId>'],
+    reject: ['/memory candidates', '/memory search --recordType candidate'],
+    forget: ['/memory recall', '/memory search --recordType accepted_memory'],
+    rebuild: ['/memory search <query>', '/memory status'],
+    scheduler: ['/memory scheduler status', '/memory scheduler tick'],
+    doctor: ['/memory doctor', '/memory status'],
+  };
+  return Object.freeze(actions[operation] ?? [`/memory ${operation}${suffix}`]);
+}
+
+function relativeToProject(projectRoot, targetPath) {
+  if (typeof targetPath !== 'string' || targetPath.length === 0) return null;
+  if (!projectRoot || !path.isAbsolute(targetPath)) return targetPath;
+  const relative = path.relative(projectRoot, targetPath).replaceAll(path.sep, '/');
+  if (relative.startsWith('..') || path.isAbsolute(relative)) return targetPath;
+  return relative === '' ? '.' : relative;
+}
+
+function artifactPathsFromResult({ operation, result, store, projectRoot }) {
+  const pathsRead = [];
+  const pathsWritten = [];
+  const root = store?.paths?.projectRoot ?? projectRoot;
+
+  if (store?.paths?.database) pathsRead.push(store.paths.database);
+  if (Array.isArray(result?.artifactPathsRead)) pathsRead.push(...result.artifactPathsRead);
+  if (Array.isArray(result?.artifactPathsWritten)) pathsWritten.push(...result.artifactPathsWritten);
+
+  if (result?.lastRecall?.relativePath) pathsWritten.push(result.lastRecall.relativePath);
+  if (result?.lastIngestProjection?.relativePath) pathsWritten.push(result.lastIngestProjection.relativePath);
+  if (result?.statusProjection?.relativePath) pathsWritten.push(result.statusProjection.relativePath);
+  if (result?.statusProjection?.relativePath && operation === 'status') pathsWritten.push(result.statusProjection.relativePath);
+
+  if (operation === 'recall' && result?.durableStateChanged === true) pathsWritten.push(`.autopm/memory/${AUTOPM_MEMORY_LAST_RECALL_PATH}`);
+  if ((operation === 'rebuild' || operation === 'search') && result?.durableStateChanged === true) pathsWritten.push(store?.paths?.database ?? AUTOPM_MEMORY_DB_PATH);
+  if ((operation === 'accept' || operation === 'reject' || operation === 'forget' || operation === 'capture' || operation === 'scheduler') && result?.durableStateChanged === true) {
+    pathsWritten.push(store?.paths?.database ?? AUTOPM_MEMORY_DB_PATH);
+  }
+  if (operation === 'get' && result?.artifact?.path && result.ok === true) pathsRead.push(result.artifact.path);
+  if (result?.artifactPath) pathsWritten.push(relativeToProject(root, result.artifactPath));
+
+  return {
+    artifactPathsRead: freezeArray(uniqueStrings(pathsRead.map((item) => relativeToProject(root, item)).filter(Boolean))),
+    artifactPathsWritten: freezeArray(uniqueStrings(pathsWritten.map((item) => relativeToProject(root, item)).filter(Boolean))),
+  };
+}
+
+function behaviorChangedFromResult(result) {
+  if (typeof result?.behaviorChanged === 'boolean') return result.behaviorChanged;
+  if (typeof result?.acceptedMemory?.behaviorChanged === 'boolean') return result.acceptedMemory.behaviorChanged;
+  if (typeof result?.summary?.behaviorChangedCount === 'number') return result.summary.behaviorChangedCount > 0;
+  return false;
+}
+
+function buildOperationEnvelope({ operation, generatedAt, result, store = null, projectRoot = process.cwd(), safeNextActions = null, extraDiagnostics = [] }) {
+  const diagnostics = freezeArray([...diagnosticsFromResult(result), ...extraDiagnostics]);
+  const warnings = freezeArray(diagnostics.filter((item) => item?.severity === 'warning'));
+  const errors = freezeArray(diagnostics.filter((item) => item?.severity === 'error'));
+  const warningCodes = freezeArray(warningCodesFrom(diagnostics, result));
+  const errorCodes = freezeArray(errorCodesFrom(diagnostics, result));
+  const status = normalizedEnvelopeStatus({ result, warningCodes, errorCodes });
+  const artifactPaths = artifactPathsFromResult({ operation, result, store, projectRoot });
+  const nextActions = safeNextActions
+    ?? (Array.isArray(result?.safeNextActions) ? result.safeNextActions : null)
+    ?? (Array.isArray(result?.status?.safeNextActions) ? result.status.safeNextActions : null)
+    ?? defaultSafeNextActions(operation, status);
+
+  return Object.freeze({
+    ok: resultOk(result, status),
+    status,
+    operationStatus: operationStatusValue(result),
+    operation,
+    generatedAt,
+    version: AUTOPM_MEMORY_OPERATION_VERSION,
+    warningCodes,
+    errorCodes,
+    durableStateChanged: result?.durableStateChanged === true,
+    behaviorChanged: behaviorChangedFromResult(result),
+    artifactPathsRead: artifactPaths.artifactPathsRead,
+    artifactPathsWritten: artifactPaths.artifactPathsWritten,
+    safeNextActions: freezeArray(nextActions),
+    summary: result?.summary ?? result?.counts ?? null,
+    result: redactMemoryValue(result ?? null),
+    diagnostics,
+    warnings,
+    errors,
+  });
+}
+
+function errorEnvelope({ operation, generatedAt, error, projectRoot = process.cwd() }) {
+  const item = diagnostic({
+    severity: 'error',
+    code: error?.code ?? 'AUTOPM_MEMORY_OPERATION_FAILED',
+    message: error instanceof Error ? error.message : String(error ?? 'AutoPM memory operation failed.'),
+    details: error?.details ?? { operation },
+  });
+  return buildOperationEnvelope({
+    operation,
+    generatedAt,
+    projectRoot,
+    result: Object.freeze({
+      ok: false,
+      status: 'error',
+      diagnostics: Object.freeze([item]),
+      durableStateChanged: false,
+      behaviorChanged: false,
+    }),
+  });
+}
+
+async function withMemoryStore({ store, projectRoot, sqliteModule, initialize = true }, fn) {
+  if (store) return fn(store, false);
+  const owned = await openAutoPmMemoryStore({ projectRoot, sqliteModule, initialize });
+  try {
+    return await fn(owned, true);
+  } finally {
+    owned.close();
+  }
+}
+
+function readJsonText(text) {
+  if (typeof text !== 'string') return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function compactCandidate(candidate, maxTextChars) {
+  const text = redactMemoryText(String(candidate?.text ?? '').replace(/\s+/g, ' ').trim());
+  const truncated = text.length > maxTextChars;
+  return Object.freeze({
+    recordType: 'candidate',
+    candidateId: candidate.candidateId,
+    kind: candidate.kind,
+    status: candidate.status,
+    confidence: candidate.confidence,
+    proposedAt: candidate.proposedAt,
+    sourceChunkIds: freezeArray(candidate.sourceChunkIds ?? []),
+    text: truncated ? `${text.slice(0, maxTextChars).trim()}…` : text,
+    textTruncated: truncated,
+    fullRecordFetch: Object.freeze({ recordType: 'candidate', recordId: candidate.candidateId }),
+  });
+}
+
+function listMemoryCandidates({ store, statuses = DEFAULT_CANDIDATE_STATUSES, limit = DEFAULT_CANDIDATE_LIMIT, maxTextChars = 320, generatedAt = nowIso() } = {}) {
+  const normalizedStatuses = normalizeStringList(statuses, DEFAULT_CANDIDATE_STATUSES);
+  const normalizedLimit = normalizeLimit(limit);
+  const rows = store.db.prepare('SELECT candidate_id, status, envelope_json FROM candidates ORDER BY proposed_at ASC, candidate_id ASC').all();
+  const diagnostics = [];
+  const candidates = [];
+
+  rows.forEach((row, index) => {
+    const envelope = readJsonText(row.envelope_json);
+    if (!envelope) {
+      diagnostics.push(diagnostic({
+        severity: 'warning',
+        code: 'AUTOPM_MEMORY_OPERATION_CANDIDATE_MALFORMED',
+        message: 'Memory candidate queue skipped a malformed candidate row.',
+        path: `$.candidates[${index}]`,
+        details: { candidateId: row.candidate_id },
+      }));
+      return;
+    }
+    if (normalizedStatuses.length > 0 && !normalizedStatuses.includes(String(envelope.status ?? row.status).toLowerCase())) return;
+    candidates.push(compactCandidate(envelope, maxTextChars));
+  });
+
+  const limited = candidates.slice(0, normalizedLimit);
+  const truncated = candidates.length > limited.length;
+  if (truncated) {
+    diagnostics.push(diagnostic({
+      severity: 'warning',
+      code: 'AUTOPM_MEMORY_OPERATION_CANDIDATES_TRUNCATED',
+      message: 'Memory candidate queue output was truncated by the requested limit.',
+      details: { limit: normalizedLimit, totalCandidateCount: candidates.length },
+    }));
+  }
+
+  diagnostics.push(diagnostic({
+    severity: 'info',
+    code: 'AUTOPM_MEMORY_OPERATION_CANDIDATES_LISTED',
+    message: 'Memory candidate review queue was listed.',
+    details: { statuses: normalizedStatuses, resultCount: limited.length, totalCandidateCount: candidates.length },
+  }));
+
+  const warnings = diagnostics.filter((item) => item.severity === 'warning');
+  return Object.freeze({
+    ok: true,
+    status: warnings.length > 0 ? 'warn' : 'ok',
+    generatedAt,
+    statuses: freezeArray(normalizedStatuses),
+    candidates: freezeArray(limited),
+    summary: Object.freeze({
+      resultCount: limited.length,
+      totalCandidateCount: candidates.length,
+      truncated,
+      statuses: freezeArray(normalizedStatuses),
+    }),
+    diagnostics: freezeArray(diagnostics),
+    warnings: freezeArray(warnings),
+    errors: freezeArray([]),
+    warningCodes: freezeArray(uniqueStrings(warnings.map((item) => item.code))),
+    errorCodes: freezeArray([]),
+    durableStateChanged: false,
+    behaviorChanged: false,
+  });
+}
+
+function missingRecordResult({ recordType, recordId, generatedAt }) {
+  const diagnostics = [diagnostic({
+    severity: 'error',
+    code: 'AUTOPM_MEMORY_OPERATION_RECORD_MISSING',
+    message: 'AutoPM memory operation could not find the requested record.',
+    details: { recordType, recordId },
+  })];
+  return Object.freeze({
+    ok: false,
+    status: 'missing',
+    generatedAt,
+    recordType,
+    recordId,
+    diagnostics: freezeArray(diagnostics),
+    warnings: freezeArray([]),
+    errors: freezeArray(diagnostics),
+    warningCodes: freezeArray([]),
+    errorCodes: freezeArray(['AUTOPM_MEMORY_OPERATION_RECORD_MISSING']),
+    durableStateChanged: false,
+    behaviorChanged: false,
+  });
+}
+
+function fetchCandidateForReview({ store, candidate, candidateId, generatedAt }) {
+  if (candidate && typeof candidate === 'object') return candidate;
+  if (typeof candidateId === 'string' && candidateId.length > 0) return store.getEnvelope('candidate', candidateId);
+  return missingRecordResult({ recordType: 'candidate', recordId: candidateId ?? null, generatedAt });
+}
+
+function fetchMemoryForLifecycle({ store, memory, memoryId, acceptedMemoryId, generatedAt }) {
+  if (memory && typeof memory === 'object') return memory;
+  const id = memoryId ?? acceptedMemoryId;
+  if (typeof id === 'string' && id.length > 0) return store.getEnvelope('accepted_memory', id);
+  return missingRecordResult({ recordType: 'accepted_memory', recordId: id ?? null, generatedAt });
+}
+
+function rememberValidationError({ generatedAt, diagnostics }) {
+  return Object.freeze({
+    ok: false,
+    status: 'error',
+    action: 'remember',
+    rememberedAt: generatedAt,
+    acceptedMemory: null,
+    durableStateChanged: false,
+    behaviorChanged: false,
+    diagnostics: freezeArray(diagnostics),
+    errors: freezeArray(diagnostics),
+    errorCodes: freezeArray(uniqueStrings(diagnostics.map((item) => item.code))),
+    summary: Object.freeze({
+      acceptedMemoryCount: 0,
+      auditEventCount: 0,
+      behaviorChangedCount: 0,
+      validationErrorCount: diagnostics.length,
+    }),
+  });
+}
+
+function directRememberAudit({ payload, generatedAt, sourceChunkIds }) {
+  return Object.freeze({
+    workflow: 'autopm-memory-direct-remember',
+    workflowVersion: 1,
+    actor: normalizeText(payload.actor) || 'agent',
+    reason: normalizeText(payload.reason) || 'agent direct memory capture',
+    rememberedAt: generatedAt,
+    sourceChunkIds: freezeArray(sourceChunkIds),
+    extra: isPlainObject(payload.metadata) ? redactMemoryValue(payload.metadata) : {},
+  });
+}
+
+function directRememberCandidate({ payload, generatedAt }) {
+  const text = normalizeText(payload.text);
+  if (text.length === 0) {
+    const diagnostics = [diagnostic({
+      severity: 'error',
+      code: 'AUTOPM_MEMORY_REMEMBER_TEXT_REQUIRED',
+      message: 'Direct memory capture requires non-empty text.',
+      path: '$.text',
+    })];
+    return { ok: false, result: rememberValidationError({ generatedAt, diagnostics }) };
+  }
+
+  const kind = normalizedRememberKind(payload.kind);
+  const actor = normalizeText(payload.actor) || 'agent';
+  const fingerprint = stableHash(`${kind}\n${text.toLowerCase()}\n${actor}`);
+  const sourceHandle = stableHash(`${kind}\n${text.toLowerCase()}\n${actor}`, 12);
+  const sourceChunkIds = uniqueStrings(payload.sourceChunkIds).length > 0
+    ? uniqueStrings(payload.sourceChunkIds)
+    : [`chunk-remember-${sourceHandle}`];
+  const audit = directRememberAudit({ payload: { ...payload, actor }, generatedAt, sourceChunkIds });
+  return {
+    ok: true,
+    audit,
+    candidate: Object.freeze({
+      schemaVersion: AUTOPM_MEMORY_SCHEMA_VERSION,
+      recordType: 'candidate',
+      candidateId: `candidate-remember-${fingerprint}`,
+      kind,
+      text,
+      confidence: normalizedRememberConfidence(payload.confidence),
+      rationale: audit.reason,
+      status: 'pending',
+      proposedAt: generatedAt,
+      sourceChunkIds: freezeArray(sourceChunkIds),
+      durableStateChanged: true,
+      behaviorChanged: false,
+      metadata: Object.freeze({
+        directRemember: audit,
+      }),
+      diagnostics: freezeArray([diagnostic({
+        severity: 'info',
+        code: 'AUTOPM_MEMORY_REMEMBER_CAPTURED',
+        message: 'Agent-authored memory was captured for direct acceptance.',
+        details: { candidateId: `candidate-remember-${fingerprint}`, actor },
+      })]),
+    }),
+  };
+}
+
+function resultForInvalidRememberedMemory({ acceptedMemory, generatedAt }) {
+  const validation = validateAcceptedMemoryEnvelope(acceptedMemory, '$.acceptedMemory');
+  if (validation.ok) return null;
+  const diagnostics = [diagnostic({
+    severity: 'error',
+    code: 'AUTOPM_MEMORY_REMEMBER_ACCEPTED_MEMORY_INVALID',
+    message: 'Direct memory capture produced an invalid accepted memory envelope.',
+    details: { validationErrors: validation.errors },
+  })];
+  return rememberValidationError({ generatedAt, diagnostics });
+}
+
+function persistGeneratedCandidates({ store, candidates, generatedAt }) {
+  if (!store || candidates.length === 0) return { persistedCandidateIds: [], diagnostics: [] };
+  const persistedCandidateIds = [];
+  const diagnostics = [];
+  store.transaction((writer) => {
+    for (const candidate of candidates) {
+      writer.writeEnvelope(candidate);
+      persistedCandidateIds.push(candidate.candidateId);
+    }
+  });
+  diagnostics.push(diagnostic({
+    severity: 'info',
+    code: 'AUTOPM_MEMORY_OPERATION_CAPTURE_PERSISTED',
+    message: 'Generated memory candidates were persisted to the review queue.',
+    details: { candidateCount: persistedCandidateIds.length, generatedAt },
+  }));
+  return { persistedCandidateIds, diagnostics };
+}
+
+async function runStatusOperation({ payload, projectRoot, sqliteModule, generatedAt }) {
+  const result = await inspectAutoPmMemorySubstrate({ projectRoot, sqliteModule, generatedAt });
+  return buildOperationEnvelope({ operation: 'status', generatedAt, result, projectRoot, safeNextActions: result.safeNextActions });
+}
+
+async function runDoctorOperation({ payload, projectRoot, sqliteModule, generatedAt }) {
+  const result = await doctorAutoPmMemorySubstrate({ projectRoot, sqliteModule, generatedAt, durableStateChanged: false, ...(payload ?? {}) });
+  return buildOperationEnvelope({ operation: 'doctor', generatedAt, result, projectRoot, safeNextActions: result.safeNextActions });
+}
+
+async function runRecallOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const result = recallAutoPmMemory({ ...payload, store: activeStore, generatedAt: payload.generatedAt ?? generatedAt });
+    return buildOperationEnvelope({ operation: 'recall', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runSearchOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const result = searchAutoPmMemory({ ...payload, store: activeStore, generatedAt: payload.generatedAt ?? generatedAt });
+    return buildOperationEnvelope({ operation: 'search', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runGetOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const result = payload.artifactPath
+      ? fetchAutoPmMemoryArtifact({ ...payload, store: activeStore, generatedAt: payload.generatedAt ?? generatedAt })
+      : payload.evidenceOnly || payload.drilldown
+        ? drilldownAutoPmMemoryEvidence({ ...payload, store: activeStore, generatedAt: payload.generatedAt ?? generatedAt })
+        : getAutoPmMemoryRecord({ ...payload, store: activeStore, generatedAt: payload.generatedAt ?? generatedAt });
+    return buildOperationEnvelope({ operation: 'get', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runRememberOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const direct = directRememberCandidate({ payload, generatedAt });
+    if (!direct.ok) {
+      return buildOperationEnvelope({ operation: 'remember', generatedAt, result: direct.result, store: activeStore, projectRoot });
+    }
+
+    const review = reviewMemoryCandidate({
+      candidate: direct.candidate,
+      action: 'accept',
+      store: null,
+      reviewer: direct.audit.actor,
+      reason: direct.audit.reason,
+      now: generatedAt,
+      tags: payload.tags ?? [],
+      supersedesMemoryIds: payload.supersedesMemoryIds ?? [],
+    });
+    if (review.ok !== true) {
+      return buildOperationEnvelope({ operation: 'remember', generatedAt, result: review, store: activeStore, projectRoot });
+    }
+
+    const acceptedMemory = Object.freeze({
+      ...review.acceptedMemory,
+      metadata: Object.freeze({
+        ...review.acceptedMemory.metadata,
+        directRemember: direct.audit,
+      }),
+    });
+    const invalid = resultForInvalidRememberedMemory({ acceptedMemory, generatedAt });
+    if (invalid) {
+      return buildOperationEnvelope({ operation: 'remember', generatedAt, result: invalid, store: activeStore, projectRoot });
+    }
+
+    activeStore.transaction((writer) => {
+      writer.writeEnvelope(review.candidate);
+      writer.writeEnvelope(acceptedMemory);
+      writer.appendEvent(review.auditEvent);
+    });
+
+    const result = Object.freeze({
+      ...review,
+      action: 'remember',
+      rememberedAt: generatedAt,
+      acceptedMemory,
+      durableStateChanged: true,
+      behaviorChanged: true,
+      diagnostics: freezeArray([
+        ...review.diagnostics,
+        diagnostic({
+          severity: 'info',
+          code: 'AUTOPM_MEMORY_REMEMBER_ACCEPTED',
+          message: 'Agent-authored memory was persisted directly into active accepted memory.',
+          details: { memoryId: acceptedMemory.memoryId, actor: direct.audit.actor },
+        }),
+      ]),
+      summary: Object.freeze({
+        ...review.summary,
+        directRememberCount: 1,
+      }),
+    });
+    return buildOperationEnvelope({ operation: 'remember', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runIngestOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  const result = await ingestAutoPmMemorySources({
+    ...payload,
+    projectRoot,
+    store,
+    sqliteModule,
+    generatedAt: payload.generatedAt ?? generatedAt,
+  });
+  return buildOperationEnvelope({ operation: 'ingest', generatedAt, result, store, projectRoot });
+}
+
+async function runCaptureOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const generated = generateMemoryCandidates({
+      scoredChunks: payload.scoredChunks ?? [],
+      chunks: payload.chunks ?? [],
+      chunkById: payload.chunkById ?? null,
+      now: payload.now ?? payload.generatedAt ?? generatedAt,
+    });
+    const persist = payload.persist !== false;
+    const persisted = persist ? persistGeneratedCandidates({ store: activeStore, candidates: generated.candidates, generatedAt }) : { persistedCandidateIds: [], diagnostics: [] };
+    const diagnostics = [...generated.diagnostics, ...persisted.diagnostics];
+    const warnings = diagnostics.filter((item) => item.severity === 'warning');
+    const errors = diagnostics.filter((item) => item.severity === 'error');
+    const result = Object.freeze({
+      ...generated,
+      status: errors.length > 0 ? 'error' : warnings.length > 0 ? 'warn' : 'ok',
+      candidates: freezeArray(generated.candidates.map((candidate) => redactMemoryValue(candidate))),
+      persistedCandidateIds: freezeArray(persisted.persistedCandidateIds),
+      diagnostics: freezeArray(diagnostics),
+      warnings: freezeArray(warnings),
+      errors: freezeArray(errors),
+      warningCodes: freezeArray(uniqueStrings(warnings.map((item) => item.code))),
+      errorCodes: freezeArray(uniqueStrings(errors.map((item) => item.code))),
+      durableStateChanged: persisted.persistedCandidateIds.length > 0,
+      behaviorChanged: false,
+      summary: Object.freeze({
+        ...generated.summary,
+        persistedCandidateCount: persisted.persistedCandidateIds.length,
+      }),
+    });
+    return buildOperationEnvelope({ operation: 'capture', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runCandidatesOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const result = listMemoryCandidates({ ...payload, store: activeStore, generatedAt: payload.generatedAt ?? generatedAt });
+    return buildOperationEnvelope({ operation: 'candidates', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runReviewOperation({ operation, payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const candidate = fetchCandidateForReview({ store: activeStore, candidate: payload.candidate, candidateId: payload.candidateId, generatedAt });
+    const result = candidate?.ok === false
+      ? candidate
+      : reviewMemoryCandidate({
+        ...payload,
+        candidate,
+        action: operation,
+        store: activeStore,
+        now: payload.now ?? payload.reviewedAt ?? payload.generatedAt ?? generatedAt,
+      });
+    return buildOperationEnvelope({ operation, generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runForgetOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const memory = fetchMemoryForLifecycle({
+      store: activeStore,
+      memory: payload.memory ?? payload.acceptedMemory,
+      memoryId: payload.memoryId,
+      acceptedMemoryId: payload.acceptedMemoryId,
+      generatedAt,
+    });
+    const result = memory?.ok === false
+      ? memory
+      : forgetAcceptedMemory({
+        ...payload,
+        memory,
+        store: activeStore,
+        now: payload.now ?? payload.occurredAt ?? payload.generatedAt ?? generatedAt,
+      });
+    return buildOperationEnvelope({ operation: 'forget', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+async function runRebuildOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const result = ensureAutoPmMemorySearchIndex({
+      store: activeStore,
+      forceFallback: payload.forceFallback === true,
+      generatedAt: payload.generatedAt ?? generatedAt,
+    });
+    const diagnostics = [...result.diagnostics, diagnostic({
+      severity: 'info',
+      code: 'AUTOPM_MEMORY_OPERATION_REBUILD_COMPLETED',
+      message: 'AutoPM memory retrieval index rebuild operation completed.',
+      details: { mode: result.mode, indexedRecordCount: result.indexedRecordCount },
+    })];
+    const wrapped = Object.freeze({
+      ...result,
+      status: diagnostics.some((item) => item.severity === 'warning') ? 'warn' : 'ok',
+      diagnostics: freezeArray(diagnostics),
+      warnings: freezeArray(diagnostics.filter((item) => item.severity === 'warning')),
+      errors: freezeArray([]),
+      warningCodes: freezeArray(uniqueStrings(diagnostics.filter((item) => item.severity === 'warning').map((item) => item.code))),
+      errorCodes: freezeArray([]),
+      durableStateChanged: result.mode === 'fts',
+      behaviorChanged: false,
+      summary: Object.freeze({ indexedRecordCount: result.indexedRecordCount, mode: result.mode, ftsAvailable: result.ftsAvailable }),
+    });
+    return buildOperationEnvelope({ operation: 'rebuild', generatedAt, result: wrapped, store: activeStore, projectRoot });
+  });
+}
+
+function runSchedulerAction({ payload, store, generatedAt }) {
+  const action = String(payload.action ?? payload.schedulerAction ?? 'status').trim().toLowerCase().replaceAll('_', '-');
+  switch (action) {
+    case 'status':
+    case 'diagnostics':
+      return getAutoPmMemorySchedulerDiagnostics({ store, generatedAt: payload.generatedAt ?? generatedAt });
+    case 'start':
+      return startAutoPmMemoryScheduler({ store, generatedAt: payload.generatedAt ?? generatedAt, reason: payload.reason ?? 'operation' });
+    case 'stop':
+      return stopAutoPmMemoryScheduler({ store, generatedAt: payload.generatedAt ?? generatedAt, reason: payload.reason ?? 'operation' });
+    case 'pause':
+      return pauseAutoPmMemoryScheduler({ store, generatedAt: payload.generatedAt ?? generatedAt, reason: payload.reason ?? 'operation' });
+    case 'resume':
+      return resumeAutoPmMemoryScheduler({ store, generatedAt: payload.generatedAt ?? generatedAt, reason: payload.reason ?? 'operation' });
+    case 'tick':
+      return tickAutoPmMemoryScheduler({ store, generatedAt: payload.generatedAt ?? generatedAt, actions: payload.actions ?? null, allowWhenStopped: payload.allowWhenStopped === true });
+    case 'one-shot':
+    case 'oneshot':
+      return runAutoPmMemorySchedulerOneShot({ store, generatedAt: payload.generatedAt ?? generatedAt, actions: payload.actions ?? null });
+    case 'recover':
+    case 'recover-on-restart':
+      return recoverAutoPmMemorySchedulerOnRestart({ store, generatedAt: payload.generatedAt ?? generatedAt, reason: payload.reason ?? 'operation' });
+    default: {
+      const diagnostics = [diagnostic({
+        severity: 'error',
+        code: 'AUTOPM_MEMORY_OPERATION_SCHEDULER_ACTION_UNSUPPORTED',
+        message: 'AutoPM memory scheduler operation does not support the requested action.',
+        details: { action, supportedActions: ['status', 'start', 'stop', 'pause', 'resume', 'tick', 'one-shot', 'recover'] },
+      })];
+      return Object.freeze({
+        ok: false,
+        status: 'error',
+        action,
+        diagnostics: freezeArray(diagnostics),
+        errors: freezeArray(diagnostics),
+        errorCodes: freezeArray(['AUTOPM_MEMORY_OPERATION_SCHEDULER_ACTION_UNSUPPORTED']),
+        durableStateChanged: false,
+        behaviorChanged: false,
+      });
+    }
+  }
+}
+
+async function runSchedulerOperation({ payload, store, projectRoot, sqliteModule, generatedAt }) {
+  return withMemoryStore({ store, projectRoot, sqliteModule }, async (activeStore) => {
+    const result = runSchedulerAction({ payload, store: activeStore, generatedAt });
+    return buildOperationEnvelope({ operation: 'scheduler', generatedAt, result, store: activeStore, projectRoot });
+  });
+}
+
+export async function runAutoPmMemoryOperation({
+  operation,
+  payload = {},
+  projectRoot = process.cwd(),
+  store = null,
+  sqliteModule = undefined,
+  generatedAt = nowIso(),
+} = {}) {
+  const normalizedOperation = normalizeOperationName(operation);
+  const normalizedPayload = isPlainObject(payload) ? payload : { value: payload };
+  const normalizedGeneratedAt = nowIso(generatedAt);
+
+  try {
+    switch (normalizedOperation) {
+      case 'status':
+        return await runStatusOperation({ payload: normalizedPayload, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'doctor':
+        return await runDoctorOperation({ payload: normalizedPayload, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'recall':
+        return await runRecallOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'search':
+        return await runSearchOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'get':
+        return await runGetOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'remember':
+        return await runRememberOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'ingest':
+        return await runIngestOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'capture':
+        return await runCaptureOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'candidates':
+        return await runCandidatesOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'accept':
+      case 'reject':
+        return await runReviewOperation({ operation: normalizedOperation, payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'forget':
+        return await runForgetOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'rebuild':
+        return await runRebuildOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      case 'scheduler':
+        return await runSchedulerOperation({ payload: normalizedPayload, store, projectRoot, sqliteModule, generatedAt: normalizedGeneratedAt });
+      default: {
+        const diagnostics = [diagnostic({
+          severity: 'error',
+          code: 'AUTOPM_MEMORY_OPERATION_UNSUPPORTED',
+          message: 'AutoPM memory operation is not supported by the shared operation core.',
+          details: { operation, normalizedOperation, supportedOperations: AUTOPM_MEMORY_OPERATION_NAMES },
+        })];
+        return buildOperationEnvelope({
+          operation: normalizedOperation || 'unknown',
+          generatedAt: normalizedGeneratedAt,
+          projectRoot,
+          result: Object.freeze({
+            ok: false,
+            status: 'error',
+            diagnostics: freezeArray(diagnostics),
+            errors: freezeArray(diagnostics),
+            errorCodes: freezeArray(['AUTOPM_MEMORY_OPERATION_UNSUPPORTED']),
+            durableStateChanged: false,
+            behaviorChanged: false,
+          }),
+        });
+      }
+    }
+  } catch (error) {
+    return errorEnvelope({ operation: normalizedOperation || 'unknown', generatedAt: normalizedGeneratedAt, error, projectRoot });
+  }
+}
+
+export const runAutoPmMemoryToolOperation = runAutoPmMemoryOperation;
+export const composeAutoPmMemoryOperation = runAutoPmMemoryOperation;