Contexts (V1)
Contexts are the fundamental unit of knowledge storage in Contox's original (V1) system. Each context is a named container that holds project knowledge as either a single markdown document or a series of append-only journal entries.
Note: The V2 system (Memory Items) is now the primary knowledge system. V1 contexts remain fully supported and are used by the MCP server's context management tools. See Memory Items for the V2 approach.
Data Model
| Field | Type | Constraints | Description |
|---|---|---|---|
name | string | 1--100 characters | Display name of the context |
description | string | max 500 characters, optional | Brief summary of what this context contains |
content | string | max 50,000 characters | The markdown content (content-based storage) |
schemaKey | string | optional | Hierarchical taxonomy key (e.g., root/frontend/hooks) |
tier | integer | 1, 2, or 3 | Controls brain inclusion priority |
state | enum | draft | approved | deprecated | Lifecycle state |
contextType | enum | system | reference | memory | Classification of the context's origin |
parentContextId | string | optional | Parent context ID for hierarchy |
Storage Models
Contexts support two distinct storage models:
Content-Based Storage
A single markdown document stored in the content field. Best suited for:
- Architecture overviews
- Convention documents
- Design decision records
- Static reference material
Content is replaced on update (not appended). The maximum content size is 50,000 characters.
Entries-Based Storage
An append-only journal where each entry has its own title, content, tags, and metadata. Best suited for:
- Implementation journals
- Bug fix logs
- Session summaries
- Any chronological record
Entries are never overwritten -- new entries are always appended. Each entry can include:
| Field | Description |
|---|---|
title | Short description of the entry (max 200 characters) |
content | Full markdown content of the entry |
entryType | Classification (e.g., bug-fix, feature, session) |
tags | Array of categorization tags |
source | Origin identifier (e.g., cli-scan, mcp-server) |
sourceRef | Reference back to the source (e.g., commit SHA) |
Context Types
The contextType field classifies how the context was created and how it should be treated:
| Type | Description | Typical Source |
|---|---|---|
system | Core project configuration and structure | Created by the system during project setup |
reference | Stable knowledge unlikely to change frequently | Populated via contox scan or manual entry |
memory | Session-derived knowledge that evolves over time | Created by contox_save_session or auto-save |
Hierarchical Organization
Contexts can be organized into a tree structure using parentContextId. This enables:
- Grouping related contexts under a common parent
- Nested navigation in the dashboard
- Scoped searches within a subtree
For example, a project might organize contexts as:
Project Memory (root)
+-- Architecture
| +-- Frontend Architecture
| +-- Backend Architecture
+-- Conventions
| +-- Code Style
| +-- Git Workflow
+-- Implementation Journal
State Machine
Every context follows a three-state lifecycle:
stateDiagram-v2
[*] --> draft : Created
draft --> approved : Approve
approved --> deprecated : Deprecate
deprecated --> approved : Re-approve
States
| State | Description | Brain Inclusion |
|---|---|---|
draft | Newly created, not yet reviewed | Excluded from brain |
approved | Reviewed and accepted as valid knowledge | Included in brain |
deprecated | Outdated or superseded by newer information | Excluded from brain |
Only approved contexts are included when assembling the brain document. Draft contexts are visible in the dashboard but do not affect the brain output. Deprecated contexts are hidden by default but can be found via search.
Tier System
The tier field controls how eagerly a context is loaded into the brain:
| Tier | Strategy | Use Case |
|---|---|---|
| 1 | Always loaded | Critical conventions, key decisions, active bugs |
| 2 | Loaded on demand | Reference material, stable architecture docs |
| 3 | Archived | Historical entries, resolved bugs, old journal entries |
Tiers map directly to the brain's layer system. See Brain Assembly for details on how tiers affect the assembled document.