@cortexmemory/cli 0.26.2 → 0.27.3

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

@@ -0,0 +1,94 @@
+/**
+ * User Registration API Route
+ *
+ * POST: Register a new user account
+ */
+
+import { getCortex } from "@/lib/cortex";
+import { hashPassword, generateSessionToken } from "@/lib/password";
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { username, password, displayName } = body;
+
+    // Validate input
+    if (!username || typeof username !== "string") {
+      return Response.json(
+        { error: "Username is required" },
+        { status: 400 }
+      );
+    }
+
+    if (!password || typeof password !== "string") {
+      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 }
+      );
+    }
+
+    if (password.length < 4) {
+      return Response.json(
+        { error: "Password must be at least 4 characters" },
+        { status: 400 }
+      );
+    }
+
+    // Sanitize username (alphanumeric, underscore, hyphen only)
+    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 }
+      );
+    }
+
+    const cortex = getCortex();
+
+    // Check if user already exists
+    const existingUser = await cortex.users.get(sanitizedUsername);
+    if (existingUser) {
+      return Response.json(
+        { error: "Username already taken" },
+        { status: 409 }
+      );
+    }
+
+    // Hash password and create user profile
+    const passwordHash = await hashPassword(password);
+    const now = Date.now();
+
+    await cortex.users.update(sanitizedUsername, {
+      displayName: displayName || sanitizedUsername,
+      passwordHash,
+      createdAt: now,
+      lastLoginAt: now,
+    });
+
+    // Generate session token
+    const sessionToken = generateSessionToken();
+
+    return Response.json({
+      success: true,
+      user: {
+        id: sanitizedUsername,
+        displayName: displayName || sanitizedUsername,
+      },
+      sessionToken,
+    });
+  } catch (error) {
+    console.error("[Register Error]", error);
+
+    return Response.json(
+      { error: "Failed to register user" },
+      { status: 500 }
+    );
+  }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Admin Setup API Route
+ *
+ * POST: Set up initial admin password (first-run only)
+ */
+
+import { getCortex } from "@/lib/cortex";
+import { hashPassword } from "@/lib/password";
+
+const ADMIN_NAMESPACE = "quickstart-config";
+const ADMIN_KEY = "admin_password_hash";
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { password } = body;
+
+    if (!password || typeof password !== "string") {
+      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 }
+      );
+    }
+
+    const cortex = getCortex();
+
+    // Check if admin already exists
+    const existingHash = await cortex.mutable.get(ADMIN_NAMESPACE, ADMIN_KEY);
+    if (existingHash !== null) {
+      return Response.json(
+        { error: "Admin already configured" },
+        { status: 409 }
+      );
+    }
+
+    // Hash and store admin password
+    const passwordHash = await hashPassword(password);
+    await cortex.mutable.set(ADMIN_NAMESPACE, ADMIN_KEY, passwordHash);
+
+    return Response.json({
+      success: true,
+      message: "Admin password configured successfully",
+    });
+  } catch (error) {
+    console.error("[Admin Setup Error]", error);
+
+    return Response.json(
+      { error: "Failed to configure admin password" },
+      { status: 500 }
+    );
+  }
+}

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

