### Interactive Project Setup with Specific Name

Source: https://docs.cortexmemory.dev/getting-started/installation

Sets up a new Cortex project with a specified name using the npm create command. It then navigates into the project directory and starts the Convex development server and the agent. This method ensures all necessary Cortex SDK and Convex components are installed and configured.

```bash
# Create new project  
npm create cortex-memories@latest my-ai-agent  
cd my-ai-agent  
npm run dev  # Start Convex  
npm start    # Run your agent  

```

--------------------------------

### Manual Convex Backend Setup (npm, npx)

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/getting-started

Provides steps for manually setting up the Convex backend, including global installation, project initialization, copying the Cortex schema, and deployment.

```bash
npm install -g convex
npx convex dev
# Copy schema from node_modules/@cortexmemory/sdk/convex-dev/ to your project's convex/ folder
npx convex deploy
```

--------------------------------

### Create New Cortex Project using npm

Source: https://docs.cortexmemory.dev/getting-started/installation

Initiates the creation of a new Cortex Memory project using npm. This command launches an interactive wizard that sets up the project, configures Convex, installs dependencies, deploys backend functions, and generates example code. This is the fastest way to get a working agent.

```bash
npm create cortex-memories  

```

--------------------------------

### Manual Installation of Cortex SDK and Convex

Source: https://docs.cortexmemory.dev/getting-started/installation

Installs Cortex SDK and Convex packages manually via npm, copies necessary backend functions from the SDK's convex-dev folder, creates a convex.json configuration file, sets up the local Convex URL in .env.local, and starts the Convex development server. This method provides full control over the installation process.

```bash
# 1. Install packages  
npm install @cortexmemory/sdk convex  
  
# 2. Copy backend functions  
# The SDK package includes convex-dev/ folder  
# Copy it to your project:  
cp -r node_modules/@cortexmemory/sdk/convex-dev ./convex  
  
# 3. Create convex.json  
echo '{"functions": "convex/"}' > convex.json  
  
# 4. Configure environment  
# Create .env.local:  
echo 'CONVEX_URL=http://127.0.0.1:3210' > .env.local  
  
# 5. Deploy Convex  
npx convex dev  

```

--------------------------------

### Start Convex Development Server and Agent

Source: https://docs.cortexmemory.dev/getting-started/installation

Starts the local Convex development server, which hosts backend functions, and then runs the agent in a separate terminal. Successful execution indicates that the Convex backend is ready and the agent can connect to it to perform its tasks, such as creating a memory.

```bash
# Start Convex (local mode)  
npm run dev  
# Should show: "Convex functions ready!"  
  
# In another terminal, run your agent  
npm start  
# Should connect and create a memory  

```

--------------------------------

### Install Cortex Memory Dependencies (npm)

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/getting-started

Installs the necessary packages for Cortex Memory, Vercel AI SDK, and an AI provider like OpenAI. Ensure you have Node.js 18+ and Next.js 14+.

```bash
npm install @cortexmemory/vercel-ai-provider @cortexmemory/sdk ai convex
npm install @ai-sdk/openai  # or @ai-sdk/anthropic, @ai-sdk/google, etc.
```

--------------------------------

### Deploying or Running Cortex Memory Backend

Source: https://docs.cortexmemory.dev/getting-started/installation

Commands to start the local development server or deploy the backend to the cloud. Ensures that Convex functions are accessible. Requires Node.js and npm.

```shell
# For local mode
npm run dev

# For cloud mode
npx convex deploy
```

--------------------------------

### Start Neo4j Service with Docker Compose

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

This command starts only the Neo4j service using the specified Docker Compose file. It's the recommended approach for users who primarily need Neo4j.

```bash
docker-compose -f docker-compose.graph.yml up -d neo4j  

```

--------------------------------

### Docker Compose: Fresh Start (Remove and Recreate)

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Commands to perform a complete fresh start of the Docker Compose environment. This involves stopping and removing existing containers along with their data, then starting them anew.

```bash
# Stop containers and remove all data
docker-compose -f docker-compose.graph.yml down -v

# Start fresh
docker-compose -f docker-compose.graph.yml up -d
```

--------------------------------

### Set Up Convex Backend with create-cortex-memories (npx)

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/getting-started

Automates the setup of your Convex backend with Cortex Memory. This is the recommended approach for a quick and easy integration.

