Teach Me

# Knowledge Store — The Teacher's Persistent Library

A real teacher doesn't re-read the textbook before every class. They build
a personal library of notes, examples, and teaching materials that grows
over time. This reference defines how the agent stores, organizes, and
refreshes topic knowledge.

## The Problem

```
WITHOUT knowledge store:
  Session 1: /teach-me quantum physics
    → 15 min researching, fetching MIT OCW, reading notes
    → Teaches the learner

  Session 2: /teach-me quantum physics (same or different learner)  
    → 15 min researching THE SAME THINGS again
    → All the analogies, examples, misconceptions — rebuilt from scratch
    → Waste of time, may produce inconsistent teaching

WITH knowledge store:
  Session 1: /teach-me quantum physics
    → 15 min researching → saves to knowledge/quantum-physics/
    → Teaches the learner

  Session 2: /teach-me quantum physics
    → Checks knowledge/quantum-physics/ → it exists!
    → Quick refresh check (has anything changed?) → 1 min
    → Teaches immediately with the SAME high-quality materials
```

## Folder Structure

```
knowledge/
├── {topic-slug}/                  ← One folder per topic
│   ├── meta.json                  ← When researched, sources, freshness
│   ├── sources.md                 ← URLs fetched, quality ratings, dates
│   ├── concept-map.md             ← Concepts, prerequisites, connections, ordering
│   ├── teaching-notes.md          ← THE TEACHER'S EDITION:
│   │   │                             analogies, examples, mistake cards,
│   │   │                             checkpoint questions, hooks, bridges
│   │   └──                           — everything from Stages 2-5
│   ├── misconceptions.md          ← Common student errors + corrections
│   └── roadmap.md                 ← Learning roadmap (for large topics)
│
├── quantum-physics/               ← Example
│   ├── meta.json
│   ├── sources.md
│   ├── concept-map.md
│   ├── teaching-notes.md
│   └── roadmap.md
│
├── playwright/
│   └── ...
│
└── linear-algebra/
    └── ...
```

## meta.json Schema

```json
{
  "topic": "quantum-physics",
  "official_docs_url": null,
  "created": "2026-04-09T12:00:00Z",
  "last_refreshed": "2026-04-09T12:00:00Z",
  "refresh_interval_days": 365,
  "confidence_tier": 1,
  "size": "large",
  "sources_fetched": [
    {
      "url": "https://ocw.mit.edu/courses/8-04.../pages/syllabus/",
      "type": "syllabus",
      "fetched": "2026-04-09",
      "quality": "authoritative"
    }
  ],
  "concept_count": 13,
  "has_roadmap": true,
  "times_taught": 0
}
```

## When to Use Stored Knowledge vs. Fresh Research

```
CHECK ORDER:

1. Does knowledge/{topic-slug}/ exist?
   NO  → Run full learning pipeline (references/learning-pipeline.md)
         Save results to knowledge/{topic-slug}/
   YES → Go to step 2

2. Is the knowledge fresh enough?
   Check meta.json → last_refreshed + refresh_interval_days
   
   Refresh intervals by tier:
   ├── Tier 1 (physics, math, algorithms):  365 days
   ├── Tier 2 (framework APIs, practices):   90 days
   └── Tier 3 (new tools, current state):    30 days
   
   FRESH → Use stored knowledge directly. Skip to Stage 4 (Plan).
   STALE → Run a REFRESH (see below), not a full re-research.

3. Quick refresh (for stale knowledge):
   - web_search: "{topic} latest changes {current_year}"
   - web_search: "{topic} new best practices"
   - Check: has the major version changed? Any deprecations?
   - If minor changes → update teaching-notes.md, bump last_refreshed
   - If major changes → re-run full pipeline, rebuild knowledge store
```

## What to Save (After Stages 1-5)

### sources.md — Where the knowledge came from

```markdown
# Sources: Quantum Physics

## Primary Sources
- **MIT OCW 8.04** (Spring 2016, Prof. Zwiebach)
  - Syllabus: https://ocw.mit.edu/courses/8-04.../pages/syllabus/
  - Lecture notes: https://ocw.mit.edu/courses/8-04.../pages/lecture-notes/
  - Quality: Authoritative, excellent pedagogy
  - Fetched: 2026-04-09

## Supplementary Sources
- **Common Misconceptions article** (The Conversation, 2022)
  - URL: https://theconversation.com/four-common-misconceptions-...
  - Quality: Good for teaching — real misconceptions from researchers
  - Fetched: 2026-04-09

## Not Useful (skip next time)
- [URL that was low quality] — why it wasn't useful
```

