memorix 1.4.3 → 1.4.5

package/src/cli/commands/lock.ts

@@ -1,97 +1,97 @@
-import { defineCommand } from 'citty';
+import { defineCommand } from 'citty';
 import { emitError, emitResult, getCliProjectContext, resolveCliActorId, shortId } from './operator-shared.js';
-
-export default defineCommand({
-  meta: {
-    name: 'lock',
-    description: 'Acquire, release, and inspect advisory team file locks',
-  },
-  args: {
-    file: { type: 'string', description: 'File path to lock or inspect' },
-    agentId: { type: 'string', description: 'Agent ID acquiring or releasing the lock' },
-    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
-  },
-  run: async ({ args }) => {
-    const action = (args._ as string[])?.[0] || '';
-    const asJson = !!args.json;
-
-    try {
+
+export default defineCommand({
+  meta: {
+    name: 'lock',
+    description: 'Acquire, release, and inspect advisory team file locks',
+  },
+  args: {
+    file: { type: 'string', description: 'File path to lock or inspect' },
+    agentId: { type: 'string', description: 'Agent ID acquiring or releasing the lock' },
+    json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+  },
+  run: async ({ args }) => {
+    const action = (args._ as string[])?.[0] || '';
+    const asJson = !!args.json;
+
+    try {
       const { project, teamStore, identity } = await getCliProjectContext();
       const agentId = resolveCliActorId(args.agentId, identity);
-
-      switch (action) {
-        case 'lock': {
+
+      switch (action) {
+        case 'lock': {
           if (!args.file || !agentId) {
             emitError('file and an active CLI identity or agentId are required for "memorix lock lock"', asJson);
             return;
           }
           const result = teamStore.acquireLock(project.id, args.file as string, agentId);
-          if (!result.success) {
-            emitError(`File is already locked by ${shortId(result.lockedBy)}`, asJson);
-            return;
-          }
-          emitResult(
+          if (!result.success) {
+            emitError(`File is already locked by ${shortId(result.lockedBy)}`, asJson);
+            return;
+          }
+          emitResult(
             { project, file: args.file, lockedBy: agentId },
-            `Locked: ${args.file as string}`,
-            asJson,
-          );
-          return;
-        }
-
-        case 'unlock': {
+            `Locked: ${args.file as string}`,
+            asJson,
+          );
+          return;
+        }
+
+        case 'unlock': {
           if (!args.file || !agentId) {
             emitError('file and an active CLI identity or agentId are required for "memorix lock unlock"', asJson);
             return;
           }
           const released = teamStore.releaseLock(project.id, args.file as string, agentId);
-          if (!released) {
-            emitError('Cannot unlock: not the owner or the file is not locked', asJson);
-            return;
-          }
-          emitResult(
-            { project, file: args.file, released: true },
-            `Unlocked: ${args.file as string}`,
-            asJson,
-          );
-          return;
-        }
-
-        case 'status': {
-          if (args.file) {
-            const lock = teamStore.getLockStatus(project.id, args.file as string);
-            emitResult(
-              { project, lock },
-              lock
-                ? `Locked by ${teamStore.getAgent(lock.locked_by)?.name ?? shortId(lock.locked_by)}: ${args.file as string}`
-                : `Unlocked: ${args.file as string}`,
-              asJson,
-            );
-            return;
-          }
-
+          if (!released) {
+            emitError('Cannot unlock: not the owner or the file is not locked', asJson);
+            return;
+          }
+          emitResult(
+            { project, file: args.file, released: true },
+            `Unlocked: ${args.file as string}`,
+            asJson,
+          );
+          return;
+        }
+
+        case 'status': {
+          if (args.file) {
+            const lock = teamStore.getLockStatus(project.id, args.file as string);
+            emitResult(
+              { project, lock },
+              lock
+                ? `Locked by ${teamStore.getAgent(lock.locked_by)?.name ?? shortId(lock.locked_by)}: ${args.file as string}`
+                : `Unlocked: ${args.file as string}`,
+              asJson,
+            );
+            return;
+          }
+
           const locks = teamStore.listLocks(project.id, agentId);
-          emitResult(
-            { project, locks },
-            locks.length === 0
-              ? 'No active file locks.'
-              : locks
-                  .map((lock) => `- ${lock.file} -> ${teamStore.getAgent(lock.locked_by)?.name ?? shortId(lock.locked_by)}`)
-                  .join('\n'),
-            asJson,
-          );
-          return;
-        }
-
-        default:
-          console.log('Memorix Lock Commands');
-          console.log('');
-          console.log('Usage:');
-          console.log('  memorix lock lock --file src/app.ts --agentId <id>');
-          console.log('  memorix lock unlock --file src/app.ts --agentId <id>');
-          console.log('  memorix lock status [--file src/app.ts] [--agentId <id>]');
-      }
-    } catch (error) {
-      emitError(error instanceof Error ? error.message : String(error), asJson);
-    }
-  },
-});
+          emitResult(
+            { project, locks },
+            locks.length === 0
+              ? 'No active file locks.'
+              : locks
+                  .map((lock) => `- ${lock.file} -> ${teamStore.getAgent(lock.locked_by)?.name ?? shortId(lock.locked_by)}`)
+                  .join('\n'),
+            asJson,
+          );
+          return;
+        }
+
+        default:
+          console.log('Memorix Lock Commands');
+          console.log('');
+          console.log('Usage:');
+          console.log('  memorix lock lock --file src/app.ts --agentId <id>');
+          console.log('  memorix lock unlock --file src/app.ts --agentId <id>');
+          console.log('  memorix lock status [--file src/app.ts] [--agentId <id>]');
+      }
+    } catch (error) {
+      emitError(error instanceof Error ? error.message : String(error), asJson);
+    }
+  },
+});

