@cortexmemory/cli 0.28.1 → 0.31.0

package/templates/basic/package.json

@@ -19,20 +19,20 @@
   },
   "dependencies": {
     "@cortexmemory/sdk": "latest",
-    "convex": "^1.31.2",
+    "convex": "^1.31.4",
     "dotenv": "^17.2.3",
-    "hono": "^4.11.3",
-    "@hono/node-server": "^1.19.7"
+    "hono": "^4.11.4",
+    "@hono/node-server": "^1.19.8"
   },
   "devDependencies": {
-    "@types/node": "^25.0.3",
-    "@vitest/coverage-v8": "^4.0.16",
+    "@types/node": "^25.0.7",
+    "@vitest/coverage-v8": "^4.0.17",
     "typescript": "^5.9.3",
     "tsx": "^4.21.0",
-    "vitest": "^4.0.16"
+    "vitest": "^4.0.17"
   },
   "optionalDependencies": {
-    "openai": "^6.15.0"
+    "openai": "^6.16.0"
   },
   "engines": {
     "node": ">=20"

package/templates/basic/src/chat.ts

@@ -45,6 +45,20 @@ export interface Fact {
   subject?: string;
 }
 
+/**
+ * Transform SDK FactRecord to local Fact interface
+ * SDK uses 'fact' field, local interface uses 'content'
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function transformFacts(sdkFacts: any[]): Fact[] {
+  return sdkFacts.map((f) => ({
+    content: f.fact || f.content || "", // SDK uses 'fact', fallback to 'content'
+    factType: f.factType,
+    confidence: f.confidence,
+    subject: f.subject,
+  }));
+}
+
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Conversation State
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -122,7 +136,9 @@ export async function chat(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result = recallResult as any;
     memories = (result.sources?.vector?.items || result.memories || []) as Memory[];
-    facts = (result.sources?.facts?.items || result.facts || []) as Fact[];
+    // Transform facts: SDK FactRecord uses 'fact' field, local Fact uses 'content'
+    const rawFacts = result.sources?.facts?.items || result.facts || [];
+    facts = transformFacts(rawFacts);
 
     stopSpinner(true, `Found ${memories.length} memories, ${facts.length} facts`);
 
@@ -207,7 +223,9 @@ export async function recallMemories(query: string): Promise<void> {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result = recallResult as any;
     const memories = (result.sources?.vector?.items || result.memories || []) as Memory[];
-    const facts = (result.sources?.facts?.items || result.facts || []) as Fact[];
+    // Transform facts: SDK FactRecord uses 'fact' field, local Fact uses 'content'
+    const rawFacts = result.sources?.facts?.items || result.facts || [];
+    const facts = transformFacts(rawFacts);
 
     stopSpinner(true, `Found ${memories.length} memories, ${facts.length} facts`);
     printRecallResults(memories, facts);
@@ -231,7 +249,10 @@ export async function listFacts(): Promise<void> {
       limit: 20,
     });
 
-    const facts = (result.facts || result || []) as Fact[];
+    // Transform facts: SDK returns FactRecord[] directly with 'fact' field
+    // Local Fact interface uses 'content'
+    const rawFacts = Array.isArray(result) ? result : [];
+    const facts = transformFacts(rawFacts);
 
     stopSpinner(true, `Found ${facts.length} facts`);
     printRecallResults([], facts);

package/templates/basic/src/cortex.ts

@@ -38,12 +38,28 @@ export const CONFIG = {
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 let cortexClient: Cortex | null = null;
+let initPromise: Promise<Cortex> | null = null;
 
 /**
- * Get or create a Cortex SDK client
+ * Initialize the Cortex SDK client (async)
+ *
+ * Uses Cortex.create() for automatic graph configuration from env vars.
+ * When CORTEX_GRAPH_SYNC=true and NEO4J_URI (or MEMGRAPH_URI) is set,
+ * the graph adapter is automatically created and connected.
+ *
+ * v0.29.0+: Graph sync is automatic when graphAdapter is configured.
+ * No need to pass syncToGraph option to remember() calls.
  */
-export function getCortex(): Cortex {
-  if (!cortexClient) {
+export async function initCortex(): Promise<Cortex> {
+  if (cortexClient) {
+    return cortexClient;
+  }
+
+  if (initPromise) {
+    return initPromise;
+  }
+
+  initPromise = (async () => {
     const convexUrl = process.env.CONVEX_URL;
     if (!convexUrl) {
       throw new Error(
@@ -65,9 +81,29 @@ export function getCortex(): Cortex {
       };
     }
 
-    cortexClient = new Cortex(config);
-  }
+    // Use Cortex.create() for async initialization with auto graph configuration
+    // This automatically:
+    // - Detects CORTEX_GRAPH_SYNC=true
+    // - Reads NEO4J_URI/MEMGRAPH_URI and credentials from env
+    // - Creates and connects the CypherGraphAdapter
+    cortexClient = await Cortex.create(config);
+    return cortexClient;
+  })();
+
+  return initPromise;
+}
 
+/**
+ * Get the Cortex SDK client (must call initCortex first)
+ *
+ * @throws Error if client hasn't been initialized
+ */
+export function getCortex(): Cortex {
+  if (!cortexClient) {
+    throw new Error(
+      "Cortex client not initialized. Call initCortex() first.",
+    );
+  }
   return cortexClient;
 }
 

package/templates/basic/src/index.ts

@@ -19,7 +19,7 @@
  */
 
 import * as readline from "readline";
-import { closeCortex } from "./cortex.js";
+import { closeCortex, initCortex, CONFIG } from "./cortex.js";
 import {
   chat,
   recallMemories,
@@ -189,6 +189,22 @@ async function main(): Promise<void> {
   // Print welcome
   printWelcome("cli");
 
+  // Initialize Cortex client (async for graph support)
+  // v0.29.0+: Uses Cortex.create() for automatic graph configuration
+  try {
+    await initCortex();
+    // Check if graph is actually configured (flag + URI)
+    const hasGraphUri = !!(process.env.NEO4J_URI || process.env.MEMGRAPH_URI);
+    if (CONFIG.enableGraphMemory && hasGraphUri) {
+      printSuccess("Graph memory connected (auto-sync active)");
+    } else if (CONFIG.enableGraphMemory && !hasGraphUri) {
+      printInfo("Graph sync enabled but no database URI configured (NEO4J_URI or MEMGRAPH_URI)");
+    }
+  } catch (error) {
+    printError("Failed to initialize Cortex", error instanceof Error ? error : undefined);
+    process.exit(1);
+  }
+
   // Initialize conversation
   const convId = getConversationId();
   printSuccess(`Conversation: ${convId}`);

package/templates/basic/src/server.ts

@@ -19,14 +19,14 @@ import { serve } from "@hono/node-server";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { logger } from "hono/logger";
-import { closeCortex, CONFIG } from "./cortex.js";
+import { closeCortex, initCortex, CONFIG } from "./cortex.js";
 import {
   chat,
   recallMemories,
   listFacts,
   generateConversationId,
 } from "./chat.js";
-import { printWelcome, printInfo, printError } from "./display.js";
+import { printWelcome, printInfo, printError, printSuccess } from "./display.js";
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Server Setup
@@ -237,6 +237,22 @@ async function main(): Promise<void> {
   // Print welcome
   printWelcome("server");
 
+  // Initialize Cortex client (async for graph support)
+  // v0.29.0+: Uses Cortex.create() for automatic graph configuration
+  try {
+    await initCortex();
+    // Check if graph is actually configured (flag + URI)
+    const hasGraphUri = !!(process.env.NEO4J_URI || process.env.MEMGRAPH_URI);
+    if (CONFIG.enableGraphMemory && hasGraphUri) {
+      printSuccess("Graph memory connected (auto-sync active)");
+    } else if (CONFIG.enableGraphMemory && !hasGraphUri) {
+      printInfo("Graph sync enabled but no database URI configured (NEO4J_URI or MEMGRAPH_URI)");
+    }
+  } catch (error) {
+    printError("Failed to initialize Cortex", error instanceof Error ? error : undefined);
+    process.exit(1);
+  }
+
   // Start server
   console.log(`🚀 Server starting on http://localhost:${PORT}`);
   console.log("");

package/templates/vercel-ai-quickstart/lib/agents/memory-agent.ts

@@ -97,13 +97,14 @@ export const memoryAgent = new ToolLoopAgent({
   // │ - Facts (extracted knowledge)                                  │
   // │ - Graph relationships (if configured)                          │
   // └─────────────────────────────────────────────────────────────────┘
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   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
-  }),
+  }) as any, // Type assertion needed due to AI SDK v6 type evolution
 
   // Default to 5 steps (sufficient for most chat interactions)
   stopWhen: stepCountIs(5),

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

@@ -2,8 +2,8 @@ const path = require("path");
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
-  transpilePackages: ["@cortexmemory/sdk", "@cortexmemory/vercel-ai-provider"],
-  serverExternalPackages: ["convex"],
+  transpilePackages: ["@cortexmemory/vercel-ai-provider"],
+  serverExternalPackages: ["convex", "neo4j-driver", "@cortexmemory/sdk"],
   // Disable image optimization to avoid sharp dependency (LGPL licensed)
   // This quickstart doesn't use image optimization features
   images: {
@@ -18,7 +18,7 @@ const nextConfig = {
   // 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) => {
+  webpack: (config, { isServer }) => {
     config.resolve.alias = {
       ...config.resolve.alias,
       "@anthropic-ai/sdk": path.resolve(
@@ -26,8 +26,17 @@ const nextConfig = {
         "node_modules/@anthropic-ai/sdk",
       ),
       openai: path.resolve(__dirname, "node_modules/openai"),
-      "neo4j-driver": path.resolve(__dirname, "node_modules/neo4j-driver"),
     };
+
+    // Mark neo4j-driver and its rxjs dependency as external for server builds
+    // neo4j-driver uses rxjs for reactive sessions which doesn't bundle well
+    if (isServer) {
+      config.externals = config.externals || [];
+      if (Array.isArray(config.externals)) {
+        config.externals.push("neo4j-driver", /^rxjs/, /^rxjs\//);
+      }
+    }
+
     return config;
   },
 };

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

@@ -19,17 +19,17 @@
     "convex:deploy": "convex deploy"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^3.0.4",
-    "@ai-sdk/react": "^3.0.11",
+    "@ai-sdk/openai": "^3.0.9",
+    "@ai-sdk/react": "^3.0.32",
     "@anthropic-ai/sdk": "^0.71.2",
     "@cortexmemory/sdk": "file:../../..",
     "@cortexmemory/vercel-ai-provider": "file:..",
-    "ai": "^6.0.11",
-    "convex": "^1.31.2",
-    "framer-motion": "^12.24.0",
+    "ai": "^6.0.30",
+    "convex": "^1.31.4",
+    "framer-motion": "^12.26.1",
     "neo4j-driver": "^6.0.1",
     "next": "^16.1.1",
-    "openai": "^6.15.0",
+    "openai": "^6.16.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "zod": "^4.3.5"
@@ -37,8 +37,8 @@
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.3",
-    "@types/react": "^19.2.7",
+    "@types/node": "^25.0.7",
+    "@types/react": "^19.2.8",
     "@types/react-dom": "^19.2.3",
     "autoprefixer": "^10.4.23",
     "jest": "^30.2.0",