Schema Keys

Schema keys are hierarchical identifiers that classify every piece of knowledge in Contox. They follow a path-based naming convention (root/category/subcategory) and serve as the organizational backbone for the brain document, memory items, and contexts.

Naming Convention

Schema keys use forward-slash-separated segments, always starting with root/:

root/category
root/category/subcategory

• All segments are lowercase
• Use hyphens for multi-word segments (e.g., backend/api)
• Maximum depth is typically 2--3 levels
• The root prefix is always present

Full Taxonomy

Contox defines 30 canonical schema keys, organized into three categories: domain keys (where in the project), package keys (which package), and type keys (what kind of knowledge).

Domain Keys

These classify knowledge by its location in the project architecture:

Backend Keys

Frontend Keys

Package Keys

Type Keys

Used when no clear domain applies -- these classify by knowledge type:

Extended Hierarchy (Brain Schema)

The brain schema defines additional keys for engineering layers beyond the core 29 enrichment keys. These are used in the static brain schema for organizing the knowledge graph:

root/
  cortex
  stack/
    database, environment, deployment
  api/
    auth, core, integrations
  frontend/
    ui, pages, hooks, design, components, routes, state, lib, stores, types
  backend/
    auth, logic, integrations, api, services
  packages/
    mcp, cli, plugin, vscode
  conventions
  decisions
  todo
  bugs
  journal
  sessions
  contracts/
    auth, brain-endpoint, entries, populate, search, links, compaction
  runbooks/
    brain-5xx, populate-stuck, search-low-recall, drafts-never-approved, audit-mismatch, appwrite-throttling
  ops
  security
  governance
  quality
  performance
  patterns
  flows
  schema
  adrs

Schema Key Resolution

Schema keys are assigned through two mechanisms depending on the event type:

LLM-Based Resolution (Primary)

For mcp_save and vscode_capture events, the LLM (Mistral) picks from the canonical enum of 30 schema keys during enrichment. The system prompt includes the full taxonomy with descriptions, and the JSON schema enforces that only valid keys are emitted.

Deterministic Resolution (Fallback)

For auto_save and scan events (or when the LLM output is invalid), schema keys are inferred from file paths using prefix-matching rules:

// Path prefix → schema key (first match wins)
'src/app/api/'           → 'root/backend/api'
'src/components/'        → 'root/frontend/components'
'src/hooks/'             → 'root/frontend/hooks'
'src/stores/'            → 'root/frontend/stores'
'packages/cli/'          → 'root/cli'
'packages/mcp-server/'   → 'root/mcp'
'.github/'               → 'root/infra'
'package.json'           → 'root/stack'

When file-based resolution fails, the system falls back to a type-based mapping:

Normalization

LLM-generated schema keys are validated and normalized before storage. The normalizer handles:

• Exact matches against the canonical set
• Case normalization (lowercasing)
• Missing root/ prefix (auto-prepended)
• Over-deep keys (truncated to 2 or 3 levels)
• Complete fallback to root/other if nothing matches

Tiers and Brain Layers

Schema keys interact with the tier system to control brain inclusion:

Note that tier assignment is not solely based on the schema key -- it also considers the item's recency, importance, confidence, and status. See Brain Assembly for the full classification logic.

Section Ordering in Brain

When the brain document is assembled, Layer 2 items are grouped by their schema key prefix (first two segments) and displayed in a fixed order:

1. Decisions
2. Conventions
3. Architecture
4. Stack
5. Data Layer
6. Authentication
7. Security
8. Backend
9. Frontend
10. Performance
11. Implementation Journal
12. Bug Fixes
13. Todo / Pending
14. CLI
15. MCP Server
16. VS Code Extension
17. Infrastructure
18. Testing
19. Documentation
20. Code Map
21. Other