cognitive-core 0.1.0 → 0.2.0

package/references/minimem/src/cli/commands/sync-init.ts

@@ -0,0 +1,290 @@
+/**
+ * minimem sync init - Initialize sync for a memory directory
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  resolveMemoryDir,
+  loadConfig,
+  saveConfig,
+  isInitialized,
+  formatPath,
+  getMachineId,
+  expandPath,
+  getDefaultSyncConfig,
+  exitWithError,
+} from "../config.js";
+import {
+  getCentralRepoPath,
+  initCentralRepo,
+  validateCentralRepo,
+} from "../sync/central.js";
+import {
+  readRegistry,
+  writeRegistry,
+  checkCollision,
+  addMapping,
+} from "../sync/registry.js";
+import { detectDirectoryType } from "../sync/detection.js";
+
+export type SyncInitOptions = {
+  /** Memory directory to initialize sync for */
+  local?: string;
+  /** Path in central repo */
+  path?: string;
+  /** Use global ~/.minimem directory */
+  global?: boolean;
+};
+
+export type SyncInitCentralOptions = {
+  /** Force creation even if directory exists */
+  force?: boolean;
+};
+
+/**
+ * Initialize a central repository
+ */
+export async function syncInitCentral(
+  repoPath: string,
+  options: SyncInitCentralOptions = {}
+): Promise<void> {
+  console.log(`Initializing central repository at ${formatPath(repoPath)}...`);
+
+  const result = await initCentralRepo(repoPath);
+
+  if (!result.success) {
+    exitWithError(result.message);
+  }
+
+  if (result.created) {
+    console.log("  Created new git repository");
+    console.log("  Created .gitignore");
+    console.log("  Created .minimem-registry.json");
+    console.log("  Created README.md");
+  } else {
+    console.log("  Configured existing directory");
+  }
+
+  console.log();
+  console.log("Central repository is ready!");
+  console.log(`Set as centralRepo in ~/.config/minimem/config.json`);
+  console.log();
+  console.log("Next steps:");
+  console.log("  1. Initialize sync for a memory directory:");
+  console.log("     minimem sync init --path myproject/");
+  console.log();
+  console.log("  2. Or from a different directory:");
+  console.log("     minimem sync init --local ~/my-memories --path mymemories/");
+}
+
+/**
+ * Initialize sync for a memory directory
+ */
+export async function syncInit(options: SyncInitOptions): Promise<void> {
+  // Resolve the memory directory
+  const memoryDir = resolveMemoryDir({
+    dir: options.local,
+    global: options.global,
+  });
+
+  // Check if initialized
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(
+      `${formatPath(memoryDir)} is not initialized.`,
+      "Run 'minimem init' first."
+    );
+  }
+
+  // Check if --path is provided
+  if (!options.path) {
+    exitWithError(
+      "--path is required.",
+      "Example: minimem sync init --path myproject/"
+    );
+  }
+
+  const centralPath = options.path;
+
+  // Get central repo
+  const centralRepo = await getCentralRepoPath();
+  if (!centralRepo) {
+    exitWithError(
+      "No central repository configured.",
+      "First initialize a central repository: minimem sync init-central ~/memories-repo"
+    );
+  }
+
+  // Validate central repo
+  const validation = await validateCentralRepo(centralRepo);
+  if (!validation.valid) {
+    exitWithError(
+      `Central repository is invalid: ${validation.errors.join(", ")}`
+    );
+  }
+
+  if (validation.warnings.length > 0) {
+    console.log("Warnings about central repository:");
+    for (const warning of validation.warnings) {
+      console.log(`  - ${warning}`);
+    }
+    console.log();
+  }
+
+  // Get machine ID
+  const machineId = await getMachineId();
+
+  // Check for collisions
+  const registry = await readRegistry(centralRepo);
+  const collisionResult = checkCollision(registry, centralPath, memoryDir, machineId);
+
+  if (collisionResult === "collision") {
+    const existingMapping = registry.mappings.find(
+      (m) => m.path === centralPath || m.path === `${centralPath}/`
+    );
+    let details = `Path '${centralPath}' is already mapped by another machine.`;
+    if (existingMapping) {
+      details += ` Machine: ${existingMapping.machineId}, Local: ${existingMapping.localPath}`;
+    }
+    exitWithError(details, "Choose a different path or remove the existing mapping.");
+  }
+
+  // Detect directory type
+  const dirType = await detectDirectoryType(memoryDir);
+
+  console.log(`Initializing sync for ${formatPath(memoryDir)}...`);
+  console.log(`  Directory type: ${dirType}`);
+  console.log(`  Central path: ${centralPath}`);
+  console.log(`  Machine ID: ${machineId}`);
+  console.log();
+
+  // Update local config
+  const localConfig = await loadConfig(memoryDir);
+  const syncDefaults = getDefaultSyncConfig();
+
+  localConfig.sync = {
+    enabled: true,
+    path: centralPath,
+    include: localConfig.sync?.include ?? syncDefaults.include,
+    exclude: localConfig.sync?.exclude ?? syncDefaults.exclude,
+  };
+
+  await saveConfig(memoryDir, localConfig);
+  console.log("  Updated .minimem/config.json with sync settings");
+
+  // Update registry
+  const updatedRegistry = addMapping(registry, {
+    path: centralPath,
+    localPath: memoryDir,
+    machineId,
+    lastSync: new Date().toISOString(),
+  });
+
+  await writeRegistry(centralRepo, updatedRegistry);
+  console.log("  Registered mapping in central repository");
+
+  // Create central path directory if it doesn't exist
+  const centralDir = path.join(centralRepo, centralPath);
+  try {
+    await fs.mkdir(centralDir, { recursive: true });
+  } catch {
+    // Directory might already exist
+  }
+
+  console.log();
+  console.log("Sync initialized successfully!");
+  console.log();
+  console.log("Next steps:");
+  console.log("  Push local files to central:");
+  console.log("    minimem push");
+  console.log();
+  console.log("  Or pull from central:");
+  console.log("    minimem pull");
+}
+
+/**
+ * List all sync mappings
+ */
+export async function syncList(): Promise<void> {
+  const centralRepo = await getCentralRepoPath();
+
+  if (!centralRepo) {
+    console.log("No central repository configured.");
+    console.log("Run: minimem sync init-central <path>");
+    return;
+  }
+
+  const machineId = await getMachineId();
+  const registry = await readRegistry(centralRepo);
+
+  console.log(`Central Repository: ${formatPath(centralRepo)}`);
+  console.log(`Machine ID: ${machineId}`);
+  console.log();
+
+  if (registry.mappings.length === 0) {
+    console.log("No sync mappings registered.");
+    console.log("Run: minimem sync init --path <name>/");
+    return;
+  }
+
+  console.log("Registered Mappings:");
+  console.log("-".repeat(80));
+
+  for (const mapping of registry.mappings) {
+    const isCurrentMachine = mapping.machineId === machineId;
+    const marker = isCurrentMachine ? " *" : "  ";
+    const lastSync = new Date(mapping.lastSync).toLocaleString();
+
+    console.log(`${marker}Path: ${mapping.path}`);
+    console.log(`    Local: ${mapping.localPath}`);
+    console.log(`    Machine: ${mapping.machineId}`);
+    console.log(`    Last Sync: ${lastSync}`);
+    console.log();
+  }
+
+  console.log("* = this machine");
+}
+
+/**
+ * Remove sync mapping for a directory
+ */
+export async function syncRemove(options: { local?: string; global?: boolean }): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.local,
+    global: options.global,
+  });
+
+  const centralRepo = await getCentralRepoPath();
+  if (!centralRepo) {
+    exitWithError("No central repository configured.");
+  }
+
+  const localConfig = await loadConfig(memoryDir);
+  if (!localConfig.sync?.path) {
+    exitWithError(`${formatPath(memoryDir)} is not configured for sync.`);
+  }
+
+  const centralPath = localConfig.sync.path;
+  const machineId = await getMachineId();
+
+  // Update local config
+  delete localConfig.sync;
+  await saveConfig(memoryDir, localConfig);
+  console.log(`Removed sync config from ${formatPath(memoryDir)}`);
+
+  // Update registry
+  const registry = await readRegistry(centralRepo);
+  const updatedRegistry = {
+    ...registry,
+    mappings: registry.mappings.filter(
+      (m) => !(m.path === centralPath && m.machineId === machineId)
+    ),
+  };
+  await writeRegistry(centralRepo, updatedRegistry);
+  console.log(`Removed mapping from central registry`);
+
+  console.log();
+  console.log("Note: Files in the central repository were NOT deleted.");
+  console.log(`They remain at: ${formatPath(path.join(centralRepo, centralPath))}`);
+}

