@cortexmemory/cli 0.27.4 → 0.28.1

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/.env.local.example

@@ -0,0 +1,23 @@
+# Cortex Memory SDK - Configuration
+# Copy this file to .env.local and fill in your values
+
+# Required: Your Convex deployment URL
+CONVEX_URL=https://your-deployment.convex.cloud
+
+# Optional: OpenAI API key for LLM responses and embeddings
+# If not set, the agent runs in "echo mode" (returns user message as response)
+OPENAI_API_KEY=sk-...
+
+# Memory configuration
+MEMORY_SPACE_ID=basic-demo
+USER_ID=demo-user
+USER_NAME=Demo User
+AGENT_ID=basic-assistant
+AGENT_NAME=Cortex CLI Assistant
+
+# Feature flags
+CORTEX_FACT_EXTRACTION=true
+CORTEX_GRAPH_SYNC=false
+
+# Debug mode (enables verbose logging)
+DEBUG=false

package/templates/basic/README.md

@@ -1,33 +1,129 @@
 # {{PROJECT_NAME}}
 
-AI agent with persistent memory powered by [Cortex Memory SDK](https://github.com/SaintNick1214/Project-Cortex).
+AI agent with persistent memory powered by [Cortex Memory SDK](https://cortexmemory.dev).
 
-## Getting Started
+This demo shows how Cortex orchestrates data through memory layers - the same logic used in the Vercel AI quickstart, but without any UI dependencies.
 
-Your Convex backend functions are deployed and configured!
+## Quick Start
 
-### For Local Development
-
-**Terminal 1** - Start Convex:
+### 1. Start Convex Backend
 
 ```bash
 npm run dev
 ```
 
-Leave this running. It watches for changes and keeps Convex server active.
+Leave this running. It watches for changes and keeps the Convex server active.
 
-**Terminal 2** - Run your agent:
+### 2. Chat via CLI
 
 ```bash
 npm start
 ```
 
-### For Cloud Deployments
+This starts an interactive CLI where you can chat and see memory orchestration in real-time.
 
-Your Convex is already running in the cloud, so just:
+### 3. Or use the HTTP API
 
 ```bash
-npm start
+npm run server
+```
+
+Then send requests:
+
+```bash
+curl -X POST http://localhost:3001/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "My name is Alex and I work at Acme Corp"}'
+```
+
+## Features
+
+### Rich Console Output
+
+Watch data flow through all memory layers in real-time:
+
+```
+You: My name is Alex and I work at Acme Corp
+
+┌────────────────────────────────────────────────────────────────────┐
+│  MEMORY ORCHESTRATION                                              │
+├────────────────────────────────────────────────────────────────────┤
+│  📦 Memory Space   ✓ complete (2ms)                                │
+│     → ID: basic-demo                                               │
+│                                                                    │
+│  👤 User           ✓ complete (5ms)                                │
+│     → ID: demo-user                                                │
+│     → Name: Demo User                                              │
+│                                                                    │
+│  🤖 Agent          ✓ complete (3ms)                                │
+│     → ID: basic-assistant                                          │
+│     → Name: Cortex CLI Assistant                                   │
+│                                                                    │
+│  💬 Conversation   ✓ complete (8ms)                                │
+│     → ID: conv-abc123                                              │
+│     → Messages: 2                                                  │
+│                                                                    │
+│  🎯 Vector Store   ✓ complete (45ms)                               │
+│     → Embedded with 1536 dimensions                                │
+│     → Importance: 75                                               │
+│                                                                    │
+│  💡 Facts          ✓ complete [NEW] (120ms)                        │
+│     → Extracted 2 facts:                                           │
+│       • "User's name is Alex" (identity, 95%)                      │
+│       • "User works at Acme Corp" (employment, 90%)                │
+│                                                                    │
+│  🕸️ Graph          ○ skipped (not configured)                      │
+├────────────────────────────────────────────────────────────────────┤
+│  Total: 183ms                                                      │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `/recall <query>` | Search memories without storing |
+| `/facts` | List all stored facts |
+| `/history` | Show conversation history |
+| `/new` | Start a new conversation |
+| `/config` | Show current configuration |
+| `/clear` | Clear the screen |
+| `/exit` | Exit the demo |
+
+### HTTP API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/chat` | POST | Chat and store memory |
+| `/recall` | GET | Search memories (`?query=...`) |
+| `/facts` | GET | List stored facts |
+| `/history/:id` | GET | Get conversation history |
+| `/health` | GET | Health check |
+
+## Configuration
+
+All configuration is via environment variables in `.env.local`:
+
+```env
+# Required
+CONVEX_URL=https://your-project.convex.cloud
+
+# Optional: Enable AI responses (otherwise runs in echo mode)
+OPENAI_API_KEY=sk-...
+
+# Optional: Customize identifiers
+MEMORY_SPACE_ID=basic-demo
+USER_ID=demo-user
+USER_NAME=Demo User
+AGENT_ID=basic-assistant
+AGENT_NAME=Cortex CLI Assistant
+
+# Optional: Feature flags
+CORTEX_FACT_EXTRACTION=true    # Enable automatic fact extraction
+CORTEX_GRAPH_SYNC=false        # Enable graph database sync
+
+# Optional: Debug mode
+DEBUG=true
 ```
 
 ## Project Structure
@@ -35,65 +131,94 @@ npm start
 ```
 .
 ├── src/
-│   └── index.ts          # Your AI agent code
-├── convex/               # Cortex backend functions (deployed to Convex)
-│   ├── schema.ts         # Database schema
-│   ├── conversations.ts  # Conversation management
-│   ├── memories.ts       # Memory storage and search
-│   └── ...              # Other Cortex functions
-├── .env.local           # Environment configuration (not committed)
+│   ├── index.ts      # CLI entry point
+│   ├── server.ts     # HTTP server entry point
+│   ├── chat.ts       # Core chat/memory logic
+│   ├── cortex.ts     # SDK client configuration
+│   ├── llm.ts        # Optional OpenAI integration
+│   └── display.ts    # Rich console output
+├── convex/           # Cortex backend functions
+├── .env.local        # Environment configuration
+├── dev-runner.mjs    # Development helper
 └── package.json
 ```
 
-## What You Get
+## How It Works
 
-- **Persistent Memory** - Your agent remembers conversations indefinitely
-- **Semantic Search** - Find relevant memories using natural language
-- **ACID Storage** - Reliable, consistent data storage
-- **Vector Search** - Optional embedding-based search (cloud only)
-- **User Profiles** - Manage user data and preferences
-- **Multi-Agent Support** - Coordinate between multiple agents
+1. **Recall** - Before responding, Cortex searches for relevant memories and facts
+2. **Generate** - Uses OpenAI (if configured) or echo mode to generate a response
+3. **Remember** - Stores the exchange through all memory layers:
+   - **Memory Space** - Isolated namespace
+   - **User** - User profile tracking
+   - **Agent** - Agent registration
+   - **Conversation** - Message storage
+   - **Vector** - Semantic embeddings for search
+   - **Facts** - Extracted structured information
+   - **Graph** - Entity relationships (optional)
 
-## Next Steps
+## Testing
+
+The project includes comprehensive tests:
+
+```bash
+# Run all unit tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run integration tests (mocked SDK)
+npm run test:integration
+
+# Run e2e tests (requires real backend)
+npm run test:e2e
 
-### Add Vector Embeddings
-
-For semantic search, add an embedding provider:
-
-```typescript
-import OpenAI from "openai";
-
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-
-await cortex.memory.remember({
-  memorySpaceId: "my-agent",
-  conversationId: "conv-1",
-  userMessage: "message",
-  agentResponse: "response",
-  userId: "user-1",
-  userName: "User",
-  generateEmbedding: async (text) => {
-    const result = await openai.embeddings.create({
-      model: "text-embedding-3-small",
-      input: text,
-    });
-    return result.data[0].embedding;
-  },
-});
+# Run all tests
+npm run test:all
 ```
 
+### E2E Test Requirements
+
+E2E tests require additional setup:
+
+1. **Memory flow tests** - Need `CONVEX_URL` pointing to a deployed Cortex backend
+2. **Fact extraction tests** - Also need `OPENAI_API_KEY` for LLM-powered extraction
+3. **Server tests** - Need the HTTP server running (`npm run server`)
+
+```bash
+# Run memory flow e2e tests
+CONVEX_URL=https://your-project.convex.cloud npm run test:e2e
+
+# Run fact extraction tests (requires OpenAI)
+CONVEX_URL=https://your-project.convex.cloud \
+OPENAI_API_KEY=sk-... \
+npm run test:e2e
+
+# Run server e2e tests
+# Terminal 1: Start server
+CONVEX_URL=https://your-project.convex.cloud npm run server
+# Terminal 2: Run tests
+npm run test:e2e
+```
+
+## Next Steps
+
+### Enable AI Responses
+
+Set `OPENAI_API_KEY` in `.env.local` for real AI-powered responses instead of echo mode.
+
 ### Enable Graph Database
 
-For advanced relationship queries, set up a graph database:
+For entity relationship queries:
 
 1. Start Neo4j: `docker-compose -f docker-compose.graph.yml up -d`
-2. See `src/graph-init.example.ts` for setup code
+2. Set `CORTEX_GRAPH_SYNC=true` in `.env.local`
 
-### Learn More
+### Explore the API
 
-- [Documentation](https://github.com/SaintNick1214/Project-Cortex/tree/main/Documentation)
-- [API Reference](https://github.com/SaintNick1214/Project-Cortex/tree/main/Documentation/03-api-reference)
-- [Examples](https://github.com/SaintNick1214/Project-Cortex/tree/main/Examples)
+- [Cortex Documentation](https://cortexmemory.dev/docs)
+- [API Reference](https://cortexmemory.dev/docs/api-reference)
+- [GitHub Repository](https://github.com/SaintNick1214/Project-Cortex)
 
 ## Support