@cortexmemory/cli 0.26.0 → 0.27.1

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

@@ -0,0 +1,99 @@
+import { Cortex } from "@cortexmemory/sdk";
+
+/**
+ * Health check endpoint to verify all backend services
+ */
+export async function GET() {
+  const checks: Record<
+    string,
+    { status: string; latencyMs?: number; error?: string }
+  > = {};
+
+  // Check 1: Environment variables
+  const hasConvexUrl = !!process.env.CONVEX_URL;
+  const hasPublicConvexUrl = !!process.env.NEXT_PUBLIC_CONVEX_URL;
+  const hasOpenAIKey = !!process.env.OPENAI_API_KEY;
+  const hasNeo4jUri = !!process.env.NEO4J_URI;
+  const hasMemgraphUri = !!process.env.MEMGRAPH_URI;
+
+  checks.environment = {
+    status: hasConvexUrl && hasOpenAIKey ? "ok" : "warning",
+    error: !hasConvexUrl
+      ? "CONVEX_URL not set"
+      : !hasOpenAIKey
+        ? "OPENAI_API_KEY not set"
+        : undefined,
+  };
+
+  // Check 2: Cortex SDK initialization
+  try {
+    const startTime = Date.now();
+    const cortex = new Cortex({
+      convexUrl: process.env.CONVEX_URL!,
+    });
+
+    // Quick test - just initialize, don't actually query
+    checks.cortexSdk = {
+      status: "ok",
+      latencyMs: Date.now() - startTime,
+    };
+
+    cortex.close();
+  } catch (error) {
+    checks.cortexSdk = {
+      status: "error",
+      error: error instanceof Error ? error.message : "Unknown error",
+    };
+  }
+
+  // Check 3: Convex backend connectivity (via HTTP)
+  if (process.env.CONVEX_URL) {
+    try {
+      const startTime = Date.now();
+      // Convex URLs are like "https://xxx.convex.cloud"
+      // We can ping the HTTP endpoint
+      const convexUrl = new URL(process.env.CONVEX_URL);
+      const response = await fetch(`${convexUrl.origin}/version`, {
+        method: "GET",
+        signal: AbortSignal.timeout(5000),
+      });
+
+      checks.convexBackend = {
+        status: response.ok ? "ok" : "error",
+        latencyMs: Date.now() - startTime,
+        error: response.ok ? undefined : `HTTP ${response.status}`,
+      };
+    } catch (error) {
+      checks.convexBackend = {
+        status: "error",
+        error: error instanceof Error ? error.message : "Connection failed",
+      };
+    }
+  } else {
+    checks.convexBackend = {
+      status: "error",
+      error: "CONVEX_URL not configured",
+    };
+  }
+
+  // Overall status
+  const hasErrors = Object.values(checks).some((c) => c.status === "error");
+  const hasWarnings = Object.values(checks).some((c) => c.status === "warning");
+
+  return Response.json({
+    status: hasErrors ? "unhealthy" : hasWarnings ? "degraded" : "healthy",
+    timestamp: new Date().toISOString(),
+    checks,
+    config: {
+      convexUrl: hasConvexUrl ? "configured" : "missing",
+      publicConvexUrl: hasPublicConvexUrl ? "configured" : "missing",
+      openaiKey: hasOpenAIKey ? "configured" : "missing",
+      graphSync: hasNeo4jUri || hasMemgraphUri ? "enabled" : "disabled",
+      graphBackend: hasNeo4jUri
+        ? "neo4j"
+        : hasMemgraphUri
+          ? "memgraph"
+          : "none",
+    },
+  });
+}

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

@@ -0,0 +1,37 @@
+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 limit = parseInt(searchParams.get("limit") || "20");
+
+    const cortex = getCortex();
+
+    // Fetch recent memories
+    const memories = await cortex.memory.list({
+      memorySpaceId,
+      limit,
+    });
+
+    return Response.json({
+      memories,
+      count: memories.length,
+      memorySpaceId,
+    });
+  } catch (error) {
+    console.error("[Memories API Error]", error);
+
+    return Response.json(
+      { error: error instanceof Error ? error.message : "Unknown error" },
+      { status: 500 },
+    );
+  }
+}

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

