@cortexmemory/cli 0.26.2 → 0.27.3

package/templates/vercel-ai-quickstart/convex/health.ts

@@ -0,0 +1,15 @@
+import { query } from "./_generated/server";
+
+/**
+ * Simple health check query to verify Convex backend is reachable
+ */
+export const ping = query({
+  args: {},
+  handler: async () => {
+    return {
+      status: "ok",
+      timestamp: Date.now(),
+      backend: "convex",
+    };
+  },
+});

package/templates/vercel-ai-quickstart/convex/memories.ts

@@ -0,0 +1,104 @@
+/**
+ * Convex queries for real-time memory updates
+ *
+ * These queries enable the LayerFlowDiagram to show live updates
+ * as vector memories are created in the Cortex system.
+ */
+
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+
+/**
+ * Get recent memories for a memory space
+ *
+ * Used by the demo to watch for new memories being created.
+ */
+export const getRecent = query({
+  args: {
+    memorySpaceId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 10;
+
+    // Query memories table (from Cortex SDK schema)
+    const memories = await ctx.db
+      .query("memories")
+      .filter((q) => q.eq(q.field("memorySpaceId"), args.memorySpaceId))
+      .order("desc")
+      .take(limit);
+
+    return memories;
+  },
+});
+
+/**
+ * Get memories for a specific user
+ */
+export const getByUser = query({
+  args: {
+    memorySpaceId: v.string(),
+    userId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 20;
+
+    const memories = await ctx.db
+      .query("memories")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("memorySpaceId"), args.memorySpaceId),
+          q.eq(q.field("userId"), args.userId),
+        ),
+      )
+      .order("desc")
+      .take(limit);
+
+    return memories;
+  },
+});
+
+/**
+ * Get memory count for a memory space
+ */
+export const count = query({
+  args: {
+    memorySpaceId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const memories = await ctx.db
+      .query("memories")
+      .filter((q) => q.eq(q.field("memorySpaceId"), args.memorySpaceId))
+      .collect();
+
+    return memories.length;
+  },
+});
+
+/**
+ * Search memories by content (simple text search for demo)
+ */
+export const search = query({
+  args: {
+    memorySpaceId: v.string(),
+    query: v.string(),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 5;
+    const queryLower = args.query.toLowerCase();
+
+    // Simple text search (in production, use vector search)
+    const allMemories = await ctx.db
+      .query("memories")
+      .filter((q) => q.eq(q.field("memorySpaceId"), args.memorySpaceId))
+      .collect();
+
+    const matching = allMemories
+      .filter((m) => m.content?.toLowerCase().includes(queryLower))
+      .slice(0, limit);
+
+    return matching;
+  },
+});

package/templates/vercel-ai-quickstart/convex/schema.ts

@@ -0,0 +1,20 @@
+/**
+ * Convex schema for the quickstart demo
+ *
+ * This extends the Cortex SDK schema to add any demo-specific tables.
+ * The actual memory tables (conversations, memories, facts) come from @cortexmemory/sdk.
+ */
+
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  // Demo session tracking (optional, for demo purposes)
+  demoSessions: defineTable({
+    sessionId: v.string(),
+    userId: v.string(),
+    memorySpaceId: v.string(),
+    startedAt: v.number(),
+    messageCount: v.number(),
+  }).index("by_session", ["sessionId"]),
+});

package/templates/vercel-ai-quickstart/convex/users.ts

@@ -0,0 +1,105 @@
+/**
+ * Convex queries for user profile data
+ *
+ * These queries enable the LayerFlowDiagram to show user context
+ * during memory orchestration.
+ */
+
+import { query } from "./_generated/server";
+import { v } from "convex/values";
+
+/**
+ * Get user profile by ID
+ *
+ * Returns user information stored in the Cortex system.
+ */
+export const get = query({
+  args: {
+    userId: v.string(),
+    memorySpaceId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    // Query users table (from Cortex SDK schema)
+    const user = await ctx.db
+      .query("users")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("userId"), args.userId),
+          q.eq(q.field("memorySpaceId"), args.memorySpaceId),
+        ),
+      )
+      .first();
+
+    return user;
+  },
+});
+
+/**
+ * Get users in a memory space
+ */
+export const list = query({
+  args: {
+    memorySpaceId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const limit = args.limit ?? 20;
+
+    const users = await ctx.db
+      .query("users")
+      .filter((q) => q.eq(q.field("memorySpaceId"), args.memorySpaceId))
+      .take(limit);
+
+    return users;
+  },
+});
+
+/**
+ * Get user stats (memory count, fact count, etc.)
+ */
+export const stats = query({
+  args: {
+    userId: v.string(),
+    memorySpaceId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    // Count memories
+    const memories = await ctx.db
+      .query("memories")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("userId"), args.userId),
+          q.eq(q.field("memorySpaceId"), args.memorySpaceId),
+        ),
+      )
+      .collect();
+
+    // Count facts
+    const facts = await ctx.db
+      .query("facts")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("userId"), args.userId),
+          q.eq(q.field("memorySpaceId"), args.memorySpaceId),
+        ),
+      )
+      .collect();
+
+    // Count conversations
+    const conversations = await ctx.db
+      .query("conversations")
+      .filter((q) =>
+        q.and(
+          q.eq(q.field("userId"), args.userId),
+          q.eq(q.field("memorySpaceId"), args.memorySpaceId),
+        ),
+      )
+      .collect();
+
+    return {
+      memoryCount: memories.length,
+      factCount: facts.length,
+      conversationCount: conversations.length,
+    };
+  },
+});

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

