[BUG] YAML frontmatter parsing fails with unquoted colons in title

[phernandez]

Issue

Users are experiencing YAML parsing errors when creating notes with colons in the title field. The YAML parser interprets unquoted colons as key-value separators, causing the frontmatter to fail validation.

Error Examples

Example 1: Title with colon

---
title: L2 Governance Core (Split: Core)
---

Error:

Invalid YAML in frontmatter: mapping values are not allowed here
  in "<unicode string>", line 2, column 33:
    title: L2 Governance Core (Split: Core)
                                    ^

Example 2: Title starting with word + colon

---
title: Governance: Rootkeeper Manifest-Diff Prompt
---

Error:

Invalid YAML in frontmatter: mapping values are not allowed here
  in "<unicode string>", line 2, column 18:
    title: Governance: Rootkeeper Manifest-Diff Prompt
                     ^

Affected Tenants

• Tenant: 78feaf4d-433e-b6a6-e855-b5c49d7c1975
• Occurrences: 4 in past 24 hours
• Timestamps:
  • 2025-10-28 12:00:00 UTC
  • 2025-10-28 11:58:27 UTC
  • 2025-10-28 05:25:39 UTC

Trace IDs

• 019a2ab07c0b13c50f89e262c1f471cb
• 019a2aaf0f6ba0a9cf7caa4421c13d67
• 019a294773f4b629ca15345218d6674a

Root Cause

YAML specification requires values containing special characters (including colons) to be quoted. When the title contains a colon, the YAML parser interprets it as a key-value separator.

Proposed Solutions

Option 1: Auto-quote title values (Recommended)

Automatically quote the title field when writing frontmatter:

# In file_utils.py or wherever frontmatter is written
frontmatter_dict['title'] = title  # Current
# Change to:
frontmatter_dict['title'] = f'"{title}"' if ':' in title else title

Option 2: Validate and reject

Reject titles containing colons and provide clear error message to user.

Option 3: Escape colons

Escape colons in title values before writing YAML.

Option 4: Always quote all string values

Quote all string values in frontmatter regardless of content (safest but verbose):

---
title: "My Title"
permalink: "my-permalink"
---

User Impact

• Users cannot create notes with colons in titles
• Error messages are technical and confusing for non-technical users
• Workaround: Manually edit YAML to add quotes or avoid colons

Priority

Medium - Affects user experience but has workaround. Not data loss issue.

Files to Modify

• apps/api/src/basic_memory/file_utils.py - YAML frontmatter writing logic
• Add test cases for titles with special characters

[claude]

Claude finished @phernandez's task —— View job • claude/issue-408-20251101-1947 • Create PR ➔

---

Issue #408 - Fixed

Task List:

• Triage and label the issue (added "bug" label)
• Search for duplicate issues (none found)
• Locate frontmatter writing logic in codebase
• Implement fix: Auto-quote string values in YAML frontmatter
• Add test cases for titles with special characters
• Commit and push changes
• Provide PR creation link

Analysis

The issue was in the dump_frontmatter() function in src/basic_memory/file_utils.py. The function used yaml.dump() without proper string quoting, which caused YAML parser errors when string values contained colons or other special characters.

Implementation

Implemented a custom YAML dumper that always quotes string values to handle special characters safely. This follows Option 4 from the issue (always quote all string values) as it's the safest approach and ensures full Obsidian compatibility.

Changes made:

1. Modified dump_frontmatter() in src/basic_memory/file_utils.py:

   • Created custom QuotedDumper class extending yaml.SafeDumper
   • Added quoted_string_representer() that uses double-quoted style for all strings
   • This ensures colons, special characters, etc. are properly escaped
   • Updated docstring with examples and explanation

2. Added 6 comprehensive test cases in tests/utils/test_frontmatter_obsidian_compatible.py:

   • test_title_with_colon() - Tests the exact error case "L2 Governance Core (Split: Core)"
   • test_title_starting_with_word_and_colon() - Tests "Governance: Rootkeeper Manifest-Diff Prompt"
   • test_multiple_colons_in_title() - Tests multiple colons in one string
   • test_other_special_characters_in_title() - Tests @, #, &, *, [], {}, |, >
   • test_all_string_values_quoted() - Verifies all string fields are quoted, not just titles

All tests include round-trip verification to ensure the YAML can be parsed back correctly.

Solution Benefits

• ✅ Prevents YAML parsing errors for titles with colons
• ✅ Handles all YAML special characters safely
• ✅ Maintains Obsidian compatibility
• ✅ No user-facing changes required
• ✅ Comprehensive test coverage

The CI pipeline will verify all tests pass. The fix is backward compatible - existing notes will continue to work, and new notes with special characters will now be properly handled.

---

| Branch: claude/issue-408-20251101-1947