@@ -0,0 +1,114 @@
+@import "tailwindcss";
+
+/* Source paths for v4 */
+@source "../components/**/*.{js,ts,jsx,tsx}";
+@source "./**/*.{js,ts,jsx,tsx}";
+
+/* Custom theme for v4 */
+@theme {
+  --color-cortex-50: #f0f7ff;
+  --color-cortex-100: #e0effe;
+  --color-cortex-200: #b9dffc;
+  --color-cortex-300: #7cc5fa;
+  --color-cortex-400: #36a8f5;
+  --color-cortex-500: #0c8ce6;
+  --color-cortex-600: #006fc4;
+  --color-cortex-700: #0159a0;
+  --color-cortex-800: #064b84;
+  --color-cortex-900: #0b3f6d;
+  --color-cortex-950: #072848;
+}
+
+/* Custom scrollbar */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: rgba(255, 255, 255, 0.05);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb {
+  background: rgba(255, 255, 255, 0.2);
+  border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: rgba(255, 255, 255, 0.3);
+}
+
+/* Layer flow animations */
+@keyframes pulse-glow {
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(34, 197, 94, 0.4);
+  }
+  50% {
+    box-shadow: 0 0 0 10px rgba(34, 197, 94, 0);
+  }
+}
+
+@keyframes flow-down {
+  0% {
+    transform: translateY(-100%);
+    opacity: 0;
+  }
+  50% {
+    opacity: 1;
+  }
+  100% {
+    transform: translateY(100%);
+    opacity: 0;
+  }
+}
+
+.layer-complete {
+  animation: pulse-glow 1.5s ease-in-out;
+}
+
+.flow-indicator {
+  animation: flow-down 1.5s ease-in-out infinite;
+}
+
+/* Chat message animations */
+@keyframes message-in {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.message-animate {
+  animation: message-in 0.3s ease-out;
+}
+
+/* Gradient backgrounds */
+.gradient-radial {
+  background: radial-gradient(
+    ellipse at center,
+    var(--tw-gradient-from) 0%,
+    var(--tw-gradient-to) 70%
+  );
+}
+
+/* Glass effect */
+.glass {
+  background: rgba(255, 255, 255, 0.05);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+/* Code block styling */
+.code-block {
+  background: rgba(0, 0, 0, 0.3);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  font-family: "Monaco", "Menlo", "Ubuntu Mono", monospace;
+  font-size: 0.875rem;
+  line-height: 1.5;
+}

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

@@ -0,0 +1,19 @@
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Cortex Memory Quickstart",
+  description: "Interactive demo of Cortex Memory with Vercel AI SDK",
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className="bg-gray-900 text-white min-h-screen">{children}</body>
+    </html>
+  );
+}

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

@@ -0,0 +1,131 @@
+"use client";
+
+import dynamic from "next/dynamic";
+import { useState } from "react";
+import { useLayerTracking } from "@/lib/layer-tracking";
+
+// Dynamic imports to avoid SSR issues with framer-motion
+const ChatInterface = dynamic(
+  () =>
+    import("@/components/ChatInterface").then((m) => ({
+      default: m.ChatInterface,
+    })),
+  { ssr: false },
+);
+const LayerFlowDiagram = dynamic(
+  () =>
+    import("@/components/LayerFlowDiagram").then((m) => ({
+      default: m.LayerFlowDiagram,
+    })),
+  { ssr: false },
+);
+const MemorySpaceSwitcher = dynamic(
+  () =>
+    import("@/components/MemorySpaceSwitcher").then((m) => ({
+      default: m.MemorySpaceSwitcher,
+    })),
+  { ssr: false },
+);
+const HealthStatus = dynamic(
+  () =>
+    import("@/components/HealthStatus").then((m) => ({
+      default: m.HealthStatus,
+    })),
+  { ssr: false },
+);
+
+export default function Home() {
+  const [memorySpaceId, setMemorySpaceId] = useState("quickstart-demo");
+  const [userId] = useState("demo-user");
+  const {
+    layers,
+    isOrchestrating,
+    startOrchestration,
+    updateLayer,
+    resetLayers,
+  } = useLayerTracking();
+
+  return (
+    <main className="min-h-screen flex flex-col">
+      {/* Header */}
+      <header className="border-b border-white/10 px-6 py-4">
+        <div className="max-w-7xl mx-auto flex items-center justify-between">
+          <div className="flex items-center gap-3">
+            <div className="w-10 h-10 rounded-lg bg-gradient-to-br from-cortex-500 to-cortex-700 flex items-center justify-center">
+              <span className="text-xl">🧠</span>
+            </div>
+            <div>
+              <h1 className="text-xl font-bold">Cortex Memory Quickstart</h1>
+              <p className="text-sm text-gray-400">
+                Real-time memory orchestration demo
+              </p>
+            </div>
+          </div>
+
+          <div className="flex items-center gap-4">
+            <HealthStatus />
+            <MemorySpaceSwitcher
+              value={memorySpaceId}
+              onChange={setMemorySpaceId}
+            />
+          </div>
+        </div>
+      </header>
+
+      {/* Main Content */}
+      <div className="flex-1 flex overflow-hidden">
+        {/* Chat Section */}
+        <div className="flex-1 flex flex-col border-r border-white/10">
+          <ChatInterface
+            memorySpaceId={memorySpaceId}
+            userId={userId}
+            onOrchestrationStart={startOrchestration}
+            onLayerUpdate={updateLayer}
+            onReset={resetLayers}
+          />
+        </div>
+
+        {/* Layer Flow Visualization */}
+        <div className="w-[480px] flex flex-col bg-black/20">
+          <div className="p-4 border-b border-white/10">
+            <h2 className="font-semibold flex items-center gap-2">
+              <span className="text-lg">📊</span>
+              Memory Orchestration Flow
+            </h2>
+            <p className="text-sm text-gray-400 mt-1">
+              Watch data flow through Cortex layers in real-time
+            </p>
+          </div>
+
+          <div className="flex-1 overflow-y-auto p-4">
+            <LayerFlowDiagram
+              layers={layers}
+              isOrchestrating={isOrchestrating}
+              memorySpaceId={memorySpaceId}
+              userId={userId}
+            />
+          </div>
+        </div>
+      </div>
+
+      {/* Footer */}
+      <footer className="border-t border-white/10 px-6 py-3">
+        <div className="max-w-7xl mx-auto 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>•</span>
+            <span>Vercel AI SDK v5</span>
+          </div>
+          <a
+            href="https://cortexmemory.dev/docs"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="hover:text-white transition-colors"
+          >
+            Documentation →
+          </a>
+        </div>
+      </footer>
+    </main>
+  );
+}

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

