Context Architecture (Technical Reference)

How the agent system loads, layers, and refreshes context to give Claude the right information at the right time.

Why Context Matters

Claude Code agents are only as effective as the context they receive. Without structured context loading, agents:

• Lack awareness of user preferences, values, and constraints
• Cannot route tasks to the right tools or workflows
• Miss domain-specific knowledge needed for quality output
• Repeat questions that should already have answers

The context architecture solves this with layered, on-demand context loading — from broad system rules down to domain-specific knowledge.

Context Layers at a Glance

  ┌─────────────────────────────────────────────┐
  │  Layer 1: Global CLAUDE.md                  │
  │  (agent behavior, safety, git rules)        │
  └──────────────────────┬──────────────────────┘
                         │
                         ▼
  ┌─────────────────────────────────────────────┐
  │  Layer 2: Project CLAUDE.md                 │
  │  (repo-specific rules)                      │
  └──────────────────────┬──────────────────────┘
                         │
                         ▼
  ┌─────────────────────────────────────────────┐
  │  Layer 3: InnerOS Self_Context              │
  │  (identity, values, health, domains)        │
  └──────────────────────┬──────────────────────┘
                         │
                         ▼
  ┌─────────────────────────────────────────────┐
  │  Layer 4: Operating System                  │
  │  (AGENT_GUIDE, conventions, LLM instr.)     │
  └──────────────────────┬──────────────────────┘
                         │
                         ▼
  ┌─────────────────────────────────────────────┐
  │  Layer 5: Goals & Workflows                 │
  │  (structured goals, workflow definitions)   │
  └──────────────────────┬──────────────────────┘
                         │
                         ▼
  ┌─────────────────────────────────────────────┐
  │  Layer 6: Coaching Layer                    │
  │  (playbook, session logs)                   │
  └─────────────────────────────────────────────┘

Layer Details

Layer 1: Global CLAUDE.md

Scope: All projects, all sessions Location: ~/.claude/CLAUDE.md Loads: Automatically on every Claude Code session

This is the foundation. It defines:

• Agent behavior rules — iteration bounds, completion promises, validation requirements
• Safety guardrails — what agents can and cannot do autonomously
• Git sync rules — when to commit, when to push, branch conventions
• Task management protocol — how to use todo.md, how to mark tasks complete
• Human handoff protocol — what to include when handing off to a human
• Skills vs agents decision framework — when to use deterministic scripts vs LLM reasoning

Every agent in every project inherits these rules. This is where you put universal constraints.

Layer 2: Project CLAUDE.md

Scope: Single repository Location: <repo-root>/CLAUDE.md Loads: Automatically when working in that repo

Project-specific rules that override or extend global behavior:

• What this repo is and how it’s structured
• Repo-specific conventions (naming, testing, deployment)
• Files to read first, directories to ignore
• Build and validation commands for this project

Example: A documentation repo’s CLAUDE.md might say “never auto-commit” and “always run npm run build before marking done,” while a Python project’s might specify “run pytest and mypy.”

Layer 3: InnerOS Self_Context

Scope: Personal identity and preferences Location: Obs_Vault/0_InnerContext/Self_Context/ Loads: On /contxt command

              ┌────────────────────────────┐
              │  master_context.md         │
              │  (hub file ~67KB)          │
              └─────────────┬──────────────┘
                            │
      ┌──────────┬──────────┼──────────┬──────────┐
      │          │          │          │          │
      ▼          ▼          ▼          ▼          ▼
  ┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────────┐
  │identity  ││values    ││health    ││domains   ││communication │
  │.md       ││.md       ││.md       ││.md       ││.md           │
  └──────────┘└──────────┘└──────────┘└──────────┘└──────────────┘
      ┌──────────┬──────────┬──────────┐
      │          │          │          │
      ▼          ▼          ▼          ▼
  ┌──────────┐┌──────────┐┌──────────┐┌──────────────┐
  │relation- ││constr-   ││prefer-   ││... (15 files │
  │ships.md  ││aints.md  ││ences.md  ││    total)    │
  │          ││(e.g.ADHD)││          ││              │
  └──────────┘└──────────┘└──────────┘└──────────────┘

This is the “who you are” layer:

Agents use this to tailor their output — a coach agent reads health.md, a planner reads constraints.md, a writer reads communication.md.