```bash
npx create-cortex-memories
```

--------------------------------

### Start Memgraph Service with Docker Compose

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

This command starts only the Memgraph service using the specified Docker Compose file. Use this if Memgraph's performance characteristics are required.

```bash
docker-compose -f docker-compose.graph.yml up -d memgraph  

```

--------------------------------

### Create Cortex Memory Project with npm

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

Initializes a new Cortex Memory project using the npm create command. It guides the user through a setup wizard to configure project name, Convex backend, and graph database options.

```bash
npm create cortex-memories
```

--------------------------------

### Start Local Convex Development Server

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

Navigates into the newly created project directory and starts the local Convex development server. This command is essential for running the AI agent and requires a running terminal.

```bash
cd my-first-agent
npm run dev
```

--------------------------------

### Start Both Neo4j and Memgraph with Docker Compose

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

This command starts both Neo4j and Memgraph services simultaneously using the specified Docker Compose file. It requires a system with at least 16GB of RAM and is intended for SDK contributors or testers performing cross-database validation.

```bash
docker-compose -f docker-compose.graph.yml up -d  

```

--------------------------------

### Install Neo4j Driver

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

This command installs the official Neo4j JavaScript driver, which is necessary for integrating your application with a Neo4j database.

```bash
npm install neo4j-driver  

```

--------------------------------

### Start Development Server (npm)

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/getting-started

Starts the Next.js development server to run your application locally. This allows you to test the chat functionality and memory persistence.

```bash
npm run dev
```

--------------------------------

### Start/Stop Graph Database Services

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Provides bash commands to start or stop individual Neo4j or Memgraph services using Docker Compose. This allows for managing the running state of the graph databases.

```bash
# Start Neo4j  
docker-compose -f docker-compose.graph.yml up -d neo4j  
  
# OR start Memgraph  
docker-compose -f docker-compose.graph.yml up -d memgraph  
  
# Stop (specify which one)  
docker-compose -f docker-compose.graph.yml stop neo4j  
docker-compose -f docker-compose.graph.yml stop memgraph  
```

--------------------------------

### Ensuring Convex Server is Running

Source: https://docs.cortexmemory.dev/getting-started/installation

A command to start the local development server for Convex. This is crucial for preventing WebSocket connection issues like code 1006.

```shell
# Make sure Convex is running in another terminal
npm run dev
```

--------------------------------

### Run Memgraph Docker Container

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-selection

Starts a Memgraph Docker container for local development or testing. This is a quick and easy way to get Memgraph up and running.

```bash
docker run -p 7687:7687 memgraph/memgraph:latest
```

--------------------------------

### Start Both Neo4j and Memgraph Containers

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Starts both Neo4j and Memgraph graph database containers simultaneously using Docker Compose. This is intended for SDK testing across databases. Assumes 'docker-compose.graph.yml' is in the current directory and runs containers in detached mode.

```bash
# Start both Neo4j and Memgraph  
docker-compose -f docker-compose.graph.yml up -d  
  
# Verify both are running  
docker ps  
```

--------------------------------

### Run Neo4j Community Edition Docker Container

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-selection

Starts a Neo4j Community Edition Docker container for production deployment. This setup is stable and proven for production environments.

```bash
docker run -p 7687:7687 neo4j:5-community
```

--------------------------------

### TypeScript: Test Neo4j and Memgraph Connections

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

An asynchronous TypeScript example using the 'neo4j-driver' to test connections to both Neo4j and Memgraph databases. It demonstrates establishing a connection, running a simple query, and closing the connection.

```typescript
import neo4j from "neo4j-driver";

// Test Neo4j connection
async function testNeo4j() {
  const driver = neo4j.driver(
    "bolt://localhost:7687",
    neo4j.auth.basic("neo4j", "cortex-dev-password")
  );

  const session = driver.session();

  try {
    const result = await session.run('RETURN "Neo4j connected!" as message');
    console.log(result.records[0].get("message"));
  } finally {
    await session.close();
    await driver.close();
  }
}

// Test Memgraph connection (same driver!)
async function testMemgraph() {
  const driver = neo4j.driver(
    "bolt://localhost:7688",
    neo4j.auth.basic("memgraph", "cortex-dev-password")
  );

  const session = driver.session();

  try {
    const result = await session.run('RETURN "Memgraph connected!" as message');
    console.log(result.records[0].get("message"));
  } finally {
    await session.close();
    await driver.close();
  }
}

await testNeo4j();
await testMemgraph();
```

