memorix 1.1.13 → 1.2.0

package/src/codegraph/lite-provider.ts

@@ -1,7 +1,8 @@
 import { createHash } from 'node:crypto';
 import { readdirSync, readFileSync, statSync, type Dirent } from 'node:fs';
 import { join, relative } from 'node:path';
-import type { CodeEdge, CodeFile, CodeSymbol } from './types.js';
+import type { CodeEdge, CodeFile, CodeStateSnapshot, CodeSymbol } from './types.js';
+import { collectCodeStateSnapshot } from './code-state.js';
 import { makeCodeEdgeId, makeCodeFileId, makeCodeSymbolId, normalizeCodePath } from './ids.js';
 import { isCodeGraphExcludedPath, normalizeCodeGraphExcludePatterns } from './exclude.js';
 import { CodeGraphStore, type CodeGraphFileDelta } from './store.js';
@@ -19,6 +20,7 @@ export interface LiteIndexResult {
   symbols: CodeSymbol[];
   edges: CodeEdge[];
   skippedOversizedFiles: number;
+  unreadableFiles: number;
 }
 
 export interface LiteRefreshResult {
@@ -30,7 +32,9 @@ export interface LiteRefreshResult {
   indexedSymbols: number;
   indexedEdges: number;
   skippedOversizedFiles: number;
+  unreadableFiles: number;
   removalScanDeferred: boolean;
+  snapshot: CodeStateSnapshot;
 }
 
 export const DEFAULT_CODEGRAPH_MAX_FILE_BYTES = 2 * 1024 * 1024;
@@ -299,13 +303,18 @@ function extractImportEdges(projectId: string, file: CodeFile, text: string, ind
   return edges;
 }
 
+interface LiteFileIndexAttempt {
+  delta?: CodeGraphFileDelta;
+  unreadable: boolean;
+}
+
 function indexFileLite(
   projectId: string,
   projectRoot: string,
   abs: string,
   indexedAt: string,
   fileStat?: ReturnType<typeof statSync>,
-): CodeGraphFileDelta | undefined {
+): LiteFileIndexAttempt {
   const rel = normalizeCodePath(relative(projectRoot, abs));
   try {
     const text = readFileSync(abs, 'utf-8');
@@ -316,17 +325,22 @@ function indexFileLite(
       path: rel,
       language: languageForPath(rel),
       contentHash: hashText(text),
-      mtimeMs: Math.round(Number(stat.mtimeMs)),
+      // Preserve filesystem precision. Rounding here made same-size edits in
+      // a short Windows timestamp window indistinguishable to refresh.
+      mtimeMs: Number(stat.mtimeMs),
       sizeBytes: Number(stat.size),
       indexedAt,
     };
     return {
-      file,
-      symbols: extractSymbols(projectId, file, text, indexedAt),
-      edges: extractImportEdges(projectId, file, text, indexedAt),
+      delta: {
+        file,
+        symbols: extractSymbols(projectId, file, text, indexedAt),
+        edges: extractImportEdges(projectId, file, text, indexedAt),
+      },
+      unreadable: false,
     };
   } catch {
-    return undefined;
+    return { unreadable: true };
   }
 }
 
@@ -340,26 +354,31 @@ export async function indexProjectLite(options: LiteIndexOptions): Promise<LiteI
   const symbols: CodeSymbol[] = [];
   const edges: CodeEdge[] = [];
   let skippedOversizedFiles = 0;
+  let unreadableFiles = 0;
 
   for (const abs of paths) {
     let stat: ReturnType<typeof statSync>;
     try {
       stat = statSync(abs);
     } catch {
+      unreadableFiles++;
       continue;
     }
     if (Number(stat.size) > maxFileBytes) {
       skippedOversizedFiles++;
       continue;
     }
-    const delta = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
-    if (!delta) continue;
-    files.push(delta.file);
-    symbols.push(...delta.symbols);
-    edges.push(...delta.edges);
+    const attempt = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
+    if (!attempt.delta) {
+      if (attempt.unreadable) unreadableFiles++;
+      continue;
+    }
+    files.push(attempt.delta.file);
+    symbols.push(...attempt.delta.symbols);
+    edges.push(...attempt.delta.edges);
   }
 
-  return { files, symbols, edges, skippedOversizedFiles };
+  return { files, symbols, edges, skippedOversizedFiles, unreadableFiles };
 }
 
 /**
@@ -382,31 +401,38 @@ export async function refreshProjectLite(
   const oversizedExistingFileIds = new Set<string>();
   let unchangedFiles = 0;
   let skippedOversizedFiles = 0;
+  let unreadableFiles = 0;
 
   for (const abs of paths) {
     const rel = normalizeCodePath(relative(options.projectRoot, abs));
+    // A discovered but temporarily unreadable path is not deletion evidence.
+    seenPaths.add(rel);
     let stat: ReturnType<typeof statSync>;
     try {
       stat = statSync(abs);
     } catch {
+      unreadableFiles++;
       continue;
     }
-    seenPaths.add(rel);
     const existing = existingByPath.get(rel);
-    const roundedMtime = Math.round(Number(stat.mtimeMs));
+    const mtimeMs = Number(stat.mtimeMs);
     const sizeBytes = Number(stat.size);
     if (sizeBytes > maxFileBytes) {
       skippedOversizedFiles++;
       if (existing) oversizedExistingFileIds.add(existing.id);
       continue;
     }
-    if (existing && existing.mtimeMs === roundedMtime && existing.sizeBytes === sizeBytes) {
+    if (existing && existing.mtimeMs === mtimeMs && existing.sizeBytes === sizeBytes) {
       unchangedFiles++;
       continue;
     }
 
-    const delta = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
-    if (!delta) continue;
+    const attempt = indexFileLite(options.projectId, options.projectRoot, abs, indexedAt, stat);
+    if (!attempt.delta) {
+      if (attempt.unreadable) unreadableFiles++;
+      continue;
+    }
+    const delta = attempt.delta;
     if (existing?.contentHash === delta.file.contentHash) {
       metadataOnly.push(delta.file);
       unchangedFiles++;
@@ -430,7 +456,24 @@ export async function refreshProjectLite(
     metadataOnly,
     removedFileIds,
   });
-
+  const completeness = {
+    scannedFiles: paths.length,
+    maxFiles,
+    changedFiles: changed.length,
+    unchangedFiles,
+    metadataOnlyFiles: metadataOnly.length,
+    removedFiles: removedFileIds.length,
+    skippedOversizedFiles,
+    unreadableFiles,
+    removalScanDeferred,
+  };
+  const snapshot = store.recordCodeStateSnapshot(await collectCodeStateSnapshot({
+    projectId: options.projectId,
+    projectRoot: options.projectRoot,
+    provider: 'lite',
+    indexedAt,
+    completeness,
+  }));
   return {
     scannedFiles: paths.length,
     changedFiles: changed.length,
@@ -440,6 +483,8 @@ export async function refreshProjectLite(
     indexedSymbols: changed.reduce((total, delta) => total + delta.symbols.length, 0),
     indexedEdges: changed.reduce((total, delta) => total + delta.edges.length, 0),
     skippedOversizedFiles,
+    unreadableFiles,
     removalScanDeferred,
+    snapshot,
   };
 }

package/src/codegraph/project-context.ts

@@ -1,6 +1,12 @@
 import type { ProjectInfo } from '../types.js';
 import { evaluateCodeRefFreshness } from './freshness.js';
-import type { CodeFile, CodeRefStatus, CodeSymbol, ObservationCodeRef } from './types.js';
+import type {
+  CodeFile,
+  CodeRefStatus,
+  CodeStateSnapshot,
+  CodeSymbol,
+  ObservationCodeRef,
+} from './types.js';
 import type { CodeGraphStore } from './store.js';
 import { isCodeGraphExcludedPath } from './exclude.js';
 
@@ -31,6 +37,7 @@ export interface ProjectContextOverview {
     refs: number;
     indexedAt?: string;
     languages: LanguageSummary[];
+    latestSnapshot?: CodeStateSnapshot;
   };
   memory: {
     total: number;
@@ -196,6 +203,7 @@ function overviewFromGraph(input: {
       refs: status.refs,
       ...(status.indexedAt ? { indexedAt: status.indexedAt } : {}),
       languages: countLanguages(input.graph.files),
+      ...(status.latestSnapshot ? { latestSnapshot: status.latestSnapshot } : {}),
     },
     memory: {
       total: input.observations.filter(obs => obs.projectId === input.project.id).length,

package/src/codegraph/store.ts

@@ -1,5 +1,15 @@
+import { randomUUID } from 'node:crypto';
 import { getDatabase } from '../store/sqlite-db.js';
-import type { CodeEdge, CodeFile, CodeGraphStatus, CodeSymbol, ObservationCodeRef } from './types.js';
+import type {
+  CodeEdge,
+  CodeFile,
+  CodeGraphStatus,
+  CodeStateScanCompleteness,
+  CodeStateSnapshot,
+  CodeStateSnapshotInput,
+  CodeSymbol,
+  ObservationCodeRef,
+} from './types.js';
 import { normalizeCodePath } from './ids.js';
 
 export interface CodeGraphFileDelta {
@@ -19,6 +29,8 @@ function rowToFile(row: any): CodeFile {
     ...(row.sizeBytes != null ? { sizeBytes: row.sizeBytes } : {}),
     indexedAt: row.indexedAt,
     ...(row.gitCommit ? { gitCommit: row.gitCommit } : {}),
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
+    ...(row.sourceEpoch != null ? { sourceEpoch: Number(row.sourceEpoch) } : {}),
   };
 }
 
@@ -37,6 +49,8 @@ function rowToSymbol(row: any): CodeSymbol {
     ...(row.contentHash ? { contentHash: row.contentHash } : {}),
     indexedAt: row.indexedAt,
     stale: !!row.stale,
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
+    ...(row.sourceEpoch != null ? { sourceEpoch: Number(row.sourceEpoch) } : {}),
   } as CodeSymbol;
 }
 
@@ -52,6 +66,8 @@ function rowToEdge(row: any): CodeEdge {
     confidence: row.confidence,
     ...(row.evidence ? { evidence: row.evidence } : {}),
     indexedAt: row.indexedAt,
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
+    ...(row.sourceEpoch != null ? { sourceEpoch: Number(row.sourceEpoch) } : {}),
   } as CodeEdge;
 }
 
@@ -68,16 +84,71 @@ function rowToRef(row: any): ObservationCodeRef {
     ...(row.reason ? { reason: row.reason } : {}),
     createdAt: row.createdAt,
     ...(row.updatedAt ? { updatedAt: row.updatedAt } : {}),
+    ...(row.snapshotId ? { snapshotId: row.snapshotId } : {}),
   } as ObservationCodeRef;
 }
 
+function parseCompleteness(raw: unknown): CodeStateScanCompleteness {
+  try {
+    const parsed = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid completeness');
+    return {
+      scannedFiles: Number((parsed as any).scannedFiles) || 0,
+      maxFiles: Number((parsed as any).maxFiles) || 0,
+      changedFiles: Number((parsed as any).changedFiles) || 0,
+      unchangedFiles: Number((parsed as any).unchangedFiles) || 0,
+      metadataOnlyFiles: Number((parsed as any).metadataOnlyFiles) || 0,
+      removedFiles: Number((parsed as any).removedFiles) || 0,
+      skippedOversizedFiles: Number((parsed as any).skippedOversizedFiles) || 0,
+      unreadableFiles: Number((parsed as any).unreadableFiles) || 0,
+      removalScanDeferred: Boolean((parsed as any).removalScanDeferred),
+    };
+  } catch {
+    return {
+      scannedFiles: 0,
+      maxFiles: 0,
+      changedFiles: 0,
+      unchangedFiles: 0,
+      metadataOnlyFiles: 0,
+      removedFiles: 0,
+      skippedOversizedFiles: 0,
+      unreadableFiles: 0,
+      removalScanDeferred: false,
+    };
+  }
+}
+
+function rowToSnapshot(row: any): CodeStateSnapshot {
+  return {
+    id: row.id,
+    projectId: row.projectId,
+    provider: row.provider,
+    ...(row.baseRevision ? { baseRevision: row.baseRevision } : {}),
+    worktreeFingerprint: row.worktreeFingerprint,
+    worktreeState: row.worktreeState,
+    changedPathCount: Number(row.changedPathCount),
+    indexedAt: row.indexedAt,
+    sourceEpoch: Number(row.sourceEpoch),
+    completeness: parseCompleteness(row.completenessJson),
+    ...(row.previousSnapshotId ? { previousSnapshotId: row.previousSnapshotId } : {}),
+  } as CodeStateSnapshot;
+}
+
 export class CodeGraphStore {
   private db: any = null;
+  private dataDir: string | null = null;
 
   async init(dataDir: string): Promise<void> {
+    this.dataDir = dataDir;
     this.db = getDatabase(dataDir);
   }
 
+  /** Data directory shared with the rest of the local project evidence stores. */
+  getDataDir(): string {
+    if (!this.dataDir) throw new Error('CodeGraphStore is not initialized');
+    return this.dataDir;
+  }
+
   upsertFiles(files: CodeFile[]): void {
     if (files.length === 0) return;
     const stmt = this.db.prepare(`
@@ -364,9 +435,9 @@ export class CodeGraphStore {
     if (refs.length === 0) return;
     const stmt = this.db.prepare(`
       INSERT OR REPLACE INTO observation_code_refs
-        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt)
+        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt, snapshotId)
       VALUES
