branch-note-convention

Branch-Note Convention

The branch-note convention is the structural spine of the bedrock memory tree. It controls how notes are named, organized, and navigated.

---

The two forms

Form 1: Flat note (no subtopics needed)

Memory/
  stack.md

A single .md file. Topic has no subtopics currently.

Form 2: Folder + same-name entry note (has subtopics)

Memory/
  auth/
    auth.md         <- entry note: same name as the folder
    jwt.md          <- subtopic note
    sessions.md     <- subtopic note

The entry note (auth/auth.md) is the summary and router for the branch. Subtopic notes (jwt.md, sessions.md) hold the detail.

The entry note always has the same name as its folder. This is non-negotiable. It makes the convention deterministic and machine-readable.

---

Naming rules

Rule	Good	Bad
Use the project's own terminology	perception.md	computer-vision.md
Lowercase hyphenated	data-pipeline.md	DataPipeline.md
Specific, not generic	billing.md	payments-and-invoicing.md
One domain per note	auth.md	auth-and-sessions-and-tokens.md
Entry note = folder name	auth/auth.md	auth/index.md, auth/overview.md

---

Promotion: flat -> folder

Start flat. Promote to a folder only when:

1. The topic accumulates 2+ subtopics that deserve their own focused notes
2. The flat note is approaching 150 lines

How to promote:

1. Create the folder: Memory/auth/
2. Move the flat note into it: Memory/auth/auth.md (keep the same name)
3. Create subtopic notes beside it: Memory/auth/jwt.md
4. Update Memory/MEMORY.md to point to the entry note: [auth/auth.md](auth/auth.md)

Do NOT rename the entry note to index.md, overview.md, or README.md.

---

Reading order

Agents follow this reading order:

1. Memory/MEMORY.md -- always first; contains branch summaries and links
2. Branch entry notes (Memory/<topic>.md or Memory/<topic>/<topic>.md) -- read only relevant ones
3. Subtopic notes (Memory/<topic>/<subtopic>.md) -- only if the specific detail is needed