@aabadin/project-memory-context 0.1.0

package/src/finalize-enrichment.mjs

@@ -0,0 +1,30 @@
+import { join } from 'node:path';
+
+import {
+  ensureProjectMemoryContextDirs,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from './artifacts.mjs';
+import { persistEnrichmentResult } from './persist-enrichment-result.mjs';
+import { updateWorklistEntry } from './worklist-state.mjs';
+
+export async function finalizeEnrichment({ projectRoot, result }) {
+  const persisted = await persistEnrichmentResult({ projectRoot, result });
+  const dirs = await ensureProjectMemoryContextDirs(projectRoot);
+  const worklistFile = join(dirs.enrichment, 'worklist.json');
+  const worklist = await readJsonArtifact(worklistFile, []);
+  const updatedWorklist = updateWorklistEntry(worklist, result.symbolKey, {
+    status: result.status,
+    memoryId: result.memoryId,
+    graphNodeId: result.graphNodeId ?? null,
+    enrichedAt: result.enrichedAt,
+    error: undefined,
+  });
+  await writeJsonArtifact(worklistFile, updatedWorklist);
+
+  return {
+    ...persisted,
+    worklistFile,
+    worklist: updatedWorklist,
+  };
+}

package/src/graph-backfill.mjs

@@ -0,0 +1,35 @@
+export function backfillGraphNode({
+  graph,
+  symbolKey,
+  graphNodeId,
+  memoryId,
+  semanticSummary,
+  codeHash,
+  enrichedAt,
+  status,
+}) {
+  return {
+    ...graph,
+    nodes: (graph.nodes ?? []).map((node) => {
+      const matchesGraphNodeId = graphNodeId && node?.id === graphNodeId;
+      const matchesSymbolKey = node?.metadata?.symbolKey === symbolKey;
+      if (!matchesGraphNodeId && !matchesSymbolKey) {
+        return node;
+      }
+
+      return {
+        ...node,
+        metadata: {
+          ...node.metadata,
+          symbolKey,
+          graphNodeId: graphNodeId ?? node.id,
+          memoryId,
+          semanticSummary,
+          codeHash,
+          lastEnrichedAt: enrichedAt,
+          enrichmentStatus: status,
+        },
+      };
+    }),
+  };
+}

package/src/graph-node-resolver.mjs

@@ -0,0 +1,64 @@
+function normalizePath(value) {
+  return String(value ?? '').replace(/\\/g, '/');
+}
+
+function getNodeMetadata(node) {
+  return node?.metadata ?? {};
+}
+
+function extractLabelFromGraphify(raw) {
+  return raw.replace(/^\./, '').replace(/\(\)$/, '');
+}
+
+function inferKindFromLabel(raw) {
+  if (/^\./.test(raw)) return 'function';
+  if (/\.\w+\(\)$/.test(raw)) return 'method';
+  return null;
+}
+
+function findBySymbolKey(graph, symbolKey) {
+  return (graph.nodes ?? []).find((node) => {
+    const metadata = getNodeMetadata(node);
+    return metadata.symbolKey === symbolKey || node.symbolKey === symbolKey;
+  }) ?? null;
+}
+
+function findByFilePathAndName(graph, symbol) {
+  const filePath = normalizePath(symbol.filePath);
+  const candidates = (graph.nodes ?? []).filter((node) => {
+    const nodeFilePath = normalizePath(node.source_file ?? node.filePath ?? '');
+    return nodeFilePath === filePath;
+  });
+
+  const exact = candidates.find((node) => {
+    const raw = node.label ?? '';
+    const cleaned = extractLabelFromGraphify(raw);
+    return cleaned === symbol.name;
+  });
+  if (exact) return exact;
+
+  const inferable = candidates.find((node) => {
+    const raw = node.label ?? '';
+    const cleaned = extractLabelFromGraphify(raw);
+    const inferredKind = inferKindFromLabel(raw);
+    if (cleaned !== symbol.name) return false;
+    if (!inferredKind) return true;
+    if (symbol.kind === 'method' && inferredKind === 'function') return true;
+    if (symbol.kind === inferredKind) return true;
+    return false;
+  });
+  if (inferable) return inferable;
+
+  const normLabel = (symbol.name ?? '').toLowerCase();
+  return candidates.find((node) => (node.norm_label ?? '').toLowerCase() === normLabel) ?? null;
+}
+
+export function attachGraphNodeIds({ symbols, graph }) {
+  return symbols.map((symbol) => {
+    const matchedNode = findBySymbolKey(graph, symbol.symbolKey) ?? findByFilePathAndName(graph, symbol);
+    return {
+      ...symbol,
+      graphNodeId: matchedNode?.id ?? symbol.graphNodeId ?? null,
+    };
+  });
+}

package/src/index.mjs

@@ -0,0 +1,2 @@
+export { resolveCommand, runCommand } from './command-dispatch.mjs';
+export { resolveConfigDirs, resolveGraphify, spawnBackground } from './platform.mjs';

package/src/intake-context.mjs

@@ -0,0 +1,16 @@
+function normalizeString(value) {
+  return String(value ?? '').trim();
+}
+
+function normalizeList(values) {
+  return Array.from(new Set((values ?? []).map((value) => normalizeString(value)).filter(Boolean)));
+}
+
+export function buildIntakeContext({ projectDescription, mappingGoals, focusAreas = [] }) {
+  return {
+    projectDescription: normalizeString(projectDescription),
+    mappingGoals: normalizeList(mappingGoals),
+    focusAreas: normalizeList(focusAreas),
+    createdAt: new Date().toISOString(),
+  };
+}

package/src/invalidation-matrix.mjs

@@ -0,0 +1,33 @@
+import { isAgentInstructionFile, normalizeProjectPath } from './platform.mjs';
+
+const PACKAGE_FILES = new Set(['package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'tsconfig.json', 'global.json']);
+
+export function detectInvalidatedProjectContextKinds(changedFiles) {
+  const invalidated = new Set();
+  for (const file of changedFiles) {
+    const normalizedFile = normalizeProjectPath(file);
+
+    if (PACKAGE_FILES.has(normalizedFile) || normalizedFile.endsWith('.csproj')) {
+      invalidated.add('stack-runtime');
+      invalidated.add('dependencies-summary');
+      invalidated.add('integrations-summary');
+    }
+    if (normalizedFile.startsWith('.planning/project-memory-context/project-context/declared/technical-rules')) {
+      invalidated.add('technical-rules');
+    }
+    if (normalizedFile.startsWith('.planning/project-memory-context/project-context/declared/project-requirements')) {
+      invalidated.add('project-requirements');
+    }
+    if (normalizedFile.startsWith('.planning/project-memory-context/project-context/declared/known-issues-and-fixes')) {
+      invalidated.add('known-issues-and-fixes');
+    }
+    if (normalizedFile.startsWith('.planning/project-memory-context/project-context/declared/architecture-target')) {
+      invalidated.add('architecture-target');
+    }
+    if (normalizedFile === 'README.md' || isAgentInstructionFile(normalizedFile)) {
+      invalidated.add('technical-rules');
+      invalidated.add('project-requirements');
+    }
+  }
+  return [...invalidated];
+}

package/src/markdown-renderer.mjs

@@ -0,0 +1,27 @@
+export function renderProjectContextMarkdown(memory) {
+  const sourceFiles = (memory.source_files ?? []).map((file) => `- \`${file}\``).join('\n') || '- None';
+  const graphRefs = (memory.graph_refs ?? []).map((ref) => `- \`${ref}\``).join('\n') || '- None';
+  return [
+    `# ${memory.title}`,
+    '',
+    `**Kind:** ${memory.kind}`,
+    `**Updated:** ${memory.updated_at}`,
+    '',
+    '## Summary',
+    '',
+    memory.summary,
+    '',
+    '## Body',
+    '',
+    memory.body,
+    '',
+    '## Source Files',
+    '',
+    sourceFiles,
+    '',
+    '## Graph References',
+    '',
+    graphRefs,
+    '',
+  ].join('\n');
+}

package/src/materializer.mjs

@@ -0,0 +1,128 @@
+import { createMaterializedProjectContext } from './project-context-schema.mjs';
+
+function formatList(label, values) {
+  return values?.length ? `- ${label}: ${values.join(', ')}` : `- ${label}: Not detected`;
+}
+
+export function materializeProjectContextMemories({ projectSlug, detected, declared, updatedAt }) {
+  const commonTags = ['project-context', `project:${projectSlug}`];
+
+  return [
+    createMaterializedProjectContext({
+      kind: 'stack-runtime',
+      title: 'Project stack and runtime',
+      summary: `Languages: ${detected.stack.languages.join(', ')}. Frameworks: ${detected.stack.frameworks.join(', ')}.`,
+      body: [
+        formatList('Languages', detected.stack.languages),
+        formatList('Runtimes', detected.stack.runtimes),
+        formatList('Frameworks', detected.stack.frameworks),
+        formatList('Package managers', detected.stack.packageManagers),
+      ].join('\n'),
+      tags: [...commonTags, 'stack'],
+      sourceFiles: ['package.json', 'tsconfig.json'],
+      graphRefs: [],
+      sourceMode: 'detected',
+      confidence: 'high',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'dependencies-summary',
+      title: 'Dependency summary',
+      summary: `Critical dependencies: ${(detected.stack.dependenciesSummary.critical ?? []).join(', ') || 'none'}.`,
+      body: [formatList('Critical', detected.stack.dependenciesSummary.critical), formatList('Testing', detected.stack.dependenciesSummary.testing)].join('\n'),
+      tags: [...commonTags, 'dependencies'],
+      sourceFiles: ['package.json'],
+      graphRefs: [],
+      sourceMode: 'detected',
+      confidence: 'high',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'integrations-summary',
+      title: 'Integration summary',
+      summary: `Detected services: ${(detected.stack.integrations.detectedServices ?? []).join(', ') || 'none'}.`,
+      body: formatList('Services', detected.stack.integrations.detectedServices),
+      tags: [...commonTags, 'integrations'],
+      sourceFiles: ['src'],
+      graphRefs: [],
+      sourceMode: 'detected',
+      confidence: 'medium',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'architecture-current',
+      title: 'Current architecture',
+      summary: `Pattern: ${detected.architecture.pattern}. Entry points: ${(detected.architecture.entryPoints ?? []).join(', ') || 'none'}.`,
+      body: [
+        `- Pattern: ${detected.architecture.pattern}`,
+        formatList('Entry points', detected.architecture.entryPoints),
+      ].join('\n'),
+      tags: [...commonTags, 'architecture', 'current-state'],
+      sourceFiles: detected.architecture.entryPoints,
+      graphRefs: detected.architecture.graphRefs,
+      sourceMode: 'detected',
+      confidence: 'medium',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'architecture-target',
+      title: 'Target architecture',
+      summary: declared.architectureTarget.architecture || 'No target architecture declared.',
+      body: declared.architectureTarget.architecture || 'No target architecture declared.',
+      tags: [...commonTags, 'architecture', 'target-state'],
+      sourceFiles: ['.planning/project-memory-context/project-context/declared/architecture-target.json'],
+      graphRefs: [],
+      sourceMode: 'declared',
+      confidence: 'high',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'structure-summary',
+      title: 'Project structure summary',
+      summary: `Root directories: ${(detected.structure.rootDirectories ?? []).join(', ') || 'none'}.`,
+      body: [formatList('Root directories', detected.structure.rootDirectories), formatList('Key subtrees', detected.structure.keySubtrees), formatList('Entry points', detected.structure.entryPoints)].join('\n'),
+      tags: [...commonTags, 'structure'],
+      sourceFiles: detected.structure.entryPoints,
+      graphRefs: [],
+      sourceMode: 'detected',
+      confidence: 'high',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'technical-rules',
+      title: 'Technical rules',
+      summary: [...(declared.technicalRules.rules ?? []), ...(detected.rules.rules ?? [])].slice(0, 2).join(' '),
+      body: [...(declared.technicalRules.rules ?? []), ...(detected.rules.rules ?? [])].map((line) => `- ${line}`).join('\n'),
+      tags: [...commonTags, 'rules'],
+      sourceFiles: ['README.md'],
+      graphRefs: [],
+      sourceMode: 'merged',
+      confidence: 'medium',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'project-requirements',
+      title: 'Project requirements',
+      summary: (declared.projectRequirements.requirements ?? []).slice(0, 2).join(' '),
+      body: (declared.projectRequirements.requirements ?? []).map((line) => `- ${line}`).join('\n') || '- No declared requirements.',
+      tags: [...commonTags, 'requirements'],
+      sourceFiles: ['.planning/project-memory-context/project-context/declared/project-requirements.json'],
+      graphRefs: [],
+      sourceMode: 'declared',
+      confidence: 'high',
+      updatedAt,
+    }),
+    createMaterializedProjectContext({
+      kind: 'known-issues-and-fixes',
+      title: 'Known issues and fixes',
+      summary: `${(declared.knownIssuesAndFixes.items ?? []).length} known issues recorded.`,
+      body: (declared.knownIssuesAndFixes.items ?? []).map((item) => `- Symptom: ${item.symptom}; Workaround: ${item.workaround}`).join('\n') || '- No known issues recorded.',
+      tags: [...commonTags, 'issues'],
+      sourceFiles: ['.planning/project-memory-context/project-context/declared/known-issues-and-fixes.json'],
+      graphRefs: [],
+      sourceMode: 'declared',
+      confidence: 'high',
+      updatedAt,
+    }),
+  ];
+}

package/src/memory-payload.mjs

@@ -0,0 +1,55 @@
+function normalizeList(values) {
+  return (values ?? []).map((value) => String(value).trim()).filter(Boolean);
+}
+
+export function buildMemoryPayload({ projectSlug, job, semantic }) {
+  const inputs = normalizeList(semantic.inputs);
+  const dependencies = normalizeList(semantic.dependencies);
+  const tags = [
+    'symbol',
+    job.language,
+    job.kind,
+    `project:${projectSlug}`,
+    `file:${job.filePath}`,
+  ];
+
+  const content = [
+    `Symbol: ${job.name}`,
+    `Kind: ${job.kind}`,
+    `Language: ${job.language}`,
+    `Location: ${job.filePath}:${job.range.startLine}-${job.range.endLine}`,
+    '',
+    'Responsibility:',
+    semantic.responsibility,
+    '',
+    'Inputs:',
+    ...(inputs.length > 0 ? inputs.map((input) => `- ${input}`) : ['- None detected']),
+    '',
+    'Output:',
+    semantic.output,
+    '',
+    'Immediate dependencies:',
+    ...(dependencies.length > 0 ? dependencies.map((dependency) => `- ${dependency}`) : ['- None detected']),
+    '',
+    'Role in module:',
+    semantic.role,
+  ].join('\n');
+
+  return {
+    content,
+    category: 'architecture',
+    tags,
+  };
+}
+
+export function buildEnrichmentResult({ job, memoryId, semanticSummary, status, enrichedAt }) {
+  return {
+    symbolKey: job.symbolKey,
+    graphNodeId: job.graphNodeId ?? null,
+    memoryId,
+    codeHash: job.codeHash,
+    semanticSummary,
+    status,
+    enrichedAt,
+  };
+}

package/src/persist-enrichment-result.mjs

@@ -0,0 +1,33 @@
+import { join } from 'node:path';
+
+import {
+  ensureProjectMemoryContextDirs,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from './artifacts.mjs';
+import { applyEnrichmentResult } from './enrichment-linker.mjs';
+
+export async function persistEnrichmentResult({ projectRoot, result }) {
+  const dirs = await ensureProjectMemoryContextDirs(projectRoot);
+  const graphFile = join(dirs.graph, 'graph.json');
+  const indexFile = join(dirs.enrichment, 'symbol-index.json');
+
+  const graph = await readJsonArtifact(graphFile, { nodes: [], edges: [] });
+  const symbolIndex = await readJsonArtifact(indexFile, {});
+
+  const updated = applyEnrichmentResult({
+    graph,
+    symbolIndex,
+    result,
+  });
+
+  await writeJsonArtifact(graphFile, updated.graph);
+  await writeJsonArtifact(indexFile, updated.symbolIndex);
+
+  return {
+    graphFile,
+    indexFile,
+    graph: updated.graph,
+    symbolIndex: updated.symbolIndex,
+  };
+}

package/src/platform.mjs

@@ -0,0 +1,111 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, posix, resolve } from 'node:path';
+
+const PROJECT_DIR_NAMES = ['.pmc', '.opencode', '.claude', '.cursor'];
+const INSTRUCTION_FILES = new Set([
+  'AGENTS.md',
+  'CLAUDE.md',
+  'GEMINI.md',
+  '.cursorrules',
+  '.windsurfrules',
+]);
+
+export function normalizeProjectPath(filePath) {
+  if (filePath === '') return '';
+  // Converts backslashes to forward slashes and resolves . / .. segments.
+  // posix.normalize preserves meaningful spaces.
+  return posix.normalize(String(filePath).replace(/\\/g, '/'));
+}
+
+export function isAgentInstructionFile(filePath) {
+  const normalizedPath = normalizeProjectPath(filePath);
+  return INSTRUCTION_FILES.has(normalizedPath.split('/').at(-1));
+}
+
+export function detectAgentType(projectRoot) {
+  if (existsSync(join(projectRoot, '.opencode'))) return 'opencode';
+  if (existsSync(join(projectRoot, 'CLAUDE.md'))) return 'claude-code';
+  if (existsSync(join(projectRoot, '.claude'))) return 'claude-code';
+  if (existsSync(join(projectRoot, '.cursorrules'))) return 'cursor';
+  if (existsSync(join(projectRoot, '.cursor'))) return 'cursor';
+  return 'generic';
+}
+
+export function resolveConfigDirs(projectRoot = process.cwd(), options = {}) {
+  const root = resolve(projectRoot);
+  const exists = options.exists ?? existsSync;
+  const homeDir = options.homeDir ?? homedir();
+
+  const projectConfig = PROJECT_DIR_NAMES
+    .map((name) => join(root, name))
+    .find((candidate) => exists(candidate)) ?? join(root, '.pmc');
+
+  const globalConfig = [
+    join(homeDir, '.config', 'pmc'),
+    join(homeDir, '.config', 'opencode'),
+    join(homeDir, '.claude'),
+  ].find((candidate) => exists(candidate)) ?? join(homeDir, '.config', 'pmc');
+
+  return {
+    projectRoot: root,
+    projectConfig,
+    globalConfig,
+    projectConfigDir: projectConfig,
+    globalConfigDir: globalConfig,
+  };
+}
+
+export function spawnBackground(command, args = [], options = {}) {
+  const spawnImpl = options.spawnImpl ?? spawn;
+  // Always use array-form args (never shell: true with a concatenated string)
+  // so paths containing spaces are passed correctly on all platforms.
+  const child = spawnImpl(command, args, {
+    cwd: options.cwd,
+    detached: true,
+    stdio: 'ignore',
+    shell: false,
+  });
+
+  child.unref();
+  return child.pid;
+}
+
+export function resolvePythonBin(options = {}) {
+  const platform = options.platform ?? process.platform;
+  const execFileSyncImpl = options.execFileSyncImpl ?? execFileSync;
+
+  if (platform === 'win32') {
+    return 'python';
+  }
+
+  try {
+    execFileSyncImpl('python3', ['--version'], { stdio: 'ignore' });
+    return 'python3';
+  } catch {
+    return 'python';
+  }
+}
+
+export function resolveGraphify(options = {}) {
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const execFileSyncImpl = options.execFileSyncImpl ?? execFileSync;
+
+  if (env.PMC_GRAPHIFY_PATH) {
+    return env.PMC_GRAPHIFY_PATH;
+  }
+
+  if (env.PMC_GRAPHIFY_BIN) {
+    return env.PMC_GRAPHIFY_BIN;
+  }
+
+  const finder = platform === 'win32' ? 'where' : 'which';
+
+  try {
+    return execFileSyncImpl(finder, ['graphify'], { encoding: 'utf8' }).trim().split(/\r?\n/)[0];
+  } catch {
+    throw new Error('graphify not found. Install it with `pip install graphifyy` or set PMC_GRAPHIFY_PATH or PMC_GRAPHIFY_BIN.');
+  }
+}

package/src/plugin-config.mjs

@@ -0,0 +1,17 @@
+export function buildInjectedPmcConfig({ installState }) {
+  return {
+    mcp: {
+      'pmc-agent-memory': {
+        type: 'local',
+        command: ['npx', '-y', '@aabadin/agent-memory-mcp'],
+        enabled: true,
+        environment: {
+          MEMORY_DB_PATH: installState.memoryDbPath,
+          EMBEDDING_MODEL: 'Xenova/bge-m3',
+          EMBEDDING_DIMENSIONS: '1024',
+          EMBEDDING_POOLING: 'cls',
+        },
+      },
+    },
+  };
+}

package/src/prepare-semantic-jobs.mjs

@@ -0,0 +1,33 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+
+import {
+  ensureProjectMemoryContextDirs,
+  readJsonArtifact,
+  writeJsonArtifact,
+} from './artifacts.mjs';
+import { buildSemanticUnit } from './semantic-unit.mjs';
+
+export async function prepareSemanticJobs({ projectRoot }) {
+  const resolvedRoot = resolve(projectRoot);
+  const dirs = await ensureProjectMemoryContextDirs(resolvedRoot);
+  const worklistFile = join(dirs.enrichment, 'worklist.json');
+  const outputFile = join(dirs.enrichment, 'semantic-jobs.json');
+  const worklist = await readJsonArtifact(worklistFile, []);
+
+  const pendingSymbols = worklist.filter((symbol) => symbol.status === 'pending');
+  const jobs = [];
+
+  for (const symbol of pendingSymbols) {
+    const absoluteFile = resolve(resolvedRoot, symbol.filePath);
+    const content = await readFile(absoluteFile, 'utf8');
+    jobs.push(buildSemanticUnit({ symbol, content }));
+  }
+
+  await writeJsonArtifact(outputFile, jobs);
+  return {
+    file: outputFile,
+    count: jobs.length,
+    jobs,
+  };
+}

package/src/project-context-schema.mjs

@@ -0,0 +1,57 @@
+import { createHash } from 'node:crypto';
+
+export const PROJECT_CONTEXT_KINDS = [
+  'stack-runtime',
+  'dependencies-summary',
+  'integrations-summary',
+  'architecture-current',
+  'architecture-target',
+  'structure-summary',
+  'technical-rules',
+  'project-requirements',
+  'known-issues-and-fixes',
+];
+
+export function buildProjectContextMemoryKey(kind) {
+  if (!PROJECT_CONTEXT_KINDS.includes(kind)) {
+    throw new Error(`Unknown project context kind: ${kind}`);
+  }
+  return `project-context:${kind}`;
+}
+
+export function hashProjectContextContent(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+export function createMaterializedProjectContext({
+  kind,
+  title,
+  summary,
+  body,
+  tags,
+  sourceFiles,
+  graphRefs,
+  sourceMode,
+  confidence,
+  detectedSources = [],
+  declaredSources = [],
+  updatedAt,
+}) {
+  const contentShape = { title, summary, body, tags, sourceFiles, graphRefs, sourceMode, confidence, detectedSources, declaredSources };
+  return {
+    memory_key: buildProjectContextMemoryKey(kind),
+    title,
+    kind,
+    source_mode: sourceMode,
+    summary,
+    body,
+    tags,
+    source_files: sourceFiles,
+    graph_refs: graphRefs,
+    detected_sources: detectedSources,
+    declared_sources: declaredSources,
+    confidence,
+    content_hash: hashProjectContextContent(contentShape),
+    updated_at: updatedAt,
+  };
+}