@aabadin/project-memory-context 0.1.0

package/cli/sanitize.mjs

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+import { resolve, dirname, basename, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile, writeFile, mkdir, readdir } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+import { ensureProjectMemoryContextDirs, readJsonArtifact, writeJsonArtifact } from '../src/artifacts.mjs';
+import { extractTopLevelSymbols } from '../src/symbol-extractor.mjs';
+import { attachGraphNodeIds } from '../src/graph-node-resolver.mjs';
+import { appendSyncEntries, createSyncEntry, clearManifest } from '../src/sync-manifest.mjs';
+import { spawnBackground } from '../src/platform.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(process.argv[2] || process.cwd());
+
+function log(msg) { console.error(`[sanitize] ${msg}`); }
+
+function safeKey(key) {
+  return key.replace(/[^a-zA-Z0-9_-]+/g, '_');
+}
+
+function codeHash(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function getGraphifyExe() {
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA || resolve(process.env.APPDATA || '', '..', 'Local');
+    return resolve(localAppData, 'Programs', 'Python', 'Python313', 'Scripts', 'graphify.exe');
+  }
+  return 'graphify';
+}
+
+async function findSourceFiles(projectRoot) {
+  const exts = new Set(['.ts', '.mjs', '.js', '.cs']);
+  const ignore = ['node_modules', 'dist', '.git', 'bin', 'obj', '.opencode', '.planning', 'graphify-out'];
+  const results = [];
+
+  async function walk(dir) {
+    const entries = await readdir(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()) {
+        await walk(full);
+      } else if (Array.from(exts).some(e => entry.name.endsWith(e))) {
+        results.push(relative(projectRoot, full).replace(/\\/g, '/'));
+      }
+    }
+  }
+
+  await walk(projectRoot);
+  return results;
+}
+
+async function runGraphifyUpdate(projectRoot) {
+  const graphifyExe = getGraphifyExe();
+  const graphifyOutDir = resolve(projectRoot, 'graphify-out');
+  const graphOutDir = resolve(projectRoot, '.planning', 'project-memory-context', 'graph');
+
+  log('Running graphify update (structural AST)...');
+  const r = spawnSync(`"${graphifyExe}"`, ['update', `"${projectRoot}"`], {
+    cwd: projectRoot,
+    stdio: 'inherit',
+    shell: true,
+  });
+
+  if (r.status !== 0) {
+    log(`WARNING: graphify update failed (code ${r.status}). Continuing with existing graph.`);
+    return false;
+  }
+
+  try {
+    const files = await readdir(graphifyOutDir);
+    for (const f of files) {
+      if (f === 'graph.json' || f === 'graph.metadata.json' || f === 'graph.html' || f === 'GRAPH_REPORT.md') {
+        const { copyFileSync } = await import('node:fs');
+        copyFileSync(resolve(graphifyOutDir, f), resolve(graphOutDir, f));
+      }
+    }
+  } catch { /* graphify-out may not exist */ }
+
+  log('Graphify update complete.');
+  return true;
+}
+
+async function extractCurrentSymbols(projectRoot, files) {
+  const allSymbols = [];
+  for (const file of files) {
+    try {
+      const content = await readFile(resolve(projectRoot, file), 'utf8');
+      const symbols = extractTopLevelSymbols({ filePath: file, content });
+      for (const sym of symbols) {
+        sym.codeHash = codeHash(
+          content.split('\n').slice(sym.range.startLine - 1, sym.range.endLine).join('\n')
+        );
+      }
+      allSymbols.push(...symbols);
+    } catch { /* skip unreadable files */ }
+  }
+  return allSymbols;
+}
+
+async function sanitize() {
+  log(`Target: ${PROJECT_ROOT}`);
+  const projectSlug = basename(PROJECT_ROOT).toLowerCase();
+  const dirs = await ensureProjectMemoryContextDirs(PROJECT_ROOT);
+
+  await runGraphifyUpdate(PROJECT_ROOT);
+
+  const graph = await readJsonArtifact(resolve(dirs.graph, 'graph.json'), { nodes: [], edges: [] });
+
+  log('Scanning source files...');
+  const files = await findSourceFiles(PROJECT_ROOT);
+  log(`Found ${files.length} source files.`);
+
+  log('Extracting symbols...');
+  const currentSymbols = await extractCurrentSymbols(PROJECT_ROOT, files);
+  const resolvedSymbols = attachGraphNodeIds({ symbols: currentSymbols, graph });
+  log(`Extracted ${resolvedSymbols.length} symbols.`);
+
+  const currentMap = new Map();
+  for (const sym of resolvedSymbols) {
+    currentMap.set(sym.symbolKey, sym);
+  }
+
+  const existingWorklist = await readJsonArtifact(resolve(dirs.enrichment, 'worklist.json'), []);
+  const existingMap = new Map();
+  for (const entry of existingWorklist) {
+    existingMap.set(entry.symbolKey, entry);
+  }
+
+  const newEntries = [];
+  const staleEntries = [];
+  const removedEntries = [];
+  const unchangedEntries = [];
+  const syncOps = [];
+
+  for (const [key, sym] of currentMap) {
+    const existing = existingMap.get(key);
+    if (!existing) {
+      newEntries.push({
+        ...sym,
+        status: 'pending',
+        memoryId: null,
+      });
+    } else if (existing.codeHash !== sym.codeHash) {
+      staleEntries.push({
+        ...sym,
+        status: 'stale',
+        staleReason: 'code-hash-changed',
+        staleAt: new Date().toISOString(),
+        memoryId: existing.memoryId || null,
+      });
+      syncOps.push(createSyncEntry({
+        action: 'delete',
+        keyTag: `key:symbol:${safeKey(key)}`,
+        tags: ['symbol', sym.language, sym.kind, `project:${projectSlug}`, `file:${sym.filePath}`],
+        source: 'sanitize',
+        symbolKey: key,
+      }));
+    } else {
+      unchangedEntries.push({
+        ...existing,
+        verifiedAt: new Date().toISOString(),
+        status: existing.status === 'stale' ? 'stale' : existing.status,
+      });
+    }
+  }
+
+  for (const [key, existing] of existingMap) {
+    if (!currentMap.has(key)) {
+      removedEntries.push(existing);
+      syncOps.push(createSyncEntry({
+        action: 'delete',
+        keyTag: `key:symbol:${safeKey(key)}`,
+        tags: ['symbol', existing.language, existing.kind, `project:${projectSlug}`, `file:${existing.filePath}`],
+        source: 'sanitize',
+        symbolKey: key,
+      }));
+    }
+  }
+
+  const newWorklist = [
+    ...newEntries,
+    ...staleEntries,
+    ...unchangedEntries,
+  ];
+
+  await writeJsonArtifact(resolve(dirs.enrichment, 'worklist.json'), newWorklist);
+
+  if (syncOps.length > 0) {
+    await appendSyncEntries(dirs.enrichment, syncOps);
+  }
+
+  const pendingCount = newWorklist.filter(e => e.status === 'pending' || e.status === 'stale').length;
+  const enrichedCount = newWorklist.filter(e => e.status === 'enriched' || e.status === 'already_enriched').length;
+
+  log('');
+  log('=== Sanitize Report ===');
+  log(`Total symbols: ${newWorklist.length}`);
+  log(`New: ${newEntries.length}`);
+  log(`Stale (code changed): ${staleEntries.length}`);
+  log(`Removed: ${removedEntries.length}`);
+  log(`Unchanged/verified: ${unchangedEntries.length}`);
+  log(`Pending enrichment: ${pendingCount}`);
+  log(`Already enriched: ${enrichedCount}`);
+  log(`Sync-manifest operations: ${syncOps.length} (deletes for stale/removed)`);
+  log('');
+
+  if (pendingCount > 0) {
+    const enrichCli = resolve(__dirname, 'enrich.mjs');
+    const launchedPid = spawnBackground(process.execPath, [enrichCli, PROJECT_ROOT], { cwd: PROJECT_ROOT });
+    log(`Background enrichment launched via spawnBackground (pid=${launchedPid})`);
+    log(`  ${process.execPath} ${enrichCli} ${PROJECT_ROOT}`);
+  }
+
+  const result = {
+    total: newWorklist.length,
+    new: newEntries.length,
+    stale: staleEntries.length,
+    removed: removedEntries.length,
+    unchanged: unchangedEntries.length,
+    pendingEnrichment: pendingCount,
+    enriched: enrichedCount,
+    syncOps: syncOps.length,
+  };
+  console.log(JSON.stringify(result, null, 2));
+}
+
+sanitize().catch(err => {
+  console.error('[sanitize] FATAL:', err.message);
+  process.exit(1);
+});

