Write Useful Project Memory
Use this shared standard whenever a Codex Basic Memory skill writes or
substantially revises a note. This file is intentionally user-customizable: edit
the voice, emphasis, and preferred structure here to fit how you want to remember
your work.
Task-specific skills still own required metadata, schemas, evidence gathering,
and workflow. This skill shapes the note; it never overrides factual constraints.
Voice
- Write for a human or agent returning later and trying to understand what happened.
- Be clear, direct, warm, and technically honest.
- Prefer concrete observations over generic praise.
- Have a point of view when the evidence supports it. It is fine to call a
change elegant, messy, risky, boring, or satisfying when you explain why.
- Keep personality in service of memory, not performance.
Tell The Story
- Give the note a narrative spine: problem -> approach -> current state and impact.
- Explain why the approach works, how the system or workflow changed, and why
that difference matters.
- Name relevant tradeoffs, sharp edges, useful simplifications, removals, and
intentionally parked work.
- Prefer exact behavior, component names, paths, and commands over phrases such
as "made progress" or "updated the implementation."
- Use substantive prose for context and reasoning. Do not reduce the note to a
wall of bullets or a commit-by-commit changelog.
- Name the durable lesson when one exists — the constraint discovered, the
boundary made explicit, the shortcut future work should avoid. That is the
part that turns a status report into project memory.
- Match depth to the subject. A small remembered fact should remain small.
Anchor The Work
- When the note records repository work, capture where that work lives: the
project or repo, the git branch, and the PR or issue — plus the commit sha
when a specific commit matters.
- Put anchors the note's schema defines in frontmatter; record the rest as
observations, e.g.
- [branch] feat/bm-writing or - [pr] #1123.
- Render GitHub-backed PR, issue, and commit anchors as Markdown links when
their canonical URLs are verified. Keep local or unpushed SHAs as code
instead of constructing links that may not exist.
- Only anchor what is relevant. A remembered fact with no repo context needs no
git anchors at all.
Preserve The Semantic Layer
- Distill durable facts under
## Observations as - [category] fact.
- Record decisions as
[decision] observations, not plain bullets in a separate
Decisions section.
- Put graph edges under
## Relations using - relation_type [[Target Note]].
Never represent a relation as an observation such as [relates_to].
- Add relations when they clarify context; do not manufacture targets merely to
make a note look connected.
Evidence Boundary
- Do not invent intent, impact, verification, decisions, or drama.
- State uncertainty and missing evidence plainly.
- Never claim a test or deployment passed unless it ran or the user supplied the result.
1---
2name: bm-writing
3description: Apply the user-customizable writing standard for Basic Memory notes created or substantially revised by Codex. Use with bm-checkpoint, bm-decide, bm-remember, and other Basic Memory note-writing workflows.
4metadata:
5 source: https://skillmd.com/skills/basicmachines-co-basic-memory/bm-writing
6---
7
8# Write Useful Project Memory
9
10Use this shared standard whenever a Codex Basic Memory skill writes or
11substantially revises a note. This file is intentionally user-customizable: edit
12the voice, emphasis, and preferred structure here to fit how you want to remember
13your work.
14
15Task-specific skills still own required metadata, schemas, evidence gathering,
16and workflow. This skill shapes the note; it never overrides factual constraints.
17
18## Voice
19
20- Write for a human or agent returning later and trying to understand what happened.
21- Be clear, direct, warm, and technically honest.
22- Prefer concrete observations over generic praise.
23- Have a point of view when the evidence supports it. It is fine to call a
24 change elegant, messy, risky, boring, or satisfying when you explain why.
25- Keep personality in service of memory, not performance.
26
27## Tell The Story
28
29- Give the note a narrative spine: problem -> approach -> current state and impact.
30- Explain why the approach works, how the system or workflow changed, and why
31 that difference matters.
32- Name relevant tradeoffs, sharp edges, useful simplifications, removals, and
33 intentionally parked work.
34- Prefer exact behavior, component names, paths, and commands over phrases such
35 as "made progress" or "updated the implementation."
36- Use substantive prose for context and reasoning. Do not reduce the note to a
37 wall of bullets or a commit-by-commit changelog.
38- Name the durable lesson when one exists — the constraint discovered, the
39 boundary made explicit, the shortcut future work should avoid. That is the
40 part that turns a status report into project memory.
41- Match depth to the subject. A small remembered fact should remain small.
42
43## Anchor The Work
44
45- When the note records repository work, capture where that work lives: the
46 project or repo, the git branch, and the PR or issue — plus the commit sha
47 when a specific commit matters.
48- Put anchors the note's schema defines in frontmatter; record the rest as
49 observations, e.g. `- [branch] feat/bm-writing` or `- [pr] #1123`.
50- Render GitHub-backed PR, issue, and commit anchors as Markdown links when
51 their canonical URLs are verified. Keep local or unpushed SHAs as code
52 instead of constructing links that may not exist.
53- Only anchor what is relevant. A remembered fact with no repo context needs no
54 git anchors at all.
55
56## Preserve The Semantic Layer
57
58- Distill durable facts under `## Observations` as `- [category] fact`.
59- Record decisions as `[decision]` observations, not plain bullets in a separate
60 Decisions section.
61- Put graph edges under `## Relations` using `- relation_type [[Target Note]]`.
62 Never represent a relation as an observation such as `[relates_to]`.
63- Add relations when they clarify context; do not manufacture targets merely to
64 make a note look connected.
65
66## Evidence Boundary
67
68- Do not invent intent, impact, verification, decisions, or drama.
69- State uncertainty and missing evidence plainly.
70- Never claim a test or deployment passed unless it ran or the user supplied the result.