This document describes the conventions used in this notes system. It supplements the base JSONHTL format specification. If you are an LLM or tool, check the version number above — if you already know version 3, you do not need to re-read this document.
All documents use JSONHTL. The base format defines three block types (para, heading, codeblock) and three inline types (plain strings, link, code). String values may also contain markdown inline formatting. See Format Details for the full rules.
Links connect documents in this store. A link may have an href that does not yet point to an existing node — this is permitted. See Link Conventions for resolution rules.
IMPORTANT: Always add links when creating child notes. See Avoiding Orphaned Notes and Information Loss for critical best practices.
Essential workflow guidance: See Workflow - Creating and Updating Notes for the correct order of operations when creating linked notes. DO NOT upload partial or incomplete documents.
Keys are plain strings. We use / as a logical separator to organise related documents, e.g. README/format. The server does not treat / specially — this is a convention only. See Key Conventions for details.
Documents should be brief. Prefer many small, focused nodes over fewer large ones. This supports fine-grained recall — an LLM or tool can load only the specific information it needs without consuming unnecessary context window.
The base JSONHTL spec allows any top-level keys. Convention documents define what additional keys mean. See Metadata Conventions for keys like version, created, and tags.
The primary CLI tool is notes_client.py (symlinked as notes). It supports read, write, load, list, and delete. See Tools Reference for full usage.
- Use notes list to discover and audit all notes in the system- Always link child notes from their parent pages- Preserve existing links when editing pages- Back up before deleting notes- Use notes load -d to load files and clean up temp files atomically
See Avoiding Orphaned Notes and Information Loss for critical guidance on maintaining system integrity.
Runnable documents (executable codeblocks) are planned. See Runnable Document Conventions for the current placeholder.