package/cli/save-intake-context.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { join, resolve } from 'node:path';
+
+import { ensureProjectMemoryContextDirs, writeJsonArtifact } from '../src/artifacts.mjs';
+import { buildIntakeContext } from '../src/intake-context.mjs';
+
+const [, , projectDescription = '', ...goalArgs] = process.argv;
+
+if (!projectDescription.trim()) {
+  console.error('Usage: node save-intake-context.mjs "project description" goal-one goal-two');
+  process.exit(1);
+}
+
+const projectRoot = resolve(process.cwd());
+const dirs = await ensureProjectMemoryContextDirs(projectRoot);
+const intake = buildIntakeContext({
+  projectDescription,
+  mappingGoals: goalArgs,
+});
+
+await writeJsonArtifact(join(dirs.intake, 'latest-context.json'), intake);
+console.log(JSON.stringify({ saved: true, file: join(dirs.intake, 'latest-context.json'), intake }, null, 2));

package/cli/setup.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+import { bootstrapProjectInstall } from '../src/setup-bootstrap.mjs';
+import { runDoctor } from '../src/doctor.mjs';
+import { resolvePythonBin } from '../src/platform.mjs';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function installGraphify() {
+  const candidates = process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python'];
+  for (const command of candidates) {
+    const result = spawnSync(command, ['-m', 'pip', 'install', 'graphifyy'], { stdio: 'inherit' });
+    if (result.status === 0) return command;
+  }
+  console.warn('\n⚠  Could not install graphifyy automatically. Run: pip install graphifyy\n');
+  return null;
+}
+
+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 rl = createInterface({ input, output });
+const cwd = resolve(process.cwd());
+
+try {
+  console.log('\n─── pmc setup ───────────────────────────────────────\n');
+
+  const ollamaBaseUrl =
+    (await rl.question('Ollama base URL [http://localhost:11434]: ')).trim() ||
+    'http://localhost:11434';
+
+  const ollamaModel =
+    (await rl.question('Ollama model name [deepseek-coder-v2:16b-ctx32k]: ')).trim() ||
+    'deepseek-coder-v2:16b-ctx32k';
+
+  installGraphify();
+
+  const result = await bootstrapProjectInstall({
+    projectRoot: cwd,
+    packageRoot,
+    ollamaBaseUrl,
+    ollamaModel,
+  });
+
+  console.log('\n─── Installation complete ───────────────────────────\n');
+  console.log(`  Memory DB path:     ${result.installState.memoryDbPath}`);
+  console.log(`  Embedding cache:    ${result.installState.embeddingCachePath}`);
+  console.log(`  MCP config:         ${result.configPath}`);
+  console.log(`  Command template:   ${result.commandPath}`);
+
+  // Run doctor to surface any remaining issues
+  console.log('\n─── Environment check ───────────────────────────────\n');
+  const env = {
+    ...process.env,
+    MEMORY_DB_PATH: result.installState.memoryDbPath,
+    EMBEDDING_CACHE_PATH: result.installState.embeddingCachePath,
+  };
+  const { checks } = await runDoctor({ env, resolvePythonBin, spawnCheck });
+
+  const icon = { ok: '✓', warn: '⚠', fail: '✗' };
+  for (const c of checks) {
+    console.log(`  ${icon[c.status]}  ${c.name.padEnd(22)} ${c.message}`);
+  }
+
+  const hasFail = checks.some(c => c.status === 'fail');
+  if (hasFail) {
+    console.log('\nFix the issues above and re-run `pmc setup` if needed.\n');
+  } else {
+    console.log('\nAll checks passed. Run `pmc enrich` to start enriching the project.\n');
+  }
+} finally {
+  rl.close();
+}

