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: working rules, the invariants that break the product, response style	always read first
ai.md	Router — what the product is, the architecture table, a "where the truth lives" table. No narrative, no status (≤100 lines, gated)	yes — the map
README.md	Human-facing intro: what the app is, how to run it, roadmap	no
TASKS.md	The active queue. Full task detail and research live in TASKS/; done work in TASKS/archive.md	when the task is "what's next"
HANDOFF.md	Current operational state: branch, in flight, next action, landmines (≤40 lines, overwritten never appended)	yes — trust it as current state
MyMistakes.md	Failure log + RECIPES REGISTRY: one-off solutions / how-tos get recorded here the same session, then grepp'd before ever re-deriving them	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
docs/ai/*.md	Subsystem truth — one file per subsystem (capture, frame pipeline, output, overlays, youtube-api, ui-surface, product, environment). ai.md routes; docs/ai/index.md lists them with a "read when"	when the task touches that subsystem
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: rules + invariants; it points you here.
2. HANDOFF.md — current state. Trust it; don't re-derive it.
3. ai.md — the router: architecture and where truth lives.
4. The one docs/ai/*.md file that matches the task.
5. <dir>/index.md — before reading that directory's files.
6. The source files themselves — always the authority over any memory file.

Integration rule

Every feature change ships with what it falsifies corrected in the same commit — a path, an invariant, a status line. Broader restatement may be batched at a milestone. The point is that the map never stays wrong; it is not a tax on every commit.