LlamaCasty/schema.md

ytLlive — Memory Map (schema)

This file defines how the repo stores durable, associative memory: context as plain markdown files, versioned in git. It is the map of the map — the schema that every other memory file follows. Read ai.md first; this file explains why and how.

Why markdown files, not a database

• Grep-able, diffable, portable, human-editable — no tooling lock-in.
• Git gives versioning and history for free; every stale fact is a git log away.
• Files form a graph: each file is a node, each relative link an edge. The map stays associative (like memory) rather than a rigid tree.

File inventory

File	Role	Entry point?
AGENTS.md	Auto-read on-ramp for AI sessions — points to the map and the working rules	always read first
README.md	Human-facing intro: what the app is, how to run it, roadmap	no
ai.md	AI guide + session handoff — architecture, patterns, decisions, the cognitive map home	yes — start here
TASKS.md	Task queue + authoritative YouTube API research facts + task statuses	yes — for status
HANDOFF.md	Current operational state: what's in flight, landmines, next step, secret/DB/port locations	yes — trust it as current state
MyMistakes.md	Per-task failure log + RECIPES REGISTRY (derived-solution rule): one-off solutions / how-tos get recorded here the same session, then grepp'd before ever re-deriving them (see AGENTS.md 🔬)	grep first on any "did this before?" wall
schema.md	This file: the conventions below	when in doubt
<dir>/index.md	Per-directory map (progressive disclosure): what lives there + links	when diving into code
Views/	Reserved for Views; currently empty	—

Conventions

1. Semantic filenames. A file's name says what it is (YouTubeAuthService.cs, FocusPreservingListBox.cs). No codes, no abbreviations. Naming beats search.
2. One index.md per code directory. The index is a Map of Content (MOC): it lists every file in that directory with a one-line purpose and links out to related directories. Details live in the files, never duplicated in the index.
3. Links over hierarchy. Prefer relative links between related files over deep nesting. Relationships that matter should be visible from ai.md or an index.md; a note that is unreachable from ai.md might as well not exist.
4. Stale facts get FIXED, not appended. A wrong map is worse than no map. When the code changes, update the memory file in the same change — no "TODO: update later" notes.
5. Progressive disclosure. Don't cram detail into ai.md. ai.md names concepts and points at files; the indexes and source are the detail. Each layer adds resolution only when you drill in.

Reading order

1. AGENTS.md — auto-read on-ramp; it points you here.
2. ai.md — what this app is, how it's built, current state, open decisions.
3. TASKS.md — what's done, what's next, and the YouTube API constraints.
4. <dir>/index.md — to understand a directory before reading its files.
5. The source files themselves — always the authority over any memory file.

Integration rule

Every feature change ships with its memory update in the same commit: ai.md for architecture / patterns, TASKS.md for status, index files when the layout changes. No code commit without its docs — a follow-up "docs backfill" commit is a broken rule, not a style. That is what keeps the map accurate enough to trust next session.