package/cli/status.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { readFile, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { detectAgentType, resolveConfigDirs } from '../src/platform.mjs';
+
+export function summarizeWorklist(worklist) {
+  return {
+    pending: worklist.filter((e) => e.status === 'pending' || e.status === 'stale').length,
+    enriched: worklist.filter((e) => e.status === 'enriched' || e.status === 'already_enriched').length,
+    errors: worklist.filter((e) => e.status === 'error').length,
+  };
+}
+
+async function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function getLastSyncTimestamp(enrichmentDir) {
+  const syncManifest = join(enrichmentDir, 'sync-manifest.json');
+  try {
+    const st = await stat(syncManifest);
+    return st.mtime.toISOString();
+  } catch {
+    return null;
+  }
+}
+
+export async function buildStatusReport({ projectRoot = process.cwd() } = {}) {
+  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 worklist = await readJsonSafe(worklistPath);
+  const installState = await readJsonSafe(installStatePath);
+  const lastSync = await getLastSyncTimestamp(enrichmentDir);
+
+  return {
+    ok: true,
+    command: 'status',
+    projectRoot: resolve(projectRoot),
+    configLocation: dirs.projectConfig,
+    agentType: detectAgentType(projectRoot),
+    installState: installState ? { installedAt: installState.installedAt, version: installState.version } : null,
+    worklist: worklist ? summarizeWorklist(worklist) : null,
+    lastSync,
+  };
+}
+
+export async function main(args = process.argv.slice(2)) {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log('Usage: pmc status [project-dir]');
+    console.log('');
+    console.log('Shows enrichment queue state, worklist counts, config location,');
+    console.log('agent type, and last sync timestamp.');
+    return 0;
+  }
+
+  const projectRoot = args.find((a) => !a.startsWith('-')) || process.cwd();
+  const report = await buildStatusReport({ projectRoot });
+  console.log(JSON.stringify(report, null, 2));
+  return 0;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const exitCode = await main().catch((error) => {
+    console.error('[status] FATAL:', error.message);
+    return 1;
+  });
+
+  if (exitCode !== 0) {
+    process.exit(exitCode);
+  }
+}

