@cortexmemory/cli 0.27.3 → 0.27.4

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/versions.ts

@@ -0,0 +1,60 @@
+/**
+ * Version detection utilities for displaying SDK versions in the UI.
+ */
+
+export interface VersionInfo {
+  cortexSdk: string;
+  aiSdk: string;
+  aiSdkMajor: number;
+}
+
+/**
+ * Detect installed SDK versions at runtime.
+ * Returns version strings for display in the UI.
+ */
+export async function detectVersions(): Promise<VersionInfo> {
+  let cortexSdk = "unknown";
+  let aiSdk = "unknown";
+  let aiSdkMajor = 5;
+
+  // Detect Cortex SDK version
+  try {
+    const cortexModule = await import("@cortexmemory/sdk");
+    // Check for version export or use package version
+    if ("VERSION" in cortexModule) {
+      cortexSdk = cortexModule.VERSION as string;
+    } else {
+      // Fallback: try to detect from package
+      cortexSdk = "0.24.0";
+    }
+  } catch {
+    cortexSdk = "0.24.0";
+  }
+
+  // Detect AI SDK version by checking for v6-specific exports
+  try {
+    const aiModule = await import("ai");
+
+    // v6 has these specific exports
+    const hasV6Features =
+      "ToolLoopAgent" in aiModule ||
+      "createAgentUIStreamResponse" in aiModule ||
+      "Output" in aiModule;
+
+    if (hasV6Features) {
+      aiSdkMajor = 6;
+      aiSdk = "v6";
+    } else {
+      aiSdkMajor = 5;
+      aiSdk = "v5";
+    }
+  } catch {
+    aiSdk = "v5";
+  }
+
+  return {
+    cortexSdk,
+    aiSdk,
+    aiSdkMajor,
+  };
+}

package/templates/vercel-ai-quickstart/package.json

@@ -9,7 +9,11 @@
     "build": "next build --webpack",
     "start": "next start",
     "lint": "next lint",
-    "test": "jest",
+    "test": "jest --selectProjects unit integration",
+    "test:unit": "jest --selectProjects unit",
+    "test:integration": "jest --selectProjects integration",
+    "test:e2e": "jest --selectProjects e2e",
+    "test:all": "jest",
     "test:watch": "jest --watch",
     "convex:dev": "convex dev",
     "convex:deploy": "convex deploy"

