@cortexmemory/cli 0.27.3 → 0.28.0

package/templates/vercel-ai-quickstart/app/page.tsx

@@ -1,8 +1,9 @@
 "use client";
 
 import dynamic from "next/dynamic";
-import { useState, useCallback } from "react";
+import { useState, useCallback, useEffect } from "react";
 import { useLayerTracking } from "@/lib/layer-tracking";
+import { detectVersions, type VersionInfo } from "@/lib/versions";
 import { AuthProvider, useAuth } from "@/components/AuthProvider";
 import { AdminSetup } from "@/components/AdminSetup";
 import { LoginScreen } from "@/components/LoginScreen";
@@ -51,7 +52,10 @@ const ChatHistorySidebar = dynamic(
 function MainContent() {
   const { isLoading, isAdminSetup, isAuthenticated, user } = useAuth();
   const [memorySpaceId, setMemorySpaceId] = useState("quickstart-demo");
-  const [currentConversationId, setCurrentConversationId] = useState<string | null>(null);
+  const [currentConversationId, setCurrentConversationId] = useState<
+    string | null
+  >(null);
+  const [versions, setVersions] = useState<VersionInfo | null>(null);
   const {
     layers,
     isOrchestrating,
@@ -60,6 +64,11 @@ function MainContent() {
     resetLayers,
   } = useLayerTracking();
 
+  // Detect SDK versions on mount
+  useEffect(() => {
+    detectVersions().then(setVersions);
+  }, []);
+
   // Handle new chat
   const handleNewChat = useCallback(() => {
     setCurrentConversationId(null);
@@ -67,18 +76,24 @@ function MainContent() {
   }, [resetLayers]);
 
   // Handle conversation selection
-  const handleSelectConversation = useCallback((conversationId: string) => {
-    setCurrentConversationId(conversationId);
-    resetLayers();
-  }, [resetLayers]);
+  const handleSelectConversation = useCallback(
+    (conversationId: string) => {
+      setCurrentConversationId(conversationId);
+      resetLayers();
+    },
+    [resetLayers],
+  );
 
   // Handle conversation update (e.g., title change after first message)
-  const handleConversationUpdate = useCallback((conversationId: string) => {
-    // Update current conversation ID if it was null (new chat created)
-    if (!currentConversationId) {
-      setCurrentConversationId(conversationId);
-    }
-  }, [currentConversationId]);
+  const handleConversationUpdate = useCallback(
+    (conversationId: string) => {
+      // Update current conversation ID if it was null (new chat created)
+      if (!currentConversationId) {
+        setCurrentConversationId(conversationId);
+      }
+    },
+    [currentConversationId],
+  );
 
   // Loading state
   if (isLoading) {
@@ -109,7 +124,7 @@ function MainContent() {
 
   // Main authenticated interface
   return (
-    <main className="min-h-screen flex flex-col">
+    <main className="h-screen flex flex-col overflow-hidden">
       {/* Header */}
       <header className="border-b border-white/10 px-6 py-4">
         <div className="flex items-center justify-between">
@@ -151,6 +166,9 @@ function MainContent() {
             memorySpaceId={memorySpaceId}
             userId={userId}
             conversationId={currentConversationId}
+            apiEndpoint={
+              versions?.aiSdkMajor === 6 ? "/api/chat-v6" : "/api/chat"
+            }
             onOrchestrationStart={startOrchestration}
             onLayerUpdate={updateLayer}
             onReset={resetLayers}
@@ -185,9 +203,17 @@ function MainContent() {
       <footer className="border-t border-white/10 px-6 py-3">
         <div className="flex items-center justify-between text-sm text-gray-500">
           <div className="flex items-center gap-4">
-            <span>Cortex SDK v0.24.0</span>
+            <span>
+              Cortex SDK {versions ? `v${versions.cortexSdk}` : "..."}
+            </span>
             <span>•</span>
-            <span>Vercel AI SDK v5</span>
+            <span>Vercel AI SDK {versions?.aiSdk ?? "..."}</span>
+            {versions?.aiSdkMajor === 6 && (
+              <>
+                <span>•</span>
+                <span className="text-cortex-400">Using ToolLoopAgent</span>
+              </>
+            )}
           </div>
           <a
             href="https://cortexmemory.dev/docs"

package/templates/vercel-ai-quickstart/components/AdminSetup.tsx

@@ -41,7 +41,9 @@ export function AdminSetup() {
             <span className="text-4xl">🧠</span>
           </div>
           <h1 className="text-3xl font-bold mb-2">Welcome to Cortex</h1>
-          <p className="text-gray-400">Set up your admin password to get started</p>
+          <p className="text-gray-400">
+            Set up your admin password to get started
+          </p>
         </div>
 
         {/* Setup Form */}

package/templates/vercel-ai-quickstart/components/AuthProvider.tsx

@@ -32,7 +32,7 @@ export interface AuthContextValue extends AuthState {
   register: (
     username: string,
     password: string,
-    displayName?: string
+    displayName?: string,
   ) => Promise<boolean>;
   logout: () => void;
   clearError: () => void;
@@ -164,7 +164,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
             JSON.stringify({
               user: data.user,
               sessionToken: data.sessionToken,
-            })
+            }),
           );
         }
 
@@ -184,7 +184,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
         return false;
       }
     },
-    []
+    [],
   );
 
   // Register
@@ -192,7 +192,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
     async (
       username: string,
       password: string,
-      displayName?: string
+      displayName?: string,
     ): Promise<boolean> => {
       setState((prev) => ({ ...prev, error: null }));
 
@@ -217,7 +217,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
             JSON.stringify({
               user: data.user,
               sessionToken: data.sessionToken,
-            })
+            }),
           );
         }
 
@@ -237,7 +237,7 @@ export function AuthProvider({ children }: { children: ReactNode }) {
         return false;
       }
     },
