Improve Obsidian compatibility: Update YAML frontmatter tag formatting

[bm-claudeai]

Issue: Obsidian YAML Frontmatter Tag Compatibility

Problem

Our current frontmatter logic adds tags using JSON array syntax:

tags: ["tag1", "tag2", "tag3"]

While this is valid YAML, it makes Obsidian unhappy and doesn't follow Obsidian's preferred conventions for YAML frontmatter tags.

Expected Behavior

Obsidian prefers tags in YAML frontmatter to be formatted using one of these standard YAML list formats:

Option 1: YAML List Format (Recommended)

tags:
  - tag1
  - tag2
  - tag3

Option 2: YAML Array Format (Alternative)

tags: [tag1, tag2, tag3]

Note: The unquoted format is preferred as it's cleaner and more aligned with Obsidian community conventions.

Current Impact

• ✅ Tags work functionally in Basic Memory
• ❌ Tags appear with JSON-style quotes in Obsidian
• ❌ May cause visual/parsing issues in Obsidian's property editor
• ❌ Doesn't follow Obsidian community best practices

References

• Obsidian Tags Documentation
• Obsidian Properties Documentation
• Obsidian Forum: YAML frontmatter formatting

Proposed Solution

Update the frontmatter generation in Basic Memory to use the YAML list format:

1. Modify tag serialization in markdown generation
2. Use unquoted strings for tag values (when they don't contain special characters)
3. Use YAML list syntax with dashes instead of JSON array syntax
4. Maintain backward compatibility for reading existing files

Implementation Areas

The changes would likely be needed in:

• src/basic_memory/markdown/ - Markdown generation and frontmatter handling
• src/basic_memory/services/entity_service.py - Entity creation with frontmatter
• Tests to verify the new format works correctly

Acceptance Criteria

• Tags are formatted using YAML list syntax (- tag) instead of JSON array syntax (["tag"])
• Obsidian can properly parse and display the tags
• Basic Memory can still read existing files with old format
• All tests pass with new format
• Documentation updated to reflect the change

Priority

Medium - Improves compatibility with a major tool in the knowledge management ecosystem, but doesn't break core functionality.

Labels

• enhancement
• compatibility
• obsidian
• yaml
• frontmatter

[bm-claudeai]

Additional Information from Official Obsidian Documentation

Based on the official Obsidian documentation, here are the key requirements for YAML frontmatter tag formatting:

Obsidian's Official Tag Format in YAML

From Obsidian Properties Documentation:

✅ Correct Format:

---
tags:
  - recipe
  - cooking
---

Key Quote from Documentation:

"Tags in YAML should always be formatted as a list"

Current Basic Memory Format Issues

Our current format:

tags: ["tag1", "tag2", "tag3"]

Problems:

1. ❌ Uses JSON array syntax instead of YAML list syntax
2. ❌ Uses quoted strings (unnecessary for simple tags)
3. ❌ Doesn't follow Obsidian's "always formatted as a list" requirement

Obsidian Tag Rules

From Obsidian Tags Documentation:

Allowed characters in tags:

• Alphabetical letters
• Numbers
• Underscore (_)
• Hyphen (-)
• Forward slash (/) for nested tags

Important notes:

• Tags must contain at least one non-numerical character
• Tags are case-insensitive
• Tags can't contain blank spaces
• Nested tags use forward slashes: #inbox/to-read

Implementation Considerations

1. Simple tags (no special characters): Can be unquoted
2. Tags with special characters: May need quotes
3. Nested tags: Should work with the list format
4. Backward compatibility: Need to handle both old and new formats when reading

This confirms that the YAML list format is not just preferred but is the official recommended format according to Obsidian's documentation.

[egoes]

Hi, I am still experiencing this same issue in Obsidian with Basic Memory version: 0.14.2
Could there be a regression or has this fix not been released yet?

Sorry, I’m still a bit clumsy in GitHub, I see the fix and commit here, but don’t see which release it is attached to!
Still learning… :) Thanks

Expected Behavior

When passing tags=["system", "overview", "reference"] to write_note, the YAML frontmatter should be:

tags:
- system
- overview
- reference

Actual Behavior

When passing tags=["system", "overview", "reference"] as a string (which happens when the AI assistant incorrectly stringifies the array), the YAML frontmatter becomes:

tags:
- '["system"'
- '"overview"'
- '"reference"]'

Environment

• Basic Memory version: 0.14.2
• Installation method: Homebrew
• Operating System: macOS

---

Written with assistance from Claude (Anthropic).

[ottsch]

Exactly same behavior here

[phernandez]

@claude it looks like we tried to change this but I can see that tags are still being rendered as a list. why did the change in #194 not fix the issue?

Lets update the code and write a test to verify tags are formatted properly.

Expected Behavior

When passing tags=["system", "overview", "reference"] to write_note, the YAML frontmatter should be:

tags:
 - system
 - overview
 - reference

Actual Behavior

When passing tags=["system", "overview", "reference"] as a string (which happens when the AI assistant incorrectly stringifies the array), the YAML frontmatter becomes:

tags:
 - '["system"'
 - '"overview"' 
 - '"reference"]'

[claude]

Claude finished @phernandez's task —— View job • claude/issue-132-20250824-1414 • Create PR ➔

---

I've successfully implemented a fix for the YAML frontmatter tag formatting issue that provides proper Obsidian compatibility.

Todo List:

• Analyze current codebase to understand frontmatter handling
• Examine PR Fix YAML tag serialization in frontmatter #194 to understand what was attempted
• Identify the root cause of the formatting issue
• Update tag serialization to use proper YAML list format
• Handle both array and stringified array inputs correctly
• Write comprehensive tests to verify proper formatting
• Run tests and linting
• Commit and push changes

Solution Implemented:

Root Cause: The frontmatter library uses PyYAML's default serialization which outputs JSON-style arrays ["tag1", "tag2"] instead of YAML list format.

Changes Made:

1. Created Custom YAML Serializer (src/basic_memory/file_utils.py):

   • Added dumps_frontmatter_obsidian_compatible() function
   • Uses custom YAML dumper that forces default_flow_style=False for lists
   • Produces proper YAML format:

     tags:
     - system
     - overview
     - reference

2. Updated All frontmatter.dumps() Calls:

   • src/basic_memory/services/entity_service.py (2 locations)
   • src/basic_memory/markdown/markdown_processor.py (1 location)

3. Enhanced parse_tags() Function (src/basic_memory/utils.py):

   • Now handles stringified JSON arrays like '["system", "overview", "reference"]'
   • Falls back to comma-separated parsing for invalid JSON
   • Prevents the problematic format that was causing issues

4. Comprehensive Test Suite:

   • Extended tests/utils/test_parse_tags.py with JSON array test cases
   • New tests/utils/test_frontmatter_obsidian_compatible.py for YAML formatting
   • New tests/mcp/test_obsidian_yaml_formatting.py for integration testing

Expected Behavior:

✅ Tags now format as YAML lists: tags:\n- system\n- overview\n- reference
✅ Stringified JSON arrays are parsed correctly
✅ Obsidian can properly display and edit the tags
✅ All existing functionality preserved

--- | Branch: claude/issue-132-20250824-1414