Overview

Brain assembly is the process of combining approved memory items into a structured markdown document that AI tools consume at the start of each session. The assembler uses a layered architecture with token budgeting to produce a focused, relevant document within size constraints.

Assembly diagram

flowchart TD
    Items[(Approved Memory Items)] --> Group[Group by Schema Key]
    Group --> Sort[Sort by Section Order]
    Sort --> L0[Layer 0: Project Metadata]
    Sort --> L1[Layer 1: Architecture & Conventions]
    Sort --> L2[Layer 2: Implementation & Decisions]
    Sort --> L3[Layer 3: Todos & Session Logs]

    L0 --> Budget{Token Budget Check}
    L1 --> Budget
    L2 --> Budget
    L3 --> Budget

    Budget -->|Within Budget| Include[Include in Brain]
    Budget -->|Exceeds Budget| Truncate[Truncate or Omit]

    Include --> Markdown[Assemble Markdown]
    Truncate --> Markdown

    Markdown --> ETag[Generate ETag]
    ETag --> Response[Return Brain + Metadata]

Layers

The brain is organized into four layers, each with different priority levels:

Layer 0: Project metadata

The foundation layer contains project-level information:

• Project name and description
• Tech stack summary
• Key configuration details

This layer is always included and never truncated.

Layer 1: Architecture and conventions

High-priority knowledge that shapes every coding decision:

• Architecture patterns and design decisions
• Tech stack details (frameworks, libraries, versions)
• Coding conventions and style rules
• Project structure and organization

Tier 1 memory items are mapped to this layer. They are always included in the brain.

Layer 2: Implementation and decisions

Working knowledge about what has been built and why:

• Implementation journal (features, components, APIs)
• Key decisions with rationale and trade-offs
• Bug reports and their fixes
• Integration details

Tier 2 memory items are mapped here. They are included when the token budget allows.

Layer 3: Supplementary data

Lower-priority information that provides additional context:

• Todo lists and planned improvements
• Session logs and activity summaries
• Technical debt notes

Tier 3 memory items are mapped here. They are included only if there is remaining token budget.

Token budgeting

The assembler works within a configurable token budget (default: 6000 tokens):

1. Layer 0 is always included (typically 200-500 tokens)
2. Layer 1 items are added in order of confidence score until the budget is 60% consumed
3. Layer 2 items fill up to 90% of the budget
4. Layer 3 items use the remaining budget
5. If a layer exceeds its allocation, lower-confidence items within that layer are omitted

You can adjust the budget via the tokenBudget query parameter on the brain endpoint:

GET /api/v2/brain?projectId=proj_abc123&tokenBudget=10000

Schema key grouping

Items are grouped by their schema key to create logical sections:

# Project Memory

## Architecture (root/architecture)
- JWT Authentication Pattern (confidence: 0.95)
- PostgreSQL with connection pooling (confidence: 0.92)

## Conventions (root/conventions)
- Void arrow functions must have braces (confidence: 0.98)
- Use explicit return types on all functions (confidence: 0.95)

## Implementation (root/implementation)
- User auth middleware (confidence: 0.90)
- Dashboard layout with sidebar (confidence: 0.88)

Items within each group are sorted by confidence score (highest first).

ETag caching

The assembler generates an ETag based on the brain content hash:

1. After assembly, the markdown content is hashed
2. The hash becomes the ETag header value
3. Subsequent requests with If-None-Match matching the ETag receive 304 Not Modified
4. The brain is only reassembled when memory items change

This significantly reduces API calls and data transfer for MCP servers that poll frequently.

When the brain updates

The brain is reassembled when:

• New memory items are approved
• Existing items are updated, deprecated, or deleted
• The enrichment pipeline completes and produces new items
• The hygiene agent applies changes

The brain does not update when:

• Raw events are ingested (before enrichment)
• Sessions are created or completed (before enrichment)
• Non-memory changes occur (settings, members, etc.)

Next steps

• V2 Brain API -- Brain endpoint reference
• Context Packs -- Task-focused alternative to the full brain
• Enrichment -- How items are extracted