memorix 1.4.0 → 1.4.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Local-first shared memory layer for AI coding agents across MCP clients, Git history, reasoning context, and project sessions.",
   "type": "module",
   "sideEffects": false,
@@ -44,6 +44,7 @@
     "README.zh-CN.md",
     "assets",
     "docs",
+    "!docs/dev-log",
     "!docs/memcode",
     "!docs/superpowers",
     "plugins",
@@ -69,9 +70,11 @@
     "generate:star-history": "node scripts/generate-star-history.mjs",
     "sync:mcp-registry": "node scripts/sync-mcp-registry-manifest.mjs",
     "check:mcp-registry": "node scripts/check-mcp-registry-manifest.mjs",
+    "sync:plugin-release": "node scripts/sync-plugin-release-manifests.mjs",
+    "check:plugin-release": "node scripts/sync-plugin-release-manifests.mjs --check",
     "audit:pi-upstream": "node scripts/pi-upstream-audit.mjs",
     "lint": "tsc --noEmit",
-    "prepublishOnly": "npm run sync:mcp-registry && npm run check:mcp-registry && npm run build && npm test"
+    "prepublishOnly": "npm run sync:mcp-registry && npm run sync:plugin-release && npm run check:mcp-registry && npm run check:plugin-release && npm run build && npm test"
   },
   "keywords": [
     "mcp",

package/plugins/claude/memorix/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "memorix",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Shared workspace memory for Claude Code and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/codex/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Shared workspace memory for Codex and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/copilot/memorix/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Shared local workspace memory for GitHub Copilot CLI and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/gemini/memorix/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "mcpServers": {
     "memorix": {
       "command": "memorix",

package/plugins/omp/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-omp-package",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Memorix shared workspace memory package for Oh-my-Pi.",
   "license": "Apache-2.0",
   "keywords": [

package/plugins/openclaw/memorix/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Shared workspace memory for OpenClaw and other AI coding agents.",
   "author": {
     "name": "AVIDS2",

package/plugins/pi/memorix/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memorix-pi-package",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Memorix shared workspace memory package for Pi coding agent.",
   "license": "Apache-2.0",
   "keywords": [

package/server.json

@@ -7,7 +7,7 @@
     "url": "https://github.com/AVIDS2/memorix",
     "source": "github"
   },
-  "version": "1.4.0",
+  "version": "1.4.2",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.4.0",
+      "version": "1.4.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli/commands/codegraph.ts

@@ -58,12 +58,52 @@ function formatUsageHint(): string {
     'Usage:',
     '  memorix codegraph refresh',
     '  memorix codegraph status --json',
+    '  memorix codegraph diff [--from <snapshot>] [--to <snapshot>]',
+    '  memorix codegraph impact --path <relative-source-path>',
     '  memorix codegraph context-pack --task "continue auth bug"',
     '',
     'Tip: use `memorix context "..."` for new work or `memorix resume "..."` for prior work.',
   ].join('\n');
 }
 
+function formatDiff(diff: ReturnType<CodeGraphStore['diffSnapshots']>, impact: ReturnType<CodeGraphStore['impactSlice']>): string {
+  if (!diff.available) {
+    return `CodeGraph diff is unavailable: ${diff.reason ?? 'unknown reason'}. Refresh twice to establish comparable snapshots.`;
+  }
+  const summary = diff.changes.reduce((counts, change) => {
+    counts[change.kind] += 1;
+    return counts;
+  }, { added: 0, modified: 0, removed: 0 });
+  const lines = [
+    `CodeGraph diff: ${diff.fromSnapshotId} -> ${diff.toSnapshotId}`,
+    `- Changed files: ${diff.changes.length} (${summary.added} added, ${summary.modified} modified, ${summary.removed} removed)`,
+  ];
+  for (const change of diff.changes.slice(0, 20)) lines.push(`- ${change.kind}: ${change.path}`);
+  if (diff.changes.length > 20) lines.push(`- ${diff.changes.length - 20} additional file change(s) omitted`);
+  if (impact.directlyConnectedPaths.length > 0) {
+    lines.push('', 'Current one-hop structural impact');
+    for (const path of impact.directlyConnectedPaths.slice(0, 20)) lines.push(`- ${path}`);
+  }
+  if (impact.relationCount === 0) lines.push('', 'No current file-edge relation was found for the changed paths.');
+  if (impact.truncated) lines.push('- Impact relation limit reached; inspect the graph before assuming coverage.');
+  return lines.join('\n');
+}
+
+function formatImpact(impact: ReturnType<CodeGraphStore['impactSlice']>): string {
+  const lines = [
+    `CodeGraph current one-hop impact: ${impact.changedPaths.join(', ')}`,
+    `- Relations inspected: ${impact.relationCount}`,
+  ];
+  if (impact.directlyConnectedPaths.length > 0) {
+    lines.push('- Directly connected paths:');
+    for (const path of impact.directlyConnectedPaths) lines.push(`  - ${path}`);
+  } else {
+    lines.push('- No current file-edge relation was found for this indexed path.');
+  }
+  if (impact.truncated) lines.push('- Impact relation limit reached; inspect the graph before assuming coverage.');
+  return lines.join('\n');
+}
+
 function compactFacts(project: { rootPath: string }): { facts: string[]; dirty: boolean } {
   const current = collectCurrentProjectFacts({ project, now: new Date() });
   const facts: string[] = [];
@@ -82,9 +122,13 @@ export default defineCommand({
     description: 'Inspect and refresh CodeGraph Memory for the current project',
   },
   args: {
-    action: { type: 'string', description: 'Action: status, refresh, or context-pack' },
+    action: { type: 'string', description: 'Action: status, refresh, diff, impact, or context-pack' },
     task: { type: 'string', description: 'Task text for context-pack' },
+    path: { type: 'string', description: 'Indexed relative source path for impact' },
     limit: { type: 'string', description: 'Max active memories to inspect for context-pack' },
+    from: { type: 'string', description: 'Earlier CodeGraph snapshot id for diff' },
+    to: { type: 'string', description: 'Later CodeGraph snapshot id for diff' },
+    impactLimit: { type: 'string', description: 'Maximum graph relations to inspect for diff impact' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
   },
   run: async ({ args }) => {
@@ -162,6 +206,43 @@ export default defineCommand({
           return;
         }
 
+        case 'diff': {
+          const snapshots = store.listSnapshots(project.id, 2);
+          const fromSnapshotId = (args.from as string | undefined)?.trim() || snapshots[1]?.id;
+          const toSnapshotId = (args.to as string | undefined)?.trim() || snapshots[0]?.id;
+          if (!fromSnapshotId || !toSnapshotId) {
+            emitError('two completed CodeGraph snapshots are required; run "memorix codegraph refresh" again after a code change.', asJson);
+            return;
+          }
+          const diff = store.diffSnapshots(project.id, fromSnapshotId, toSnapshotId);
+          const impact = store.impactSlice(
+            project.id,
+            diff.changes.map(change => change.path),
+            parsePositiveInt(args.impactLimit as string | undefined, 24),
+          );
+          emitResult({ project, diff, impact }, formatDiff(diff, impact), asJson);
+          return;
+        }
+
+        case 'impact': {
+          const sourcePath = (args.path as string | undefined)?.trim() || positional.slice(1).join(' ').trim();
+          if (!sourcePath) {
+            emitError('path is required for "memorix codegraph impact"', asJson);
+            return;
+          }
+          if (!store.getFile(project.id, sourcePath)) {
+            emitError(`path is not in the current CodeGraph index: ${sourcePath}. Run "memorix codegraph refresh" and retry.`, asJson);
+            return;
+          }
+          const impact = store.impactSlice(
+            project.id,
+            [sourcePath],
+            parsePositiveInt(args.impactLimit as string | undefined, 24),
+          );
+          emitResult({ project, impact }, formatImpact(impact), asJson);
+          return;
+        }
+
         case 'context-pack': {
           const task = (args.task as string | undefined)?.trim() || positional.slice(1).join(' ').trim();
           if (!task) {
@@ -224,7 +305,7 @@ export default defineCommand({
         }
 
         default:
-          emitError(`unknown codegraph action "${action}". Use "status", "refresh", or "context-pack".`, asJson);
+          emitError(`unknown codegraph action "${action}". Use "status", "refresh", "diff", "impact", or "context-pack".`, asJson);
       }
     } catch (error) {
       emitError(error instanceof Error ? error.message : String(error), asJson);

package/src/codegraph/auto-context.ts

@@ -259,6 +259,25 @@ export async function buildAutoProjectContext(input: {
   const overview = explain.overview;
   const currentFacts = collectCurrentProjectFacts({ project: input.project, now });
   const latestSnapshot = overview.code.latestSnapshot;
+  let codeEvolution: TaskWorkset['codeEvolution'];
+  if (continuationRequested && latestSnapshot?.previousSnapshotId && latestSnapshot.changedPathCount > 0) {
+    const diff = store.diffSnapshots(input.project.id, latestSnapshot.previousSnapshotId, latestSnapshot.id);
+    if (diff.available && diff.changes.length > 0) {
+      const impact = store.impactSlice(input.project.id, diff.changes.map(change => change.path));
+      const changedFileIds = new Set([
+        ...store.listSnapshotFiles(diff.fromSnapshotId),
+        ...store.listSnapshotFiles(diff.toSnapshotId),
+      ].filter(file => diff.changes.some(change => change.path === file.path)).map(file => file.fileId));
+      codeEvolution = {
+        fromSnapshotId: diff.fromSnapshotId,
+        toSnapshotId: diff.toSnapshotId,
+        changes: diff.changes.slice(0, 5).map(change => ({ path: change.path, kind: change.kind })),
+        directlyConnectedPaths: impact.directlyConnectedPaths.slice(0, 3),
+        affectedMemoryCount: store.countStaleObservationRefsForFiles(input.project.id, [...changedFileIds]),
+        truncated: impact.truncated || diff.changes.length > 5,
+      };
+    }
+  }
   const sourceSets = lensSourceSets({ task, lens, explain });
   let externalOutline: ExternalCodeGraphOutline | undefined;
   let externalCaution: string | undefined;
@@ -348,6 +367,7 @@ export async function buildAutoProjectContext(input: {
     currentFacts: worksetFactLines(currentFacts),
     ...(continuation ? { continuation } : {}),
     codeState: codeStateLine(overview),
+    ...(codeEvolution ? { codeEvolution } : {}),
     reliableMemory: sourceSets.reliableSources
       .slice(0, lens.sourceLimit)
       .map(source => ({

package/src/codegraph/current-facts.ts

@@ -129,6 +129,7 @@ function detectStaleProgressNotes(input: {
   now: Date;
 }): ProjectStaleNote[] {
   const candidates = [
+    'ACTIVE_WORK.md',
     'progress.txt',
     'docs/dev-log/progress.txt',
     'docs/memcode/dev-log/progress.txt',

package/src/codegraph/external-provider.ts

@@ -302,6 +302,7 @@ function providerQuality(input: {
       capabilities: {
         declarations: true,
         importHints: true,
+        localRelativeImportTargets: true,
         resolvedRelations: false,
         exactLocations: false,
       },

package/src/codegraph/store.ts

@@ -1,9 +1,14 @@
 import { randomUUID } from 'node:crypto';
+import { posix as pathPosix } from 'node:path';
 import { getDatabase } from '../store/sqlite-db.js';
 import type {
   CodeEdge,
   CodeFile,
+  CodeGraphImpactSlice,
   CodeGraphStatus,
+  CodeStateDiff,
+  CodeStateFileChange,
+  CodeStateSnapshotFile,
   CodeStateScanCompleteness,
   CodeStateSnapshot,
   CodeStateSnapshotInput,
@@ -71,6 +76,41 @@ function rowToEdge(row: any): CodeEdge {
   } as CodeEdge;
 }
 
+function resolveRelativeImportTarget(
+  sourcePath: string,
+  evidence: string | undefined,
+  fileByPath: Map<string, CodeFile>,
+): CodeFile | undefined {
+  const target = evidence?.trim().replace(/\\/g, '/');
+  if (!target?.startsWith('.')) return undefined;
+  const base = normalizeCodePath(pathPosix.normalize(pathPosix.join(pathPosix.dirname(sourcePath), target)));
+  if (!base || base === '..' || base.startsWith('../')) return undefined;
+  const candidates = [base];
+  const extensionMatch = base.match(/(\.[A-Za-z0-9]+)$/);
+  const hasExtension = Boolean(extensionMatch);
+  if (!hasExtension) {
+    const extensions = [...new Set([...fileByPath.keys()]
+      .map(path => path.match(/(\.[A-Za-z0-9]+)$/)?.[1])
+      .filter((extension): extension is string => Boolean(extension)))];
+    for (const extension of extensions) {
+      candidates.push(`${base}${extension}`, `${base}/index${extension}`);
+    }
+  } else {
+    // Node ESM projects commonly import the emitted .js path from a .ts source.
+    // Keep an exact path first, then resolve only equivalent local source forms.
+    const sourceStem = base.slice(0, -extensionMatch![1].length);
+    const sourceExtensions = extensionMatch![1] === '.js'
+      ? ['.ts', '.tsx', '.js', '.jsx']
+      : extensionMatch![1] === '.mjs'
+        ? ['.mts', '.mjs']
+        : extensionMatch![1] === '.cjs'
+          ? ['.cts', '.cjs']
+          : [];
+    for (const extension of sourceExtensions) candidates.push(`${sourceStem}${extension}`);
+  }
+  return candidates.map(candidate => fileByPath.get(candidate)).find((file): file is CodeFile => Boolean(file));
+}
+
 function rowToRef(row: any): ObservationCodeRef {
   return {
     id: row.id,
@@ -134,6 +174,22 @@ function rowToSnapshot(row: any): CodeStateSnapshot {
   } as CodeStateSnapshot;
 }
 
+function rowToSnapshotFile(row: any): CodeStateSnapshotFile {
+  return {
+    snapshotId: row.snapshotId,
+    projectId: row.projectId,
+    fileId: row.fileId,
+    path: row.path,
+    contentHash: row.contentHash,
+  };
+}
+
+function snapshotIsIncomplete(snapshot: CodeStateSnapshot): boolean {
+  return snapshot.completeness.skippedOversizedFiles > 0
+    || (snapshot.completeness.unreadableFiles ?? 0) > 0
+    || snapshot.completeness.removalScanDeferred;
+}
+
 export class CodeGraphStore {
   private db: any = null;
   private dataDir: string | null = null;
@@ -312,6 +368,7 @@ export class CodeGraphStore {
     });
 
     tx();
+    this.reconcileLocalImportTargets(projectId);
   }
 
   /**
@@ -329,7 +386,10 @@ export class CodeGraphStore {
     const changed = input.changed.filter((delta) => delta.file.projectId === projectId);
     const metadataOnly = (input.metadataOnly ?? []).filter((file) => file.projectId === projectId);
     const removedFileIds = input.removedFileIds ?? [];
-    if (changed.length === 0 && metadataOnly.length === 0 && removedFileIds.length === 0) return;
+    if (changed.length === 0 && metadataOnly.length === 0 && removedFileIds.length === 0) {
+      this.reconcileLocalImportTargets(projectId);
+      return;
+    }
 
     const staleRefsForFile = this.db.prepare(`
       UPDATE observation_code_refs
@@ -340,9 +400,18 @@ export class CodeGraphStore {
         )
       )
     `);
-    const deleteEdgesForFile = this.db.prepare(`
+    const deleteEdgesFromFile = this.db.prepare(`
+      DELETE FROM code_edges
+      WHERE projectId = ? AND fromFileId = ?
+    `);
+    const clearImportTargetsForFile = this.db.prepare(`
+      UPDATE code_edges
+      SET toFileId = NULL
+      WHERE projectId = ? AND toFileId = ? AND type = 'imports'
+    `);
+    const deleteOtherIncomingEdgesForFile = this.db.prepare(`
       DELETE FROM code_edges
-      WHERE projectId = ? AND (fromFileId = ? OR toFileId = ?)
+      WHERE projectId = ? AND toFileId = ? AND type != 'imports'
     `);
     const deleteSymbolsForFile = this.db.prepare(`DELETE FROM code_symbols WHERE projectId = ? AND fileId = ?`);
     const deleteFile = this.db.prepare(`DELETE FROM code_files WHERE projectId = ? AND id = ?`);
@@ -380,7 +449,9 @@ export class CodeGraphStore {
       const staleAt = new Date().toISOString();
       for (const fileId of removedFileIds) {
         staleRefsForFile.run(staleAt, projectId, fileId, projectId, fileId);
-        deleteEdgesForFile.run(projectId, fileId, fileId);
+        deleteEdgesFromFile.run(projectId, fileId);
+        clearImportTargetsForFile.run(projectId, fileId);
+        deleteOtherIncomingEdgesForFile.run(projectId, fileId);
         deleteSymbolsForFile.run(projectId, fileId);
         deleteFile.run(projectId, fileId);
       }
@@ -388,7 +459,9 @@ export class CodeGraphStore {
       for (const delta of changed) {
         const fileId = delta.file.id;
         staleRefsForFile.run(staleAt, projectId, fileId, projectId, fileId);
-        deleteEdgesForFile.run(projectId, fileId, fileId);
+        deleteEdgesFromFile.run(projectId, fileId);
+        clearImportTargetsForFile.run(projectId, fileId);
+        deleteOtherIncomingEdgesForFile.run(projectId, fileId);
         deleteSymbolsForFile.run(projectId, fileId);
         writeFile(delta.file);
 
@@ -429,6 +502,7 @@ export class CodeGraphStore {
       for (const file of metadataOnly) writeFile(file);
     });
     tx();
+    this.reconcileLocalImportTargets(projectId);
   }
 
   upsertObservationRefs(refs: ObservationCodeRef[]): void {
@@ -493,6 +567,26 @@ export class CodeGraphStore {
     tx();
   }
 
+  /**
+   * Lite import extraction records the original import text first. Resolve only
+   * local relative imports against the current index after each refresh, so an
+   * added or removed target cannot leave a fabricated file-to-file relation.
+   */
+  reconcileLocalImportTargets(projectId: string): void {
+    const fileById = new Map(this.listFiles(projectId).map(file => [file.id, file]));
+    const fileByPath = new Map([...fileById.values()].map(file => [file.path, file]));
+    const update = this.db.prepare('UPDATE code_edges SET toFileId = ? WHERE id = ?');
+    const tx = this.db.transaction(() => {
+      for (const edge of this.listEdges(projectId)) {
+        if (edge.type !== 'imports' || !edge.fromFileId) continue;
+        const source = fileById.get(edge.fromFileId);
+        const target = source ? resolveRelativeImportTarget(source.path, edge.evidence, fileByPath) : undefined;
+        update.run(target?.id ?? null, edge.id);
+      }
+    });
+    tx();
+  }
+
   getFile(projectId: string, path: string): CodeFile | null {
     const row = this.db.prepare(`SELECT * FROM code_files WHERE projectId = ? AND path = ?`).get(projectId, normalizeCodePath(path));
     return row ? rowToFile(row) : null;
@@ -577,6 +671,19 @@ export class CodeGraphStore {
     `).all(projectId).map(rowToRef);
   }
 
+  /** Count distinct observations whose binding to these exact files is stale. */
+  countStaleObservationRefsForFiles(projectId: string, fileIds: string[]): number {
+    const ids = [...new Set(fileIds.filter(Boolean))];
+    if (ids.length === 0) return 0;
+    const placeholders = ids.map(() => '?').join(', ');
+    const row = this.db.prepare(`
+      SELECT COUNT(DISTINCT observationId) AS count
+      FROM observation_code_refs
+      WHERE projectId = ? AND status = 'stale' AND fileId IN (${placeholders})
+    `).get(projectId, ...ids);
+    return Number(row?.count ?? 0);
+  }
+
   listReferencedSymbols(projectId: string): CodeSymbol[] {
     return this.db.prepare(`
       SELECT DISTINCT symbols.*
@@ -601,6 +708,100 @@ export class CodeGraphStore {
     ).all(projectId, safeLimit).map(rowToSnapshot);
   }
 
+  listSnapshotFiles(snapshotId: string): CodeStateSnapshotFile[] {
+    return this.db.prepare(`
+      SELECT snapshotId, projectId, fileId, path, contentHash
+      FROM code_state_snapshot_files
+      WHERE snapshotId = ?
+      ORDER BY path
+    `).all(snapshotId).map(rowToSnapshotFile);
+  }
+
+  diffSnapshots(projectId: string, fromSnapshotId: string, toSnapshotId: string): CodeStateDiff {
+    const snapshots = this.db.prepare(`
+      SELECT * FROM code_state_snapshots WHERE id IN (?, ?)
+    `).all(fromSnapshotId, toSnapshotId).map(rowToSnapshot) as CodeStateSnapshot[];
+    if (snapshots.length !== 2) {
+      return { projectId, fromSnapshotId, toSnapshotId, available: false, reason: 'missing-snapshot', changes: [] };
+    }
+    if (snapshots.some(snapshot => snapshot.projectId !== projectId)) {
+      return { projectId, fromSnapshotId, toSnapshotId, available: false, reason: 'project-mismatch', changes: [] };
+    }
+    if (snapshots.some(snapshotIsIncomplete)) {
+      return { projectId, fromSnapshotId, toSnapshotId, available: false, reason: 'incomplete-snapshot', changes: [] };
+    }
+    const before = this.listSnapshotFiles(fromSnapshotId);
+    const after = this.listSnapshotFiles(toSnapshotId);
+    if (before.length === 0 || after.length === 0) {
+      return {
+        projectId,
+        fromSnapshotId,
+        toSnapshotId,
+        available: false,
+        reason: 'legacy-snapshot-without-manifest',
+        changes: [],
+      };
+    }
+    const beforeByPath = new Map(before.map(file => [file.path, file]));
+    const afterByPath = new Map(after.map(file => [file.path, file]));
+    const paths = [...new Set([...beforeByPath.keys(), ...afterByPath.keys()])].sort();
+    const changes: CodeStateFileChange[] = [];
+    for (const path of paths) {
+      const oldFile = beforeByPath.get(path);
+      const newFile = afterByPath.get(path);
+      if (!oldFile && newFile) {
+        changes.push({ path, kind: 'added', afterHash: newFile.contentHash });
+      } else if (oldFile && !newFile) {
+        changes.push({ path, kind: 'removed', beforeHash: oldFile.contentHash });
+      } else if (oldFile && newFile && oldFile.contentHash !== newFile.contentHash) {
+        changes.push({ path, kind: 'modified', beforeHash: oldFile.contentHash, afterHash: newFile.contentHash });
+      }
+    }
+    return { projectId, fromSnapshotId, toSnapshotId, available: true, changes };
+  }
+
+  impactSlice(projectId: string, changedPaths: string[], maxRelations = 24): CodeGraphImpactSlice {
+    const safeLimit = Number.isFinite(maxRelations) ? Math.max(1, Math.min(100, Math.floor(maxRelations))) : 24;
+    const normalizedPaths = [...new Set(changedPaths.map(normalizeCodePath).filter(Boolean))].sort();
+    const files = this.listFiles(projectId);
+    const fileById = new Map(files.map(file => [file.id, file.path]));
+    const fileIdBySymbolId = new Map(this.listSymbols(projectId).map(symbol => [symbol.id, symbol.fileId]));
+    const changedIds = new Set(files.filter(file => normalizedPaths.includes(file.path)).map(file => file.id));
+    const direct = new Set<string>();
+    let relationCount = 0;
+    let truncated = false;
+    for (const edge of this.listEdges(projectId)) {
+      const endpoints = [
+        edge.fromFileId,
+        edge.toFileId,
+        edge.fromSymbolId ? fileIdBySymbolId.get(edge.fromSymbolId) : undefined,
+        edge.toSymbolId ? fileIdBySymbolId.get(edge.toSymbolId) : undefined,
+      ].filter((id): id is string => Boolean(id));
+      if (!endpoints.some(id => changedIds.has(id))) continue;
+      const relatedPaths = endpoints
+        .filter(id => !changedIds.has(id))
+        .map(id => fileById.get(id))
+        .filter((path): path is string => Boolean(path));
+      if (relatedPaths.length === 0) continue;
+      if (relationCount >= safeLimit) {
+        truncated = true;
+        break;
+      }
+      relationCount += 1;
+      for (const path of relatedPaths) direct.add(path);
+    }
+    const snapshot = this.latestSnapshot(projectId);
+    return {
+      projectId,
+      ...(snapshot ? { snapshotId: snapshot.id } : {}),
+      changedPaths: normalizedPaths,
+      directlyConnectedPaths: [...direct].sort(),
+      relationCount,
+      truncated,
+      provider: snapshot?.provider ?? 'lite',
+    };
+  }
+
   /**
    * Record a completed scan and mark all current structural facts with its
    * epoch. The snapshot is written only after refresh reconciliation succeeds,
@@ -642,6 +843,16 @@ export class CodeGraphStore {
       this.db.prepare(
         "UPDATE observation_code_refs SET snapshotId = ? WHERE projectId = ? AND status = 'current'",
       ).run(id, input.projectId);
+      const snapshotFileRows = this.db.prepare(`
+        SELECT id, projectId, path, contentHash FROM code_files WHERE projectId = ? ORDER BY path
+      `).all(input.projectId) as Array<{ id: string; projectId: string; path: string; contentHash: string }>;
+      const insertSnapshotFile = this.db.prepare(`
+        INSERT INTO code_state_snapshot_files (snapshotId, projectId, fileId, path, contentHash)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+      for (const file of snapshotFileRows) {
+        insertSnapshotFile.run(id, file.projectId, file.id, file.path, file.contentHash);
+      }
       snapshot = {
         ...input,
         id,

package/src/codegraph/types.ts

@@ -116,6 +116,46 @@ export interface CodeStateSnapshot extends CodeStateSnapshotInput {
   previousSnapshotId?: string;
 }
 
+/** Hash-only file state retained for an explicit Code State snapshot. */
+export interface CodeStateSnapshotFile {
+  snapshotId: string;
+  projectId: string;
+  fileId: string;
+  path: string;
+  contentHash: string;
+}
+
+export interface CodeStateFileChange {
+  path: string;
+  kind: 'added' | 'modified' | 'removed';
+  beforeHash?: string;
+  afterHash?: string;
+}
+
+/**
+ * An exact file-level comparison when both snapshots have hash manifests.
+ * It intentionally makes no claim about source-level semantic equivalence.
+ */
+export interface CodeStateDiff {
+  projectId: string;
+  fromSnapshotId: string;
+  toSnapshotId: string;
+  available: boolean;
+  reason?: 'missing-snapshot' | 'project-mismatch' | 'legacy-snapshot-without-manifest' | 'incomplete-snapshot';
+  changes: CodeStateFileChange[];
+}
+
+/** Bounded one-hop structural evidence around changed file paths. */
+export interface CodeGraphImpactSlice {
+  projectId: string;
+  snapshotId?: string;
+  changedPaths: string[];
+  directlyConnectedPaths: string[];
+  relationCount: number;
+  truncated: boolean;
+  provider: CodeGraphProviderKind;
+}
+
 export interface CodeGraphStatus {
   provider: CodeGraphProviderKind;
   files: number;
@@ -164,6 +204,8 @@ export interface CodeGraphProviderQuality {
     capabilities: {
       declarations: boolean;
       importHints: boolean;
+      /** Deterministic local-path mapping only; not semantic name resolution. */
+      localRelativeImportTargets: boolean;
       resolvedRelations: false;
       exactLocations: false;
     };