Skip to content

Commit 82375b6

Browse files
committed
docs: add write_note safety warnings to memory-notes and memory-reflect skills
write_note silently overwrites existing notes. Agents need clear guidance to use edit_note for files that accumulate content (daily notes, MEMORY.md, logs). This prevents accidental data loss. Refs: basicmachines-co/basic-memory#625
1 parent 56acb8d commit 82375b6

File tree

2 files changed

+40
-0
lines changed

2 files changed

+40
-0
lines changed

skills/memory-notes/SKILL.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,3 +248,28 @@ edit_note(
248248
6. **Link related concepts.** The value of a knowledge graph compounds with connections. A note with zero relations is an island — useful, but not as powerful as a connected one.
249249

250250
7. **Let the graph grow naturally.** Don't try to design a perfect taxonomy upfront. Write notes as you work, add relations as connections emerge, and periodically use `/reflect` or `/defrag` to consolidate.
251+
252+
## ⚠️ write_note vs edit_note — Avoiding Data Loss
253+
254+
**`write_note` is destructive.** If a note with the same title already exists, `write_note` silently replaces it. This will destroy accumulated content in daily notes, logs, or any file that grows over time.
255+
256+
### Rules
257+
258+
- **New notes**: Use `write_note` — it creates the file and frontmatter correctly.
259+
- **Existing notes**: Use `edit_note` — it modifies without replacing.
260+
- `operation: "append"` — add content to the end
261+
- `operation: "prepend"` — add content to the beginning
262+
- `operation: "find_replace"` — surgical text replacement
263+
- `operation: "replace_section"` — replace a specific heading section
264+
265+
### Common Mistake
266+
267+
```
268+
# ❌ WRONG — destroys existing daily note content
269+
write_note(title="2026-02-26", folder="memory", content="## New Section\n...")
270+
271+
# ✅ RIGHT — appends to existing daily note
272+
edit_note(identifier="2026-02-26", operation="append", content="\n## New Section\n...")
273+
```
274+
275+
**When in doubt, use `edit_note`.** It's always safe. `write_note` is only safe when you're certain the note doesn't exist yet or you intentionally want to replace it entirely.

skills/memory-reflect/SKILL.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,3 +61,18 @@ Append a brief entry to today's daily note:
6161
- **Flag uncertainty.** If something seems important but you're not sure, add it with a note like "(needs confirmation)" rather than skipping it entirely.
6262
- **Restructure over time.** If MEMORY.md is a chronological dump, restructure it into topical sections during reflection. Curated knowledge > raw logs.
6363
- **Check for filesystem issues.** Look for recursive nesting (memory/memory/memory/...), orphaned files, or bloat while gathering material.
64+
65+
## ⚠️ Safe Writing Pattern
66+
67+
**Never use `write_note` on daily notes or MEMORY.md.** These files accumulate content throughout the day. `write_note` replaces the entire file — use `edit_note` instead:
68+
69+
```
70+
# ✅ Update a section in MEMORY.md
71+
edit_note(identifier="MEMORY", operation="replace_section", section="About Me", content="...")
72+
73+
# ✅ Append reflection log to today's daily note
74+
edit_note(identifier="2026-02-26", operation="append", content="\n## Reflection (22:00)\n...")
75+
76+
# ❌ NEVER do this — destroys the existing file
77+
write_note(title="2026-02-26", folder="memory", content="...")
78+
```

0 commit comments

Comments
 (0)