claude-memory-layer 1.0.26 → 1.0.28

package/src/apps/cli/codex-import-runner.ts

@@ -0,0 +1,125 @@
+import {
+  createCodexSessionHistoryImporter,
+  type CodexSessionHistoryImporter,
+  type CodexSessionHistoryImporterOptions
+} from '../../services/codex-session-history-importer.js';
+import {
+  getDefaultMemoryService,
+  getMemoryServiceForProject,
+  type MemoryService
+} from '../../services/memory-service.js';
+import type { ImportOptions, ImportResult, ProgressEvent } from '../../services/session-history-importer.js';
+
+export interface CodexImportCommandOptions {
+  project?: string;
+  session?: string;
+  all?: boolean;
+  limit?: string;
+  sessionLimit?: string;
+  force?: boolean;
+  verbose?: boolean;
+  sessionsDir?: string;
+  processEmbeddings?: boolean;
+}
+
+export interface CodexImportOutcome {
+  mode: 'project' | 'session' | 'all';
+  storageScope: 'project' | 'global';
+  projectPath?: string;
+  result: ImportResult;
+  embedCount: number;
+}
+
+export interface CodexImportRunnerDeps {
+  cwd: () => string;
+  getDefaultMemoryService: () => MemoryService;
+  getMemoryServiceForProject: (projectPath: string) => MemoryService;
+  createImporter: (
+    memoryService: MemoryService,
+    options?: CodexSessionHistoryImporterOptions
+  ) => Pick<CodexSessionHistoryImporter, 'importProject' | 'importAll' | 'importSessionFile'>;
+  onProgress?: (event: ProgressEvent) => void;
+}
+
+const realDeps: CodexImportRunnerDeps = {
+  cwd: () => process.cwd(),
+  getDefaultMemoryService,
+  getMemoryServiceForProject,
+  createImporter: createCodexSessionHistoryImporter
+};
+
+function parsePositiveInteger(value: string | undefined, name: string): number | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new Error(`Invalid --${name}: expected a positive integer`);
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${name}: expected a positive integer`);
+  }
+  return parsed;
+}
+
+function shouldUseGlobalStorage(options: CodexImportCommandOptions): boolean {
+  return options.all === true && !options.project && !options.session;
+}
+
+export async function runCodexImportOnce(
+  options: CodexImportCommandOptions,
+  deps: CodexImportRunnerDeps = realDeps
+): Promise<CodexImportOutcome> {
+  const targetProjectPath = options.project || deps.cwd();
+  const useGlobalStorage = shouldUseGlobalStorage(options);
+  const memoryService = useGlobalStorage
+    ? deps.getDefaultMemoryService()
+    : deps.getMemoryServiceForProject(targetProjectPath);
+  const importer = deps.createImporter(memoryService, { sessionsDir: options.sessionsDir });
+
+  await memoryService.initialize();
+  await memoryService.ensureEmbeddingModelForImport({ autoMigrate: true });
+
+  const importOptions: ImportOptions = {
+    limit: parsePositiveInteger(options.limit, 'limit'),
+    sessionLimit: parsePositiveInteger(options.sessionLimit, 'session-limit'),
+    force: options.force,
+    verbose: options.verbose,
+    onProgress: deps.onProgress
+  };
+
+  let mode: CodexImportOutcome['mode'];
+  let result: ImportResult;
+
+  try {
+    if (options.session) {
+      mode = 'session';
+      result = await importer.importSessionFile(options.session, {
+        ...importOptions,
+        projectPath: targetProjectPath
+      });
+    } else if (options.all) {
+      mode = 'all';
+      result = await importer.importAll(importOptions);
+    } else {
+      mode = 'project';
+      result = await importer.importProject(targetProjectPath, {
+        ...importOptions,
+        projectPath: targetProjectPath
+      });
+    }
+
+    const embedCount = options.processEmbeddings === false
+      ? 0
+      : await memoryService.processPendingEmbeddings();
+
+    return {
+      mode,
+      storageScope: useGlobalStorage ? 'global' : 'project',
+      projectPath: useGlobalStorage ? undefined : targetProjectPath,
+      result,
+      embedCount
+    };
+  } finally {
+    await memoryService.shutdown();
+  }
+}

package/src/apps/cli/codex-validation-output.ts

@@ -0,0 +1,95 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { CodexSessionValidationReport } from '../../services/codex-session-history-importer.js';
+
+export type CodexValidationReportFormat = 'json' | 'markdown';
+
+function formatNumber(value: number): string {
+  return Number.isFinite(value) ? value.toLocaleString('en-US') : String(value);
+}
+
+export function formatCodexValidationReport(
+  report: CodexSessionValidationReport,
+  format: CodexValidationReportFormat = 'markdown'
+): string {
+  if (format === 'json') {
+    return `${JSON.stringify(report, null, 2)}\n`;
+  }
+
+  const lines: string[] = [
+    '# Codex dry-run validation report',
+    '',
+    `Generated: ${report.generatedAt}`,
+    `Dry-run: ${report.dryRun ? 'yes' : 'no'}`,
+    `Will mutate memory: ${report.willMutate ? 'yes' : 'no'}`,
+    `Sessions directory: ${report.source.sessionsDir}`,
+    `Project filter: ${report.source.projectPath ?? '(none)'}`,
+    `Source paths: ${report.source.sourcePaths.join(', ')}`,
+    `Session limit: ${report.limits.sessionLimit ?? '(none)'}`,
+    `Max content chars: ${formatNumber(report.limits.maxContentChars)}`,
+    '',
+    '## Totals',
+    '',
+    `- Sessions scanned: ${formatNumber(report.totals.sessionsScanned)}`,
+    `- Sessions matched: ${formatNumber(report.totals.sessionsMatched)}`,
+    `- Files read: ${formatNumber(report.totals.filesRead)}`,
+    `- Records read: ${formatNumber(report.totals.recordsRead)}`,
+    `- Messages normalized: ${formatNumber(report.totals.messagesNormalized)}`,
+    `- Turns normalized: ${formatNumber(report.totals.turnsNormalized)}`,
+    `- User messages: ${formatNumber(report.totals.userMessages)}`,
+    `- Assistant messages: ${formatNumber(report.totals.assistantMessages)}`,
+    `- Malformed lines: ${formatNumber(report.totals.malformedLines)}`,
+    `- Skipped/unsupported records: ${formatNumber(report.totals.skippedUnsupportedRecords)}`,
+    `- Empty assistant messages: ${formatNumber(report.totals.emptyAssistantMessages)}`,
+    `- Truncated messages: ${formatNumber(report.totals.truncatedMessages)}`,
+    `- Missing project cwd: ${formatNumber(report.totals.missingProjectCwd)}`,
+    `- Warnings: ${formatNumber(report.totals.warnings)}`,
+    '',
+    '## Top projects',
+    '',
+    '| Project | Hash | Sessions | Messages | Turns | User | Assistant | Malformed | Skipped/unsupported | Truncated | Empty assistant |',
+    '| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |'
+  ];
+
+  if (report.topProjects.length === 0) {
+    lines.push('| (none) | - | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |');
+  } else {
+    for (const project of report.topProjects) {
+      lines.push([
+        `| ${project.pathLabel}`,
+        project.projectHash,
+        formatNumber(project.sessions),
+        formatNumber(project.messagesNormalized),
+        formatNumber(project.turnsNormalized),
+        formatNumber(project.userMessages),
+        formatNumber(project.assistantMessages),
+        formatNumber(project.malformedLines),
+        formatNumber(project.skippedUnsupportedRecords),
+        formatNumber(project.truncatedMessages),
+        `${formatNumber(project.emptyAssistantMessages)} |`
+      ].join(' | '));
+    }
+  }
+
+  lines.push('', '## Warnings', '');
+  if (report.warnings.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const warning of report.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  lines.push('', '_Aggregate counts only; transcript content is not included._', '');
+  return lines.join('\n');
+}
+
+export function writeCodexValidationReport(
+  outputPath: string,
+  report: CodexSessionValidationReport,
+  format: CodexValidationReportFormat = 'markdown'
+): void {
+  const dir = path.dirname(outputPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(outputPath, formatCodexValidationReport(report, format), 'utf8');
+}

package/src/apps/cli/hermes-import-runner.ts

@@ -0,0 +1,130 @@
+import {
+  createHermesSessionHistoryImporter,
+  type HermesSessionHistoryImporter,
+  type HermesSessionHistoryImporterOptions
+} from '../../services/hermes-session-history-importer.js';
+import {
+  getDefaultMemoryService,
+  getMemoryServiceForProject,
+  type MemoryService
+} from '../../services/memory-service.js';
+import type { ImportOptions, ImportResult, ProgressEvent } from '../../services/session-history-importer.js';
+
+export interface HermesImportCommandOptions {
+  project?: string;
+  session?: string;
+  all?: boolean;
+  limit?: string;
+  sessionLimit?: string;
+  force?: boolean;
+  verbose?: boolean;
+  stateDb?: string;
+  stateDbPath?: string;
+  processEmbeddings?: boolean;
+}
+
+export interface HermesImportOutcome {
+  mode: 'project' | 'session' | 'all';
+  storageScope: 'project' | 'global';
+  projectPath?: string;
+  result: ImportResult;
+  embedCount: number;
+}
+
+export interface HermesImportRunnerDeps {
+  cwd: () => string;
+  getDefaultMemoryService: () => MemoryService;
+  getMemoryServiceForProject: (projectPath: string) => MemoryService;
+  createImporter: (
+    memoryService: MemoryService,
+    options?: HermesSessionHistoryImporterOptions
+  ) => Pick<HermesSessionHistoryImporter, 'importProject' | 'importAll' | 'importSession'>;
+  onProgress?: (event: ProgressEvent) => void;
+}
+
+const realDeps: HermesImportRunnerDeps = {
+  cwd: () => process.cwd(),
+  getDefaultMemoryService,
+  getMemoryServiceForProject,
+  createImporter: createHermesSessionHistoryImporter
+};
+
+function parsePositiveInteger(value: string | undefined, name: string): number | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.trim();
+  if (!/^\d+$/.test(normalized)) {
+    throw new Error(`Invalid --${name}: expected a positive integer`);
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid --${name}: expected a positive integer`);
+  }
+  return parsed;
+}
+
+function shouldUseGlobalStorage(options: HermesImportCommandOptions): boolean {
+  return options.all === true && !options.project && !options.session;
+}
+
+function getStateDbPathOption(options: HermesImportCommandOptions): string | undefined {
+  return options.stateDbPath ?? options.stateDb;
+}
+
+export async function runHermesImportOnce(
+  options: HermesImportCommandOptions,
+  deps: HermesImportRunnerDeps = realDeps
+): Promise<HermesImportOutcome> {
+  const targetProjectPath = options.project || deps.cwd();
+  const useGlobalStorage = shouldUseGlobalStorage(options);
+  const memoryService = useGlobalStorage
+    ? deps.getDefaultMemoryService()
+    : deps.getMemoryServiceForProject(targetProjectPath);
+  const importer = deps.createImporter(memoryService, { stateDbPath: getStateDbPathOption(options) });
+
+  await memoryService.initialize();
+  await memoryService.ensureEmbeddingModelForImport({ autoMigrate: true });
+
+  const importOptions: ImportOptions = {
+    limit: parsePositiveInteger(options.limit, 'limit'),
+    sessionLimit: parsePositiveInteger(options.sessionLimit, 'session-limit'),
+    force: options.force,
+    verbose: options.verbose,
+    onProgress: deps.onProgress
+  };
+
+  let mode: HermesImportOutcome['mode'];
+  let result: ImportResult;
+
+  try {
+    if (options.session) {
+      mode = 'session';
+      result = await importer.importSession(options.session, {
+        ...importOptions,
+        projectPath: targetProjectPath
+      });
+    } else if (options.all) {
+      mode = 'all';
+      result = await importer.importAll(importOptions);
+    } else {
+      mode = 'project';
+      result = await importer.importProject(targetProjectPath, {
+        ...importOptions,
+        projectPath: targetProjectPath
+      });
+    }
+
+    const embedCount = options.processEmbeddings === false
+      ? 0
+      : await memoryService.processPendingEmbeddings();
+
+    return {
+      mode,
+      storageScope: useGlobalStorage ? 'global' : 'project',
+      projectPath: useGlobalStorage ? undefined : targetProjectPath,
+      result,
+      embedCount
+    };
+  } finally {
+    await memoryService.shutdown();
+  }
+}

