The File-Based Context Architecture

In Part 1, I covered why skills beat custom agents. In Part 2, I showed how skills compose. Now the question becomes: where does all this context actually live?

The answer is simpler than you'd expect: files.

The Problem with AI Context

Most AI assistant setups fail for one of two reasons:

1. They dump everything into context upfront. Every memory, every preference, every project detail—loaded on every conversation. Result: bloated context windows, degraded performance, high costs.

2. They're stateless. Each conversation starts fresh. No memory of what you worked on yesterday. No awareness of your projects. No accumulated knowledge.

The solution isn't a fancier model or more tools. It's architecture: a file-based context system with progressive disclosure.

Files as Memory

Claude Code is already designed to read files. That's its superpower. You don't need a vector database. You don't need a custom memory system. You need organized markdown files and a clear structure.

My system follows the PARA method from Tiago Forte's Building a Second Brain—Projects, Areas, Resources, Archives—with numbered prefixes for sorting and a .claude/ directory for AI-specific configuration:

digital-self/
├── 0-inbox/           # Capture: raw inputs, daily brief
├── 1-projects/        # Active work with deadlines
├── 2-areas/           # Ongoing responsibilities (journal, content)
├── 3-resources/       # Reference material (video insights, templates)
├── 4-archives/        # Completed/inactive items
├── _tools/            # CLI scripts Claude can invoke
└── .claude/
    ├── commands/      # Slash commands
    ├── skills/        # Composable capabilities
    └── settings.json  # Permissions, tool access

The key: Claude reads context on-demand, not upfront. When I ask about a project, it reads the relevant project folder. When I need my schedule, it reads the daily brief. Progressive disclosure.

The Three Context Layers

Layer 1: CLAUDE.md (Always Present)

A lean file (~2-3k tokens) that explains:

• The folder structure
• Current roles and projects
• Conventions (date formats, frontmatter requirements)
• What NOT to do

This is the only context loaded on every conversation. Keep it tight.

Layer 2: Commands and Skills (On-Demand)

Slash commands that package complex workflows:

• /daily-brief - Aggregates calendar, pipelines, inbox triage
• /shutdown - Creates handoff for session continuity
• /archive - Routes completed work to the right location

Skills that auto-trigger based on context:

• voice-formatter - Applies my voice when publishing
• expressing-insights - Structures content creation

Each command and skill is a markdown file. Claude reads it only when invoked. Zero overhead otherwise.

Layer 3: Project Context (Progressive)

Each project folder has its own CLAUDE.md explaining:

• What the project is
• Key files and their purposes
• Current status and priorities

Claude reads these only when the conversation touches that project. A conversation about content creation doesn't load my Mission Control codebase context.

The 40% Rule

Here's the critical insight I wish I'd known earlier: roughly 40% into your context window, model performance degrades measurably. Not at capacity. At 40%.

Dex Horthy calls this the "dumb zone." The more you fill up the context window, the worse outcomes you get. This explains why even lean setups can produce slop when conversations drag on.

Worse: corrections compound the problem. Telling Claude it's wrong repeatedly creates "trajectory poison"—the model sees a pattern of failure and learns to expect it.

The fix isn't more context. It's intentional compaction:

• Start fresh contexts instead of correcting endlessly
• Use subagents to explore, then compress findings
• Keep your main agent operating under 40%

This reframes /clear and /compact from "cleanup between tasks" to active tools for maintaining output quality mid-session.

The Daily Brief Pattern

The most valuable part of my system: a single ephemeral file that gets regenerated each morning.

0-inbox/daily-brief.md contains:

• Today's schedule (from Google Calendar)
• Pipeline statuses (content, leads)
• Inbox triage recommendations
• Risk flags
• The Big 3 priorities

This file is overwritten daily. History lives in git (git log -p -- 0-inbox/daily-brief.md).

The /daily-brief command:

1. Reads calendar events
2. Scans project statuses
3. Triages inbox items
4. Identifies risks
5. Generates the brief

One command, full operational awareness. And it stays under 40% of the context window.

Why Files Beat Databases

You might wonder: why not use a proper database? Vector embeddings? RAG?

For a personal AI system, files win because:

1. Git history. Every change is tracked. You can see how your priorities evolved, what you were thinking last month, when you made decisions.

2. Portability. It's just markdown. Works with any editor. Works offline. No vendor lock-in.

3. Claude already knows how to read files. No additional tooling needed. Read, Glob, Grep—all built in.

4. Human-readable. You can browse your own system. Edit files directly. The AI doesn't own your data.

5. Progressive disclosure is natural. Folders are hierarchies. Claude reads deeper when needed.

The Frontmatter Scanner Pattern

Progressive disclosure needs a mechanism. How do you know which of 37 resource files to actually read?

I built a simple CLI tool that extracts frontmatter (title, description, tags) from markdown files without reading their full content. Scanning 37 files costs ~1,500 tokens. Reading them all would cost ~30,000.

The workflow: scan first, review summaries, read only what matches. Claude decides which 2-3 files to actually open based on the metadata.

This is the "search before read" principle that makes file-based systems practical at scale.

The Decision Framework

Before adding any context to your system, ask:

1. Does this need to be in every conversation? If no, it shouldn't be in CLAUDE.md.
2. Is this a repeatable workflow? Make it a command.
3. Does it need to auto-trigger? Make it a skill.
4. Could it be project-scoped? Add it to that project's CLAUDE.md.
5. What's my current context budget? Check with /context.

The best Claude Code setup isn't the one with the most context. It's the one where every token earns its keep.

The 80/20 Implementation

If you want to build something similar, start here:

Day 1:

• Create a CLAUDE.md file explaining your folder structure
• Set up inbox, projects, areas, resources folders
• Write one slash command for your most repeated workflow

Week 1:

• Add a daily brief command
• Create project-specific CLAUDE.md files
• Build the handoff pattern (/shutdown)

Month 1:

• Add skills for composable capabilities
• Build CLI tools for external integrations
• Refine based on what you actually use

The goal isn't to build Jarvis. It's to build a system where Claude has exactly the context it needs, exactly when it needs it, and nothing more.

The Series Connection

This architecture is what makes skills-based development work:

• Part 1 explained why skills beat monolithic agents—they load on demand
• Part 2 showed how skills compose—separation of concerns
• Part 3 (this piece) reveals where it all lives—file-based progressive disclosure

The skills don't float in a vacuum. They're markdown files in .claude/skills/. The commands are markdown files in .claude/commands/. The context is markdown files in your folder structure. It's files all the way down.

And that's the point. Simple primitives. Boring technology. Powerful composition.

---

This is Part 3 of the Skills-First Architecture series.

• Part 1: Skills vs Agents — Why the industry converged on skills
• Part 2: Composable Skills — From theory to implementation
• Prequel: The Hidden Cost of MCP Servers — The context overhead problem

---

Building your own AI context architecture? The specifics will differ, but the principle holds: progressive disclosure beats monolithic context every time.