cognitive-core 0.1.0 → 0.2.0

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

@@ -0,0 +1,177 @@
+/**
+ * minimem mcp - Run as MCP server (stdio)
+ *
+ * Supports multiple memory directories for cross-directory search.
+ * Auto-initializes global ~/.minimem directory as a fallback.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { Minimem } from "../../minimem.js";
+import { createMcpServer, runMcpServer } from "../../server/mcp.js";
+import type { MemoryInstance } from "../../server/tools.js";
+import {
+  resolveMemoryDirs,
+  getGlobalMemoryDir,
+  getDirName,
+  loadConfig,
+  buildMinimemConfig,
+  isInitialized,
+  formatPath,
+  getInitConfig,
+  saveConfig,
+  exitWithError,
+  warn,
+  note,
+} from "../config.js";
+
+export type McpOptions = {
+  dir?: string[];
+  global?: boolean;
+  provider?: string;
+};
+
+export async function mcp(options: McpOptions): Promise<void> {
+  // Collect all directories (now uses shared implementation)
+  const directories = resolveMemoryDirs(options);
+  const globalDir = getGlobalMemoryDir();
+
+  if (directories.length === 0) {
+    exitWithError(
+      "No memory directories specified.",
+      "Use --dir <path> or --global to specify directories."
+    );
+  }
+
+  // Auto-initialize global directory if it will be used
+  const includesGlobal = directories.includes(globalDir);
+  if (includesGlobal && !(await isInitialized(globalDir))) {
+    await ensureGlobalInitialized(globalDir);
+  }
+
+  // Validate and create instances for each directory
+  const instances: MemoryInstance[] = [];
+  const minimemInstances: Minimem[] = [];
+
+  for (const memoryDir of directories) {
+    const isGlobal = memoryDir === globalDir;
+
+    if (!(await isInitialized(memoryDir))) {
+      // Write to stderr so it doesn't interfere with MCP JSON-RPC
+      warn(`${formatPath(memoryDir)} is not initialized, skipping.`);
+
+      // If current directory isn't initialized and global isn't already included,
+      // add global as a fallback
+      if (!isGlobal && !includesGlobal) {
+        console.error(`  Using global (~/.minimem) as fallback.`);
+        if (!(await isInitialized(globalDir))) {
+          await ensureGlobalInitialized(globalDir);
+        }
+        directories.push(globalDir);
+      }
+      continue;
+    }
+
+    try {
+      const cliConfig = await loadConfig(memoryDir);
+      const config = buildMinimemConfig(memoryDir, cliConfig, {
+        provider: options.provider,
+        watch: true, // Enable watching for MCP server
+      });
+
+      const minimem = await Minimem.create(config);
+      minimemInstances.push(minimem);
+
+      // Check if running in BM25-only mode
+      const status = await minimem.status();
+      if (status.bm25Only && instances.length === 0) {
+        // Only warn once
+        note("Running in BM25-only mode (no embedding API configured).");
+        note("Search results will be based on keyword matching only.");
+      }
+
+      // Create a friendly name for the directory
+      const name = getDirName(memoryDir);
+
+      instances.push({
+        minimem,
+        memoryDir,
+        name,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      warn(`Failed to load ${formatPath(memoryDir)}: ${message}`);
+    }
+  }
+
+  if (instances.length === 0) {
+    exitWithError("No valid memory directories found.");
+  }
+
+  // Log which directories are being served (to stderr)
+  if (instances.length === 1) {
+    console.error(`Serving: ${instances[0].name} (${formatPath(instances[0].memoryDir)})`);
+  } else {
+    console.error(`Serving ${instances.length} directories:`);
+    for (const inst of instances) {
+      console.error(`  - ${inst.name} (${formatPath(inst.memoryDir)})`);
+    }
+  }
+
+  const server = createMcpServer(instances);
+
+  // Handle shutdown gracefully
+  const shutdown = () => {
+    for (const minimem of minimemInstances) {
+      minimem.close();
+    }
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  // Run the MCP server (this blocks)
+  await runMcpServer(server);
+}
+
+// resolveDirectories and getDirName are now imported from ../config.js (via shared.ts)
+
+/**
+ * Auto-initialize the global memory directory silently
+ */
+export async function ensureGlobalInitialized(globalDir: string): Promise<void> {
+  console.error(`Auto-initializing global memory directory (~/.minimem)...`);
+
+  // Create directories
+  await fs.mkdir(globalDir, { recursive: true });
+  await fs.mkdir(path.join(globalDir, "memory"), { recursive: true });
+  await fs.mkdir(path.join(globalDir, ".minimem"), { recursive: true });
+
+  // Create MEMORY.md
+  const memoryFilePath = path.join(globalDir, "MEMORY.md");
+  try {
+    await fs.access(memoryFilePath);
+  } catch {
+    const template = `# Global Memory
+
+This is your global memory file. Add notes, decisions, and context here.
+
+Notes stored here are available across all projects.
+
+## Notes
+
+`;
+    await fs.writeFile(memoryFilePath, template, "utf-8");
+  }
+
+  // Create config
+  const config = getInitConfig();
+  await saveConfig(globalDir, config);
+
+  // Create .gitignore
+  const gitignorePath = path.join(globalDir, ".minimem", ".gitignore");
+  await fs.writeFile(gitignorePath, "index.db\nindex.db-*\n", "utf-8");
+
+  console.error(`  Created ~/.minimem with default configuration.`);
+}

