memorix 1.1.13 → 1.2.1

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 */

package/src/dashboard/server.ts

@@ -22,6 +22,7 @@ import { loadDotenv } from '../config/dotenv-loader.js';
 import { resetDotenv } from '../config/dotenv-loader.js';
 import { initProjectRoot } from '../config/yaml-loader.js';
 import { clearProjectRoot } from '../config/yaml-loader.js';
+import { scopeKnowledgeGraphToProject } from '../memory/graph-scope.js';
 
 // MIME types for static file serving
 const MIME_TYPES: Record<string, string> = {
@@ -92,22 +93,15 @@ export function prepareDashboardConfig(projectRoot: string | null): void {
 
 /**
  * Compute project-scoped graph counts from observations.
- * Only entities referenced by this project's active observations are counted.
+ * Active observation entities and their explicit cross-references are counted.
  */
 function computeProjectGraphCounts(
     allEntities: Array<{ name: string }>,
     allRelations: Array<{ from: string; to: string }>,
-    projectObs: Array<{ entityName?: string; status?: string }>,
+    projectObs: Array<{ entityName?: string; relatedEntities?: string[]; status?: string }>,
 ): { entities: number; relations: number; entityNames: Set<string> } {
-    const entityNames = new Set(
-        projectObs
-            .filter(o => (o.status ?? 'active') === 'active' && o.entityName)
-            .map(o => o.entityName!),
-    );
-    const entities = allEntities.filter(e => entityNames.has(e.name));
-    const entityNameSet = new Set(entities.map(e => e.name));
-    const relations = allRelations.filter(r => entityNameSet.has(r.from) && entityNameSet.has(r.to));
-    return { entities: entities.length, relations: relations.length, entityNames };
+    const scoped = scopeKnowledgeGraphToProject({ entities: allEntities, relations: allRelations }, projectObs);
+    return { entities: scoped.entities.length, relations: scoped.relations.length, entityNames: scoped.entityNames };
 }
 
 /**
@@ -210,17 +204,9 @@ async function handleApi(
                 await initGraphStore(effectiveDataDir);
                 const gStore = getGraphStore();
                 const graph = { entities: gStore.loadEntities(), relations: gStore.loadRelations() };
-                // Project-scope the graph: only include entities that have observations in this project
-                const graphObs = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }) as Array<{ entityName?: string }>;
-                const projectEntityNames = new Set(
-                    graphObs
-                        .filter(o => o.entityName)
-                        .map(o => o.entityName!),
-                );
-                const entities = graph.entities.filter((e: any) => projectEntityNames.has(e.name));
-                const entityNameSet = new Set(entities.map((e: any) => e.name));
-                const relations = graph.relations.filter((r: any) => entityNameSet.has(r.from) && entityNameSet.has(r.to));
-                sendJson(res, { entities, relations });
+                const graphObs = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' });
+                const scoped = scopeKnowledgeGraphToProject(graph, graphObs);
+                sendJson(res, { entities: scoped.entities, relations: scoped.relations });
                 break;
             }
 
@@ -240,11 +226,11 @@ async function handleApi(
             case '/stats': {
                 await initGraphStore(effectiveDataDir);
                 const graph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
-                const observations = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }) as Array<{ type?: string; id?: number; createdAt?: string; title?: string; entityName?: string; status?: string }>;
+                const observations = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }) as Array<{ type?: string; id?: number; createdAt?: string; title?: string; entityName?: string; relatedEntities?: string[]; status?: string }>;
                 const nextId = await getObservationStore().loadIdCounter();
 
                 // Project-scoped graph counts (must match /api/graph and /api/export)
-                const projectGraphCounts = computeProjectGraphCounts(graph.entities, graph.relations, observations as Array<{ entityName?: string; status?: string }>);
+                const projectGraphCounts = computeProjectGraphCounts(graph.entities, graph.relations, observations);
 
                 // Type counts (exclude probe -- operational heartbeats, not durable knowledge)
                 const typeCounts: Record<string, number> = {};
@@ -322,9 +308,15 @@ async function handleApi(
                 };
 
                 let maintenance = { total: 0, pending: 0, running: 0, retrying: 0, completed: 0, failed: 0 };
+                let lifecycle: unknown;
                 try {
                     const { MaintenanceJobStore } = await import('../runtime/maintenance-jobs.js');
                     maintenance = new MaintenanceJobStore(effectiveDataDir).summary(effectiveProjectId);
+                    const { collectLifecycleDiagnostics } = await import('../runtime/lifecycle-status.js');
+                    lifecycle = await collectLifecycleDiagnostics({
+                        dataDir: effectiveDataDir,
+                        projectId: effectiveProjectId,
+                    });
                 } catch { /* optional maintenance diagnostics */ }
 
                 sendJson(res, {
@@ -338,6 +330,7 @@ async function handleApi(
                     embedding: embeddingStatus,
                     storage: storageInfo,
                     maintenance,
+                    ...(lifecycle ? { lifecycle } : {}),
                     gitSummary: {
                         total: gitMemories.length,
                         recentWeek: recentGitCount,
@@ -349,7 +342,10 @@ async function handleApi(
             }
 
             case '/maintenance': {
-                const { MaintenanceJobStore } = await import('../runtime/maintenance-jobs.js');
+                const [{ MaintenanceJobStore }, { collectLifecycleDiagnostics }] = await Promise.all([
+                    import('../runtime/maintenance-jobs.js'),
+                    import('../runtime/lifecycle-status.js'),
+                ]);
                 const jobs = new MaintenanceJobStore(effectiveDataDir).list({
                     projectId: effectiveProjectId,
                     limit: 50,
@@ -357,6 +353,10 @@ async function handleApi(
                 sendJson(res, {
                     summary: new MaintenanceJobStore(effectiveDataDir).summary(effectiveProjectId),
                     jobs,
+                    lifecycle: await collectLifecycleDiagnostics({
+                        dataDir: effectiveDataDir,
+                        projectId: effectiveProjectId,
+                    }),
                 });
                 break;
             }
@@ -447,24 +447,15 @@ async function handleApi(
                 const allObs = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' });
                 const skills = await getMiniSkillStore().loadByProject(effectiveProjectId);
 
-                // Project-scope graph store (same logic as /api/graph)
                 const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
-                const graphObs = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' }) as Array<{ entityName?: string }>;
-                const projectEntityNames = new Set(
-                    graphObs
-                        .filter(o => o.entityName)
-                        .map(o => o.entityName!),
-                );
-                const scopedEntities = fullGraph.entities.filter((e: any) => projectEntityNames.has(e.name));
-                const scopedEntityNameSet = new Set(scopedEntities.map((e: any) => e.name));
-                const scopedRelations = fullGraph.relations.filter((r: any) => scopedEntityNameSet.has(r.from) && scopedEntityNameSet.has(r.to));
+                const scoped = scopeKnowledgeGraphToProject(fullGraph, allObs);
 
                 const graph = generateKnowledgeGraph({
                     projectId: effectiveProjectId,
                     observations: allObs,
                     miniSkills: skills,
-                    graphEntities: scopedEntities,
-                    graphRelations: scopedRelations,
+                    graphEntities: scoped.entities,
+                    graphRelations: scoped.relations,
                 });
 
                 sendJson(res, graph);
@@ -733,19 +724,11 @@ async function handleApi(
                     const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
                     const observations = await getObservationStore().loadByProject(effectiveProjectId, { status: 'active' });
                     const nextId = await getObservationStore().loadIdCounter();
-                    // Project-scope the graph: only entities referenced by this project's observations
-                    const exportEntityNames = new Set(
-                        observations
-                            .filter(o => (o.status ?? 'active') === 'active' && o.entityName)
-                            .map(o => o.entityName!),
-                    );
-                    const exportEntities = fullGraph.entities.filter((e: any) => exportEntityNames.has(e.name));
-                    const exportEntitySet = new Set(exportEntities.map((e: any) => e.name));
-                    const exportRelations = fullGraph.relations.filter((r: any) => exportEntitySet.has(r.from) && exportEntitySet.has(r.to));
+                    const scoped = scopeKnowledgeGraphToProject(fullGraph, observations);
                     const exportData = {
                         project: { id: effectiveProjectId, name: effectiveProjectName },
                         exportedAt: new Date().toISOString(),
-                        graph: { entities: exportEntities, relations: exportRelations },
+                        graph: { entities: scoped.entities, relations: scoped.relations },
                         observations,
                         nextId,
                     };

package/src/evaluation/workset-evaluation.ts

@@ -0,0 +1,120 @@
+import { countTextTokens } from '../compact/token-budget.js';
+
+export const WORKSET_VARIANTS = [
+  'memory-only',
+  'current-context',
+  'candidate-workset',
+] as const;
+
+export type WorksetVariant = typeof WORKSET_VARIANTS[number];
+
+/**
+ * A normalized result shape for evaluating a task context. The production
+ * Workset builder will populate this shape in Phase 5; Phase 0 uses it to
+ * establish deterministic baseline fixtures without an LLM dependency.
+ */
+export interface EvaluatedWorkset {
+  variant: WorksetVariant;
+  prompt: string;
+  startHere: string[];
+  evidenceIds: string[];
+  cautions: string[];
+}
+
+export interface WorksetExpectation {
+  requiredStartHere?: string[];
+  requiredEvidenceIds?: string[];
+  requiredCautions?: string[];
+  maxTokens: number;
+  maxTokensByVariant?: Partial<Record<WorksetVariant, number>>;
+}
+
+export interface WorksetEvaluationFixture {
+  id: string;
+  title: string;
+  task: string;
+  expectation: WorksetExpectation;
+}
+
+export interface WorksetEvaluationResult {
+  fixtureId: string;
+  variant: WorksetVariant;
+  tokenCount: number;
+  tokenBudget: number;
+  withinBudget: boolean;
+  missingStartHere: string[];
+  missingEvidenceIds: string[];
+  missingCautions: string[];
+  passed: boolean;
+}
+
+export interface WorksetComparison {
+  fixtureId: string;
+  results: WorksetEvaluationResult[];
+  byVariant: Partial<Record<WorksetVariant, WorksetEvaluationResult>>;
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function missing(required: string[] | undefined, actual: string[]): string[] {
+  const available = new Set(actual);
+  return unique(required ?? []).filter(value => !available.has(value));
+}
+
+function tokenBudgetFor(
+  expectation: WorksetExpectation,
+  variant: WorksetVariant,
+): number {
+  return expectation.maxTokensByVariant?.[variant] ?? expectation.maxTokens;
+}
+
+/**
+ * Evaluate one context against source-backed fixture requirements. This is
+ * deliberately mechanical: it reports evidence, safety, and token gaps
+ * instead of asking a model to grade another model's answer.
+ */
+export function evaluateWorkset(
+  fixture: WorksetEvaluationFixture,
+  workset: EvaluatedWorkset,
+): WorksetEvaluationResult {
+  const tokenCount = countTextTokens(workset.prompt);
+  const missingStartHere = missing(fixture.expectation.requiredStartHere, workset.startHere);
+  const missingEvidenceIds = missing(fixture.expectation.requiredEvidenceIds, workset.evidenceIds);
+  const missingCautions = missing(fixture.expectation.requiredCautions, workset.cautions);
+  const tokenBudget = tokenBudgetFor(fixture.expectation, workset.variant);
+  const withinBudget = tokenCount <= tokenBudget;
+
+  return {
+    fixtureId: fixture.id,
+    variant: workset.variant,
+    tokenCount,
+    tokenBudget,
+    withinBudget,
+    missingStartHere,
+    missingEvidenceIds,
+    missingCautions,
+    passed: withinBudget
+      && missingStartHere.length === 0
+      && missingEvidenceIds.length === 0
+      && missingCautions.length === 0,
+  };
+}
+
+/**
+ * Compare memory-only, current-context, and candidate Worksets against the
+ * same task requirements. Missing variants are intentionally allowed so a
+ * new retrieval implementation can be introduced incrementally.
+ */
+export function compareWorksets(
+  fixture: WorksetEvaluationFixture,
+  worksets: EvaluatedWorkset[],
+): WorksetComparison {
+  const results = worksets.map(workset => evaluateWorkset(fixture, workset));
+  const byVariant: Partial<Record<WorksetVariant, WorksetEvaluationResult>> = {};
+  for (const result of results) {
+    byVariant[result.variant] = result;
+  }
+  return { fixtureId: fixture.id, results, byVariant };
+}

package/src/hooks/handler.ts

@@ -298,12 +298,12 @@ async function handleSessionStart(input: NormalizedHookInput): Promise<{
         dataDir,
         observations: activeObservations,
         refresh: 'auto',
-        enqueueRefresh: () => import('../runtime/maintenance-jobs.js').then(({ MaintenanceJobStore }) => {
-            new MaintenanceJobStore(dataDir).enqueue({
+        enqueueRefresh: () => import('../runtime/lifecycle.js').then(({ enqueueCodegraphRefresh }) => {
+            enqueueCodegraphRefresh({
+              dataDir,
               projectId: canonicalId,
-              kind: 'codegraph-refresh',
-              dedupeKey: 'hook-codegraph-refresh',
-              payload: { maxFiles: 5_000 },
+              source: 'hook-session-start',
+              maxFiles: 5_000,
             });
           }),
       });
@@ -337,7 +337,7 @@ async function handleSessionStart(input: NormalizedHookInput): Promise<{
  * Pipeline: Classify → Policy check → Store → Respond
  * Pattern detection is used for classification only, not storage gating.
  */
-export async function handleHookEvent(input: NormalizedHookInput): Promise<{
+async function handleHookEventCore(input: NormalizedHookInput): Promise<{
   observation: ReturnType<typeof buildObservation> | null;
   output: HookOutput;
 }> {
@@ -431,6 +431,48 @@ export async function handleHookEvent(input: NormalizedHookInput): Promise<{
   };
 }
 
+/** Queue a later scan after an actual file mutation without scanning in the hook. */
+async function queueCodegraphRefreshForMutation(input: NormalizedHookInput): Promise<void> {
+  if (classifyTool(input) !== 'file_modify') return;
+  try {
+    const [
+      { detectProject },
+      { getProjectDataDir },
+      { initAliasRegistry, registerAlias },
+      { enqueueCodegraphRefresh },
+    ] = await Promise.all([
+      import('../project/detector.js'),
+      import('../store/persistence.js'),
+      import('../project/aliases.js'),
+      import('../runtime/lifecycle.js'),
+    ]);
+    const project = detectProject(input.cwd || process.cwd());
+    if (!project) return;
+    const dataDir = await getProjectDataDir(project.id);
+    initAliasRegistry(dataDir);
+    const projectId = await registerAlias(project);
+    enqueueCodegraphRefresh({
+      dataDir,
+      projectId,
+      source: 'hook-file-mutation',
+      maxFiles: 5_000,
+    });
+  } catch {
+    // Hooks remain capture-first even if optional Code Memory scheduling fails.
+  }
+}
+
+export async function handleHookEvent(input: NormalizedHookInput): Promise<{
+  observation: ReturnType<typeof buildObservation> | null;
+  output: HookOutput;
+}> {
+  try {
+    return await handleHookEventCore(input);
+  } finally {
+    await queueCodegraphRefreshForMutation(input);
+  }
+}
+
 /**
  * Convert Memorix's neutral hook response into the host-specific response
  * schema expected by each supported agent.