-        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt)
+        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt, @snapshotId)
     `);
     const tx = this.db.transaction((items: ObservationCodeRef[]) => {
       for (const ref of items) {
@@ -382,6 +453,7 @@ export class CodeGraphStore {
           reason: ref.reason ?? null,
           createdAt: ref.createdAt,
           updatedAt: ref.updatedAt ?? null,
+          snapshotId: ref.snapshotId ?? this.latestSnapshot(ref.projectId)?.id ?? null,
         });
       }
     });
@@ -395,9 +467,9 @@ export class CodeGraphStore {
     `);
     const insertRef = this.db.prepare(`
       INSERT OR REPLACE INTO observation_code_refs
-        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt)
+        (id, projectId, observationId, fileId, symbolId, capturedFileHash, capturedSymbolHash, status, reason, createdAt, updatedAt, snapshotId)
       VALUES
-        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt)
+        (@id, @projectId, @observationId, @fileId, @symbolId, @capturedFileHash, @capturedSymbolHash, @status, @reason, @createdAt, @updatedAt, @snapshotId)
     `);
     const tx = this.db.transaction(() => {
       deleteRefs.run(projectId, observationId);
@@ -414,6 +486,7 @@ export class CodeGraphStore {
           reason: ref.reason ?? null,
           createdAt: ref.createdAt,
           updatedAt: ref.updatedAt ?? null,
+          snapshotId: ref.snapshotId ?? this.latestSnapshot(ref.projectId)?.id ?? null,
         });
       }
     });
