robotaitai/project-bedrock/project-memory-writing

Project Memory Writing

Focused rules for writing durable memory notes. This is the craft side of memory management: how to write notes that stay useful across sessions and agents.

When to use this skill

• Creating a new branch note or subtopic note
• Updating Current State or Recent Changes sections
• Reviewing a note that has grown noisy or stale
• Any time the question is "how should I write this?"

For tree structure and reading strategy, see memory-management. For bootstrapping from scratch, see project-ontology-bootstrap.

Verification first

Before writing anything to Memory/, verify the fact against the source:

Do NOT write:

• Speculative plans
• In-progress task state (use Sessions/)
• Raw agent summaries without verification
• Facts that change faster than once per week

Required frontmatter

Every Memory/ note must open with YAML frontmatter:

---
note_type: <type>
area: <branch-name>
updated: <YYYY-MM-DD>
---

note_type values: durable-memory-root (for MEMORY.md), branch-entry, branch-leaf, decision.

Do not add extra frontmatter fields that tools or other agents don't need.

Required sections for branch notes

Use this section order. Keep each section focused.

## Purpose
One sentence. What this branch covers. Rarely changes.
 
## Current State
Bullet list of verified facts about what is true right now.
-Lead each bullet with the fact itself.
-Do not describe what you "observed" -- state what IS.
-Each bullet should be independently verifiable.
 
## Recent Changes
Rolling log. Newest first. YYYY-MM-DD format. Prune to ~8 entries.
-2025-01-15 - Switched from Prisma to raw SQL. See decisions/.
-2025-01-10 - Added retry logic to all DB calls.
 
## Decisions
Links to decision files that affect this area.
-[2025-01-15-use-raw-sql.md](../decisions/2025-01-15-use-raw-sql.md) -- raw SQL over ORM
 
## Open Questions
Unresolved items. Remove when resolved.
-Why does the worker pool size default to 4? Is this tuned or a placeholder?

Quality rules

Be specific. "Uses Python 3.12" not "uses modern Python".

State facts, not observations. "Auth uses JWT with 24h expiry" not "I noticed auth seems to use JWT".

Stay bounded. Each note covers one domain. Do not add cross-domain facts to a branch note. If a fact belongs to two domains, put it in the more specific one and link from the other.

Keep Current State evergreen. Remove outdated bullets. Do not append without pruning. If you're adding a new fact, check if an old bullet should be removed.

Keep Recent Changes short. 6-10 entries. Oldest entries get pruned by compaction. The purpose is "what changed recently", not a full changelog.

Keep notes scannable. Use short bullets over prose paragraphs. Headers are navigation -- keep them consistent across notes.

Note sizing

When splitting, the entry note stays as the summary and router. Subtopic notes hold the detail.

Linking

Use relative markdown links, not wiki-links:

See [navigation](navigation/navigation.md) for path planning details.

Not:

See [[navigation]] -- avoid wiki-links for portability

Links from entry notes to subtopic notes:

## Branches
-[object-detection.md](object-detection.md) -- YOLO v8, TensorRT inference
-[lane-detection.md](lane-detection.md) -- semantic segmentation, road edge tracking

Links from branch notes to decisions:

## Decisions
-[2025-01-15-use-raw-sql.md](../decisions/2025-01-15-use-raw-sql.md) -- raw SQL over ORM

What goes where

Never put raw content in Memory/. Never put curated facts in Evidence/.

Memory/MEMORY.md rules

The root index must stay short (under 30 lines of content):

• One line per branch, with a brief inline summary
• No dense detail
• Updated only when branches are added, removed, or substantially renamed

## Branches
-[stack.md](stack.md) -- Python 3.12, FastAPI, PostgreSQL
-[auth/auth.md](auth/auth.md) -- JWT, bcrypt, refresh token rotation
-[decisions/decisions.md](decisions/decisions.md) -- decision log