Layer 4: Operating System

Scope: Agent routing and conventions Location: Obs_Vault/0_InnerContext/ Loads: On /contxt command (Step 1: essentials)

AGENT_GUIDE.md is the most critical file in the system. It’s the “table of contents” that lets any agent navigate the vault and find what it needs.

Layer 5: Goals & Workflows

Scope: Domain-specific plans and processes Location: Obs_Vault/1_Projects/ and Obs_Vault/2_Areas/ Loads: On /contxt [domain] command

Each life domain has:

• Goals file — structured goals with status, metrics, and next actions
• Workflows file — _workflows.md defining repeatable processes
• Active projects — current work in progress

Domains follow the PARA structure:

Layer 6: Coaching

Scope: Personal growth and reflection Location: Obs_Vault/2_Areas/Coaching/ Loads: On /contxt coaching or coaching-related commands

• Coaching playbook — frameworks, exercises, prompts
• Session logs — past coaching session notes and insights
• Growth tracking — patterns identified over time

Layer Interaction

  ┌─ Always Loaded ───────────────┐      ┌─ On-Demand ─────────────────────┐
  │                               │      │                                 │
  │  Global CLAUDE.md             │      │  Self_Context                   │
  │       │                       │      │       │                         │
  │       ▼                       │      │       ▼                         │
  │  Project CLAUDE.md            │──▶   │  Operating System               │
  │                               │      │       │                         │
  └───────────────────────────────┘      │  ┌────┴─────┐                   │
                                         │  ▼          ▼                   │
                                         │  Goals &    Coaching            │
                                         │  Workflows                      │
                                         └─────────────────────────────────┘

Key principle: Lower layers constrain upper layers. If Global CLAUDE.md says “never force-push to main,” no amount of domain context can override that. This creates a safe, predictable system where adding context adds capability without removing guardrails.

Loading & Routing

How the /contxt command fetches the right context for any session.

The Loading Mechanism

Context loading follows a 2-step bundle pattern: first load the essentials that every session needs, then load domain-specific context based on what you’re working on.

  User ──▶ /contxt [domain] ──▶ Step 1: Essentials ──▶ Step 2: Domain Bundle ──▶ Agent
                                       │                       │
                                  Load llm_instructions.md     │
                                  Load AGENT_GUIDE.md     (if domain specified)
                                       │                  Route to domain bundle
                                  Essentials ready        Domain context loaded
                                       │                       │
                                       └───────────────────────┘
                                                │
                                       Full context injected
                                                │
                                                ▼
                                    Agent ──▶ Ready with context

Step 1: Load Essentials

Every /contxt invocation loads two critical files:

These files give the agent enough orientation to navigate the vault and understand system conventions, regardless of what domain you’re working in.

Step 2: Domain-Specific Bundle

When you specify a domain, the command loads additional context:

Each bundle is a curated set of files from the vault that gives the agent domain expertise.

The Routing Index: AGENT_GUIDE.md

AGENT_GUIDE.md is the single most important file in the context system. It acts as a table of contents for the entire vault, telling agents:

• Where to find files for each domain
• Which workflows apply to which tasks
• What conventions to follow
• Where to store outputs

                ┌──────────────────────────────┐
                │  AGENT_GUIDE.md              │
                │  (master routing index)      │
                └──────────────┬───────────────┘
                               │
         ┌──────────┬──────────┼──────────┬──────────┬──────────┐
         │          │          │          │          │          │
         ▼          ▼          ▼          ▼          ▼          ▼
  ┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐┌──────────┐
  │ Coding   ││ Music    ││ Finance  ││ Health   ││ Admin    ││ Content  │
  │ projects ││ sessions ││ portfolio││ metrics  ││ house    ││ writing  │
  │ stack    ││ releases ││ DeFi     ││ goals    ││ suppliers││ publish  │
  │ convent. ││ gear     ││ tax      ││ constr.  ││ calendar ││ social   │
  └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘

Without this file, agents would need to search the vault blindly. With it, they can jump directly to the relevant files.

Building Your Own Routing

To set up context loading for your system:

1. Create your AGENT_GUIDE.md

List every important file and directory, organized by domain:

# Agent Guide
 
## Coding
- Projects: `1_Projects/Coding/`
- Stack preferences: `2_Areas/Coding/stack.md`
- Conventions: `_System/Conventions/coding.md`
 
