@aabadin/project-memory-context 0.1.0

package/cli/enrich-loop.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+# Continuous enrichment loop - keeps 8 parallel slots running always
+# Each run processes 8 symbols, syncs, then re-runs until done
+
+ENRICH_DIR=".planning/project-memory-context/enrichment"
+WORKLIST="$ENRICH_DIR/worklist.json"
+OLLAMA_URL="${OLLAMA_URL:-http://localhost:11434}"
+OLLAMA_MODEL="${OLLAMA_MODEL:-deepseek-coder-v2:16b-ctx32k}"
+
+check_pending() {
+  node -e "const w=require('$WORKLIST'); const p=w.filter(s=>s.status==='pending').length; console.log(p)" 2>/dev/null || echo "99"
+}
+
+echo "[loop] Starting continuous enrichment loop"
+echo "[loop] Ollama: $OLLAMA_URL | Model: $OLLAMA_MODEL"
+
+batch=0
+while true; do
+  pending=$(check_pending)
+  if [ "$pending" -eq "0" ]; then
+    echo "[loop] All symbols enriched! Done."
+    break
+  fi
+  if [ "$pending" -gt "87" ]; then
+    echo "[loop] Worklist corrupted or missing. Stop."
+    break
+  fi
+
+  batch=$((batch + 1))
+  echo ""
+  echo "[loop] ===== BATCH $batch ===== ($pending symbols remaining)"
+  echo "[loop] $(date +%H:%M:%S) Dispatching 8 subagents via Task tool..."
+
+  # Run orchestrator to get next 8 symbols + prompts
+  manifest=$(node tools/project-memory-context/cli/enrich-orchestrator.mjs 2>/dev/null)
+  if [ $? -ne 0 ]; then
+    echo "[loop] Orchestrator failed. Retrying in 5s..."
+    sleep 5
+    continue
+  fi
+
+  echo "$manifest" | node -e "
+    const stdin = require('fs').readFileSync('/dev/stdin', 'utf8');
+    const j = JSON.parse(stdin);
+    if (j.complete) { console.log('ALL_DONE'); process.exit(0); }
+    if (!j.subagentPrompts || j.subagentPrompts.length === 0) {
+      console.log('NO_PROMPTS');
+      process.exit(1);
+    }
+    console.log(JSON.stringify(j.subagentPrompts.map((p, i) => ({
+      idx: i,
+      prompt: p,
+      symbolKey: j.pending[i]?.symbolKey || 'unknown'
+    }))));
+  " > /tmp/pmc_batch_$batch.json 2>/dev/null
+
+  if [ $? -ne 0 ]; then
+    echo "[loop] Failed to get batch. Retrying..."
+    sleep 5
+    continue
+  fi
+
+  batch_data=$(cat /tmp/pmc_batch_$batch.json)
+  if [ "$batch_data" = "ALL_DONE" ] || [ "$batch_data" = "NO_PROMPTS" ]; then
+    echo "[loop] No more symbols to process."
+    break
+  fi
+
+  # Extract symbol keys and names for dispatch
+  echo "$batch_data" | node -e "
+    const data = JSON.parse(require('fs').readFileSync('/dev/stdin', 'utf8'));
+    data.forEach((item, i) => {
+      const sym = JSON.parse(item.prompt.split('SYMBOL: ')[1].split('\n')[0]);
+      console.log(JSON.stringify(sym));
+    });
+  " > /tmp/pmc_symbols_$batch.json 2>/dev/null
+
+  echo "[loop] Dispatching 8 subagents in parallel..."
+
+  # Dispatch all 8 subagents in background and collect task IDs
+  declare -a TASK_IDS
+  idx=0
+  while read -r symbol_json; do
+    [ -z "$symbol_json" ] && continue
+    task_id=$(node -e "
+      const spawn = require('child_process').spawn;
+      const sym = $symbol_json;
+      const prompt = 'You are enriching ONE code symbol for project-memory-context.\n\nSYMBOL: ' + JSON.stringify(sym) + '\nPROJECT_ROOT: C:\\\\Users\\\\aabad\\\\Documents\\\\CODE\\\\ia\\\\memory-context\nOLLAMA_URL: http://localhost:11434\nOLLAMA_MODEL: deepseek-coder-v2:16b-ctx32k\n\nSTEPS:\n1. Read the source file at the symbol filePath (use Read tool), lines startLine to endLine PLUS imports above\n2. Call Ollama via bash: node -e \"fetch('http://localhost:11434/api/generate',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({model:'deepseek-coder-v2:16b-ctx32k',prompt:'YOUR_PROMPT',stream:false,options:{temperature:0.1,num_predict:512}})}).then(r=>r.json()).then(d=>process.stdout.write(d.response))\"\n3. Store via agent-memory_store: content, category architecture, tags symbol ts kind project:memory-context file:filepath\n4. Return JSON with symbolKey memoryId status enrichedAt\n\nDo NOT update any JSON files. Return result.'
+      // Can't actually dispatch task from here - output the prompt for manual use
+      console.log(prompt);
+    " 2>&1 | head -1) &
+    TASK_IDS[$idx]=$!
+    idx=$((idx + 1))
+  done < /tmp/pmc_symbols_$batch.json
+
+  # Wait for all background jobs
+  for pid in "${TASK_IDS[@]}"; do
+    wait $pid 2>/dev/null
+  done
+
+  echo "[loop] Batch $batch dispatched. Sleeping 5s before checking..."
+  sleep 5
+
+  # Check if we should continue
+  pending=$(check_pending)
+  if [ "$pending" -eq "0" ]; then
+    echo "[loop] All done!"
+    break
+  fi
+  if [ "$batch" -ge 20 ]; then
+    echo "[loop] Max batches reached ($batch). Stopping safely."
+    break
+  fi
+done
+
+echo "[loop] Loop complete. Final state:"
+node -e "const w=require('.planning/project-memory-context/enrichment/worklist.json'); const p=w.filter(s=>s.status==='pending').length; const e=w.filter(s=>s.status==='enriched').length; const err=w.filter(s=>s.status==='error').length; console.log('pending='+p+' enriched='+e+' error='+err+' total='+w.length)"

package/cli/enrich-orchestrator.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+console.error('[enrich-orchestrator] DEPRECATED: This script hardcodes Ollama and generates subagent manifests.');
+console.error('[enrich-orchestrator] Use enrich-queue.mjs which supports the shared fallback driver.');
+console.error('[enrich-orchestrator] Run: node tools/project-memory-context/cli/enrich-queue.mjs');
+process.exit(1);

package/cli/enrich-queue.mjs

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname, basename } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { appendProviderEvent, withRecordedAttempt } from '../src/enrichment-attempts.mjs';
+import { PMC_ENRICHMENT_CONFIG_FILE, resolveEnrichmentConfig } from '../src/enrichment-config.mjs';
+import { runEnrichmentWithFallback } from '../src/enrichment-driver.mjs';
+import { createCloudApiProvider } from '../src/providers/cloud-api-provider.mjs';
+import { createLocalModelProvider } from '../src/providers/local-model-provider.mjs';
+import { appendSyncEntry, createSyncEntry } from '../src/sync-manifest.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..', '..', '..');
+
+export function parseQueueConcurrency(rawValue) {
+  const parsed = parseInt(rawValue || '8', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+}
+
+const PMC_CONCURRENCY = parseQueueConcurrency(process.env.PMC_CONCURRENCY);
+const PROJECT_SLUG = process.env.PMC_PROJECT_SLUG || basename(PROJECT_ROOT);
+const TIMEOUT_MS = parseInt(process.env.PMC_TIMEOUT_MS || '300000', 10);
+const REPORT_INTERVAL_MS = parseInt(process.env.PMC_REPORT_INTERVAL || '30000', 10);
+
+let _worklist = [];
+let _symbolIndex = {};
+let _worklistFile = '';
+let _symbolIndexFile = '';
+let _enrichmentDir = '';
+
+async function loadJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function loadOptionalJson(path, fallback = null) {
+  try {
+    return await loadJson(path);
+  } catch {
+    return fallback;
+  }
+}
+
+async function saveJson(path, data) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+function safeKey(key) {
+  return key.replace(/[^a-zA-Z0-9_-]+/g, '_');
+}
+
+class SlotTracker {
+  constructor(maxSlots) {
+    this.maxSlots = maxSlots;
+    this.slots = new Map();
+    this.completedCount = 0;
+    this.errorCount = 0;
+    this.totalProcessed = 0;
+  }
+
+  allocate(symbol) {
+    for (let i = 0; i < this.maxSlots; i++) {
+      if (!this.slots.has(i)) {
+        const startTime = Date.now();
+        this.slots.set(i, { symbol, startTime });
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  complete(slotIdx, result) {
+    const slot = this.slots.get(slotIdx);
+    if (!slot) return null;
+    const elapsed = Date.now() - slot.startTime;
+    this.slots.delete(slotIdx);
+    this.completedCount++;
+    this.totalProcessed++;
+    return { ...slot, elapsed, result };
+  }
+
+  fail(slotIdx, error) {
+    const slot = this.slots.get(slotIdx);
+    if (!slot) return null;
+    const elapsed = Date.now() - slot.startTime;
+    this.slots.delete(slotIdx);
+    this.errorCount++;
+    this.totalProcessed++;
+    return { ...slot, elapsed, error };
+  }
+
+  isFull() {
+    return this.slots.size >= this.maxSlots;
+  }
+
+  activeCount() {
+    return this.slots.size;
+  }
+
+  hasActiveSlots() {
+    return this.slots.size > 0;
+  }
+}
+
+function createAgentSubagentProvider() {
+  return {
+    kind: 'agent-subagent',
+    isConfigured(context) {
+      const { enabled = true, agentName = 'enrich' } = context?.config?.agentSubagent ?? {};
+      if (!enabled) {
+        return { ok: false, reason: 'agent-subagent is disabled' };
+      }
+
+      return { ok: true, provider: agentName };
+    },
+    async isAvailable() {
+      return { ok: false, reason: 'agent-subagent is unavailable in cli context', errorType: 'provider' };
+    },
+    async enrich() {
+      throw new Error('agent-subagent is unavailable in cli context');
+    },
+  };
+}
+
+async function buildSymbolPrompt(symbol, projectRoot) {
+  const absoluteFile = resolve(projectRoot, symbol.filePath);
+  const content = await readFile(absoluteFile, 'utf8');
+  const lines = content.split('\n');
+
+  const codeSection = lines.slice(symbol.range.startLine - 1, symbol.range.endLine).join('\n');
+  const importsSection = lines.slice(0, symbol.range.startLine - 1).filter(l => /^\s*import\b/.test(l) || /^\s*using\b/.test(l)).join('\n');
+
+  return `Symbol: ${symbol.name}\nKind: ${symbol.kind}\nLanguage: ${symbol.language}\nLocation: ${symbol.filePath}:${symbol.range.startLine}-${symbol.range.endLine}\n\nContext (imports):\n${importsSection || '(none)'}\n\nCode:\n${codeSection}\n\nReturn a compact structured explanation with:\n- responsibility\n- primary inputs\n- output\n- immediate dependencies\n- role in module`;
+}
+
+function applyAttemptsToEntry(entry, attempts) {
+  let updated = { ...entry };
+  for (const attempt of attempts ?? []) {
+    updated = withRecordedAttempt(updated, attempt);
+  }
+  return updated;
+}
+
+function getLastAttemptMode(attempts) {
+  return attempts?.length ? attempts[attempts.length - 1].mode ?? null : null;
+}
+
+function getLastAttemptError(attempts) {
+  for (let idx = (attempts?.length ?? 0) - 1; idx >= 0; idx--) {
+    const message = attempts[idx]?.errorMessage;
+    if (message) {
+      return message;
+    }
+  }
+
+  return 'All enrichment providers failed';
+}
+
+function createQueueEnrichmentError(result) {
+  const error = new Error(result.error);
+  error.symbolKey = result.symbolKey;
+  error.attempts = result.attempts;
+  error.lastModeUsed = result.lastModeUsed;
+  error.failedAt = result.failedAt;
+  return error;
+}
+
+export function buildQueueSummary(worklist) {
+  return {
+    enriched: worklist.filter((entry) => entry.status === 'enriched' || entry.status === 'already_enriched').length,
+    errors: worklist.filter((entry) => entry.status === 'error').length,
+    pending: worklist.filter((entry) => entry.status === 'pending' || entry.status === 'stale').length,
+  };
+}
+
+async function loadRuntimeEnrichmentConfig(projectRoot, env) {
+  const projectConfig = await loadOptionalJson(resolve(projectRoot, '.opencode', PMC_ENRICHMENT_CONFIG_FILE));
+  const globalConfig = await loadOptionalJson(resolve(homedir(), '.config', 'opencode', PMC_ENRICHMENT_CONFIG_FILE));
+  return resolveEnrichmentConfig({ projectConfig, globalConfig, env });
+}
+
+function createQueueProviders() {
+  return [
+    createLocalModelProvider(),
+    createCloudApiProvider(),
+    createAgentSubagentProvider(),
+  ];
+}
+
+export async function runQueueSymbolEnrichment({
+  symbol,
+  projectRoot,
+  projectSlug,
+  timeoutMs,
+  enrichmentDir,
+  worklist,
+  worklistFile,
+  symbolIndex = {},
+  symbolIndexFile = '',
+  config,
+  providers,
+  env = process.env,
+  runEnrichmentWithFallbackImpl = runEnrichmentWithFallback,
+}) {
+  const prompt = await buildSymbolPrompt(symbol, projectRoot);
+  const result = await runEnrichmentWithFallbackImpl({
+    request: { prompt, timeoutMs },
+    config,
+    providers,
+    env,
+  });
+  const wlEntry = worklist.find((entry) => entry.symbolKey === symbol.symbolKey);
+
+  for (const attempt of result.attempts ?? []) {
+    await appendProviderEvent(enrichmentDir, {
+      symbolKey: symbol.symbolKey,
+      name: symbol.name,
+      ...attempt,
+    });
+  }
+
+  if (result.status === 'succeeded') {
+    const memoryId = `queue-${safeKey(symbol.symbolKey)}`;
+    const enrichedAt = new Date().toISOString();
+    const memoryFile = resolve(enrichmentDir, `${safeKey(symbol.symbolKey)}.memory.json`);
+    await saveJson(memoryFile, {
+      content: result.content,
+      category: 'architecture',
+      tags: ['symbol', symbol.language, symbol.kind, `project:${projectSlug}`, `file:${symbol.filePath}`],
+    });
+
+    if (wlEntry) {
+      Object.assign(wlEntry, applyAttemptsToEntry(wlEntry, result.attempts), {
+        status: 'enriched',
+        memoryId,
+        enrichedAt,
+        error: undefined,
+        failedAt: undefined,
+      });
+    }
+
+    symbolIndex[symbol.symbolKey] = {
+      memoryId,
+      graphNodeId: wlEntry?.graphNodeId ?? symbol.graphNodeId ?? null,
+      codeHash: symbol.codeHash,
+      status: 'enriched',
+      lastEnrichedAt: enrichedAt,
+    };
+
+    await saveJson(worklistFile, worklist);
+    if (symbolIndexFile) {
+      await saveJson(symbolIndexFile, symbolIndex);
+    }
+
+    try {
+      await appendSyncEntry(enrichmentDir, createSyncEntry({
+        action: 'upsert',
+        keyTag: `key:symbol:${safeKey(symbol.symbolKey)}`,
+        content: `## ${symbol.name}\n\n${result.content}`,
+        category: 'architecture',
+        tags: ['symbol', symbol.language, symbol.kind, `project:${projectSlug}`, `file:${symbol.filePath}`, 'enriched-by-queue'],
+        source: 'enrich-queue',
+        symbolKey: symbol.symbolKey,
+      }));
+    } catch (syncErr) {
+      console.error(`[queue] WARN: sync-manifest append failed for ${symbol.name}: ${syncErr.message}`);
+    }
+
+    return {
+      status: 'enriched',
+      symbolKey: symbol.symbolKey,
+      memoryId,
+      memoryContent: result.content,
+      language: symbol.language,
+      kind: symbol.kind,
+      filePath: symbol.filePath,
+      projectSlug,
+      codeHash: symbol.codeHash,
+      attempts: result.attempts ?? [],
+      lastModeUsed: wlEntry?.lastModeUsed ?? result.mode ?? getLastAttemptMode(result.attempts),
+      enrichedAt,
+    };
+  }
+
+  const error = getLastAttemptError(result.attempts);
+  const failedAt = new Date().toISOString();
+
+  if (wlEntry) {
+    Object.assign(wlEntry, applyAttemptsToEntry(wlEntry, result.attempts), {
+      status: 'error',
+      error,
+      failedAt,
+    });
+  }
+
+  symbolIndex[symbol.symbolKey] = {
+    memoryId: null,
+    graphNodeId: wlEntry?.graphNodeId ?? symbol.graphNodeId ?? null,
+    codeHash: symbol.codeHash,
+    status: 'error',
+    lastEnrichedAt: failedAt,
+  };
+
+  await saveJson(worklistFile, worklist);
+  if (symbolIndexFile) {
+    await saveJson(symbolIndexFile, symbolIndex);
+  }
+
+  const failure = {
+    status: 'error',
+    symbolKey: symbol.symbolKey,
+    error,
+    attempts: result.attempts ?? [],
+    lastModeUsed: wlEntry?.lastModeUsed ?? getLastAttemptMode(result.attempts),
+    failedAt,
+  };
+
+  throw createQueueEnrichmentError(failure);
+}
+
+async function checkpointSave() {
+  if (!_worklistFile) return;
+  console.error('\n[checkpoint] Saving progress...');
+  await saveJson(_worklistFile, _worklist);
+  await saveJson(_symbolIndexFile, _symbolIndex);
+  const pending = _worklist.filter(s => s.status === 'pending').length;
+  const enriched = _worklist.filter(s => s.status === 'enriched').length;
+  const errors = _worklist.filter(s => s.status === 'error').length;
+  console.error(`[checkpoint] Saved: pending=${pending} enriched=${enriched} errors=${errors}`);
+}
+
+process.on('SIGINT', async () => {
+  console.error('\n[queue] Interrupted — checkpointing...');
+  await checkpointSave();
+  process.exit(0);
+});
+
+process.on('SIGTERM', async () => {
+  console.error('\n[queue] Terminated — checkpointing...');
+  await checkpointSave();
+  process.exit(0);
+});
+
+async function main() {
+  const enrichmentDir = resolve(PROJECT_ROOT, '.planning/project-memory-context/enrichment');
+  await mkdir(enrichmentDir, { recursive: true });
+
+  const worklistFile = resolve(enrichmentDir, 'worklist.json');
+  const symbolIndexFile = resolve(enrichmentDir, 'symbol-index.json');
+
+  _worklistFile = worklistFile;
+  _symbolIndexFile = symbolIndexFile;
+
+  let worklist;
+  try {
+    worklist = await loadJson(worklistFile);
+  } catch {
+    console.error('[queue] No worklist found. Run Stage A first.');
+    process.exit(1);
+  }
+
+  let symbolIndex = {};
+  try { symbolIndex = await loadJson(symbolIndexFile); } catch {}
+
+  const enrichmentConfig = await loadRuntimeEnrichmentConfig(PROJECT_ROOT, process.env);
+  const providers = createQueueProviders();
+
+  _enrichmentDir = enrichmentDir;
+  _worklist = worklist;
+  _symbolIndex = symbolIndex;
+
+  for (const entry of worklist) {
+    if (entry.status === 'enriched' && entry.memoryId) {
+      entry.status = 'already_enriched';
+      console.error(`[resume] Skipping ${entry.name} (${entry.symbolKey}) — already enriched`);
+    }
+  }
+
+  const pending = worklist.filter(s => s.status === 'pending' || s.status === 'stale');
+  const alreadyEnriched = worklist.filter(s => s.status === 'already_enriched').length;
+  const staleCount = worklist.filter(s => s.status === 'stale').length;
+  const total = worklist.length;
+
+  if (pending.length === 0) {
+    const summary = buildQueueSummary(worklist);
+    console.log(JSON.stringify({ complete: true, total, enriched: summary.enriched, errors: summary.errors }));
+    return;
+  }
+
+  console.error(`[queue] Starting continuous enrichment: ${pending.length} pending (${staleCount} stale), ${alreadyEnriched} already enriched, ${PMC_CONCURRENCY} parallel slots`);
+  console.error(`[queue] Modes: ${enrichmentConfig.preferredModes.join(', ')} | Local: ${enrichmentConfig.localModel.baseUrl} | Model: ${enrichmentConfig.localModel.model} | Timeout: ${TIMEOUT_MS}ms per symbol\n`);
+
+  const tracker = new SlotTracker(PMC_CONCURRENCY);
+  const queue = [...pending];
+  const results = [];
+  const errors = [];
+
+  const startTime = Date.now();
+
+  async function dispatchNext() {
+    if (queue.length === 0) return null;
+    const symbol = queue.shift();
+    const slotIdx = tracker.allocate(symbol);
+    if (slotIdx === -1) {
+      queue.unshift(symbol);
+      return null;
+    }
+
+    runQueueSymbolEnrichment({
+      symbol,
+      projectRoot: PROJECT_ROOT,
+      projectSlug: PROJECT_SLUG,
+      timeoutMs: TIMEOUT_MS,
+      enrichmentDir: _enrichmentDir,
+      worklist,
+      worklistFile,
+      symbolIndex,
+      symbolIndexFile,
+      config: enrichmentConfig,
+      providers,
+      env: process.env,
+    })
+      .then(async (result) => {
+        const completion = tracker.complete(slotIdx, result);
+
+        console.error(`[slot ${slotIdx}] DONE ${symbol.name} (${symbol.filePath}) — ${Math.round(completion.elapsed / 1000)}s — queuing next`);
+        results.push({ symbolKey: symbol.symbolKey, memoryId: result.memoryId, elapsed: completion.elapsed });
+
+        dispatchNext();
+      })
+      .catch(async (err) => {
+        const failure = tracker.fail(slotIdx, err.message);
+        console.error(`[slot ${slotIdx}] ERROR ${symbol.name}: ${err.message} (${Math.round(failure.elapsed / 1000)}s)`);
+        errors.push({ symbolKey: symbol.symbolKey, error: err.message, elapsed: failure.elapsed, failedAt: err.failedAt ?? null });
+
+        const wlEntry = worklist.find(s => s.symbolKey === symbol.symbolKey);
+        if (wlEntry) {
+          wlEntry.status = 'error';
+          wlEntry.error = err.message;
+          wlEntry.failedAt = new Date().toISOString();
+        }
+
+        await saveJson(worklistFile, worklist);
+
+        dispatchNext();
+      });
+
+    return slotIdx;
+  }
+
+  const initPromises = [];
+  for (let i = 0; i < PMC_CONCURRENCY && queue.length > 0; i++) {
+    initPromises.push(dispatchNext());
+  }
+
+  await Promise.all(initPromises);
+
+  await new Promise((resolve) => {
+    const checkInterval = setInterval(() => {
+      if (!tracker.hasActiveSlots() && queue.length === 0) {
+        clearInterval(checkInterval);
+        resolve();
+      } else {
+        const elapsedTotal = Date.now() - startTime;
+        const remaining = queue.length;
+        const active = tracker.activeCount();
+        const done = results.length + errors.length;
+        console.error(`[queue status] done=${done} active=${active} queued=${remaining} elapsed=${Math.round(elapsedTotal / 1000)}s`);
+      }
+    }, REPORT_INTERVAL_MS);
+  });
+
+  await checkpointSave();
+
+  for (const r of results) {
+    const entry = worklist.find(s => s.symbolKey === r.symbolKey);
+    if (entry) {
+      symbolIndex[r.symbolKey] = {
+        memoryId: r.memoryId,
+        graphNodeId: entry.graphNodeId ?? null,
+        codeHash: entry.codeHash,
+        status: 'enriched',
+        lastEnrichedAt: entry.enrichedAt,
+      };
+    }
+  }
+  for (const err of errors) {
+    const entry = worklist.find(s => s.symbolKey === err.symbolKey);
+    if (entry) {
+      symbolIndex[err.symbolKey] = {
+        memoryId: null,
+        graphNodeId: entry.graphNodeId ?? null,
+        codeHash: entry.codeHash,
+        status: 'error',
+        lastEnrichedAt: err.failedAt || null,
+      };
+    }
+  }
+  await saveJson(symbolIndexFile, symbolIndex);
+
+  const totalElapsed = Date.now() - startTime;
+  const summary = buildQueueSummary(worklist);
+  const avgTime = results.length > 0 ? results.reduce((a, r) => a + r.elapsed, 0) / results.length : 0;
+
+  console.log(JSON.stringify({
+    complete: summary.pending === 0,
+    total: worklist.length,
+    enriched: summary.enriched,
+    errors: summary.errors,
+    pending: summary.pending,
+    totalElapsedSeconds: Math.round(totalElapsed / 1000),
+    avgSymbolTimeSeconds: Math.round(avgTime / 1000),
+    resultsPerSecond: Math.round((results.length / (totalElapsed / 1000)) * 100) / 100,
+    timing: results.map(r => ({ symbolKey: r.symbolKey, seconds: Math.round(r.elapsed / 1000) })),
+  }, null, 2));
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(err => {
+    console.error('[fatal]', err.message);
+    process.exit(1);
+  });
+}

package/cli/enrich-sync.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+console.error('[enrich-sync] DEPRECATED: This script hardcodes Ollama. Use enrich-queue.mjs instead.');
+console.error('[enrich-sync] The enrich-queue supports the shared fallback driver (local-model → cloud-api → agent-subagent).');
+console.error('[enrich-sync] Run: node tools/project-memory-context/cli/enrich-queue.mjs');
+process.exit(1);

package/cli/enrich.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export { runQueueSymbolEnrichment, buildQueueSummary, parseQueueConcurrency } from './enrich-queue.mjs';
+
+const SCRIPT_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'enrich-queue.mjs');
+
+function printHelp() {
+  console.log('Usage: pmc enrich');
+}
+
+export async function runEnrichQueue(projectRoot = process.cwd()) {
+  const mod = await import('./enrich-queue.mjs');
+  if (typeof mod.default === 'function') {
+    return mod.default(projectRoot);
+  }
+  return null;
+}
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return 0;
+  }
+
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(process.execPath, [SCRIPT_PATH, ...args], { stdio: 'inherit' });
+    child.once('error', rejectPromise);
+    child.once('exit', (code, signal) => {
+      if (signal) {
+        rejectPromise(new Error(`enrich exited from signal ${signal}`));
+        return;
+      }
+
+      resolvePromise(code ?? 0);
+    });
+  });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch((error) => {
+    console.error('[enrich] FATAL:', error.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}