@cortexmemory/cli 0.27.4 → 0.28.0

package/templates/basic/src/index.ts

@@ -1,85 +1,215 @@
 /**
- * Cortex Memory SDK - Getting Started
+ * Cortex Memory - CLI Demo
  *
- * This is a simple example to get you started with Cortex.
- * Your AI agent now has persistent memory!
+ * Interactive command-line interface for demonstrating Cortex Memory SDK.
+ * Shows the "thinking" behind each memory layer as messages are processed.
  *
- * Note: This is a template file. TypeScript errors about missing '@cortexmemory/sdk'
- * are expected and will be resolved when dependencies are installed in your project.
+ * Usage:
+ *   npm start              # Start CLI mode
+ *   npm run server         # Start HTTP server mode
+ *
+ * Commands:
+ *   /recall <query>        # Search memories without storing
+ *   /facts                 # List all stored facts
+ *   /history               # Show conversation history
+ *   /new                   # Start a new conversation
+ *   /config                # Show current configuration
+ *   /clear                 # Clear the screen
+ *   /exit                  # Exit the demo
  */
 
-import { Cortex } from "@cortexmemory/sdk";
+import * as readline from "readline";
+import { closeCortex } from "./cortex.js";
+import {
+  chat,
+  recallMemories,
+  listFacts,
+  getHistory,
+  newConversation,
+  printConfig,
+  getConversationId,
+} from "./chat.js";
+import { printWelcome, printError, printInfo, printSuccess } from "./display.js";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// CLI Interface
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-// Initialize Cortex with your Convex deployment
-const cortex = new Cortex({
-  convexUrl: process.env.CONVEX_URL!,
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
 });
 
