Files

T

gramps 804b1d2f5f docs(memory): split the frame pipeline out of ai.md into docs/ai

ai.md is the mandatory read every session; at 2,702 lines / ~64k tokens it
costs the whole subsystem history even when the task never touches it. This
is a verbatim move, not a compression - nothing is deleted and each stub is
written from the moved text.

- docs/ai/frame-pipeline.md: 'Frame cadence', 'Per-element composite timing +
  scene dump', 'What the first instrumented take said', 'Render budget',
  'Scene compositor' and 'Live frame pipeline', byte-identical, plus a short
  'Related in ai.md' footer and two stale 'below' pointers corrected.
- ai.md keeps two stubs carrying the invariants that must not be missed
  (overlay on every render path, VideoFrame.Epoch, StripPool threads,
  Release-only render numbers; arrival-stamped rawvideo, non-blocking submit,
  stop order, burned _outputIndex judge) and links the new file.
- docs/ai/index.md + docs/index.md route the split; schema.md inventory lists
  the new tier.
- 4 index-row references and 2 TASKS.md anchors repointed; ai.md's Services
  row too.

Measured: ai.md 63.6k -> 47.1k tokens, 2,702 -> 1,975 lines. Progressive
disclosure per schema.md convention 5. No source touched; no push.

2026-10-26 10:25:21 -07:00

3.9 KiB

Raw Blame History

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`	Catalog/index for the task queue. The actual task files live in `TASKS/` (one file per task); `TASKS.md` carries the status table, open items, and research facts pointer. Read this for queue state; open task files for full detail.	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
`docs/ai/*.md`	Split-out subsystems of `ai.md` — verbatim moves (from 2026-10-26); `ai.md` keeps a short invariant stub + link, and `docs/ai/index.md` routes	when the task touches a moved subsystem
`Views/`	Reserved for Views; currently empty	—

Conventions

Semantic filenames. A file's name says what it is (YouTubeAuthService.cs, FocusPreservingListBox.cs). No codes, no abbreviations. Naming beats search.
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.
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.
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.
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

AGENTS.md — auto-read on-ramp; it points you here.
ai.md — what this app is, how it's built, current state, open decisions.
TASKS.md — what's done, what's next, and the YouTube API constraints.
<dir>/index.md — to understand a directory before reading its files.
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.

3.9 KiB Raw Blame History