package/mcp/local-model-server.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const OLLAMA_BASE_URL = (process.env.OLLAMA_BASE_URL ?? 'http://localhost:11434').replace(/\/+$/, '');
+const OLLAMA_MODEL = process.env.OLLAMA_MODEL ?? 'deepseek-coder-v2:16b-ctx32k';
+
+async function generateSemanticReport(prompt) {
+  const system = [
+    'You analyze a single code symbol and must answer in compact structured text.',
+    'Always emit these lines exactly once:',
+    'responsibility: ...',
+    'inputs: item1, item2',
+    'output: ...',
+    'dependencies: dep1, dep2',
+    'role: ...',
+  ].join('\n');
+
+  const response = await fetch(`${OLLAMA_BASE_URL}/api/generate`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model: OLLAMA_MODEL,
+      prompt,
+      system,
+      stream: false,
+      options: {
+        temperature: 0.1,
+        num_ctx: 8192,
+      },
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Ollama API error (${response.status})`);
+  }
+
+  const data = await response.json();
+  const raw = String(data.response ?? '').trim();
+  return {
+    summary: raw.split('\n').find((line) => line.toLowerCase().startsWith('responsibility:'))?.split(':').slice(1).join(':').trim() ?? raw,
+    findings: raw.split('\n').map((line) => line.trim()).filter(Boolean),
+    raw,
+  };
+}
+
+const server = new McpServer({
+  name: 'pmc-local-model',
+  version: '0.1.0',
+});
+
+server.tool(
+  'semantic_report',
+  'Analyze a single symbol prompt with a local Ollama model and return a structured semantic report.',
+  {
+    prompt: z.string().describe('Prepared semantic prompt for a single symbol'),
+  },
+  async ({ prompt }) => {
+    try {
+      const report = await generateSemanticReport(prompt);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(report, null, 2) }],
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: `semantic_report failed: ${String(error)}` }],
+        isError: true,
+      };
+    }
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@aabadin/project-memory-context",
+  "version": "0.1.0",
+  "description": "Portable project memory context CLI — bootstraps semantic enrichment workflows for any AI coding agent.",
+  "license": "GPL-3.0-or-later",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./platform": "./src/platform.mjs",
+    "./retrieval": "./src/retrieval/query-engine.mjs"
+  },
+  "bin": {
+    "pmc": "bin/pmc.mjs"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "test:watch": "node --test --watch tests/*.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "mcp/",
+    "plugin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "memory",
+    "project-context",
+    "semantic-enrichment",
+    "code-intelligence",
+    "graphify",
+    "agent-memory",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adamrdrew/agent-memory-mcp.git",
+    "directory": "tools/project-memory-context"
+  },
+  "author": "Adam Drew",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.26.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "acorn": "^8.16.0",
+    "acorn-walk": "^8.3.0",
+    "zod": "^3.24.0"
+  }
+}

package/plugin/index.mjs

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { buildInjectedPmcConfig } from '../src/plugin-config.mjs';
+
+async function readInstallState(projectRoot) {
+  try {
+    return JSON.parse(await readFile(join(projectRoot, '.planning', 'project-memory-context', 'install.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export default async ({ directory }) => {
+  return {
+    config: async (cfg) => {
+      const installState = await readInstallState(directory);
+      if (!installState) return;
+
+      const injected = buildInjectedPmcConfig({ installState });
+      cfg.mcp = {
+        ...(cfg.mcp ?? {}),
+        ...injected.mcp,
+      };
+    },
+  };
+};

package/src/artifacts.mjs

@@ -0,0 +1,39 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+export async function ensureProjectMemoryContextDirs(projectRoot) {
+  const base = join(projectRoot, '.planning', 'project-memory-context');
+  const projectContext = join(base, 'project-context');
+  const dirs = {
+    base,
+    intake: join(base, 'intake'),
+    graph: join(base, 'graph'),
+    enrichment: join(base, 'enrichment'),
+    runs: join(base, 'runs'),
+    projectContext,
+    projectContextDetected: join(projectContext, 'detected'),
+    projectContextDeclared: join(projectContext, 'declared'),
+    projectContextMaterialized: join(projectContext, 'materialized'),
+    projectContextMarkdown: join(projectContext, 'markdown'),
+    projectContextState: join(projectContext, 'state'),
+  };
+
+  await Promise.all(Object.values(dirs).map((dir) => mkdir(dir, { recursive: true })));
+  return dirs;
+}
+
+export async function writeJsonArtifact(filePath, value) {
+  await mkdir(dirname(filePath), { recursive: true });
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export async function readJsonArtifact(filePath, fallback = null) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return fallback;
+    }
+    throw error;
+  }
+}

package/src/change-detector.mjs

@@ -0,0 +1,10 @@
+export function detectChangedFilesFromHashes(previousHashes, nextHashes) {
+  const changed = [];
+  const files = new Set([...Object.keys(previousHashes), ...Object.keys(nextHashes)]);
+  for (const file of files) {
+    if (previousHashes[file] !== nextHashes[file]) {
+      changed.push(file);
+    }
+  }
+  return changed;
+}