@aabadin/project-memory-context 0.1.5 → 0.2.1

package/cli/retry-errors.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { appendProviderEvent, withRecordedAttempt } from '../src/enrichment-attempts.mjs';
+import { resolveEnrichmentConfig, PMC_ENRICHMENT_CONFIG_FILE } from '../src/enrichment-config.mjs';
+import { runEnrichmentWithFallback } from '../src/enrichment-driver.mjs';
+import { createLocalModelProvider } from '../src/providers/local-model-provider.mjs';
+import { appendSyncEntry, createSyncEntry } from '../src/sync-manifest.mjs';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+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, '_');
+}
+
+async function buildSymbolPrompt(symbol, projectRoot, maxCodeLines = 80) {
+  const absoluteFile = resolve(projectRoot, symbol.filePath);
+  const content = await readFile(absoluteFile, 'utf8');
+  const lines = content.split('\n');
+  const totalSymbolLines = symbol.range.endLine - symbol.range.startLine + 1;
+  let codeSection = lines.slice(symbol.range.startLine - 1, symbol.range.endLine).join('\n');
+  let truncated = false;
+  if (totalSymbolLines > maxCodeLines) {
+    const header = lines.slice(symbol.range.startLine - 1, symbol.range.startLine - 1 + Math.floor(maxCodeLines * 0.6)).join('\n');
+    const footer = lines.slice(symbol.range.endLine - Math.floor(maxCodeLines * 0.4), symbol.range.endLine).join('\n');
+    codeSection = header + '\n  // ... truncated ...\n' + footer;
+    truncated = true;
+  }
+  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}${truncated ? ` (truncated from ${totalSymbolLines} lines)` : ''}\n\nContext (imports):\n${importsSection || '(none)'}\n\nCode:\n${codeSection}\n\nReturn a compact structured explanation (max 150 words) with:\n- responsibility\n- primary inputs\n- output\n- immediate dependencies\n- role in module`;
+}
+
+function parseArgs(argv) {
+  const args = { concurrency: 4, timeoutMs: 600000, model: null, baseUrl: null, reportFile: null, limit: null };
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--concurrency' && argv[i + 1]) { args.concurrency = parseInt(argv[++i], 10); }
+    else if (arg === '--timeout' && argv[i + 1]) { args.timeoutMs = parseInt(argv[++i], 10); }
+    else if (arg === '--model' && argv[i + 1]) { args.model = argv[++i]; }
+    else if (arg === '--base-url' && argv[i + 1]) { args.baseUrl = argv[++i]; }
+    else if (arg === '--report' && argv[i + 1]) { args.reportFile = argv[++i]; }
+    else if (arg === '--limit' && argv[i + 1]) { args.limit = parseInt(argv[++i], 10); }
+    else if (arg === '--help' || arg === '-h') { args.help = true; }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+PMC Retry Errors — Re-enriches symbols that failed using Ollama directly
+
+Usage: node tools/project-memory-context/cli/retry-errors.mjs [options]
+
+Options:
+  --concurrency N     Parallel slots (default: 4)
+  --timeout MS        Timeout per symbol in ms (default: 600000 = 10min)
+  --model NAME        Ollama model name (default: from config)
+  --base-url URL      Ollama base URL (default: http://localhost:11434)
+  --limit N           Only retry first N error entries (default: all)
+  --report PATH       Save JSON report to file (default: .planning/.../retry-report.json)
+  -h, --help          Show this help
+`);
+}
+
+async function main() {
+  const rawArgs = process.argv.slice(2);
+  const projectRoot = rawArgs.find(a => !a.startsWith('-')) || process.cwd();
+  const args = parseArgs(process.argv);
+  if (args.help) { printHelp(); return 0; }
+
+  const enrichmentDir = resolve(projectRoot, '.planning/project-memory-context/enrichment');
+  await mkdir(enrichmentDir, { recursive: true });
+
+  const worklistFile = resolve(enrichmentDir, 'worklist.json');
+  const symbolIndexFile = resolve(enrichmentDir, 'symbol-index.json');
+
+  let worklist;
+  try {
+    worklist = await loadJson(worklistFile);
+  } catch {
+    console.error('[retry] No worklist found.');
+    process.exit(1);
+  }
+
+  const errorEntries = worklist.filter(e => e.status === 'error');
+  if (errorEntries.length === 0) {
+    console.log('[retry] No error entries found in worklist. Nothing to retry.');
+    return;
+  }
+
+  if (args.limit && args.limit < errorEntries.length) {
+    console.error(`[retry] Limiting to first ${args.limit} of ${errorEntries.length} error entries`);
+    errorEntries.splice(args.limit);
+  }
+
+  let symbolIndex = {};
+  try { symbolIndex = await loadJson(symbolIndexFile); } catch {}
+
+  const projectConfig = await loadOptionalJson(resolve(projectRoot, '.opencode', PMC_ENRICHMENT_CONFIG_FILE));
+  const globalConfig = await loadOptionalJson(resolve(homedir(), '.config', 'opencode', PMC_ENRICHMENT_CONFIG_FILE));
+  let config = resolveEnrichmentConfig({ projectConfig, globalConfig, env: process.env });
+
+  config.preferredModes = ['local-model'];
+
+  if (args.model) {
+    config.localModel.model = args.model;
+  }
+  if (args.baseUrl) {
+    config.localModel.baseUrl = args.baseUrl;
+  }
+
+  const projectSlug = process.env.PMC_PROJECT_SLUG || basename(projectRoot);
+
+  const providers = [createLocalModelProvider()];
+
+  console.error(`\n[retry] ═════════════════════════════════════════════════════`);
+  console.error(`[retry] Retrying ${errorEntries.length} error symbols`);
+  console.error(`[retry] Provider: ${config.localModel.provider} | Model: ${config.localModel.model}`);
+  console.error(`[retry] Base URL: ${config.localModel.baseUrl}`);
+  console.error(`[retry] Concurrency: ${args.concurrency} | Timeout: ${args.timeoutMs / 1000}s`);
+  console.error(`[retry] ═════════════════════════════════════════════════════\n`);
+
+  const report = {
+    startedAt: new Date().toISOString(),
+    config: { model: config.localModel.model, baseUrl: config.localModel.baseUrl, concurrency: args.concurrency, timeoutMs: args.timeoutMs },
+    previousErrors: {},
+    results: [],
+    summary: { succeeded: 0, failed: 0, skipped: 0 },
+  };
+
+  for (const entry of errorEntries) {
+    const lastLocalAttempt = (entry.attempts ?? []).find(a => a.mode === 'local-model');
+    report.previousErrors[entry.symbolKey] = {
+      name: entry.name,
+      filePath: entry.filePath,
+      kind: entry.kind,
+      previousError: entry.error,
+      localModelError: lastLocalAttempt?.errorMessage ?? null,
+      localModelErrorType: lastLocalAttempt?.errorType ?? null,
+      attemptCount: entry.attempts?.length ?? 0,
+    };
+  }
+
+  const queue = [...errorEntries];
+  const activeSlots = new Map();
+  const results = [];
+  let slotIdCounter = 0;
+
+  async function dispatchSlot() {
+    while (queue.length > 0) {
+      const entry = queue.shift();
+
+      entry.status = 'pending';
+      delete entry.error;
+      delete entry.failedAt;
+
+      const slotId = slotIdCounter++;
+      const startTime = Date.now();
+
+      activeSlots.set(slotId, { entry, startTime });
+
+      try {
+        const prompt = await buildSymbolPrompt(entry, projectRoot);
+        const result = await runEnrichmentWithFallback({
+          request: { prompt, timeoutMs: args.timeoutMs },
+          config,
+          providers,
+          env: process.env,
+        });
+
+        const elapsed = Date.now() - startTime;
+        activeSlots.delete(slotId);
+
+        for (const attempt of result.attempts ?? []) {
+          await appendProviderEvent(enrichmentDir, { symbolKey: entry.symbolKey, name: entry.name, ...attempt });
+        }
+
+        const reportEntry = {
+          symbolKey: entry.symbolKey,
+          name: entry.name,
+          filePath: entry.filePath,
+          kind: entry.kind,
+          language: entry.language,
+          elapsedMs: elapsed,
+          attempts: result.attempts ?? [],
+        };
+
+        if (result.status === 'succeeded') {
+          const memoryId = `queue-${safeKey(entry.symbolKey)}`;
+          const enrichedAt = new Date().toISOString();
+          const memoryFile = resolve(enrichmentDir, `${safeKey(entry.symbolKey)}.memory.json`);
+
+          await saveJson(memoryFile, {
+            content: result.content,
+            category: 'architecture',
+            tags: ['symbol', entry.language, entry.kind, `project:${projectSlug}`, `file:${entry.filePath}`],
+          });
+
+          const newAttempts = [...(entry.attempts ?? []), ...(result.attempts ?? [])];
+          Object.assign(entry, {
+            status: 'enriched',
+            memoryId,
+            enrichedAt,
+            error: undefined,
+            failedAt: undefined,
+            attempts: newAttempts,
+            lastModeUsed: 'local-model',
+          });
+
+          symbolIndex[entry.symbolKey] = {
+            memoryId,
+            graphNodeId: entry.graphNodeId ?? null,
+            codeHash: entry.codeHash,
+            status: 'enriched',
+            lastEnrichedAt: enrichedAt,
+          };
+
+          try {
+            await appendSyncEntry(enrichmentDir, createSyncEntry({
+              action: 'upsert',
+              keyTag: `key:symbol:${safeKey(entry.symbolKey)}`,
+              content: `## ${entry.name}\n\n${result.content}`,
+              category: 'architecture',
+              tags: ['symbol', entry.language, entry.kind, `project:${projectSlug}`, `file:${entry.filePath}`, 'enriched-by-retry'],
+              source: 'retry-errors',
+              symbolKey: entry.symbolKey,
+            }));
+          } catch (syncErr) {
+            console.error(`[retry] WARN: sync append failed for ${entry.name}: ${syncErr.message}`);
+          }
+
+          reportEntry.status = 'succeeded';
+          reportEntry.contentPreview = result.content?.substring(0, 200);
+          reportEntry.memoryId = memoryId;
+          report.summary.succeeded++;
+
+          const done = report.summary.succeeded + report.summary.failed;
+          console.error(`  [OK] ${entry.name} (${entry.filePath}:${entry.range.startLine}) — ${Math.round(elapsed / 1000)}s [${done}/${errorEntries.length}]`);
+        } else {
+          const lastError = result.attempts?.find(a => a.errorMessage)?.errorMessage ?? 'all providers failed';
+
+          const newAttempts = [...(entry.attempts ?? []), ...(result.attempts ?? [])];
+          Object.assign(entry, {
+            status: 'error',
+            error: lastError,
+            failedAt: new Date().toISOString(),
+            attempts: newAttempts,
+          });
+
+          symbolIndex[entry.symbolKey] = {
+            memoryId: null,
+            graphNodeId: entry.graphNodeId ?? null,
+            codeHash: entry.codeHash,
+            status: 'error',
+            lastEnrichedAt: new Date().toISOString(),
+          };
+
+          reportEntry.status = 'failed';
+          reportEntry.failureReason = lastError;
+          report.summary.failed++;
+
+          const done = report.summary.succeeded + report.summary.failed;
+          console.error(`  [FAIL] ${entry.name} (${entry.filePath}:${entry.range.startLine}) — ${lastError} — ${Math.round(elapsed / 1000)}s [${done}/${errorEntries.length}]`);
+        }
+
+        results.push(reportEntry);
+      } catch (err) {
+        const elapsed = Date.now() - startTime;
+        activeSlots.delete(slotId);
+
+        entry.status = 'error';
+        entry.error = err.message;
+        entry.failedAt = new Date().toISOString();
+
+        const reportEntry = {
+          symbolKey: entry.symbolKey,
+          name: entry.name,
+          filePath: entry.filePath,
+          kind: entry.kind,
+          language: entry.language,
+          elapsedMs: elapsed,
+          status: 'failed',
+          failureReason: err.message,
+          attempts: [],
+        };
+
+        results.push(reportEntry);
+        report.summary.failed++;
+
+        const done = report.summary.succeeded + report.summary.failed;
+        console.error(`  [ERR] ${entry.name} — ${err.message} — ${Math.round(elapsed / 1000)}s [${done}/${errorEntries.length}]`);
+      }
+
+      await saveJson(worklistFile, worklist);
+      await saveJson(symbolIndexFile, symbolIndex);
+    }
+  }
+
+  const slots = [];
+  for (let i = 0; i < args.concurrency; i++) {
+    slots.push(dispatchSlot());
+  }
+  await Promise.all(slots);
+
+  report.results = results;
+  report.finishedAt = new Date().toISOString();
+  report.totalElapsedMs = results.reduce((a, r) => a + (r.elapsedMs ?? 0), 0);
+
+  const reportPath = args.reportFile || resolve(enrichmentDir, 'retry-report.json');
+  await saveJson(reportPath, report);
+
+  console.error(`\n[retry] ═════════════════════════════════════════════════════`);
+  console.error(`[retry] DONE — ${report.summary.succeeded} succeeded, ${report.summary.failed} failed, ${report.summary.skipped} skipped`);
+  console.error(`[retry] Report: ${reportPath}`);
+  console.error(`[retry] ═════════════════════════════════════════════════════\n`);
+
+  console.log(JSON.stringify({
+    ok: true,
+    command: 'retry-errors',
+    total: errorEntries.length,
+    succeeded: report.summary.succeeded,
+    failed: report.summary.failed,
+    reportPath,
+  }, null, 2));
+
+  return report.summary.failed > 0 ? 1 : 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch(err => {
+    console.error('[retry] FATAL:', err.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

package/cli/status.mjs

@@ -5,6 +5,8 @@ import { fileURLToPath } from 'node:url';
 
 import { detectAgentType, resolveConfigDirs } from '../src/platform.mjs';
 
+const DEFAULT_STALE_AFTER_SECONDS = 90;
+
 export function summarizeWorklist(worklist) {
   return {
     pending: worklist.filter((e) => e.status === 'pending' || e.status === 'stale').length,
@@ -21,6 +23,52 @@ async function readJsonSafe(filePath) {
   }
 }
 
+function toIsoString(value) {
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+
+function heartbeatIsFresh(heartbeatAt, now, staleAfterSeconds = DEFAULT_STALE_AFTER_SECONDS) {
+  if (!heartbeatAt) return false;
+  const heartbeat = new Date(heartbeatAt).getTime();
+  const current = new Date(now).getTime();
+  if (!Number.isFinite(heartbeat) || !Number.isFinite(current)) return false;
+  return current - heartbeat <= staleAfterSeconds * 1000;
+}
+
+function deriveRuntimeState(queueState, now, staleAfterSeconds = DEFAULT_STALE_AFTER_SECONDS) {
+  if (!queueState || typeof queueState !== 'object') {
+    return { state: 'idle', runtime: null };
+  }
+
+  const runtime = {
+    pid: Number.isInteger(queueState.pid) ? queueState.pid : null,
+    startedAt: toIsoString(queueState.startedAt),
+    heartbeatAt: toIsoString(queueState.heartbeatAt),
+    finishedAt: toIsoString(queueState.finishedAt),
+    staleAfterSeconds,
+    lastError: queueState.lastError ?? null,
+  };
+
+  if (queueState.status === 'finished') {
+    return { state: 'finished', runtime };
+  }
+
+  if (queueState.status === 'failed') {
+    return { state: 'failed', runtime };
+  }
+
+  if (queueState.status === 'running') {
+    return {
+      state: heartbeatIsFresh(runtime.heartbeatAt, now, staleAfterSeconds) ? 'running' : 'stalled',
+      runtime,
+    };
+  }
+
+  return { state: 'idle', runtime: null };
+}
+
 async function getLastSyncTimestamp(enrichmentDir) {
   const syncManifest = join(enrichmentDir, 'sync-manifest.json');
   try {
@@ -31,16 +79,20 @@ async function getLastSyncTimestamp(enrichmentDir) {
   }
 }
 
-export async function buildStatusReport({ projectRoot = process.cwd() } = {}) {
+export async function buildStatusReport({ projectRoot = process.cwd(), now = new Date().toISOString() } = {}) {
   const dirs = resolveConfigDirs(projectRoot);
   const planningDir = join(projectRoot, '.planning', 'project-memory-context');
   const enrichmentDir = join(planningDir, 'enrichment');
   const worklistPath = join(enrichmentDir, 'worklist.json');
   const installStatePath = join(planningDir, 'install.json');
+  const queueStatePath = join(enrichmentDir, 'queue-state.json');
 
   const worklist = await readJsonSafe(worklistPath);
   const installState = await readJsonSafe(installStatePath);
+  const queueState = await readJsonSafe(queueStatePath);
   const lastSync = await getLastSyncTimestamp(enrichmentDir);
+  const { state, runtime } = deriveRuntimeState(queueState, now);
+  const worklistSummary = Array.isArray(worklist) ? summarizeWorklist(worklist) : null;
 
   return {
     ok: true,
@@ -49,7 +101,9 @@ export async function buildStatusReport({ projectRoot = process.cwd() } = {}) {
     configLocation: dirs.projectConfig,
     agentType: detectAgentType(projectRoot),
     installState: installState ? { installedAt: installState.installedAt, version: installState.version } : null,
-    worklist: worklist ? summarizeWorklist(worklist) : null,
+    state,
+    runtime,
+    worklist: worklistSummary,
     lastSync,
   };
 }

package/mcp/pmc-query-server.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { createQueryOrchestrator } from '../src/query/orchestrator.mjs';
+
+const projectRoot = process.env.PMC_PROJECT_ROOT || process.cwd();
+const orchestrator = createQueryOrchestrator({ projectRoot });
+
+function textResult(value) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+  };
+}
+
+function errorResult(toolName, error) {
+  return {
+    content: [{ type: 'text', text: `${toolName} failed: ${String(error)}` }],
+    isError: true,
+  };
+}
+
+const server = new McpServer({
+  name: 'pmc-query',
+  version: '0.1.5',
+});
+
+server.tool(
+  'pmc_query_project',
+  'Query PMC project context and symbol artifacts using a natural-language question.',
+  {
+    question: z.string().describe('Natural-language project question'),
+  },
+  async ({ question }) => {
+    try {
+      return textResult(await orchestrator.query(question));
+    } catch (error) {
+      return errorResult('pmc_query_project', error);
+    }
+  },
+);
+
+server.tool(
+  'pmc_search_symbols',
+  'Search PMC symbols by semantic summary and optional file path filter.',
+  {
+    query: z.string().describe('Search query for symbols'),
+    file: z.string().optional().describe('Optional normalized file path filter'),
+  },
+  async ({ query, file }) => {
+    try {
+      return textResult(await orchestrator.searchSymbols(query, file));
+    } catch (error) {
+      return errorResult('pmc_search_symbols', error);
+    }
+  },
+);
+
+server.tool(
+  'pmc_get_dependents',
+  'List symbols that depend on the given symbol key.',
+  {
+    symbol: z.string().describe('Normalized PMC symbol key'),
+  },
+  async ({ symbol }) => {
+    try {
+      return textResult(await orchestrator.getDependents(symbol));
+    } catch (error) {
+      return errorResult('pmc_get_dependents', error);
+    }
+  },
+);
+
+server.tool(
+  'pmc_get_dependencies',
+  'List symbols the given symbol key depends on.',
+  {
+    symbol: z.string().describe('Normalized PMC symbol key'),
+  },
+  async ({ symbol }) => {
+    try {
+      return textResult(await orchestrator.getDependencies(symbol));
+    } catch (error) {
+      return errorResult('pmc_get_dependencies', error);
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aabadin/project-memory-context",
-  "version": "0.1.5",
+  "version": "0.2.1",
   "description": "Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.",
   "license": "GPL-3.0-or-later",
   "type": "module",
@@ -11,7 +11,8 @@
     "./retrieval": "./src/retrieval/query-engine.mjs"
   },
   "bin": {
-    "pmc": "bin/pmc.mjs"
+    "pmc": "bin/pmc.mjs",
+    "pmc-query-server": "mcp/pmc-query-server.mjs"
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs",

package/src/command-dispatch.mjs

@@ -14,6 +14,8 @@ const COMMANDS = new Map([
   ['install-pmc', 'cli/install-pmc.mjs'],
   ['new-project', 'cli/new-project.mjs'],
   ['project-context', 'cli/project-context.mjs'],
+  ['query', 'cli/query.mjs'],
+  ['retry-errors', 'cli/retry-errors.mjs'],
   ['sanitize', 'cli/sanitize.mjs'],
   ['setup', 'cli/setup.mjs'],
   ['status', 'cli/status.mjs'],

package/src/plugin-config.mjs

@@ -1,6 +1,14 @@
 export function buildInjectedPmcConfig({ installState }) {
   return {
     mcp: {
+      'pmc-query': {
+        type: 'local',
+        command: ['npx', '--yes', '--package', '@aabadin/project-memory-context', 'pmc-query-server'],
+        enabled: true,
+        environment: {
+          PMC_PROJECT_ROOT: installState.projectRoot,
+        },
+      },
       'pmc-agent-memory': {
         type: 'local',
         command: ['npx', '-y', '@aabadin/agent-memory-mcp'],

package/src/query/load-artifacts.mjs

@@ -0,0 +1,96 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+function normalizePath(filePath) {
+  return String(filePath ?? '').replace(/\\/g, '/');
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+async function readJsonDirectory(directoryPath) {
+  try {
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith('.json'))
+      .map((entry) => entry.name)
+      .sort((a, b) => a.localeCompare(b));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+async function loadMemories(projectContextDir) {
+  const materializedDir = join(projectContextDir, 'materialized');
+  const materializedEntries = await readJsonDirectory(materializedDir);
+  const directory = materializedEntries.length > 0 ? materializedDir : projectContextDir;
+  const fileNames = materializedEntries.length > 0
+    ? materializedEntries
+    : await readJsonDirectory(projectContextDir);
+
+  const memories = [];
+  for (const fileName of fileNames) {
+    const path = join(directory, fileName);
+    const memory = await readJson(path, null);
+    if (memory) {
+      memories.push({ ...memory, path });
+    }
+  }
+
+  return memories;
+}
+
+function parseSymbol(symbolKey, entry, semanticSummary) {
+  const parts = String(symbolKey ?? '').split('|');
+  return {
+    symbolKey,
+    filePath: parts.length >= 2 ? normalizePath(parts[1]) : '',
+    name: parts.length >= 2 ? parts[parts.length - 2] : '',
+    graphNodeId: entry?.graphNodeId ?? null,
+    memoryId: entry?.memoryId ?? null,
+    status: entry?.status ?? null,
+    semanticSummary,
+  };
+}
+
+export async function loadQueryArtifacts(projectRoot) {
+  const pmcRoot = join(projectRoot, '.planning', 'project-memory-context');
+  const projectContextDir = join(pmcRoot, 'project-context');
+  const symbolIndexPath = join(pmcRoot, 'enrichment', 'symbol-index.json');
+  const graphPath = join(pmcRoot, 'graph', 'graph.json');
+
+  const memories = await loadMemories(projectContextDir);
+  const symbolIndex = await readJson(symbolIndexPath, {});
+  const graph = await readJson(graphPath, {});
+  const nodes = graph.nodes ?? [];
+  const edges = graph.edges ?? graph.links ?? [];
+
+  const nodeById = new Map(nodes.map((node) => [node?.id, node]));
+  const symbols = Object.entries(symbolIndex).map(([symbolKey, entry]) => {
+    const semanticSummary = String(
+      entry?.semanticSummary
+      ?? nodeById.get(entry?.graphNodeId)?.metadata?.semanticSummary
+      ?? '',
+    ).trim();
+
+    return parseSymbol(symbolKey, entry, semanticSummary);
+  });
+
+  return {
+    memories,
+    symbols,
+    nodes,
+    edges,
+  };
+}