robotaitai/project-bedrock/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

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

Do not read the full tree on every session. Load only what the task requires.

Linking between notes

Use relative markdown links. No wiki-links.

From MEMORY.md to a flat note:

-[stack.md](stack.md) -- Python 3.12, FastAPI, PostgreSQL

From MEMORY.md to a branch entry note:

-[auth/auth.md](auth/auth.md) -- JWT, bcrypt, refresh token rotation

From an entry note to a subtopic note:

See [JWT handling](jwt.md) for token structure and expiry.

From a branch note to a decision:

See [decisions/2025-01-15-use-raw-sql.md](../decisions/2025-01-15-use-raw-sql.md) for rationale.

Decisions branch

Memory/decisions/ uses the same convention but with dated filenames:

Memory/
  decisions/
    decisions.md              <- log of all decisions (same-name entry note)
    2025-01-15-use-raw-sql.md <- individual decision
    2025-02-03-drop-redis.md  <- another decision

The log (decisions.md) is the entry note for the decisions branch. Individual decision files are subtopic notes with dated slugs.

Frontmatter convention

---
note_type: branch-entry     # or branch-leaf, durable-memory-root, decision
area: <topic>               # matches folder/file name
updated: 2025-01-15
---

All Memory/ notes must have frontmatter. Evidence and Outputs also use frontmatter but with canonical: false and note_type: evidence or note_type: output.

Checklist for a new branch note

• [ ] File is named <topic>.md or <topic>/<topic>.md
• [ ] YAML frontmatter with note_type, area, updated
• [ ] Has ## Purpose (one sentence)
• [ ] Has ## Current State (bullet list of verified facts)
• [ ] Has ## Recent Changes (YYYY-MM-DD entries, newest first)
• [ ] Has ## Decisions (links to relevant decision files)
• [ ] Has ## Open Questions (unresolved items)
• [ ] Under ~150 lines
• [ ] Linked from Memory/MEMORY.md

What is NOT a branch note

• README.md in any folder
• INDEX.md -- not used in this system
• index.md -- the entry note pattern uses the folder name, not "index"
• Any file in Evidence/, Outputs/, or Sessions/