--------------------------------

### Convex Setup and Cortex Memory Installation

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/migration-from-mem0

Commands to set up a new Convex project and install Cortex Memory. These are essential initial steps for the migration.

```bash
npx convex dev
npx create-cortex-memories
```

--------------------------------

### Example: Full Cortex Configuration with Graph

Source: https://docs.cortexmemory.dev/getting-started/configuration

Demonstrates a comprehensive configuration of Cortex, including integration with a graph database. This example initializes both the graph adapter and Cortex, setting options like `orphanCleanup`. It assumes necessary environment variables are set for Convex and the graph database.

```javascript
import { Cortex } from "@cortexmemory/sdk";
import {
  CypherGraphAdapter,
  initializeGraphSchema,
} from "@cortexmemory/sdk/graph";

// Setup graph (optional)
const graphAdapter = new CypherGraphAdapter();
await graphAdapter.connect({
  uri: process.env.NEO4J_URI!,
  username: process.env.NEO4J_USERNAME!,
  password: process.env.NEO4J_PASSWORD!,
});
await initializeGraphSchema(graphAdapter);

// Initialize Cortex with all options
const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!,
  graph: {
    adapter: graphAdapter,
    orphanCleanup: true,
  },
});
```

--------------------------------

### Install OpenAI for Vector Embeddings

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

Installs the OpenAI Node.js client library, which is necessary for generating vector embeddings for semantic search capabilities within the Cortex Memory SDK.

```bash
npm install openai
```

--------------------------------

### Initialize Cortex SDK (Minimal Setup)

Source: https://docs.cortexmemory.dev/getting-started/configuration

This snippet shows the most basic way to initialize the Cortex SDK. It requires the Convex URL, typically provided via an environment variable. This setup is sufficient for storing and searching memories.

```javascript
import { Cortex } from "@cortexmemory/sdk";

const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!,
});
```

--------------------------------

### Local Neo4j Installation Commands

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-integration

Provides commands for installing Neo4j locally on macOS and Linux systems. It includes instructions for using Homebrew on macOS and `apt-get` on Linux, followed by the command to start the Neo4j service.

```bash
# macOS
brew install neo4j
  
# Linux
wget -O - https://debian.neo4j.com/neotechnology.gpg.key | sudo apt-key add -
sudo apt-get install neo4j
  
# Start
neo4j start
```

--------------------------------

### Multi-Tenant Setup (TypeScript)

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/getting-started

Demonstrates how to implement a multi-tenant architecture by assigning a unique memory space per team or user. This is achieved by dynamically setting the `memorySpaceId` based on the current team or user context.

```typescript
// Different memory space per team
const cortexMemory = createCortexMemory({
  convexUrl: process.env.CONVEX_URL!,
  memorySpaceId: `team-${currentTeam.id}`,
  userId: currentUser.id,
});
```

--------------------------------

### Verify Cortex SDK and Convex Package Installation

Source: https://docs.cortexmemory.dev/getting-started/installation

Checks if the Cortex SDK and Convex packages are correctly installed within the project's node_modules directory. It also lists the files present in the 'convex' directory to confirm the backend functions have been set up.

```bash
# Verify SDK is installed  
npm list @cortexmemory/sdk  
# Should show: @cortexmemory/sdk@0.8.1  
  
# Verify Convex is installed  
npm list convex  
# Should show: convex@^1.28.0  
  
# Check backend files exist  
ls convex/  
# Should list: schema.ts, conversations.ts, memories.ts, etc.  

```

--------------------------------

### Install and Run Cortex MCP Server

Source: https://docs.cortexmemory.dev/core-features/mcp-server

Instructions for installing the Cortex MCP Server globally using npm or running it directly with npx. It also shows how to start the server with a Convex URL, which is necessary for data storage. The server typically starts on http://localhost:3000.

```bash
# Install globally  
npm install -g @cortex-platform/mcp-server  

# Or use npx (no install)  
npx @cortex-platform/mcp-server  
```

```bash
# With your Convex URL  
cortex-mcp-server --convex-url=https://your-project.convex.cloud  

# Server starts on http://localhost:3000  
```

