@aabadin/project-memory-context 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @aabadin/project-memory-context
+
+Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.
+
+This package installs and wires together:
+
+- a project bootstrapper (`pmc bootstrap` / `pmc setup`)
+- a local semantic MCP backed by Ollama (`pmc-local-model`)
+- an `agent-memory` MCP registration using `npx -y @aabadin/agent-memory-mcp`
+- command/workflow templates for `project-memory-context`
+- helper CLIs and artifact management for the semantic enrichment loop
+
+## What it installs for you
+
+The setup flow is designed to resolve everything automatically except:
+
+- installing Ollama itself
+- pulling/downloading your local model
+
+The setup flow handles:
+
+- asking for `OLLAMA_BASE_URL`
+- asking for `OLLAMA_MODEL`
+- installing `graphifyy` with Python/pip
+- creating `.planning/project-memory-context/`
+- writing project install state
+- registering MCP servers in `.mcp.json`
+- registering the plugin in `.opencode/opencode.json` when using OpenCode
+- copying `project-memory-context.md` and `project-memory-context workflow.md` into the target project
+
+## Install
+
+Install the package globally, or run it with `npx`, then run setup inside the target repository.
+
+```bash
+npm install -g @aabadin/project-memory-context
+pmc setup
+```
+
+Without a global install:
+
+```bash
+npx @aabadin/project-memory-context setup
+```
+
+## Setup prompts
+
+`pmc setup` asks for:
+
+- Ollama base URL, default `http://localhost:11434`
+- Ollama model name, default `deepseek-coder-v2:16b-ctx32k`
+
+It then attempts to install:
+
+```bash
+python -m pip install graphifyy
+```
+
+or an equivalent Python launcher depending on platform.
+
+## Resulting project files
+
+After setup, the target project contains:
+
+```text
+.mcp.json
+.planning/project-memory-context/install.json
+project-memory-context.md
+project-memory-context workflow.md
+```
+
+## Runtime layout
+
+During workflow execution, artifacts accumulate under:
+
+```text
+.planning/project-memory-context/
+  intake/
+  graph/
+  enrichment/
+  runs/
+```
+
+## MCP servers
+
+The bootstrap flow writes `.mcp.json` with an `agent-memory` server that runs:
+
+```bash
+npx -y @aabadin/agent-memory-mcp
+```
+
+OpenCode plugin integration may also inject local MCP entries at runtime using values from `.planning/project-memory-context/install.json`:
+
+- `pmc-local-model`
+- `pmc-agent-memory`
+
+`pmc-local-model` exposes a semantic report tool backed by Ollama.
+
+`pmc-agent-memory` points at the public `agent-memory-mcp` binary when plugin injection is used.
+
+## Workflow order
+
+1. `stage-a`
+   - intake
+   - brainstorming clarification
+   - graphify structural mapping
+
+2. `stage-b`
+   - build worklist
+   - prepare semantic jobs
+   - call `pmc-local-model`
+   - materialize `*.memory.json`
+   - store/update in `pmc-agent-memory`
+   - materialize `*.result.json`
+   - finalize or fail each symbol
+
+## Development verification
+
+Run the local test suite:
+
+```bash
+node --test "tools/project-memory-context/tests/*.test.mjs"
+```

package/bin/pmc.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runCommand } from '../src/command-dispatch.mjs';
+
+const exitCode = await runCommand(process.argv.slice(2)).catch((error) => {
+  console.error('[pmc] FATAL:', error.message);
+  return 1;
+});
+
+if (exitCode !== 0) {
+  process.exit(exitCode);
+}

package/cli/apply-enrichment-result.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+
+import { persistEnrichmentResult } from '../src/persist-enrichment-result.mjs';
+import { loadResultInput } from '../src/result-input.mjs';
+
+const [, , rawJson] = process.argv;
+
+if (!rawJson) {
+  console.error('Usage: node apply-enrichment-result.mjs "{...json result...}"');
+  process.exit(1);
+}
+
+let result;
+try {
+  result = await loadResultInput(rawJson);
+} catch (error) {
+  console.error(`Invalid JSON payload: ${error.message}`);
+  process.exit(1);
+}
+
+const projectRoot = resolve(process.cwd());
+const persisted = await persistEnrichmentResult({ projectRoot, result });
+console.log(JSON.stringify({
+  saved: true,
+  graphFile: persisted.graphFile,
+  indexFile: persisted.indexFile,
+  symbolKey: result.symbolKey,
+  memoryId: result.memoryId ?? null,
+  graphNodeId: result.graphNodeId ?? null,
+}, null, 2));