package/references/minimem/src/cli/commands/sync.ts

@@ -0,0 +1,70 @@
+/**
+ * minimem sync - Force re-index memory files
+ */
+
+import { Minimem } from "../../minimem.js";
+import {
+  resolveMemoryDir,
+  exitWithError,
+  loadConfig,
+  buildMinimemConfig,
+  isInitialized,
+  formatPath,
+} from "../config.js";
+
+export type SyncOptions = {
+  dir?: string;
+  global?: boolean;
+  force?: boolean;
+  provider?: string;
+};
+
+export async function sync(options: SyncOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({ dir: options.dir, global: options.global });
+
+  // Check if initialized
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(
+      `${formatPath(memoryDir)} is not initialized.`,
+      `Run: minimem init${options.dir ? ` ${options.dir}` : ""}`
+    );
+  }
+
+  console.log(`Syncing ${formatPath(memoryDir)}...`);
+
+  // Load config and create Minimem instance
+  const cliConfig = await loadConfig(memoryDir);
+  const config = buildMinimemConfig(memoryDir, cliConfig, {
+    provider: options.provider,
+    watch: false,
+  });
+
+  // Add debug logging
+  config.debug = (message, data) => {
+    if (data) {
+      console.log(`  ${message}`, data);
+    } else {
+      console.log(`  ${message}`);
+    }
+  };
+
+  let minimem: Minimem | null = null;
+
+  try {
+    minimem = await Minimem.create(config);
+
+    const startTime = Date.now();
+    await minimem.sync({ force: options.force });
+    const duration = Date.now() - startTime;
+
+    const status = await minimem.status();
+
+    console.log();
+    console.log(`Sync complete in ${duration}ms`);
+    console.log(`  Files: ${status.fileCount}`);
+    console.log(`  Chunks: ${status.chunkCount}`);
+    console.log(`  Cache: ${status.cacheCount} embeddings`);
+  } finally {
+    minimem?.close();
+  }
+}

