@cortexmemory/cli 0.27.1 → 0.27.4

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

@@ -0,0 +1,333 @@
+/**
+ * Chat API Route (AI SDK v6 Style)
+ *
+ * This route uses AI SDK v6's patterns while maintaining full Cortex Memory
+ * capabilities including:
+ * - Memory recall (reading past memories)
+ * - Memory storage (saving new conversations)
+ * - Fact extraction (extracting knowledge from conversations)
+ * - Belief revision (superseding outdated facts)
+ * - Layer observer (real-time UI updates)
+ *
+ * The key difference from v5 is using v6's cleaner APIs, but the memory
+ * infrastructure is identical to ensure feature parity.
+ */
+
+import { createCortexMemoryAsync } from "@cortexmemory/vercel-ai-provider";
+import type {
+  LayerObserver,
+  CortexMemoryConfig,
+} from "@cortexmemory/vercel-ai-provider";
+import { openai, createOpenAI } from "@ai-sdk/openai";
+import {
+  streamText,
+  embed,
+  convertToModelMessages,
+  createUIMessageStream,
+  createUIMessageStreamResponse,
+} from "ai";
+import { getCortex } from "@/lib/cortex";
+
+// Create OpenAI client for embeddings
+const openaiClient = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+// System prompt for the assistant
+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`;
+
+/**
+ * Create Cortex Memory config - IDENTICAL to v5 route for feature parity
+ */
+function getCortexMemoryConfig(
+  memorySpaceId: string,
+  userId: string,
+  conversationId: string,
+  layerObserver?: LayerObserver
+): CortexMemoryConfig {
+  return {
+    convexUrl: process.env.CONVEX_URL!,
+    memorySpaceId,
+
+    // User identification
+    userId,
+    userName: "Demo User",
+
+    // Agent identification
+    agentId: "cortex-memory-agent",
+    agentName: "Cortex v6 Assistant",
+
+    // Conversation ID for chat history isolation
+    conversationId,
+
+    // Enable graph memory sync
+    enableGraphMemory: process.env.CORTEX_GRAPH_SYNC === "true",
+
+    // Enable fact extraction - CRITICAL for memory to work!
+    enableFactExtraction: process.env.CORTEX_FACT_EXTRACTION === "true",
+
+    // Belief Revision - handles fact updates and supersessions
+    beliefRevision: {
+      enabled: true,
+      slotMatching: true,
+      llmResolution: true,
+    },
+
+    // Embedding provider for semantic matching
+    embeddingProvider: {
+      generate: async (text: string) => {
+        const result = await embed({
+          model: openaiClient.embedding("text-embedding-3-small"),
+          value: text,
+        });
+        return result.embedding;
+      },
+    },
+
+    // Streaming enhancements
+    streamingOptions: {
+      storePartialResponse: true,
+      progressiveFactExtraction: true,
+      enableAdaptiveProcessing: true,
+    },
+
+    // Memory recall configuration
+    memorySearchLimit: 20,
+
+    // Real-time layer tracking
+    layerObserver,
+
+    // Debug in development
+    debug: process.env.NODE_ENV === "development",
+  };
+}
+
+/**
+ * Normalize messages to AI SDK v6 UIMessage format
+ */
+function normalizeMessages(messages: unknown[]): unknown[] {
+  return messages.map((msg: unknown) => {
+    const m = msg as Record<string, unknown>;
+
+    // Normalize role: "agent" -> "assistant"
+    let role = m.role as string;
+    if (role === "agent") {
+      role = "assistant";
+    }
+
+    // Ensure parts array exists
+    let parts = m.parts as Array<{ type: string; text?: string }> | undefined;
+    if (!parts) {
+      const content = m.content as string | undefined;
+      if (content) {
+        parts = [{ type: "text", text: content }];
+      } else {
+        parts = [];
+      }
+    }
+
+    return {
+      ...m,
+      role,
+      parts,
+    };
+  });
+}
+
+/**
+ * Extract text from a message
+ */
+function getMessageText(message: {
+  content?: string;
+  parts?: Array<{ type: string; text?: string }>;
+}): string {
+  if (typeof message.content === "string") {
+    return message.content;
+  }
+  if (message.parts && Array.isArray(message.parts)) {
+    return message.parts
+      .filter((part) => part.type === "text" && part.text)
+      .map((part) => part.text)
+      .join("");
+  }
+  return "";
+}
+
+/**
+ * Generate a title from the first user message
+ */
+function generateTitle(message: string): string {
+  let title = message.slice(0, 50);
+  if (message.length > 50) {
+    const lastSpace = title.lastIndexOf(" ");
+    if (lastSpace > 20) {
+      title = title.slice(0, lastSpace);
+    }
+    title += "...";
+  }
+  return title;
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const {
+      messages,
+      memorySpaceId = "quickstart-demo",
+      userId = "demo-user",
+      conversationId: providedConversationId,
+    } = body;
+
+    // Validate messages array exists
+    if (!messages || !Array.isArray(messages)) {
+      return new Response(
+        JSON.stringify({ error: "messages array is required" }),
+        { status: 400, headers: { "Content-Type": "application/json" } }
+      );
+    }
+
+    // Generate conversation ID if not provided
+    const conversationId =
+      providedConversationId ||
+      `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const isNewConversation = !providedConversationId;
+
+    // Normalize messages for convertToModelMessages
+    const normalizedMessages = normalizeMessages(messages);
+
+    // Convert to model messages
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const modelMessagesResult = convertToModelMessages(normalizedMessages as any);
+    const modelMessages =
+      modelMessagesResult instanceof Promise
+        ? await modelMessagesResult
+        : modelMessagesResult;
+
+    // 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) : "";
+
+    // Use createUIMessageStreamResponse - same as v5 for full memory support
+    return createUIMessageStreamResponse({
+      stream: createUIMessageStream({
+        execute: async ({ writer }) => {
+          // Create layer observer for real-time UI updates
+          const layerObserver: LayerObserver = {
+            onOrchestrationStart: (orchestrationId) => {
+              writer.write({
+                type: "data-orchestration-start",
+                data: { orchestrationId },
+                transient: true,
+              });
+            },
+            onLayerUpdate: (event) => {
+              writer.write({
+                type: "data-layer-update",
+                data: {
+                  layer: event.layer,
+                  status: event.status,
+                  timestamp: event.timestamp,
+                  latencyMs: event.latencyMs,
+                  data: event.data,
+                  error: event.error,
+                  revisionAction: event.revisionAction,
+                  supersededFacts: event.supersededFacts,
+                },
+                transient: true,
+              });
+            },
+            onOrchestrationComplete: (summary) => {
+              writer.write({
+                type: "data-orchestration-complete",
+                data: {
+                  orchestrationId: summary.orchestrationId,
+                  totalLatencyMs: summary.totalLatencyMs,
+                  createdIds: summary.createdIds,
+                },
+                transient: true,
+              });
+            },
+          };
+
+          // Build config with observer
+          const config = getCortexMemoryConfig(
+            memorySpaceId,
+            userId,
+            conversationId,
+            layerObserver
+          );
+
+          // Create memory-augmented model - THIS handles both recall AND storage!
+          const cortexMemory = await createCortexMemoryAsync(config);
+
+          // Stream response with automatic memory integration
+          const result = streamText({
+            model: cortexMemory(openai("gpt-4o-mini")),
+            messages: modelMessages,
+            system: SYSTEM_PROMPT,
+          });
+
+          // Merge LLM stream into UI message stream
+          writer.merge(result.toUIMessageStream());
+
+          // Create conversation if new
+          if (isNewConversation && messageText) {
+            try {
+              const cortex = getCortex();
+              await cortex.conversations.create({
+                memorySpaceId,
+                conversationId,
+                type: "user-agent",
+                participants: {
+                  userId,
+                  agentId: "cortex-memory-agent",
+                },
+                metadata: { title: generateTitle(messageText) },
+              });
+
+              // Send conversation update to client
+              writer.write({
+                type: "data-conversation-update",
+                data: {
+                  conversationId,
+                  title: generateTitle(messageText),
+                },
+                transient: true,
+              });
+            } catch (error) {
+              console.error("Failed to create conversation:", error);
+            }
+          }
+        },
+      }),
+    });
+  } catch (error) {
+    console.error("[Chat v6 API Error]", error);
+
+    return new Response(
+      JSON.stringify({
+        error: error instanceof Error ? error.message : "Unknown error",
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" },
+      }
+    );
+  }
+}

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

