fix(sync): preserve frontmatterless markdown sync

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

Author: phernandez

src/basic_memory/indexing/batch_indexer.py

@@ -562,8 +562,16 @@ async def _reconcile_persisted_permalink(
         prepared: _PreparedMarkdownFile,
         entity: Entity,
     ) -> _PreparedMarkdownFile:
+        # Trigger: the source file started without frontmatter and sync is configured
+        #          to leave frontmatterless files alone.
+        # Why: upsert may still assign a DB permalink even when disk content should stay untouched.
+        # Outcome: skip reconciliation writes that would silently inject frontmatter.
         if (
             self.app_config.disable_permalinks
+            or (
+                not prepared.file_contains_frontmatter
+                and not self.app_config.ensure_frontmatter_on_sync
+            )
             or entity.permalink is None
             or entity.permalink == prepared.markdown.frontmatter.permalink
         ):

src/basic_memory/sync/sync_service.py

@@ -18,7 +18,7 @@
 from basic_memory import telemetry
 from basic_memory import db
 from basic_memory.config import BasicMemoryConfig, ConfigManager
-from basic_memory.file_utils import compute_checksum, remove_frontmatter
+from basic_memory.file_utils import ParseError, compute_checksum, remove_frontmatter
 from basic_memory.indexing import (
     BatchIndexer,
     IndexFileMetadata,
@@ -1126,9 +1126,18 @@ async def sync_one_markdown_file(
             raise ValueError(f"Failed to update markdown entity metadata for {path}")
 
         if index_search:
+            # Trigger: markdown may start with '---' as a thematic break or malformed
+            #          frontmatter that the parser already treated as plain content.
+            # Why: one-file sync should not fail after the entity upsert just because
+            #      strict frontmatter stripping rejects that exact text shape.
+            # Outcome: fall back to indexing the raw markdown content for these cases.
+            try:
+                search_content = remove_frontmatter(final_markdown_content)
+            except ParseError:
+                search_content = final_markdown_content
             await self.search_service.index_entity_data(
                 updated_entity,
-                content=remove_frontmatter(final_markdown_content),
+                content=search_content,
             )
 
         logger.debug(

tests/indexing/test_batch_indexer.py

@@ -677,3 +677,61 @@ async def test_batch_indexer_strips_frontmatter_from_search_content_when_body_is
     args, kwargs = await_args
     assert args[0].id == entity.id
     assert kwargs["content"] == remove_frontmatter(persisted_content)
+
+
+@pytest.mark.asyncio
+async def test_batch_indexer_does_not_inject_frontmatter_when_sync_enforcement_is_disabled(
+    app_config,
+    entity_service,
+    entity_repository,
+    relation_repository,
+    search_service,
+    file_service,
+    project_config,
+    monkeypatch,
+):
+    app_config.ensure_frontmatter_on_sync = False
+
+    created = await entity_service.create_entity_with_content(
+        EntitySchema(
+            title="Frontmatterless",
+            directory="notes",
+            content="# Frontmatterless\n\nOriginal content.\n",
+        )
+    )
+    path = created.entity.file_path
+    assert path is not None
+    existing_permalink = created.entity.permalink
+    assert existing_permalink is not None
+
+    original_content = "# Frontmatterless\n\nBody content.\n"
+    await _create_file(project_config.home / path, original_content)
+
+    original_writer = file_service.update_frontmatter_with_result
+    frontmatter_writer = AsyncMock(side_effect=original_writer)
+    monkeypatch.setattr(file_service, "update_frontmatter_with_result", frontmatter_writer)
+
+    batch_indexer = _make_batch_indexer(
+        app_config,
+        entity_service,
+        entity_repository,
+        relation_repository,
+        search_service,
+        file_service,
+    )
+
+    indexed = await batch_indexer.index_markdown_file(
+        await _load_input(file_service, path),
+        index_search=False,
+    )
+
+    # Trigger: Windows persists CRLF for text files even when the test literal uses LF.
+    # Why: this assertion cares about preserving a frontmatterless file, not about newline style.
+    # Outcome: compare against the exact content stored on disk after sync.
+    persisted_content = (project_config.home / path).read_bytes().decode("utf-8")
+    entity = await entity_repository.get_by_file_path(path)
+    assert entity is not None
+    assert entity.permalink == existing_permalink
+    assert frontmatter_writer.await_count == 0
+    assert indexed.markdown_content == persisted_content
+    assert await file_service.read_file_content(path) == persisted_content

tests/sync/test_sync_one_markdown_file.py

@@ -146,9 +146,14 @@ async def test_sync_one_markdown_file_returns_original_content_when_no_rewrite_n
 
     result = await sync_service.sync_one_markdown_file("notes/no-rewrite.md", index_search=False)
 
+    # Trigger: Windows persists CRLF for text files even when the test literal uses LF.
+    # Why: this assertion cares about "no rewrite happened", not about pinning one newline style.
+    # Outcome: compare against the exact markdown bytes stored on disk.
+    persisted_content = file_path.read_bytes().decode("utf-8")
+
     assert frontmatter_writer.await_count == 0
-    assert result.markdown_content == original_content
-    assert file_path.read_text(encoding="utf-8") == original_content
+    assert result.markdown_content == persisted_content
+    assert file_path.read_text(encoding="utf-8") == persisted_content
     assert result.checksum == await sync_service.file_service.compute_checksum(
         "notes/no-rewrite.md"
     )
@@ -216,3 +221,35 @@ async def test_sync_markdown_file_remains_tuple_compatible(sync_service, test_pr
     assert entity.file_path == "notes/compat.md"
     assert entity.permalink == f"{test_project.name}/notes/compat"
     assert checksum == await sync_service.file_service.compute_checksum("notes/compat.md")
+
+
+@pytest.mark.asyncio
+async def test_sync_one_markdown_file_indexes_thematic_break_content_without_frontmatter(
+    sync_service,
+    test_project,
+    app_config,
+    monkeypatch,
+):
+    """Leading thematic-break markdown should index as raw content when frontmatter is absent."""
+    app_config.ensure_frontmatter_on_sync = False
+
+    original_content = "---\nBody content after a thematic break.\n"
+    file_path = _write_markdown(
+        Path(test_project.path),
+        "notes/thematic-break.md",
+        original_content,
+    )
+
+    index_entity_data = AsyncMock()
+    monkeypatch.setattr(sync_service.search_service, "index_entity_data", index_entity_data)
+
+    result = await sync_service.sync_one_markdown_file("notes/thematic-break.md")
+
+    persisted_content = file_path.read_bytes().decode("utf-8")
+
+    assert result.markdown_content == persisted_content
+    assert file_path.read_text(encoding="utf-8") == persisted_content
+    index_entity_data.assert_awaited_once_with(
+        result.entity,
+        content=persisted_content,
+    )