package/references/minimem/src/cli/commands/upsert.ts

@@ -0,0 +1,197 @@
+/**
+ * minimem upsert - Create or update a memory file
+ *
+ * File paths are relative to the memory directory:
+ *   minimem upsert MEMORY.md "content"        → {memoryDir}/MEMORY.md
+ *   minimem upsert memory/notes.md "content"  → {memoryDir}/memory/notes.md
+ *   minimem upsert /abs/path.md "content"     → /abs/path.md
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { Minimem } from "../../minimem.js";
+import {
+  resolveMemoryDir,
+  exitWithError,
+  note,
+  loadConfig,
+  buildMinimemConfig,
+  isInitialized,
+  formatPath,
+} from "../config.js";
+import {
+  addFrontmatter,
+  parseFrontmatter,
+  type SessionContext,
+} from "../../session.js";
+
+export type UpsertOptions = {
+  dir?: string;
+  global?: boolean;
+  provider?: string;
+  stdin?: boolean;
+  session?: string;
+  sessionSource?: string;
+};
+
+export async function upsert(
+  file: string,
+  content: string | undefined,
+  options: UpsertOptions,
+): Promise<void> {
+  const memoryDir = resolveMemoryDir({ dir: options.dir, global: options.global });
+
+  // Check if initialized
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(
+      `${formatPath(memoryDir)} is not initialized.`,
+      `Run: minimem init${options.dir ? ` ${options.dir}` : ""}`
+    );
+  }
+
+  // Get content from stdin if --stdin flag is set
+  let finalContent = content;
+  if (options.stdin) {
+    finalContent = await readStdin();
+  }
+
+  if (!finalContent) {
+    exitWithError(
+      "No content provided.",
+      "Use --stdin or provide content as argument."
+    );
+  }
+
+  // Build session context from explicit options
+  const session: SessionContext | undefined = options.session
+    ? {
+        id: options.session,
+        source: options.sessionSource,
+        project: process.cwd(),
+      }
+    : undefined;
+
+  // Resolve file path - all relative paths are relative to memoryDir
+  const filePath = resolveFilePath(file, memoryDir);
+
+  // Ensure the file is within the memory directory
+  const resolvedPath = path.resolve(filePath);
+  const resolvedMemoryDir = path.resolve(memoryDir);
+  if (!resolvedPath.startsWith(resolvedMemoryDir + path.sep) && resolvedPath !== resolvedMemoryDir) {
+    exitWithError(
+      "File path must be within the memory directory.",
+      `Memory dir: ${formatPath(memoryDir)}, File: ${formatPath(filePath)}`
+    );
+  }
+
+  // Ensure parent directory exists
+  const parentDir = path.dirname(filePath);
+  await fs.mkdir(parentDir, { recursive: true });
+
+  // Check if file exists (for reporting)
+  let isUpdate = false;
+  let existingContent: string | undefined;
+  try {
+    await fs.access(filePath);
+    isUpdate = true;
+    existingContent = await fs.readFile(filePath, "utf-8");
+  } catch {
+    // File doesn't exist, this is a create
+  }
+
+  // Add session frontmatter if session context exists and file is markdown
+  let contentToWrite = finalContent;
+  if (session && filePath.endsWith(".md")) {
+    if (isUpdate && existingContent) {
+      // For updates, preserve existing frontmatter but update session
+      const { frontmatter: existing, body } = parseFrontmatter(existingContent);
+      // Check if the new content already has frontmatter
+      const { frontmatter: newFm, body: newBody } = parseFrontmatter(finalContent);
+      if (newFm) {
+        // New content has frontmatter, merge with existing
+        contentToWrite = addFrontmatter(newBody, {
+          ...existing,
+          ...newFm,
+          session: { ...existing?.session, ...newFm.session, ...session },
+        });
+      } else {
+        // New content has no frontmatter, add session to new content
+        contentToWrite = addFrontmatter(finalContent, {
+          ...existing,
+          session: { ...existing?.session, ...session },
+        });
+      }
+    } else {
+      // New file - add frontmatter with session
+      const { frontmatter: existingFm, body } = parseFrontmatter(finalContent);
+      contentToWrite = addFrontmatter(body, {
+        ...existingFm,
+        session,
+      });
+    }
+  }
+
+  // Write content to file
+  await fs.writeFile(filePath, contentToWrite, "utf-8");
+
+  const relativePath = path.relative(memoryDir, filePath);
+  const action = isUpdate ? "Updated" : "Created";
+  console.log(`${action}: ${relativePath}`);
+  console.log(`  in ${formatPath(memoryDir)}`);
+  if (options.session) {
+    console.log(`  Session: ${options.session}`);
+  }
+
+  // Try to sync the index (requires embedding provider)
+  let minimem: Minimem | null = null;
+
+  try {
+    const cliConfig = await loadConfig(memoryDir);
+    const config = buildMinimemConfig(memoryDir, cliConfig, {
+      provider: options.provider,
+      watch: false,
+    });
+
+    minimem = await Minimem.create(config);
+    await minimem.sync();
+    console.log("  Index synced.");
+  } catch {
+    // Sync failed, but file was written successfully
+    note("Index not synced (run 'minimem sync' with API key to index).");
+  } finally {
+    minimem?.close();
+  }
+}
+
+/**
+ * Resolve file path to an absolute path.
+ *
+ * Simple rules:
+ * - Absolute paths are used as-is
+ * - Relative paths are relative to memoryDir
+ *
+ * Examples:
+ *   MEMORY.md           → {memoryDir}/MEMORY.md
+ *   memory/notes.md     → {memoryDir}/memory/notes.md
+ *   memory/2024/jan.md  → {memoryDir}/memory/2024/jan.md
+ *   /abs/path.md        → /abs/path.md
+ */
+function resolveFilePath(file: string, memoryDir: string): string {
+  if (path.isAbsolute(file)) {
+    return file;
+  }
+  return path.join(memoryDir, file);
+}
+
+/**
+ * Read content from stdin
+ */
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+
+  return new Promise((resolve, reject) => {
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+    process.stdin.on("error", reject);
+  });
+}