package/src/apps/cli/hermes-validation-output.ts

@@ -0,0 +1,91 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { HermesSessionValidationReport } from '../../services/hermes-session-history-importer.js';
+
+export type HermesValidationReportFormat = 'json' | 'markdown';
+
+function formatNumber(value: number): string {
+  return Number.isFinite(value) ? value.toLocaleString('en-US') : String(value);
+}
+
+export function formatHermesValidationReport(
+  report: HermesSessionValidationReport,
+  format: HermesValidationReportFormat = 'markdown'
+): string {
+  if (format === 'json') {
+    return `${JSON.stringify(report, null, 2)}\n`;
+  }
+
+  const lines: string[] = [
+    '# Hermes dry-run validation report',
+    '',
+    `Generated: ${report.generatedAt}`,
+    `Dry-run: ${report.dryRun ? 'yes' : 'no'}`,
+    `Will mutate memory: ${report.willMutate ? 'yes' : 'no'}`,
+    `State DB: ${report.source.stateDbPath}`,
+    `Project filter: ${report.source.projectPath ?? '(none)'}`,
+    `Source paths: ${report.source.sourcePaths.join(', ')}`,
+    `Session limit: ${report.limits.sessionLimit ?? '(none)'}`,
+    `Max content chars: ${formatNumber(report.limits.maxContentChars)}`,
+    '',
+    '## Totals',
+    '',
+    `- Sessions scanned: ${formatNumber(report.totals.sessionsScanned)}`,
+    `- Sessions matched: ${formatNumber(report.totals.sessionsMatched)}`,
+    `- Messages read: ${formatNumber(report.totals.messagesRead)}`,
+    `- Messages normalized: ${formatNumber(report.totals.messagesNormalized)}`,
+    `- Turns normalized: ${formatNumber(report.totals.turnsNormalized)}`,
+    `- User messages: ${formatNumber(report.totals.userMessages)}`,
+    `- Assistant messages: ${formatNumber(report.totals.assistantMessages)}`,
+    `- Skipped/unsupported messages: ${formatNumber(report.totals.skippedUnsupportedMessages)}`,
+    `- Empty assistant messages: ${formatNumber(report.totals.emptyAssistantMessages)}`,
+    `- Truncated messages: ${formatNumber(report.totals.truncatedMessages)}`,
+    `- Missing project context: ${formatNumber(report.totals.missingProjectContext)}`,
+    `- Warnings: ${formatNumber(report.totals.warnings)}`,
+    '',
+    '## Top sources',
+    '',
+    '| Source | Sessions | Messages | Turns | User | Assistant | Skipped/unsupported | Truncated | Empty assistant |',
+    '| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |'
+  ];
+
+  if (report.topSources.length === 0) {
+    lines.push('| (none) | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |');
+  } else {
+    for (const source of report.topSources) {
+      lines.push([
+        `| ${source.source}`,
+        formatNumber(source.sessions),
+        formatNumber(source.messagesNormalized),
+        formatNumber(source.turnsNormalized),
+        formatNumber(source.userMessages),
+        formatNumber(source.assistantMessages),
+        formatNumber(source.skippedUnsupportedMessages),
+        formatNumber(source.truncatedMessages),
+        `${formatNumber(source.emptyAssistantMessages)} |`
+      ].join(' | '));
+    }
+  }
+
+  lines.push('', '## Warnings', '');
+  if (report.warnings.length === 0) {
+    lines.push('- None');
+  } else {
+    for (const warning of report.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  lines.push('', '_Aggregate counts only; transcript content is not included._', '');
+  return lines.join('\n');
+}
+
+export function writeHermesValidationReport(
+  outputPath: string,
+  report: HermesSessionValidationReport,
+  format: HermesValidationReportFormat = 'markdown'
+): void {
+  const dir = path.dirname(outputPath);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(outputPath, formatHermesValidationReport(report, format), 'utf8');
+}