memorix 1.1.13 → 1.2.1

package/src/cli/commands/doctor.ts

@@ -319,9 +319,11 @@ export default defineCommand({
         const { CodeGraphStore } = await import('../../codegraph/store.js');
         const { buildProjectContextOverview } = await import('../../codegraph/project-context.js');
         const { getResolvedConfig } = await import('../../config/resolved-config.js');
+        const { inspectExternalCodeGraph } = await import('../../codegraph/external-provider.js');
         const codeStore = new CodeGraphStore();
         await codeStore.init(dataDir);
-        const exclude = getResolvedConfig({ projectRoot: projectRoot || process.cwd() }).codegraph.excludePatterns;
+        const codegraphConfig = getResolvedConfig({ projectRoot: projectRoot || process.cwd() }).codegraph;
+        const exclude = codegraphConfig.excludePatterns;
         const overview = buildProjectContextOverview({
           project: {
             id: projectId,
@@ -335,6 +337,12 @@ export default defineCommand({
         const languageText = overview.code.languages.length > 0
           ? overview.code.languages.map((item: any) => `${item.language} ${item.files}`).join(', ')
           : 'none indexed yet';
+        const providerQuality = await inspectExternalCodeGraph({
+          projectRoot: projectRoot || process.cwd(),
+          mode: codegraphConfig.externalContext,
+          command: codegraphConfig.externalCommand,
+          timeoutMs: codegraphConfig.externalTimeoutMs,
+        });
 
         if (overview.code.files > 0) {
           lines.push(ok(`Code memory: ${overview.code.files} files, ${overview.code.symbols} symbols, ${overview.code.refs} memory links`));
@@ -344,6 +352,15 @@ export default defineCommand({
           tips.push('Run `memorix codegraph refresh` once to seed project context.');
         }
 
+        lines.push(info(
+          `Code provider: Lite durable index; external semantic graph ${providerQuality.health.state}`,
+        ));
+        if (providerQuality.health.state !== 'ready'
+          && providerQuality.health.state !== 'not-detected'
+          && providerQuality.health.state !== 'disabled') {
+          lines.push(warn(`External CodeGraph: ${providerQuality.health.reason ?? providerQuality.health.state}`));
+        }
+
         if (overview.freshness.stale > 0 || overview.freshness.suspect > 0) {
           lines.push(warn(`Freshness: ${overview.freshness.current} current, ${overview.freshness.suspect} suspect, ${overview.freshness.stale} stale`));
         } else {
@@ -362,6 +379,7 @@ export default defineCommand({
           refs: overview.code.refs,
           languages: overview.code.languages,
           freshness: overview.freshness,
+          providerQuality: providerQuality.quality,
           ...(overview.code.indexedAt ? { indexedAt: overview.code.indexedAt } : {}),
         };
       } catch (e) {
@@ -373,7 +391,58 @@ export default defineCommand({
       lines.push(info('Project context unavailable without a detected project.'));
     }
 
-    // ── 6. Conflict Check ────────────────────────────────────────
+    // ── 6. Knowledge Lifecycle ──────────────────────────────────
+    lines.push('');
+    lines.push('┌─ Knowledge Lifecycle ─────────────────────────────');
+
+    if (projectId && dataDir) {
+      try {
+        const { collectLifecycleDiagnostics } = await import('../../runtime/lifecycle-status.js');
+        const lifecycle = await collectLifecycleDiagnostics({ dataDir, projectId });
+        report.lifecycle = lifecycle;
+
+        const queued = lifecycle.maintenance.summary.pending + lifecycle.maintenance.summary.retrying;
+        const running = lifecycle.maintenance.summary.running;
+        if (lifecycle.maintenance.summary.failed > 0) {
+          lines.push(warn(`Maintenance: ${lifecycle.maintenance.summary.failed} failed job(s)`));
+          for (const job of lifecycle.maintenance.failedJobs) {
+            lines.push(info(`Failed: ${job.kind} after ${job.attempts} attempt(s)`));
+          }
+          issues.push('Knowledge maintenance has failed work. Run `memorix doctor --json` to inspect the affected job kind.');
+        } else if (queued > 0 || running > 0) {
+          lines.push(info(`Maintenance: ${queued} queued, ${running} running`));
+        } else {
+          lines.push(ok('Maintenance: idle'));
+        }
+
+        lines.push(info(
+          `Claims: ${lifecycle.claims.active} active, ${lifecycle.claims.needsReview} need review, ${lifecycle.claims.unknown} unknown`,
+        ));
+        if (lifecycle.claims.conflicts > 0) {
+          lines.push(warn(`Claim conflicts: ${lifecycle.claims.conflicts}`));
+          issues.push('Source-backed claims conflict and need review before they guide work.');
+        }
+
+        if (lifecycle.workspaces.length === 0) {
+          lines.push(info('Knowledge workspace: not initialized'));
+        } else {
+          for (const workspace of lifecycle.workspaces) {
+            lines.push(info(
+              `${workspace.mode} workspace: ${workspace.pages} pages, ${workspace.pendingProposals} pending proposal(s), ${workspace.status}`,
+            ));
+          }
+        }
+        lines.push(info(`Workflows: ${lifecycle.workflows.active}/${lifecycle.workflows.total} active, ${lifecycle.workflows.failedRuns} failed run(s)`));
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        lines.push(warn(`Knowledge lifecycle unavailable: ${message}`));
+        report.lifecycle = { error: message };
+      }
+    } else {
+      lines.push(info('Knowledge lifecycle unavailable without a detected project.'));
+    }
+
+    // ── 7. Conflict Check ────────────────────────────────────────
     lines.push('');
     lines.push('┌─ Conflict Check ──────────────────────────────────');
 
@@ -403,7 +472,7 @@ export default defineCommand({
     }
     report.conflicts = { found: conflictsFound };
 
-    // ── 7. LLM Status ────────────────────────────────────────────
+    // ── 8. LLM Status ────────────────────────────────────────────
     lines.push('');
     lines.push('┌─ LLM Enhanced Mode ───────────────────────────────');
 
@@ -427,7 +496,7 @@ export default defineCommand({
       report.llm = { enabled: false };
     }
 
-    // ── 8. Auto-Update Status ──────────────────────────────────
+    // ── 9. Auto-Update Status ──────────────────────────────────
     lines.push('');
     lines.push('┌─ Auto-Update ─────────────────────────────────────');
 

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,322 @@
+import { defineCommand } from 'citty';
+import { CodeGraphStore } from '../../codegraph/store.js';
+import { ClaimStore } from '../../knowledge/claim-store.js';
+import { reviewClaim } from '../../knowledge/claims.js';
+import { applyKnowledgeProposal, compileKnowledgeWorkspace, lintKnowledgeWorkspace } from '../../knowledge/wiki.js';
+import { initializeKnowledgeWorkspace, loadKnowledgeWorkspace } from '../../knowledge/workspace.js';
+import { KnowledgeWorkspaceStore } from '../../knowledge/workspace-store.js';
+import { WorkflowStore } from '../../knowledge/workflow-store.js';
+import {
+  applyWorkflowAdapter,
+  importWindsurfWorkflows,
+  previewWorkflowAdapter,
+  recordWorkflowRun,
+  selectWorkspaceWorkflows,
+  syncCanonicalWorkflows,
+} from '../../knowledge/workflows.js';
+import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
+
+function modeFrom(value: unknown): 'local' | 'versioned' {
+  if (!value || value === 'local') return 'local';
+  if (value === 'versioned') return 'versioned';
+  throw new Error('knowledge mode must be local or versioned');
+}
+
+function usage(): string {
+  return [
+    'Memorix Knowledge Commands',
+    '',
+    '  memorix knowledge init [--mode local]',
+    '  memorix knowledge init --mode versioned --path C:\\project\\docs\\knowledge',
+    '  memorix knowledge status',
+    '  memorix knowledge claims',
+    '  memorix knowledge review --id <claim-id> --review approved --detail "checked current source evidence"',
+    '  memorix knowledge compile',
+    '  memorix knowledge lint',
+    '  memorix knowledge apply --proposal <id> [--force]',
+    '  memorix knowledge workflow import',
+    '  memorix knowledge workflow list',
+    '  memorix knowledge workflow select --task "prepare a release"',
+    '  memorix knowledge workflow preview --id <workflow-id> --agent codex',
+    '  memorix knowledge workflow apply --id <workflow-id> --agent codex',
+    '  memorix knowledge workflow run --id <workflow-id> --task "..." --outcome passed',
+  ].join('\n');
+}
+
+function requiredText(value: unknown, field: string): string {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) throw new Error(field + ' is required');
+  return text;
+}
+
+function workflowOutcome(value: unknown): 'passed' | 'failed' | 'cancelled' | 'in-progress' {
+  if (value === 'passed' || value === 'failed' || value === 'cancelled' || value === 'in-progress') return value;
+  throw new Error('workflow outcome must be passed, failed, cancelled, or in-progress');
+}
+
+function workflowVerdict(value: unknown): 'passed' | 'failed' | 'not-run' | undefined {
+  if (value === undefined || value === null || value === '') return undefined;
+  if (value === 'passed' || value === 'failed' || value === 'not-run') return value;
+  throw new Error('workflow verdict must be passed, failed, or not-run');
+}
+
+function claimReviewState(value: unknown): 'approved' | 'rejected' {
+  if (value === 'approved' || value === 'rejected') return value;
+  throw new Error('claim review must be approved or rejected');
+}
+
+function evidenceList(value: unknown): string[] {
+  if (typeof value !== 'string' || !value.trim()) return [];
+  return [...new Set(value.split(',').map(item => item.trim()).filter(Boolean))];
+}
+
+export default defineCommand({
+  meta: {
+    name: 'knowledge',
+    description: 'Initialize, review, and lint the Memorix Knowledge Workspace',
+  },
+  args: {
+    action: { type: 'string', description: 'Action: init, status, compile, lint, or apply' },
+    mode: { type: 'string', description: 'Workspace mode: local or versioned' },
+    path: { type: 'string', description: 'Explicit versioned workspace path for init' },
+    proposal: { type: 'string', description: 'Proposal id for apply' },
+    force: { type: 'boolean', description: 'Explicitly allow an approved proposal to replace manual page edits' },
+    id: { type: 'string', description: 'Canonical workflow id' },
+    agent: { type: 'string', description: 'Target agent for a workflow adapter' },
+    task: { type: 'string', description: 'Task wording for workflow selection or a workflow run' },
+    outcome: { type: 'string', description: 'Workflow run outcome: passed, failed, cancelled, or in-progress' },
+    verdict: { type: 'string', description: 'Workflow verification verdict: passed, failed, or not-run' },
+    failure: { type: 'string', description: 'Sanitized failure reason for a workflow run' },
+    snapshot: { type: 'string', description: 'Starting code snapshot id for a workflow run' },
+    evidence: { type: 'string', description: 'Comma-separated evidence ids selected for a workflow run' },
+    review: { type: 'string', description: 'Claim review verdict: approved or rejected' },
+    detail: { type: 'string', description: 'Evidence check performed for a claim review' },
+    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+  },
+  run: async ({ args }) => {
+    const positional = (args._ as string[]) ?? [];
+    const action = (positional[0] || (args.action as string | undefined) || 'status').toLowerCase();
+    const asJson = !!args.json;
+    try {
+      const { project, dataDir } = await getCliProjectContext();
+      const mode = modeFrom(args.mode);
+      if (action === 'init') {
+        const workspace = await initializeKnowledgeWorkspace({
+          projectId: project.id,
+          dataDir,
+          mode,
+          ...(mode === 'versioned'
+            ? {
+              projectRoot: project.rootPath,
+              rootPath: (args.path as string | undefined) ?? '',
+            }
+            : {}),
+        });
+        emitResult(
+          { project, workspace },
+          'Knowledge workspace initialized at ' + workspace.rootPath,
+          asJson,
+        );
+        return;
+      }
+
+      const workspace = await loadKnowledgeWorkspace({ projectId: project.id, dataDir, mode });
+      if (!workspace) {
+        emitError('Knowledge workspace is not initialized. Run "memorix knowledge init" first.', asJson);
+        return;
+      }
+      const claimStore = new ClaimStore();
+      await claimStore.init(dataDir);
+      const workspaceStore = new KnowledgeWorkspaceStore();
+      await workspaceStore.init(dataDir);
+
+      if (action === 'claims') {
+        const claims = claimStore.listClaims(project.id, { limit: 100 });
+        emitResult(
+          { project, workspace, claims },
+          'Claims: ' + claims.length + ' total, ' + claims.filter(claim => claim.reviewState === 'needs-review').length + ' awaiting review.',
+          asJson,
+        );
+        return;
+      }
+
+      if (action === 'review') {
+        const claimId = requiredText(args.id, 'claim id');
+        const existing = claimStore.getClaim(claimId);
+        if (!existing || existing.projectId !== project.id) {
+          emitError('Claim was not found for this knowledge workspace.', asJson);
+          return;
+        }
+        const claim = reviewClaim(claimStore, {
+          claimId,
+          reviewState: claimReviewState(args.review),
+          detail: requiredText(args.detail, 'review detail'),
+        });
+        emitResult(
+          { project, workspace, claim },
+          'Claim ' + claim.id + ' marked ' + claim.reviewState + '.',
+          asJson,
+        );
+        return;
+      }
+
+      if (action === 'workflow') {
+        const workflowAction = (positional[1] || 'list').toLowerCase();
+        const workflowStore = new WorkflowStore();
+        await workflowStore.init(dataDir);
+        const projectRoot = workspace.projectRoot ?? project.rootPath;
+
+        if (workflowAction === 'import') {
+          const result = await importWindsurfWorkflows({ workspace, projectRoot });
+          emitResult(
+            { project, workspace, result },
+            'Imported ' + result.imported.length + ' Windsurf workflow(s); preserved ' + result.skipped.length + ' existing source or canonical file(s).',
+            asJson,
+          );
+          return;
+        }
+
+        const synced = await syncCanonicalWorkflows(workspace);
+        if (workflowAction === 'list') {
+          emitResult(
+            {
+              project,
+              workspace,
+              workflows: workflowStore.listWorkflows(workspace.id),
+              parseErrors: synced.errors,
+            },
+            [
+              'Canonical workflows: ' + workflowStore.listWorkflows(workspace.id).length,
+              'Parse errors: ' + synced.errors.length,
+            ].join('\n'),
+            asJson,
+          );
+          return;
+        }
+
+        if (workflowAction === 'select') {
+          const task = requiredText(args.task, 'task');
+          const result = await selectWorkspaceWorkflows({ workspace, task });
+          emitResult(
+            { project, workspace, task, ...result },
+            result.selections.length
+              ? 'Selected ' + result.selections.length + ' workflow(s) for this task.'
+              : 'No project workflow matches this task.',
+            asJson,
+          );
+          return;
+        }
+
+        const workflowId = requiredText(args.id, 'workflow id');
+        const workflow = workflowStore.getWorkflow(workflowId);
+        if (!workflow || workflow.workspaceId !== workspace.id) {
+          emitError('Workflow was not found for this knowledge workspace.', asJson);
+          return;
+        }
+
+        if (workflowAction === 'preview' || workflowAction === 'apply') {
+          const agent = requiredText(args.agent, 'agent');
+          const result = workflowAction === 'preview'
+            ? await previewWorkflowAdapter({ workflow, projectRoot, agent: agent as any })
+            : await applyWorkflowAdapter({ workflow, projectRoot, agent: agent as any });
+          emitResult(
+            { project, workspace, result },
+            'Workflow adapter ' + result.status + ': ' + result.reason,
+            asJson,
+          );
+          return;
+        }
+
+        if (workflowAction === 'run') {
+          const task = requiredText(args.task, 'task');
+          const outcome = workflowOutcome(args.outcome);
+          const result = await recordWorkflowRun({
+            workspace,
+            run: {
+              workflowId,
+              projectId: project.id,
+              task,
+              outcome,
+              ...(workflowVerdict(args.verdict) ? { verificationVerdict: workflowVerdict(args.verdict) } : {}),
+              ...(typeof args.failure === 'string' && args.failure.trim() ? { failureReason: args.failure.trim() } : {}),
+              ...(typeof args.snapshot === 'string' && args.snapshot.trim() ? { startingSnapshotId: args.snapshot.trim() } : {}),
+              selectedEvidence: evidenceList(args.evidence),
+            },
+          });
+          emitResult(
+            { project, workspace, result },
+            'Recorded workflow run ' + result.id + ' (' + result.outcome + ').',
+            asJson,
+          );
+          return;
+        }
+
+        emitResult({ usage: usage() }, usage(), asJson);
+        return;
+      }
+
+      switch (action) {
+        case 'status': {
+          const pages = workspaceStore.listPages(workspace.id);
+          const pending = workspaceStore.listProposals(workspace.id, 'pending');
+          emitResult(
+            { project, workspace, pages, pendingProposals: pending },
+            [
+              'Knowledge workspace: ' + workspace.rootPath,
+              '- Mode: ' + workspace.mode,
+              '- Published pages: ' + pages.filter(page => page.status === 'active').length,
+              '- Pending proposals: ' + pending.length,
+              '- Status: ' + workspace.status,
+            ].join('\n'),
+            asJson,
+          );
+          return;
+        }
+        case 'compile': {
+          const result = await compileKnowledgeWorkspace({ workspace, claims: claimStore });
+          emitResult(
+            { project, workspace, result },
+            'Knowledge compilation completed: ' + result.proposals.length + ' proposal(s), ' + result.published.length + ' unchanged published page(s).',
+            asJson,
+          );
+          return;
+        }
+        case 'lint': {
+          const codeStore = new CodeGraphStore();
+          await codeStore.init(dataDir);
+          const result = await lintKnowledgeWorkspace({ workspace, claims: claimStore, codeStore });
+          emitResult(
+            { project, workspace, result },
+            result.valid
+              ? 'Knowledge workspace lint passed.'
+              : 'Knowledge workspace lint found ' + result.issues.length + ' issue(s).',
+            asJson,
+          );
+          return;
+        }
+        case 'apply': {
+          const proposalId = (args.proposal as string | undefined)?.trim();
+          if (!proposalId) {
+            emitError('proposal is required for "memorix knowledge apply"', asJson);
+            return;
+          }
+          const result = await applyKnowledgeProposal({
+            workspace,
+            proposalId,
+            allowManualOverwrite: !!args.force,
+          });
+          emitResult(
+            { project, workspace, result },
+            'Knowledge proposal applied to ' + result.targetPath,
+            asJson,
+          );
+          return;
+        }
+        default:
+          emitResult({ usage: usage() }, usage(), asJson);
+      }
+    } catch (error) {
+      emitError(error instanceof Error ? error.message : String(error), asJson);
+    }
+  },
+});

package/src/cli/commands/serve-http.ts

@@ -23,6 +23,7 @@ import { defineCommand } from 'citty';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { ObservationStore } from '../../store/obs-store.js';
 import { resolveToolProfile } from '../../server/tool-profile.js';
+import { scopeKnowledgeGraphToProject } from '../../memory/graph-scope.js';
 
 export const DEFAULT_SESSION_TIMEOUT_MS = 30 * 60 * 1000;
 
@@ -764,6 +765,7 @@ export default defineCommand({
             source?: string;
             commitHash?: string;
             filesModified?: string[];
+            relatedEntities?: string[];
             status?: string;
             importance?: number;
             accessCount?: number;
@@ -860,22 +862,20 @@ export default defineCommand({
           } catch { /* best effort */ }
 
           // Project-scoped graph counts (must match /graph and /export)
-          const projectEntityNames = new Set(
-            observations.filter(o => o.entityName).map(o => o.entityName!)
-          );
-          const projectEntities = graph.entities.filter((e: any) => projectEntityNames.has(e.name));
-          const projectEntitySet = new Set(projectEntities.map((e: any) => e.name));
-          const projectRelations = graph.relations.filter((r: any) => projectEntitySet.has(r.from) && projectEntitySet.has(r.to));
+          const projectGraph = scopeKnowledgeGraphToProject(graph, observations);
 
           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(statsDataDir).summary(statsProjectId);
+            const { collectLifecycleDiagnostics } = await import('../../runtime/lifecycle-status.js');
+            lifecycle = await collectLifecycleDiagnostics({ dataDir: statsDataDir, projectId: statsProjectId });
           } catch { /* optional maintenance diagnostics */ }
 
           sendJson({
-            entities: projectEntities.length,
-            relations: projectRelations.length,
+            entities: projectGraph.entities.length,
+            relations: projectGraph.relations.length,
             observations: observations.length,
             nextId,
             typeCounts,
@@ -892,17 +892,25 @@ export default defineCommand({
             },
             retentionSummary,
             maintenance,
+            ...(lifecycle ? { lifecycle } : {}),
           });
           return;
         }
 
         if (apiPath === '/maintenance') {
           const { projectId: maintenanceProjectId, dataDir: maintenanceDataDir } = await resolveRequestProject(url);
-          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 queue = new MaintenanceJobStore(maintenanceDataDir);
           sendJson({
             summary: queue.summary(maintenanceProjectId),
             jobs: queue.list({ projectId: maintenanceProjectId, limit: 50 }),
+            lifecycle: await collectLifecycleDiagnostics({
+              dataDir: maintenanceDataDir,
+              projectId: maintenanceProjectId,
+            }),
           });
           return;
         }
@@ -919,19 +927,9 @@ export default defineCommand({
           await initGraphStore(graphDataDir);
           const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
 
-          // Project-scope the graph: only include entities that have observations in this project
-          const allObs = await loadDashboardProjectObservations(graphDataDir, graphProjectId, 'active') as Array<{ entityName?: string }>;
-          const projectEntityNames = new Set(
-            allObs
-              .filter(o => o.entityName)
-              .map(o => o.entityName!)
-          );
-
-          const entities = fullGraph.entities.filter(e => projectEntityNames.has(e.name));
-          const entityNameSet = new Set(entities.map(e => e.name));
-          const relations = fullGraph.relations.filter(r => entityNameSet.has(r.from) && entityNameSet.has(r.to));
-
-          sendJson({ entities, relations });
+          const allObs = await loadDashboardProjectObservations(graphDataDir, graphProjectId, 'active');
+          const scoped = scopeKnowledgeGraphToProject(fullGraph, allObs);
+          sendJson({ entities: scoped.entities, relations: scoped.relations });
           return;
         }
 
@@ -1001,24 +999,15 @@ export default defineCommand({
           const allObs = await loadDashboardProjectObservations(kgDataDir, kgProjectId, 'active');
           const skills = await getMiniSkillStore().loadByProject(kgProjectId);
 
-          // Project-scope graph store (same logic as /api/graph)
           const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
-          const graphObs = await loadDashboardProjectObservations(kgDataDir, kgProjectId, 'active') as Array<{ entityName?: string }>;
-          const projectEntityNames = new Set(
-            graphObs
-              .filter(o => o.entityName)
-              .map(o => o.entityName!)
-          );
-          const scopedEntities = fullGraph.entities.filter(e => projectEntityNames.has(e.name));
-          const scopedEntityNameSet = new Set(scopedEntities.map(e => e.name));
-          const scopedRelations = fullGraph.relations.filter(r => scopedEntityNameSet.has(r.from) && scopedEntityNameSet.has(r.to));
+          const scoped = scopeKnowledgeGraphToProject(fullGraph, allObs);
 
           const graph = generateKnowledgeGraph({
             projectId: kgProjectId,
             observations: allObs,
             miniSkills: skills,
-            graphEntities: scopedEntities,
-            graphRelations: scopedRelations,
+            graphEntities: scoped.entities,
+            graphRelations: scoped.relations,
           });
 
           sendJson(graph);
@@ -1358,19 +1347,14 @@ export default defineCommand({
           const { initGraphStore, getGraphStore } = await import('../../store/graph-store.js');
           await initGraphStore(expDataDir);
           const fullGraph = { entities: getGraphStore().loadEntities(), relations: getGraphStore().loadRelations() };
-          const observations = await loadDashboardProjectObservations(expDataDir, expProjectId, 'active') as Array<{ entityName?: string }>;
+          const observations = await loadDashboardProjectObservations(expDataDir, expProjectId, 'active');
           const expStore = await getDashboardObservationStore(expDataDir);
           const nextId = await expStore.loadIdCounter();
-          const exportEntityNames = new Set(
-            observations.filter(o => 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: expProjectId, name: expProjectName },
             exportedAt: new Date().toISOString(),
-            graph: { entities: exportEntities, relations: exportRelations },
+            graph: { entities: scoped.entities, relations: scoped.relations },
             observations,
             nextId,
           };

package/src/cli/commands/setup.ts

@@ -1062,7 +1062,7 @@ function tryInstallOmpPackage(packagePath: string): { ok: boolean; message: stri
   };
 }
 
-async function installAgentSetup(agent: AgentName, plan: SetupPlan, global: boolean): Promise<void> {
+export async function installAgentSetup(agent: AgentName, plan: SetupPlan, global: boolean): Promise<void> {
   const { installAgentGuidance, installHooks } = await import('../../hooks/installers/index.js');
   const targetRoot = global ? homedir() : process.cwd();
   const hasPluginPackage = plan.actions.includes('plugin-package') && PLUGIN_PACKAGE_AGENTS.has(agent);
@@ -1200,13 +1200,19 @@ async function installAgentSetup(agent: AgentName, plan: SetupPlan, global: bool
   } else if (hasOmpPackage) {
     p.log.info(`${agent}: extension command, hook events, and skills are bundled in the Oh-my-Pi package`);
   } else if (hasExtensionPackage) {
-    if (plan.actions.includes('hooks') || plan.actions.includes('project-guidance')) {
+    if (plan.actions.includes('hooks')) {
       const result = await installHooks(agent, targetRoot, global);
       p.log.success(`${agent}: integration files -> ${result.configPath}`);
+    } else if (plan.actions.includes('project-guidance')) {
+      const rulesPath = await installAgentGuidance(agent, targetRoot, global);
+      p.log.success(`${agent}: guidance -> ${rulesPath}`);
     }
-  } else if (agent === 'opencode' || plan.actions.includes('hooks') || plan.actions.includes('project-guidance')) {
+  } else if (plan.actions.includes('hooks')) {
     const result = await installHooks(agent, targetRoot, global);
     p.log.success(`${agent}: integration files -> ${result.configPath}`);
+  } else if (plan.actions.includes('project-guidance')) {
+    const rulesPath = await installAgentGuidance(agent, targetRoot, global);
+    p.log.success(`${agent}: guidance -> ${rulesPath}`);
   }
 
   if (agent === 'pi') {

package/src/cli/index.ts

@@ -989,6 +989,7 @@ const main = defineCommand({
     context: () => import('./commands/context.js').then(m => m.default),
     explain: () => import('./commands/explain.js').then(m => m.default),
     codegraph: () => import('./commands/codegraph.js').then(m => m.default),
+    knowledge: () => import('./commands/knowledge.js').then(m => m.default),
     reasoning: () => import('./commands/reasoning.js').then(m => m.default),
     retention: () => import('./commands/retention.js').then(m => m.default),
     formation: () => import('./commands/formation.js').then(m => m.default),
@@ -1048,7 +1049,7 @@ const main = defineCommand({
     // Detect by checking if the first CLI arg matches a registered subcommand name.
     const firstArg = process.argv[2];
     const knownSubs = ['ask', 'search', 'remember', 'recent', 'memcode', 'config',
-      'init', 'setup', 'integrate', 'memory', 'context', 'explain', 'codegraph', 'reasoning', 'retention', 'formation', 'audit', 'transfer', 'skills',
+      'init', 'setup', 'integrate', 'memory', 'context', 'explain', 'codegraph', 'knowledge', 'reasoning', 'retention', 'formation', 'audit', 'transfer', 'skills',
       'session', 'team', 'task', 'message', 'lock', 'handoff', 'poll',
       'receipt',
       'serve', 'serve-http', 'status', 'sync',
@@ -1088,6 +1089,7 @@ const main = defineCommand({
       console.error('  context    Show the Memory Autopilot brief for this project');
       console.error('  explain    Explain where Memorix project context comes from');
       console.error('  codegraph  Refresh/status/context-pack for CodeGraph Memory');
+      console.error('  knowledge  Review source-backed knowledge pages and project workflows');
       console.error('  reasoning  Store/search decision rationale');
       console.error('  retention  Inspect stale/archive status');
       console.error('  formation  Inspect Memory Formation metrics');

package/src/cli/tui/App.tsx

@@ -598,7 +598,7 @@ export function WorkbenchApp({ version, onExitForInteractive }: AppProps): React
           setKnowledgeSelectedIdx(0);
           setLoading(false);
           navigateTo('knowledge');
-          setStatusMsg({ text: kb ? `Knowledge Base: ${kb.stats.observationsUsed} obs, ${kb.stats.miniSkillsUsed} skills` : 'No knowledge available', type: 'info' });
+          setStatusMsg({ text: kb ? `Memory Overview: ${kb.stats.observationsUsed} obs, ${kb.stats.miniSkillsUsed} skills` : 'No memory overview available', type: 'info' });
           break;
         }
         case 'memory': {