| name | branch-note-convention |
| description | The exact naming and structure convention for memory branch notes. Use when creating, naming, or reorganizing notes in Memory/, or when checking whether a note follows the 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:
- The topic accumulates 2+ subtopics that deserve their own focused notes
- The flat note is approaching 150 lines
How to promote:
- Create the folder:
Memory/auth/
- Move the flat note into it:
Memory/auth/auth.md (keep the same name)
- Create subtopic notes beside it:
Memory/auth/jwt.md
- 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:
Memory/MEMORY.md -- always first; contains branch summaries and links- Branch entry notes (
Memory/<topic>.md or Memory/<topic>/<topic>.md) -- read only relevant ones
- 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
What is NOT a branch note
README.md in any folderINDEX.md -- not used in this systemindex.md -- the entry note pattern uses the folder name, not "index"- Any file in
Evidence/, Outputs/, or Sessions/