-    []
+    [],
   );
 
   // Logout

package/templates/vercel-ai-quickstart/components/ChatHistorySidebar.tsx

@@ -26,9 +26,15 @@ interface ChatHistorySidebarProps {
 // Helpers
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-function groupByDate(conversations: Conversation[]): Record<string, Conversation[]> {
+function groupByDate(
+  conversations: Conversation[],
+): Record<string, Conversation[]> {
   const now = new Date();
-  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+  const today = new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate(),
+  ).getTime();
   const yesterday = today - 86400000;
   const weekAgo = today - 7 * 86400000;
 
@@ -44,7 +50,7 @@ function groupByDate(conversations: Conversation[]): Record<string, Conversation
     const convDay = new Date(
       convDate.getFullYear(),
       convDate.getMonth(),
-      convDate.getDate()
+      convDate.getDate(),
     ).getTime();
 
     if (convDay >= today) {
@@ -89,7 +95,7 @@ export function ChatHistorySidebar({
 
     try {
       const response = await fetch(
-        `/api/conversations?userId=${encodeURIComponent(user.id)}&memorySpaceId=${encodeURIComponent(memorySpaceId)}`
+        `/api/conversations?userId=${encodeURIComponent(user.id)}&memorySpaceId=${encodeURIComponent(memorySpaceId)}`,
       );
       const data = await response.json();
       if (data.conversations) {
@@ -121,13 +127,18 @@ export function ChatHistorySidebar({
     setDeletingId(conversationId);
 
     try {
-      const response = await fetch(`/api/conversations?conversationId=${encodeURIComponent(conversationId)}`, {
-        method: "DELETE",
-      });
+      const response = await fetch(
+        `/api/conversations?conversationId=${encodeURIComponent(conversationId)}`,
+        {
+          method: "DELETE",
+        },
+      );
 
       if (!response.ok) {
         const data = await response.json().catch(() => ({}));
-        throw new Error(data.error || `Delete failed with status ${response.status}`);
+        throw new Error(
+          data.error || `Delete failed with status ${response.status}`,
+        );
       }
 
       // Remove from local state only after successful deletion

package/templates/vercel-ai-quickstart/components/ChatInterface.tsx

@@ -26,6 +26,8 @@ interface ChatInterfaceProps {
   memorySpaceId: string;
   userId: string;
   conversationId: string | null;
+  /** API endpoint for chat - defaults to /api/chat, use /api/chat-v6 for AI SDK v6 */
+  apiEndpoint?: string;
   onOrchestrationStart?: () => void;
   onLayerUpdate?: (
     layer: MemoryLayer,
@@ -44,6 +46,7 @@ export function ChatInterface({
   memorySpaceId,
   userId,
   conversationId,
+  apiEndpoint = "/api/chat",
   onOrchestrationStart,
   onLayerUpdate,
   onReset,
@@ -66,12 +69,15 @@ export function ChatInterface({
     conversationIdRef.current = conversationId;
   }, [conversationId]);
 
+  // Track if we should skip history load (when we create a new conversation ourselves)
+  const skipHistoryLoadRef = useRef<string | null>(null);
+
   // Create transport with a function that reads from ref for conversationId
   // This ensures we always send the latest conversationId
   const transport = useMemo(
     () =>
       new DefaultChatTransport({
-        api: "/api/chat",
+        api: apiEndpoint,
         // Use a function to get body so it reads latest conversationId from ref
         body: () => ({
           memorySpaceId,
@@ -79,7 +85,7 @@ export function ChatInterface({
           conversationId: conversationIdRef.current,
         }),
       }),
-    [memorySpaceId, userId], // Note: conversationId removed - ref handles updates
+    [apiEndpoint, memorySpaceId, userId], // Note: conversationId removed - ref handles updates
   );
 
   // Handle layer data parts from the stream
@@ -101,6 +107,8 @@ export function ChatInterface({
       // Handle conversation title update
       if (part.type === "data-conversation-update") {
         const update = part.data as { conversationId: string; title: string };
+        // Mark this conversation ID to skip history load - we just created it
+        skipHistoryLoadRef.current = update.conversationId;
         onConversationUpdate?.(update.conversationId, update.title);
       }
     },
@@ -119,20 +127,28 @@ export function ChatInterface({
 
   // Load messages when conversation changes
   useEffect(() => {
-    // Clear messages first
-    setMessages([]);
-
-    // If no conversation selected, nothing more to do
+    // If no conversation selected, just clear messages
     if (!conversationId) {
+      setMessages([]);
+      return;
+    }
+
+    // Skip loading if we just created this conversation ourselves
+    // (we already have the messages in state from the current chat session)
+    if (skipHistoryLoadRef.current === conversationId) {
+      skipHistoryLoadRef.current = null;
       return;
     }
 
+    // Clear messages before loading new conversation
+    setMessages([]);
+
     // Fetch conversation history
     const loadConversationHistory = async () => {
       setIsLoadingHistory(true);
       try {
         const response = await fetch(
-          `/api/conversations?conversationId=${encodeURIComponent(conversationId)}`
+          `/api/conversations?conversationId=${encodeURIComponent(conversationId)}`,
         );
 
         if (!response.ok) {
@@ -144,12 +160,19 @@ export function ChatInterface({
 
         if (data.messages && data.messages.length > 0) {
           // Transform to the format expected by useChat
-          const loadedMessages = data.messages.map((msg: { id: string; role: string; content: string; createdAt: string }) => ({
-            id: msg.id,
-            role: msg.role,
-            content: msg.content,
-            createdAt: new Date(msg.createdAt),
-          }));
+          const loadedMessages = data.messages.map(
+            (msg: {
+              id: string;
+              role: string;
+              content: string;
+              createdAt: string;
+            }) => ({
+              id: msg.id,
+              role: msg.role,
+              content: msg.content,
+              createdAt: new Date(msg.createdAt),
+            }),
+          );
           setMessages(loadedMessages);
         }
       } catch (error) {
@@ -190,7 +213,10 @@ export function ChatInterface({
   };
 
   // Extract text content from message parts (AI SDK v5 format)
-  const getMessageContent = (message: { content?: string; parts?: Array<{ type: string; text?: string }> }): string => {
+  const getMessageContent = (message: {
+    content?: string;
+    parts?: Array<{ type: string; text?: string }>;
+  }): string => {
     if (typeof message.content === "string") {
       return message.content;
     }
@@ -230,7 +256,9 @@ export function ChatInterface({
                   d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
                 />
               </svg>
-              <span className="text-gray-400 text-sm">Loading conversation...</span>
+              <span className="text-gray-400 text-sm">
+                Loading conversation...
+              </span>
             </div>
           </div>
         )}
@@ -241,7 +269,9 @@ export function ChatInterface({
               <span className="text-3xl">🧠</span>
             </div>
             <h2 className="text-xl font-semibold mb-2">
-              {conversationId ? "Continue your conversation" : "Start a new conversation"}
+              {conversationId
+                ? "Continue your conversation"
+                : "Start a new conversation"}
             </h2>
             <p className="text-gray-400 max-w-md mx-auto mb-6">
               This demo shows how Cortex orchestrates memory across multiple

package/templates/vercel-ai-quickstart/components/LoginScreen.tsx

@@ -57,7 +57,9 @@ export function LoginScreen() {
             <span className="text-4xl">🧠</span>
           </div>
           <h1 className="text-3xl font-bold mb-2">Cortex Memory Demo</h1>
-          <p className="text-gray-400">Sign in to explore AI with long-term memory</p>
+          <p className="text-gray-400">
+            Sign in to explore AI with long-term memory
+          </p>
         </div>
 
         {/* Login/Register Card */}
@@ -114,8 +116,7 @@ export function LoginScreen() {
                   htmlFor="displayName"
                   className="block text-sm font-medium text-gray-300 mb-2"
                 >
-                  Display Name{" "}
-                  <span className="text-gray-500">(optional)</span>
+                  Display Name <span className="text-gray-500">(optional)</span>
                 </label>
                 <input
                   id="displayName"
@@ -144,7 +145,9 @@ export function LoginScreen() {
                 placeholder="Enter your password"
                 className="w-full px-4 py-3 bg-white/5 border border-white/10 rounded-xl focus:outline-none focus:border-cortex-500 transition-colors"
                 disabled={isLoading}
-                autoComplete={activeTab === "login" ? "current-password" : "new-password"}
+                autoComplete={
+                  activeTab === "login" ? "current-password" : "new-password"
+                }
               />
             </div>
 
@@ -181,7 +184,9 @@ export function LoginScreen() {
                       d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
                     />
                   </svg>
-                  {activeTab === "login" ? "Signing in..." : "Creating account..."}
+                  {activeTab === "login"
+                    ? "Signing in..."
+                    : "Creating account..."}
                 </>
               ) : activeTab === "login" ? (
                 "Sign In"

package/templates/vercel-ai-quickstart/jest.config.js

@@ -1,9 +1,10 @@
 /**
  * Jest Configuration for Vercel AI Quickstart
  *
- * Two test projects:
+ * Three test projects:
  * - unit: Fast unit tests with mocked dependencies
  * - integration: Integration tests for API routes with mocked SDK
+ * - e2e: End-to-end tests with real Cortex backend (requires CONVEX_URL, OPENAI_API_KEY)
  */
 
 const baseConfig = {
@@ -41,5 +42,11 @@ module.exports = {
       testMatch: ["<rootDir>/tests/integration/**/*.test.ts"],
       testTimeout: 30000,
     },
+    {
+      ...baseConfig,
+      displayName: "e2e",
+      testMatch: ["<rootDir>/tests/e2e/**/*.test.ts"],
+      testTimeout: 120000, // 2 minutes for real network calls
+    },
   ],
 };

package/templates/vercel-ai-quickstart/lib/agents/memory-agent.ts

@@ -0,0 +1,165 @@
+/**
+ * Memory-Enabled Agent (AI SDK v6)
+ *
+ * This file demonstrates how to create a reusable agent with
+ * Cortex Memory integration using AI SDK v6's ToolLoopAgent.
+ *
+ * The agent:
+ * - Automatically injects relevant memories into context
+ * - Can be used with both generate() and stream()
+ * - Supports type-safe call options for userId, memorySpaceId, etc.
+ *
+ * @example
+ * ```typescript
+ * const result = await memoryAgent.generate({
+ *   prompt: 'What do you remember about me?',
+ *   options: {
+ *     userId: 'user_123',
+ *     memorySpaceId: 'my-app',
+ *   },
+ * });
+ * ```
+ */
+
+import { ToolLoopAgent, tool, stepCountIs } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { z } from "zod";
+import {
+  createCortexCallOptionsSchema,
+  createMemoryPrepareCall,
+  type CortexCallOptions,
+} from "@cortexmemory/vercel-ai-provider";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Agent 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`;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Memory Agent Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * A memory-enabled agent using AI SDK v6's ToolLoopAgent.
+ *
+ * This agent demonstrates:
+ * - callOptionsSchema for type-safe runtime config (userId, memorySpaceId, etc.)
+ * - prepareCall for automatic memory context injection via Cortex's recall() API
+ * - Built-in tools for memory operations (optional)
+ *
+ * The callOptionsSchema ensures TypeScript type safety when calling the agent:
+ * - userId: required for memory isolation per user
+ * - memorySpaceId: required for data partitioning
+ * - conversationId: optional for session continuity
+ * - agentId: optional agent identifier
+ */
+export const memoryAgent = new ToolLoopAgent({
+  id: "cortex-memory-agent",
+  model: openai("gpt-4o-mini"),
+  instructions: SYSTEM_PROMPT,
+
+  // ┌─────────────────────────────────────────────────────────────────┐
+  // │ callOptionsSchema: Type-Safe Runtime Configuration             │
+  // │                                                                 │
+  // │ This Zod schema defines what options must/can be passed when   │
+  // │ calling the agent. AI SDK v6 validates these at runtime.       │
+  // │                                                                 │
+  // │ Example usage:                                                  │
+  // │   await memoryAgent.generate({                                 │
+  // │     prompt: 'Hello!',                                          │
+  // │     options: { userId: 'u1', memorySpaceId: 'app1' }, // typed!│
+  // │   });                                                          │
+  // └─────────────────────────────────────────────────────────────────┘
+  callOptionsSchema: createCortexCallOptionsSchema(),
+
+  // ┌─────────────────────────────────────────────────────────────────┐
+  // │ prepareCall: Memory Context Injection                          │
+  // │                                                                 │
+  // │ Called before each agent invocation. This hook:                │
+  // │ 1. Extracts the user's query from messages                     │
+  // │ 2. Calls Cortex memory.recall() with userId + memorySpaceId    │
+  // │ 3. Injects the returned context into instructions              │
+  // │                                                                 │
+  // │ The recall() API orchestrates all memory layers:               │
+  // │ - Vector memories (semantic search)                            │
+  // │ - Facts (extracted knowledge)                                  │
+  // │ - Graph relationships (if configured)                          │
+  // └─────────────────────────────────────────────────────────────────┘
+  prepareCall: createMemoryPrepareCall({
+    convexUrl: process.env.CONVEX_URL!,
+    maxMemories: 20, // Max items to inject from recall
+    includeFacts: true, // Include Layer 3 facts
+    includeVector: true, // Include Layer 2 vector memories
+    includeGraph: true, // Expand through graph relationships
+  }),
+
+  // Default to 5 steps (sufficient for most chat interactions)
+  stopWhen: stepCountIs(5),
+
+  // Optional: Add memory-specific tools for explicit memory operations
+  // Uncomment to let the agent actively search/store memories
+  /*
+  tools: {
+    searchMemory: tool({
+      description: 'Search for specific memories about the user',
+      inputSchema: z.object({
+        query: z.string().describe('What to search for in memory'),
+      }),
+      execute: async ({ query }, { options }) => {
+        const { Cortex } = await import('@cortexmemory/sdk');
+        const cortex = new Cortex({ convexUrl: process.env.CONVEX_URL! });
+        const result = await cortex.memory.recall({
+          memorySpaceId: options.memorySpaceId,
+          query,
+          userId: options.userId,
+          limit: 5,
+        });
+        return result.context || 'No memories found.';
+      },
+    }),
+  },
+  */
+});
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Type Exports for Client Components
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Inferred UIMessage type for this agent.
+ *
+ * Use this in your client components for full type safety:
+ *
+ * ```typescript
+ * import { useChat } from '@ai-sdk/react';
+ * import type { MemoryAgentUIMessage } from '@/lib/agents/memory-agent';
+ *
+ * const { messages } = useChat<MemoryAgentUIMessage>();
+ * ```
+ */
+export type MemoryAgentUIMessage = {
+  id: string;
+  role: "user" | "assistant" | "system";
+  createdAt?: Date;
+  parts?: Array<
+    | { type: "text"; text: string }
+    | { type: "tool-invocation"; toolCallId: string; state: string }
+  >;
+};
+
+/**
+ * Re-export call options type for convenience.
+ */
+export type { CortexCallOptions };

package/templates/vercel-ai-quickstart/lib/password.ts

@@ -28,7 +28,7 @@ export async function hashPassword(password: string): Promise<string> {
     passwordBuffer,
     "PBKDF2",
     false,
-    ["deriveBits"]
+    ["deriveBits"],
   );
 
   // Derive key using PBKDF2
@@ -40,7 +40,7 @@ export async function hashPassword(password: string): Promise<string> {
       hash: "SHA-256",
     },
     keyMaterial,
-    KEY_LENGTH
+    KEY_LENGTH,
   );
 
   // Convert to base64 strings
@@ -60,7 +60,7 @@ export async function hashPassword(password: string): Promise<string> {
  */
 export async function verifyPassword(
   password: string,
-  storedHash: string
+  storedHash: string,
 ): Promise<boolean> {
   try {
     const [saltB64, expectedHashB64] = storedHash.split(":");
@@ -84,7 +84,7 @@ export async function verifyPassword(
       passwordBuffer,
       "PBKDF2",
       false,
-      ["deriveBits"]
+      ["deriveBits"],
     );
 
     // Derive key using same parameters
@@ -96,7 +96,7 @@ export async function verifyPassword(
         hash: "SHA-256",
       },
       keyMaterial,
-      KEY_LENGTH
+      KEY_LENGTH,
     );
 
     // Compare hashes