@cortexmemory/cli 0.27.1 → 0.27.4

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

@@ -0,0 +1,202 @@
+"use client";
+
+import { useState } from "react";
+import { useAuth } from "./AuthProvider";
+
+type Tab = "login" | "register";
+
+export function LoginScreen() {
+  const { login, register, error, clearError } = useAuth();
+  const [activeTab, setActiveTab] = useState<Tab>("login");
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [isLoading, setIsLoading] = useState(false);
+  const [localError, setLocalError] = useState<string | null>(null);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLocalError(null);
+    clearError();
+
+    if (!username.trim()) {
+      setLocalError("Username is required");
+      return;
+    }
+
+    if (!password) {
+      setLocalError("Password is required");
+      return;
+    }
+
+    setIsLoading(true);
+
+    if (activeTab === "login") {
+      await login(username, password);
+    } else {
+      await register(username, password, displayName || undefined);
+    }
+
+    setIsLoading(false);
+  };
+
+  const handleTabChange = (tab: Tab) => {
+    setActiveTab(tab);
+    setLocalError(null);
+    clearError();
+  };
+
+  const displayError = localError || error;
+
+  return (
+    <div className="min-h-screen flex items-center justify-center p-4">
+      <div className="w-full max-w-md">
+        {/* Logo and Title */}
+        <div className="text-center mb-8">
+          <div className="w-20 h-20 mx-auto mb-6 rounded-2xl bg-gradient-to-br from-cortex-500 to-cortex-700 flex items-center justify-center shadow-lg shadow-cortex-500/20">
+            <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>
+        </div>
+
+        {/* Login/Register Card */}
+        <div className="glass rounded-2xl overflow-hidden">
+          {/* Tabs */}
+          <div className="flex border-b border-white/10">
+            <button
+              onClick={() => handleTabChange("login")}
+              className={`flex-1 py-4 text-sm font-medium transition-colors ${
+                activeTab === "login"
+                  ? "text-white border-b-2 border-cortex-500"
+                  : "text-gray-400 hover:text-white"
+              }`}
+            >
+              Sign In
+            </button>
+            <button
+              onClick={() => handleTabChange("register")}
+              className={`flex-1 py-4 text-sm font-medium transition-colors ${
+                activeTab === "register"
+                  ? "text-white border-b-2 border-cortex-500"
+                  : "text-gray-400 hover:text-white"
+              }`}
+            >
+              Create Account
+            </button>
+          </div>
+
+          {/* Form */}
+          <form onSubmit={handleSubmit} className="p-8 space-y-5">
+            <div>
+              <label
+                htmlFor="username"
+                className="block text-sm font-medium text-gray-300 mb-2"
+              >
+                Username
+              </label>
+              <input
+                id="username"
+                type="text"
+                value={username}
+                onChange={(e) => setUsername(e.target.value)}
+                placeholder="Enter your username"
+                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}
+                autoFocus
+                autoComplete="username"
+              />
+            </div>
+
+            {activeTab === "register" && (
+              <div>
+                <label
+                  htmlFor="displayName"
+                  className="block text-sm font-medium text-gray-300 mb-2"
+                >
+                  Display Name{" "}
+                  <span className="text-gray-500">(optional)</span>
+                </label>
+                <input
+                  id="displayName"
+                  type="text"
+                  value={displayName}
+                  onChange={(e) => setDisplayName(e.target.value)}
+                  placeholder="How should we call you?"
+                  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}
+                />
+              </div>
+            )}
+
+            <div>
+              <label
+                htmlFor="password"
+                className="block text-sm font-medium text-gray-300 mb-2"
+              >
+                Password
+              </label>
+              <input
+                id="password"
+                type="password"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                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"}
+              />
+            </div>
+
+            {displayError && (
+              <div className="p-3 bg-red-500/10 border border-red-500/20 rounded-xl text-red-400 text-sm">
+                {displayError}
+              </div>
+            )}
+
+            <button
+              type="submit"
+              disabled={isLoading || !username || !password}
+              className="w-full py-3 bg-cortex-600 hover:bg-cortex-700 disabled:opacity-50 disabled:cursor-not-allowed rounded-xl font-medium transition-colors flex items-center justify-center gap-2"
+            >
+              {isLoading ? (
+                <>
+                  <svg
+                    className="animate-spin h-5 w-5"
+                    xmlns="http://www.w3.org/2000/svg"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                  >
+                    <circle
+                      className="opacity-25"
+                      cx="12"
+                      cy="12"
+                      r="10"
+                      stroke="currentColor"
+                      strokeWidth="4"
+                    />
+                    <path
+                      className="opacity-75"
+                      fill="currentColor"
+                      d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+                    />
+                  </svg>
+                  {activeTab === "login" ? "Signing in..." : "Creating account..."}
+                </>
+              ) : activeTab === "login" ? (
+                "Sign In"
+              ) : (
+                "Create Account"
+              )}
+            </button>
+          </form>
+        </div>
+
+        {/* Demo hint */}
+        <p className="mt-6 text-center text-sm text-gray-500">
+          Create an account to start chatting with memory-enabled AI
+        </p>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Jest Configuration for Vercel AI Quickstart
+ *
+ * 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 = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  moduleNameMapper: {
+    // Handle path aliases from tsconfig
+    "^@/(.*)$": "<rootDir>/$1",
+  },
+  transform: {
+    "^.+\\.tsx?$": [
+      "ts-jest",
+      {
+        tsconfig: "tsconfig.json",
+      },
+    ],
+  },
+  setupFilesAfterEnv: ["<rootDir>/tests/helpers/setup.ts"],
+  // Ignore Next.js build output
+  testPathIgnorePatterns: ["/node_modules/", "/.next/"],
+};
+
+module.exports = {
+  ...baseConfig,
+  projects: [
+    {
+      ...baseConfig,
+      displayName: "unit",
+      testMatch: ["<rootDir>/tests/unit/**/*.test.ts"],
+      testTimeout: 10000,
+    },
+    {
+      ...baseConfig,
+      displayName: "integration",
+      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/cortex.ts

@@ -0,0 +1,27 @@
+/**
+ * Cortex SDK Client
+ *
+ * Shared Cortex client instance for API routes.
+ */
+
+import { Cortex } from "@cortexmemory/sdk";
+
+let cortexClient: Cortex | null = null;
+
+/**
+ * Get or create a Cortex SDK client
+ */
+export function getCortex(): Cortex {
+  if (!cortexClient) {
+    const convexUrl = process.env.CONVEX_URL;
+    if (!convexUrl) {
+      throw new Error("CONVEX_URL environment variable is required");
+    }
+
+    cortexClient = new Cortex({
+      convexUrl,
+    });
+  }
+
+  return cortexClient;
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Password Hashing Utilities
+ *
+ * Uses Web Crypto API (PBKDF2) for password hashing.
+ * Works in Edge runtime - no external dependencies.
+ */
+
+const ITERATIONS = 100000;
+const KEY_LENGTH = 256;
+const SALT_LENGTH = 16;
+
+/**
+ * Hash a password using PBKDF2
+ *
+ * @param password - Plain text password to hash
+ * @returns Hashed password as base64 string (format: salt:hash)
+ */
+export async function hashPassword(password: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const passwordBuffer = encoder.encode(password);
+
+  // Generate random salt
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+
+  // Import password as key material
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    passwordBuffer,
+    "PBKDF2",
+    false,
+    ["deriveBits"]
+  );
+
+  // Derive key using PBKDF2
+  const derivedBits = await crypto.subtle.deriveBits(
+    {
+      name: "PBKDF2",
+      salt,
+      iterations: ITERATIONS,
+      hash: "SHA-256",
+    },
+    keyMaterial,
+    KEY_LENGTH
+  );
+
+  // Convert to base64 strings
+  const saltB64 = btoa(String.fromCharCode(...salt));
+  const hashB64 = btoa(String.fromCharCode(...new Uint8Array(derivedBits)));
+
+  // Return combined format: salt:hash
+  return `${saltB64}:${hashB64}`;
+}
+
+/**
+ * Verify a password against a stored hash
+ *
+ * @param password - Plain text password to verify
+ * @param storedHash - Previously hashed password (format: salt:hash)
+ * @returns True if password matches
+ */
+export async function verifyPassword(
+  password: string,
+  storedHash: string
+): Promise<boolean> {
+  try {
+    const [saltB64, expectedHashB64] = storedHash.split(":");
+    if (!saltB64 || !expectedHashB64) {
+      return false;
+    }
+
+    const encoder = new TextEncoder();
+    const passwordBuffer = encoder.encode(password);
+
+    // Decode salt from base64
+    const saltStr = atob(saltB64);
+    const salt = new Uint8Array(saltStr.length);
+    for (let i = 0; i < saltStr.length; i++) {
+      salt[i] = saltStr.charCodeAt(i);
+    }
+
+    // Import password as key material
+    const keyMaterial = await crypto.subtle.importKey(
+      "raw",
+      passwordBuffer,
+      "PBKDF2",
+      false,
+      ["deriveBits"]
+    );
+
+    // Derive key using same parameters
+    const derivedBits = await crypto.subtle.deriveBits(
+      {
+        name: "PBKDF2",
+        salt,
+        iterations: ITERATIONS,
+        hash: "SHA-256",
+      },
+      keyMaterial,
+      KEY_LENGTH
+    );
+
+    // Compare hashes
+    const hashB64 = btoa(String.fromCharCode(...new Uint8Array(derivedBits)));
+    return hashB64 === expectedHashB64;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Generate a secure random session token
+ *
+ * @returns Random token as hex string
+ */
+export function generateSessionToken(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}

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/next.config.js

@@ -1,7 +1,27 @@
+const path = require("path");
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   transpilePackages: ["@cortexmemory/sdk", "@cortexmemory/vercel-ai-provider"],
   serverExternalPackages: ["convex"],
+  experimental: {
+    // Ensure linked packages resolve dependencies from this project's node_modules
+    externalDir: true,
+  },
+  // Empty turbopack config to silence the warning about missing turbopack config
+  turbopack: {},
+  // Webpack configuration for module resolution when SDK is file-linked
+  // This is needed because the SDK uses dynamic imports that don't resolve
+  // correctly from a linked package's location during local development
+  webpack: (config) => {
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      "@anthropic-ai/sdk": path.resolve(__dirname, "node_modules/@anthropic-ai/sdk"),
+      "openai": path.resolve(__dirname, "node_modules/openai"),
+      "neo4j-driver": path.resolve(__dirname, "node_modules/neo4j-driver"),
+    };
+    return config;
+  },
 };
 
 module.exports = nextConfig;

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

@@ -5,10 +5,16 @@
   "license": "UNLICENSED",
   "description": "Cortex Memory + Vercel AI SDK Quickstart Demo",
   "scripts": {
-    "dev": "next dev",
-    "build": "next build",
+    "dev": "next dev --webpack",
+    "build": "next build --webpack",
     "start": "next start",
     "lint": "next lint",
+    "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"
   },
@@ -30,12 +36,15 @@
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",
+    "@types/jest": "^29.5.14",
     "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "autoprefixer": "^10.4.23",
+    "jest": "^29.7.0",
     "postcss": "^8.5.6",
     "tailwindcss": "^4.1.18",
+    "ts-jest": "^29.2.5",
     "typescript": "^5.9.3"
   }
 }