fix: Update YAML frontmatter tag formatting for Obsidian compatibility (#280)

Signed-off-by: Drew Cain <groksrc@users.noreply.github.com>
Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Paul Hernandez <phernandez@users.noreply.github.com>
Co-authored-by: Paul Hernandez <60959+phernandez@users.noreply.github.com>

src/basic_memory/file_utils.py

@@ -6,6 +6,7 @@ import re
 from typing import Any, Dict, Union
 
 import yaml
+import frontmatter
 from loguru import logger
 
 from basic_memory.utils import FilePath
@@ -236,6 +237,50 @@ async def update_frontmatter(path: FilePath, updates: Dict[str, Any]) -> str:
         raise FileError(f"Failed to update frontmatter: {e}")
 
 
+def dump_frontmatter(post: frontmatter.Post) -> str:
+    """
+    Serialize frontmatter.Post to markdown with Obsidian-compatible YAML format.
+    
+    This function ensures that tags are formatted as YAML lists instead of JSON arrays:
+    
+    Good (Obsidian compatible):
+    ---
+    tags:
+    - system
+    - overview  
+    - reference
+    ---
+    
+    Bad (current behavior):
+    ---
+    tags: ["system", "overview", "reference"]
+    ---
+    
+    Args:
+        post: frontmatter.Post object to serialize
+        
+    Returns:
+        String containing markdown with properly formatted YAML frontmatter
+    """    
+    if not post.metadata:
+        # No frontmatter, just return content
+        return post.content
+        
+    # Serialize YAML with block style for lists
+    yaml_str = yaml.dump(
+        post.metadata,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False
+    )
+    
+    # Construct the final markdown with frontmatter
+    if post.content:
+        return f"---\n{yaml_str}---\n\n{post.content}"
+    else:
+        return f"---\n{yaml_str}---\n"
+
+
 def sanitize_for_filename(text: str, replacement: str = "-") -> str:
     """
     Sanitize string to be safe for use as a note title
@@ -252,3 +297,4 @@ def sanitize_for_filename(text: str, replacement: str = "-") -> str:
     text = re.sub(f"{re.escape(replacement)}+", replacement, text)
 
     return text.strip(replacement)
+

src/basic_memory/markdown/markdown_processor.py

@@ -7,6 +7,7 @@ from frontmatter import Post
 from loguru import logger
 
 from basic_memory import file_utils
+from basic_memory.file_utils import dump_frontmatter
 from basic_memory.markdown.entity_parser import EntityParser
 from basic_memory.markdown.schemas import EntityMarkdown, Observation, Relation
 
@@ -115,7 +116,7 @@ class MarkdownProcessor:
 
         # Create Post object for frontmatter
         post = Post(content, **frontmatter_dict)
-        final_content = frontmatter.dumps(post, sort_keys=False)
+        final_content = dump_frontmatter(post)
 
         logger.debug(f"writing file {path} with content:\n{final_content}")
 

src/basic_memory/services/entity_service.py

@@ -9,7 +9,7 @@ from loguru import logger
 from sqlalchemy.exc import IntegrityError
 
 from basic_memory.config import ProjectConfig, BasicMemoryConfig
-from basic_memory.file_utils import has_frontmatter, parse_frontmatter, remove_frontmatter
+from basic_memory.file_utils import has_frontmatter, parse_frontmatter, remove_frontmatter, dump_frontmatter
 from basic_memory.markdown import EntityMarkdown
 from basic_memory.markdown.entity_parser import EntityParser
 from basic_memory.markdown.utils import entity_model_from_markdown, schema_to_markdown
@@ -196,7 +196,7 @@ class EntityService(BaseService[EntityModel]):
         post = await schema_to_markdown(schema)
 
         # write file
-        final_content = frontmatter.dumps(post, sort_keys=False)
+        final_content = dump_frontmatter(post)
         checksum = await self.file_service.write_file(file_path, final_content)
 
         # parse entity from file
@@ -273,7 +273,7 @@ class EntityService(BaseService[EntityModel]):
         merged_post = frontmatter.Post(post.content, **existing_markdown.frontmatter.metadata)
 
         # write file
-        final_content = frontmatter.dumps(merged_post, sort_keys=False)
+        final_content = dump_frontmatter(merged_post)
         checksum = await self.file_service.write_file(file_path, final_content)
 
         # parse entity from file

src/basic_memory/utils.py

@@ -219,8 +219,21 @@ def parse_tags(tags: Union[List[str], str, None]) -> List[str]:
         # First strip whitespace, then strip leading '#' characters to prevent accumulation
         return [tag.strip().lstrip("#") for tag in tags if tag and tag.strip()]
 
-    # Process comma-separated string of tags
+    # Process string input
     if isinstance(tags, str):
+        # Check if it's a JSON array string (common issue from AI assistants)
+        import json
+        if tags.strip().startswith('[') and tags.strip().endswith(']'):
+            try:
+                # Try to parse as JSON array
+                parsed_json = json.loads(tags)
+                if isinstance(parsed_json, list):
+                    # Recursively parse the JSON array as a list
+                    return parse_tags(parsed_json)
+            except json.JSONDecodeError:
+                # Not valid JSON, fall through to comma-separated parsing
+                pass
+        
         # Split by comma, strip whitespace, then strip leading '#' characters
         return [tag.strip().lstrip("#") for tag in tags.split(",") if tag and tag.strip()]