## Finance
- Portfolio: `2_Areas/Finance/portfolio.md`
- Tax docs: `2_Areas/Finance/tax/`

2. Create your /contxt command

A slash command that reads the routing index and loads the right files:

# Context Loader
 
Load system context for the current session.
 
## Usage
/contxt [domain]
 
## Steps
1. Read `llm_instructions.md` for base instructions
2. Read `AGENT_GUIDE.md` for routing
3. If domain specified, load domain-specific files listed in AGENT_GUIDE
4. Confirm what was loaded

3. Define domain bundles

For each domain, decide which files the agent needs. Keep bundles focused — loading too much context wastes tokens and dilutes attention.

Good bundle: 3-5 focused files totaling under 30KB Bad bundle: 20 files totaling 200KB (agent will lose focus)

Context Budget

Every token of context loaded is a token not available for reasoning. Be strategic:

The /contxt command should respect these budgets, loading only what’s needed for the current task rather than everything available.

Refresh Cycle

Context goes stale. Here’s how the system keeps it fresh automatically and manually.

Why Refresh Matters

Context files represent your current state — goals, priorities, active projects, health, preferences. When these files drift from reality, agents make decisions based on outdated information.

Two mechanisms keep context fresh:

1. Automated refresh via NightCrew (daily, runs at 3 AM)
2. Manual refresh when you make significant changes

NightCrew: Automated Refresh

NightCrew is a LaunchAgent-triggered pipeline that runs every night. It collects data from across your system and updates context files.

  ┌─ 3:00 AM - NightCrew Pipeline ──────────────────────────────────────────┐
  │                                                                         │
  │  Stage 1-3              Stage 4-6              Stage 7-9                │
  │  File triage &   ──▶   Messages, voice  ──▶   Photos, activity          │
  │  session extraction     memos, calendar        summary, morning brief   │
  │                                                      │                  │
  │                                                      ▼                  │
  │  Stage 13-15            Stage 10-12                                     │
  │  Context file    ──     Conversation analysis                           │
  │  updates                & pattern detection                             │
  │       │                                                                 │
  │       ▼                                                                 │
  │  Stage 16                                                               │
  │  Git push to sync                                                       │
  │       │                                                                 │
  └───────┼─────────────────────────────────────────────────────────────────┘
          │
          ▼
  ┌──────────────────────────────┐
  │  master_context.md           │
  │  Updated with fresh data     │
  └──────────────────────────────┘

What Gets Refreshed

The Key Output: master_context.md

The most important output of NightCrew is the updated master_context.md. This file is the hub that links to all other Self_Context files. When agents load context via /contxt, this file tells them what’s current.

NightCrew rewrites master_context.md by:

1. Scanning conversation patterns from recent Claude sessions
2. Analyzing photo library changes (vision-based classification)
3. Pulling reading highlights and notes
4. Aggregating health and activity data
5. Synthesizing all of the above into updated priorities and status

Manual Refresh

Some changes can’t wait for the nightly pipeline. Update context files manually when:

Manual Refresh Workflow

                                     ┌─── Yes ──▶ Let NightCrew handle it
                                     │
  Change happens ──▶ Can it wait? ───┤
                     for NightCrew   │
                                     └─── No ───▶ Update file ──▶ Update ──▶ Git commit
                                                  directly       AGENT_GUIDE   & push
                                                                 (if routing
                                                                  changed)

Setting Up Your Own Refresh

Minimal Setup (No Automation)

Just update files manually. This works if you have a small vault and few context files.

Recommended Setup (Hybrid)

1. Create a nightly script that collects data from your key sources
2. Set up a LaunchAgent to run it at a fixed time
3. Include a master_context.md regeneration step — even a simple concatenation of key files helps
4. Git push at the end to sync changes

Advanced Setup (Full NightCrew)

Build a multi-stage pipeline:

1. Data collection scripts for each source (Python recommended)
2. Aggregation step that merges data into summaries
3. Context generation step that updates vault files
4. Analysis step (optional) that uses Claude to find patterns
5. Sync step that commits and pushes

The staged approach means each step can fail independently without breaking the whole pipeline.

Freshness Indicators

How to tell if your context is stale:

Tip: Add a last_updated: field to your key context files. NightCrew can write this automatically, and you can grep for stale files with a simple script.