package/cli/batch-enrich.mjs

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

package/cli/bootstrap.mjs

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { access, constants, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync, readdirSync, mkdirSync, copyFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import { bootstrapProjectInstall } from '../src/setup-bootstrap.mjs';
+import { resolveGraphify, spawnBackground, resolvePythonBin } from '../src/platform.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PMC_CLI_ROOT = resolve(__dirname);
+const PMC_ROOT = resolve(__dirname, '..', '..', '..');
+const PMC_PACKAGE_ROOT = resolve(__dirname, '..');
+
+const OLLAMA_URL = process.env.OLLAMA_URL || 'http://localhost:11434';
+const OLLAMA_MODEL = process.env.OLLAMA_MODEL || 'deepseek-coder-v2:16b-ctx32k';
+const PMC_CONCURRENCY = parseInt(process.env.PMC_CONCURRENCY || '8', 10);
+
+function log(msg) { console.error(`[bootstrap] ${msg}`); }
+
+export function buildDefaultEnrichmentConfig() {
+  return {
+    preferredModes: ['local-model', 'cloud-api', 'agent-subagent'],
+    localModel: {
+      provider: 'ollama',
+      baseUrl: OLLAMA_URL,
+      model: OLLAMA_MODEL,
+    },
+    cloudApi: {
+      provider: 'openai-compatible',
+      baseUrl: '',
+      model: '',
+      apiKeyEnv: 'PMC_CLOUD_API_KEY',
+    },
+    agentSubagent: {
+      enabled: true,
+      agentName: 'enrich',
+    },
+  };
+}
+
+export function mergeEnrichmentConfig(current = {}) {
+  current = current ?? {};
+  const source = current.enrichment ?? current;
+  const defaults = buildDefaultEnrichmentConfig();
+  return {
+    ...defaults,
+    ...source,
+    preferredModes: source.preferredModes ?? defaults.preferredModes,
+    localModel: {
+      ...defaults.localModel,
+      ...source.localModel,
+    },
+    cloudApi: {
+      ...defaults.cloudApi,
+      ...source.cloudApi,
+    },
+    agentSubagent: {
+      ...defaults.agentSubagent,
+      ...source.agentSubagent,
+    },
+  };
+}
+
+function getTargetDir(args) {
+  for (const arg of args) {
+    if (arg === '--help' || arg === '-h') return null;
+    if (!arg.startsWith('--')) return resolve(arg);
+  }
+  return process.cwd();
+}
+
+async function ensureDir(dir) {
+  try { await access(dir, constants.F_OK); return true; }
+  catch { return false; }
+}
+
+async function readJson(filePath) {
+  try { return JSON.parse(await readFile(filePath, 'utf8')); }
+  catch { return null; }
+}
+
+async function installGraphify() {
+  log('Installing graphify (Python)...');
+  const pythonBin = resolvePythonBin();
+  const r = spawnSync(pythonBin, ['-m', 'pip', 'install', 'graphifyy'], { stdio: 'inherit' });
+  if (r.status === 0) {
+    log(`graphifyy installed via ${pythonBin}`);
+    return true;
+  }
+  log('WARNING: graphifyy install failed. Graphify step may not work.');
+  return false;
+}
+
+async function syncToolsToTarget(projectRoot) {
+  log('Copying PMC tools to target repo...');
+  const srcCli = resolve(PMC_ROOT, 'tools', 'project-memory-context', 'cli');
+  const dstCli = resolve(projectRoot, 'tools', 'project-memory-context', 'cli');
+
+  mkdirSync(resolve(projectRoot, 'tools', 'project-memory-context'), { recursive: true });
+  mkdirSync(dstCli, { recursive: true });
+
+  const files = ['new-project.mjs', 'bootstrap.mjs', 'enrich-queue.mjs', 'build-worklist.mjs', 'project-context.mjs', 'sanitize.mjs'];
+  for (const f of files) {
+    try {
+      copyFileSync(resolve(srcCli, f), resolve(dstCli, f));
+      log(`  copied ${f}`);
+    } catch {
+      log(`  skipped ${f} (not found in source)`);
+    }
+  }
+
+  const srcSrc = resolve(PMC_ROOT, 'tools', 'project-memory-context', 'src');
+  const dstSrc = resolve(projectRoot, 'tools', 'project-memory-context', 'src');
+  mkdirSync(dstSrc, { recursive: true });
+
+  function copyTree(srcDir, dstDir) {
+    mkdirSync(dstDir, { recursive: true });
+    const entries = readdirSync(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcPath = resolve(srcDir, entry.name);
+      const dstPath = resolve(dstDir, entry.name);
+      if (entry.isDirectory()) {
+        copyTree(srcPath, dstPath);
+      } else if (entry.isFile() && entry.name.endsWith('.mjs')) {
+        copyFileSync(srcPath, dstPath);
+        log(`  copied ${dstPath.replace(`${projectRoot}\\`, '').replace(/\\/g, '/')}`);
+      }
+    }
+  }
+
+  try {
+    copyTree(srcSrc, dstSrc);
+  } catch { log('  src/ copy skipped (may not exist)'); }
+
+  log('  PMC tools synced to target repo.');
+}
+
+async function runStageA(projectRoot) {
+  log('Running graphify update (structural AST analysis, no LLM)...');
+
+  let graphifyExe;
+  try {
+    graphifyExe = resolveGraphify();
+  } catch (e) {
+    log(`  ${e.message}`);
+    log('  Stage-a skipped. Install graphify with `pip install graphifyy` or set PMC_GRAPHIFY_PATH.');
+    return true;
+  }
+
+  const graphOutDir = resolve(projectRoot, '.planning', 'project-memory-context', 'graph');
+  const graphifyOutDir = resolve(projectRoot, 'graphify-out');
+
+  const r = spawnSync(`"${graphifyExe}"`, ['update', projectRoot], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (r.status === 0) {
+    log('  Graph extraction complete. Copying to .planning...');
+    try {
+      if (!existsSync(graphifyOutDir)) { log('  graphify-out not found'); return false; }
+      const files = readdirSync(graphifyOutDir);
+      for (const f of files) {
+        if (f === 'graph.json' || f === 'graph.metadata.json' || f === 'graph.html' || f === 'GRAPH_REPORT.md') {
+          copyFileSync(resolve(graphifyOutDir, f), resolve(graphOutDir, f));
+          log(`    copied ${f}`);
+        }
+      }
+    } catch (e) { log(`  Copy error: ${e.message}`); }
+    log('  Graphify update complete (AST only, no semantic LLM).');
+    log('  For full semantic enrichment, set ANTHROPIC_API_KEY and run graphify extract.');
+  } else {
+    log(`  Graphify update failed with code ${r.status}. Stage-b and enrichment still work.`);
+  }
+
+  return true;
+}
+
+function findFiles(dir, exts, ignore, projectRoot) {
+  const results = [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = resolve(dir, entry.name);
+      if (ignore.some(i => full.includes(i))) continue;
+      if (entry.isDirectory()) {
+        results.push(...findFiles(full, exts, ignore, projectRoot));
+      } else if (exts.some(e => entry.name.endsWith(e))) {
+        results.push(full.replace(`${projectRoot}\\`, '').replace(`${projectRoot}/`, '').replace(/\\/g, '/'));
+      }
+    }
+  } catch { /* skip inaccessible dirs */ }
+  return results;
+}
+
+async function runStageB(projectRoot) {
+  log('Running stage-b (build-worklist)...');
+
+  const ignore = ['node_modules', 'dist', '.git', 'bin', 'obj', '.opencode', '.planning'];
+  const files = [
+    ...findFiles(projectRoot, ['.ts', '.mjs', '.js'], ignore, projectRoot),
+    ...findFiles(projectRoot, ['.cs'], ignore, projectRoot),
+  ];
+
+  log(`  Found ${files.filter(f => f.endsWith('.cs')).length} CS files, ${files.filter(f => !f.endsWith('.cs')).length} TS/JS files`);
+
+  if (files.length === 0) {
+    log('No files to process. Skipping stage-b.');
+    return true;
+  }
+
+  const worklistScript = resolve(PMC_CLI_ROOT, 'build-worklist.mjs');
+  const r = spawnSync('node', [worklistScript, ...files], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    env: { ...process.env, PMC_CONCURRENCY: String(PMC_CONCURRENCY) },
+  });
+
+  if (r.status !== 0) {
+    const altWorklistScript = resolve(projectRoot, 'tools', 'project-memory-context', 'cli', 'build-worklist.mjs');
+    log(`  Primary worklist failed, trying local: ${altWorklistScript}`);
+    const r2 = spawnSync('node', [altWorklistScript, ...files], {
+      cwd: projectRoot,
+      stdio: 'inherit',
+      env: { ...process.env, PMC_CONCURRENCY: String(PMC_CONCURRENCY) },
+    });
+    if (r2.status !== 0) {
+      log(`Stage-b failed with code ${r2.status}`);
+      return false;
+    }
+  }
+
+  log('Stage-b complete.');
+  return true;
+}
+
+function printUsage() {
+  console.log(`
+bootstrap - Portable PMC bootstrap for any repo
+
+Usage:
+  node bootstrap.mjs <target-repo> [--stage-a] [--stage-b] [--all] [--enrich]
+
+Arguments:
+  target-repo          Path to the target repository (default: current dir)
+
+Options:
+  --stage-a            Run intake + graphify after setup
+  --stage-b            Run symbol extraction + worklist after setup
+  --all                Run both stages after setup (default: setup only)
+  --enrich             Also start the enrichment queue in background after setup
+  --help, -h           Show this help
+
+Environment variables:
+  OLLAMA_URL           Ollama URL (default: http://localhost:11434)
+  OLLAMA_MODEL         Ollama model (default: deepseek-coder-v2:16b-ctx32k)
+  PMC_CONCURRENCY      Parallel slots (default: 8)
+  PMC_GRAPHIFY_PATH    Custom path to graphify executable
+
+Example:
+  node bootstrap.mjs /path/to/my-repo --all
+  node bootstrap.mjs /path/to/my-repo --all --enrich
+  OLLAMA_MODEL=qwen3-coder:30b node bootstrap.mjs . --stage-b --enrich
+`);
+}
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printUsage();
+    return 0;
+  }
+
+  const targetDir = getTargetDir(args);
+  if (!targetDir) { printUsage(); return 0; }
+
+  const runStageAFlag = args.includes('--stage-a') || args.includes('--all');
+  const runStageBFlag = args.includes('--stage-b') || args.includes('--all');
+  const runEnrichFlag = args.includes('--enrich');
+
+  log(`Target repo: ${targetDir}`);
+  log(`PMC package root: ${PMC_ROOT}`);
+  log(`Ollama: ${OLLAMA_URL} | Model: ${OLLAMA_MODEL}`);
+
+  if (!await ensureDir(targetDir)) {
+    console.error(`[bootstrap] ERROR: Directory not found: ${targetDir}`);
+    return 1;
+  }
+
+  log('Installing graphify...');
+  await installGraphify();
+
+  log('Running portable project install...');
+  const { configPath } = await bootstrapProjectInstall({
+    projectRoot: targetDir,
+    packageRoot: PMC_PACKAGE_ROOT,
+    ollamaBaseUrl: OLLAMA_URL,
+    ollamaModel: OLLAMA_MODEL,
+  });
+
+  log('Syncing PMC tools to target repo...');
+  await syncToolsToTarget(targetDir);
+
+  log('Generating project context artifacts...');
+  const projectContextScript = resolve(PMC_CLI_ROOT, 'project-context.mjs');
+  const contextResult = spawnSync('node', [projectContextScript, targetDir], {
+    cwd: targetDir,
+    stdio: 'inherit',
+    env: { ...process.env },
+  });
+  if (contextResult.status !== 0) {
+    log(`WARNING: project-context generation failed with code ${contextResult.status}`);
+  }
+
+  log('');
+  log('========================================');
+  log('PMC installed successfully!');
+  log(`  Target: ${targetDir}`);
+  log(`  Config: ${configPath}`);
+  log('========================================');
+  log('');
+
+  if (runStageAFlag) {
+    log('Executing stage-a...');
+    await runStageA(targetDir);
+  }
+
+  if (runStageBFlag) {
+    log('Executing stage-b...');
+    const ok = await runStageB(targetDir);
+    if (!ok) log('WARNING: stage-b had issues. Check output above.');
+  }
+
+  if (runEnrichFlag && (runStageAFlag || runStageBFlag)) {
+    log('Starting background enrichment queue...');
+    const enrichScript = resolve(targetDir, 'tools', 'project-memory-context', 'cli', 'enrich-queue.mjs');
+    spawnBackground(process.execPath, [enrichScript], { cwd: targetDir });
+    log('  Enrichment running in background.');
+  } else if (!runStageAFlag && !runStageBFlag) {
+    log('Run enrichment with:');
+    log(`  cd ${targetDir}`);
+    log(`  node tools/project-memory-context/cli/enrich-queue.mjs`);
+  }
+
+  log('Done.');
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch((err) => {
+    console.error('[bootstrap] FATAL:', err.message);
+    return 1;
+  });
+  if (exitCode !== 0) process.exit(exitCode);
+}

