Overview

Enrichment is the AI-powered process that transforms raw session events into structured, verified memory items. It is the core intelligence layer of Contox, responsible for extracting factual claims from developer activity and organizing them into a usable knowledge base.

AI model selection

The default AI model is determined by your subscription plan. All paid plans can override the model per-project in Project Settings > AI Model.

Higher-tier models produce more accurate memory items with better confidence scores, but consume more credits. Free plan users see the model options but must upgrade to Personal or higher to change them.

Evidence indexing

Before AI processing begins, the enrichment pipeline indexes all evidence from the session events:

1. Event scanning -- All events in the session are scanned for content
2. Diff extraction -- Code diffs are extracted (up to 3000 characters per commit)
3. Summary collection -- Session summaries and change descriptions are gathered
4. Evidence truncation -- Large evidence blocks are truncated to 2000 characters to stay within model context limits

This indexed evidence is provided to the AI alongside the raw events.

Pre-classification

Events are pre-classified before AI processing to optimize extraction:

• Events are tagged with likely categories (architecture, implementation, bug, etc.)
• Related events are grouped together
• Metadata (file paths, timestamps, authors) is extracted and structured

This pre-processing helps the AI model focus on extraction rather than organization.

Event chunking

Events are processed in chunks of 10. Each chunk is sent to the AI model as a single request. Chunking provides several benefits:

• Keeps context window usage manageable
• Allows parallel processing of independent chunks
• Provides natural failure boundaries (a failed chunk does not block others)

V16 JSON schema

The AI model outputs memory items conforming to the V16 JSON schema. This schema defines:

{
  "items": [
    {
      "title": "string - Short descriptive title",
      "content": "string - Detailed markdown content",
      "type": "string - architecture|convention|implementation|decision|bug|todo",
      "confidence": "number - 0 to 1",
      "files": ["string - Related file paths"],
      "quote": "string - Source quote from evidence",
      "schemaKey": "string - Brain hierarchy path"
    }
  ]
}

Each field is validated against the schema. Malformed items are rejected.

Quote verification

Quote verification is a critical quality control step that rejects hallucinated memory items:

1. Every extracted item must include a quote field referencing specific evidence
2. The system programmatically verifies that the quote exists in the source evidence
3. Items with fabricated or inaccurate quotes are rejected
4. This prevents the AI from inventing facts not supported by actual session data

This mechanism significantly improves memory accuracy by ensuring every item is grounded in real evidence.

Context-aware processing

Enrichment is context-aware. The AI model receives the existing project brain as additional input:

• Avoids duplication -- The model knows what already exists and avoids extracting redundant items
• Maintains consistency -- New items are consistent with established conventions and architecture
• Enables updates -- The model can identify when new evidence updates or supersedes existing items
• Preserves structure -- Items are assigned schema keys that fit the existing brain hierarchy

Pipeline stages

After AI extraction, items pass through additional stages:

Embedding

Each extracted item is converted into a vector embedding for semantic search. These embeddings power context packs and the relevant-scope brain assembly.

Deduplication

New items are compared against existing items using both semantic similarity (embeddings) and structural matching (schema keys, titles). Duplicates are merged, with the higher-confidence version taking precedence.

Drift check

Existing brain items are evaluated against new evidence. If a new session contradicts an existing item (e.g., a technology was replaced, a convention changed), the existing item is flagged for review or automatically deprecated.

Monitoring enrichment in the Dashboard

Track enrichment progress in real time from the Memory page:

1. Switch to the Sessions tab to see all sessions for the current project
2. Find the session being enriched — its status updates live (active, enriching, completed, failed)
3. Click the session to open the detail view:
   • Pipeline Timeline — A visual progress indicator showing the current stage (Enrich → Embed → Dedup → Drift Check) with duration for each completed stage
   • Events tab — Browse all raw events captured during the session (save, scan, git digest, etc.)
   • Jobs tab — Full job history with per-stage timing, item counts, and error details

4. Once enrichment completes, switch to the Brain tab to see the newly extracted memory items

Retrying failed enrichment

If a stage fails, click Retry on the failed job. The pipeline restarts from the failed stage, preserving progress from earlier stages. Common failure causes:

• Temporary LLM API errors or rate limiting
• Network timeouts (mitigated by automatic retry with direct Mistral fallback)
• Malformed evidence data

Configuring the AI model

To change the enrichment model for a project:

1. Open the Projects page
2. Click the gear icon on the project card
3. In the General tab, find the AI Model section
4. Select Small (fast, cost-effective) or Medium (higher quality)
5. Save changes — the next enrichment run will use the selected model

Deep Enrichment (GitHub)

When a project has a linked GitHub repository, the pipeline adds a deep enrichment stage between Enrich and Embed. Instead of working only from commit messages and session summaries, deep enrichment reads the actual source files to produce implementation-level memory.

How it works

1. The pipeline collects file paths from newly created memory items, prioritized by importance score
2. Source files are fetched from GitHub at the session's headCommitSha (max 20 files, 500 KB total)
3. Pass 1 (Extract) -- Devstral Small analyzes each file and extracts structured facts by category:
   • Routes: HTTP method, path, params, Zod validation schema, response shape, middleware
   • Models/Schemas: field names, types, constraints, relations, indexes
   • Functions: signatures with types, logic steps, error cases, async behavior
   • Auth: flow description, token format, permission checks
   • Config: env vars, external services, feature flags
4. Pass 2 (Compile) -- Facts are compiled into concise markdown (max 3,500 chars) and written to the item's facts field

Setup

1. Open Project Settings > Repository tab
2. Connect via GitHub OAuth (recommended) or paste a Personal Access Token with repo scope
3. Select the repository
4. Ensure the Deep Enrichment toggle is enabled (on by default)

Resource limits

Deep enrichment enforces strict limits to control costs and latency:

Auto-Enrichment

By default, enrichment is triggered automatically when the VS Code extension captures git commits. This is controlled by the Auto-Learn from commits toggle in Project Settings > General.

When enabled:

• Every commit captured by VS Code triggers the full enrichment pipeline
• Memory items are created and enriched without manual intervention
• Credits are consumed automatically

When disabled:

• Commits are still captured and stored as raw events
• You must manually click Generate Memory on a session to trigger enrichment
• No credits are consumed until you choose to enrich

Staleness Detection

After each enrichment run, Contox automatically checks whether new commits have made existing memory items outdated. This is a zero-cost check (no LLM calls) that works by comparing modified file paths:

1. Files modified in the current commit are collected
2. Existing memory items referencing those files are identified
3. Items with 2+ referenced files modified are flagged as review
4. A problem document is created linking the item to the commit

Flagged items appear in the Review tab where you can:

• Accept -- The item is still accurate despite the file changes
• Edit -- Update the item's content to reflect the changes
• Archive -- The item is outdated and should be removed from the brain

Next steps

• V2 Pipeline -- The full event-to-memory flow
• Hygiene Agent -- Post-enrichment cleanup
• V2 Sessions API -- Trigger enrichment programmatically