Xray

## 🔬 X-Ray: What Just Happened

Let me explain what happened under the hood in our conversation.

---

### 📖 The Story of This Chat

Here's what I did, step by step:

**1. Session Started**
Before you typed anything, the system loaded:
- `CLAUDE.md` (~X tokens) — My personality, your preferences, available tools
- Session memories from earlier today — [list what was injected]
- [Any other context visible from hooks]

**Why this matters:** Without those session memories, I'd have no idea about 
[specific context]. That came from a **session hook** that runs before you type.

**2. You Asked: "[summarize their first message]"**

To respond, I:
- Read `[file 1]` — Because [reason]
- Read `[file 2]` — To check [what]
- Used [tool/MCP] — To [action]

**Why these files?** Your CLAUDE.md tells me where to look. It says [quote relevant 
instruction]. Without those instructions, I wouldn't know your file structure.

**3. [Continue for each major exchange in the conversation]**

---

### 🔧 Tools Used This Session

| Tool | Times Used | What For |
|------|------------|----------|
| `read` | X | Reading vault files |
| `write` | X | Creating new content |
| `edit` | X | Updating existing files |
| `bash` | X | Running commands |
| [other tools] | X | [purpose] |

**Why tools matter:** Without tools, I can only generate text. Tools let me 
actually DO things — read your files, write new ones, check your calendar, etc.

---

### 💡 Key Insight: The Context Window

Everything I "know" right now is what's in the **context window**:

If something isn't in this window, I literally don't know it exists.

---

### 📁 Files Touched This Session

**Read (loaded into my context):**
- `[file]` — [why it was needed]
- [continue for each file]

**Written/Modified:**
- `[file]` — [what was created/changed]
- [continue for each file]

**Why this matters:** Every file I read uses "tokens" (space in the context 
window). I try to read only what's relevant, not everything.

---

### 🎓 Concepts You Just Saw in Action

| What Happened | The Underlying Concept |
|---------------|------------------------|
| I knew about earlier conversations | **Session hooks** inject context at start |
| I read CLAUDE.md first | **System prompt** loads before anything |
| I created files with tools | **Tools** let AI take action, not just talk |
| I followed your file conventions | **CLAUDE.md instructions** define your structure |
| I didn't know about [X] | **Context limitation** — only know what's loaded |

---

### 🔮 What You Could Customize

Based on what just happened:

**1. Add to CLAUDE.md**
If you want me to always [behavior], add it to your `USER_EXTENSIONS` block.

**2. Create a Skill**
If you do [this workflow] often, create a skill to automate it.

**3. Add a Session Hook**
If you always want [context] loaded at start, write a hook that injects it.

---

### 🎓 Want to Go Deeper?

- `/xray ai` — First principles: context windows, tokens, statelessness
- `/xray dex` — Full architecture: CLAUDE.md, hooks, MCPs, skills, vault
- `/xray boot` — The session startup sequence in detail
- `/xray extend` — Step-by-step guide to customizing

Or ask anything: "How do hooks work?", "What's an MCP?", "How can I add my own tools?"

## 🧠 How AI Actually Works

Let me explain the core concepts that underpin everything Dex does.

---

### The Big Truth: AI Has No Memory

**The fundamental problem:** Every time you start a new chat, Claude has amnesia. 
It doesn't remember yesterday's conversation. It doesn't know your name, your 
projects, or what you discussed last week.

This is true for ALL LLM-based AI — ChatGPT, Claude, Gemini, all of them.

**Why?** LLMs are "stateless." They process text in, text out, with no permanent 
storage between sessions. Each conversation starts from zero.

**So how does Dex remember things?** We engineer around the limitation. 
That's what Dex is — clever engineering to give a forgetful AI the *appearance* 
of memory, context, and continuity.

---

### Concept 1: The Context Window

When you chat with an AI, there's an invisible "window" of text the AI can see:

**Key insight:** The AI can only work with what's IN the context window. 
If information isn't in there, the AI doesn't know it exists.

**Dex's job:** Get the RIGHT information INTO that window at the RIGHT time.

---

### Concept 2: Tokens (The Currency)

Context windows are measured in "tokens" (roughly 4 characters = 1 token).

- Claude's window: ~200,000 tokens (~150,000 words)
- Your CLAUDE.md: ~4,500 tokens
- A typical person page: ~500 tokens

**Why it matters:** There's a budget. Load too much context and you hit limits 
or slow things down. Load too little and the AI lacks crucial information.

**Dex's approach:** Selective loading. Don't dump everything — load what's 
*relevant* to what you're asking about.

---

### Concept 3: System Prompts (The Personality)

Before your first message, there's already text in the context window: 
the **system prompt**. For Dex, that's `CLAUDE.md`.

**The power move:** Everything in CLAUDE.md influences EVERY response. 
It's like setting the AI's personality and knowledge before you say hello.

---

### Concept 4: Tools (How AI Does Things)

Claude can't *do* things by default — it can only generate text. But with 
**tools**, it can take actions:

- Read files from your computer
- Write new files
- Run commands
- Query databases
- Call APIs

In Dex, tools come from **MCP servers** (Model Context Protocol). Each MCP 
gives Claude new capabilities.

**Without tools:** Claude can only talk.
**With tools:** Claude can take action on your behalf.

---

### Concept 5: The Conversation Loop

Here's what happens every time you send a message:

**Key insight:** Each turn, Claude sees MORE context (the history grows). 
Long conversations = more context = closer to limits.

---

### So What?

Understanding these fundamentals helps you:

1. **Know why Dex loads things at session start** — to get context into the window
2. **Understand why some info is "missing"** — it wasn't loaded into context
3. **See opportunities to extend** — what else could be loaded? what tools could help?

---

**Want to see Dex's specific architecture?** Try `/xray dex`

## 🏗️ How Dex Works: The Architecture

Now that you understand AI fundamentals, here's how Dex engineers around 
the limitations to create something useful.

---

### The Core Insight

**Problem:** Claude forgets everything between sessions.  
**Solution:** Store everything in FILES and reload context intelligently.

**The magic:** Your knowledge lives in files. AI reads files. 
Therefore, AI can "remember" by reading what was written before.

---

### Building Block 1: CLAUDE.md (The Brain)

The system prompt that defines who Dex is and how it behaves.

**Location:** `/CLAUDE.md` (root of your vault)

**Contains:**
- Your user profile (name, role, company)
- Your strategic pillars
- How Dex should behave
- What skills are available
- References to other docs

**Why it matters:** This loads FIRST, before anything else. It shapes every 
response. Edit this, and you change how Dex thinks.

**You can customize:**
```markdown
## USER_EXTENSIONS_START
<!-- Your personal additions go here -->
## USER_EXTENSIONS_END