@cortexmemory/cli 0.27.4 → 0.28.0

package/templates/basic/src/server.ts

@@ -0,0 +1,280 @@
+/**
+ * Cortex Memory - HTTP Server Mode
+ *
+ * REST API server for demonstrating Cortex Memory SDK.
+ * Useful for testing with tools like curl, Postman, or integrating with other apps.
+ *
+ * Usage:
+ *   npm run server
+ *
+ * Endpoints:
+ *   POST /chat          Chat and store memory
+ *   GET  /recall        Search memories
+ *   GET  /facts         List stored facts
+ *   GET  /history/:id   Get conversation history
+ *   GET  /health        Health check
+ */
+
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+import { closeCortex, CONFIG } from "./cortex.js";
+import {
+  chat,
+  recallMemories,
+  listFacts,
+  generateConversationId,
+} from "./chat.js";
+import { printWelcome, printInfo, printError } from "./display.js";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Setup
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const app = new Hono();
+
+// Middleware
+app.use("*", cors());
+app.use("*", logger());
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Routes
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Health check
+ */
+app.get("/health", (c) => {
+  return c.json({
+    status: "ok",
+    memorySpaceId: CONFIG.memorySpaceId,
+    agentId: CONFIG.agentId,
+    features: {
+      factExtraction: CONFIG.enableFactExtraction,
+      graphSync: CONFIG.enableGraphMemory,
+      llm: !!process.env.OPENAI_API_KEY,
+    },
+  });
+});
+
+/**
+ * Chat endpoint
+ *
+ * POST /chat
+ * Body: { message: string, conversationId?: string }
+ */
+app.post("/chat", async (c) => {
+  try {
+    const body = await c.req.json();
+    const { message, conversationId } = body;
+
+    if (!message || typeof message !== "string") {
+      return c.json({ error: "message is required" }, 400);
+    }
+
+    const convId = conversationId || generateConversationId();
+
+    console.log(`\n[Chat] User: ${message.slice(0, 50)}${message.length > 50 ? "..." : ""}`);
+
+    const result = await chat(message, convId);
+
+    console.log(`[Chat] Response sent (${result.memoriesRecalled} memories, ${result.factsRecalled} facts recalled)\n`);
+
+    return c.json({
+      response: result.response,
+      conversationId: result.conversationId,
+      memoriesRecalled: result.memoriesRecalled,
+      factsRecalled: result.factsRecalled,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    printError("Chat failed", error instanceof Error ? error : undefined);
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Recall endpoint
+ *
+ * GET /recall?query=<query>
+ */
+app.get("/recall", async (c) => {
+  try {
+    const query = c.req.query("query");
+
+    if (!query) {
+      return c.json({ error: "query parameter is required" }, 400);
+    }
+
+    console.log(`\n[Recall] Query: ${query}`);
+
+    // Use the internal recall function but capture results
+    const { getCortex } = await import("./cortex.js");
+    const cortex = getCortex();
+
+    const result = await cortex.memory.recall({
+      memorySpaceId: CONFIG.memorySpaceId,
+      query,
+      limit: 10,
+      sources: {
+        vector: true,
+        facts: true,
+        graph: CONFIG.enableGraphMemory,
+      },
+    });
+
+    console.log(`[Recall] Found ${result.memories?.length || 0} memories, ${result.facts?.length || 0} facts\n`);
+
+    return c.json({
+      memories: result.memories || [],
+      facts: result.facts || [],
+      query,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Facts endpoint
+ *
+ * GET /facts
+ */
+app.get("/facts", async (c) => {
+  try {
+    const { getCortex } = await import("./cortex.js");
+    const cortex = getCortex();
+
+    const result = await cortex.facts.list({
+      memorySpaceId: CONFIG.memorySpaceId,
+      limit: 50,
+    });
+
+    const facts = result.facts || result || [];
+
+    return c.json({ facts, count: facts.length });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Conversation history endpoint
+ *
+ * GET /history/:conversationId
+ */
+app.get("/history/:conversationId", async (c) => {
+  try {
+    const conversationId = c.req.param("conversationId");
+
+    const { getCortex } = await import("./cortex.js");
+    const cortex = getCortex();
+
+    const conversation = await cortex.conversations.get(conversationId);
+
+    if (!conversation) {
+      return c.json({ error: "Conversation not found" }, 404);
+    }
+
+    return c.json({
+      conversationId,
+      messages: conversation.messages || [],
+      messageCount: conversation.messages?.length || 0,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return c.json({ error: message }, 500);
+  }
+});
+
+/**
+ * Root endpoint - API docs
+ */
+app.get("/", (c) => {
+  return c.json({
+    name: "Cortex Memory - Basic Demo API",
+    version: "1.0.0",
+    endpoints: {
+      "POST /chat": {
+        description: "Chat and store memory",
+        body: { message: "string", conversationId: "string (optional)" },
+      },
+      "GET /recall": {
+        description: "Search memories",
+        query: { query: "string" },
+      },
+      "GET /facts": {
+        description: "List all stored facts",
+      },
+      "GET /history/:id": {
+        description: "Get conversation history",
+      },
+      "GET /health": {
+        description: "Health check",
+      },
+    },
+  });
+});
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Server Start
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const PORT = parseInt(process.env.PORT || "3001", 10);
+
+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",
+    );
+    process.exit(1);
+  }
+
+  // Print welcome
+  printWelcome("server");
+
+  // Start server
+  console.log(`🚀 Server starting on http://localhost:${PORT}`);
+  console.log("");
+  console.log("Endpoints:");
+  console.log(`   POST http://localhost:${PORT}/chat`);
+  console.log(`   GET  http://localhost:${PORT}/recall?query=...`);
+  console.log(`   GET  http://localhost:${PORT}/facts`);
+  console.log(`   GET  http://localhost:${PORT}/history/:id`);
+  console.log(`   GET  http://localhost:${PORT}/health`);
+  console.log("");
+  console.log("Example:");
+  console.log(`   curl -X POST http://localhost:${PORT}/chat \\`);
+  console.log('     -H "Content-Type: application/json" \\');
+  console.log('     -d \'{"message": "My name is Alex"}\'');
+  console.log("");
+
+  serve({
+    fetch: app.fetch,
+    port: PORT,
+  });
+
+  printInfo(`Server running on port ${PORT}`);
+}
+
+// Handle cleanup
+process.on("SIGINT", () => {
+  console.log("\n\nShutting down...");
+  closeCortex();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  closeCortex();
+  process.exit(0);
+});
+
+// Run
+main().catch((error) => {
+  printError("Fatal error", error instanceof Error ? error : undefined);
+  process.exit(1);
+});

package/templates/basic/vitest.config.ts

@@ -0,0 +1,33 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: [
+      "src/**/*.test.ts",
+      "src/__tests__/**/*.test.ts",
+    ],
+    // Unit tests run fast
+    testTimeout: 10000,
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/*.test.ts",
+        "src/__tests__/**",
+        "src/index.ts", // Entry point, tested via integration
+        "src/server.ts", // Entry point, tested via integration
+      ],
+    },
+    clearMocks: true,
+    restoreMocks: true,
+    // Separate pools for different test types
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});

package/templates/basic/vitest.e2e.config.ts

@@ -0,0 +1,28 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Configuration for E2E tests.
+ * These tests require real Convex backend and optionally OpenAI API key.
+ *
+ * Run with:
+ *   CONVEX_URL=<url> npm run test:e2e
+ *   CONVEX_URL=<url> OPENAI_API_KEY=<key> npm run test:e2e
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/__tests__/e2e/**/*.test.ts"],
+    testTimeout: 180000, // 3 minutes for E2E tests (fact extraction takes time)
+    hookTimeout: 60000, // 1 minute for setup/teardown
+    clearMocks: true,
+    restoreMocks: true,
+    // Run E2E tests sequentially to avoid rate limits
+    pool: "forks",
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});

package/templates/basic/vitest.integration.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from "vitest/config";
+
+/**
+ * Configuration for integration tests.
+ * These tests use mocked SDK but test real component interactions.
+ */
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/__tests__/integration/**/*.test.ts"],
+    testTimeout: 30000, // 30 seconds for integration tests
+    coverage: {
+      provider: "v8",
+      reporter: ["text", "json", "html"],
+      include: ["src/**/*.ts"],
+      exclude: [
+        "src/**/*.test.ts",
+        "src/__tests__/**",
+      ],
+    },
+    clearMocks: true,
+    restoreMocks: true,
+  },
+});

package/templates/vercel-ai-quickstart/app/api/auth/check/route.ts

@@ -24,7 +24,7 @@ export async function GET() {
 
     return Response.json(
       { error: "Failed to check admin setup status" },
-      { status: 500 }
+      { status: 500 },
     );
   }
 }

package/templates/vercel-ai-quickstart/app/api/auth/login/route.ts

@@ -12,7 +12,7 @@ import { verifyPassword, generateSessionToken } from "@/lib/password";
  * Returns validated credentials or null if invalid.
  */
 function validateLoginBody(
-  body: unknown
+  body: unknown,
 ): { username: string; password: string } | null {
   if (typeof body !== "object" || body === null) {
     return null;
@@ -65,7 +65,7 @@ export async function POST(req: Request) {
     if (!credentials) {
       return Response.json(
         { error: "Username and password are required" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
@@ -79,7 +79,7 @@ export async function POST(req: Request) {
     if (!user) {
       return Response.json(
         { error: "Invalid username or password" },
-        { status: 401 }
+        { status: 401 },
       );
     }
 
@@ -88,7 +88,7 @@ export async function POST(req: Request) {
     if (!storedHash) {
       return Response.json(
         { error: "Invalid username or password" },
-        { status: 401 }
+        { status: 401 },
       );
     }
 
@@ -96,7 +96,7 @@ export async function POST(req: Request) {
     if (!isValid) {
       return Response.json(
         { error: "Invalid username or password" },
-        { status: 401 }
+        { status: 401 },
       );
     }
 
@@ -120,9 +120,6 @@ export async function POST(req: Request) {
     // Log sanitized error to prevent log injection
     console.error("[Login Error]", getSafeErrorMessage(error));
 
-    return Response.json(
-      { error: "Failed to authenticate" },
-      { status: 500 }
-    );
+    return Response.json({ error: "Failed to authenticate" }, { status: 500 });
   }
 }

package/templates/vercel-ai-quickstart/app/api/auth/register/route.ts

@@ -14,39 +14,38 @@ export async function POST(req: Request) {
 
     // Validate input
     if (!username || typeof username !== "string") {
-      return Response.json(
-        { error: "Username is required" },
-        { status: 400 }
-      );
+      return Response.json({ error: "Username is required" }, { status: 400 });
     }
 
     if (!password || typeof password !== "string") {
-      return Response.json(
-        { error: "Password is required" },
-        { status: 400 }
-      );
+      return Response.json({ error: "Password is required" }, { status: 400 });
     }
 
     if (username.length < 2) {
       return Response.json(
         { error: "Username must be at least 2 characters" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
     if (password.length < 4) {
       return Response.json(
         { error: "Password must be at least 4 characters" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
     // Sanitize username (alphanumeric, underscore, hyphen only)
-    const sanitizedUsername = username.toLowerCase().replace(/[^a-z0-9_-]/g, "");
+    const sanitizedUsername = username
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, "");
     if (sanitizedUsername !== username.toLowerCase()) {
       return Response.json(
-        { error: "Username can only contain letters, numbers, underscores, and hyphens" },
-        { status: 400 }
+        {
+          error:
+            "Username can only contain letters, numbers, underscores, and hyphens",
+        },
+        { status: 400 },
       );
     }
 
@@ -57,7 +56,7 @@ export async function POST(req: Request) {
     if (existingUser) {
       return Response.json(
         { error: "Username already taken" },
-        { status: 409 }
+        { status: 409 },
       );
     }
 
@@ -86,9 +85,6 @@ export async function POST(req: Request) {
   } catch (error) {
     console.error("[Register Error]", error);
 
-    return Response.json(
-      { error: "Failed to register user" },
-      { status: 500 }
-    );
+    return Response.json({ error: "Failed to register user" }, { status: 500 });
   }
 }

package/templates/vercel-ai-quickstart/app/api/auth/setup/route.ts

@@ -16,16 +16,13 @@ export async function POST(req: Request) {
     const { password } = body;
 
     if (!password || typeof password !== "string") {
-      return Response.json(
-        { error: "Password is required" },
-        { status: 400 }
-      );
+      return Response.json({ error: "Password is required" }, { status: 400 });
     }
 
     if (password.length < 4) {
       return Response.json(
         { error: "Password must be at least 4 characters" },
-        { status: 400 }
+        { status: 400 },
       );
     }
 
@@ -36,7 +33,7 @@ export async function POST(req: Request) {
     if (existingHash !== null) {
       return Response.json(
         { error: "Admin already configured" },
-        { status: 409 }
+        { status: 409 },
       );
     }
 
@@ -53,7 +50,7 @@ export async function POST(req: Request) {
 
     return Response.json(
       { error: "Failed to configure admin password" },
-      { status: 500 }
+      { status: 500 },
     );
   }
 }

package/templates/vercel-ai-quickstart/app/api/chat/route.ts

@@ -164,7 +164,10 @@ function normalizeMessages(messages: unknown[]): unknown[] {
 /**
  * Extract text from a message (handles both content string and parts array)
  */
-function getMessageText(message: { content?: string; parts?: Array<{ type: string; text?: string }> }): string {
+function getMessageText(message: {
+  content?: string;
+  parts?: Array<{ type: string; text?: string }>;
+}): string {
   if (typeof message.content === "string") {
     return message.content;
   }
@@ -180,7 +183,12 @@ function getMessageText(message: { content?: string; parts?: Array<{ type: strin
 export async function POST(req: Request) {
   try {
     const body = await req.json();
-    const { messages, memorySpaceId, userId, conversationId: providedConversationId } = body;
+    const {
+      messages,
+      memorySpaceId,
+      userId,
+      conversationId: providedConversationId,
+    } = body;
 
     // Validate messages array exists
     if (!messages || !Array.isArray(messages)) {
@@ -191,7 +199,8 @@ export async function POST(req: Request) {
     }
 
     // Generate conversation ID if not provided (new chat)
-    const conversationId = providedConversationId || 
+    const conversationId =
+      providedConversationId ||
       `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const isNewConversation = !providedConversationId;
 
@@ -202,20 +211,28 @@ export async function POST(req: Request) {
     // Convert UIMessage[] from useChat to ModelMessage[] for streamText
     // Note: In AI SDK v6+, convertToModelMessages may return a Promise
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const modelMessagesResult = convertToModelMessages(normalizedMessages as any);
+    const modelMessagesResult = convertToModelMessages(
+      normalizedMessages as any,
+    );
     const modelMessages =
       modelMessagesResult instanceof Promise
         ? await modelMessagesResult
         : modelMessagesResult;
 
     // Get the first user message for title generation
-    const firstUserMessage = messages.find((m: { role: string }) => m.role === "user") as {
-      role: string;
-      content?: string;
-      parts?: Array<{ type: string; text?: string }>;
-    } | undefined;
-    
-    const messageText = firstUserMessage ? getMessageText(firstUserMessage) : "";
+    const firstUserMessage = messages.find(
+      (m: { role: string }) => m.role === "user",
+    ) as
+      | {
+          role: string;
+          content?: string;
+          parts?: Array<{ type: string; text?: string }>;
+        }
+      | undefined;
+
+    const messageText = firstUserMessage
+      ? getMessageText(firstUserMessage)
+      : "";
 
     // Use createUIMessageStream to send both LLM text and layer events
     return createUIMessageStreamResponse({

package/templates/vercel-ai-quickstart/app/api/chat-v6/route.ts

@@ -52,7 +52,7 @@ function getCortexMemoryConfig(
   memorySpaceId: string,
   userId: string,
   conversationId: string,
-  layerObserver?: LayerObserver
+  layerObserver?: LayerObserver,
 ): CortexMemoryConfig {
   return {
     convexUrl: process.env.CONVEX_URL!,
@@ -191,7 +191,7 @@ export async function POST(req: Request) {
     if (!messages || !Array.isArray(messages)) {
       return new Response(
         JSON.stringify({ error: "messages array is required" }),
-        { status: 400, headers: { "Content-Type": "application/json" } }
+        { status: 400, headers: { "Content-Type": "application/json" } },
       );
     }
 
@@ -206,7 +206,9 @@ export async function POST(req: Request) {
 
     // Convert to model messages
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const modelMessagesResult = convertToModelMessages(normalizedMessages as any);
+    const modelMessagesResult = convertToModelMessages(
+      normalizedMessages as any,
+    );
     const modelMessages =
       modelMessagesResult instanceof Promise
         ? await modelMessagesResult
@@ -214,14 +216,18 @@ export async function POST(req: Request) {
 
     // Get first user message for title
     const firstUserMessage = messages.find(
-      (m: { role: string }) => m.role === "user"
-    ) as {
-      role: string;
-      content?: string;
-      parts?: Array<{ type: string; text?: string }>;
-    } | undefined;
-
-    const messageText = firstUserMessage ? getMessageText(firstUserMessage) : "";
+      (m: { role: string }) => m.role === "user",
+    ) as
+      | {
+          role: string;
+          content?: string;
+          parts?: Array<{ type: string; text?: string }>;
+        }
+      | undefined;
+
+    const messageText = firstUserMessage
+      ? getMessageText(firstUserMessage)
+      : "";
 
     // Use createUIMessageStreamResponse - same as v5 for full memory support
     return createUIMessageStreamResponse({
@@ -270,7 +276,7 @@ export async function POST(req: Request) {
             memorySpaceId,
             userId,
             conversationId,
-            layerObserver
+            layerObserver,
           );
 
           // Create memory-augmented model - THIS handles both recall AND storage!
@@ -327,7 +333,7 @@ export async function POST(req: Request) {
       {
         status: 500,
         headers: { "Content-Type": "application/json" },
-      }
+      },
     );
   }
 }