@@ -514,12 +587,87 @@ export class CodeGraphStore {
     `).all(projectId, projectId).map(rowToSymbol);
   }
 
+  latestSnapshot(projectId: string): CodeStateSnapshot | undefined {
+    const row = this.db.prepare(
+      'SELECT * FROM code_state_snapshots WHERE projectId = ? ORDER BY sourceEpoch DESC LIMIT 1',
+    ).get(projectId);
+    return row ? rowToSnapshot(row) : undefined;
+  }
+
+  listSnapshots(projectId: string, limit = 20): CodeStateSnapshot[] {
+    const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(200, Math.floor(limit))) : 20;
+    return this.db.prepare(
+      'SELECT * FROM code_state_snapshots WHERE projectId = ? ORDER BY sourceEpoch DESC LIMIT ?',
+    ).all(projectId, safeLimit).map(rowToSnapshot);
+  }
+
+  /**
+   * Record a completed scan and mark all current structural facts with its
+   * epoch. The snapshot is written only after refresh reconciliation succeeds,
+   * so an interrupted scan cannot be advertised as complete.
+   */
+  recordCodeStateSnapshot(input: CodeStateSnapshotInput): CodeStateSnapshot {
+    const id = randomUUID();
+    let snapshot: CodeStateSnapshot | undefined;
+    const tx = this.db.transaction(() => {
+      const previous = this.db.prepare(
+        'SELECT id, sourceEpoch FROM code_state_snapshots WHERE projectId = ? ORDER BY sourceEpoch DESC LIMIT 1',
+      ).get(input.projectId);
+      const sourceEpoch = Number(previous?.sourceEpoch ?? 0) + 1;
+      const previousSnapshotId = previous?.id as string | undefined;
+      this.db.prepare(
+        'INSERT INTO code_state_snapshots (id, projectId, provider, baseRevision, worktreeFingerprint, worktreeState, changedPathCount, indexedAt, sourceEpoch, completenessJson, previousSnapshotId) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+      ).run(
+        id,
+        input.projectId,
+        input.provider,
+        input.baseRevision ?? null,
+        input.worktreeFingerprint,
+        input.worktreeState,
+        input.changedPathCount,
+        input.indexedAt,
+        sourceEpoch,
+        JSON.stringify(input.completeness),
+        previousSnapshotId ?? null,
+      );
+      this.db.prepare(
+        'UPDATE code_files SET snapshotId = ?, sourceEpoch = ?, gitCommit = COALESCE(?, gitCommit) WHERE projectId = ?',
+      ).run(id, sourceEpoch, input.baseRevision ?? null, input.projectId);
+      this.db.prepare(
+        'UPDATE code_symbols SET snapshotId = ?, sourceEpoch = ? WHERE projectId = ? AND stale = 0',
+      ).run(id, sourceEpoch, input.projectId);
+      this.db.prepare(
+        'UPDATE code_edges SET snapshotId = ?, sourceEpoch = ? WHERE projectId = ?',
+      ).run(id, sourceEpoch, input.projectId);
+      this.db.prepare(
+        "UPDATE observation_code_refs SET snapshotId = ? WHERE projectId = ? AND status = 'current'",
+      ).run(id, input.projectId);
+      snapshot = {
+        ...input,
+        id,
+        sourceEpoch,
+        ...(previousSnapshotId ? { previousSnapshotId } : {}),
+      };
+    });
+    tx();
+    return snapshot!;
+  }
+
   status(projectId: string): CodeGraphStatus {
     const files = this.db.prepare(`SELECT COUNT(*) AS count FROM code_files WHERE projectId = ?`).get(projectId).count;
     const symbols = this.db.prepare(`SELECT COUNT(*) AS count FROM code_symbols WHERE projectId = ? AND stale = 0`).get(projectId).count;
     const edges = this.db.prepare(`SELECT COUNT(*) AS count FROM code_edges WHERE projectId = ?`).get(projectId).count;
     const refs = this.db.prepare(`SELECT COUNT(*) AS count FROM observation_code_refs WHERE projectId = ?`).get(projectId).count;
     const latest = this.db.prepare(`SELECT MAX(indexedAt) AS indexedAt FROM code_files WHERE projectId = ?`).get(projectId);
-    return { provider: 'lite', files, symbols, edges, refs, ...(latest?.indexedAt ? { indexedAt: latest.indexedAt } : {}) };
+    const latestSnapshot = this.latestSnapshot(projectId);
+    return {
+      provider: 'lite',
+      files,
+      symbols,
+      edges,
+      refs,
+      ...(latest?.indexedAt ? { indexedAt: latest.indexedAt } : {}),
+      ...(latestSnapshot ? { latestSnapshot } : {}),
+    };
   }
 }

package/src/codegraph/types.ts

@@ -32,6 +32,8 @@ export interface CodeFile {
   sizeBytes?: number;
   indexedAt: string;
   gitCommit?: string;
+  snapshotId?: string;
+  sourceEpoch?: number;
 }
 
 export interface CodeSymbol {
@@ -48,6 +50,8 @@ export interface CodeSymbol {
   contentHash?: string;
   indexedAt: string;
   stale?: boolean;
+  snapshotId?: string;
+  sourceEpoch?: number;
 }
 
 export interface CodeEdge {
@@ -61,6 +65,8 @@ export interface CodeEdge {
   confidence: number;
   evidence?: string;
   indexedAt: string;
+  snapshotId?: string;
+  sourceEpoch?: number;
 }
 
 export interface ObservationCodeRef {
@@ -75,6 +81,39 @@ export interface ObservationCodeRef {
   reason?: string;
   createdAt: string;
   updatedAt?: string;
+  snapshotId?: string;
+}
+
+export type CodeStateWorktreeState = 'clean' | 'dirty' | 'unavailable';
+
+export interface CodeStateScanCompleteness {
+  scannedFiles: number;
+  maxFiles: number;
+  changedFiles: number;
+  unchangedFiles: number;
+  metadataOnlyFiles: number;
+  removedFiles: number;
+  skippedOversizedFiles: number;
+  /** Source paths discovered but unavailable for stat/read during this scan. */
+  unreadableFiles?: number;
+  removalScanDeferred: boolean;
+}
+
+export interface CodeStateSnapshotInput {
+  projectId: string;
+  provider: CodeGraphProviderKind;
+  baseRevision?: string;
+  worktreeFingerprint: string;
+  worktreeState: CodeStateWorktreeState;
+  changedPathCount: number;
+  indexedAt: string;
+  completeness: CodeStateScanCompleteness;
+}
+
+export interface CodeStateSnapshot extends CodeStateSnapshotInput {
+  id: string;
+  sourceEpoch: number;
+  previousSnapshotId?: string;
 }
 
 export interface CodeGraphStatus {
@@ -84,4 +123,82 @@ export interface CodeGraphStatus {
   edges: number;
   refs: number;
   indexedAt?: string;
+  latestSnapshot?: CodeStateSnapshot;
+}
+
+/** Policy for using a separately installed, local semantic CodeGraph index. */
+export type CodeGraphExternalMode = 'auto' | 'off';
+
+/**
+ * The external provider state is deliberately more precise than a boolean.
+ * A caller can distinguish an absent optional tool from a stale or invalid
+ * result without treating either as a fatal failure for Code Memory.
+ */
+export type ExternalCodeGraphState =
+  | 'disabled'
+  | 'not-detected'
+  | 'unavailable'
+  | 'not-initialized'
+  | 'stale'
+  | 'timed-out'
+  | 'invalid'
+  | 'ready';
+
+export interface ExternalCodeGraphHealth {
+  state: ExternalCodeGraphState;
+  reason?: string;
+  indexedFiles?: number;
+  indexedNodes?: number;
+  indexedEdges?: number;
+  languages?: string[];
+}
+
+export interface CodeGraphProviderQuality {
+  /** Provider that contributed task-scoped code evidence to this response. */
+  selected: CodeGraphProviderKind;
+  /** Lite is heuristic; external outlines are only semantic after validation. */
+  selectedQuality: 'heuristic' | 'semantic';
+  mode: CodeGraphExternalMode;
+  lite: {
+    quality: 'heuristic';
+    capabilities: {
+      declarations: boolean;
+      importHints: boolean;
+      resolvedRelations: false;
+      exactLocations: false;
+    };
+    supportedLanguages: string[];
+  };
+  external: ExternalCodeGraphHealth;
+}
+
+export interface ExternalCodeGraphSymbol {
+  id: string;
+  name: string;
+  qualifiedName?: string;
+  kind: string;
+  path: string;
+  startLine?: number;
+  endLine?: number;
+  language?: string;
+}
+
+export interface ExternalCodeGraphRelation {
+  from: ExternalCodeGraphSymbol;
+  to: ExternalCodeGraphSymbol;
+  kind: string;
+  line?: number;
+}
+
+/** A bounded, non-source-code semantic outline returned for one task. */
+export interface ExternalCodeGraphOutline {
+  provider: 'external';
+  entryPoints: ExternalCodeGraphSymbol[];
+  relations: ExternalCodeGraphRelation[];
+  relatedFiles: string[];
+  stats: {
+    nodes: number;
+    edges: number;
+    files: number;
+  };
 }

package/src/config/resolved-config.ts

@@ -55,6 +55,9 @@ export interface ResolvedMemorixConfig {
   codegraph: {
     excludePatterns?: string[];
     maxFileBytes?: number;
+    externalContext: 'auto' | 'off';
+    externalCommand?: string;
+    externalTimeoutMs?: number;
   };
   server: {
     transport?: 'stdio' | 'http';
@@ -156,6 +159,22 @@ export function getResolvedConfig(options: ResolvedLaneOptions = {}): ResolvedMe
     codegraph: {
       excludePatterns: firstArray(toml.codegraph?.exclude_patterns, yaml.codegraph?.excludePatterns),
       maxFileBytes: firstNumber(toml.codegraph?.max_file_bytes, yaml.codegraph?.maxFileBytes),
+      externalContext: first(
+        normalizeExternalContext(process.env.MEMORIX_CODEGRAPH_EXTERNAL_CONTEXT),
+        toml.codegraph?.external_context,
+        yaml.codegraph?.externalContext,
+        'auto',
+      )!,
+      externalCommand: first(
+        process.env.MEMORIX_CODEGRAPH_EXTERNAL_COMMAND,
+        toml.codegraph?.external_command,
+        yaml.codegraph?.externalCommand,
+      ),
+      externalTimeoutMs: firstNumber(
+        parseNumber(process.env.MEMORIX_CODEGRAPH_EXTERNAL_TIMEOUT_MS),
+        toml.codegraph?.external_timeout_ms,
+        yaml.codegraph?.externalTimeoutMs,
+      ),
     },
     server: {
       transport: first(toml.server?.transport, yaml.server?.transport),
@@ -254,6 +273,9 @@ function getEnvSourceNames(): string[] {
     'MEMORIX_EMBEDDING_BASE_URL',
     'MEMORIX_EMBEDDING_MODEL',
     'MEMORIX_EMBEDDING_DIMENSIONS',
+    'MEMORIX_CODEGRAPH_EXTERNAL_CONTEXT',
+    'MEMORIX_CODEGRAPH_EXTERNAL_COMMAND',
+    'MEMORIX_CODEGRAPH_EXTERNAL_TIMEOUT_MS',
     'OPENROUTER_API_KEY',
   ].filter((name) => process.env[name]);
 }
@@ -267,3 +289,9 @@ function isOpenRouterUrl(value: string | undefined): boolean {
     return /(^|\.)openrouter\.ai(?::|\/|$)/i.test(value);
   }
 }
+
+function normalizeExternalContext(value: string | undefined): 'auto' | 'off' | undefined {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === 'auto' || normalized === 'off') return normalized;
+  return undefined;
+}

package/src/config/toml-loader.ts

@@ -43,6 +43,9 @@ export interface MemorixTomlConfig {
   codegraph?: {
     exclude_patterns?: string[];
     max_file_bytes?: number;
+    external_context?: 'auto' | 'off';
+    external_command?: string;
+    external_timeout_ms?: number;
   };
   server?: {
     transport?: 'stdio' | 'http';

package/src/config/yaml-loader.ts

@@ -70,6 +70,12 @@ export interface MemorixYamlConfig {
     excludePatterns?: string[];
     /** Maximum source file size to parse into CodeGraph Memory */
     maxFileBytes?: number;
+    /** Use a healthy pre-existing local CodeGraph index when present (default: auto). */
+    externalContext?: 'auto' | 'off';
+    /** Optional CodeGraph executable path when it is not available on PATH. */
+    externalCommand?: string;
+    /** Bound for one local semantic context request. */
+    externalTimeoutMs?: number;
   };
 
   /** Behavior settings */