@@ -0,0 +1,45 @@
+/**
+ * Jest Configuration for Vercel AI Quickstart
+ *
+ * Two test projects:
+ * - unit: Fast unit tests with mocked dependencies
+ * - integration: Integration tests for API routes with mocked SDK
+ */
+
+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,
+    },
+  ],
+};

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

@@ -0,0 +1,146 @@
+import type { Variants } from "framer-motion";
+
+/**
+ * Framer Motion animation variants for the layer flow visualization
+ */
+
+// Layer card entrance animation
+export const layerCardVariants: Variants = {
+  hidden: {
+    opacity: 0,
+    x: -20,
+    scale: 0.95,
+  },
+  visible: (i: number) => ({
+    opacity: 1,
+    x: 0,
+    scale: 1,
+    transition: {
+      delay: i * 0.1,
+      duration: 0.3,
+      ease: "easeOut",
+    },
+  }),
+  exit: {
+    opacity: 0,
+    x: 20,
+    transition: {
+      duration: 0.2,
+    },
+  },
+};
+
+// Status indicator pulse animation
+export const statusPulseVariants: Variants = {
+  pending: {
+    scale: 1,
+    opacity: 0.5,
+  },
+  processing: {
+    scale: [1, 1.2, 1],
+    opacity: [0.5, 1, 0.5],
+    transition: {
+      duration: 1,
+      repeat: Infinity,
+      ease: "easeInOut",
+    },
+  },
+  complete: {
+    scale: [1, 1.3, 1],
+    opacity: 1,
+    transition: {
+      duration: 0.3,
+      ease: "easeOut",
+    },
+  },
+};
+
+// Flow line animation
+export const flowLineVariants: Variants = {
+  idle: {
+    opacity: 0.2,
+    pathLength: 0,
+  },
+  flowing: {
+    opacity: [0.2, 1, 0.2],
+    pathLength: [0, 1, 0],
+    transition: {
+      duration: 1.5,
+      repeat: Infinity,
+      ease: "easeInOut",
+    },
+  },
+  complete: {
+    opacity: 1,
+    pathLength: 1,
+  },
+};
+
+// Data preview expand animation
+export const dataPreviewVariants: Variants = {
+  collapsed: {
+    height: 0,
+    opacity: 0,
+  },
+  expanded: {
+    height: "auto",
+    opacity: 1,
+    transition: {
+      height: {
+        duration: 0.3,
+        ease: "easeOut",
+      },
+      opacity: {
+        duration: 0.2,
+        delay: 0.1,
+      },
+    },
+  },
+};
+
+// Message animation
+export const messageVariants: Variants = {
+  hidden: {
+    opacity: 0,
+    y: 10,
+    scale: 0.95,
+  },
+  visible: {
+    opacity: 1,
+    y: 0,
+    scale: 1,
+    transition: {
+      duration: 0.2,
+      ease: "easeOut",
+    },
+  },
+};
+
+// Stagger children animation
+export const staggerContainerVariants: Variants = {
+  hidden: { opacity: 0 },
+  visible: {
+    opacity: 1,
+    transition: {
+      staggerChildren: 0.1,
+      delayChildren: 0.2,
+    },
+  },
+};
+
+// Glow effect animation (for completed layers)
+export const glowVariants: Variants = {
+  idle: {
+    boxShadow: "0 0 0 0 rgba(34, 197, 94, 0)",
+  },
+  glow: {
+    boxShadow: [
+      "0 0 0 0 rgba(34, 197, 94, 0.4)",
+      "0 0 0 10px rgba(34, 197, 94, 0)",
+    ],
+    transition: {
+      duration: 0.6,
+      ease: "easeOut",
+    },
+  },
+};

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/layer-tracking.ts

