docs(core): document relation grammar

Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+### Breaking Changes
+
+- Relation parsing no longer treats unquoted multi-word text before a wikilink as a
+  custom relation type. Use single-token relation types like `relates_to [[Target]]`,
+  or quote multi-word relation types like `"relates to" [[Target]]` or
+  `'relates to' [[Target]]`.
+  - Bare list wikilinks like `- [[Target]]` now index as `links_to`.
+  - Prose list items like `- some other thing [[Target]]` now index as `links_to`.
+  - To preserve existing multi-word relation types on re-sync, quote them before upgrading.
+
 ## v0.20.3 (2026-03-26)
 
 ### Bug Fixes

README.md

@@ -285,8 +285,13 @@ Markdown format:
 
 ```markdown
 - relation_type [[WikiLink]] (optional context)
+- "multi word relation type" [[WikiLink]] (optional context)
+- 'multi word relation type' [[WikiLink]] (optional context)
 ```
 
+Unquoted relation types are single tokens. Use quotes when the relation type contains
+spaces. Bare wikilinks and prose with wikilinks are stored as `links_to` relations.
+
 Examples of relations:
 
 ```markdown
@@ -295,6 +300,8 @@ Examples of relations:
 - contrasts_with [[Tea Brewing Methods]]
 - requires [[Burr Grinder]]
 - improves_with [[Fresh Beans]]
+- "pairs well with" [[Chocolate Desserts]]
+- 'documented in' [[Coffee Journal]]
 - relates_to [[Morning Routine]]
 - inspired_by [[Japanese Coffee Culture]]
 - documented_in [[Coffee Journal]]

docs/NOTE-FORMAT.md

@@ -106,7 +106,7 @@ The parser excludes these list item patterns:
 |---------|---------|--------|
 | Checkboxes | `- [ ] Todo item`, `- [x] Done`, `- [-] Cancelled` | Task list syntax |
 | Markdown links | `- [text](url)` | URL link syntax |
-| Bare wiki links | `- [[Target]]` | Treated as a relation instead |
+| Bare wiki links | `- [[Target]]` | Treated as a `links_to` relation instead |
 
 A list item with `#tags` but no `[category]` is still parsed — the tags are extracted and the category defaults to `Note`.
 
@@ -116,47 +116,65 @@ Relations connect documents to form the knowledge graph. There are two kinds.
 
 ### Explicit Relations
 
-Written as list items with a relation type and a `[[wiki link]]` target.
+Written as list items with a relation type and a `[[wiki link]]` target. Unquoted
+relation types are single tokens. Quote relation types that contain spaces.
 
 **Syntax:**
 
 ```
 - relation_type [[Target Entity]] (context)
+- "multi word relation type" [[Target Entity]] (context)
+- 'multi word relation type' [[Target Entity]] (context)
 ```
 
 | Part | Required | Description |
 |------|----------|-------------|
-| `relation_type` | No | Text before `[[`. Defaults to `relates_to` if omitted. |
+| `relation_type` | Yes | Single unquoted token before `[[`, or quoted text for multi-word labels. |
 | `[[Target]]` | Yes | Wiki link to the target entity. Matched by title or permalink. |
 | `(context)` | No | Parenthesized text after `]]`. Supporting details. |
 
 ### Examples
 
+Explicit relations:
+
 ```markdown
 - implements [[Search Design]]
 - depends_on [[Database Schema]]
 - works_at [[Y Combinator]] (co-founder)
+- "based on" [[Customer Interview]]
+- 'in response to' [[Incident Review]]
+```
+
+Bare wiki links and prose list items create implicit `links_to` relations:
+
+```markdown
 - [[Some Entity]]
+- some other thing [[Some Entity]]
 ```
 
-The last example — a bare `[[wiki link]]` in a list item — gets relation type `relates_to`.
+Both examples above create `links_to [[Some Entity]]`. Use quotes when the words before
+`[[` are meant to be a multi-word relation type.
 
 Common relation types:
 - `implements`, `depends_on`, `relates_to`, `inspired_by`
 - `extends`, `part_of`, `contains`, `pairs_with`
 - `works_at`, `authored`, `collaborated_with`
 
-Any text works as a relation type. These are conventions, not a fixed set.
+Any single-token text or quoted text works as a relation type. These are conventions,
+not a fixed set.
 
 ### Inline References
 
-Wiki links appearing in regular prose (not as list items) create implicit `links_to` relations.
+Wiki links appearing in regular prose create implicit `links_to` relations. This includes
+list items that do not match the explicit relation grammar above.
 
 ```markdown
 This builds on [[Core Design]] and uses [[Utility Functions]].
+- We should revisit [[Search Design]] after the API changes.
 ```
 
-This creates two relations: `links_to [[Core Design]]` and `links_to [[Utility Functions]]`.
+This creates three relations: `links_to [[Core Design]]`, `links_to [[Utility Functions]]`,
+and `links_to [[Search Design]]`.
 
 ### Forward References
 

src/basic_memory/mcp/tools/write_note.py

@@ -66,10 +66,14 @@ async def write_note(
 
     Relations format:
         - Explicit: `- relation_type [[Entity]] (optional context)`
-        - Inline: Any `[[Entity]]` reference creates a relation
+        - Quoted: `- "multi word relation type" [[Entity]] (optional context)`
+        - Quoted: `- 'multi word relation type' [[Entity]] (optional context)`
+        - Inline: Any other `[[Entity]]` reference creates a `links_to` relation
 
         Examples:
         `- depends_on [[Content Parser]] (Need for semantic extraction)`
+        `- "based on" [[Design Notes]]`
+        `- 'in response to' [[Incident Review]]`
         `- implements [[Search Spec]] (Initial implementation)`
         `- This feature extends [[Base Design]] and uses [[Core Utils]]`
 

tests/mcp/test_tool_write_note.py

@@ -7,6 +7,7 @@
 
 from basic_memory import config as config_module
 from basic_memory.mcp.tools import write_note, read_note, delete_note
+from basic_memory.repository.relation_repository import RelationRepository
 from basic_memory.utils import normalize_newlines
 
 
@@ -309,7 +310,7 @@ async def test_write_note_with_tag_array_from_bug_report(app, test_project):
 
 
 @pytest.mark.asyncio
-async def test_write_note_verbose(app, test_project):
+async def test_write_note_verbose(app, test_project, engine_factory):
     """Test creating a new note.
 
     Should:
@@ -326,7 +327,7 @@ async def test_write_note_verbose(app, test_project):
 # Test\nThis is a test note
 
 - [note] First observation
-- relates to [[Knowledge]]
+- "relates to" [[Knowledge]]
 
 """,
         tags=["test", "documentation"],
@@ -343,6 +344,11 @@ async def test_write_note_verbose(app, test_project):
     assert "- test, documentation" in result
     assert f"[Session: Using project '{test_project.name}']" in result
 
+    _, session_maker = engine_factory
+    relation_repository = RelationRepository(session_maker, project_id=test_project.id)
+    relations = await relation_repository.find_by_type("relates to")
+    assert any(relation.to_name == "Knowledge" for relation in relations)
+
 
 @pytest.mark.asyncio
 async def test_write_note_preserves_custom_metadata(app, project_config, test_project):