Quick Start

This guide walks you through setting up Contox from scratch. By the end, your AI coding assistant will have persistent memory of your project. Every step can be completed from the dashboard UI or the CLI -- choose whichever you prefer.

Prerequisites

• An AI coding tool such as Claude Code, Cursor, Windsurf, Copilot, Cline, or Aider
• A project you want to give your AI memory for
• Node.js 18+ if you plan to use the CLI or MCP server

Step 1: Sign up

Create your account at contox.dev. After signing up, you land on the onboarding wizard that walks you through creating your first organization, project, and connecting your tools.

Step 2: Create an API key

From the Dashboard

1. Open Settings > API Keys in the dashboard
2. Click the Create API Key button
3. Enter a descriptive name (e.g., "CLI - MacBook Pro" or "MCP Server - Work")
4. Click Create -- the full key appears in a dialog with a copy button
5. Copy it immediately -- it is only shown once

The API Keys tab shows all your keys with their name, a prefix for identification, and the last-used timestamp.

Step 3: Install a client

Choose at least one client to connect your AI tool to Contox:

Option A: CLI (recommended for most tools)

The CLI is the universal interface that works with any AI coding tool.

npm install -g contox-cli

Verify the installation:

contox --version

Then store your API key:

contox login -k <your-api-key>
contox whoami  # Verify the connection

Option B: MCP Server (for Claude Code)

The MCP server gives Claude Code direct access to Contox tools in its tool palette.

npm install -g @contox/mcp-server

Then add a .mcp.json in your project root:

{
  "mcpServers": {
    "contox": {
      "command": "contox-mcp",
      "env": {
        "CONTOX_API_KEY": "your-api-key",
        "CONTOX_TEAM_ID": "your-team-id"
      }
    }
  }
}

Option C: VS Code Extension

Install the Contox extension from the VS Code Marketplace (contox.contox-vscode). It captures git commits automatically and manages sessions without any manual effort.

Step 4: Create your project

From the Dashboard

1. Open the Projects page in the dashboard
2. Click the New Project button in the top-right corner
3. Enter a project name (e.g., "my-saas-app") and an optional description
4. Choose visibility: Public (all team members can access) or Private (only invited members)
5. Click Create

Your project is created instantly. You can see its Project ID and Team ID in the project settings (click the gear icon on the project card).

From the CLI

Create the project and initialize in one step:

cd /path/to/your/project
contox init -t <your-team-id> -n "My Project"

Or link to a project you already created in the dashboard:

contox init -t <your-team-id> -p <project-id>

This creates a .contox.json file in your project root.

Step 5: Scan your codebase

Give Contox an instant understanding of your project structure.

From the CLI

contox scan

The scanner analyzes your project and generates 15-20 structured sub-contexts covering routes, components, libraries, hooks, dependencies, and configuration.

From the Dashboard

After scanning, you can browse the results in the Memory page. The Brain tab shows the hierarchical tree of all scanned knowledge, organized by schema keys like root/routes, root/components, and root/dependencies.

Step 6: Start coding with memory

When you start a session with your AI coding assistant, it loads your project memory automatically:

• Claude Code (MCP) -- Calls contox_get_memory at session start (triggered by the CLAUDE.md protocol)
• Other tools -- Run contox memory and paste the output, or use contox export --format cursor to generate a .cursorrules file
• VS Code Extension -- Captures session events automatically in the background

Step 7: Save your first session

At the end of your coding session, save what was accomplished:

From the CLI

contox save "Built user authentication with JWT tokens"

From the MCP Server (Claude Code)

Claude Code uses the contox_save_session tool automatically at the end of a session. The CLAUDE.md protocol instructs it to save when explicitly asked.

Monitoring enrichment in the Dashboard

After saving, the data goes through the enrichment pipeline. You can watch the progress in real time:

1. Open the Memory page and switch to the Sessions tab
2. Find your session in the list -- it shows status, event count, and timestamps
3. Click the session to see its detail view with the Pipeline Timeline
4. The timeline shows the pipeline stages: Enrich → Deep Enrich (if a GitHub repo is linked) → Embed → Dedup → Drift Check

5. Once complete, the extracted memory items appear in the Brain tab

What happens next

From this point forward, every new AI session in this project will have access to:

• What you built and when
• Architectural decisions you made
• Coding conventions you established
• Bugs you encountered and how you fixed them
• Pending tasks and technical debt

The more you use Contox, the smarter your AI becomes about your specific project. You can review, approve, or edit all extracted knowledge from the Memory page in the dashboard.

Next steps