memorix 1.2.1 → 1.2.3

package/src/cli/commands/transfer.ts

@@ -1,7 +1,41 @@
 import { defineCommand } from 'citty';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
 import { exportAsJson, exportAsMarkdown, importFromJson } from '../../memory/export-import.js';
 import { emitError, emitResult, getCliProjectContext } from './operator-shared.js';
 
+async function readStandardInput(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let content = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      content += chunk;
+    });
+    process.stdin.on('end', () => resolve(content));
+    process.stdin.on('error', reject);
+  });
+}
+
+async function readImportPayload(args: Record<string, unknown>, projectRoot: string): Promise<string> {
+  const data = typeof args.data === 'string' ? args.data.trim() : '';
+  const file = typeof args.file === 'string' ? args.file.trim() : '';
+  const readFromStdin = args.stdin === true || data === '-';
+  const sources = Number(Boolean(data && data !== '-')) + Number(Boolean(file)) + Number(readFromStdin);
+  if (sources !== 1) {
+    throw new Error('Choose exactly one import source: --data <json>, --file <path>, or --stdin.');
+  }
+  if (readFromStdin) return readStandardInput();
+  if (file) return fs.readFile(path.resolve(projectRoot, file), 'utf8');
+  return data;
+}
+
+async function writeExportPayload(projectRoot: string, output: string, payload: string): Promise<string> {
+  const outputPath = path.resolve(projectRoot, output);
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, payload, 'utf8');
+  return outputPath;
+}
+
 export default defineCommand({
   meta: {
     name: 'transfer',
@@ -10,6 +44,9 @@ export default defineCommand({
   args: {
     format: { type: 'string', description: 'Export format: json or markdown' },
     data: { type: 'string', description: 'JSON payload from a previous export' },
+    file: { type: 'string', description: 'File containing a JSON payload to import' },
+    stdin: { type: 'boolean', description: 'Read a JSON import payload from standard input' },
+    out: { type: 'string', description: 'Write the export payload to this file instead of stdout' },
     json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
   },
   run: async ({ args }) => {
@@ -17,31 +54,45 @@ export default defineCommand({
     const asJson = !!args.json;
 
     try {
-      const { project, dataDir } = await getCliProjectContext();
+      const { project, dataDir, reader } = await getCliProjectContext();
 
       switch (action) {
         case 'export': {
           const format = (args.format as string | undefined) === 'markdown' ? 'markdown' : 'json';
           if (format === 'markdown') {
-            const markdown = await exportAsMarkdown(dataDir, project.id);
+            const markdown = await exportAsMarkdown(dataDir, project.id, reader);
+            const output = (args.out as string | undefined)?.trim();
+            if (output) {
+              const outputPath = await writeExportPayload(project.rootPath, output, markdown);
+              emitResult({ project, format, outputPath }, `Export written: ${outputPath}`, asJson);
+              return;
+            }
             emitResult({ project, format, markdown }, markdown, asJson);
             return;
           }
-          const exported = await exportAsJson(dataDir, project.id);
+          const exported = await exportAsJson(dataDir, project.id, reader);
+          const serialized = JSON.stringify(exported, null, 2);
+          const output = (args.out as string | undefined)?.trim();
+          if (output) {
+            const outputPath = await writeExportPayload(project.rootPath, output, `${serialized}\n`);
+            emitResult(
+              { project, format, outputPath, stats: exported.stats },
+              `Export written: ${outputPath}`,
+              asJson,
+            );
+            return;
+          }
           emitResult(
             { project, format, export: exported },
-            JSON.stringify(exported, null, 2),
+            serialized,
             asJson,
           );
           return;
         }
 
         case 'import': {
-          const raw = (args.data as string | undefined)?.trim();
-          if (!raw) {
-            emitError('data is required for "memorix transfer import"', asJson);
-            return;
-          }
+          const raw = (await readImportPayload(args as Record<string, unknown>, project.rootPath)).trim();
+          if (!raw) throw new Error('Import payload is empty.');
           let parsed: Parameters<typeof importFromJson>[1];
           try {
             parsed = JSON.parse(raw);
@@ -62,7 +113,9 @@ export default defineCommand({
           console.log('Memorix Transfer Commands');
           console.log('');
           console.log('Usage:');
-          console.log('  memorix transfer export [--format json|markdown]');
+          console.log('  memorix transfer export [--format json|markdown] [--out ./.memorix-export.json]');
+          console.log('  memorix transfer import --file ./.memorix-export.json');
+          console.log('  memorix transfer import --stdin');
           console.log('  memorix transfer import --data "<json>"');
       }
     } catch (error) {

package/src/cli/identity.ts

@@ -0,0 +1,89 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import type { ObservationReader, ProjectInfo } from '../types.js';
+import type { TeamStore } from '../team/team-store.js';
+
+export interface CliIdentity {
+  agentId: string;
+  projectId: string;
+  activatedAt: string;
+}
+
+export interface CliIdentityResolution {
+  identity: CliIdentity | null;
+  reader: ObservationReader;
+  warning?: string;
+}
+
+function identityPath(dataDir: string): string {
+  return path.join(dataDir, 'cli-identity.json');
+}
+
+function isCliIdentity(value: unknown): value is CliIdentity {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Partial<CliIdentity>;
+  return typeof candidate.agentId === 'string'
+    && typeof candidate.projectId === 'string'
+    && typeof candidate.activatedAt === 'string';
+}
+
+export async function loadCliIdentity(dataDir: string, projectId: string): Promise<CliIdentity | null> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(identityPath(dataDir), 'utf8'));
+    return isCliIdentity(parsed) && parsed.projectId === projectId ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function saveCliIdentity(dataDir: string, identity: CliIdentity): Promise<void> {
+  await fs.writeFile(identityPath(dataDir), `${JSON.stringify(identity, null, 2)}\n`, 'utf8');
+}
+
+export async function clearCliIdentity(dataDir: string): Promise<void> {
+  await fs.rm(identityPath(dataDir), { force: true });
+}
+
+/**
+ * An unbound terminal remains project-scoped. Private and team access becomes
+ * available only after the operator explicitly chooses an active team identity.
+ */
+export async function resolveCliIdentity(options: {
+  project: ProjectInfo;
+  dataDir: string;
+  teamStore: TeamStore;
+  explicitActorId?: string;
+}): Promise<CliIdentityResolution> {
+  const stored = await loadCliIdentity(options.dataDir, options.project.id);
+  const requestedAgentId = options.explicitActorId ?? stored?.agentId;
+  const projectReader: ObservationReader = { projectId: options.project.id };
+  if (!requestedAgentId) return { identity: null, reader: projectReader };
+
+  const agent = options.teamStore.getAgent(requestedAgentId);
+  const activeForProject = agent
+    && agent.project_id === options.project.id
+    && agent.status === 'active';
+  if (!activeForProject) {
+    if (options.explicitActorId) {
+      throw new Error(`CLI actor "${requestedAgentId}" is not an active member of this project.`);
+    }
+    return {
+      identity: null,
+      reader: projectReader,
+      warning: `Saved CLI identity "${requestedAgentId}" is no longer active for this project.`,
+    };
+  }
+
+  return {
+    identity: stored ?? {
+      agentId: agent.agent_id,
+      projectId: options.project.id,
+      activatedAt: new Date().toISOString(),
+    },
+    reader: {
+      projectId: options.project.id,
+      agentId: agent.agent_id,
+      isTeamMember: true,
+    },
+  };
+}

package/src/cli/index.ts

@@ -19,6 +19,8 @@ import { execSync, spawn } from 'node:child_process';
 import { getCliVersion } from './version.js';
 import { importBundledMemcode } from './memcode-bootstrap.js';
 import { installCliPipeErrorGuard } from './pipe-errors.js';
+import { normalizeCliInvocation } from './invocation.js';
+import { printCliGuideForHelp, renderCliGuide } from './command-guide.js';
 
 installCliPipeErrorGuard();
 
@@ -129,8 +131,9 @@ async function getWorkbenchHeader(): Promise<string[]> {
         const dataDir = await getProjectDataDir(proj.id);
         await initStore(dataDir);
         const { getObservationStore: getStore } = await import('../store/obs-store.js');
-        const obs = await getStore().loadAll() as any[];
-        const active = obs.filter((o: any) => (o.status ?? 'active') === 'active').length;
+        const { filterReadableObservations } = await import('../memory/visibility.js');
+        const obs = filterReadableObservations(await getStore().loadAll(), { projectId: proj.id });
+        const active = obs.filter((o) => (o.status ?? 'active') === 'active').length;
         if (active > 0) {
           memLabel = `${BOLD}${active}${RESET} ${DIM}active${RESET}`;
         }
@@ -801,6 +804,7 @@ async function runSearch(query: string): Promise<void> {
   
   try {
     const { searchObservations, getDb, hydrateIndex } = await import('../store/orama-store.js');
+    const { filterReadableObservations } = await import('../memory/visibility.js');
     const { getProjectDataDir } = await import('../store/persistence.js');
     const { detectProject } = await import('../project/detector.js');
     const { initObservations } = await import('../memory/observations.js');
@@ -825,7 +829,7 @@ async function runSearch(query: string): Promise<void> {
     await hydrateIndex(allObs);
     mark('hydrateIndex');
     
-    const results = await searchObservations({ query, limit: 10, projectId: project.id });
+    const results = await searchObservations({ query, limit: 10, projectId: project.id, reader: { projectId: project.id } });
     mark('search');
     s.stop('Search complete');
     
@@ -855,14 +859,16 @@ async function runList(): Promise<void> {
     const { getProjectDataDir } = await import('../store/persistence.js');
     const { detectProject } = await import('../project/detector.js');
     const { initObservationStore: initStore, getObservationStore: getStore } = await import('../store/obs-store.js');
+    const { filterReadableObservations } = await import('../memory/visibility.js');
     
     const project = detectProject(process.cwd());
     if (!project) { s.stop('No git repo'); p.log.error(NO_GIT_MSG); return; }
     const dataDir = await getProjectDataDir(project.id);
     await initStore(dataDir);
-    const observations = await getStore().loadAll() as unknown as Array<{
-      id: number; title: string; type: string; timestamp: string; status?: string;
-    }>;
+    const observations = filterReadableObservations(
+      await getStore().loadAll(),
+      { projectId: project.id },
+    );
     
     const active = observations.filter(o => (o.status ?? 'active') === 'active');
     const recent = active.slice(-10).reverse();
@@ -876,7 +882,7 @@ async function runList(): Promise<void> {
     
     console.log('');
     for (const o of recent) {
-      const typeLabel = { gotcha: '[!]', decision: '[D]', 'problem-solution': '[S]', discovery: '[?]', 'how-it-works': '[H]', 'what-changed': '[C]' }[o.type] ?? '[·]';
+      const typeLabel = ({ gotcha: '[!]', decision: '[D]', 'problem-solution': '[S]', discovery: '[?]', 'how-it-works': '[H]', 'what-changed': '[C]' } as Record<string, string>)[o.type] ?? '[·]';
       console.log(`  ${typeLabel} #${o.id} ${o.title?.slice(0, 60) ?? '(untitled)'}`);
     }
     console.log('');
@@ -927,11 +933,26 @@ async function runCommand(cmd: string, _args: string[] = []): Promise<void> {
 // Main command
 // ============================================================
 
+async function runMemoryShortcut(action: string, args: Record<string, unknown>): Promise<void> {
+  const { detectProject } = await import('../project/detector.js');
+  if (!detectProject(process.cwd())) {
+    console.log(NO_GIT_MSG);
+    process.exitCode = 1;
+    return;
+  }
+  const memory = await import('./commands/memory.js');
+  await memory.default.run?.({
+    args: { ...args, _: [action] },
+    rawArgs: [],
+    cmd: memory.default,
+  } as any);
+}
+
 const main = defineCommand({
   meta: {
     name: 'memorix',
     version: getCliVersion(),
-    description: 'Local-first memory control plane for AI coding agents via MCP',
+    description: 'Local-first memory control plane for AI coding agents through CLI, MCP, and local workflows',
   },
   subCommands: {
     // One-shot product commands (primary user paths)
@@ -960,18 +981,55 @@ const main = defineCommand({
       },
     })),
     search: () => Promise.resolve(defineCommand({
-      meta: { name: 'search', description: 'Search memories' },
-      args: { query: { type: 'positional', description: 'Search query', required: true } },
-      async run({ args }) { await runSearch(args.query as string); },
+      meta: { name: 'search', description: 'Shortcut for `memorix memory search`' },
+      args: {
+        query: { type: 'positional', description: 'Search query', required: true },
+        limit: { type: 'string', description: 'Maximum results' },
+        json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+      },
+      async run({ args }) {
+        await runMemoryShortcut('search', {
+          query: args.query,
+          limit: args.limit,
+          json: args.json,
+        });
+      },
     })),
     remember: () => Promise.resolve(defineCommand({
-      meta: { name: 'remember', description: 'Store a quick memory' },
-      args: { text: { type: 'positional', description: 'Text to remember', required: true } },
-      async run({ args }) { await runRemember(args.text as string); },
+      meta: { name: 'remember', description: 'Shortcut for `memorix memory store`' },
+      args: {
+        text: { type: 'positional', description: 'Text to remember', required: true },
+        title: { type: 'string', description: 'Optional observation title' },
+        type: { type: 'string', description: 'Observation type' },
+        visibility: { type: 'string', description: 'project (default), personal, or team' },
+        json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+      },
+      async run({ args }) {
+        await runMemoryShortcut('store', {
+          text: args.text,
+          title: args.title,
+          type: args.type,
+          visibility: args.visibility,
+          json: args.json,
+        });
+      },
     })),
     recent: () => Promise.resolve(defineCommand({
-      meta: { name: 'recent', description: 'View recent memories' },
-      async run() { await runList(); },
+      meta: { name: 'recent', description: 'Shortcut for `memorix memory recent`' },
+      args: {
+        limit: { type: 'string', description: 'Maximum results' },
+        json: { type: 'boolean', description: 'Emit machine-readable JSON output' },
+      },
+      async run({ args }) { await runMemoryShortcut('recent', { limit: args.limit, json: args.json }); },
+    })),
+    help: () => Promise.resolve(defineCommand({
+      meta: { name: 'help', description: 'Show action-oriented help for a command group' },
+      args: {
+        command: { type: 'positional', description: 'Command group to inspect', required: false },
+      },
+      async run({ args }) {
+        console.log(renderCliGuide(args.command as string | undefined));
+      },
     })),
     // Infrastructure commands
     init: () => import('./commands/init.js').then(m => m.default),
@@ -996,6 +1054,7 @@ const main = defineCommand({
     audit: () => import('./commands/audit.js').then(m => m.default),
     transfer: () => import('./commands/transfer.js').then(m => m.default),
     skills: () => import('./commands/skills.js').then(m => m.default),
+    identity: () => import('./commands/identity.js').then(m => m.default),
     session: () => import('./commands/session.js').then(m => m.default),
     team: () => import('./commands/team.js').then(m => m.default),
     task: () => import('./commands/task.js').then(m => m.default),
@@ -1031,6 +1090,13 @@ const main = defineCommand({
     cleanup: () => import('./commands/cleanup.js').then(m => m.default),
     uninstall: () => import('./commands/uninstall.js').then(m => m.default),
     orchestrate: () => import('./commands/orchestrate.js').then(m => m.default),
+    workbench: () => Promise.resolve(defineCommand({
+      meta: { name: 'workbench', description: 'Open the interactive terminal memory control plane' },
+      async run() {
+        const { startWorkbench } = await import('./workbench.js');
+        await startWorkbench();
+      },
+    })),
     memcode: () => Promise.resolve(defineCommand({
       meta: { name: 'memcode', description: 'Enter memcode TUI — native coding agent with memory' },
       async run() {
@@ -1048,8 +1114,8 @@ const main = defineCommand({
     // Guard: if citty already resolved a subcommand, its run() was called before this.
     // 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', 'knowledge', 'reasoning', 'retention', 'formation', 'audit', 'transfer', 'skills',
+    const knownSubs = ['ask', 'search', 'remember', 'recent', 'help', 'workbench', 'memcode', 'config',
+      'init', 'setup', 'integrate', 'memory', 'context', 'explain', 'codegraph', 'knowledge', 'reasoning', 'retention', 'formation', 'audit', 'transfer', 'skills', 'identity',
       'session', 'team', 'task', 'message', 'lock', 'handoff', 'poll',
       'receipt',
       'serve', 'serve-http', 'status', 'sync',
@@ -1080,6 +1146,8 @@ const main = defineCommand({
       console.error(`Memorix v${getCliVersion()} — Local-first memory control plane\n`);
       console.error('Usage: memorix <command>\n');
       console.error('Commands:');
+      console.error('  help       Show action-oriented help (`memorix memory --help`)');
+      console.error('  workbench  Open interactive terminal memory control plane');
       console.error('  memcode    Enter memcode TUI (native coding agent)');
       console.error('  ask "q"    Ask Memorix a question (single-shot chat)');
       console.error('             Pipe: echo "q" | memorix ask');
@@ -1096,6 +1164,7 @@ const main = defineCommand({
       console.error('  audit      Audit trail and project attribution checks');
       console.error('  transfer   Export/import memory snapshots');
       console.error('  skills     List/generate/show project skills');
+      console.error('  identity   Select the explicit CLI actor for private/team memory');
       console.error('  team       Join/status/role operations for coordination state');
       console.error('  task       Create/claim/complete/list team tasks');
       console.error('  message    Send/broadcast/read team messages');
@@ -1121,4 +1190,12 @@ const main = defineCommand({
   },
 });
 
-runMain(main);
+try {
+  normalizeCliInvocation();
+  if (!printCliGuideForHelp()) {
+    runMain(main);
+  }
+} catch (error) {
+  console.error(`Memorix CLI invocation error: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/src/cli/invocation.ts

@@ -0,0 +1,115 @@
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export interface CliInvocation {
+  projectRoot?: string;
+  actorId?: string;
+}
+
+type InvocationOption = 'projectRoot' | 'actorId';
+
+const GLOBAL_OPTIONS: Record<string, InvocationOption> = {
+  '--cwd': 'projectRoot',
+  '--project-root': 'projectRoot',
+  '--as': 'actorId',
+  '--actor': 'actorId',
+};
+
+// Existing commands use camelCase Citty keys. Preserve them for compatibility
+// while accepting the shell-native kebab-case spelling everywhere.
+const FLAG_ALIASES: Record<string, string> = {
+  '--agent-type': '--agentType',
+  '--instance-id': '--instanceId',
+  '--agent-id': '--agentId',
+  '--from-agent-id': '--fromAgentId',
+  '--to-agent-id': '--toAgentId',
+  '--join-team': '--joinTeam',
+  '--session-id': '--sessionId',
+  '--task-id': '--taskId',
+  '--topic-key': '--topicKey',
+  '--graph-limit': '--graphLimit',
+  '--graph-query': '--graphQuery',
+  '--skill-id': '--skillId',
+  '--required-role': '--requiredRole',
+  '--preferred-role': '--preferredRole',
+  '--to-role': '--toRole',
+  '--handoff-status': '--handoffStatus',
+  '--max-concurrent': '--maxConcurrent',
+  '--role-id': '--roleId',
+  '--preferred-agent-types': '--preferredAgentTypes',
+  '--files-modified': '--filesModified',
+  '--expected-outcome': '--expectedOutcome',
+  '--related-commits': '--relatedCommits',
+  '--related-entities': '--relatedEntities',
+  '--mime-type': '--mimeType',
+  '--mark-read': '--markRead',
+  '--mark-inbox-read': '--markInboxRead',
+};
+
+function readOption(argument: string): { name: string; value?: string } {
+  const equals = argument.indexOf('=');
+  return equals === -1
+    ? { name: argument }
+    : { name: argument.slice(0, equals), value: argument.slice(equals + 1) };
+}
+
+/**
+ * Normalize the small set of global operator flags before Citty resolves a
+ * command. This gives every CLI command the same project and actor anchors
+ * without duplicating those flags across dozens of command definitions.
+ */
+export function normalizeCliInvocation(argv: string[] = process.argv): CliInvocation {
+  const normalized = argv.slice(0, 2);
+  const invocation: CliInvocation = {};
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === '--') {
+      normalized.push(...argv.slice(index));
+      break;
+    }
+
+    const { name, value: inlineValue } = readOption(argument);
+    const target = GLOBAL_OPTIONS[name];
+    if (!target) {
+      const alias = FLAG_ALIASES[name];
+      normalized.push(alias
+        ? (inlineValue === undefined ? alias : `${alias}=${inlineValue}`)
+        : argument);
+      continue;
+    }
+
+    const value = inlineValue ?? argv[index + 1];
+    if (!value || value.startsWith('--')) {
+      throw new Error(`${name} requires a value`);
+    }
+    invocation[target] = value;
+    if (inlineValue === undefined) index += 1;
+  }
+
+  if (invocation.projectRoot) {
+    const projectRoot = resolve(invocation.projectRoot);
+    if (!existsSync(projectRoot) || !statSync(projectRoot).isDirectory()) {
+      throw new Error(`CLI project directory does not exist: ${projectRoot}`);
+    }
+    process.chdir(projectRoot);
+    process.env.MEMORIX_CLI_PROJECT_ROOT = projectRoot;
+    invocation.projectRoot = projectRoot;
+  }
+
+  if (invocation.actorId) {
+    process.env.MEMORIX_CLI_ACTOR_ID = invocation.actorId;
+  }
+
+  process.argv = normalized;
+  return invocation;
+}
+
+export function getCliInvocation(): CliInvocation {
+  const projectRoot = process.env.MEMORIX_CLI_PROJECT_ROOT?.trim();
+  const actorId = process.env.MEMORIX_CLI_ACTOR_ID?.trim();
+  return {
+    ...(projectRoot ? { projectRoot } : {}),
+    ...(actorId ? { actorId } : {}),
+  };
+}