package/templates/vercel-ai-quickstart/test-api.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * Programmatic API Route Tests
+ * Tests both v5 and v6 routes for memory functionality
+ */
+
+const BASE_URL = process.env.QUICKSTART_URL || 'http://localhost:3000';
+
+// Test configuration
+const TEST_USER_ID = `test-user-${Date.now()}`;
+const TEST_MEMORY_SPACE_ID = 'quickstart-demo';
+
+async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function testRoute(routePath, routeName) {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`Testing ${routeName} (${routePath})`);
+  console.log('='.repeat(60));
+  
+  const conversationId = `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  
+  // Test 1: Send a message with a fact
+  console.log('\n📤 Test 1: Sending message with a fact...');
+  const message1 = {
+    id: `msg-${Date.now()}-1`,
+    role: 'user',
+    content: `My favorite programming language is TypeScript and I work at a company called TechCorp.`,
+    createdAt: new Date().toISOString(),
+  };
+  
+  try {
+    const response1 = await fetch(`${BASE_URL}${routePath}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messages: [message1],
+        userId: TEST_USER_ID,
+        memorySpaceId: TEST_MEMORY_SPACE_ID,
+        conversationId,
+      }),
+    });
+    
+    if (!response1.ok) {
+      const errorText = await response1.text();
+      console.log(`❌ Request failed with status ${response1.status}`);
+      console.log(`   Error: ${errorText.slice(0, 500)}`);
+      return { success: false, route: routeName, error: `HTTP ${response1.status}` };
+    }
+    
+    // Read streaming response
+    const reader = response1.body.getReader();
+    const decoder = new TextDecoder();
+    let fullResponse = '';
+    let chunks = 0;
+    
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      const chunk = decoder.decode(value, { stream: true });
+      fullResponse += chunk;
+      chunks++;
+    }
+    
+    console.log(`✅ Response received (${chunks} chunks, ${fullResponse.length} bytes)`);
+    
+    // Check for layer observer data
+    const hasLayerData = fullResponse.includes('FACTS_LAYER') || 
+                          fullResponse.includes('MEMORY_LAYER') ||
+                          fullResponse.includes('layerId');
+    console.log(`   Layer observer data: ${hasLayerData ? '✅ Present' : '❌ Missing'}`);
+    
+    // Check for text content
+    const hasTextContent = fullResponse.includes('"type":"text"') || 
+                           fullResponse.includes('text-delta');
+    console.log(`   Text content: ${hasTextContent ? '✅ Present' : '❌ Missing'}`);
+    
+  } catch (error) {
+    console.log(`❌ Request error: ${error.message}`);
+    return { success: false, route: routeName, error: error.message };
+  }
+  
+  // Wait for async processing (fact extraction, etc.)
+  console.log('\n⏳ Waiting for memory processing...');
+  await sleep(3000);
+  
+  // Test 2: Check if facts were stored
+  console.log('\n🔍 Test 2: Checking stored facts...');
+  try {
+    const factsResponse = await fetch(
+      `${BASE_URL}/api/facts?userId=${TEST_USER_ID}&memorySpaceId=${TEST_MEMORY_SPACE_ID}`,
+      { method: 'GET' }
+    );
+    
+    if (factsResponse.ok) {
+      const factsData = await factsResponse.json();
+      const facts = factsData.facts || factsData || [];
+      console.log(`✅ Facts API returned: ${Array.isArray(facts) ? facts.length : 'unknown'} facts`);
+      
+      if (Array.isArray(facts) && facts.length > 0) {
+        console.log('   Sample facts:');
+        facts.slice(0, 3).forEach((fact, i) => {
+          const content = fact.content || fact.text || JSON.stringify(fact).slice(0, 100);
+          console.log(`     ${i + 1}. ${content.slice(0, 80)}...`);
+        });
+      }
+    } else {
+      console.log(`⚠️ Facts API returned ${factsResponse.status}`);
+    }
+  } catch (error) {
+    console.log(`⚠️ Could not check facts: ${error.message}`);
+  }
+  
+  // Test 3: Send follow-up message and verify recall
+  console.log('\n📤 Test 3: Sending follow-up to test recall...');
+  const message2 = {
+    id: `msg-${Date.now()}-2`,
+    role: 'user',
+    content: 'What programming language do I prefer?',
+    createdAt: new Date().toISOString(),
+  };
+  
+  // Include previous assistant response for context
+  const message1Response = {
+    id: `msg-${Date.now()}-1r`,
+    role: 'assistant',
+    content: 'Great! TypeScript is a fantastic choice for type-safe development.',
+    createdAt: new Date().toISOString(),
+  };
+  
+  try {
+    const response2 = await fetch(`${BASE_URL}${routePath}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        messages: [message1, message1Response, message2],
+        userId: TEST_USER_ID,
+        memorySpaceId: TEST_MEMORY_SPACE_ID,
+        conversationId,
+      }),
+    });
+    
+    if (!response2.ok) {
+      console.log(`❌ Follow-up request failed with status ${response2.status}`);
+      return { success: false, route: routeName, error: `Follow-up HTTP ${response2.status}` };
+    }
+    
+    const reader = response2.body.getReader();
+    const decoder = new TextDecoder();
+    let fullResponse = '';
+    
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      fullResponse += decoder.decode(value, { stream: true });
+    }
+    
+    // Check if TypeScript was mentioned in the response (recall working)
+    const mentionsTypeScript = fullResponse.toLowerCase().includes('typescript');
+    console.log(`✅ Response received`);
+    console.log(`   Recalls TypeScript preference: ${mentionsTypeScript ? '✅ Yes' : '❌ No'}`);
+    
+    return { 
+      success: true, 
+      route: routeName, 
+      recallWorks: mentionsTypeScript 
+    };
+    
+  } catch (error) {
+    console.log(`❌ Follow-up request error: ${error.message}`);
+    return { success: false, route: routeName, error: error.message };
+  }
+}
+
+async function testConversationAPI() {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('Testing Conversation API');
+  console.log('='.repeat(60));
+  
+  try {
+    const response = await fetch(
+      `${BASE_URL}/api/conversations?userId=${TEST_USER_ID}&memorySpaceId=${TEST_MEMORY_SPACE_ID}`,
+      { method: 'GET' }
+    );
+    
+    if (response.ok) {
+      const data = await response.json();
+      const conversations = data.conversations || data || [];
+      console.log(`✅ Conversations API works: ${Array.isArray(conversations) ? conversations.length : 'unknown'} conversations`);
+      return true;
+    } else {
+      console.log(`❌ Conversations API returned ${response.status}`);
+      return false;
+    }
+  } catch (error) {
+    console.log(`❌ Conversations API error: ${error.message}`);
+    return false;
+  }
+}
+
+async function checkServerHealth() {
+  console.log('🏥 Checking server health...');
+  try {
+    const response = await fetch(`${BASE_URL}/api/health`, { 
+      method: 'GET',
+      signal: AbortSignal.timeout(5000)
+    });
+    if (response.ok) {
+      console.log('✅ Server is healthy');
+      return true;
+    } else {
+      console.log(`❌ Health check failed: ${response.status}`);
+      return false;
+    }
+  } catch (error) {
+    console.log(`❌ Server not reachable: ${error.message}`);
+    return false;
+  }
+}
+
+async function main() {
+  console.log('🧪 Cortex Memory API Route Tests');
+  console.log(`📍 Testing server at: ${BASE_URL}`);
+  console.log(`👤 Test user: ${TEST_USER_ID}`);
+  console.log(`📦 Memory space: ${TEST_MEMORY_SPACE_ID}`);
+  
+  // Check server health first
+  const healthy = await checkServerHealth();
+  if (!healthy) {
+    console.log('\n❌ Server is not running. Please start the quickstart first:');
+    console.log('   cd packages/vercel-ai-provider/quickstart && npm run dev');
+    process.exit(1);
+  }
+  
+  const results = [];
+  
+  // Test conversation API
+  await testConversationAPI();
+  
+  // Test v5 route
+  const v5Result = await testRoute('/api/chat', 'V5 Route');
+  results.push(v5Result);
+  
+  // Test v6 route
+  const v6Result = await testRoute('/api/chat-v6', 'V6 Route');
+  results.push(v6Result);
+  
+  // Summary
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('📊 Test Summary');
+  console.log('='.repeat(60));
+  
+  let allPassed = true;
+  for (const result of results) {
+    const status = result.success ? '✅ PASS' : '❌ FAIL';
+    const recall = result.recallWorks !== undefined 
+      ? (result.recallWorks ? ' (recall ✅)' : ' (recall ❌)') 
+      : '';
+    const error = result.error ? ` - ${result.error}` : '';
+    console.log(`${status} ${result.route}${recall}${error}`);
+    if (!result.success) allPassed = false;
+  }
+  
+  console.log('');
+  process.exit(allPassed ? 0 : 1);
+}
+
+main().catch(error => {
+  console.error('Test runner error:', error);
+  process.exit(1);
+});