package/cli/build-worklist.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { join, relative, resolve } from 'node:path';
+
+import {
+  ensureProjectMemoryContextDirs,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from '../src/artifacts.mjs';
+import { attachGraphNodeIds } from '../src/graph-node-resolver.mjs';
+import { buildEnrichmentWorklist, extractTopLevelSymbols } from '../src/symbol-extractor.mjs';
+
+const projectRoot = resolve(process.cwd());
+const dirs = await ensureProjectMemoryContextDirs(projectRoot);
+const symbolIndex = await readJsonArtifact(join(dirs.enrichment, 'symbol-index.json'), {});
+const graph = await readJsonArtifact(join(dirs.graph, 'graph.json'), { nodes: [], edges: [] });
+const files = process.argv.slice(2);
+
+if (files.length === 0) {
+  console.error('Usage: node build-worklist.mjs <file1> [file2 ...]');
+  process.exit(1);
+}
+
+const symbols = [];
+for (const file of files) {
+  const absolute = resolve(projectRoot, file);
+  const content = await readFile(absolute, 'utf8');
+  symbols.push(...extractTopLevelSymbols({ filePath: relative(projectRoot, absolute), content }));
+}
+
+const resolvedSymbols = attachGraphNodeIds({ symbols, graph });
+const worklist = buildEnrichmentWorklist({ symbols: resolvedSymbols, symbolIndex });
+const outputFile = join(dirs.enrichment, 'worklist.json');
+await writeJsonArtifact(outputFile, worklist);
+console.log(JSON.stringify({ saved: true, file: outputFile, count: worklist.length }, null, 2));

package/cli/context.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_PATH = resolve(dirname(fileURLToPath(import.meta.url)), 'project-context.mjs');
+
+function printHelp() {
+  console.log('Usage: pmc context [project-root] [--refresh]');
+}
+
+export async function runProjectContext(projectRoot = process.cwd(), refresh = false) {
+  const mod = await import('./project-context.mjs');
+  if (typeof mod.runProjectContextCli === 'function') {
+    return mod.runProjectContextCli(projectRoot, { refresh });
+  }
+  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(`context 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('[context] FATAL:', error.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

package/cli/doctor.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { runDoctor } from '../src/doctor.mjs';
+import { resolvePythonBin } from '../src/platform.mjs';
+
+function spawnCheck(bin, args) {
+  const result = spawnSync(bin, args, { encoding: 'utf-8', timeout: 5000 });
+  return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+
+const { checks } = await runDoctor({ resolvePythonBin, spawnCheck });
+
+const icon = { ok: '✓', warn: '⚠', fail: '✗' };
+const color = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', reset: '\x1b[0m' };
+
+console.log('\npmc doctor\n');
+for (const c of checks) {
+  const col = color[c.status] ?? '';
+  console.log(`  ${col}${icon[c.status]}${color.reset}  ${c.name.padEnd(22)} ${c.message}`);
+}
+console.log('');
+
+const hasFail = checks.some(c => c.status === 'fail');
+if (hasFail) {
+  console.log('Some checks failed. Fix the issues above before running pmc setup.\n');
+  process.exit(1);
+} else {
+  console.log('All checks passed.\n');
+}

package/cli/enrich-batch.mjs

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..', '..', '..');
+
+console.error('[enrich-batch] DEPRECATED: This script hardcodes Ollama. Use enrich-queue.mjs instead.');
+console.error('[enrich-batch] The enrich-queue supports the shared fallback driver (local-model → cloud-api → agent-subagent).');
+console.error('[enrich-batch] Run: node tools/project-memory-context/cli/enrich-queue.mjs');
+process.exit(1);