This document explains critical practices for maintaining the integrity of the notes system and preventing information loss.
An orphaned note is one that exists in the system but has no links pointing to it from any other page. It is effectively hidden and undiscoverable unless you know its exact key and use notes read <key> directly.
Example: A note created at key envoy/design-spec with valuable architectural information, but no link from the envoy parent page, remains undiscovered even though it contains important documentation.
1. Create a child note but forget to link it: You create project/design but forget to add a link from the project page.
2. Delete a link without reviewing content: You remove a link from the parent page thinking the document is no longer needed, but valuable information was in that child note.
3. Update a parent page and accidentally omit child links: You edit the envoy page but don't preserve links to envoy/design-spec and envoy/design-supplement.
4. Overwrite metadata accidentally: You reset the version number, lose the created date, or remove tags when updating content.
5. Strip important structural information: You remove the title or lose descriptive metadata that provides context.
When editing any note, always preserve:
All links pointing to related documents, especially child pages. These maintain the discoverability and navigation structure of the system.
title — The human-readable document title
version — Must be incremented, never reset or removed
created — Original creation date (ISO format). Never change this.
updated — Set to current date when making changes
tags — Classification tags. Review before removing.
Hierarchical relationships between parent and child documents. Check notes list to see what child keys exist before editing a parent.
Any custom top-level keys specific to the document type (e.g., description, status, author). Review the existing structure before overwriting.
Discoverability: LLMs, tools, and humans rely on navigating from linked pages. Orphaned notes become lost knowledge.
Information Loss: Valuable architectural decisions, design discussions, and domain knowledge can disappear from active use, even if the data technically exists in the database.
Historical Context: Version numbers and timestamps provide chronology. Losing them makes it impossible to understand when decisions were made or how documents evolved.
System Integrity: The notes system depends on explicit links and consistent metadata. Broken relationships indicate gaps in the system structure.
1. Create the child note with notes load -d <child_key> /path/to/file.json
2. IMMEDIATELY read the parent page: notes read <parent_key>
3. Update the parent page to include a link to the child
4. Verify the link resolves correctly
Before you overwrite a page:
1. Read the current content: notes read <key>
2. Review for child links you might accidentally remove
3. Check metadata: version, created, title, tags, etc.
4. Use notes list to check if child notes exist (keys with your page as a prefix)
5. Preserve all existing links when you update
6. Preserve all metadata fields unless you explicitly intend to change them
7. Increment the version number
8. Update the updated field to today's date
Before removing a link:
1. Verify the target still has value2. Check if anyone depends on it3. If deleting, consider archiving instead of removing4. Document why the link was removed
Use notes delete only after:
1. Verifying the note has no value for future reference2. Checking that no links point to it3. Confirming no child notes exist under it4. Optionally backing up the content first
Use the notes list command regularly to audit the system:
1. Run notes list to see all keys
2. For each key, use notes read to check its content
3. Verify that parent-child relationships are properly linked
4. Check that metadata is present and consistent
5. If you find an orphaned note, either link it from a parent or delete it with confidence
On 2026-02-09, two important design documents were created:
- envoy/design-spec (architectural specification)
- envoy/design-supplement (design decisions)
However, the main envoy page was not updated to include links to these notes. They remained orphaned and undiscoverable until explicitly searched for using notes list. This valuable architectural guidance was effectively hidden despite existing in the system.
Lesson: Always link new child notes immediately from their parent pages.
- Create + Link must happen together- Read before you write — always check existing content- Preserve ALL metadata: version, created, title, tags, etc.- Never remove links without reviewing the target- Increment version numbers, never reset them- Never change the 'created' date; update 'updated' instead- Use notes list to audit regularly- Document deletions if you must remove content