@@ -0,0 +1,277 @@
+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
+
+Example interactions:
+- User: "My name is Alex" → Remember and use their name
+- User: "I work at Acme Corp" → Remember their employer
+- User: "My favorite color is blue" → Remember their preference
+- User: "What do you know about me?" → List everything you remember`;
+
+// Create Cortex Memory config factory
+// Uses createCortexMemoryAsync for graph support when CORTEX_GRAPH_SYNC=true
+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 (required for user-agent conversations in SDK v0.17.0+)
+    agentId: "quickstart-assistant",
+    agentName: "Cortex Demo Assistant",
+
+    // Conversation ID for chat history isolation
+    conversationId,
+
+    // Enable graph memory sync (auto-configured via env vars)
+    // When true, uses CypherGraphAdapter to sync to Neo4j/Memgraph
+    enableGraphMemory: process.env.CORTEX_GRAPH_SYNC === "true",
+
+    // Enable fact extraction (auto-configured via env vars)
+    enableFactExtraction: process.env.CORTEX_FACT_EXTRACTION === "true",
+
+    // Belief Revision (v0.24.0+)
+    // Automatically handles fact updates, supersessions, and deduplication
+    // When a user changes their preference (e.g., "I now prefer purple"),
+    // the system intelligently updates or supersedes the old fact.
+    beliefRevision: {
+      enabled: true, // Enable the belief revision pipeline
+      slotMatching: true, // Fast slot-based conflict detection (subject-predicate matching)
+      llmResolution: true, // LLM-based resolution for nuanced conflicts
+    },
+
+    // Embedding provider for semantic matching (required for semantic dedup & belief revision)
+    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 (v0.23.0 - unified retrieval across all layers)
+    memorySearchLimit: 20, // Results from combined vector + facts + graph search
+
+    // Real-time layer tracking (v0.24.0+)
+    // Events are emitted as each layer processes, enabling live UI updates
+    layerObserver,
+
+    // Debug in development
+    debug: process.env.NODE_ENV === "development",
+  };
+}
+
+/**
+ * Generate a title from the first user message
+ */
+function generateTitle(message: string): string {
+  // Take first 50 chars, cut at word boundary
+  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, userId, conversationId: providedConversationId } = body;
+
+    // Generate conversation ID if not provided (new chat)
+    const conversationId = providedConversationId || 
+      `conv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const isNewConversation = !providedConversationId;
+
+    // Convert UIMessage[] from useChat to ModelMessage[] for streamText
+    // Note: In AI SDK v6+, convertToModelMessages may return a Promise
+    const modelMessagesResult = convertToModelMessages(messages);
+    const modelMessages =
+      modelMessagesResult instanceof Promise
+        ? await modelMessagesResult
+        : modelMessagesResult;
+
+    // Get the first user message for title generation
+    // AI SDK v5+ uses `parts` array instead of `content` string
+    const firstUserMessage = messages.find((m: { role: string }) => m.role === "user") as {
+      role: string;
+      content?: string;
+      parts?: Array<{ type: string; text?: string }>;
+    } | undefined;
+    
+    let messageText = "";
+    if (firstUserMessage) {
+      if (typeof firstUserMessage.content === "string") {
+        // Legacy format: content is a string
+        messageText = firstUserMessage.content;
+      } else if (firstUserMessage.parts && Array.isArray(firstUserMessage.parts)) {
+        // AI SDK v5+ format: extract text from parts array
+        messageText = firstUserMessage.parts
+          .filter((part) => part.type === "text" && part.text)
+          .map((part) => part.text)
+          .join("");
+      }
+    }
+
+    // Use createUIMessageStream to send both LLM text and layer events
+    return createUIMessageStreamResponse({
+      stream: createUIMessageStream({
+        execute: async ({ writer }) => {
+          // Create observer that writes layer events to the stream
+          // These events are transient (not persisted in message history)
+          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 the observer and conversation ID
+          const config = getCortexMemoryConfig(
+            memorySpaceId || "quickstart-demo",
+            userId || "demo-user",
+            conversationId,
+            layerObserver,
+          );
+
+          // Create memory-augmented model with async initialization (enables graph support)
+          // This connects to Neo4j/Memgraph if CORTEX_GRAPH_SYNC=true
+          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 the UI message stream
+          writer.merge(result.toUIMessageStream());
+
+          // If this is a new conversation, create it in the SDK and update the title
+          if (isNewConversation && messageText) {
+            try {
+              const cortex = getCortex();
+              const title = generateTitle(messageText);
+
+              // Create the conversation with the SDK
+              await cortex.conversations.create({
+                memorySpaceId: memorySpaceId || "quickstart-demo",
+                conversationId,
+                type: "user-agent",
+                participants: {
+                  userId: userId || "demo-user",
+                  agentId: "quickstart-assistant",
+                },
+                metadata: { title },
+              });
+
+              // Send conversation update to the client
+              writer.write({
+                type: "data-conversation-update",
+                data: {
+                  conversationId,
+                  title,
+                },
+                transient: true,
+              });
+            } catch (error) {
+              console.error("Failed to create conversation:", error);
+            }
+          }
+        },
+      }),
+    });
+  } catch (error) {
+    console.error("[Chat 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/api/facts/route.ts

@@ -0,0 +1,39 @@
+import { Cortex } from "@cortexmemory/sdk";
+
+export const dynamic = "force-dynamic";
+
+function getCortex() {
+  return new Cortex({ convexUrl: process.env.CONVEX_URL! });
+}
+
+export async function GET(req: Request) {
+  try {
+    const { searchParams } = new URL(req.url);
+    const memorySpaceId =
+      searchParams.get("memorySpaceId") || "quickstart-demo";
+    const userId = searchParams.get("userId");
+    const limit = parseInt(searchParams.get("limit") || "50");
+
+    const cortex = getCortex();
+
+    // Fetch facts for the user/memory space
+    const facts = await cortex.facts.list({
+      memorySpaceId,
+      ...(userId ? { userId } : {}),
+      limit,
+    });
+
+    return Response.json({
+      facts,
+      count: facts.length,
+      memorySpaceId,
+    });
+  } catch (error) {
+    console.error("[Facts API Error]", error);
+
+    return Response.json(
+      { error: error instanceof Error ? error.message : "Unknown error" },
+      { status: 500 },
+    );
+  }
+}