@cortexmemory/cli 0.27.3 → 0.28.0

package/templates/basic/package.json

@@ -1,22 +1,40 @@
 {
   "name": "{{PROJECT_NAME}}",
-  "version": "0.1.1",
-  "description": "AI agent with Cortex Memory SDK",
+  "version": "1.0.0",
+  "description": "AI agent with Cortex Memory SDK - demonstrating memory orchestration",
   "type": "module",
   "scripts": {
     "dev": "node dev-runner.mjs",
+    "start": "tsx --env-file=.env.local src/index.ts",
+    "server": "tsx --env-file=.env.local src/server.ts",
     "build": "tsc && npm run build:convex",
     "build:convex": "convex deploy",
-    "start": "tsx --env-file=.env.local src/index.ts"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
   },
   "dependencies": {
     "@cortexmemory/sdk": "latest",
     "convex": "^1.31.2",
-    "dotenv": "^17.2.3"
+    "dotenv": "^17.2.3",
+    "hono": "^4.11.3",
+    "@hono/node-server": "^1.19.7"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
     "typescript": "^5.9.3",
-    "tsx": "^4.21.0"
+    "tsx": "^4.21.0",
+    "vitest": "^4.0.16"
+  },
+  "optionalDependencies": {
+    "openai": "^6.15.0"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

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

@@ -0,0 +1,340 @@
+/**
+ * Unit tests for chat.ts
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+// Create mock functions we can control
+const mockRecall = vi.fn();
+const mockRemember = vi.fn();
+const mockFactsList = vi.fn();
+const mockConversationsGet = vi.fn();
+
+const mockCortex = {
+  memory: {
+    recall: mockRecall,
+    remember: mockRemember,
+  },
+  facts: {
+    list: mockFactsList,
+  },
+  conversations: {
+    get: mockConversationsGet,
+  },
+};
+
+// Mock dependencies
+vi.mock("../cortex.js", () => ({
+  getCortex: vi.fn(() => mockCortex),
+  CONFIG: {
+    memorySpaceId: "test-space",
+    userId: "test-user",
+    userName: "Test User",
+    agentId: "test-agent",
+    agentName: "Test Agent",
+    enableFactExtraction: true,
+    enableGraphMemory: false,
+    debug: false,
+  },
+  buildRememberParams: vi.fn().mockResolvedValue({
+    memorySpaceId: "test-space",
+    conversationId: "conv-123",
+    userId: "test-user",
+    agentId: "test-agent",
+    userMessage: "Hello",
+    agentResponse: "Hi there",
+  }),
+  createLayerObserver: vi.fn().mockReturnValue({
+    onOrchestrationStart: vi.fn(),
+    onLayerUpdate: vi.fn(),
+    onOrchestrationComplete: vi.fn(),
+  }),
+}));
+
+vi.mock("../display.js", () => ({
+  printRecallResults: vi.fn(),
+  printOrchestrationComplete: vi.fn(),
+  printInfo: vi.fn(),
+}));
+
+vi.mock("../llm.js", () => ({
+  generateResponse: vi.fn().mockResolvedValue("Test response"),
+  isLLMAvailable: vi.fn().mockReturnValue(false),
+}));
+
+describe("chat", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset default mock behaviors
+    mockRecall.mockResolvedValue({ memories: [], facts: [] });
+    mockRemember.mockResolvedValue({});
+    mockFactsList.mockResolvedValue({ facts: [] });
+    mockConversationsGet.mockResolvedValue(null);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("generateConversationId", () => {
+    it("generates unique IDs", async () => {
+      const { generateConversationId } = await import("../chat.js");
+
+      const id1 = generateConversationId();
+      const id2 = generateConversationId();
+
+      expect(id1).not.toBe(id2);
+    });
+
+    it("generates IDs with correct format", async () => {
+      const { generateConversationId } = await import("../chat.js");
+
+      const id = generateConversationId();
+
+      expect(id).toMatch(/^conv-\d+-[a-z0-9]+$/);
+    });
+  });
+
+  describe("getConversationId", () => {
+    it("creates a new conversation ID if none exists", async () => {
+      vi.resetModules();
+      const { getConversationId } = await import("../chat.js");
+
+      const id = getConversationId();
+
+      expect(id).toMatch(/^conv-\d+-[a-z0-9]+$/);
+    });
+
+    it("returns the same ID on subsequent calls", async () => {
+      vi.resetModules();
+      const { getConversationId } = await import("../chat.js");
+
+      const id1 = getConversationId();
+      const id2 = getConversationId();
+
+      expect(id1).toBe(id2);
+    });
+  });
+
+  describe("newConversation", () => {
+    it("creates a new conversation ID", async () => {
+      vi.resetModules();
+      const { newConversation, getConversationId } = await import("../chat.js");
+
+      const oldId = getConversationId();
+      const newId = newConversation();
+
+      expect(newId).not.toBe(oldId);
+    });
+
+    it("prints info message", async () => {
+      const { printInfo } = await import("../display.js");
+      vi.resetModules();
+      const { newConversation } = await import("../chat.js");
+
+      newConversation();
+
+      expect(printInfo).toHaveBeenCalledWith(
+        expect.stringContaining("Started new conversation"),
+      );
+    });
+  });
+
+  describe("chat", () => {
+    it("calls recall, generate, and remember in sequence", async () => {
+      mockRecall.mockResolvedValue({ memories: [], facts: [] });
+      mockRemember.mockResolvedValue({});
+
+      const { generateResponse } = await import("../llm.js");
+      vi.mocked(generateResponse).mockResolvedValue("Test response");
+
+      vi.resetModules();
+      const { chat } = await import("../chat.js");
+
+      const result = await chat("Hello", "conv-123");
+
+      expect(mockRecall).toHaveBeenCalled();
+      expect(generateResponse).toHaveBeenCalledWith("Hello", [], []);
+      expect(mockRemember).toHaveBeenCalled();
+      expect(result.response).toBe("Test response");
+    });
+
+    it("returns conversation ID and recall counts", async () => {
+      mockRecall.mockResolvedValue({
+        memories: [{ content: "mem1" }],
+        facts: [{ content: "fact1" }, { content: "fact2" }],
+      });
+      mockRemember.mockResolvedValue({});
+
+      vi.resetModules();
+      const { chat } = await import("../chat.js");
+
+      const result = await chat("Hello", "conv-123");
+
+      expect(result.conversationId).toBe("conv-123");
+      expect(result.memoriesRecalled).toBe(1);
+      expect(result.factsRecalled).toBe(2);
+    });
+
+    it("handles recall errors gracefully", async () => {
+      // Reset the generateResponse mock to ensure it returns expected value
+      const { generateResponse } = await import("../llm.js");
+      vi.mocked(generateResponse).mockResolvedValue("Test response");
+
+      // Import chat first before setting up error behavior
+      const { chat, generateConversationId } = await import("../chat.js");
+
+      // Now set up the error
+      mockRecall.mockRejectedValueOnce(new Error("Recall failed"));
+      mockRemember.mockResolvedValue({});
+
+      // Should not throw
+      const convId = generateConversationId();
+      const result = await chat("Hello", convId);
+
+      expect(result.response).toBe("Test response");
+      expect(result.memoriesRecalled).toBe(0);
+      expect(result.factsRecalled).toBe(0);
+    });
+
+    it("still returns response if remember fails", async () => {
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      // Reset the generateResponse mock to ensure it returns expected value
+      const { generateResponse } = await import("../llm.js");
+      vi.mocked(generateResponse).mockResolvedValue("Test response");
+
+      // Import chat first
+      const { chat, generateConversationId } = await import("../chat.js");
+
+      // Now set up the behaviors
+      mockRecall.mockResolvedValueOnce({ memories: [], facts: [] });
+      mockRemember.mockRejectedValueOnce(new Error("Remember failed"));
+
+      const convId = generateConversationId();
+      const result = await chat("Hello", convId);
+
+      expect(result.response).toBe("Test response");
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "Failed to store memory:",
+        expect.any(Error),
+      );
+
+      consoleSpy.mockRestore();
+    });
+
+    it("uses current conversation ID if none provided", async () => {
+      mockRecall.mockResolvedValue({ memories: [], facts: [] });
+      mockRemember.mockResolvedValue({});
+
+      vi.resetModules();
+      const { chat, getConversationId } = await import("../chat.js");
+
+      const currentId = getConversationId();
+      const result = await chat("Hello");
+
+      expect(result.conversationId).toBe(currentId);
+    });
+  });
+
+  describe("recallMemories", () => {
+    it("searches and prints results", async () => {
+      mockRecall.mockResolvedValue({
+        memories: [{ content: "test memory" }],
+        facts: [{ content: "test fact" }],
+      });
+
+      const { printRecallResults } = await import("../display.js");
+
+      vi.resetModules();
+      const { recallMemories } = await import("../chat.js");
+
+      await recallMemories("test query");
+
+      expect(mockRecall).toHaveBeenCalledWith(
+        expect.objectContaining({
+          query: "test query",
+        }),
+      );
+      expect(printRecallResults).toHaveBeenCalled();
+    });
+
+    it("handles errors gracefully", async () => {
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      mockRecall.mockRejectedValue(new Error("Search failed"));
+
+      vi.resetModules();
+      const { recallMemories } = await import("../chat.js");
+
+      await recallMemories("test query");
+
+      expect(consoleSpy).toHaveBeenCalledWith(
+        "Recall failed:",
+        expect.any(Error),
+      );
+
+      consoleSpy.mockRestore();
+    });
+  });
+
+  describe("listFacts", () => {
+    it("lists facts and prints results", async () => {
+      mockFactsList.mockResolvedValue({
+        facts: [{ content: "fact 1" }, { content: "fact 2" }],
+      });
+
+      const { printRecallResults } = await import("../display.js");
+
+      vi.resetModules();
+      const { listFacts } = await import("../chat.js");
+
+      await listFacts();
+
+      expect(mockFactsList).toHaveBeenCalled();
+      expect(printRecallResults).toHaveBeenCalledWith(
+        [],
+        expect.arrayContaining([
+          expect.objectContaining({ content: "fact 1" }),
+        ]),
+      );
+    });
+  });
+
+  describe("getHistory", () => {
+    it("prints info when no conversation is active", async () => {
+      const { printInfo } = await import("../display.js");
+
+      vi.resetModules();
+      const { getHistory } = await import("../chat.js");
+
+      // getHistory will call getCortex and use the mock
+      await getHistory();
+
+      // Without a conversation ID, it should print info
+      expect(printInfo).toHaveBeenCalled();
+    });
+  });
+
+  describe("printConfig", () => {
+    it("prints configuration details", async () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      vi.resetModules();
+      const { printConfig } = await import("../chat.js");
+
+      printConfig();
+
+      const output = consoleSpy.mock.calls.flat().join("\n");
+      expect(output).toContain("Configuration:");
+      expect(output).toContain("Memory Space:");
+      expect(output).toContain("User:");
+      expect(output).toContain("Agent:");
+      expect(output).toContain("Fact Extraction:");
+      expect(output).toContain("Graph Sync:");
+      expect(output).toContain("LLM:");
+
+      consoleSpy.mockRestore();
+    });
+  });
+});

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

@@ -0,0 +1,260 @@
+/**
+ * Unit tests for cortex.ts
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+// Mock the display module before importing cortex
+vi.mock("../display.js", () => ({
+  printLayerUpdate: vi.fn(),
+  printOrchestrationStart: vi.fn(),
+}));
+
+describe("cortex", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    vi.clearAllMocks();
+  });
+
+  describe("CONFIG", () => {
+    it("uses default values when environment variables are not set", async () => {
+      delete process.env.MEMORY_SPACE_ID;
+      delete process.env.USER_ID;
+      delete process.env.USER_NAME;
+      delete process.env.AGENT_ID;
+      delete process.env.AGENT_NAME;
+      delete process.env.CORTEX_FACT_EXTRACTION;
+      delete process.env.CORTEX_GRAPH_SYNC;
+      delete process.env.DEBUG;
+
+      const { CONFIG } = await import("../cortex.js");
+
+      expect(CONFIG.memorySpaceId).toBe("basic-demo");
+      expect(CONFIG.userId).toBe("demo-user");
+      expect(CONFIG.userName).toBe("Demo User");
+      expect(CONFIG.agentId).toBe("basic-assistant");
+      expect(CONFIG.agentName).toBe("Cortex CLI Assistant");
+      expect(CONFIG.enableFactExtraction).toBe(true);
+      expect(CONFIG.enableGraphMemory).toBe(false);
+      expect(CONFIG.debug).toBe(false);
+    });
+
+    it("uses environment variables when set", async () => {
+      process.env.MEMORY_SPACE_ID = "custom-space";
+      process.env.USER_ID = "custom-user";
+      process.env.USER_NAME = "Custom User";
+      process.env.AGENT_ID = "custom-agent";
+      process.env.AGENT_NAME = "Custom Agent";
+      process.env.CORTEX_FACT_EXTRACTION = "false";
+      process.env.CORTEX_GRAPH_SYNC = "true";
+      process.env.DEBUG = "true";
+
+      const { CONFIG } = await import("../cortex.js");
+
+      expect(CONFIG.memorySpaceId).toBe("custom-space");
+      expect(CONFIG.userId).toBe("custom-user");
+      expect(CONFIG.userName).toBe("Custom User");
+      expect(CONFIG.agentId).toBe("custom-agent");
+      expect(CONFIG.agentName).toBe("Custom Agent");
+      expect(CONFIG.enableFactExtraction).toBe(false);
+      expect(CONFIG.enableGraphMemory).toBe(true);
+      expect(CONFIG.debug).toBe(true);
+    });
+  });
+
+  describe("getCortex", () => {
+    it("throws error when CONVEX_URL is not set", async () => {
+      delete process.env.CONVEX_URL;
+
+      const { getCortex } = await import("../cortex.js");
+
+      expect(() => getCortex()).toThrow("CONVEX_URL environment variable is required");
+    });
+
+    it("creates Cortex client when CONVEX_URL is set", async () => {
+      process.env.CONVEX_URL = "https://test.convex.cloud";
+
+      // Mock Cortex SDK
+      vi.doMock("@cortexmemory/sdk", () => ({
+        Cortex: vi.fn().mockImplementation(() => ({
+          memory: {},
+          close: vi.fn(),
+        })),
+      }));
+
+      const { getCortex } = await import("../cortex.js");
+      const cortex = getCortex();
+
+      expect(cortex).toBeDefined();
+      expect(cortex.memory).toBeDefined();
+    });
+
+    it("returns same instance on subsequent calls (singleton)", async () => {
+      process.env.CONVEX_URL = "https://test.convex.cloud";
+
+      vi.doMock("@cortexmemory/sdk", () => ({
+        Cortex: vi.fn().mockImplementation(() => ({
+          memory: {},
+          close: vi.fn(),
+        })),
+      }));
+
+      const { getCortex } = await import("../cortex.js");
+
+      const instance1 = getCortex();
+      const instance2 = getCortex();
+
+      expect(instance1).toBe(instance2);
+    });
+  });
+
+  describe("closeCortex", () => {
+    it("closes the client and resets singleton", async () => {
+      process.env.CONVEX_URL = "https://test.convex.cloud";
+
+      const closeMock = vi.fn();
+      vi.doMock("@cortexmemory/sdk", () => ({
+        Cortex: vi.fn().mockImplementation(() => ({
+          memory: {},
+          close: closeMock,
+        })),
+      }));
+
+      const { getCortex, closeCortex } = await import("../cortex.js");
+
+      getCortex(); // Create instance
+      closeCortex();
+
+      expect(closeMock).toHaveBeenCalled();
+    });
+
+    it("does nothing when no client exists", async () => {
+      const { closeCortex } = await import("../cortex.js");
+
+      // Should not throw
+      expect(() => closeCortex()).not.toThrow();
+    });
+  });
+
+  describe("createLayerObserver", () => {
+    it("returns an observer with required methods", async () => {
+      const { createLayerObserver } = await import("../cortex.js");
+
+      const observer = createLayerObserver();
+
+      expect(observer).toHaveProperty("onOrchestrationStart");
+      expect(observer).toHaveProperty("onLayerUpdate");
+      expect(observer).toHaveProperty("onOrchestrationComplete");
+      expect(typeof observer.onOrchestrationStart).toBe("function");
+      expect(typeof observer.onLayerUpdate).toBe("function");
+      expect(typeof observer.onOrchestrationComplete).toBe("function");
+    });
+
+    it("calls printOrchestrationStart on orchestration start", async () => {
+      const { printOrchestrationStart } = await import("../display.js");
+      const { createLayerObserver } = await import("../cortex.js");
+
+      const observer = createLayerObserver();
+      observer.onOrchestrationStart("test-id");
+
+      expect(printOrchestrationStart).toHaveBeenCalledWith("test-id");
+    });
+
+    it("calls printLayerUpdate on layer update", async () => {
+      const { printLayerUpdate } = await import("../display.js");
+      const { createLayerObserver } = await import("../cortex.js");
+
+      const observer = createLayerObserver();
+      const event = {
+        layer: "facts",
+        status: "complete" as const,
+        timestamp: Date.now(),
+        latencyMs: 100,
+      };
+      observer.onLayerUpdate(event);
+
+      expect(printLayerUpdate).toHaveBeenCalledWith(event);
+    });
+  });
+
+  describe("getEmbeddingProvider", () => {
+    it("returns undefined when OPENAI_API_KEY is not set", async () => {
+      delete process.env.OPENAI_API_KEY;
+
+      const { getEmbeddingProvider } = await import("../cortex.js");
+      const provider = await getEmbeddingProvider();
+
+      expect(provider).toBeUndefined();
+    });
+
+    it("returns embedding function when OPENAI_API_KEY is set", async () => {
+      process.env.OPENAI_API_KEY = "sk-test-key";
+
+      // Mock OpenAI
+      vi.doMock("openai", () => ({
+        default: vi.fn().mockImplementation(() => ({
+          embeddings: {
+            create: vi.fn().mockResolvedValue({
+              data: [{ embedding: new Array(1536).fill(0.1) }],
+            }),
+          },
+        })),
+      }));
+
+      const { getEmbeddingProvider } = await import("../cortex.js");
+      const provider = await getEmbeddingProvider();
+
+      expect(provider).toBeDefined();
+      expect(typeof provider).toBe("function");
+    });
+  });
+
+  describe("buildRememberParams", () => {
+    it("builds params with CONFIG values", async () => {
+      delete process.env.OPENAI_API_KEY;
+
+      const { buildRememberParams, CONFIG } = await import("../cortex.js");
+
+      const params = await buildRememberParams({
+        userMessage: "Hello",
+        agentResponse: "Hi there",
+        conversationId: "conv-123",
+      });
+
+      expect(params.memorySpaceId).toBe(CONFIG.memorySpaceId);
+      expect(params.userId).toBe(CONFIG.userId);
+      expect(params.userName).toBe(CONFIG.userName);
+      expect(params.agentId).toBe(CONFIG.agentId);
+      expect(params.userMessage).toBe("Hello");
+      expect(params.agentResponse).toBe("Hi there");
+      expect(params.conversationId).toBe("conv-123");
+    });
+
+    it("includes belief revision when fact extraction is enabled", async () => {
+      delete process.env.OPENAI_API_KEY;
+      process.env.CORTEX_FACT_EXTRACTION = "true";
+
+      const { buildRememberParams } = await import("../cortex.js");
+
+      const params = await buildRememberParams({
+        userMessage: "Hello",
+        agentResponse: "Hi",
+        conversationId: "conv-123",
+      });
+
+      expect(params.extractFacts).toBe(true);
+      expect(params.beliefRevision).toEqual({
+        enabled: true,
+        slotMatching: true,
+        llmResolution: false, // No OpenAI key
+      });
+    });
+  });
+});