fix(api): honor ignore rules in sync-file and fail fast in disk recovery

Address BM Bossbot review findings on the #581 recovery path:

- The sync-file endpoint went straight from boundary/markdown checks to
  sync_one_markdown_file, bypassing the ignore filtering that scan and watch
  flows apply before indexing. Hidden files, .bmignore matches, and project
  .gitignore matches could be indexed and made searchable (also indirectly
  via edit_note disk recovery). The canonical path is now checked against
  the same should_ignore_path() rules and rejected with 400. Regression
  tests cover hidden, .gitignore-ignored, and .bmignore-ignored files.
- edit_note disk recovery treated every sync-file ToolError as a harmless
  non-recovery case, masking auth/server/transport failures as not-found
  and letting append/prepend continue into auto-create. Only expected
  400/404 candidate rejections are suppressed now; anything else propagates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

Author: phernandez

src/basic_memory/api/v2/routers/knowledge_router.py

@@ -17,6 +17,7 @@
 from loguru import logger
 
 import logfire
+from basic_memory.ignore_utils import load_gitignore_patterns, should_ignore_path
 from basic_memory.deps import (
     EntityServiceV2ExternalDep,
     SearchServiceV2ExternalDep,
@@ -300,8 +301,8 @@ async def sync_file(
 
     Raises:
         HTTPException: 400 if the path escapes the project root, contains
-            non-normalized segments, or is not markdown, 404 if the file does
-            not exist on disk
+            non-normalized segments, matches the project ignore rules, or is
+            not markdown, 404 if the file does not exist on disk
     """
     with logfire.span(
         "api.request.knowledge.sync_file",
@@ -336,6 +337,20 @@ async def sync_file(
             raise HTTPException(
                 status_code=404, detail=f"File not found on disk: '{data.file_path}'"
             )
+        # Trigger: the canonical path matches the .bmignore / project .gitignore rules
+        # Why: scan and watch flows filter ignored files before they ever reach the
+        #      indexer; indexing one here would bypass the ignored-file contract and
+        #      make hidden or gitignored content searchable
+        # Outcome: the same should_ignore_path() rules apply to single-file sync
+        ignore_patterns = load_gitignore_patterns(project_config.home)
+        if should_ignore_path(
+            project_config.home / file_path, project_config.home, ignore_patterns
+        ):
+            raise HTTPException(
+                status_code=400,
+                detail=f"File path '{data.file_path}' matches Basic Memory ignore rules "
+                "(.bmignore or project .gitignore) and cannot be indexed",
+            )
         if not sync_service.file_service.is_markdown(file_path):
             raise HTTPException(
                 status_code=400,

src/basic_memory/mcp/tools/edit_note.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING, Annotated, Optional, Literal
 
 import logfire
+from httpx import HTTPStatusError
 from loguru import logger
 from fastmcp import Context
 from mcp.server.fastmcp.exceptions import ToolError
@@ -73,9 +74,20 @@ async def _resolve_after_disk_recovery(
     try:
         await knowledge_client.sync_file(candidate)
     except ToolError as sync_error:
-        # Trigger: server rejected the candidate path (missing file, traversal, non-markdown)
-        # Why: only identifiers that plausibly map to a real file qualify for recovery
-        # Outcome: caller falls through to its existing not-found behavior
+        # Trigger: the sync-file request failed
+        # Why: 400/404 are the expected "nothing to recover" rejections (missing file,
+        #      traversal, ignored path, non-markdown); anything else — auth, server,
+        #      transport-level failures — is a real error that must not be masked as
+        #      a not-found miss
+        # Outcome: expected rejections fall through to the caller's existing
+        #      not-found behavior; unexpected failures propagate
+        cause = sync_error.__cause__
+        candidate_rejected = isinstance(cause, HTTPStatusError) and cause.response.status_code in (
+            400,
+            404,
+        )
+        if not candidate_rejected:
+            raise
         logger.debug(f"edit_note disk recovery skipped for '{candidate}': {sync_error}")
         return None
 

tests/api/v2/test_knowledge_router.py

@@ -7,6 +7,7 @@
 import pytest
 from httpx import AsyncClient
 
+from basic_memory.ignore_utils import get_bmignore_path
 from basic_memory.models import Entity as EntityModel, Project
 from basic_memory.repository.entity_repository import EntityRepository
 from basic_memory.repository.project_repository import ProjectRepository
@@ -1120,6 +1121,62 @@ async def test_sync_file_path_through_file_returns_404(
     assert "File not found on disk" in response.json()["detail"]
 
 
+@pytest.mark.asyncio
+async def test_sync_file_rejects_hidden_file(
+    client: AsyncClient, v2_project_url, test_project: Project
+):
+    """sync-file refuses hidden files, matching the default '.*' ignore pattern."""
+    hidden_path = Path(test_project.path) / ".secrets.md"
+    hidden_path.write_text("# Hidden\n\nShould never be indexed.\n", encoding="utf-8")
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": ".secrets.md"},
+    )
+    assert response.status_code == 400
+    assert "ignore rules" in response.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_rejects_gitignored_file(
+    client: AsyncClient, v2_project_url, test_project: Project
+):
+    """sync-file honors the project .gitignore, matching scan/watch filtering."""
+    project_path = Path(test_project.path)
+    (project_path / ".gitignore").write_text("private/\n", encoding="utf-8")
+    note_path = project_path / "private" / "secret.md"
+    note_path.parent.mkdir(parents=True, exist_ok=True)
+    note_path.write_text("# Secret\n\nGitignored content.\n", encoding="utf-8")
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "private/secret.md"},
+    )
+    assert response.status_code == 400
+    assert "ignore rules" in response.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_rejects_bmignored_file(
+    client: AsyncClient, v2_project_url, test_project: Project
+):
+    """sync-file honors user .bmignore patterns, matching scan/watch filtering."""
+    bmignore_path = get_bmignore_path()
+    bmignore_path.parent.mkdir(parents=True, exist_ok=True)
+    bmignore_path.write_text("drafts-wip\n", encoding="utf-8")
+
+    note_path = Path(test_project.path) / "drafts-wip" / "scratch.md"
+    note_path.parent.mkdir(parents=True, exist_ok=True)
+    note_path.write_text("# Scratch\n\nBmignored content.\n", encoding="utf-8")
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "drafts-wip/scratch.md"},
+    )
+    assert response.status_code == 400
+    assert "ignore rules" in response.json()["detail"]
+
+
 @pytest.mark.asyncio
 async def test_sync_file_rejects_non_markdown(
     client: AsyncClient, v2_project_url, test_project: Project

tests/mcp/test_tool_edit_note.py

@@ -3,9 +3,12 @@
 from pathlib import Path
 from unittest.mock import patch
 
+import httpx
 import pytest
+from mcp.server.fastmcp.exceptions import ToolError
 
-from basic_memory.mcp.tools.edit_note import edit_note
+from basic_memory.mcp.clients import KnowledgeClient
+from basic_memory.mcp.tools.edit_note import _resolve_after_disk_recovery, edit_note
 from basic_memory.mcp.tools.read_note import read_note
 from basic_memory.mcp.tools.write_note import write_note
 
@@ -1329,6 +1332,25 @@ async def test_edit_note_append_recovers_file_on_disk_instead_of_autocreate(clie
     assert "Appended line." in final_content
 
 
+@pytest.mark.asyncio
+async def test_resolve_after_disk_recovery_propagates_unexpected_errors():
+    """Server-side failures during disk recovery must not be masked as a not-found miss.
+
+    Only 400/404 sync-file rejections mean "nothing to recover"; a 500 (or auth
+    failure) would otherwise be swallowed and edit_note would continue into
+    auto-create with a misleading not-found error.
+    """
+
+    def server_error(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, json={"detail": "boom"})
+
+    transport = httpx.MockTransport(server_error)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as http_client:
+        knowledge_client = KnowledgeClient(http_client, "project-external-id")
+        with pytest.raises(ToolError, match="boom"):
+            await _resolve_after_disk_recovery(knowledge_client, "notes/unlucky-note")
+
+
 @pytest.mark.asyncio
 async def test_edit_note_append_traversal_identifier_is_blocked(client, test_project):
     """A traversal identifier must be rejected by both disk recovery and auto-create."""