package/references/minimem/src/cli/commands/push-pull.ts

@@ -0,0 +1,213 @@
+/**
+ * minimem push/pull - Sync commands
+ */
+
+import {
+  resolveMemoryDir,
+  exitWithError,
+  isInitialized,
+  formatPath,
+} from "../config.js";
+import { push, pull, bidirectionalSync } from "../sync/operations.js";
+import { detectConflicts } from "../sync/conflicts.js";
+
+export type PushPullOptions = {
+  dir?: string;
+  global?: boolean;
+  force?: boolean;
+  dryRun?: boolean;
+};
+
+/**
+ * Push local changes to central repository
+ */
+export async function pushCommand(options: PushPullOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  console.log(`Pushing from ${formatPath(memoryDir)}...`);
+
+  if (options.dryRun) {
+    console.log("(dry run - no changes will be made)");
+  }
+
+  try {
+    const result = await push(memoryDir, {
+      force: options.force,
+      dryRun: options.dryRun,
+    });
+
+    if (result.pushed.length > 0) {
+      console.log(`\nPushed ${result.pushed.length} file(s):`);
+      for (const file of result.pushed) {
+        console.log(`  + ${file}`);
+      }
+    }
+
+    if (result.skipped.length > 0) {
+      console.log(`\nSkipped ${result.skipped.length} file(s) (no local changes)`);
+    }
+
+    if (result.conflicts.length > 0) {
+      console.log(`\nConflicts (${result.conflicts.length}):`);
+      for (const file of result.conflicts) {
+        console.log(`  ! ${file}`);
+      }
+      console.log("\nResolve conflicts or use --force to overwrite");
+    }
+
+    if (result.errors.length > 0) {
+      console.error(`\nErrors:`);
+      for (const error of result.errors) {
+        console.error(`  ${error}`);
+      }
+    }
+
+    if (!result.success) {
+      process.exit(1);
+    }
+
+    if (result.pushed.length === 0 && result.conflicts.length === 0) {
+      console.log("Nothing to push - already in sync");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}
+
+/**
+ * Pull changes from central repository
+ */
+export async function pullCommand(options: PushPullOptions): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  console.log(`Pulling to ${formatPath(memoryDir)}...`);
+
+  if (options.dryRun) {
+    console.log("(dry run - no changes will be made)");
+  }
+
+  try {
+    const result = await pull(memoryDir, {
+      force: options.force,
+      dryRun: options.dryRun,
+    });
+
+    if (result.pulled.length > 0) {
+      console.log(`\nPulled ${result.pulled.length} file(s):`);
+      for (const file of result.pulled) {
+        console.log(`  + ${file}`);
+      }
+    }
+
+    if (result.skipped.length > 0) {
+      console.log(`\nSkipped ${result.skipped.length} file(s) (no remote changes)`);
+    }
+
+    if (result.conflicts.length > 0) {
+      console.log(`\nConflicts (${result.conflicts.length}):`);
+      for (const file of result.conflicts) {
+        console.log(`  ! ${file}`);
+      }
+      console.log("\nResolve conflicts or use --force to overwrite");
+    }
+
+    if (result.errors.length > 0) {
+      console.error(`\nErrors:`);
+      for (const error of result.errors) {
+        console.error(`  ${error}`);
+      }
+    }
+
+    if (!result.success) {
+      process.exit(1);
+    }
+
+    if (result.pulled.length === 0 && result.conflicts.length === 0) {
+      console.log("Nothing to pull - already in sync");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}
+
+/**
+ * Show sync status
+ */
+export async function syncStatusCommand(options: { dir?: string; global?: boolean }): Promise<void> {
+  const memoryDir = resolveMemoryDir({
+    dir: options.dir,
+    global: options.global,
+  });
+
+  if (!(await isInitialized(memoryDir))) {
+    exitWithError(`${formatPath(memoryDir)} is not initialized.`);
+  }
+
+  try {
+    const detection = await detectConflicts(memoryDir);
+    const { summary } = detection;
+
+    console.log(`Sync status for ${formatPath(memoryDir)}`);
+    console.log("-".repeat(50));
+
+    if (summary.unchanged > 0) {
+      console.log(`  Unchanged:      ${summary.unchanged}`);
+    }
+    if (summary.localOnly > 0) {
+      console.log(`  Local changes:  ${summary.localOnly} (push to sync)`);
+    }
+    if (summary.remoteOnly > 0) {
+      console.log(`  Remote changes: ${summary.remoteOnly} (pull to sync)`);
+    }
+    if (summary.newLocal > 0) {
+      console.log(`  New local:      ${summary.newLocal}`);
+    }
+    if (summary.newRemote > 0) {
+      console.log(`  New remote:     ${summary.newRemote}`);
+    }
+    if (summary.deletedLocal > 0) {
+      console.log(`  Deleted local:  ${summary.deletedLocal}`);
+    }
+    if (summary.deletedRemote > 0) {
+      console.log(`  Deleted remote: ${summary.deletedRemote}`);
+    }
+    if (summary.conflicts > 0) {
+      console.log(`  CONFLICTS:      ${summary.conflicts}`);
+    }
+
+    const totalChanges =
+      summary.localOnly +
+      summary.remoteOnly +
+      summary.newLocal +
+      summary.newRemote +
+      summary.conflicts;
+
+    if (totalChanges === 0) {
+      console.log("\n  All files in sync!");
+    } else {
+      console.log(`\n  Total changes: ${totalChanges}`);
+      if (summary.conflicts > 0) {
+        console.log("  Run 'minimem push --force' or 'minimem pull --force' to resolve");
+      }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithError(message);
+  }
+}

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

@@ -0,0 +1,158 @@
+/**
+ * minimem search - Semantic search through memory
+ *
+ * Supports searching across multiple memory directories in a single query.
+ */
+
+import { Minimem, type MinimemSearchResult } from "../../minimem.js";
+import {
+  resolveMemoryDirs,
+  exitWithError,
+  warn,
+  note,
+  loadConfig,
+  buildMinimemConfig,
+  isInitialized,
+  formatPath,
+} from "../config.js";
+
+export type SearchOptions = {
+  dir?: string[];
+  global?: boolean;
+  max?: string;
+  minScore?: string;
+  provider?: string;
+  json?: boolean;
+};
+
+type SearchResultWithSource = MinimemSearchResult & {
+  memoryDir: string;
+};
+
+export async function search(
+  query: string,
+  options: SearchOptions,
+): Promise<void> {
+  const directories = resolveMemoryDirs(options);
+
+  if (directories.length === 0) {
+    exitWithError(
+      "No memory directories specified.",
+      "Use --dir <path> or --global to specify directories to search."
+    );
+  }
+
+  // Validate all directories are initialized
+  const validDirs: string[] = [];
+  for (const dir of directories) {
+    if (await isInitialized(dir)) {
+      validDirs.push(dir);
+    } else {
+      warn(`${formatPath(dir)} is not initialized, skipping.`);
+    }
+  }
+
+  if (validDirs.length === 0) {
+    exitWithError("No valid initialized memory directories found.");
+  }
+
+  const maxResults = options.max ? parseInt(options.max, 10) : 10;
+  const minScore = options.minScore ? parseFloat(options.minScore) : undefined;
+
+  // Search each directory and collect results
+  const allResults: SearchResultWithSource[] = [];
+  const instances: Minimem[] = [];
+
+  let warnedBm25 = false;
+
+  try {
+    for (const memoryDir of validDirs) {
+      const cliConfig = await loadConfig(memoryDir);
+      const config = buildMinimemConfig(memoryDir, cliConfig, {
+        provider: options.provider,
+        watch: false,
+      });
+
+      const minimem = await Minimem.create(config);
+      instances.push(minimem);
+
+      // Warn once if running in BM25-only mode
+      if (!warnedBm25) {
+        const status = await minimem.status();
+        if (status.bm25Only) {
+          note("Running in BM25-only mode (no embedding API configured).");
+          note("Results are based on keyword matching only.\n");
+          warnedBm25 = true;
+        }
+      }
+
+      // Get more results per directory, then merge and trim
+      const perDirMax = Math.ceil(maxResults * 1.5);
+      const results = await minimem.search(query, { maxResults: perDirMax, minScore });
+
+      // Add source directory to each result
+      for (const result of results) {
+        allResults.push({
+          ...result,
+          memoryDir,
+        });
+      }
+    }
+
+    // Sort by score descending and limit to maxResults
+    allResults.sort((a, b) => b.score - a.score);
+    const topResults = allResults.slice(0, maxResults);
+
+    if (topResults.length === 0) {
+      console.log("No results found.");
+      return;
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(topResults, null, 2));
+      return;
+    }
+
+    // Format results for terminal
+    const showSource = validDirs.length > 1;
+
+    for (const result of topResults) {
+      const score = (result.score * 100).toFixed(1);
+      const location = `${result.path}:${result.startLine}-${result.endLine}`;
+
+      if (showSource) {
+        console.log(`[${score}%] ${formatPath(result.memoryDir)}`);
+        console.log(`       ${location}`);
+      } else {
+        console.log(`[${score}%] ${location}`);
+      }
+      console.log(formatSnippet(result.snippet));
+      console.log();
+    }
+
+    const dirSummary = validDirs.length > 1
+      ? ` across ${validDirs.length} directories`
+      : "";
+    console.log(`Found ${topResults.length} result${topResults.length === 1 ? "" : "s"}${dirSummary}`);
+  } finally {
+    // Clean up all instances
+    for (const instance of instances) {
+      instance.close();
+    }
+  }
+}
+
+/**
+ * Format snippet for terminal display
+ */
+function formatSnippet(snippet: string): string {
+  const lines = snippet.split("\n");
+  const formatted = lines.map((line) => `  ${line}`).join("\n");
+
+  // Truncate if too long
+  if (formatted.length > 500) {
+    return formatted.slice(0, 497) + "...";
+  }
+
+  return formatted;
+}

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

@@ -0,0 +1,84 @@
+/**
+ * minimem status - Show index stats and provider info
+ */
+
+import { Minimem } from "../../minimem.js";
+import {
+  resolveMemoryDir,
+  exitWithError,
+  loadConfig,
+  buildMinimemConfig,
+  isInitialized,
+  formatPath,
+} from "../config.js";
+
+export type StatusOptions = {
+  dir?: string;
+  global?: boolean;
+  json?: boolean;
+  provider?: string;
+};
+
+export async function status(options: StatusOptions): 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}` : ""}`
+    );
+  }
+
+  // Load config and create Minimem instance
+  const cliConfig = await loadConfig(memoryDir);
+  const config = buildMinimemConfig(memoryDir, cliConfig, {
+    provider: options.provider,
+    watch: false,
+  });
+
+  let minimem: Minimem | null = null;
+
+  try {
+    minimem = await Minimem.create(config);
+    const info = await minimem.status();
+
+    if (options.json) {
+      console.log(JSON.stringify(info, null, 2));
+      return;
+    }
+
+    console.log("Minimem Status");
+    console.log("==============");
+    console.log();
+    console.log(`Memory Dir:  ${formatPath(info.memoryDir)}`);
+    console.log(`Database:    ${formatPath(info.dbPath)}`);
+    console.log();
+    console.log("Embedding Provider");
+    if (info.bm25Only) {
+      console.log(`  Provider:  none (BM25-only mode)`);
+      console.log(`  Model:     ${info.model}`);
+      if (info.fallbackReason) {
+        console.log(`  Reason:    ${info.fallbackReason}`);
+      }
+    } else {
+      console.log(`  Provider:  ${info.provider}`);
+      console.log(`  Model:     ${info.model}`);
+    }
+    console.log();
+    console.log("Search Capabilities");
+    if (info.bm25Only) {
+      console.log(`  Vector:    disabled (no embedding provider)`);
+    } else {
+      console.log(`  Vector:    ${info.vectorAvailable ? "available" : "not available"}`);
+    }
+    console.log(`  FTS:       ${info.ftsAvailable ? "available" : "not available"}`);
+    console.log();
+    console.log("Index Stats");
+    console.log(`  Files:     ${info.fileCount}`);
+    console.log(`  Chunks:    ${info.chunkCount}`);
+    console.log(`  Cache:     ${info.cacheCount} embeddings`);
+  } finally {
+    minimem?.close();
+  }
+}