--------------------------------

### Troubleshooting: Install Dependencies

Source: https://docs.cortexmemory.dev/getting-started/installation

Installs all project dependencies using npm install. This command is a common fix for the 'Cannot find module @cortexmemory/sdk' error, which typically occurs when the project's dependencies have not been installed after cloning or setting up a project.

```bash
cd your-project  
npm install  

```

--------------------------------

### Upgrading Cortex Memory SDK and Convex

Source: https://docs.cortexmemory.dev/getting-started/installation

Commands to update the Cortex Memory SDK and the Convex framework to their latest versions. After updating, the backend needs to be redeployed.

```shell
# Update SDK
npm install @cortexmemory/sdk@latest

# Update Convex
npm install convex@latest

# Redeploy backend
npx convex deploy
```

--------------------------------

### Project Structure Overview (Text)

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

This text output illustrates a typical project structure for a Cortex Memory agent, including directories for source code (src/), backend functions (convex/), environment configuration (.env.local), package management (package.json), and TypeScript configuration (tsconfig.json).

```text
my-first-agent/  
├── src/  
│   └── index.ts              # Your agent code  
├── convex/                   # Backend functions (Cortex)  
│   ├── schema.ts             # Database schema  
│   ├── conversations.ts      # Conversation management  
│   ├── memories.ts           # Memory storage/search  
│   ├── immutable.ts          # Versioned storage  
│   ├── mutable.ts            # Live data  
│   ├── facts.ts              # Fact extraction  
│   ├── contexts.ts           # Context chains  
│   ├── memorySpaces.ts       # Memory space registry  
│   ├── users.ts              # User profiles  
│   ├── agents.ts             # Agent registry  
│   └── graphSync.ts          # Graph integration  
├── .env.local                # Environment config (not committed)  
├── package.json              # Dependencies  
├── tsconfig.json             # TypeScript config  
└── README.md                 # Project-specific docs  
```

--------------------------------

### Deploy to Convex Cloud (Shell)

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

This shell command deploys your project to the Convex cloud platform. Ensure your environment variables are correctly set in .env.local. This command handles the migration of your data to the cloud deployment.

```bash
npx convex deploy  
```

--------------------------------

### Start Memgraph Container with Docker Compose

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Starts the Memgraph graph database container using Docker Compose. Assumes the 'docker-compose.graph.yml' file is present in the current directory. This command runs the container in detached mode.

```bash
# Start Memgraph  
docker-compose -f docker-compose.graph.yml up -d memgraph  
  
# Verify it's running  
docker ps  
```

--------------------------------

### Start Neo4j Container with Docker Compose

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Starts the Neo4j graph database container using Docker Compose. Assumes the 'docker-compose.graph.yml' file is present in the current directory. This command runs the container in detached mode.

```bash
# Start Neo4j  
docker-compose -f docker-compose.graph.yml up -d neo4j  
  
# Verify it's running  
docker ps  
```

--------------------------------

### Common Project Commands (Shell)

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

This snippet lists common npm commands for managing a Cortex Memory project. It includes starting Convex in watch mode, running the agent, building TypeScript code, and deploying to Convex cloud. These commands are essential for development and deployment workflows.

```bash
# Start Convex in watch mode  
npm run dev  

# Run your agent  
npm start  

# Build TypeScript  
npm run build  

# Deploy to cloud Convex  
npm run build:convex  
```

--------------------------------

### Run First AI Agent with Cortex SDK

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

Executes the main script for the AI agent in a new terminal after the Convex server is running. This demonstrates storing and retrieving a memory using the Cortex SDK.

```bash
cd my-first-agent
npm start
```

--------------------------------

### Create Conversations Early in Session (Best Practice)

Source: https://docs.cortexmemory.dev/api-reference/conversation-operations

An example of the best practice to create or get a conversation at the start of a session and then use its ID throughout the session for adding messages.

```javascript
// ✅ Create at start of session  
const conversation = await cortex.conversations.getOrCreate({  
  type: 'user-agent',  
  participants: { userId, memorySpaceId, participantId },  
});  
  
// Then use throughout session  
await cortex.conversations.addMessage(conversation.conversationId, { ... });  

```

--------------------------------

### Performance Tuning: Neo4j Query Profiling

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Example of using the 'PROFILE' command in Cypher to analyze the execution plan of a query. This helps in identifying performance bottlenecks and optimizing query logic.

