Brain Assembly

The brain is the central output of Contox -- a structured markdown document assembled from a project's memory items. It is what AI coding assistants (Claude, Cursor, etc.) consume to understand your project's context. The brain is assembled on-demand, not stored as a static document, ensuring it always reflects the latest state of your project's knowledge.

How It Works

When the brain is requested (via GET /api/v2/brain or the MCP contox_get_memory tool), the system:

1. Fetches all active memory items for the project
2. Classifies each item into a layer based on recency, importance, and type
3. Consolidates items sharing dedup hints to avoid redundancy
4. Assembles a layered markdown document within a strict token budget
5. Computes an ETag hash for caching

flowchart LR
    A[Memory Items DB] --> B[Fetch Active Items]
    B --> C[Classify into Layers]
    C --> D[Consolidate by DedupHint]
    D --> E[Assemble Markdown]
    E --> F[Token Budget Enforcement]
    F --> G[Compute ETag Hash]
    G --> H[Return Brain Document]

The Four Layers

The brain uses a layered architecture to prioritize what knowledge gets included within the token budget:

graph TB
    subgraph Brain Document
        L0["Layer 0: Project Brief<br/>~500 tokens"]
        L1["Layer 1: Active Knowledge<br/>~1,500 tokens"]
        L2["Layer 2: Reference Knowledge<br/>~2,000 tokens"]
    end
    L3["Layer 3: Archive<br/>(excluded from brain)"]

    L0 --- L1
    L1 --- L2
    L2 -.->|"available via search"| L3

    style L0 fill:#FF5C00,color:#fff
    style L1 fill:#cc4a00,color:#fff
    style L2 fill:#993800,color:#fff
    style L3 fill:#333,color:#aaa,stroke-dasharray: 5 5

Layer 0: Project Brief (~500 tokens)

A synthesized overview of the project, generated without any LLM call. It is built by extracting and compressing information from existing memory items:

• Stack -- Top architecture/stack items summarized into a single line
• Key Decisions -- The 3 most important decisions by importance score
• Conventions -- Up to 5 top conventions as one-liners
• Active Areas -- Recent implementation facts from the last 14 days
• Open Issues -- Count of active bugs and pending todos

The project brief is always included as the first section of the brain document.

Layer 1: Active Knowledge (~1,500 tokens)

Recent, high-importance, and actionable items. This layer contains the knowledge most likely to be relevant to an ongoing coding session. Items are grouped by type:

1. Key Decisions -- Recent architectural choices
2. Recent Fixes & Known Issues -- Active or high-importance bugs
3. Pending Tasks -- Active todos
4. Conventions -- Recently established coding rules
5. Recent Work -- Implementation facts from the last 30 days
6. Architecture -- Recent architecture notes

Items qualify for Layer 1 based on these criteria:

• Updated within the last 30 days with importance >= 3
• Decisions updated within 30 days (any importance)
• Active bugs with importance >= 4 or updated within 7 days
• Active todos
• Conventions updated within 14 days
• Any item with importance >= 4 updated within 60 days

Layer 1 items include rich metadata: confidence, importance, tags, files, and age.

Layer 2: Reference Knowledge (~2,000 tokens)

Stable, high-confidence knowledge that provides useful background but is not immediately actionable. Items are grouped by schema key prefix (e.g., Decisions, Conventions, Architecture, Frontend, Backend).

Items in Layer 2 are formatted more compactly than Layer 1 to fit more knowledge within the budget. They include confidence and file references but omit age and importance metadata.

Layer 3: Archive (Excluded)

Items classified as Layer 3 are excluded from the brain document entirely. They remain in the database and can be accessed via contox_search or contox_context_pack. Items land in Layer 3 when:

• Their status is superseded or archived
• They are CodeMapNode type (always archived)
• They have low confidence (< 0.4) and are older than 14 days
• They are old implementation facts or bug fixes past their archival threshold

The brain footer shows a count of archived items and directs users to search tools.

Token Budget

The brain enforces a strict token budget to ensure the document fits within AI assistant context windows:

Token estimation uses a simple heuristic: 1 token ~ 4 characters. When a layer exceeds its budget, items are truncated at line boundaries. Higher-scoring items (computed from importance, confidence, and recency) are included first, so the most valuable knowledge always makes it into the brain.

The budget is configurable via BrainAssemblyOptions:

interface BrainAssemblyOptions {
  tokenBudget?: number;      // default 6000
  layer0Budget?: number;     // default 500
  layer1Budget?: number;     // default 1500
  layer2Budget?: number;     // default 2000
  includeProjectBrief?: boolean; // default true
}

Item Scoring

Within each layer, items are sorted by a composite score that balances three factors:

score = (importance / 5) * confidence * recency

Where:

• importance is the 1--5 scale (default 3)
• confidence is the 0.0--1.0 score
• recency decays from 1.0 (today) to 0.1 (at 90 days)

This ensures recently updated, high-importance, high-confidence items appear first.

ETag Caching

The brain response includes a brainHash field -- a deterministic hash computed from all included item IDs and their updatedAt timestamps:

// Hash is a truncated SHA-256 of sorted "id:updatedAt" pairs
const hash = sha256(items.map(i => `${i.id}:${i.updatedAt}`).sort().join('|'))
  .slice(0, 16);

Clients can send this hash via the If-None-Match header. If the brain has not changed, the server responds with 304 Not Modified, avoiding the cost of re-assembly and transfer. This is particularly valuable for the MCP server, which loads the brain at the start of every AI session.

Brain Response

The GET /api/v2/brain endpoint returns:

interface V2BrainResponse {
  document: string;       // Full assembled markdown
  tokenEstimate: number;  // Estimated token count
  itemsLoaded: number;    // Items included (Layer 1 + 2)
  schemaKeys: string[];   // Unique schema keys present
  brainHash: string;      // ETag for caching
  tree: V2BrainTreeNode[]; // Hierarchical view of schema keys
}

CLAUDE.md Summary

In addition to the full brain document, the assembler produces a compact summary optimized for injection into CLAUDE.md project instruction files. This summary (~1,000 tokens) includes only the project brief, recent decisions, and known issues -- enough for an AI assistant to get quick orientation without the full brain.

Viewing the Brain in the Dashboard

The brain is accessible from the Memory page in the Brain tab:

• Tree view -- Browse the hierarchical brain structure organized by schema keys. Each node shows its name, item count, and state badges (draft/approved/deprecated)
• Item details -- Click any item to see its full content, confidence score, importance, evidence references, and related files
• Tier badges -- Items display their layer classification (Layer 0, 1, 2, or 3) so you can see which knowledge is actively included in the brain document
• State management -- Approve draft items to include them, or deprecate outdated items to exclude them