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