```cypher
PROFILE
MATCH (c:Context {contextId: 'ctx-123'})
RETURN c;
```

--------------------------------

### Install Neo4j Driver and Start Graph Database

Source: https://docs.cortexmemory.dev/api-reference/graph-operations

Installs the Neo4j driver using npm and starts the Neo4j graph database using Docker Compose. Ensure Docker is installed and the `docker-compose.graph.yml` file is present.

```bash
# Install Neo4j driver  
npm install neo4j-driver  
  
# Start graph database (Docker)  
docker-compose -f docker-compose.graph.yml up -d neo4j  

```

--------------------------------

### Configure Cloud Deployment Environment Variables (Shell)

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

This shell snippet shows how to update your local environment file (.env.local) with Convex cloud deployment credentials. It requires your Convex deployment URL and a deploy key. This configuration is essential for migrating your project to the cloud and enabling features like vector search and scaling.

```bash
# Update .env.local with your cloud URL  
CONVEX_URL=https://your-deployment.convex.cloud  
CONVEX_DEPLOY_KEY=your-deploy-key-here  
```

--------------------------------

### Docker Compose: Service Management

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Commands to manage Docker Compose services for the graph database, including starting, stopping, restarting, and removing containers. Options are available to keep or delete data upon removal.

```bash
docker-compose -f docker-compose.graph.yml restart neo4j
docker-compose -f docker-compose.graph.yml restart memgraph

docker-compose -f docker-compose.graph.yml down

docker-compose -f docker-compose.graph.yml down -v
```

```bash
# Start both
docker-compose -f docker-compose.graph.yml up -d

# Stop both
docker-compose -f docker-compose.graph.yml stop

# Restart both
docker-compose -f docker-compose.graph.yml restart

# Remove both (keeps data)
docker-compose -f docker-compose.graph.yml down

# Remove both AND data
docker-compose -f docker-compose.graph.yml down -v
```

--------------------------------

### Troubleshooting: Neo4j Memory Settings

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

Example configuration snippet for adjusting Neo4j's memory settings within the Docker Compose file to mitigate out-of-memory errors. It shows how to reduce heap and page cache sizes.

```yaml
# Neo4j
- NEO4J_dbms_memory_heap_max__size=1G # was 2G
- NEO4J_dbms_memory_pagecache_size=512M # was 1G
```

--------------------------------

### Cortex SDK: Store and Search Memories (TypeScript)

Source: https://docs.cortexmemory.dev/getting-started/five-minute-quickstart

Demonstrates core functionality of the Cortex SDK in TypeScript. It shows how to initialize the Cortex client, store a memory with user and agent messages, and search for relevant memories using natural language.

```typescript
import { Cortex } from "@cortexmemory/sdk";

// Initialize Cortex
const cortex = new Cortex({
  convexUrl: process.env.CONVEX_URL!, // From .env.local
});

// Store a memory
await cortex.memory.remember({
  memorySpaceId: "my-first-agent", // Isolation boundary
  conversationId: "conversation-1", // Conversation ID
  userMessage: "I prefer dark mode", // What user said
  agentResponse: "Got it!", // What agent said
  userId: "user-123", // User identifier
  userName: "User", // User name
});

// Search memories
const results = await cortex.memory.search(
  "my-first-agent",
  "what are the user preferences?",
);
```

--------------------------------

### Troubleshooting: Port Conflicts

Source: https://docs.cortexmemory.dev/advanced-topics/graph-database-setup

A bash command to check for network ports that might be in use, which can prevent Docker containers from starting. If ports are found to be in use, the solution suggests stopping conflicting services or reconfiguring port mappings in the Docker Compose file.

```bash
# Check if ports are already in use
netstat -an | findstr "7474 7687 7688 3001"

# If ports are in use, stop conflicting services or change ports in docker-compose.graph.yml
```

--------------------------------

### Deploy to Vercel (vercel CLI)

Source: https://docs.cortexmemory.dev/integrations/vercel-ai-sdk/getting-started

Deploys your Next.js application to Vercel. Ensure you configure the necessary environment variables (`CONVEX_URL`, `OPENAI_API_KEY`, `MEMORY_SPACE_ID`) in your Vercel project settings.

```bash
vercel
```