Your first project

This guide walks through every step of setting up a Contox project in detail, from creation through your first complete memory cycle. Each step shows both the dashboard and CLI approach.

Prerequisites

Before starting, make sure you have:

• A Contox account (sign up at contox.dev)
• An API key (created in Settings > API Keys)
• The CLI installed and authenticated (optional — you can do most steps from the dashboard):

npm install -g contox-cli
contox login -k <your-api-key>
contox whoami  # Verify connection

Creating a project

From the Dashboard

1. Open the Projects page in the dashboard
2. Click New Project — a modal appears with a form
3. Enter a name for your project (e.g., "my-saas-app"). This is displayed throughout the dashboard and in your brain document
4. Add an optional description to help your team identify the project
5. Choose visibility:
   • Public — All members of your organization can see and access this project
   • Private — Only explicitly added members can access it
6. Click Create

The project card appears immediately in the project list:

You can see the project name and description, a gear icon to open settings (where you find the Project ID and Team ID), a context count, and the status badge.

From the CLI

Create the project and initialize in one step:

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

This creates the project on the Contox platform and writes a .contox.json file in your project root.

The .contox.json file

After initialization, your project root contains a .contox.json file:

{
  "teamId": "your-team-id",
  "projectId": "generated-project-id",
  "projectName": "My Awesome Project"
}

This file tells the CLI and MCP server which project to use when running commands in this directory. The file is discovered automatically by walking up the directory tree (up to 20 levels), so it works from subdirectories too.

CLAUDE.md integration

When you run contox init, the CLI also updates or creates a CLAUDE.md file in your project root. This file contains a contox:start / contox:end section with memory protocol instructions that Claude Code reads automatically. Your own content outside these markers is preserved.

Configuring project settings

From the Dashboard

Open project settings by clicking the gear icon on the project card, or navigate to the project and click Settings. The settings modal has three tabs:

General tab

• Name and Description — Edit the project's display name and summary
• AI Model — Choose the enrichment model for this project:
  • Small (mistral-small-latest) — Fast and cost-effective
  • Medium (mistral-medium-latest) — Higher quality analysis
  • The default depends on your plan (Small for Free/Personal, Medium for Team+)
  • Free plan users see the options but must upgrade to change them
• Visibility — Switch between Public and Private
• Danger Zone — Archive or delete the project

Members tab

• View current members with their roles
• Add Member — Invite users by email with a role (admin or member)
• Remove members by clicking the remove button

Repository tab

Link a GitHub repository to enable deep enrichment -- AI reads your actual source code for richer memory items.

• GitHub OAuth (recommended) — One-click authentication, works with public and private repos
• Personal Access Token — Paste a PAT with repo scope for fine-grained control
• Deep Enrichment toggle — When enabled (default), the pipeline fetches source files and enriches items with routes, schemas, function signatures, and auth flows
• Change / Unlink / Disconnect — Manage the connection at any time

Scanning your codebase

The scan command gives Contox an instant understanding of your project structure.

From the CLI

contox scan

You will see output similar to:

  Contox Scanner

  Directory: /path/to/your/project
  Scanning...
  ✓ Found 247 files, 42 dirs
  ✓ 12 API endpoints, 18 pages
  ✓ 35 components, 8 libs, 6 hooks

Viewing scan results in the Dashboard

After scanning, browse the results in the Memory page:

1. Switch to the Brain tab to see the hierarchical tree
2. Expand schema keys like root/overview, root/routes, root/components to explore
3. Each item shows its title, confidence score, state (draft/approved/deprecated), and tier (Layer 0-3)
4. Click any item to view its full content, evidence, and related links

The scanner generates approximately 15-20 structured sub-contexts covering:

Dry run mode

If you want to see what the scanner will generate before pushing to Contox:

contox scan --dry-run

This generates the contexts locally and shows them in the terminal without sending anything to the server.

Saving scan output locally

To save the generated context to a local file:

contox scan -o context.md

Re-scanning

You can run contox scan any time your project structure changes significantly. The scanner uses content hashing to deduplicate, so re-scanning is safe and will only update sub-contexts that have actually changed.

Loading memory in your AI tool

How you load memory depends on which AI tool you use.

Claude Code (MCP Server)

If you have the MCP server configured, Claude Code automatically has access to the contox_get_memory tool. The memory protocol in your CLAUDE.md instructs Claude to call this tool at the start of every session.

The tool returns a structured markdown document containing all your project memory -- architecture, conventions, implementation journal, decisions, bugs, and pending tasks.

Any AI tool (CLI)

For any AI tool, you can load memory via the CLI:

# Print to stdout (paste into chat)
contox memory

# Save to a file
contox memory --file memory.md

# Output as JSON (for programmatic use)
contox memory --json

Focused context packs

If you are working on a specific task and want relevant context rather than the full brain, use the context pack command:

contox context "implement user authentication"

This uses semantic search to find the most relevant memory items for your task and assembles a token-budgeted context document.

Browsing memory in the Dashboard

You can also explore your project memory visually from the Memory page:

• Brain tab — Browse the full brain tree hierarchy, view item details, approve or deprecate items
• Search tab — Semantic search across all memory items with confidence-ranked results
• Sessions tab — View session history, trigger enrichment, monitor pipeline progress
• Hygiene tab — Run the memory cleanup agent to detect duplicates, outdated items, and quality issues

Saving your first session

At the end of a coding session, save what was accomplished.

From the CLI

The most common way to save is a simple summary:

contox save "Built user registration with email verification"

This creates a session entry in the implementation category with your summary.

From Claude Code (MCP Server)

Claude Code uses the contox_save_session tool. The CLAUDE.md protocol instructs it to save when you explicitly ask (e.g., "save session" or "contox save").

Structured save (CLI)

For more detailed session records, you can provide structured JSON:

contox save --json <<'EOF'
{
  "summary": "Built user registration and fixed login bug",
  "changes": [
    {
      "category": "implementation",
      "title": "User registration flow",
      "content": "Implemented signup with email verification using Resend"
    },
    {
      "category": "bugs",
      "title": "Fixed login redirect loop",
      "content": "Login was redirecting back to itself when session cookie expired"
    },
    {
      "category": "conventions",
      "title": "Auth error handling pattern",
      "content": "All auth errors should use the AuthError class and return 401 status"
    }
  ]
}
EOF

Available categories

Session changes are organized into six categories:

Monitoring enrichment in the Dashboard

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

1. Switch to the Sessions tab
2. Find your session in the list — it shows status, event count, and timestamps
3. Click the session to open its detail view
4. The detail view shows:
   • Events tab — All raw events captured during the session (save, scan, git digest, etc.)
   • Jobs tab — Enrichment job history with status and duration
   • Pipeline Timeline — Visual progress through the pipeline stages:

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

The memory cycle

With your project set up, you now have a continuous memory cycle:

Each cycle makes the AI more knowledgeable about your specific project. Over time, it understands your architecture, follows your conventions, and remembers past decisions and bugs.

Next steps