cognitive-core 0.1.0 → 0.2.0

package/references/minimem/src/cli/index.ts

@@ -0,0 +1,264 @@
+/**
+ * Minimem CLI
+ *
+ * A file-based memory system with vector search for AI agents.
+ */
+
+import { program } from "commander";
+
+import { init } from "./commands/init.js";
+import { search } from "./commands/search.js";
+import { sync } from "./commands/sync.js";
+import { status } from "./commands/status.js";
+import { append } from "./commands/append.js";
+import { upsert } from "./commands/upsert.js";
+import { mcp } from "./commands/mcp.js";
+import { config } from "./commands/config.js";
+import { syncInit, syncInitCentral, syncList, syncRemove } from "./commands/sync-init.js";
+import { pushCommand, pullCommand, syncStatusCommand } from "./commands/push-pull.js";
+import { conflictsCommand, resolveCommand, cleanupCommand, logCommand } from "./commands/conflicts.js";
+import { daemonCommand, daemonStopCommand, daemonStatusCommand, daemonLogsCommand } from "./commands/daemon.js";
+import { validateRegistry, formatValidationResult } from "./sync/validation.js";
+import { VERSION } from "./version.js";
+import { exitWithError } from "./config.js";
+
+program
+  .name("minimem")
+  .description("File-based memory system with vector search for AI agents")
+  .version(VERSION);
+
+// minimem init [dir]
+program
+  .command("init [dir]")
+  .description("Initialize a memory directory")
+  .option("-g, --global", "Use ~/.minimem as global memory directory")
+  .option("-f, --force", "Reinitialize even if already initialized")
+  .action(init);
+
+// minimem search <query>
+program
+  .command("search <query>")
+  .description("Semantic search through memory files")
+  .option("-d, --dir <path...>", "Memory directories (can specify multiple)")
+  .option("-g, --global", "Include ~/.minimem in search")
+  .option("-n, --max <number>", "Maximum results (default: 10)")
+  .option("-s, --min-score <number>", "Minimum score threshold 0-1 (default: 0.3)")
+  .option("-p, --provider <name>", "Embedding provider (openai, gemini, local, auto)")
+  .option("--json", "Output results as JSON")
+  .action(search);
+
+// minimem sync
+program
+  .command("sync")
+  .description("Force re-index memory files")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-f, --force", "Force full re-index")
+  .option("-p, --provider <name>", "Embedding provider (openai, gemini, local, auto)")
+  .action(sync);
+
+// minimem status
+program
+  .command("status")
+  .description("Show index stats and provider info")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-p, --provider <name>", "Embedding provider (openai, gemini, local, auto)")
+  .option("--json", "Output as JSON")
+  .action(status);
+
+// minimem append <text>
+program
+  .command("append <text>")
+  .description("Append text to today's daily log (memory/YYYY-MM-DD.md)")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-f, --file <path>", "Append to specific file instead of today's log")
+  .option("-p, --provider <name>", "Embedding provider (openai, gemini, local, auto)")
+  .option("-s, --session <id>", "Session ID to associate with this memory")
+  .option("--session-source <name>", "Session source (claude-code, vscode, etc.)")
+  .action(append);
+
+// minimem upsert <file> [content]
+program
+  .command("upsert <file> [content]")
+  .description("Create or update a memory file (file path relative to memory dir)")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-p, --provider <name>", "Embedding provider (openai, gemini, local, auto)")
+  .option("--stdin", "Read content from stdin")
+  .option("-s, --session <id>", "Session ID to associate with this memory")
+  .option("--session-source <name>", "Session source (claude-code, vscode, etc.)")
+  .action(upsert);
+
+// minimem mcp
+program
+  .command("mcp")
+  .description("Run as MCP server over stdio (for Claude Desktop, Cursor, etc.)")
+  .option("-d, --dir <path...>", "Memory directories (can specify multiple)")
+  .option("-g, --global", "Include ~/.minimem")
+  .option("-p, --provider <name>", "Embedding provider (openai, gemini, local, auto)")
+  .action(mcp);
+
+// minimem config
+program
+  .command("config")
+  .description("View or modify configuration")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("--xdg-global", "Modify ~/.config/minimem/config.json (for sync settings)")
+  .option("--json", "Output as JSON")
+  .option("--set <key=value>", "Set a config value (e.g., embedding.provider=openai)")
+  .option("--unset <key>", "Remove a config value")
+  .action(config);
+
+// minimem sync init-central <path>
+program
+  .command("sync:init-central <path>")
+  .description("Initialize a central repository for syncing memories")
+  .option("-f, --force", "Force creation even if directory exists")
+  .action(syncInitCentral);
+
+// minimem sync init
+program
+  .command("sync:init")
+  .description("Initialize sync for a memory directory")
+  .option("-d, --local <path>", "Memory directory to sync")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-p, --path <path>", "Path in central repo (e.g., myproject/)")
+  .action(syncInit);
+
+// minimem sync list
+program
+  .command("sync:list")
+  .description("List all sync mappings")
+  .action(syncList);
+
+// minimem sync remove
+program
+  .command("sync:remove")
+  .description("Remove sync mapping for a directory")
+  .option("-d, --local <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .action(syncRemove);
+
+// minimem push
+program
+  .command("push")
+  .description("Push local changes to central repository")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-f, --force", "Force push (overwrite remote on conflicts)")
+  .option("--dry-run", "Show what would be pushed without making changes")
+  .action(pushCommand);
+
+// minimem pull
+program
+  .command("pull")
+  .description("Pull changes from central repository")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-f, --force", "Force pull (overwrite local on conflicts)")
+  .option("--dry-run", "Show what would be pulled without making changes")
+  .action(pullCommand);
+
+// minimem sync:status
+program
+  .command("sync:status")
+  .description("Show sync status for a directory")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .action(syncStatusCommand);
+
+// minimem sync:conflicts
+program
+  .command("sync:conflicts")
+  .description("List quarantined conflicts")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("--json", "Output as JSON")
+  .action(conflictsCommand);
+
+// minimem sync:resolve <timestamp>
+program
+  .command("sync:resolve <timestamp>")
+  .description("Resolve a quarantined conflict using merge tool")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-t, --tool <name>", "Merge tool (code, meld, kdiff3, vimdiff)")
+  .action(resolveCommand);
+
+// minimem sync:cleanup
+program
+  .command("sync:cleanup")
+  .description("Clean up old quarantined conflicts")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("--days <number>", "Remove conflicts older than N days (default: 30)")
+  .option("--dry-run", "Show what would be removed without removing")
+  .action(cleanupCommand);
+
+// minimem sync:log
+program
+  .command("sync:log")
+  .description("Show sync history")
+  .option("-d, --dir <path>", "Memory directory")
+  .option("-g, --global", "Use ~/.minimem")
+  .option("-n, --limit <number>", "Number of entries to show (default: 20)")
+  .option("--json", "Output as JSON")
+  .action(logCommand);
+
+// minimem daemon
+program
+  .command("daemon")
+  .description("Start the sync daemon")
+  .option("-b, --background", "Run in background")
+  .option("--foreground", "Run in foreground (internal use)")
+  .action(daemonCommand);
+
+// minimem daemon:stop
+program
+  .command("daemon:stop")
+  .description("Stop the sync daemon")
+  .action(daemonStopCommand);
+
+// minimem daemon:status
+program
+  .command("daemon:status")
+  .description("Show daemon status")
+  .action(daemonStatusCommand);
+
+// minimem daemon:logs
+program
+  .command("daemon:logs")
+  .description("Show daemon logs")
+  .option("-n, --lines <number>", "Number of lines to show (default: 50)")
+  .option("-f, --follow", "Follow log output")
+  .action(daemonLogsCommand);
+
+// minimem sync:validate
+program
+  .command("sync:validate")
+  .description("Validate registry for collisions and stale mappings")
+  .option("--json", "Output as JSON")
+  .action(async (options: { json?: boolean }) => {
+    try {
+      const result = await validateRegistry();
+
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(formatValidationResult(result));
+      }
+
+      if (!result.valid) {
+        process.exit(1);
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      exitWithError(message);
+    }
+  });
+
+// Parse and run
+program.parse();

package/references/minimem/src/cli/shared.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared CLI utilities
+ *
+ * Centralized functions for directory resolution, error handling,
+ * and other cross-cutting concerns used by all CLI commands.
+ */
+
+import * as path from "node:path";
+import * as os from "node:os";
+
+/**
+ * Options that affect directory resolution
+ */
+export type DirOptions = {
+  dir?: string | string[];
+  global?: boolean;
+};
+
+/**
+ * Resolve a single memory directory from options.
+ *
+ * Priority:
+ * 1. --dir flag (first element if array)
+ * 2. MEMORY_DIR environment variable
+ * 3. --global flag → ~/.minimem
+ * 4. Current working directory
+ *
+ * Use this for commands that operate on a single directory.
+ */
+export function resolveMemoryDir(options: DirOptions): string {
+  // Handle --dir flag (use first if array)
+  const dir = Array.isArray(options.dir) ? options.dir[0] : options.dir;
+  if (dir) {
+    return path.resolve(dir);
+  }
+
+  // Check MEMORY_DIR environment variable
+  const envDir = process.env.MEMORY_DIR;
+  if (envDir) {
+    return path.resolve(envDir);
+  }
+
+  // Handle --global flag
+  if (options.global) {
+    return path.join(os.homedir(), ".minimem");
+  }
+
+  // Default to current working directory
+  return process.cwd();
+}
+
+/**
+ * Resolve multiple memory directories from options.
+ *
+ * Use this for commands that can search across multiple directories
+ * (e.g., search, mcp).
+ *
+ * Returns deduplicated list of absolute paths.
+ */
+export function resolveMemoryDirs(options: DirOptions): string[] {
+  const dirs: string[] = [];
+
+  // Add explicit directories from --dir flag
+  if (options.dir) {
+    const dirList = Array.isArray(options.dir) ? options.dir : [options.dir];
+    dirs.push(...dirList.map((d) => path.resolve(d)));
+  }
+
+  // If no explicit dirs, check MEMORY_DIR environment variable
+  if (dirs.length === 0 && process.env.MEMORY_DIR) {
+    dirs.push(path.resolve(process.env.MEMORY_DIR));
+  }
+
+  // Add global directory if --global flag is set
+  if (options.global) {
+    const globalDir = path.join(os.homedir(), ".minimem");
+    if (!dirs.includes(globalDir)) {
+      dirs.push(globalDir);
+    }
+  }
+
+  // Default to current directory if nothing specified
+  if (dirs.length === 0) {
+    dirs.push(process.cwd());
+  }
+
+  // Deduplicate
+  return [...new Set(dirs)];
+}
+
+/**
+ * Get the global memory directory path (~/.minimem)
+ */
+export function getGlobalMemoryDir(): string {
+  return path.join(os.homedir(), ".minimem");
+}
+
+/**
+ * Exit with an error message and optional suggestion.
+ *
+ * All CLI errors should use this for consistent formatting.
+ */
+export function exitWithError(message: string, suggestion?: string): never {
+  console.error(`Error: ${message}`);
+  if (suggestion) {
+    console.error(`  Suggestion: ${suggestion}`);
+  }
+  process.exit(1);
+}
+
+/**
+ * Print a warning message (non-fatal).
+ */
+export function warn(message: string): void {
+  console.error(`Warning: ${message}`);
+}
+
+/**
+ * Print a note/informational message.
+ */
+export function note(message: string): void {
+  console.error(`Note: ${message}`);
+}
+
+/**
+ * Log an error with context (for debugging).
+ * Only logs if a debug function is provided.
+ */
+export function logError(
+  context: string,
+  error: unknown,
+  debug?: (msg: string) => void
+): void {
+  const message = error instanceof Error ? error.message : String(error);
+  if (debug) {
+    debug(`[${context}] Error: ${message}`);
+  }
+}
+
+/**
+ * Get a friendly display name for a directory.
+ */
+export function getDirName(memoryDir: string): string {
+  const home = os.homedir();
+
+  // Check if it's the global directory
+  if (memoryDir === path.join(home, ".minimem")) {
+    return "global";
+  }
+
+  // Use the directory name
+  const name = path.basename(memoryDir);
+
+  // If it's a hidden directory, use parent + name
+  if (name.startsWith(".")) {
+    const parent = path.basename(path.dirname(memoryDir));
+    return `${parent}/${name}`;
+  }
+
+  return name;
+}

package/references/minimem/src/cli/sync/__tests__/central.test.ts

@@ -0,0 +1,152 @@
+/**
+ * Tests for central repository initialization
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, it, expect } from "vitest";
+
+import {
+  initCentralRepo,
+  validateCentralRepo,
+} from "../central.js";
+import { readRegistry } from "../registry.js";
+
+describe("Central Repository", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "minimem-central-test-"));
+  });
+
+  afterEach(async () => {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe("initCentralRepo", () => {
+    it("should create new central repository", async () => {
+      const repoPath = path.join(tempDir, "memories-repo");
+      const result = await initCentralRepo(repoPath);
+
+      expect(result.success).toBe(true);
+      expect(result.created).toBe(true);
+      expect(result.message.includes("Created")).toBeTruthy();
+
+      // Check .git exists
+      const gitStat = await fs.stat(path.join(repoPath, ".git"));
+      expect(gitStat.isDirectory()).toBeTruthy();
+
+      // Check .gitignore exists and has correct content
+      const gitignore = await fs.readFile(path.join(repoPath, ".gitignore"), "utf-8");
+      expect(gitignore.includes("*.db")).toBeTruthy();
+      expect(gitignore.includes("staging/")).toBeTruthy();
+      expect(gitignore.includes("conflicts/")).toBeTruthy();
+
+      // Check registry exists
+      const registry = await readRegistry(repoPath);
+      expect(registry.mappings).toEqual([]);
+
+      // Check README exists
+      const readme = await fs.readFile(path.join(repoPath, "README.md"), "utf-8");
+      expect(readme.includes("Minimem Central Repository")).toBeTruthy();
+    });
+
+    it("should configure existing directory", async () => {
+      // Create directory first
+      await fs.mkdir(tempDir, { recursive: true });
+
+      const result = await initCentralRepo(tempDir);
+
+      expect(result.success).toBe(true);
+      expect(result.created).toBe(false);
+      expect(result.message.includes("Configured")).toBeTruthy();
+    });
+
+    it("should not overwrite existing .gitignore", async () => {
+      const repoPath = path.join(tempDir, "existing-repo");
+      await fs.mkdir(repoPath, { recursive: true });
+      await fs.writeFile(path.join(repoPath, ".gitignore"), "custom-ignore\n");
+
+      await initCentralRepo(repoPath);
+
+      const gitignore = await fs.readFile(path.join(repoPath, ".gitignore"), "utf-8");
+      expect(gitignore).toBe("custom-ignore\n");
+    });
+
+    it("should not overwrite existing registry", async () => {
+      const repoPath = path.join(tempDir, "existing-repo");
+      await fs.mkdir(repoPath, { recursive: true });
+      await fs.writeFile(
+        path.join(repoPath, ".minimem-registry.json"),
+        JSON.stringify({ version: 1, mappings: [{ path: "test/" }] })
+      );
+
+      await initCentralRepo(repoPath);
+
+      const content = await fs.readFile(
+        path.join(repoPath, ".minimem-registry.json"),
+        "utf-8"
+      );
+      const registry = JSON.parse(content);
+      expect(registry.mappings.length).toBe(1);
+    });
+
+    it("should handle ~ in path", async () => {
+      // We can't easily test ~ expansion to home in isolation,
+      // but we can test that it doesn't crash
+      const result = await initCentralRepo(path.join(tempDir, "test-repo"));
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("validateCentralRepo", () => {
+    it("should validate a properly configured repo", async () => {
+      const repoPath = path.join(tempDir, "valid-repo");
+      await initCentralRepo(repoPath);
+
+      const result = await validateCentralRepo(repoPath);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors.length).toBe(0);
+    });
+
+    it("should report missing directory", async () => {
+      const result = await validateCentralRepo(path.join(tempDir, "nonexistent"));
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some(e => e.includes("does not exist"))).toBeTruthy();
+    });
+
+    it("should warn about missing registry", async () => {
+      await fs.mkdir(tempDir, { recursive: true });
+      // Initialize git but don't create registry
+      const { execSync } = await import("node:child_process");
+      execSync("git init", { cwd: tempDir, stdio: "pipe" });
+
+      const result = await validateCentralRepo(tempDir);
+
+      expect(result.valid).toBe(true); // Still valid, just has warnings
+      expect(result.warnings.some(w => w.includes("Registry"))).toBeTruthy();
+    });
+
+    it("should warn about missing .gitignore", async () => {
+      const repoPath = path.join(tempDir, "no-gitignore");
+      await fs.mkdir(repoPath, { recursive: true });
+      const { execSync } = await import("node:child_process");
+      execSync("git init", { cwd: repoPath, stdio: "pipe" });
+
+      const result = await validateCentralRepo(repoPath);
+
+      expect(result.warnings.some(w => w.includes(".gitignore"))).toBeTruthy();
+    });
+
+    it("should warn if not a git repo", async () => {
+      await fs.mkdir(tempDir, { recursive: true });
+
+      const result = await validateCentralRepo(tempDir);
+
+      expect(result.warnings.some(w => w.includes("Not a git repository"))).toBeTruthy();
+    });
+  });
+});