@@ -0,0 +1,179 @@
+/**
+ * Conversations API Route
+ *
+ * GET: List conversations for a user (chat history)
+ * POST: Create a new conversation
+ * DELETE: Delete a conversation
+ */
+
+import { getCortex } from "@/lib/cortex";
+
+export async function GET(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const conversationId = searchParams.get("conversationId");
+    const userId = searchParams.get("userId");
+    const memorySpaceId = searchParams.get("memorySpaceId") || "quickstart-demo";
+
+    const cortex = getCortex();
+
+    // If conversationId is provided, fetch single conversation with messages
+    if (conversationId) {
+      const conversation = await cortex.conversations.get(conversationId, {
+        includeMessages: true,
+        messageLimit: 100,
+      });
+
+      if (!conversation) {
+        return Response.json(
+          { error: "Conversation not found" },
+          { status: 404 }
+        );
+      }
+
+      // Transform messages to the format expected by AI SDK useChat
+      const messages = (conversation.messages || []).map((msg) => ({
+        id: msg.id,
+        role: msg.role as "user" | "assistant",
+        content: msg.content,
+        createdAt: new Date(msg.timestamp),
+      }));
+
+      return Response.json({
+        conversation: {
+          id: conversation.conversationId,
+          title: (conversation.metadata?.title as string) || getDefaultTitle(conversation),
+          createdAt: conversation.createdAt,
+          updatedAt: conversation.updatedAt,
+          messageCount: conversation.messageCount || 0,
+        },
+        messages,
+      });
+    }
+
+    // List conversations for user (requires userId)
+    if (!userId) {
+      return Response.json(
+        { error: "userId is required" },
+        { status: 400 }
+      );
+    }
+
+    // Get conversations for the user
+    const result = await cortex.conversations.list({
+      memorySpaceId,
+      userId,
+      limit: 50,
+    });
+
+    // Map conversations to a simpler format for the UI
+    const conversations = result.conversations.map((conv) => ({
+      id: conv.conversationId,
+      title: (conv.metadata?.title as string) || getDefaultTitle(conv),
+      createdAt: conv.createdAt,
+      updatedAt: conv.updatedAt,
+      messageCount: conv.messageCount || 0,
+    }));
+
+    // Sort by updatedAt descending (most recent first)
+    conversations.sort((a, b) => b.updatedAt - a.updatedAt);
+
+    return Response.json({ conversations });
+  } catch (error) {
+    console.error("[Conversations Error]", error);
+
+    return Response.json(
+      { error: "Failed to fetch conversations" },
+      { status: 500 }
+    );
+  }
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { userId, memorySpaceId = "quickstart-demo", title } = body;
+
+    if (!userId) {
+      return Response.json(
+        { error: "userId is required" },
+        { status: 400 }
+      );
+    }
+
+    const cortex = getCortex();
+
+    // Create a new conversation
+    const conversationId = `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const conversation = await cortex.conversations.create({
+      memorySpaceId,
+      conversationId,
+      type: "user-agent",
+      participants: {
+        userId,
+        agentId: "quickstart-assistant",
+      },
+      metadata: {
+        title: title || "New Chat",
+      },
+    });
+
+    return Response.json({
+      success: true,
+      conversation: {
+        id: conversation.conversationId,
+        title: (conversation.metadata?.title as string) || "New Chat",
+        createdAt: conversation.createdAt,
+        updatedAt: conversation.updatedAt,
+        messageCount: 0,
+      },
+    });
+  } catch (error) {
+    console.error("[Conversation Create Error]", error);
+
+    return Response.json(
+      { error: "Failed to create conversation" },
+      { status: 500 }
+    );
+  }
+}
+
+export async function DELETE(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const conversationId = searchParams.get("conversationId");
+
+    if (!conversationId) {
+      return Response.json(
+        { error: "conversationId is required" },
+        { status: 400 }
+      );
+    }
+
+    const cortex = getCortex();
+
+    await cortex.conversations.delete(conversationId);
+
+    return Response.json({ success: true });
+  } catch (error) {
+    console.error("[Conversation Delete Error]", error);
+
+    return Response.json(
+      { error: "Failed to delete conversation" },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * Generate a default title from conversation data
+ */
+function getDefaultTitle(conv: { createdAt: number; messageCount?: number }): string {
+  const date = new Date(conv.createdAt);
+  const timeStr = date.toLocaleTimeString("en-US", {
+    hour: "numeric",
+    minute: "2-digit",
+  });
+  return `Chat at ${timeStr}`;
+}

package/templates/vercel-ai-quickstart/app/globals.css

@@ -112,3 +112,164 @@
   font-size: 0.875rem;
   line-height: 1.5;
 }
+
+/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Auth Screen Animations
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+
+@keyframes fade-in-up {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes logo-pulse {
+  0%, 100% {
+    transform: scale(1);
+    box-shadow: 0 0 0 0 rgba(12, 140, 230, 0.4);
+  }
+  50% {
+    transform: scale(1.02);
+    box-shadow: 0 0 40px 10px rgba(12, 140, 230, 0.2);
+  }
+}
+
+.auth-screen {
+  animation: fade-in-up 0.5s ease-out;
+}
+
+.auth-logo {
+  animation: logo-pulse 3s ease-in-out infinite;
+}
+
+/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Sidebar Animations
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+
+@keyframes sidebar-slide-in {
+  from {
+    opacity: 0;
+    transform: translateX(-20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes conversation-item-in {
+  from {
+    opacity: 0;
+    transform: translateX(-10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.sidebar-animate {
+  animation: sidebar-slide-in 0.3s ease-out;
+}
+
+.conversation-item {
+  animation: conversation-item-in 0.2s ease-out;
+}
+
+/* Staggered animation for conversation list */
+.conversation-item:nth-child(1) { animation-delay: 0ms; }
+.conversation-item:nth-child(2) { animation-delay: 30ms; }
+.conversation-item:nth-child(3) { animation-delay: 60ms; }
+.conversation-item:nth-child(4) { animation-delay: 90ms; }
+.conversation-item:nth-child(5) { animation-delay: 120ms; }
+.conversation-item:nth-child(n+6) { animation-delay: 150ms; }
+
+/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Input Focus Animations
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+
+input:focus {
+  box-shadow: 0 0 0 2px rgba(12, 140, 230, 0.2);
+}
+
+/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Button Hover Effects
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+
+.btn-primary {
+  position: relative;
+  overflow: hidden;
+}
+
+.btn-primary::after {
+  content: "";
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0;
+  height: 0;
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 50%;
+  transform: translate(-50%, -50%);
+  transition: width 0.4s ease, height 0.4s ease;
+}
+
+.btn-primary:hover::after {
+  width: 300px;
+  height: 300px;
+}
+
+/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Loading States
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+
+@keyframes shimmer {
+  0% {
+    background-position: -200% 0;
+  }
+  100% {
+    background-position: 200% 0;
+  }
+}
+
+.skeleton {
+  background: linear-gradient(
+    90deg,
+    rgba(255, 255, 255, 0.05) 25%,
+    rgba(255, 255, 255, 0.1) 50%,
+    rgba(255, 255, 255, 0.05) 75%
+  );
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
+}
+
+/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   Responsive Sidebar
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+
+@media (max-width: 1024px) {
+  /* On smaller screens, the layer flow visualization is hidden */
+  .layer-flow-panel {
+    display: none;
+  }
+}
+
+@media (max-width: 768px) {
+  /* On mobile, sidebar becomes collapsible */
+  .sidebar-mobile-hidden {
+    transform: translateX(-100%);
+    transition: transform 0.3s ease;
+  }
+  
+  .sidebar-mobile-visible {
+    transform: translateX(0);
+    position: fixed;
+    z-index: 50;
+    height: 100vh;
+  }
+}