Core Concepts

Understand how your brain works so you're not just cargo-culting commands.

Your Brain is Three Things

1. Research Archive (What You Know)

Your brain stores everything you want to remember:

• Newsletters in research/newsletters/

  • Saved as markdown, one file per issue
  • Summaries generated automatically
  • Organized by source (ethan, ben, simon, etc.)

• YouTube transcripts in research/youtube/

  • Full transcripts saved by channel
  • Key insights extracted
  • Searchable like newsletters

• Your notes in various folders

  • Ideas, meeting notes, observations
  • Todo items, project plans
  • All searchable, all citable

The power: Everything is text, searchable, and can be synthesized across sources.

2. Memory System (How It Thinks)

Your brain uses config files to know how to behave. There are two levels:

Two levels:

1. Global Config (~/.claude/CLAUDE.md)

   • Your personal preferences across all Claude Code projects
   • Who you are, what you care about
   • Communication style, focus areas
   • Applies everywhere, not just your brain

2. Brain Config (CLAUDE.md in your brain folder)

   • Instructions specific to this brain
   • Which research sources to use
   • How brain-advisor should work
   • Custom workflows and preferences

How it works: When you use your brain, Claude reads both configs. Brain-specific settings override global ones when there's a conflict.

Example:

• Global: "Be concise in all responses"
• Brain: "Provide detailed analysis with citations"
• Result: Brain responses are detailed, other projects stay concise

3. Intelligence Layer (How It Helps)

Four types of intelligence work together:

Skills → Auto-activate expertise Agents → Specialist workers Commands → Manual workflows MCP Servers → External tool access

Let's understand each one.

Skills vs Agents vs Commands vs MCP

Skills (Auto-Activate)

What: Expertise that loads automatically when Claude detects you need it

When: Claude sees trigger words/patterns in your request

Example:

You: "Get search terms for my Google Ads account"
→ google-ads-data skill auto-activates
→ Parses your request
→ Builds and runs query
→ Returns results

You don't invoke skills. Claude does.

Located: .claude/skills/ in your brain folder

Included skills:

• google-ads-data - Auto-activates on Google Ads requests
• draft-post - Creates posts from your notes
• video-script - Generates video scripts
• csv-analyzer - Analyzes CSV data files

Agents (Specialists)

What: Focused AI workers for specific jobs

When: You or Claude invoke them explicitly for specialized tasks

Example:

You: "Use brain-advisor to research AI pricing models"
→ brain-advisor agent launches
→ Searches your research indexes
→ Synthesizes insights from multiple sources
→ Returns answer with citations

You can invoke agents, or Claude can recommend them.

Located: .claude/agents/ in your brain folder

Key agents:

• brain-advisor - Searches your research, answers strategic questions
• inboxy - Processes inbox notes, routes to appropriate actions
• ads-query - Executes Google Ads queries, saves to CSV
• posty - Creates LinkedIn/Circle/email posts

Commands (Manual Workflows)

What: User-triggered workflows you type yourself

When: You explicitly run /command

Example:

You: /fetch https://youtube.com/watch?v=xyz123
→ Fetches transcript
→ Saves to research/youtube/
→ Generates summary
→ Updates index

Always user-invoked. You type the slash.

Located: .claude/commands/ in your brain folder

Common commands:

• /fetch <youtube-url> - Fetch YouTube transcript and save
• /verify-sheet-access - Check Google Sheets access
• /gemini <task> - Run task with Gemini model

MCP Servers (External Tools)

What: Connections to external systems and APIs

When: Skills/agents need to access external data or services

Example:

Skill needs Google Ads data
→ Uses Google Ads MCP server
→ MCP server authenticates with your account
→ Executes GAQL query
→ Returns results to skill

Configured globally, used by skills/agents.

Located: ~/.claude/mcp_settings.json (in your home directory, not the brain folder)

Available servers:

• google-ads - Google Ads API access (if configured)
• brave-search - Web search capability
• More can be added as needed

Comparison Table

How Research Indexing Works

Here's the full flow from newsletter arriving to you getting answers:

1. Newsletter arrives in Gmail

• Your subscriptions
• Gmail labels them "8020brain" (you set this up)

2. Script fetches and saves

• Runs daily (or on-demand when you ask)
• Downloads labeled emails
• Converts to markdown
• Saves to research/newsletters/[source]/ in your brain folder

3. AI generates summary

• Reads full newsletter
• Extracts key insights
• Creates structured summary
• Adds to newsletter file

4. Index updated

• Summary added to context/ideas/[source].md
• Source index now includes this issue
• Searchable by brain-advisor

5. Now queryable

• You ask: "What does Ethan say about AI in education?"
• brain-advisor searches indexes in your brain
• Finds relevant summaries
• Synthesizes answer with citations

The Big Picture:

Your brain remembers everything you've read so you can ask questions like "What have I learned about AI agents?" and get answers synthesized from 50+ sources in seconds.

No manual filing. No trying to remember where you read something. Just ask.

Why This Architecture

Separates concerns:

• Content (research) separate from intelligence (Claude)
• Manual (commands) separate from automatic (skills)
• Your brain separate from other Claude Code projects

Composes well:

• Skills use agents
• Agents use MCP servers
• Commands trigger skills
• Everything is text files

Easy to extend:

• Add new research sources → New folder
• Add new skill → New skill file
• Add new agent → New agent file
• Add new MCP server → Update config

Portable:

• All text files
• Git versioned
• No vendor lock-in
• Easy to backup

Mental Model Summary

Think of your brain as:

A library (research archive)

• Books on shelves (newsletters, transcripts)
• Organized by source (folders)
• Cataloged (index files)

A librarian (Claude + brain-advisor)

• Knows where everything is
• Can search the entire collection
• Synthesizes from multiple sources

Your workspace (your local brain folder)

• Your personal copy of the template
• Your preferences applied
• Your customizations active

A network (MCP servers)

• Connections to external systems
• Bring in fresh data
• Integrate with tools

When you ask a question, the librarian searches the library, consults the network if needed, and returns a synthesis based on your workspace preferences.

Simple concept. Powerful in practice.

Next: Feed your brain some knowledge →

Quick Reference

File Structure:

• research/ - Your captured content
• context/ideas/ - Summary indexes
• .claude/skills/ - Auto-activating expertise
• .claude/agents/ - Specialist workers
• .claude/commands/ - Manual workflows
• CLAUDE.md - Brain configuration

Intelligence types:

• Skills → Auto-activate
• Agents → Specialists
• Commands → Manual
• MCP → External access

Config levels:

• Global (~/.claude/CLAUDE.md) - Applies everywhere
• Brain (CLAUDE.md in brain folder) - Applies here

Research flow:

• Source → Capture → Summarize → Index → Query