@cortexmemory/cli 0.27.4 → 0.28.0

package/templates/basic/src/__tests__/llm.test.ts

@@ -0,0 +1,344 @@
+/**
+ * Unit tests for llm.ts
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+// Mock cortex.js CONFIG
+vi.mock("../cortex.js", () => ({
+  CONFIG: {
+    debug: false,
+  },
+}));
+
+describe("llm", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    vi.clearAllMocks();
+  });
+
+  describe("isLLMAvailable", () => {
+    it("returns false when OPENAI_API_KEY is not set", async () => {
+      delete process.env.OPENAI_API_KEY;
+
+      const { isLLMAvailable } = await import("../llm.js");
+
+      expect(isLLMAvailable()).toBe(false);
+    });
+
+    it("returns true when OPENAI_API_KEY is set", async () => {
+      process.env.OPENAI_API_KEY = "sk-test-key";
+
+      const { isLLMAvailable } = await import("../llm.js");
+
+      expect(isLLMAvailable()).toBe(true);
+    });
+  });
+
+  describe("generateResponse", () => {
+    describe("echo mode (no LLM)", () => {
+      beforeEach(() => {
+        delete process.env.OPENAI_API_KEY;
+      });
+
+      it("echoes the user message", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const response = await generateResponse("Hello world", [], []);
+
+        expect(response).toContain('I heard you say: "Hello world"');
+      });
+
+      it("shows empty memory message when no memories", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const response = await generateResponse("Hello", [], []);
+
+        expect(response).toContain("I don't have any memories of you yet");
+        expect(response).toContain("Tell me something about yourself");
+      });
+
+      it("shows facts when available", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const facts = [
+          { content: "User's name is Alex", factType: "identity" },
+          { content: "User likes coffee", factType: "preference" },
+        ];
+
+        const response = await generateResponse("Hello", [], facts);
+
+        expect(response).toContain("Here's what I remember about you");
+        expect(response).toContain("Facts:");
+        expect(response).toContain("User's name is Alex");
+        expect(response).toContain("[identity]");
+        expect(response).toContain("User likes coffee");
+      });
+
+      it("shows memories when available", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const memories = [
+          { content: "User said hello yesterday" },
+          { content: "User asked about the weather" },
+        ];
+
+        const response = await generateResponse("Hello", memories, []);
+
+        expect(response).toContain("Here's what I remember about you");
+        expect(response).toContain("Recent conversations:");
+        expect(response).toContain("User said hello yesterday");
+        expect(response).toContain("User asked about the weather");
+      });
+
+      it("truncates long memory content", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const memories = [
+          {
+            content: "A".repeat(100), // 100 characters
+          },
+        ];
+
+        const response = await generateResponse("Hello", memories, []);
+
+        // Should truncate at 80 chars with "..."
+        expect(response).toContain("A".repeat(80) + "...");
+      });
+
+      it("truncates long fact lists", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const facts = Array(10)
+          .fill(null)
+          .map((_, i) => ({ content: `Fact ${i}` }));
+
+        const response = await generateResponse("Hello", [], facts);
+
+        expect(response).toContain("... and 5 more facts");
+      });
+
+      it("truncates long memory lists", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const memories = Array(10)
+          .fill(null)
+          .map((_, i) => ({ content: `Memory ${i}` }));
+
+        const response = await generateResponse("Hello", memories, []);
+
+        expect(response).toContain("... and 7 more memories");
+      });
+
+      it("shows info about echo mode", async () => {
+        const { generateResponse } = await import("../llm.js");
+
+        const response = await generateResponse("Hello", [], []);
+
+        expect(response).toContain("Running in echo mode");
+        expect(response).toContain("OPENAI_API_KEY");
+      });
+    });
+
+    describe("LLM mode", () => {
+      it("calls OpenAI API when API key is set", async () => {
+        process.env.OPENAI_API_KEY = "sk-test-key";
+
+        const mockCreate = vi.fn().mockResolvedValue({
+          choices: [{ message: { content: "Hello from AI!" } }],
+        });
+
+        vi.doMock("openai", () => ({
+          default: vi.fn().mockImplementation(() => ({
+            chat: {
+              completions: {
+                create: mockCreate,
+              },
+            },
+          })),
+        }));
+
+        const { generateResponse } = await import("../llm.js");
+
+        const response = await generateResponse("Hello", [], []);
+
+        expect(response).toBe("Hello from AI!");
+        expect(mockCreate).toHaveBeenCalledWith(
+          expect.objectContaining({
+            model: "gpt-4o-mini",
+            messages: expect.arrayContaining([
+              expect.objectContaining({ role: "system" }),
+              expect.objectContaining({ role: "user", content: "Hello" }),
+            ]),
+          }),
+        );
+      });
+
+      it("includes memory context in system message", async () => {
+        process.env.OPENAI_API_KEY = "sk-test-key";
+
+        const mockCreate = vi.fn().mockResolvedValue({
+          choices: [{ message: { content: "AI response" } }],
+        });
+
+        vi.doMock("openai", () => ({
+          default: vi.fn().mockImplementation(() => ({
+            chat: {
+              completions: {
+                create: mockCreate,
+              },
+            },
+          })),
+        }));
+
+        const { generateResponse } = await import("../llm.js");
+
+        const facts = [{ content: "User's name is Alex", factType: "identity" }];
+        const memories = [{ content: "User said hello" }];
+
+        await generateResponse("Hello", memories, facts);
+
+        expect(mockCreate).toHaveBeenCalledWith(
+          expect.objectContaining({
+            messages: expect.arrayContaining([
+              expect.objectContaining({
+                role: "system",
+                content: expect.stringContaining("Alex"),
+              }),
+            ]),
+          }),
+        );
+      });
+
+      it("falls back to echo mode on API error", async () => {
+        process.env.OPENAI_API_KEY = "sk-test-key";
+
+        vi.doMock("openai", () => ({
+          default: vi.fn().mockImplementation(() => ({
+            chat: {
+              completions: {
+                create: vi.fn().mockRejectedValue(new Error("API Error")),
+              },
+            },
+          })),
+        }));
+
+        const { generateResponse } = await import("../llm.js");
+
+        const response = await generateResponse("Hello", [], []);
+
+        // Should fall back to echo mode
+        expect(response).toContain('I heard you say: "Hello"');
+        expect(response).toContain("echo mode");
+      });
+
+      it("handles empty API response", async () => {
+        process.env.OPENAI_API_KEY = "sk-test-key";
+
+        vi.doMock("openai", () => ({
+          default: vi.fn().mockImplementation(() => ({
+            chat: {
+              completions: {
+                create: vi.fn().mockResolvedValue({
+                  choices: [{ message: { content: null } }],
+                }),
+              },
+            },
+          })),
+        }));
+
+        const { generateResponse } = await import("../llm.js");
+
+        const response = await generateResponse("Hello", [], []);
+
+        expect(response).toBe("I couldn't generate a response.");
+      });
+    });
+  });
+
+  describe("context building", () => {
+    it("builds context from facts and memories", async () => {
+      delete process.env.OPENAI_API_KEY;
+
+      const { generateResponse } = await import("../llm.js");
+
+      const facts = [
+        { content: "User's name is Alex", factType: "identity" },
+      ];
+      const memories = [
+        { content: "User mentioned they like TypeScript" },
+      ];
+
+      const response = await generateResponse("Hello", memories, facts);
+
+      expect(response).toContain("Alex");
+      expect(response).toContain("TypeScript");
+    });
+
+    it("handles facts without factType", async () => {
+      delete process.env.OPENAI_API_KEY;
+
+      const { generateResponse } = await import("../llm.js");
+
+      const facts = [{ content: "Some fact without type" }];
+
+      const response = await generateResponse("Hello", [], facts);
+
+      expect(response).toContain("Some fact without type");
+      // Should not have brackets for type
+      expect(response).not.toMatch(/\[\]/);
+    });
+
+    it("handles memories without content", async () => {
+      delete process.env.OPENAI_API_KEY;
+
+      const { generateResponse } = await import("../llm.js");
+
+      const memories = [{ content: undefined } as { content?: string }];
+
+      // Should not throw
+      const response = await generateResponse("Hello", memories, []);
+
+      expect(response).toBeDefined();
+    });
+  });
+
+  describe("system prompt", () => {
+    it("includes capabilities and guidelines", async () => {
+      process.env.OPENAI_API_KEY = "sk-test-key";
+
+      let capturedMessages: unknown[] = [];
+      vi.doMock("openai", () => ({
+        default: vi.fn().mockImplementation(() => ({
+          chat: {
+            completions: {
+              create: vi.fn().mockImplementation((opts: { messages: unknown[] }) => {
+                capturedMessages = opts.messages;
+                return { choices: [{ message: { content: "response" } }] };
+              }),
+            },
+          },
+        })),
+      }));
+
+      const { generateResponse } = await import("../llm.js");
+
+      await generateResponse("Hello", [], []);
+
+      const systemMessage = capturedMessages.find(
+        (m: unknown) => (m as { role: string }).role === "system",
+      ) as { content: string } | undefined;
+
+      expect(systemMessage?.content).toContain("Cortex");
+      expect(systemMessage?.content).toContain("remember");
+      expect(systemMessage?.content).toContain("recall");
+    });
+  });
+});

package/templates/basic/src/chat.ts

@@ -0,0 +1,300 @@
+/**
+ * Core Chat Logic
+ *
+ * Handles the chat flow: recall → generate response → remember
+ * This mirrors the Vercel AI quickstart's chat route logic.
+ */
+
+import {
+  getCortex,
+  CONFIG,
+  buildRememberParams,
+  createLayerObserver,
+} from "./cortex.js";
+import {
+  printRecallResults,
+  printOrchestrationComplete,
+  printInfo,
+  startSpinner,
+  stopSpinner,
+} from "./display.js";
+import { generateResponse, isLLMAvailable } from "./llm.js";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Types
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export interface ChatResult {
+  response: string;
+  conversationId: string;
+  memoriesRecalled: number;
+  factsRecalled: number;
+}
+
+export interface Memory {
+  content?: string;
+  importance?: number;
+  source?: string;
+  conversationId?: string;
+}
+
+export interface Fact {
+  content?: string;
+  factType?: string;
+  confidence?: number;
+  subject?: string;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Conversation State
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+let currentConversationId: string | null = null;
+
+/**
+ * Generate a new conversation ID
+ */
+export function generateConversationId(): string {
+  return `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Get or create current conversation ID
+ */
+export function getConversationId(): string {
+  if (!currentConversationId) {
+    currentConversationId = generateConversationId();
+  }
+  return currentConversationId;
+}
+
+/**
+ * Start a new conversation
+ */
+export function newConversation(): string {
+  currentConversationId = generateConversationId();
+  printInfo(`Started new conversation: ${currentConversationId}`);
+  return currentConversationId;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Main Chat Function
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Process a chat message through the full memory pipeline
+ *
+ * 1. Recall relevant memories and facts
+ * 2. Generate response (LLM or echo)
+ * 3. Remember the exchange (triggers layer orchestration)
+ */
+export async function chat(
+  userMessage: string,
+  conversationId?: string,
+): Promise<ChatResult> {
+  const cortex = getCortex();
+  const convId = conversationId || getConversationId();
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Step 1: Recall relevant memories
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  let memories: Memory[] = [];
+  let facts: Fact[] = [];
+
+  startSpinner("Searching memories...");
+
+  try {
+    // Use the unified recall API (v0.23.0+)
+    const recallResult = await cortex.memory.recall({
+      memorySpaceId: CONFIG.memorySpaceId,
+      query: userMessage,
+      limit: 10,
+      sources: {
+        vector: true,
+        facts: true,
+        graph: CONFIG.enableGraphMemory,
+      },
+    });
+
+    // Extract memories and facts from the correct result structure
+    // SDK returns: result.sources.vector.items and result.sources.facts.items
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = recallResult as any;
+    memories = (result.sources?.vector?.items || result.memories || []) as Memory[];
+    facts = (result.sources?.facts?.items || result.facts || []) as Fact[];
+
+    stopSpinner(true, `Found ${memories.length} memories, ${facts.length} facts`);
+
+    // Display recall results
+    printRecallResults(memories, facts);
+  } catch (error) {
+    stopSpinner(false, "No memories found (starting fresh)");
+    // Recall might fail if no memories exist yet - that's ok
+    if (CONFIG.debug) {
+      console.log("[Debug] Recall error (may be empty):", error);
+    }
+  }
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Step 2: Generate response
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  startSpinner("Thinking...");
+  const response = await generateResponse(userMessage, memories, facts);
+  stopSpinner(true, "Response generated");
+
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Step 3: Remember the exchange (triggers orchestration)
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  const startTime = Date.now();
+
+  try {
+    const params = await buildRememberParams({
+      userMessage,
+      agentResponse: response,
+      conversationId: convId,
+    });
+
+    // Add layer observer for console output - uses 'observer' not 'layerObserver'
+    await cortex.memory.remember({
+      ...params,
+      observer: createLayerObserver(),
+    });
+
+    // Print orchestration summary
+    const totalMs = Date.now() - startTime;
+    printOrchestrationComplete(totalMs);
+  } catch (error) {
+    console.error("Failed to store memory:", error);
+    // Still return the response even if storage fails
+  }
+
+  return {
+    response,
+    conversationId: convId,
+    memoriesRecalled: memories.length,
+    factsRecalled: facts.length,
+  };
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Query Functions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Search memories without storing anything
+ */
+export async function recallMemories(query: string): Promise<void> {
+  const cortex = getCortex();
+
+  startSpinner("Searching memories...");
+
+  try {
+    const recallResult = await cortex.memory.recall({
+      memorySpaceId: CONFIG.memorySpaceId,
+      query,
+      limit: 10,
+      sources: {
+        vector: true,
+        facts: true,
+        graph: CONFIG.enableGraphMemory,
+      },
+    });
+
+    // Extract from correct result structure
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = recallResult as any;
+    const memories = (result.sources?.vector?.items || result.memories || []) as Memory[];
+    const facts = (result.sources?.facts?.items || result.facts || []) as Fact[];
+
+    stopSpinner(true, `Found ${memories.length} memories, ${facts.length} facts`);
+    printRecallResults(memories, facts);
+  } catch (error) {
+    stopSpinner(false, "Recall failed");
+    console.error("Recall failed:", error);
+  }
+}
+
+/**
+ * List all facts in the memory space
+ */
+export async function listFacts(): Promise<void> {
+  const cortex = getCortex();
+
+  startSpinner("Loading facts...");
+
+  try {
+    const result = await cortex.facts.list({
+      memorySpaceId: CONFIG.memorySpaceId,
+      limit: 20,
+    });
+
+    const facts = (result.facts || result || []) as Fact[];
+
+    stopSpinner(true, `Found ${facts.length} facts`);
+    printRecallResults([], facts);
+  } catch (error) {
+    stopSpinner(false, "Failed to load facts");
+    console.error("List facts failed:", error);
+  }
+}
+
+/**
+ * Get conversation history
+ */
+export async function getHistory(): Promise<void> {
+  const cortex = getCortex();
+  const convId = currentConversationId;
+
+  if (!convId) {
+    printInfo("No active conversation");
+    return;
+  }
+
+  startSpinner("Loading history...");
+
+  try {
+    const conversation = await cortex.conversations.get(convId);
+
+    if (conversation && conversation.messages) {
+      stopSpinner(true, `Found ${conversation.messages.length} messages`);
+      console.log("");
+      console.log(`📜 Conversation: ${convId}`);
+      console.log(`   Messages: ${conversation.messages.length}`);
+      console.log("");
+
+      for (const msg of conversation.messages.slice(-10)) {
+        const role = msg.role === "user" ? "You" : "Assistant";
+        const content =
+          typeof msg.content === "string"
+            ? msg.content
+            : JSON.stringify(msg.content);
+        console.log(`   ${role}: ${content.slice(0, 60)}${content.length > 60 ? "..." : ""}`);
+      }
+      console.log("");
+    } else {
+      stopSpinner(false, "Conversation not found or empty");
+    }
+  } catch (error) {
+    stopSpinner(false, "Failed to load history");
+    console.error("Get history failed:", error);
+  }
+}
+
+/**
+ * Print current configuration
+ */
+export function printConfig(): void {
+  console.log("");
+  console.log("⚙️  Configuration:");
+  console.log(`   Memory Space: ${CONFIG.memorySpaceId}`);
+  console.log(`   User: ${CONFIG.userId} (${CONFIG.userName})`);
+  console.log(`   Agent: ${CONFIG.agentId} (${CONFIG.agentName})`);
+  console.log(`   Fact Extraction: ${CONFIG.enableFactExtraction ? "enabled" : "disabled"}`);
+  console.log(`   Graph Sync: ${CONFIG.enableGraphMemory ? "enabled" : "disabled"}`);
+  console.log(`   LLM: ${isLLMAvailable() ? "OpenAI (enabled)" : "Echo mode (no API key)"}`);
+  console.log(`   Conversation: ${currentConversationId || "none"}`);
+  console.log("");
+}