memorix 1.1.13 → 1.2.0

package/src/cli/commands/knowledge.ts

@@ -0,0 +1,282 @@
+import { defineCommand } from 'citty';
+import { CodeGraphStore } from '../../codegraph/store.js';
+import { ClaimStore } from '../../knowledge/claim-store.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 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 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' },
+    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 === '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

@@ -868,9 +868,12 @@ export default defineCommand({
           const projectRelations = graph.relations.filter((r: any) => projectEntitySet.has(r.from) && projectEntitySet.has(r.to));
 
           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({
@@ -892,17 +895,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;
         }

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': {

package/src/cli/tui/Panels.tsx

@@ -553,8 +553,8 @@ export function WikiView({ knowledge, loading }: WikiViewProps): React.ReactElem
   if (loading) {
     return (
       <Box flexDirection="column" paddingX={1}>
-        <Text color={COLORS.brand} bold>Knowledge Base</Text>
-        <Text color={COLORS.muted}>  LLM Wiki</Text>
+        <Text color={COLORS.brand} bold>Memory Overview</Text>
+        <Text color={COLORS.muted}>  Generated from durable memory</Text>
         <Text color={COLORS.border}>{separator()}</Text>
         <Text color={COLORS.muted}>Loading...</Text>
       </Box>
@@ -564,19 +564,19 @@ export function WikiView({ knowledge, loading }: WikiViewProps): React.ReactElem
   if (!knowledge) {
     return (
       <Box flexDirection="column" paddingX={1}>
-        <Text color={COLORS.brand} bold>Knowledge Base</Text>
-        <Text color={COLORS.muted}>  LLM Wiki</Text>
+        <Text color={COLORS.brand} bold>Memory Overview</Text>
+        <Text color={COLORS.muted}>  Generated from durable memory</Text>
         <Text color={COLORS.border}>{separator()}</Text>
-        <Text color={COLORS.warning}>No knowledge available for this project.</Text>
-        <Text color={COLORS.textDim}>Store memories with /remember or /chat to build your Knowledge Base.</Text>
+        <Text color={COLORS.warning}>No memory overview is available for this project.</Text>
+        <Text color={COLORS.textDim}>Store durable memories with /remember or /chat to build your overview.</Text>
       </Box>
     );
   }
 
   return (
     <Box flexDirection="column" paddingX={1}>
-      <Text color={COLORS.brand} bold>Knowledge Base</Text>
-      <Text color={COLORS.muted}>  LLM Wiki</Text>
+      <Text color={COLORS.brand} bold>Memory Overview</Text>
+      <Text color={COLORS.muted}>  Generated from durable memory</Text>
       <Box>
         <Text color={COLORS.textDim}>  Project: {knowledge.projectId}</Text>
         <Text color={COLORS.muted}> │ {knowledge.stats.observationsUsed} obs, {knowledge.stats.miniSkillsUsed} skills</Text>

package/src/cli/tui/theme.ts

@@ -31,7 +31,7 @@ export const SLASH_COMMANDS: SlashCommand[] = [
   { name: '/integrate',  description: 'Set up an IDE',          alias: '/setup' },
   { name: '/cleanup',    description: 'Cleanup and purge' },
   { name: '/ingest',     description: 'Git to Memory' },
-  { name: '/wiki',       description: 'Knowledge Base',         alias: '/knowledge' },
+  { name: '/wiki',       description: 'Memory overview',        alias: '/knowledge' },
   { name: '/exit',       description: 'Exit workbench',         alias: '/q' },
 ];
 

package/src/cli/tui/views/GraphView.tsx

@@ -1,5 +1,5 @@
 /**
- * GraphView — Knowledge graph text browser.
+ * GraphView — deterministic memory-map text browser.
  *
  * Modes: browse (clusters + nodes), detail (single node with edge summary).
  * Keyboard: f filter, up/down navigate, enter detail, k -> Knowledge, esc back.
@@ -168,7 +168,7 @@ export function GraphView({ projectId, inputFocused, onNavigateKnowledge }: Grap
     return (
       <Box flexDirection="column" paddingX={1}>
         <Box>
-          <Text color={COLORS.brand} bold>Graph Node Detail</Text>
+          <Text color={COLORS.brand} bold>Memory Map Item</Text>
         </Box>
         <Text color={COLORS.border}>{separator()}</Text>
         <Box marginY={1} flexDirection="column">
@@ -190,7 +190,7 @@ export function GraphView({ projectId, inputFocused, onNavigateKnowledge }: Grap
         )}
         {/* Edge summary */}
         <Box marginY={1} flexDirection="column">
-          <Text color={COLORS.brandDim} bold>Edges</Text>
+          <Text color={COLORS.brandDim} bold>Links</Text>
           <Text color={COLORS.muted}>Outgoing ({outgoing.length}): </Text>
           {outgoing.slice(0, 6).map((e) => {
             const targetNode = graph?.nodes.find((n) => n.id === e.target);
@@ -213,7 +213,7 @@ export function GraphView({ projectId, inputFocused, onNavigateKnowledge }: Grap
           {incoming.length > 6 && <Text color={COLORS.muted}>  ... +{incoming.length - 6} more</Text>}
         </Box>
         <Box marginTop={1}>
-          <Text color={COLORS.muted}>esc back  |  k {'>'} Knowledge</Text>
+          <Text color={COLORS.muted}>esc back  |  k {'>'} Memory Overview</Text>
         </Box>
       </Box>
     );
@@ -230,11 +230,12 @@ export function GraphView({ projectId, inputFocused, onNavigateKnowledge }: Grap
     <Box flexDirection="column" paddingX={1}>
       <Box flexDirection="column">
         <Box>
-          <Text color={COLORS.brand} bold>Knowledge Graph</Text>
+          <Text color={COLORS.brand} bold>Memory Map</Text>
           {!loading && graph && (
             <Text color={COLORS.muted}> | {graph.stats.totalNodes} nodes, {graph.stats.totalEdges} edges, {graph.stats.clusterCount} clusters</Text>
           )}
         </Box>
+        <Text color={COLORS.textDim}>Deterministic links from shared entities, skill sources, and explicit relations</Text>
         {/* Filter bar */}
         {!loading && graph && (
           <Box marginTop={0}>
@@ -248,7 +249,7 @@ export function GraphView({ projectId, inputFocused, onNavigateKnowledge }: Grap
       {loading ? (
         <Text color={COLORS.muted}>Loading...</Text>
       ) : !graph ? (
-        <Text color={COLORS.muted}>No graph data available. Store observations to build the knowledge graph.</Text>
+        <Text color={COLORS.muted}>No memory map data is available. Store durable observations to build deterministic links.</Text>
       ) : flatItems.length === 0 ? (
         <Text color={COLORS.muted}>
           {filterMode !== 'all' ? 'No nodes match this filter.' : 'No nodes in graph.'}
@@ -290,7 +291,7 @@ export function GraphView({ projectId, inputFocused, onNavigateKnowledge }: Grap
 
       <Box marginTop={1} flexDirection="column">
         <Text color={COLORS.textDim}>
-          f filter  |  up/down navigate  |  enter detail  |  k {'>'} Knowledge
+          f filter  |  up/down navigate  |  enter detail  |  k {'>'} Memory Overview
         </Text>
       </Box>
     </Box>

package/src/cli/tui/views/KnowledgeView.tsx

@@ -1,5 +1,5 @@
 /**
- * KnowledgeView — Wiki browser for the shared knowledge layer.
+ * KnowledgeView — read-only memory overview browser.
  *
  * Displays ProjectKnowledgeOverview sections and items.
  * Each item shows its provenance refs; pressing 'm' on an item
@@ -36,8 +36,8 @@ export function KnowledgeView({ knowledge, loading, selectedItemIdx, itemCount }
   if (loading) {
     return (
       <Box flexDirection="column" paddingX={1}>
-        <Text color={COLORS.brand} bold>Knowledge Base</Text>
-        <Text color={COLORS.muted}>  LLM Wiki</Text>
+        <Text color={COLORS.brand} bold>Memory Overview</Text>
+        <Text color={COLORS.muted}>  Generated from durable memory</Text>
         <Text color={COLORS.border}>{separator()}</Text>
         <Text color={COLORS.muted}>Loading…</Text>
       </Box>
@@ -47,11 +47,11 @@ export function KnowledgeView({ knowledge, loading, selectedItemIdx, itemCount }
   if (!knowledge) {
     return (
       <Box flexDirection="column" paddingX={1}>
-        <Text color={COLORS.brand} bold>Knowledge Base</Text>
-        <Text color={COLORS.muted}>  LLM Wiki</Text>
+        <Text color={COLORS.brand} bold>Memory Overview</Text>
+        <Text color={COLORS.muted}>  Generated from durable memory</Text>
         <Text color={COLORS.border}>{separator()}</Text>
-        <Text color={COLORS.warning}>No knowledge available for this project.</Text>
-        <Text color={COLORS.textDim}>Store memories with /remember or use Workbench to build context.</Text>
+        <Text color={COLORS.warning}>No memory overview is available for this project.</Text>
+        <Text color={COLORS.textDim}>Store durable memories with /remember or use Workbench to build context.</Text>
       </Box>
     );
   }
@@ -68,8 +68,8 @@ export function KnowledgeView({ knowledge, loading, selectedItemIdx, itemCount }
   return (
     <Box flexDirection="column" paddingX={1}>
       <Box>
-        <Text color={COLORS.brand} bold>Knowledge Base</Text>
-        <Text color={COLORS.muted}>  LLM Wiki</Text>
+        <Text color={COLORS.brand} bold>Memory Overview</Text>
+        <Text color={COLORS.muted}>  Generated from durable memory</Text>
       </Box>
       <Box>
         <Text color={COLORS.textDim}>  {knowledge.projectId}</Text>