@cortexmemory/cli 0.26.2 → 0.27.1

package/templates/vercel-ai-quickstart/README.md

@@ -0,0 +1,280 @@
+# Cortex Memory + Vercel AI SDK Quickstart
+
+This is the official quickstart demo for **Cortex Memory** with the **Vercel AI SDK**. It provides an interactive visualization of how data flows through the Cortex memory orchestration system in real-time.
+
+> **SDK v0.24.0**: Now with **Belief Revision**! When users change their preferences (e.g., "I now prefer purple" after saying "I like blue"), Cortex intelligently updates or supersedes existing facts instead of creating duplicates.
+
+## Features
+
+- 🧠 **Real-time Memory Visualization** - Watch data flow through all Cortex layers (Memory Space → User → Agent → Conversation → Vector → Facts → Graph)
+- 💬 **Interactive Chat** - Send messages and see them processed with automatic memory storage
+- 📊 **Layer Flow Diagram** - Animated visualization showing latency and data at each layer
+- 🔀 **Memory Space Switching** - Demonstrate multi-tenant isolation by switching between memory spaces
+- ⚡ **Streaming Support** - Full streaming with progressive fact extraction
+- 🧹 **Belief Revision** - Intelligent fact updates when information changes (v0.24.0)
+- 🔄 **Smart Fact Deduplication** - Semantic matching prevents duplicate facts across sessions (v0.22.0)
+
+## Prerequisites
+
+- Node.js 18+
+- A Convex deployment ([get started](https://www.convex.dev/))
+- An OpenAI API key ([get one](https://platform.openai.com/api-keys))
+
+## Quick Start
+
+### Local Development (within monorepo)
+
+1. **Install dependencies**
+
+```bash
+cd packages/vercel-ai-provider/quickstart
+npm install
+```
+
+> **Note**: The `package.json` uses `file:` references to link to the local SDK and provider packages. This allows you to test changes to the provider immediately.
+
+### Using Published Packages
+
+If you want to use the published npm packages instead, update `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@cortexmemory/sdk": "^0.24.0",
+    "@cortexmemory/vercel-ai-provider": "^1.0.0"
+    // ... other deps
+  }
+}
+```
+
+2. **Set up environment variables**
+
+```bash
+cp .env.local.example .env.local
+```
+
+Edit `.env.local` and add your credentials:
+
+```env
+CONVEX_URL=https://your-project.convex.cloud
+NEXT_PUBLIC_CONVEX_URL=https://your-project.convex.cloud
+OPENAI_API_KEY=sk-...
+```
+
+3. **Deploy Convex schema**
+
+```bash
+npm run convex:dev
+```
+
+4. **Start the development server**
+
+```bash
+npm run dev
+```
+
+5. **Open the demo**
+
+Visit [http://localhost:3000](http://localhost:3000) to see the demo in action.
+
+## What This Demo Shows
+
+### Memory Layer Orchestration
+
+When you send a message, you'll see it flow through these layers:
+
+| Layer            | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| **Memory Space** | Isolated namespace for multi-tenancy            |
+| **User**         | User profile and identity                       |
+| **Agent**        | AI agent participant (required in SDK v0.17.0+) |
+| **Conversation** | Message storage with threading                  |
+| **Vector**       | Semantic embeddings for similarity search       |
+| **Facts**        | Extracted structured information                |
+| **Graph**        | Entity relationships (optional)                 |
+
+### Key Features Demonstrated
+
+1. **Belief Revision** - SDK v0.24.0 intelligently updates/supersedes facts when information changes
+2. **Unified Retrieval (recall)** - SDK v0.23.0 retrieves from vector + facts + graph in one call
+3. **agentId Requirement** - SDK v0.17.0+ requires `agentId` for all user-agent conversations
+4. **Automatic Fact Extraction** - LLM-powered extraction of preferences, identity, relationships
+5. **Semantic Fact Deduplication** - SDK v0.22.0 automatically prevents duplicate facts using embedding similarity
+6. **Multi-tenant Isolation** - Switch memory spaces to see complete isolation
+7. **Streaming with Memory** - Full streaming support with progressive storage
+
+## Configuration
+
+The chat API route at `/app/api/chat/route.ts` shows how to configure the Cortex Memory provider:
+
+```typescript
+import { createCortexMemory } from "@cortexmemory/vercel-ai-provider";
+import { openai, createOpenAI } from "@ai-sdk/openai";
+import { streamText, embed } from "ai";
+
+const openaiClient = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+
+const cortexMemory = createCortexMemory({
+  convexUrl: process.env.CONVEX_URL!,
+  memorySpaceId: "quickstart-demo",
+
+  // User identification
+  userId: "demo-user",
+  userName: "Demo User",
+
+  // Agent identification (REQUIRED in SDK v0.17.0+)
+  agentId: "quickstart-assistant",
+  agentName: "Cortex Demo Assistant",
+
+  // Optional features
+  enableGraphMemory: process.env.CORTEX_GRAPH_SYNC === "true",
+  enableFactExtraction: process.env.CORTEX_FACT_EXTRACTION === "true",
+
+  // Belief Revision (v0.24.0+)
+  // Automatically handles fact updates when user changes their mind
+  // e.g., "I like blue" → "I prefer purple" will UPDATE/SUPERSEDE the old fact
+  beliefRevision: {
+    enabled: true,
+    slotMatching: true, // Fast slot-based conflict detection
+    llmResolution: true, // LLM-based resolution for nuanced conflicts
+  },
+
+  // Embedding provider (required for semantic matching)
+  embeddingProvider: {
+    generate: async (text) => {
+      const result = await embed({
+        model: openaiClient.embedding("text-embedding-3-small"),
+        value: text,
+      });
+      return result.embedding;
+    },
+  },
+});
+
+const result = await streamText({
+  model: cortexMemory(openai("gpt-4o-mini")),
+  messages,
+});
+```
+
+## Architecture
+
+```
+quickstart/
+├── app/
+│   ├── api/
+│   │   ├── chat/route.ts      # Main chat endpoint with Cortex
+│   │   ├── memories/route.ts  # Memory inspection endpoint
+│   │   └── facts/route.ts     # Facts inspection endpoint
+│   ├── layout.tsx
+│   ├── page.tsx               # Main demo page
+│   └── globals.css
+├── components/
+│   ├── ChatInterface.tsx      # Chat UI component
+│   ├── LayerFlowDiagram.tsx   # Hero visualization component
+│   ├── LayerCard.tsx          # Individual layer status card
+│   ├── DataPreview.tsx        # Expandable data viewer
+│   └── MemorySpaceSwitcher.tsx
+├── lib/
+│   ├── layer-tracking.ts      # Layer status management
+│   └── animations.ts          # Framer Motion variants
+└── convex/
+    ├── schema.ts              # Convex schema
+    ├── conversations.ts       # Conversation queries
+    ├── memories.ts            # Memory queries
+    ├── facts.ts               # Facts queries
+    └── users.ts               # User queries
+```
+
+## Learn More
+
+- [Cortex Memory Documentation](https://cortexmemory.dev/docs)
+- [Vercel AI SDK Documentation](https://sdk.vercel.ai/docs)
+- [API Reference](/Documentation/03-api-reference/02-memory-operations.md)
+
+## Troubleshooting
+
+### "agentId is required"
+
+Since SDK v0.17.0, all user-agent conversations require an `agentId`. Add it to your configuration:
+
+```typescript
+const cortexMemory = createCortexMemory({
+  // ... other config
+  agentId: "my-assistant", // Required!
+});
+```
+
+### Memories not appearing
+
+1. Check that your Convex deployment is running
+2. Verify `CONVEX_URL` is set correctly
+3. Ensure the memory space ID matches between frontend and backend
+
+### Fact extraction not working
+
+Enable fact extraction via environment variable:
+
+```env
+CORTEX_FACT_EXTRACTION=true
+```
+
+### Duplicate facts being created
+
+Ensure you have `embeddingProvider` configured for optimal semantic deduplication:
+
+```typescript
+const cortexMemory = createCortexMemory({
+  // ... other config
+  embeddingProvider: {
+    generate: async (text) => {
+      const result = await embed({
+        model: openaiClient.embedding("text-embedding-3-small"),
+        value: text,
+      });
+      return result.embedding;
+    },
+  },
+});
+```
+
+Without `embeddingProvider`, deduplication falls back to `structural` matching (subject + predicate + object), which is less accurate for semantically similar facts.
+
+To disable deduplication entirely (not recommended):
+
+```typescript
+const cortexMemory = createCortexMemory({
+  // ... other config
+  factDeduplication: false, // Uses pre-v0.22.0 behavior
+});
+```
+
+### Facts not being updated when user changes preferences
+
+If you say "I like blue" then later say "I prefer purple" and both facts remain, enable **Belief Revision** (v0.24.0+):
+
+```typescript
+const cortexMemory = createCortexMemory({
+  // ... other config
+  beliefRevision: {
+    enabled: true,
+    slotMatching: true, // Fast detection via subject-predicate matching
+    llmResolution: true, // LLM resolves nuanced conflicts
+  },
+});
+```
+
+**Revision actions explained:**
+
+| Action      | Description                                        | Example                               |
+| ----------- | -------------------------------------------------- | ------------------------------------- |
+| `CREATE`    | New fact with no conflicts                         | First time mentioning favorite color  |
+| `UPDATE`    | Existing fact refined with new details             | "I like blue" → "I love dark blue"    |
+| `SUPERSEDE` | Old fact replaced by contradicting new information | "I like blue" → "I prefer purple now" |
+| `NONE`      | Duplicate or irrelevant, no storage needed         | Saying "I like blue" twice            |
+
+The demo visualization shows these actions with colored badges on the Facts layer.
+
+## License
+
+FSL-1.1-Apache-2.0 - See LICENSE.md in the root of the repository.

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

@@ -0,0 +1,196 @@
+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";
+
+// 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,
+  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",
+
+    // 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",
+  };
+}
+
+export async function POST(req: Request) {
+  try {
+    const body = await req.json();
+    const { messages, memorySpaceId, userId } = body;
+
+    // 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;
+
+    // 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
+          const config = getCortexMemoryConfig(
+            memorySpaceId || "quickstart-demo",
+            userId || "demo-user",
+            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());
+        },
+      }),
+    });
+  } 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/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 },
+    );
+  }
+}

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 },
+    );
+  }
+}