### concept-map.md — The structured knowledge

```markdown
# Concept Map: Quantum Physics

## Learning Order (from MIT 8.04)
1. Why classical physics breaks (photoelectric, blackbody)
2. Wave-particle duality (double slit, de Broglie)
3. Superposition & measurement
4. Wavefunctions and probability
5. Schrödinger equation
...

## Dependency Graph
classical-fails → wave-particle → superposition → wavefunctions → schrödinger
                                 → measurement ↗
                                 → uncertainty ↗

## Per Concept
### 1. Why Classical Physics Breaks
- Complexity: 1/5
- Prerequisites: basic physics (energy, waves, light)
- Key insight: energy is quantized, not continuous
- Difficulty type: counterintuitive
- Connects to: wave-particle duality, quantization
```

### teaching-notes.md — The Teacher's Edition

This is the most valuable file. It contains everything prepared in Stages 2-5
so the teacher can walk into any session ready to teach:

```markdown
# Teaching Notes: Quantum Physics

## Track Selection
- Conceptual track: no calculus needed, analogy-heavy
- Mathematical track: requires calculus + basic linear algebra

## Hooks (prepared openings)
- Surprise: "Shine light on metal. Classical physics says brighter = 
  more energetic electrons. Reality: brightness doesn't matter. Only 
  COLOR matters. Classical physics is wrong."
- Story: "In 1900, Max Planck made an assumption he called 'an act of
  despair.' It accidentally started a revolution."

## Concept 1: Why Classical Physics Breaks
### Analogy
Radio dial (continuous tuning) vs light switch (on/off discrete).
Classical = dial. Quantum = switch. Energy comes in fixed packets.
⚠️ Boundary: analogy breaks for continuous spectra.

### Examples
Minimal: Photoelectric effect — shine UV light, electrons pop out.
         Brighter light = more electrons, NOT more energetic electrons.
Realistic: Solar cells use this — photon energy must exceed band gap.
Challenging: Why don't radio waves cause sunburn? (photon energy too low)

### Mistake Card
❌ "More light = more energy per photon"
✅ "More light = more photons. Each photon's energy depends only on frequency."
Why: conflating intensity with energy-per-quantum.

### Checkpoint
"If I double the brightness of a red laser, what happens to each 
 electron's energy? What if I switch to blue light?"
Expected: brightness → no change in energy. Blue → more energy per electron.

### Bridge to Next
"So energy comes in packets. But if light is made of particles (photons),
 why does it make interference patterns? That's the wave-particle duality..."

---
[...continues for each concept...]
```

### misconceptions.md — Student Error Patterns

```markdown
# Misconceptions: Quantum Physics

## 1. "Schrödinger's cat IS alive and dead"
- Reality: Schrödinger's point was that this is ABSURD at macro scale
- Source: pop culture, memes
- How to address: "Schrödinger was making fun of this idea, not endorsing it"
- When it comes up: usually Session 1 when discussing superposition

## 2. "Observation requires consciousness"
- Reality: any physical interaction that extracts information causes decoherence
- Source: Wigner, pop quantum mysticism
- How to address: explain what "measurement" means physically

## 3. "Uncertainty is because we disturb things by measuring"
- Reality: it's a fundamental property of wave-like states
- Source: Heisenberg's gamma-ray microscope thought experiment (misleading)
- How to address: show the math — Δx·Δp ≥ ℏ/2 is about wavefunctions
```

## Knowledge Store Lifecycle

```
CREATE (first time teaching a topic):
  Run full pipeline → save all outputs to knowledge/{topic}/

USE (subsequent sessions on same topic):
  Load from knowledge/{topic}/ → check freshness → teach

REFRESH (knowledge is stale):
  Quick search for changes → update affected files → bump timestamp

GROW (teaching reveals new insights):
  After each session, optionally update teaching-notes.md:
  - "This analogy worked great" → keep it
  - "Learner was confused by X" → add to misconceptions.md
  - "Found a better example" → replace in teaching-notes.md
  - "New checkpoint question that worked" → add it

DELETE (topic no longer relevant):
  Remove the folder. Rare — knowledge accumulates.
```

## Post-Session Update

After teaching, quickly update the knowledge store:

```
AFTER EACH SESSION, consider:
  □ Did any analogy work particularly well? → star it in teaching-notes
  □ Did the learner have a misconception I didn't anticipate? → add it
  □ Did I find a better example mid-session? → save it
  □ Did a checkpoint question fail to detect confusion? → improve it
  □ Increment times_taught in meta.json
```