@@ -0,0 +1,214 @@
+"use client";
+
+import { useState, useCallback } from "react";
+
+// Layer types (defined locally to avoid import issues before npm install)
+export type MemoryLayer =
+  | "memorySpace"
+  | "user"
+  | "agent"
+  | "conversation"
+  | "vector"
+  | "facts"
+  | "graph";
+
+export type LayerStatus =
+  | "pending"
+  | "in_progress"
+  | "complete"
+  | "error"
+  | "skipped";
+
+/**
+ * Revision action taken by the belief revision system (v0.24.0+)
+ * - ADD: New fact was created (no conflicts)
+ * - UPDATE: Existing fact was updated with new information
+ * - SUPERSEDE: Old fact was superseded by contradicting information
+ * - NONE: No action taken (duplicate or irrelevant)
+ */
+export type RevisionAction = "ADD" | "UPDATE" | "SUPERSEDE" | "NONE";
+
+export interface LayerState {
+  status: LayerStatus;
+  latencyMs?: number;
+  data?: {
+    id?: string;
+    preview?: string;
+    metadata?: Record<string, unknown>;
+  };
+  startedAt?: number;
+  completedAt?: number;
+  /**
+   * Revision action taken (v0.24.0+)
+   * Only present for facts layer when belief revision is enabled
+   */
+  revisionAction?: RevisionAction;
+  /**
+   * Facts that were superseded by this action (v0.24.0+)
+   * Only present when revisionAction is "SUPERSEDE"
+   */
+  supersededFacts?: string[];
+}
+
+export interface LayerTrackingState {
+  layers: Record<string, LayerState>;
+  isOrchestrating: boolean;
+  orchestrationStartTime?: number;
+}
+
+const initialLayerState: LayerState = {
+  status: "pending",
+};
+
+const allLayers: MemoryLayer[] = [
+  "memorySpace",
+  "user",
+  "agent",
+  "conversation",
+  "vector",
+  "facts",
+  "graph",
+];
+
+export function useLayerTracking() {
+  const [state, setState] = useState<LayerTrackingState>({
+    layers: Object.fromEntries(
+      allLayers.map((layer) => [layer, { ...initialLayerState }]),
+    ),
+    isOrchestrating: false,
+  });
+
+  const startOrchestration = useCallback(() => {
+    const now = Date.now();
+    setState({
+      layers: Object.fromEntries(
+        allLayers.map((layer) => [
+          layer,
+          { status: "pending" as LayerStatus, startedAt: now },
+        ]),
+      ),
+      isOrchestrating: true,
+      orchestrationStartTime: now,
+    });
+  }, []);
+
+  const updateLayer = useCallback(
+    (
+      layer: MemoryLayer,
+      status: LayerStatus,
+      data?: LayerState["data"],
+      revisionInfo?: {
+        action?: RevisionAction;
+        supersededFacts?: string[];
+      },
+    ) => {
+      setState((prev: LayerTrackingState) => {
+        const now = Date.now();
+        const layerState = prev.layers[layer];
+        const latencyMs = layerState?.startedAt
+          ? now - layerState.startedAt
+          : prev.orchestrationStartTime
+            ? now - prev.orchestrationStartTime
+            : undefined;
+
+        // Check if all layers are complete
+        const updatedLayers: Record<string, LayerState> = {
+          ...prev.layers,
+          [layer]: {
+            ...layerState,
+            status,
+            latencyMs,
+            data,
+            completedAt: status === "complete" ? now : layerState?.completedAt,
+            // Belief revision info (v0.24.0+)
+            revisionAction: revisionInfo?.action,
+            supersededFacts: revisionInfo?.supersededFacts,
+          },
+        };
+
+        const isStillOrchestrating = Object.values(updatedLayers).some(
+          (l: LayerState) =>
+            l.status === "pending" || l.status === "in_progress",
+        );
+
+        return {
+          ...prev,
+          layers: updatedLayers,
+          isOrchestrating: isStillOrchestrating,
+        };
+      });
+    },
+    [],
+  );
+
+  const resetLayers = useCallback(() => {
+    setState({
+      layers: Object.fromEntries(
+        allLayers.map((layer) => [layer, { ...initialLayerState }]),
+      ),
+      isOrchestrating: false,
+    });
+  }, []);
+
+  return {
+    layers: state.layers,
+    isOrchestrating: state.isOrchestrating,
+    startOrchestration,
+    updateLayer,
+    resetLayers,
+  };
+}
+
+/**
+ * Generate sample data for layer previews (used in demos)
+ */
+export function generateSampleLayerData(
+  layer: MemoryLayer,
+  userMessage?: string,
+): LayerState["data"] {
+  switch (layer) {
+    case "memorySpace":
+      return {
+        id: "quickstart-demo",
+        preview: "Memory space for demo",
+        metadata: { isolation: "full" },
+      };
+    case "user":
+      return {
+        id: "demo-user",
+        preview: "Demo User",
+        metadata: { memories: 5 },
+      };
+    case "agent":
+      return {
+        id: "quickstart-assistant",
+        preview: "Cortex Demo Assistant",
+      };
+    case "conversation":
+      return {
+        id: `conv-${Date.now()}`,
+        preview: userMessage?.slice(0, 50) || "New conversation",
+        metadata: { messages: 2 },
+      };
+    case "vector":
+      return {
+        id: `mem-${Date.now()}`,
+        preview: "Embedded content...",
+        metadata: { dimensions: 1536, importance: 75 },
+      };
+    case "facts":
+      return {
+        id: `fact-${Date.now()}`,
+        preview: "Extracted facts from conversation",
+        metadata: { count: 3, types: ["identity", "preference"] },
+      };
+    case "graph":
+      return {
+        id: `graph-sync-${Date.now()}`,
+        preview: "Entity relationships",
+        metadata: { nodes: 4, edges: 3 },
+      };
+    default:
+      return undefined;
+  }
+}