package/src/cli/commands/media-image.ts

@@ -0,0 +1,27 @@
+import { readFile, stat } from 'node:fs/promises';
+
+import { MAX_VISION_IMAGE_BYTES } from '../../multimodal/image-payload.js';
+
+function matchesImagePrefix(bytes: Buffer, prefix: number[]): boolean {
+  return prefix.every((byte, index) => bytes[index] === byte);
+}
+
+function detectReferenceImageMimeType(bytes: Buffer): string | undefined {
+  if (bytes.length >= 8 && matchesImagePrefix(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return 'image/png';
+  if (bytes.length >= 3 && matchesImagePrefix(bytes, [0xff, 0xd8, 0xff])) return 'image/jpeg';
+  if (bytes.length >= 6 && (bytes.subarray(0, 6).toString('ascii') === 'GIF87a' || bytes.subarray(0, 6).toString('ascii') === 'GIF89a')) return 'image/gif';
+  if (bytes.length >= 12 && bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP') return 'image/webp';
+  return undefined;
+}
+
+export async function readSubjectImage(filePath: string): Promise<{ data: string; mimeType: string }> {
+  const fileStats = await stat(filePath);
+  if (fileStats.size > MAX_VISION_IMAGE_BYTES) {
+    throw new Error(`Reference image exceeds the ${MAX_VISION_IMAGE_BYTES}-byte visual analysis limit`);
+  }
+  const bytes = await readFile(filePath);
+  if (bytes.length === 0) throw new Error(`Reference image is empty: ${filePath}`);
+  const mimeType = detectReferenceImageMimeType(bytes);
+  if (!mimeType) throw new Error('Reference image must be a PNG, JPEG, GIF, or WebP file');
+  return { data: bytes.toString('base64'), mimeType };
+}

package/src/cli/commands/media.ts

@@ -18,6 +18,7 @@ import {
 import { launchMediaVideoRunner, queueMiniMaxVideoGeneration } from '../../media/video-jobs.js';
 import { launchMediaAudioRunner, queueAudioTranscription } from '../../media/audio-jobs.js';
 import type { MediaKind } from '../../media/types.js';
+import { readSubjectImage } from './media-image.js';
 import {
   emitError,
   emitResult,
@@ -118,7 +119,7 @@ function help(): string {
     '  memorix media attach --asset <asset-id> [--title "Architecture"] [--text "..."]',
     '  memorix media embed --asset <asset-id>',
     '  memorix media similar --asset <asset-id> [--limit 10]',
-    '  memorix media generate image --prompt "..." [--model image-01] [--attach]',
+    '  memorix media generate image --prompt "..." [--model image-01] [--image ./reference.png] [--attach]',
     '  memorix media generate video --prompt "..." [--model MiniMax-H3] [--duration 5] [--ratio 16:9] [--attach]',
     '  memorix media status --job <media-job-id>',
     '  memorix media cancel --job <media-job-id>',
@@ -145,6 +146,7 @@ export default defineCommand({
     concepts: { type: 'string', description: 'Comma-separated concepts when attaching' },
     visibility: { type: 'string', description: 'Observation visibility when attaching' },
     prompt: { type: 'string', description: 'Generation prompt' },
+    image: { type: 'string', description: 'Path to a reference image for image-to-image generation' },
     model: { type: 'string', description: 'Provider model' },
     provider: { type: 'string', description: 'Audio transcription provider: openai or groq' },
     language: { type: 'string', description: 'Optional ISO-639-1 hint for audio transcription' },
@@ -223,6 +225,10 @@ export default defineCommand({
             );
             return;
           }
+          const referenceImagePath = getValue(args.image);
+          const subjectImages = referenceImagePath
+            ? [await readSubjectImage(referenceImagePath)]
+            : undefined;
           const generated = await generateMiniMaxImages({
             dataDir,
             projectId: project.id,
@@ -235,6 +241,7 @@ export default defineCommand({
             height: parseOptionalInteger(args.height, 'height', 1, 8_192),
             seed: parseOptionalInteger(args.seed, 'seed', 0, 2_147_483_647),
             promptOptimizer: args.promptOptimizer === true || args['prompt-optimizer'] === true,
+            subjectImages,
             maxBytes: parseByteLimit(args.maxBytes ?? args['max-bytes'], 100 * 1024 * 1024),
           });
           const observations = args.attach === true

package/src/cli/commands/memory.ts

@@ -5,6 +5,7 @@ import { getAllObservations, getObservation, getProjectObservations, resolveObse
 import { buildGraphContextPacket, formatGraphContextPrompt } from '../../memory/graph-context.js';
 import { canManageObservation, filterReadableObservations, resolveObservationVisibility } from '../../memory/visibility.js';
 import {
+  asStringArg,
   coerceObservationStatus,
   coerceObservationType,
   coerceRetrievalQuality,
@@ -12,6 +13,7 @@ import {
   emitResult,
   getCliReadContext,
   getCliProjectContext,
+  lastStringArg,
   parseCsvList,
   parsePositiveInt,
   resolveCliWriteScope,
@@ -66,7 +68,7 @@ export default defineCommand({
     const action = (args._ as string[])?.[0] || '';
     const positional = ((args._ as string[]) ?? []).slice(1);
     const longTermAction = action === 'long-term'
-      ? (positional[0] || (args.action as string | undefined) || 'list').trim().toLowerCase()
+      ? (positional[0] || asStringArg(args.action) || 'list').trim().toLowerCase()
       : undefined;
     const asJson = !!args.json;
 
@@ -107,7 +109,7 @@ export default defineCommand({
             query,
             limit: parsePositiveInt(args.graphLimit as string | undefined, 5),
           });
-          const format = (args.format as string | undefined)?.trim().toLowerCase();
+          const format = asStringArg(args.format)?.toLowerCase();
           const formatted = format === 'prompt'
             ? formatGraphContextPrompt(packet)
             : [
@@ -146,10 +148,10 @@ export default defineCommand({
             emitError('text is required for "memorix memory store"', asJson);
             return;
           }
-          const title = (args.title as string | undefined)?.trim() || narrative.slice(0, 80);
+          const title = asStringArg(args.title) || narrative.slice(0, 80);
           const type = coerceObservationType(args.type as string | undefined);
           const topicKey =
-            (args.topicKey as string | undefined)?.trim() ||
+            asStringArg(args.topicKey) ||
             suggestTopicKey(type, title) ||
             undefined;
           const writeScope = resolveCliWriteScope(
@@ -157,7 +159,7 @@ export default defineCommand({
             args.visibility as string | undefined,
           );
           const result = await storeObservation({
-            entityName: (args.entity as string | undefined)?.trim() || 'general',
+            entityName: asStringArg(args.entity) || 'general',
             type,
             title,
             narrative,
@@ -179,7 +181,7 @@ export default defineCommand({
 
         case 'suggest-topic-key': {
           const type = coerceObservationType(args.type as string | undefined);
-          const title = (args.title as string | undefined)?.trim();
+          const title = asStringArg(args.title);
           if (!title) {
             emitError('title is required for "memorix memory suggest-topic-key"', asJson);
             return;
@@ -274,7 +276,7 @@ export default defineCommand({
         }
 
         case 'deduplicate': {
-          const query = (args.query as string | undefined)?.trim();
+          const query = asStringArg(args.query);
           const dryRun = !!args.dryRun || !!args['dry-run'];
           const { isLLMEnabled } = await import('../../llm/provider.js');
           if (!isLLMEnabled()) {
@@ -479,8 +481,8 @@ export default defineCommand({
           };
 
           const memoryId = (): string => {
-            const id = (args.id as string | undefined)?.trim()
-              || (args.fromObservation as string | undefined)?.trim()
+            const id = asStringArg(args.id)
+              || asStringArg(args.fromObservation)
               || longTermPositional[0]?.trim();
             if (!id) throw new Error('long-term memory id is required.');
             return id;
@@ -535,11 +537,11 @@ export default defineCommand({
                 projectId: project.id,
                 scope: scope(),
                 kind: kind(),
-                title: (args.title as string | undefined)?.trim() || content.slice(0, 100),
+                title: asStringArg(args.title) || content.slice(0, 100),
                 content,
                 facts: parseCsvList(args.facts as string | undefined),
                 tags: parseCsvList(args.tags as string | undefined),
-                applicability: (args.applicability as string | undefined)?.trim(),
+                applicability: asStringArg(args.applicability),
                 portability: portability(),
                 reader: longTermReader,
               });
@@ -552,8 +554,8 @@ export default defineCommand({
             }
 
             case 'promote': {
-              const rawId = (args.fromObservation as string | undefined)?.trim()
-                || (args.id as string | undefined)?.trim()
+              const rawId = asStringArg(args.fromObservation)
+                || asStringArg(args.id)
                 || longTermPositional[0]?.trim();
               const observationId = Number.parseInt(rawId || '', 10);
               if (!Number.isFinite(observationId)) {
@@ -571,7 +573,7 @@ export default defineCommand({
                 scope: scope(),
                 kind: kind(),
                 tags: parseCsvList(args.tags as string | undefined),
-                applicability: (args.applicability as string | undefined)?.trim(),
+                applicability: asStringArg(args.applicability),
                 reader: longTermReader,
               });
               emitResult(
@@ -604,8 +606,8 @@ export default defineCommand({
             }
 
             case 'supersede': {
-              const supersededBy = (args.supersededBy as string | undefined)?.trim()
-                || (args['superseded-by'] as string | undefined)?.trim();
+              const supersededBy = asStringArg(args.supersededBy)
+                || asStringArg(args['superseded-by']);
               if (!supersededBy) {
                 emitError('supersededBy is required for "memorix memory long-term supersede"', asJson);
                 return;
@@ -642,31 +644,39 @@ export default defineCommand({
   },
 });
 
-function getStringArg(named: string | undefined, positional: string[]): string | undefined {
-  const value = named?.trim() || positional.join(' ').trim();
+/**
+ * Read a free-text citty named argument with positional fallback.
+ *
+ * Named values may be arrays: citty accumulates repeated flags and Windows
+ * shells can split one long quoted argument into argv fragments that
+ * re-introduce the flag mid-value (issue #194). Joining array fragments
+ * preserves the original text instead of throwing on `.trim()`.
+ */
+function getStringArg(named: unknown, positional: string[]): string | undefined {
+  const value = asStringArg(named) || positional.join(' ').trim();
   return value || undefined;
 }
 
 function getIdArg(args: Record<string, unknown>, positional: string[]): string {
   return (
-    (args.ids as string | undefined) ||
-    (args.id as string | undefined) ||
+    lastStringArg(args.ids) ||
+    lastStringArg(args.id) ||
     positional.join(',')
   );
 }
 
-function parseObservationId(value: string): number {
-  const normalized = value.trim();
+function parseObservationId(value: unknown): number {
+  const normalized = (asStringArg(value) ?? '').trim();
   if (!/^[1-9]\d*$/.test(normalized)) {
-    throw new Error(`Invalid observation ID: ${value}`);
+    throw new Error(`Invalid observation ID: ${String(value ?? '')}`);
   }
   const id = Number(normalized);
-  if (!Number.isSafeInteger(id)) throw new Error(`Invalid observation ID: ${value}`);
+  if (!Number.isSafeInteger(id)) throw new Error(`Invalid observation ID: ${String(value ?? '')}`);
   return id;
 }
 
-function parseObservationIds(value: string): number[] {
-  const values = parseCsvList(value);
+function parseObservationIds(value: unknown): number[] {
+  const values = parseCsvList(typeof value === 'string' || Array.isArray(value) ? value : undefined);
   if (values.length === 0) return [];
   return values.map(parseObservationId);
 }
@@ -695,26 +705,26 @@ function printMemoryUsage(): void {
   console.log('  memorix memory long-term supersede --id <old-id> --superseded-by <qualified-id> --reason "replaced"');
 }
 
-function longTermKind(value: string | undefined): 'episodic' | 'semantic' | 'procedural' {
-  const normalized = (value ?? 'semantic').trim().toLowerCase();
+function longTermKind(value: unknown): 'episodic' | 'semantic' | 'procedural' {
+  const normalized = (asStringArg(value) ?? 'semantic').toLowerCase();
   if (normalized === 'episodic' || normalized === 'semantic' || normalized === 'procedural') return normalized;
   throw new Error('long-term kind must be episodic, semantic, or procedural.');
 }
 
-function longTermScope(value: string | undefined): 'project' | 'user' | 'team' {
-  const normalized = (value ?? 'project').trim().toLowerCase();
+function longTermScope(value: unknown): 'project' | 'user' | 'team' {
+  const normalized = (asStringArg(value) ?? 'project').toLowerCase();
   if (normalized === 'project' || normalized === 'user' || normalized === 'team') return normalized;
   throw new Error('long-term scope must be project, user, or team.');
 }
 
-function longTermPortability(value: string | undefined): 'project-bound' | 'portable' {
-  const normalized = (value ?? 'project-bound').trim().toLowerCase();
+function longTermPortability(value: unknown): 'project-bound' | 'portable' {
+  const normalized = (asStringArg(value) ?? 'project-bound').toLowerCase();
   if (normalized === 'project-bound' || normalized === 'portable') return normalized;
   throw new Error('long-term portability must be project-bound or portable.');
 }
 
-function requiredLongTermReason(value: string | undefined): string {
-  const reason = value?.trim();
+function requiredLongTermReason(value: unknown): string {
+  const reason = asStringArg(value);
   if (!reason) throw new Error('reason is required for this long-term memory transition.');
   return reason;
 }