memorix 1.1.13 → 1.2.1

package/src/server.ts

@@ -28,6 +28,7 @@ import { initSessionStore } from './store/session-store.js';
 import { checkProjectAttribution, auditProjectObservations } from './memory/attribution-guard.js';
 import { createAutoRelations } from './memory/auto-relations.js';
 import { extractEntities } from './memory/entity-extractor.js';
+import { scopeKnowledgeGraphToProject } from './memory/graph-scope.js';
 import { compactSearch, compactTimeline, compactDetail } from './compact/engine.js';
 import { buildGraphContextPacket, formatGraphContextPrompt } from './memory/graph-context.js';
 import { detectProject } from './project/detector.js';
@@ -469,10 +470,11 @@ export async function createMemorixServer(
   let maintenanceWorker: { stop(): void } | null = null;
   const startProjectMaintenanceWorker = async (autoCleanup = false): Promise<void> => {
     maintenanceWorker?.stop();
-    const [{ MaintenanceJobStore, MaintenanceJobWorker }, maintenance, observations] = await Promise.all([
+    const [{ MaintenanceJobStore, MaintenanceJobWorker }, maintenance, observations, lifecycle] = await Promise.all([
       import('./runtime/maintenance-jobs.js'),
       import('./runtime/project-maintenance.js'),
       import('./memory/observations.js'),
+      import('./runtime/lifecycle.js'),
     ]);
     const queue = new MaintenanceJobStore(projectDir);
     const vectorStatus = observations.getVectorStatus(project.id);
@@ -509,11 +511,12 @@ export async function createMemorixServer(
         || !Number.isFinite(indexedAt)
         || Date.now() - indexedAt > 10 * 60_000;
       if (needsRefresh) {
-        queue.enqueue({
+        lifecycle.enqueueCodegraphRefresh({
+          dataDir: projectDir,
           projectId: project.id,
-          kind: 'codegraph-refresh',
-          dedupeKey: 'startup-codegraph-refresh',
-          payload: { maxFiles: 5_000 },
+          source: 'startup',
+          maxFiles: 5_000,
+          queue,
         });
       }
     } catch {
@@ -1329,10 +1332,12 @@ export async function createMemorixServer(
         },
         { getObservationStore },
         { MaintenanceJobStore },
+        { enqueueCodegraphRefresh },
       ] = await Promise.all([
         import('./codegraph/auto-context.js'),
         import('./store/obs-store.js'),
         import('./runtime/maintenance-jobs.js'),
+        import('./runtime/lifecycle.js'),
       ]);
       const observations = await getObservationStore().loadByProject(project.id, { status: 'active' });
       const context = await buildAutoProjectContext({
@@ -1342,11 +1347,12 @@ export async function createMemorixServer(
         task,
         refresh: refresh ?? 'auto',
         enqueueRefresh: () => {
-          new MaintenanceJobStore(projectDir).enqueue({
+          enqueueCodegraphRefresh({
+            dataDir: projectDir,
             projectId: project.id,
-            kind: 'codegraph-refresh',
-            dedupeKey: 'context-codegraph-refresh',
-            payload: { maxFiles: 5_000 },
+            source: 'project-context',
+            maxFiles: 5_000,
+            queue: new MaintenanceJobStore(projectDir),
           });
         },
       });
@@ -1373,13 +1379,24 @@ export async function createMemorixServer(
       const unresolved = requireResolvedProject('show CodeGraph Memory status for the current project');
       if (unresolved) return unresolved;
 
-      const { CodeGraphStore } = await import('./codegraph/store.js');
+      const [{ CodeGraphStore }, { getResolvedConfig }, { inspectExternalCodeGraph }] = await Promise.all([
+        import('./codegraph/store.js'),
+        import('./config/resolved-config.js'),
+        import('./codegraph/external-provider.js'),
+      ]);
       const store = new CodeGraphStore();
       await store.init(projectDir);
       const status = store.status(project.id);
+      const codegraphConfig = getResolvedConfig({ projectRoot: project.rootPath }).codegraph;
+      const providerQuality = await inspectExternalCodeGraph({
+        projectRoot: project.rootPath,
+        mode: codegraphConfig.externalContext,
+        command: codegraphConfig.externalCommand,
+        timeoutMs: codegraphConfig.externalTimeoutMs,
+      });
 
       return {
-        content: [{ type: 'text' as const, text: JSON.stringify(status, null, 2) }],
+        content: [{ type: 'text' as const, text: JSON.stringify({ ...status, providerQuality: providerQuality.quality }, null, 2) }],
       };
     },
   );
@@ -1405,21 +1422,28 @@ export async function createMemorixServer(
 
       const [
         { CodeGraphStore },
-        { assembleContextPackForTask, buildContextPackPrompt },
+        { assembleContextPackForTask, attachTaskWorkset, buildContextPackPrompt },
         { getResolvedConfig },
+        { getExternalCodeGraphContext },
         { getObservationStore },
+        { collectCurrentProjectFacts, formatGitFact },
+        { resolveTaskLens },
       ] = await Promise.all([
         import('./codegraph/store.js'),
         import('./codegraph/context-pack.js'),
         import('./config/resolved-config.js'),
+        import('./codegraph/external-provider.js'),
         import('./store/obs-store.js'),
+        import('./codegraph/current-facts.js'),
+        import('./codegraph/task-lens.js'),
       ]);
       const store = new CodeGraphStore();
       await store.init(projectDir);
-      const exclude = getResolvedConfig({ projectRoot: project.rootPath }).codegraph.excludePatterns;
+      const codegraphConfig = getResolvedConfig({ projectRoot: project.rootPath }).codegraph;
+      const exclude = codegraphConfig.excludePatterns;
       const observations = await getObservationStore().loadByProject(project.id, { status: 'active' });
       observations.reverse();
-      const pack = assembleContextPackForTask({
+      const basePack = assembleContextPackForTask({
         store,
         projectId: project.id,
         task,
@@ -1427,6 +1451,55 @@ export async function createMemorixServer(
         limit: typeof limit === 'number' ? limit : 20,
         exclude,
       });
+      const status = store.status(project.id);
+      const currentFacts = collectCurrentProjectFacts({ project, now: new Date() });
+      const snapshot = status.latestSnapshot;
+      const external = await getExternalCodeGraphContext({
+        projectRoot: project.rootPath,
+        task,
+        exclude,
+        mode: codegraphConfig.externalContext,
+        command: codegraphConfig.externalCommand,
+        timeoutMs: codegraphConfig.externalTimeoutMs,
+      });
+      const worksetFacts: string[] = [];
+      if (currentFacts.packageVersion) worksetFacts.push('Package version: ' + currentFacts.packageVersion);
+      if (currentFacts.latestChangelog) {
+        worksetFacts.push('Latest changelog: ' + currentFacts.latestChangelog.version
+          + (currentFacts.latestChangelog.date ? ' (' + currentFacts.latestChangelog.date + ')' : ''));
+      }
+      worksetFacts.push(formatGitFact(currentFacts.git));
+      const codeState = snapshot
+        ? '- Code state: ' + (snapshot.baseRevision ? snapshot.baseRevision.slice(0, 12) : 'Git unavailable')
+          + ', ' + snapshot.worktreeState + ' worktree'
+          + ', epoch ' + snapshot.sourceEpoch
+        : '- Code state: no completed snapshot yet';
+      const pack = await attachTaskWorkset({
+        pack: basePack,
+        projectId: project.id,
+        dataDir: projectDir,
+        lens: resolveTaskLens(task).id,
+        worktreeDirty: currentFacts.git.dirty,
+        currentFacts: worksetFacts,
+        codeState,
+        ...(snapshot
+          ? {
+            snapshot: {
+              id: snapshot.id,
+              sourceEpoch: snapshot.sourceEpoch,
+              worktreeState: snapshot.worktreeState,
+              incomplete: snapshot.completeness.skippedOversizedFiles > 0
+                || (snapshot.completeness.unreadableFiles ?? 0) > 0
+                || snapshot.completeness.removalScanDeferred,
+            },
+          }
+          : {}),
+        ...(external.outline ? { semanticCode: external.outline } : {}),
+        providerQuality: external.quality,
+        ...(external.caution
+          ? { runtimeCautions: [{ kind: 'external-codegraph-fallback' as const, message: external.caution }] }
+          : {}),
+      });
       const text = buildContextPackPrompt(pack);
 
       return {
@@ -1435,6 +1508,339 @@ export async function createMemorixServer(
     },
   );
 
+  server.registerTool(
+    'memorix_knowledge',
+    {
+      title: 'Knowledge Workspace',
+      description:
+        'Manage the reviewable project Knowledge Workspace. Use it only for deliberate knowledge operations: initialize a local or versioned workspace, review source-backed claims, compile proposals, lint, apply a reviewed proposal, or manage canonical workflows. It is intentionally absent from the default micro/lite profiles.',
+      inputSchema: {
+        action: z.enum([
+          'workspace_init',
+          'status',
+          'claim_list',
+          'claim_review',
+          'compile',
+          'lint',
+          'proposal_apply',
+          'workflow_import',
+          'workflow_list',
+          'workflow_select',
+          'workflow_preview',
+          'workflow_apply',
+          'workflow_run',
+        ]).describe('Knowledge operation to perform'),
+        mode: z.enum(['local', 'versioned']).optional().default('local').describe('Workspace mode; versioned writes require an explicit project path during workspace_init'),
+        path: z.string().optional().describe('Explicit versioned workspace path, used only by workspace_init'),
+        proposalId: z.string().optional().describe('Pending proposal id for proposal_apply'),
+        allowManualOverwrite: z.boolean().optional().default(false).describe('Explicitly allow proposal_apply to replace a manually edited page'),
+        claimId: z.string().optional().describe('Source-backed claim id for claim_review'),
+        claimReviewState: z.enum(['approved', 'rejected']).optional().describe('Deliberate review verdict for claim_review'),
+        reviewDetail: z.string().max(2_000).optional().describe('Evidence check performed before approving or rejecting a claim'),
+        workflowId: z.string().optional().describe('Canonical workflow id for workflow preview, apply, or run'),
+        agent: z.string().optional().describe('Target agent for a workflow adapter'),
+        task: z.string().optional().describe('Task text for workflow selection or a workflow run'),
+        outcome: z.enum(['passed', 'failed', 'cancelled', 'in-progress']).optional().describe('Workflow run outcome'),
+        verificationVerdict: z.enum(['passed', 'failed', 'not-run']).optional().describe('Workflow run verification verdict'),
+        failureReason: z.string().optional().describe('Sanitized workflow failure reason'),
+        startingSnapshotId: z.string().optional().describe('Code snapshot id present when a workflow run began'),
+        evidenceIds: z.array(z.string()).max(24).optional().describe('Selected evidence ids for a workflow run'),
+      },
+    },
+    async ({
+      action,
+      mode,
+      path: workspacePath,
+      proposalId,
+      allowManualOverwrite,
+      claimId,
+      claimReviewState,
+      reviewDetail,
+      workflowId,
+      agent,
+      task,
+      outcome,
+      verificationVerdict,
+      failureReason,
+      startingSnapshotId,
+      evidenceIds,
+    }) => {
+      const unresolved = requireResolvedProject('manage the Knowledge Workspace for the current project');
+      if (unresolved) return unresolved;
+
+      const text = (value: unknown, isError = false) => ({
+        content: [{ type: 'text' as const, text: JSON.stringify(value, null, 2) }],
+        ...(isError ? { isError: true as const } : {}),
+      });
+      const modeValue = mode ?? 'local';
+      const requireText = (value: string | undefined, field: string): string | undefined => {
+        const normalized = value?.trim();
+        return normalized ? normalized : undefined;
+      };
+
+      const [
+        { ClaimStore },
+        { reviewClaim },
+        { CodeGraphStore },
+        { initializeKnowledgeWorkspace, loadKnowledgeWorkspace },
+        { KnowledgeWorkspaceStore },
+        { applyKnowledgeProposal, compileKnowledgeWorkspace, lintKnowledgeWorkspace },
+        { WorkflowStore },
+        {
+          applyWorkflowAdapter,
+          importWindsurfWorkflows,
+          previewWorkflowAdapter,
+          recordWorkflowRun,
+          selectWorkspaceWorkflows,
+          syncCanonicalWorkflows,
+        },
+      ] = await Promise.all([
+        import('./knowledge/claim-store.js'),
+        import('./knowledge/claims.js'),
+        import('./codegraph/store.js'),
+        import('./knowledge/workspace.js'),
+        import('./knowledge/workspace-store.js'),
+        import('./knowledge/wiki.js'),
+        import('./knowledge/workflow-store.js'),
+        import('./knowledge/workflows.js'),
+      ]);
+
+      if (action === 'workspace_init') {
+        if (modeValue === 'versioned' && !requireText(workspacePath, 'path')) {
+          return text({ error: 'path is required to initialize a versioned Knowledge Workspace.' }, true);
+        }
+        const workspace = await initializeKnowledgeWorkspace({
+          projectId: project.id,
+          dataDir: projectDir,
+          mode: modeValue,
+          ...(modeValue === 'versioned'
+            ? { projectRoot: project.rootPath, rootPath: requireText(workspacePath, 'path')! }
+            : {}),
+        });
+        return text({
+          workspace: {
+            id: workspace.id,
+            mode: workspace.mode,
+            rootPath: workspace.rootPath,
+            status: workspace.status,
+          },
+          next: 'Compile creates reviewable proposals; it does not silently publish pages.',
+        });
+      }
+
+      const workspace = await loadKnowledgeWorkspace({ projectId: project.id, dataDir: projectDir, mode: modeValue });
+      if (!workspace) {
+        return text({ error: 'Knowledge Workspace is not initialized. Run workspace_init first.' }, true);
+      }
+      const claims = new ClaimStore();
+      const workspaceStore = new KnowledgeWorkspaceStore();
+      await Promise.all([claims.init(projectDir), workspaceStore.init(projectDir)]);
+
+      if (action === 'status') {
+        const pages = workspaceStore.listPages(workspace.id);
+        const pending = workspaceStore.listProposals(workspace.id, 'pending');
+        return text({
+          workspace: {
+            id: workspace.id,
+            mode: workspace.mode,
+            rootPath: workspace.rootPath,
+            status: workspace.status,
+            publishedPages: pages.filter(page => page.status === 'active').length,
+            pendingProposals: pending.map(proposal => ({
+              id: proposal.id,
+              targetPath: proposal.targetPath,
+              reason: proposal.reason,
+              createdAt: proposal.createdAt,
+            })),
+            reviewableClaims: claims.listClaims(project.id, { limit: 100 })
+              .filter(claim => claim.reviewState === 'needs-review')
+              .map(claim => ({ id: claim.id, subject: claim.subject, predicate: claim.predicate, objectValue: claim.objectValue })),
+          },
+        });
+      }
+
+      if (action === 'claim_list') {
+        return text({
+          claims: claims.listClaims(project.id, { limit: 100 }).map(claim => ({
+            id: claim.id,
+            subject: claim.subject,
+            predicate: claim.predicate,
+            objectValue: claim.objectValue,
+            status: claim.status,
+            reviewState: claim.reviewState,
+            origin: claim.origin,
+            confidence: claim.confidence,
+            evidenceCount: claims.listEvidence(claim.id).length,
+          })),
+          next: 'Approve only after checking the linked evidence. Rejected claims stay out of retrieval and publication.',
+        });
+      }
+
+      if (action === 'claim_review') {
+        const requestedClaimId = requireText(claimId, 'claimId');
+        const detail = requireText(reviewDetail, 'reviewDetail');
+        if (!requestedClaimId || !claimReviewState || !detail) {
+          return text({ error: 'claimId, claimReviewState, and reviewDetail are required for claim_review.' }, true);
+        }
+        const existing = claims.getClaim(requestedClaimId);
+        if (!existing || existing.projectId !== project.id) {
+          return text({ error: 'Claim was not found for the current project.' }, true);
+        }
+        const claim = reviewClaim(claims, {
+          claimId: requestedClaimId,
+          reviewState: claimReviewState,
+          detail,
+        });
+        return text({
+          claim: {
+            id: claim.id,
+            status: claim.status,
+            reviewState: claim.reviewState,
+            updatedAt: claim.updatedAt,
+          },
+          next: claim.reviewState === 'approved'
+            ? 'This approved source-backed claim can now be considered by knowledge compilation.'
+            : 'This rejected claim is excluded from retrieval and knowledge compilation.',
+        });
+      }
+
+      if (action === 'compile') {
+        const result = await compileKnowledgeWorkspace({ workspace, claims });
+        return text({
+          proposals: result.proposals.map(proposal => ({
+            id: proposal.id,
+            targetPath: proposal.targetPath,
+            proposalPath: proposal.proposalPath,
+            reason: proposal.reason,
+          })),
+          unchangedPublishedPages: result.published.map(page => page.relativePath),
+          next: result.proposals.length ? 'Review a proposal, then use proposal_apply deliberately.' : undefined,
+        });
+      }
+
+      if (action === 'lint') {
+        const codeStore = new CodeGraphStore();
+        await codeStore.init(projectDir);
+        const result = await lintKnowledgeWorkspace({ workspace, claims, codeStore });
+        return text(result);
+      }
+
+      if (action === 'proposal_apply') {
+        const proposal = requireText(proposalId, 'proposalId');
+        if (!proposal) return text({ error: 'proposalId is required for proposal_apply.' }, true);
+        const result = await applyKnowledgeProposal({
+          workspace,
+          proposalId: proposal,
+          allowManualOverwrite: !!allowManualOverwrite,
+        });
+        return text({
+          proposal: { id: result.proposal.id, status: result.proposal.status },
+          targetPath: result.targetPath,
+        });
+      }
+
+      const workflowStore = new WorkflowStore();
+      await workflowStore.init(projectDir);
+      const projectRoot = workspace.projectRoot ?? project.rootPath;
+
+      if (action === 'workflow_import') {
+        const result = await importWindsurfWorkflows({ workspace, projectRoot });
+        return text({
+          imported: result.imported.map(workflow => ({
+            id: workflow.id,
+            title: workflow.title,
+            sourcePath: workflow.sourcePath,
+            importedFrom: workflow.importedFrom,
+            verificationGates: workflow.verificationGates,
+          })),
+          skipped: result.skipped,
+        });
+      }
+
+      const synced = await syncCanonicalWorkflows(workspace);
+      if (action === 'workflow_list') {
+        return text({
+          workflows: workflowStore.listWorkflows(workspace.id).map(workflow => ({
+            id: workflow.id,
+            title: workflow.title,
+            status: workflow.status,
+            taskLenses: workflow.taskLenses,
+            sourcePath: workflow.sourcePath,
+            importedFrom: workflow.importedFrom,
+            verificationGates: workflow.verificationGates,
+          })),
+          parseErrors: synced.errors,
+        });
+      }
+
+      if (action === 'workflow_select') {
+        const selectedTask = requireText(task, 'task');
+        if (!selectedTask) return text({ error: 'task is required for workflow_select.' }, true);
+        const result = await selectWorkspaceWorkflows({ workspace, task: selectedTask });
+        return text({
+          selections: result.selections.map(selection => ({
+            id: selection.workflow.id,
+            title: selection.workflow.title,
+            reasons: selection.reasons,
+            firstPhase: selection.firstPhase.title,
+            cautions: selection.cautions,
+          })),
+          parseErrors: result.errors,
+        });
+      }
+
+      const requestedWorkflowId = requireText(workflowId, 'workflowId');
+      if (!requestedWorkflowId) return text({ error: 'workflowId is required for this workflow action.' }, true);
+      const workflow = workflowStore.getWorkflow(requestedWorkflowId);
+      if (!workflow || workflow.workspaceId !== workspace.id) {
+        return text({ error: 'Workflow was not found for this Knowledge Workspace.' }, true);
+      }
+
+      if (action === 'workflow_preview' || action === 'workflow_apply') {
+        const targetAgent = requireText(agent, 'agent');
+        if (!targetAgent) return text({ error: 'agent is required for a workflow adapter action.' }, true);
+        const result = action === 'workflow_preview'
+          ? await previewWorkflowAdapter({ workflow, projectRoot, agent: targetAgent as any })
+          : await applyWorkflowAdapter({ workflow, projectRoot, agent: targetAgent as any });
+        return text({
+          workflowId: workflow.id,
+          agent: targetAgent,
+          status: result.status,
+          targetPath: result.targetPath,
+          reason: result.reason,
+          ...(action === 'workflow_preview' && result.content ? { content: result.content } : {}),
+        });
+      }
+
+      if (action === 'workflow_run') {
+        const runTask = requireText(task, 'task');
+        if (!runTask) return text({ error: 'task is required for workflow_run.' }, true);
+        if (!outcome) return text({ error: 'outcome is required for workflow_run.' }, true);
+        const result = await recordWorkflowRun({
+          workspace,
+          run: {
+            workflowId: workflow.id,
+            projectId: project.id,
+            task: runTask,
+            outcome,
+            ...(verificationVerdict ? { verificationVerdict } : {}),
+            ...(requireText(failureReason, 'failureReason') ? { failureReason: requireText(failureReason, 'failureReason') } : {}),
+            ...(requireText(startingSnapshotId, 'startingSnapshotId') ? { startingSnapshotId: requireText(startingSnapshotId, 'startingSnapshotId') } : {}),
+            selectedEvidence: [...new Set((evidenceIds ?? []).map(item => item.trim()).filter(Boolean))],
+          },
+        });
+        return text({
+          id: result.id,
+          workflowId: result.workflowId,
+          outcome: result.outcome,
+          verificationVerdict: result.verificationVerdict,
+        });
+      }
+
+      return text({ error: 'Unsupported knowledge action.' }, true);
+    },
+  );
+
   /**
    * memorix_resolve — Mark memories as resolved/completed
    *
@@ -2399,15 +2805,11 @@ export async function createMemorixServer(
   async function scopeGraphToProject(graph: { entities: any[]; relations: any[] }) {
     const { getAllObservations } = await import('./memory/observations.js');
     const allObs = await withFreshIndex(() => getAllObservations());
-    const projectEntityNames = new Set(
-      allObs
-        .filter(o => o.projectId === project.id && (o.status ?? 'active') === 'active' && o.entityName)
-        .map(o => o.entityName),
+    const scoped = scopeKnowledgeGraphToProject(
+      graph,
+      allObs.filter(observation => observation.projectId === project.id),
     );
-    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));
-    return { entities, relations };
+    return { entities: scoped.entities, relations: scoped.relations };
   }
 
   /** read_graph — MCP Official compatible */

package/src/store/file-lock.ts

@@ -9,6 +9,7 @@
  */
 
 import { promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 
 /** Lock is considered stale after 10 seconds (process crash recovery) */
@@ -17,6 +18,7 @@ const LOCK_STALE_MS = 10_000;
 const RETRY_INTERVAL_MS = 50;
 /** Maximum retries before giving up (50ms × 60 = 3 seconds) */
 const MAX_RETRIES = 60;
+const atomicWriteTails = new Map<string, Promise<void>>();
 
 /**
  * Acquire a lock file atomically.
@@ -93,8 +95,26 @@ export async function withFileLock<T>(projectDir: string, fn: () => Promise<T>):
  * On most filesystems, rename() is atomic within the same directory,
  * so readers always see either the old complete file or the new complete file.
  */
-export async function atomicWriteFile(filePath: string, data: string): Promise<void> {
-  const tmpPath = filePath + `.tmp.${process.pid}`;
-  await fs.writeFile(tmpPath, data, 'utf-8');
-  await fs.rename(tmpPath, filePath);
+async function atomicWriteFileOnce(filePath: string, data: string): Promise<void> {
+  const tmpPath = filePath + `.tmp.${process.pid}.${randomUUID()}`;
+  try {
+    await fs.writeFile(tmpPath, data, 'utf-8');
+    await fs.rename(tmpPath, filePath);
+  } catch (error) {
+    await fs.unlink(tmpPath).catch(() => {});
+    throw error;
+  }
+}
+
+/**
+ * Serialize same-process writes to one target. Windows refuses concurrent
+ * replacements of the same path even when each writer has its own temp file.
+ */
+export function atomicWriteFile(filePath: string, data: string): Promise<void> {
+  const previous = atomicWriteTails.get(filePath) ?? Promise.resolve();
+  const next = previous.catch(() => undefined).then(() => atomicWriteFileOnce(filePath, data));
+  atomicWriteTails.set(filePath, next);
+  return next.finally(() => {
+    if (atomicWriteTails.get(filePath) === next) atomicWriteTails.delete(filePath);
+  });
 }