@cortexmemory/cli 0.28.0 → 0.29.0

package/scripts/postinstall.js

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+
+/**
+ * Cortex CLI Postinstall Script
+ *
+ * Automatically installs shell completion for the cortex CLI.
+ * Supports zsh, bash, and fish shells.
+ *
+ * This script runs after `npm install -g @cortexmemory/cli`
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, copyFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const home = homedir();
+
+// Marker comments for identifying our additions
+const MARKER_START = '# >>> cortex completion >>>';
+const MARKER_END = '# <<< cortex completion <<<';
+
+/**
+ * Get the completion scripts directory (relative to this script)
+ */
+function getCompletionsDir() {
+  return join(__dirname, 'completions');
+}
+
+/**
+ * Get the target directory for completion scripts (~/.cortex/completions/)
+ */
+function getTargetDir() {
+  return join(home, '.cortex', 'completions');
+}
+
+/**
+ * Ensure directory exists
+ */
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Check if a file already contains our completion setup
+ */
+function hasCompletionSetup(filePath) {
+  if (!existsSync(filePath)) {
+    return false;
+  }
+  const content = readFileSync(filePath, 'utf-8');
+  return content.includes(MARKER_START);
+}
+
+/**
+ * Detect the user's shell
+ */
+function detectShell() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('bash')) return 'bash';
+  if (shell.includes('fish')) return 'fish';
+  return null;
+}
+
+/**
+ * Get the shell RC file path
+ */
+function getShellRcPath(shell) {
+  switch (shell) {
+    case 'zsh':
+      return join(home, '.zshrc');
+    case 'bash': {
+      // Check for .bashrc first, then .bash_profile
+      const bashrc = join(home, '.bashrc');
+      const bashProfile = join(home, '.bash_profile');
+      if (existsSync(bashrc)) return bashrc;
+      if (existsSync(bashProfile)) return bashProfile;
+      return bashrc; // Default to .bashrc
+    }
+    case 'fish':
+      return join(home, '.config', 'fish', 'config.fish');
+    default:
+      return null;
+  }
+}
+
+/**
+ * Get the source line for shell RC file
+ */
+function getSourceLine(shell, targetPath) {
+  switch (shell) {
+    case 'zsh':
+      return `[[ -f "${targetPath}" ]] && source "${targetPath}"`;
+    case 'bash':
+      return `[[ -f "${targetPath}" ]] && source "${targetPath}"`;
+    case 'fish':
+      return `test -f "${targetPath}"; and source "${targetPath}"`;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Install completion for a specific shell
+ */
+function installCompletion(shell) {
+  const completionsDir = getCompletionsDir();
+  const targetDir = getTargetDir();
+
+  // Source completion script
+  const sourceFile = join(completionsDir, `cortex.${shell}`);
+  if (!existsSync(sourceFile)) {
+    return false;
+  }
+
+  // Ensure target directory exists
+  ensureDir(targetDir);
+
+  // Copy completion script to target
+  const targetFile = join(targetDir, `cortex.${shell}`);
+  copyFileSync(sourceFile, targetFile);
+
+  // Get shell RC file
+  const rcPath = getShellRcPath(shell);
+  if (!rcPath) {
+    return false;
+  }
+
+  // Check if already installed
+  if (hasCompletionSetup(rcPath)) {
+    return true; // Already installed
+  }
+
+  // Ensure RC file's parent directory exists (for fish)
+  ensureDir(dirname(rcPath));
+
+  // Create RC file if it doesn't exist
+  if (!existsSync(rcPath)) {
+    writeFileSync(rcPath, '', 'utf-8');
+  }
+
+  // Add source line to RC file
+  const sourceLine = getSourceLine(shell, targetFile);
+  if (!sourceLine) {
+    return false;
+  }
+
+  const completionBlock = `
+${MARKER_START}
+${sourceLine}
+${MARKER_END}
+`;
+
+  appendFileSync(rcPath, completionBlock, 'utf-8');
+  return true;
+}
+
+/**
+ * Main installation function
+ */
+function main() {
+  // Skip if running in CI or non-interactive environment
+  if (process.env.CI || process.env.CORTEX_SKIP_COMPLETION) {
+    return;
+  }
+
+  // Detect shell
+  const shell = detectShell();
+  if (!shell) {
+    // Unknown shell, skip silently
+    return;
+  }
+
+  try {
+    // Install completion for detected shell
+    installCompletion(shell);
+
+    // Also try to install for other common shells if their RC files exist
+    const otherShells = ['zsh', 'bash', 'fish'].filter(s => s !== shell);
+    for (const otherShell of otherShells) {
+      const rcPath = getShellRcPath(otherShell);
+      if (rcPath && existsSync(rcPath)) {
+        installCompletion(otherShell);
+      }
+    }
+  } catch {
+    // Silently fail - completion is not critical
+    // User can manually run `cortex completion <shell>` if needed
+  }
+}
+
+main();

package/scripts/preuninstall.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+
+/**
+ * Cortex CLI Preuninstall Script
+ *
+ * Removes shell completion configuration when the CLI is uninstalled.
+ * Cleans up ~/.cortex/completions/ and removes source lines from shell RC files.
+ *
+ * This script runs before `npm uninstall -g @cortexmemory/cli`
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const home = homedir();
+
+// Marker comments for identifying our additions
+const MARKER_START = '# >>> cortex completion >>>';
+const MARKER_END = '# <<< cortex completion <<<';
+
+/**
+ * Get the target directory for completion scripts (~/.cortex/completions/)
+ */
+function getTargetDir() {
+  return join(home, '.cortex', 'completions');
+}
+
+/**
+ * Get shell RC file paths to clean up
+ */
+function getShellRcPaths() {
+  return [
+    join(home, '.zshrc'),
+    join(home, '.bashrc'),
+    join(home, '.bash_profile'),
+    join(home, '.config', 'fish', 'config.fish'),
+  ];
+}
+
+/**
+ * Remove completion block from a shell RC file
+ */
+function removeCompletionFromRc(rcPath) {
+  if (!existsSync(rcPath)) {
+    return;
+  }
+
+  const content = readFileSync(rcPath, 'utf-8');
+
+  // Check if our completion setup exists
+  if (!content.includes(MARKER_START)) {
+    return;
+  }
+
+  // Remove the completion block (including markers and content between them)
+  const regex = new RegExp(
+    `\\n?${escapeRegex(MARKER_START)}[\\s\\S]*?${escapeRegex(MARKER_END)}\\n?`,
+    'g'
+  );
+
+  const newContent = content.replace(regex, '\n');
+
+  // Write cleaned content back
+  writeFileSync(rcPath, newContent, 'utf-8');
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegex(string) {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Remove completion scripts directory
+ */
+function removeCompletionsDir() {
+  const targetDir = getTargetDir();
+  if (existsSync(targetDir)) {
+    rmSync(targetDir, { recursive: true, force: true });
+  }
+
+  // Also remove parent .cortex directory if empty
+  const cortexDir = join(home, '.cortex');
+  if (existsSync(cortexDir)) {
+    try {
+      const files = readdirSync(cortexDir);
+      if (files.length === 0) {
+        rmSync(cortexDir, { recursive: true, force: true });
+      }
+    } catch {
+      // Directory not empty or other error, leave it
+    }
+  }
+}
+
+/**
+ * Main uninstall function
+ */
+function main() {
+  // Skip if running in CI
+  if (process.env.CI || process.env.CORTEX_SKIP_COMPLETION) {
+    return;
+  }
+
+  try {
+    // Remove completion setup from all shell RC files
+    const rcPaths = getShellRcPaths();
+    for (const rcPath of rcPaths) {
+      removeCompletionFromRc(rcPath);
+    }
+
+    // Remove completion scripts directory
+    removeCompletionsDir();
+  } catch {
+    // Silently fail - cleanup is not critical
+  }
+}
+
+main();

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