memorix 1.4.1 → 1.4.2

package/docs/1.4.2-EVIDENCE-GOVERNED-MEMORY-SPEC.md

@@ -0,0 +1,434 @@
+# Memorix 1.4.2: Evidence-Governed Memory and CodeGraph
+
+Status: implementation complete; release verification recorded in v1.4.2
+Branch: `codex/1.4.2-evidence-governor`
+Baseline: `v1.4.1`
+Updated: 2026-08-06
+
+## One-Sentence Product Contract
+
+Memorix should give an agent the smallest useful set of **current, source-backed
+project knowledge**, and should say "do not use memory here" when it cannot
+justify a useful answer.
+
+This is not a new prompt wrapper or a second knowledge store. It is the policy
+layer that unifies existing observations, claims, workflows, CodeGraph evidence,
+Git state, and verification results before they reach an agent.
+
+## Why This Release Exists
+
+The product already has much of the necessary foundation:
+
+- source-backed claims and code-reference freshness;
+- versioned CodeGraph snapshots and bounded Worksets;
+- retention, archive, workflow, and background-maintenance primitives;
+- project context through MCP and CLI.
+
+Those pieces currently answer related questions in different modules. A memory
+can be relevant but old, source-backed but never verified, or compact but still
+harmful for the current task. 1.4.2 makes the final decision explicit,
+consistent, inspectable, and shared by CLI, MCP, hooks, and dashboard surfaces.
+
+## Research Constraints
+
+This release follows published findings without overstating what they prove.
+
+1. Similar retrieved experiences can cause agents to imitate prior outputs,
+   including wrong or misaligned ones. Memory quality and deletion policy are
+   product safety concerns, not cleanup cosmetics.
+2. Long-horizon memory needs indexing, retrieval, reading, temporal updates,
+   and abstention. Retrieval quality alone is not enough.
+3. Dynamic note links and hierarchical storage are useful only when the source,
+   freshness, and revision path remain visible.
+4. Persistent memory is a privacy boundary. Retrieval must preserve scope,
+   visibility, and provenance instead of treating all stored text as promptable.
+
+The primary research references are listed at the end of this document. Recent
+2026 preprints may guide investigation but do not become product truth without
+reproducible local tests.
+
+## Terms
+
+| Term | Meaning |
+| --- | --- |
+| Candidate | Any possible context item: observation, claim, workflow, code fact, Git fact, test result, or wiki page. |
+| Evidence | A source that can be checked later: file/symbol hash, CodeGraph snapshot, commit, test/run result, document, or explicit user action. |
+| Qualification | The deterministic check that decides whether a candidate is current enough, visible to this caller, and safe enough to use. |
+| Context plan | The bounded answer to: inject nothing, inject a compact card, inject selected evidence, or schedule more work. |
+| Outcome signal | A later, auditable fact such as a focused test passing, a claim being corrected, or a memory helping a verified task. |
+| Observation period | The period after capture before a memory is promoted to trusted reusable knowledge. |
+
+## Non-Negotiable Invariants
+
+1. **No automatic context dump.** Existing memory is not a reason to inject it.
+2. **No silent truth rewrite.** A model may propose a link, summary, or
+   promotion; it cannot overwrite evidence-backed claims without an auditable
+   transition.
+3. **No model-only authority.** Test, Git, code, and explicit user signals outrank
+   a generated confidence score.
+4. **No new default MCP tool explosion.** `memorix_project_context` remains the
+   primary agent surface. Advanced diagnostics stay grouped and opt-in.
+5. **CLI and MCP parity.** Both construct the same context plan from the same
+   policy. Hooks only trigger the plan; they do not own a separate policy.
+6. **Foreground stays fast.** Context assembly may schedule refresh or analysis,
+   but never waits for a corpus scan, remote provider, or LLM synthesis.
+7. **Code facts are versioned.** A narrative cannot claim that code is current
+   without a matching snapshot or an explicit caution.
+8. **Scope is enforced before relevance.** Personal, project, team, and public
+   knowledge do not mix merely because embeddings are similar.
+
+## Target Architecture
+
+```text
+observations / claims / workflows / wiki / Git / tests / CodeGraph
+                              |
+                              v
+                    candidate collection
+                              |
+                              v
+                  evidence qualification gate
+          scope -> provenance -> freshness -> conflict -> quality
+                              |
+                              v
+                   budgeted context planner
+             abstain | compact card | selected detail
+                              |
+                              v
+               MCP / CLI / hook / dashboard explain view
+                              |
+                              v
+          verified outcomes feed lifecycle and CodeGraph links
+```
+
+The governor is deliberately a pure, deterministic core. Storage adapters and
+renderers call it; it does not import an MCP server, hook implementation, or UI.
+
+## Data Contracts
+
+### 1. Context Candidate
+
+```text
+ContextCandidate
+  id, kind, projectId, scope, visibility
+  title, compactText, sourceRefs
+  capturedAt, observedAt
+  freshness                 current | suspect | stale | unknown
+  conflict                  none | possible | confirmed
+  quality                   probation | verified | degraded | blocked
+  relevanceSignals          lexical, semantic, task-lens, code-link
+  estimatedTokens
+```
+
+Existing records are adapted into candidates. This is not a duplicated store.
+
+### 2. Qualification Result
+
+```text
+QualificationResult
+  candidateId
+  disposition              include | compact | defer | exclude
+  reasons[]                stable machine-readable reason codes
+  evidenceSummary[]        source type, id, snapshot/revision, locator
+  qualitySignals[]         verified test, successful reuse, user pin, correction
+  freshness
+  tokenCost
+```
+
+An excluded item is visible in diagnostics only. It is never silently presented
+as if it had not existed.
+
+### 3. Context Plan
+
+```text
+ContextPlan
+  task, taskLens, projectState
+  mode                     abstain | card | workset
+  selected[]               QualificationResult
+  deferred[]               bounded follow-up suggestions
+  cautions[]
+  budget                   requested, used, remaining
+  scheduledMaintenance[]
+  explanationId
+```
+
+`abstain` is a successful result. It means Memorix did not find sufficiently
+qualified context and recommends normal repository inspection instead.
+
+### 4. Outcome Signal
+
+```text
+MemoryOutcomeSignal
+  id, candidateId, projectId, kind
+  kind                     test-pass | test-fail | verified-reuse |
+                           user-pin | user-correction | source-changed |
+                           conflict-confirmed | manual-review
+  sourceRef, snapshotId, observedAt
+  detail                   sanitized, bounded explanation
+```
+
+Outcome signals are append-only audit facts. They update a derived quality
+state; they do not erase the original memory. A generic manual review is
+auditable but does not by itself raise quality: verification or an explicit
+user pin is still required.
+
+## Lifecycle Policy
+
+1. **Capture:** new observations remain usable as local session material but are
+   labelled `probation` for durable retrieval.
+2. **Qualify:** source and scope are checked. Code-bound items are matched to a
+   snapshot; unbound assertions remain lower confidence.
+3. **Promote:** explicit user pin, review approval, successful verified reuse,
+   or source-backed test/Git evidence can promote a candidate.
+4. **Degrade:** changed/deleted source, failing verification, contradiction, or
+   a user correction downgrades the derived quality state.
+5. **Archive:** retention rules continue to govern cleanup, but archive decisions
+   consume this shared state instead of copying their own freshness formula.
+6. **Recover:** an archived fact can be revisited with its original evidence;
+   archive never means invisible deletion by default.
+
+No score alone can cause destructive deletion. A score can only suggest a
+review or make a candidate ineligible for automatic injection.
+
+## CodeGraph Upgrade
+
+### Product Goal
+
+CodeGraph becomes the code evidence service for the governor. It should answer
+four practical questions quickly:
+
+1. What files and symbols are relevant to this task now?
+2. What changed since this memory or workflow was formed?
+3. What may be affected if this symbol or file changes?
+4. How complete and trustworthy is that structural answer?
+
+### New Capabilities
+
+#### A. Snapshot Diff
+
+The first 1.4.2 slice adds a hash-only **file** manifest to each completed
+snapshot. It can report added, modified, and removed indexed files between two
+complete snapshots. It stores paths and hashes, never a second copy of source.
+
+Symbol and relation history are not yet retained per snapshot, so this release
+does **not** pretend to provide historical symbol/edge diffs. Current graph
+relations are used only for the bounded impact slice below.
+
+Target shape for later schema evolution:
+
+```text
+CodeStateDiff
+  fromSnapshotId, toSnapshotId
+  added/changed/removed files
+  added/changed/removed symbols
+  added/changed/removed relations
+  completeness delta
+  affected observation/claim/workflow references
+```
+
+This must report unknowns from incomplete scans. It is not allowed to label an
+unscanned path as unchanged.
+
+#### B. Impact Slice
+
+Given a file or symbol, return a bounded, explainable graph slice:
+
+```text
+ImpactSlice
+  root references
+  inbound and outbound relations
+  direct test/config/workflow references when available
+  confidence, coverage, traversal limit, and reasons
+```
+
+The first release supports direct edges and a small bounded traversal only. It
+does not claim whole-program call-graph precision.
+
+#### Implemented Slice
+
+- `memorix codegraph diff` compares the newest two snapshots by default, or
+  accepts explicit `--from` and `--to` snapshot ids.
+- `memorix codegraph impact --path <relative-source-path>` exposes the same
+  bounded current one-hop graph slice to CLI-only agents. It rejects paths that
+  are not in the current index instead of reporting a misleading empty result.
+- A diff is refused when either snapshot is incomplete or predates the manifest
+  schema. The result explains why instead of treating absent data as unchanged.
+- The impact view resolves both file edges and symbol edges to current files,
+  follows only one hop, and caps relation traversal. It is an inspection aid,
+  not a guarantee of complete impact coverage.
+- Lite deterministically resolves local relative import paths, including the
+  Node ESM `.js`-from-`.ts` convention. It still does not claim semantic symbol
+  resolution or whole-program call-graph precision.
+- A continuation Workset reports how many stale memory bindings point directly
+  at the changed snapshot files. It does not attribute unrelated old stale
+  memory to the current change.
+- The Workset governor now filters optional claims, workflows, durable memory,
+  and code-bound memory before prompt rendering. Its receipt records the safe
+  disposition and reason without exposing hidden content. In this first slice,
+  task facts, Git state, current code state, and safety cautions remain outside
+  the optional-evidence gate so an abstention never hides current source facts.
+
+#### C. Test and Verification Links
+
+Workflow runs now record an append-only pass/fail signal for their selected
+claims and durable memories. The newest signal is applied only as a delivery
+qualification: a failed verification degrades optional context instead of
+silently rewriting or deleting the original record. A later code change can
+then downgrade the confidence of a memory that says "this is verified" rather
+than leaving an old green test as permanent proof. File/symbol references on
+individual test outcomes remain a later extension.
+
+#### D. Provider Coverage Contract
+
+Every provider returns:
+
+```text
+ProviderCoverage
+  provider, parserMode, supportedLanguages
+  indexedFiles, skippedFiles, skippedReasons
+  relationTypes, confidencePolicy
+  snapshotCompleteness
+```
+
+CodeGraph Lite remains a mandatory local fallback. Parser-backed or external
+providers are optional accelerators and may only add normalized facts through
+this contract. They cannot bypass project scope, source epoch, or secret rules.
+
+#### E. Claim-to-Code Requalification
+
+Existing claim and observation code references should consume snapshot diffs:
+
+- removed source -> `blocked` or `needs-review`;
+- changed bound source -> `degraded` until rechecked;
+- current source plus fresh verification -> `verified`;
+- incomplete provider coverage -> `unknown`, never falsely `current`.
+
+## Retrieval Policy
+
+The governor collects candidates first, then applies this order:
+
+1. project identity, scope, visibility, and secret policy;
+2. hard exclusions: deleted evidence, forbidden scope, confirmed contradiction;
+3. source freshness and provider completeness;
+4. task lens and direct code/Git/test links;
+5. quality signals and explicit user review;
+6. relevance ranking and diversity;
+7. strict section and total token budgets.
+
+Default delivery is progressive:
+
+- **abstain:** no qualified advantage; return normal start files only;
+- **card:** one compact "where we were / what changed / what to verify" card;
+- **workset:** selected details with source references and cautions;
+- **defer:** schedule a refresh or requalification without blocking the agent.
+
+## Public Experience
+
+Normal users still say a natural-language task, for example:
+
+> Continue the auth migration. What remains and what must be checked first?
+
+They receive a short, useful answer. They do not see score arithmetic.
+
+An explicit diagnostic path can answer:
+
+```text
+Why did Memorix include or skip this memory?
+Which code snapshot supports it?
+What changed since it was verified?
+How much context budget did it consume?
+```
+
+This diagnostic output is grouped under existing context/knowledge diagnostics;
+it is not a new default tool for every graph operation.
+
+## Delivery Phases
+
+### Phase 0: Baseline and Compatibility
+
+- Inventory all existing context ranking, retention, claim, freshness, and
+  CodeGraph paths.
+- Add a behavior matrix covering current output and no-regression fixtures.
+- Establish deterministic context-plan fixtures: abstain, compact card, stale
+  code caution, conflict exclusion, and incomplete graph coverage.
+
+### Phase 1: Governor Core
+
+- Implement candidate adapters and pure qualification/context-plan modules.
+- Route `project_context`, `context_pack`, and CLI context/resume through the
+  same plan builder without changing their stable output contracts.
+- Add explicit abstention and reason codes.
+
+### Phase 2: Outcome and Lifecycle Unification
+
+- Add append-only outcome signals and derived candidate quality.
+- Route retention report, HTTP/dashboard status, archive eligibility, and
+  claim requalification through one lifecycle evaluation path.
+- Treat test/Git/source changes as higher-quality signals than model estimates.
+
+### Phase 3: CodeGraph Evidence Upgrade
+
+- Add snapshot diffs, bounded impact slices, coverage reporting, and test/run
+  reference links.
+- Requalify claim/observation references from diffs.
+- Add fixture coverage for changed symbol, removed file, incomplete scan, and
+  uncertain relation handling.
+
+### Phase 4: Explainability and Operator UX
+
+- Add context-plan explanations to CLI JSON and grouped diagnostics.
+- Add dashboard views for quality state, source freshness, impact slice, and
+  exclusion reason without leaking hidden/private evidence.
+- Keep the normal agent path quiet.
+
+### Phase 5: Verification and Release Gate
+
+- Run unit, SQLite reopen, provider fallback, CLI, MCP, hook, and packaged
+  installation checks.
+- Run isolated agent smoke tests with qualified context, stale context, and
+  abstention scenarios.
+- Measure first-turn latency, token usage, stale-context catches, and false
+  inclusion/exclusion rates against Phase 0 fixtures.
+
+## Acceptance Criteria
+
+1. Every automatic inclusion has a machine-readable reason and at least one
+   visible source or explicit `unknown` caution.
+2. A changed or deleted code source changes the retrieval disposition without a
+   human rediscovering the mismatch.
+3. A task with no qualified memory returns less context, not a generic summary.
+4. CLI, MCP, and hooks select the same qualified evidence for the same task and
+   project state.
+5. An incomplete CodeGraph provider result can never be formatted as complete
+   code truth.
+6. Test failure, user correction, and source change can lower reusable-memory
+   quality; no score-only path deletes a memory.
+7. Existing stored observations, claims, workflows, context commands, and lite
+   MCP profile remain backward compatible.
+8. Default MCP tool count does not increase.
+
+## Explicit Non-Goals
+
+- A remote graph database requirement.
+- Silent LLM rewriting of a project's wiki or workflow.
+- Claiming exact whole-program impact analysis from CodeGraph Lite.
+- Replacing a real language server, CodeGraph product, Git, or test runner.
+- Auto-capturing all conversations, screenshots, or tool outputs.
+- Treating a visual graph as proof of a maintained semantic knowledge graph.
+
+## Research References
+
+- Xiong et al., "How Memory Management Impacts LLM Agents: An Empirical Study
+  of Experience-Following Behavior," ACL 2026.
+  https://aclanthology.org/2026.acl-long.27/
+- Wu et al., "LongMemEval: Benchmarking Chat Assistants on Long-Term
+  Interactive Memory," ICLR 2025.
+  https://iclr.cc/virtual/2025/poster/28290
+- Xu et al., "A-MEM: Agentic Memory for LLM Agents," NeurIPS 2025.
+  https://neurips.cc/virtual/2025/poster/119020
+- Kang et al., "Memory OS of AI Agent," EMNLP 2025.
+  https://aclanthology.org/2025.emnlp-main.1318
+- Tan et al., "MemBench: Towards More Comprehensive Evaluation on the Memory
+  of LLM-based Agents," Findings of ACL 2025.
+  https://aclanthology.org/2025.findings-acl.989.pdf
+- Wang et al., "Unveiling Privacy Risks in LLM Agent Memory," ACL 2025.
+  https://aclanthology.org/2025.acl-long.1227.pdf

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "memorix",
   "mcpName": "io.github.AVIDS2/memorix",
-  "version": "1.4.1",
+  "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,

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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "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.1",
+  "version": "1.4.2",
   "websiteUrl": "https://github.com/AVIDS2/memorix#readme",
   "icons": [
     {
@@ -22,7 +22,7 @@
     {
       "registryType": "npm",
       "identifier": "memorix",
-      "version": "1.4.1",
+      "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 => ({