Projects

A project is the top-level container in Contox. Every piece of knowledge -- contexts, memory items, sessions, and the assembled brain document -- belongs to exactly one project. Projects are owned by a team (organization) and enforce plan-based quotas on resource usage.

Data Model

Visibility

Projects support two visibility modes:

• Public -- Any authenticated member of the team can see the project and its contents. This is the default.
• Private -- Only explicitly added members can access the project.

Visibility is set at creation time and can be changed later via the project settings.

Members and Roles

Each project can have members with one of four roles, listed from most to least privileged:

Members are assigned at the project level. A user's team-level role does not automatically grant project access when the project is set to private visibility.

Plan Quotas

The number of projects a team can create is governed by their subscription plan:

When a team reaches their project limit, new project creation is blocked until existing projects are archived or the plan is upgraded. Quota checks read from pre-aggregated usage rollups for O(1) performance.

AI Model Override

By default, the AI model used for enrichment is determined by the team's plan:

• Free / Personal -- mistral-small-latest (faster, lower cost)
• Team / Business / Enterprise -- mistral-medium-latest (higher quality)

All paid plans can override the default model on a per-project basis via Project Settings > AI Model. Two options are available:

• Small (mistral-small-latest) -- Fast and cost-effective
• Medium (mistral-medium-latest) -- Higher quality analysis

Setting aiTier to null (the default) uses the plan's default model. Free plan users see the model selector but must upgrade to change it.

// Example: override a project to use Medium model
await updateProject(projectId, { aiTier: 'medium' });

// Reset to plan default
await updateProject(projectId, { aiTier: null });

GitHub Repository Connection

Linking a GitHub repository enables deep enrichment -- an additional pipeline stage where AI reads your actual source code to produce richer, implementation-level memory items instead of just analyzing commit messages.

Authentication methods

Tokens are encrypted server-side with AES-256-GCM before storage. They are write-only -- the API never returns them in GET responses.

Deep Enrichment

When a linked repo exists and deep enrichment is enabled (the default), the pipeline adds a deep_enrich stage after the standard enrichment. It uses Devstral Small (Mistral's code-specialized model) to:

1. Fetch source files referenced by memory items (max 20 files, 500 KB total)
2. Extract structured facts -- routes, schemas, function signatures, auth flows, config
3. Compile enriched markdown back into each item's facts field

Deep enrichment can be toggled per-project in Project Settings > Repository. When disabled, items retain the standard enrichment output.

// Example: toggle deep enrichment via API
await updateProject(projectId, { deepEnrichEnabled: false });

// Disconnect GitHub entirely
await updateProject(projectId, { disconnectGithub: true });

Project Lifecycle

Projects follow a simple two-state lifecycle:

1. ACTIVE -- The project is in use. All operations (ingestion, enrichment, brain assembly) are available.
2. ARCHIVED -- The project is read-only. No new events can be ingested, but the brain and memory items remain accessible for reference.

Archiving a project does not delete any data. It can be restored to ACTIVE status at any time.

Managing Projects in the Dashboard

Projects are managed from the Projects page in the dashboard:

• Create -- Click New Project to create a project with a name, description, and visibility setting
• Settings -- Click the gear icon on any project card to open the settings modal with three tabs:
  • General -- Name, description, AI model override, visibility, archive/delete
  • Members -- Add/remove members with role-based access (admin, editor, writer, viewer)
  • Repository -- Link a GitHub repository and configure authentication (PAT)
• Switch projects -- Click any project card to switch context. All dashboard pages (Memory, Operations, etc.) operate on the currently selected project

Relationship to Other Concepts

• Contexts (V1) and Memory Items (V2) are scoped to a project.
• Sessions track AI coding activity within a project.
• The Brain is assembled per-project from that project's memory items.
• Schema Keys organize knowledge within a project's namespace.
• Enrichment runs against a project's raw events to produce memory items.