@@ -0,0 +1,237 @@
+"use client";
+
+import { useChat } from "@ai-sdk/react";
+import { DefaultChatTransport } from "ai";
+import { useState, useRef, useEffect, useMemo, useCallback } from "react";
+import type {
+  LayerStatus,
+  MemoryLayer,
+  LayerState,
+  RevisionAction,
+} from "@/lib/layer-tracking";
+
+// Type for layer update data parts from the stream
+interface LayerUpdateData {
+  layer: MemoryLayer;
+  status: LayerStatus;
+  timestamp: number;
+  latencyMs?: number;
+  data?: LayerState["data"];
+  error?: { message: string; code?: string };
+  revisionAction?: RevisionAction;
+  supersededFacts?: string[];
+}
+
+interface ChatInterfaceProps {
+  memorySpaceId: string;
+  userId: string;
+  onOrchestrationStart?: () => void;
+  onLayerUpdate?: (
+    layer: MemoryLayer,
+    status: LayerStatus,
+    data?: LayerState["data"],
+    revisionInfo?: {
+      action?: RevisionAction;
+      supersededFacts?: string[];
+    },
+  ) => void;
+  onReset?: () => void;
+}
+
+export function ChatInterface({
+  memorySpaceId,
+  userId,
+  onOrchestrationStart,
+  onLayerUpdate,
+  onReset,
+}: ChatInterfaceProps) {
+  const messagesEndRef = useRef<HTMLDivElement>(null);
+  const [input, setInput] = useState("");
+  const [suggestedMessages] = useState([
+    "Hi! My name is Alex and I work at Acme Corp as a senior engineer.",
+    "My favorite color is blue and I love hiking on weekends.",
+    "I'm learning Spanish and prefer dark mode interfaces.",
+    "What do you remember about me?",
+  ]);
+
+  // Create transport with body parameters - memoized to prevent recreation
+  const transport = useMemo(
+    () =>
+      new DefaultChatTransport({
+        api: "/api/chat",
+        body: { memorySpaceId, userId },
+      }),
+    [memorySpaceId, userId],
+  );
+
+  // Handle layer data parts from the stream
+  const handleDataPart = useCallback(
+    (dataPart: any) => {
+      if (dataPart.type === "data-orchestration-start") {
+        onOrchestrationStart?.();
+      }
+
+      if (dataPart.type === "data-layer-update") {
+        const event = dataPart.data as LayerUpdateData;
+        onLayerUpdate?.(event.layer, event.status, event.data, {
+          action: event.revisionAction,
+          supersededFacts: event.supersededFacts,
+        });
+      }
+
+      // orchestration-complete is informational - layer diagram already updated
+      // via individual layer events
+    },
+    [onOrchestrationStart, onLayerUpdate],
+  );
+
+  const { messages, sendMessage, status } = useChat({
+    transport,
+    onData: handleDataPart,
+    onError: (error) => {
+      console.error("Chat error:", error);
+    },
+  });
+
+  // Determine if we're actively streaming (only time to show typing indicator)
+  const isStreaming = status === "streaming";
+
+  // Auto-scroll to latest message
+  useEffect(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages]);
+
+  // Handle form submission
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!input.trim() || isStreaming) return;
+
+    const message = input.trim();
+    setInput("");
+
+    try {
+      await sendMessage({ text: message });
+    } catch (error) {
+      console.error("Failed to send message:", error);
+    }
+  };
+
+  const handleSuggestedMessage = (message: string) => {
+    setInput(message);
+  };
+
+  // Extract text content from message parts (AI SDK v5 format)
+  const getMessageContent = (message: any): string => {
+    if (typeof message.content === "string") {
+      return message.content;
+    }
+    if (message.parts) {
+      return message.parts
+        .filter((part: any) => part.type === "text")
+        .map((part: any) => part.text)
+        .join("");
+    }
+    return "";
+  };
+
+  return (
+    <div className="flex flex-col h-full">
+      {/* Messages */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-4">
+        {messages.length === 0 && (
+          <div className="text-center py-12">
+            <div className="w-16 h-16 mx-auto mb-4 rounded-2xl bg-gradient-to-br from-cortex-500/20 to-cortex-700/20 flex items-center justify-center">
+              <span className="text-3xl">🧠</span>
+            </div>
+            <h2 className="text-xl font-semibold mb-2">
+              Welcome to Cortex Memory Demo
+            </h2>
+            <p className="text-gray-400 max-w-md mx-auto mb-6">
+              This demo shows how Cortex orchestrates memory across multiple
+              layers in real-time. Try telling me about yourself!
+            </p>
+
+            {/* Suggested messages */}
+            <div className="flex flex-wrap justify-center gap-2 max-w-lg mx-auto">
+              {suggestedMessages.map((msg, i) => (
+                <button
+                  key={i}
+                  onClick={() => handleSuggestedMessage(msg)}
+                  className="px-3 py-2 text-sm bg-white/5 hover:bg-white/10 rounded-lg border border-white/10 transition-colors text-left"
+                >
+                  {msg.length > 40 ? msg.slice(0, 40) + "..." : msg}
+                </button>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {messages.map((message, i) => (
+          <div
+            key={message.id || i}
+            className={`message-animate flex ${
+              message.role === "user" ? "justify-end" : "justify-start"
+            }`}
+          >
+            <div
+              className={`max-w-[80%] px-4 py-3 rounded-2xl ${
+                message.role === "user"
+                  ? "bg-cortex-600 text-white"
+                  : "bg-white/10 text-white"
+              }`}
+            >
+              <p className="whitespace-pre-wrap">
+                {getMessageContent(message)}
+              </p>
+            </div>
+          </div>
+        ))}
+
+        {/* Typing indicator - only show during active streaming */}
+        {isStreaming && (
+          <div className="flex justify-start">
+            <div className="bg-white/10 px-4 py-3 rounded-2xl">
+              <div className="flex gap-1">
+                <span className="w-2 h-2 bg-white/50 rounded-full animate-bounce" />
+                <span className="w-2 h-2 bg-white/50 rounded-full animate-bounce [animation-delay:0.1s]" />
+                <span className="w-2 h-2 bg-white/50 rounded-full animate-bounce [animation-delay:0.2s]" />
+              </div>
+            </div>
+          </div>
+        )}
+
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Input - only disabled during active streaming, NOT during background orchestration */}
+      <div className="border-t border-white/10 p-4">
+        <form onSubmit={handleSubmit} className="flex gap-2">
+          <input
+            type="text"
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            placeholder="Tell me about yourself..."
+            className="flex-1 px-4 py-3 bg-white/5 border border-white/10 rounded-xl focus:outline-none focus:border-cortex-500 transition-colors"
+            disabled={isStreaming}
+          />
+          <button
+            type="submit"
+            disabled={isStreaming || !input.trim()}
+            className="px-6 py-3 bg-cortex-600 hover:bg-cortex-700 disabled:opacity-50 disabled:cursor-not-allowed rounded-xl font-medium transition-colors"
+          >
+            Send
+          </button>
+        </form>
+
+        {messages.length > 0 && (
+          <button
+            onClick={onReset}
+            className="mt-2 text-sm text-gray-500 hover:text-white transition-colors"
+          >
+            Clear visualization →
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,21 @@
+"use client";
+
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { ReactNode, useMemo } from "react";
+
+export function ConvexClientProvider({ children }: { children: ReactNode }) {
+  const convex = useMemo(() => {
+    if (!process.env.NEXT_PUBLIC_CONVEX_URL) {
+      console.warn("NEXT_PUBLIC_CONVEX_URL not set");
+      return null;
+    }
+    return new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL);
+  }, []);
+
+  if (!convex) {
+    // Render without Convex for development without backend
+    return <>{children}</>;
+  }
+
+  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+}