System Overview

Contox is a persistent AI project memory platform built on three layers: capture, enrichment, and retrieval.

graph TB
    subgraph Capture ["Capture Layer"]
        MCP["MCP Server<br/>(Claude Code)"]
        CLI["CLI<br/>(All AI tools)"]
        VSC["VS Code Extension<br/>(Auto-capture)"]
    end

    subgraph Ingest ["Ingestion"]
        API["POST /api/v2/ingest<br/>HMAC + Idempotence"]
        Events["Raw Events<br/>(Appwrite DB)"]
        Blobs["Evidence Blobs<br/>(Appwrite Storage)"]
    end

    subgraph Enrich ["Enrichment Pipeline"]
        Indexer["Evidence Indexer"]
        LLM["LLM Extraction<br/>(Mistral Small/Medium)"]
        Verify["Quote Verification"]
        Dedup["Deduplication"]
    end

    subgraph Store ["Knowledge Store"]
        Items["Memory Items<br/>(7 types)"]
        Links["Knowledge Graph<br/>(Links)"]
        Brain["Brain Assembly<br/>(Layered Markdown)"]
    end

    subgraph Retrieve ["Retrieval Layer"]
        BrainAPI["GET /api/v2/brain<br/>ETag Cached"]
        Search["Semantic Search<br/>Embeddings"]
        Pack["Context Packs<br/>Task-Focused"]
    end

    MCP --> API
    CLI --> API
    VSC --> API
    API --> Events
    API --> Blobs
    Events --> Indexer
    Blobs --> Indexer
    Indexer --> LLM
    LLM --> Verify
    Verify --> Dedup
    Dedup --> Items
    Items --> Links
    Items --> Brain
    Brain --> BrainAPI
    Items --> Search
    Search --> Pack

Technology Stack

Data Flow

1. Capture

Events are captured from three sources:

• MCP Server — Direct tool calls from Claude Code (contox_save_session, contox_scan)
• CLI — Manual commands (contox save, contox scan, contox collect)
• VS Code Extension — Automatic git commit capture with diffs

All events are sent to POST /api/v2/ingest with:

• HMAC signature for authentication
• Timestamp validation (anti-replay, ±5 minutes)
• Content hash for idempotence (deduplication)

2. Ingestion

The ingest endpoint:

1. Validates HMAC signature against the project's secret
2. Checks timestamp freshness
3. Verifies idempotence via event hash (SHA-256)
4. Finds or creates a session (4-hour window)
5. Stores the raw event in Appwrite
6. Uploads evidence blobs to Storage

3. Enrichment

Triggered manually from the dashboard ("Generate Memory"):

1. Evidence Indexer — Builds structured evidence from raw events
2. Pre-classification — Filters irrelevant evidence, assigns schema key hints
3. LLM Extraction — Mistral extracts structured memory items using V16 JSON schema
4. Quote Verification — Programmatic check that cited quotes exist in evidence
5. Deduplication — Merges similar items based on semantic similarity and dedupHints

4. Storage

Memory items are stored with:

• Type classification (Decision, Convention, BugFix, etc.)
• Confidence score (0.0–1.0)
• Schema key mapping (hierarchical: root/api/auth)
• Evidence references (links to raw blobs)
• Dedup hints (for future merge detection)

5. Retrieval

The brain document is assembled on-demand:

• Layered architecture — 4 layers with token budgets
• ETag caching — brainHash for 304 Not Modified responses
• Semantic search — Embeddings for relevant context retrieval
• Context packs — Task-focused subsets for token efficiency

Security Architecture

• HMAC signing — Per-project secrets for V2 ingest authentication
• API key hashing — Keys stored as SHA-256 hashes, raw key shown once
• RBAC — Role-based access (owner, admin, member) with permission matrix
• Rate limiting — 200 req/min global, per-route configurable
• CORS — Strict origin allowlist
• Security headers — HSTS, X-Frame-Options DENY, nosniff, strict referrer