-async function main() {
-  console.log("🧠 Cortex Memory SDK - Example");
-  console.log("================================\n");
+/**
+ * Process a line of input
+ */
+async function processInput(input: string): Promise<boolean> {
+  const trimmed = input.trim();
+
+  if (!trimmed) {
+    return true; // Continue
+  }
 
-  // Define your memory space (isolation boundary)
-  const memorySpaceId = "my-first-agent";
-  const conversationId = "conversation-1";
+  // Handle commands
+  if (trimmed.startsWith("/")) {
+    return handleCommand(trimmed);
+  }
 
+  // Regular chat message
   try {
-    // Store a memory (remember() auto-creates conversation if needed!)
-    console.log("💾 Storing a memory...");
-    await cortex.memory.remember({
-      memorySpaceId,
-      conversationId,
-      userMessage: "I prefer dark mode and TypeScript",
-      agentResponse: "Got it! I'll remember your preferences.",
-      userId: "user-123",
-      userName: "User",
-    });
-    console.log("✓ Memory stored!\n");
-
-    // Search for memories
-    console.log("🔍 Searching memories...");
-    const results = await cortex.memory.search(
-      memorySpaceId,
-      "what are the user preferences?",
-    );
+    console.log("");
+    const result = await chat(trimmed);
+
+    // Print assistant response
+    console.log("\x1b[36mAssistant:\x1b[0m");
+    console.log(result.response);
+    console.log("");
+
+    return true;
+  } catch (error) {
+    printError("Failed to process message", error instanceof Error ? error : undefined);
+    return true;
+  }
+}
+
+/**
+ * Handle slash commands
+ */
+async function handleCommand(input: string): Promise<boolean> {
+  const parts = input.slice(1).split(" ");
+  const command = parts[0].toLowerCase();
+  const args = parts.slice(1).join(" ");
+
+  switch (command) {
+    case "exit":
+    case "quit":
+    case "q":
+      printInfo("Goodbye!");
+      return false;
+
+    case "clear":
+    case "cls":
+      console.clear();
+      printWelcome("cli");
+      return true;
+
+    case "recall":
+    case "search":
+      if (!args) {
+        printInfo("Usage: /recall <query>");
+      } else {
+        await recallMemories(args);
+      }
+      return true;
+
+    case "facts":
+      await listFacts();
+      return true;
+
+    case "history":
+    case "h":
+      await getHistory();
+      return true;
+
+    case "new":
+      newConversation();
+      return true;
+
+    case "config":
+    case "status":
+      printConfig();
+      return true;
 
-    console.log(`✓ Found ${results.length} relevant memories:`);
-    results.forEach((result: any, i: number) => {
-      // Handle both MemoryEntry and EnrichedMemory formats
-      const memory = "memory" in result ? result.memory : result;
-      console.log(`\n${i + 1}. ${memory.content}`);
-      console.log(`   Importance: ${memory.importance}`);
-    });
-
-    // Get conversation history
-    console.log("\n📜 Getting conversation history...");
-    const conversation = await cortex.conversations.get(conversationId);
-
-    if (conversation) {
-      console.log(
-        `✓ Conversation has ${conversation.messages.length} messages`,
-      );
+    case "help":
+    case "?":
+      printHelp();
+      return true;
+
+    default:
+      printInfo(`Unknown command: /${command}. Type /help for available commands.`);
+      return true;
+  }
+}
+
+/**
+ * Print help message
+ */
+function printHelp(): void {
+  console.log("");
+  console.log("📖 Available Commands:");
+  console.log("");
+  console.log("  /recall <query>  Search memories without storing");
+  console.log("  /facts           List all stored facts");
+  console.log("  /history         Show conversation history");
+  console.log("  /new             Start a new conversation");
+  console.log("  /config          Show current configuration");
+  console.log("  /clear           Clear the screen");
+  console.log("  /help            Show this help message");
+  console.log("  /exit            Exit the demo");
+  console.log("");
+}
+
+/**
+ * Prompt for input
+ */
+function prompt(): void {
+  rl.question("\x1b[33mYou:\x1b[0m ", async (input) => {
+    const shouldContinue = await processInput(input);
+
+    if (shouldContinue) {
+      prompt();
+    } else {
+      cleanup();
     }
+  });
+}
 
-    console.log("\n🎉 Success! Your AI agent has persistent memory.");
-    console.log("\n📚 Next steps:");
-    console.log(
-      "   - Explore the API: https://github.com/SaintNick1214/Project-Cortex",
+/**
+ * Cleanup on exit
+ */
+function cleanup(): void {
+  closeCortex();
+  rl.close();
+  process.exit(0);
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Main Entry Point
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+async function main(): Promise<void> {
+  // Check for required environment
+  if (!process.env.CONVEX_URL) {
+    printError(
+      "CONVEX_URL is required. Set it in .env.local or run: cortex init",
     );
-    console.log("   - Add vector embeddings for semantic search");
-    console.log("   - Set up graph database for advanced queries");
-    console.log("   - Build multi-agent systems with context chains\n");
-  } catch (error) {
-    console.error("❌ Error:", error);
-    throw error;
-  } finally {
-    // Cleanup
-    cortex.close();
+    process.exit(1);
   }
+
+  // Print welcome
+  printWelcome("cli");
+
+  // Initialize conversation
+  const convId = getConversationId();
+  printSuccess(`Conversation: ${convId}`);
+  console.log("");
+
+  // Handle signals
+  process.on("SIGINT", () => {
+    console.log("");
+    cleanup();
+  });
+
+  process.on("SIGTERM", () => {
+    cleanup();
+  });
+
+  // Start prompt loop
+  prompt();
 }
 
-// Run the example
+// Run
 main().catch((error) => {
-  console.error("Fatal error:", error);
+  printError("Fatal error", error instanceof Error ? error : undefined);
   process.exit(1);
 });

package/templates/basic/src/llm.ts

@@ -0,0 +1,214 @@
+/**
+ * LLM Integration (Optional)
+ *
+ * Provides AI-powered responses when OPENAI_API_KEY is set.
+ * Falls back to echo mode with memory context when no API key is available.
+ */
+
+import type { Memory, Fact } from "./chat.js";
+import { CONFIG } from "./cortex.js";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Configuration
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const SYSTEM_PROMPT = `You are a helpful AI assistant with long-term memory powered by Cortex.
+
+Your capabilities:
+- You remember everything users tell you across conversations
+- You can recall facts, preferences, and context from past interactions
+- You naturally reference what you've learned about the user
+
+Behavior guidelines:
+- When you remember something from a previous conversation, mention it naturally
+- If asked about something you learned, reference it specifically
+- Be conversational and friendly
+- Help demonstrate the memory system by showing what you remember
+
+Example interactions:
+- User: "My name is Alex" → Remember and use their name
+- User: "I work at Acme Corp" → Remember their employer
+- User: "My favorite color is blue" → Remember their preference
+- User: "What do you know about me?" → List everything you remember`;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// LLM State
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+let openaiClient: unknown = null;
+let llmAvailable = false;
+
+/**
+ * Check if LLM is available
+ */
+export function isLLMAvailable(): boolean {
+  return llmAvailable || !!process.env.OPENAI_API_KEY;
+}
+
+/**
+ * Initialize OpenAI client if API key is available
+ */
+async function getOpenAIClient(): Promise<unknown> {
+  if (openaiClient) return openaiClient;
+
+  if (!process.env.OPENAI_API_KEY) {
+    return null;
+  }
+
+  try {
+    const { default: OpenAI } = await import("openai");
+    openaiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    llmAvailable = true;
+    return openaiClient;
+  } catch {
+    // OpenAI not installed
+    return null;
+  }
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Response Generation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Generate a response using LLM or echo mode
+ */
+export async function generateResponse(
+  userMessage: string,
+  memories: Memory[],
+  facts: Fact[],
+): Promise<string> {
+  const client = await getOpenAIClient();
+
+  if (client) {
+    return generateLLMResponse(client, userMessage, memories, facts);
+  } else {
+    return generateEchoResponse(userMessage, memories, facts);
+  }
+}
+
+/**
+ * Generate response using OpenAI
+ */
+async function generateLLMResponse(
+  client: unknown,
+  userMessage: string,
+  memories: Memory[],
+  facts: Fact[],
+): Promise<string> {
+  // Build context from memories and facts
+  const context = buildContext(memories, facts);
+
+  // Build messages array
+  const messages = [
+    { role: "system" as const, content: SYSTEM_PROMPT },
+  ];
+
+  // Add memory context if available
+  if (context) {
+    messages.push({
+      role: "system" as const,
+      content: `Here is what you remember about this user:\n\n${context}`,
+    });
+  }
+
+  // Add user message
+  messages.push({ role: "user" as const, content: userMessage });
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const openai = client as any;
+    const completion = await openai.chat.completions.create({
+      model: "gpt-4o-mini",
+      messages,
+      max_tokens: 500,
+      temperature: 0.7,
+    });
+
+    return completion.choices[0]?.message?.content || "I couldn't generate a response.";
+  } catch (error) {
+    if (CONFIG.debug) {
+      console.error("[Debug] OpenAI error:", error);
+    }
+    // Fall back to echo mode on error
+    return generateEchoResponse(userMessage, memories, facts);
+  }
+}
+
+/**
+ * Generate echo response (no LLM)
+ */
+function generateEchoResponse(
+  userMessage: string,
+  memories: Memory[],
+  facts: Fact[],
+): string {
+  const lines: string[] = [];
+
+  lines.push(`I heard you say: "${userMessage}"`);
+  lines.push("");
+
+  if (memories.length > 0 || facts.length > 0) {
+    lines.push("📚 Here's what I remember about you:");
+    lines.push("");
+
+    if (facts.length > 0) {
+      lines.push("Facts:");
+      for (const fact of facts.slice(0, 5)) {
+        const type = fact.factType ? ` [${fact.factType}]` : "";
+        lines.push(`  • ${fact.content}${type}`);
+      }
+      if (facts.length > 5) {
+        lines.push(`  ... and ${facts.length - 5} more facts`);
+      }
+      lines.push("");
+    }
+
+    if (memories.length > 0) {
+      lines.push("Recent conversations:");
+      for (const mem of memories.slice(0, 3)) {
+        const content = mem.content?.slice(0, 80) || "";
+        lines.push(`  • ${content}${content.length >= 80 ? "..." : ""}`);
+      }
+      if (memories.length > 3) {
+        lines.push(`  ... and ${memories.length - 3} more memories`);
+      }
+    }
+  } else {
+    lines.push("💭 I don't have any memories of you yet.");
+    lines.push("   Tell me something about yourself!");
+  }
+
+  lines.push("");
+  lines.push("ℹ️  Running in echo mode (no OPENAI_API_KEY)");
+  lines.push("   Set OPENAI_API_KEY in .env.local for AI responses.");
+
+  return lines.join("\n");
+}
+
+/**
+ * Build context string from memories and facts
+ */
+function buildContext(memories: Memory[], facts: Fact[]): string {
+  const parts: string[] = [];
+
+  // Add facts
+  if (facts.length > 0) {
+    parts.push("Known facts about the user:");
+    for (const fact of facts) {
+      const type = fact.factType ? ` (${fact.factType})` : "";
+      parts.push(`- ${fact.content}${type}`);
+    }
+    parts.push("");
+  }
+
+  // Add relevant memories
+  if (memories.length > 0) {
+    parts.push("Relevant past conversations:");
+    for (const mem of memories.slice(0, 5)) {
+      parts.push(`- ${mem.content}`);
+    }
+  }
+
+  return parts.join("\n");
+}