fix(api): canonicalize sync-file paths before indexing

Review fixes for the #581 recovery endpoint:

- The sync-file endpoint indexed the caller-supplied path verbatim. On
  case-insensitive filesystems (macOS/Windows) a wrong-cased path like
  'notes/Disk-Note.md' passes the existence check for 'notes/disk-note.md',
  misses the DB row keyed by the on-disk path, and inserts a duplicate
  entity under the wrong-cased path. The endpoint now rejects non-normalized
  segments ('./', '//') with 400 and canonicalizes the path by matching real
  directory entries (exact name first, then a unique case-insensitive match),
  so the index lookup and sync always use the on-disk casing. Behavior is
  identical on case-sensitive and case-insensitive filesystems.
- Document the automatic single-file disk recovery in the edit_note
  docstring.

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

@@ -10,6 +10,9 @@
 - Simplified caching strategies
 """
 
+import os
+import pathlib
+
 from fastapi import APIRouter, HTTPException, Response, Path
 from loguru import logger
 
@@ -242,6 +245,40 @@ async def resolve_identifier(
 ## Single-file sync endpoint
 
 
+def _canonical_file_path(home: pathlib.Path, segments: list[str]) -> str | None:
+    """Resolve the actual on-disk casing of a file path under the project home.
+
+    Trigger: case-insensitive filesystems (macOS/Windows) pass existence checks for
+        wrong-cased paths like 'notes/Disk-Note.md' when the file is 'notes/disk-note.md'.
+    Why: indexing the caller-supplied casing misses the existing DB row keyed by the
+        on-disk path and inserts a duplicate entity under the wrong-cased path.
+    Outcome: each segment is matched against real directory entries — exact name first
+        (so distinct case-variant files on case-sensitive filesystems stay distinct),
+        then a unique case-insensitive match. Returns None when any segment cannot be
+        matched to exactly one entry, including missing files.
+    """
+    current = home
+    canonical_segments: list[str] = []
+    for segment in segments:
+        try:
+            with os.scandir(current) as entries_iter:
+                entries = [entry.name for entry in entries_iter]
+        except OSError:
+            # A parent segment resolved to a non-directory (or vanished): no canonical
+            # path exists for the remaining segments.
+            return None
+        if segment in entries:
+            matched = segment
+        else:
+            matches = [entry for entry in entries if entry.lower() == segment.lower()]
+            if len(matches) != 1:
+                return None
+            matched = matches[0]
+        canonical_segments.append(matched)
+        current = current / matched
+    return "/".join(canonical_segments)
+
+
 @router.post("/sync-file", response_model=EntityResponseV2)
 async def sync_file(
     data: SyncFileRequest,
@@ -262,8 +299,9 @@ async def sync_file(
         The indexed entity
 
     Raises:
-        HTTPException: 400 if the path escapes the project root or is not
-            markdown, 404 if the file does not exist on disk
+        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
     """
     with logfire.span(
         "api.request.knowledge.sync_file",
@@ -279,11 +317,26 @@ async def sync_file(
                 detail=f"File path '{data.file_path}' is not allowed - "
                 "paths must stay within project boundaries",
             )
-        if not (project_config.home / data.file_path).is_file():
+
+        # Trigger: segments like './' or '//' survive the traversal check above
+        # Why: a non-normalized path would index under a non-canonical DB key
+        # Outcome: reject fail-fast instead of guessing the canonical form
+        segments = data.file_path.replace("\\", "/").split("/")
+        if any(segment in ("", ".") for segment in segments):
+            raise HTTPException(
+                status_code=400,
+                detail=f"File path '{data.file_path}' is not normalized - "
+                "segments like './' or '//' are not allowed",
+            )
+
+        # Canonicalize to the actual on-disk casing so the DB lookup below hits the
+        # row keyed by the real path instead of inserting a wrong-cased duplicate.
+        file_path = _canonical_file_path(project_config.home, segments)
+        if file_path is None or not (project_config.home / file_path).is_file():
             raise HTTPException(
                 status_code=404, detail=f"File not found on disk: '{data.file_path}'"
             )
-        if not sync_service.file_service.is_markdown(data.file_path):
+        if not sync_service.file_service.is_markdown(file_path):
             raise HTTPException(
                 status_code=400,
                 detail=f"Only markdown files can be indexed: '{data.file_path}'",
@@ -292,15 +345,14 @@ async def sync_file(
         # Trigger: the file may already have a DB row (e.g. modified on disk after indexing)
         # Why: the indexer needs to know whether to insert or update the entity
         # Outcome: new is computed from the database instead of assumed by the caller
-        existing = await sync_service.entity_repository.get_by_file_path(data.file_path)
+        existing = await sync_service.entity_repository.get_by_file_path(file_path)
         synced = await sync_service.sync_one_markdown_file(
-            data.file_path, new=existing is None, index_search=True
+            file_path, new=existing is None, index_search=True
         )
 
         result = EntityResponseV2.model_validate(synced.entity)
         logger.info(
-            f"API v2 response: sync_file file_path='{data.file_path}' "
-            f"external_id={result.external_id}"
+            f"API v2 response: sync_file file_path='{file_path}' external_id={result.external_id}"
         )
         return result
 

src/basic_memory/mcp/tools/edit_note.py

@@ -375,7 +375,9 @@ async def edit_note(
 
     Note:
         Edit operations require exact identifier matches. If unsure, use read_note() or
-        search_notes() first to find the correct identifier. The tool provides detailed
+        search_notes() first to find the correct identifier. When the identifier looks
+        like a file path and the file exists on disk but is not indexed yet, edit_note
+        indexes that file automatically and retries the edit. The tool provides detailed
         error messages with suggestions if operations fail.
     """
     # Resolve effective default: allow MCP clients to send null for optional int field

tests/api/v2/test_knowledge_router.py

@@ -1034,6 +1034,92 @@ async def test_sync_file_rejects_path_traversal(client: AsyncClient, v2_project_
     assert "project boundaries" in response.json()["detail"]
 
 
+@pytest.mark.asyncio
+async def test_sync_file_wrong_cased_path_does_not_create_duplicate(
+    client: AsyncClient, v2_project_url, test_project: Project, entity_repository
+):
+    """A wrong-cased path resolves to the canonical on-disk file without duplicating it.
+
+    On case-insensitive filesystems (macOS/Windows) a wrong-cased path passes existence
+    checks; without canonicalization the indexer would insert a second entity keyed by
+    the wrong-cased path. The endpoint matches real directory entries, so the request
+    behaves identically on case-sensitive and case-insensitive filesystems.
+    """
+    note_path = Path(test_project.path) / "notes" / "disk-note.md"
+    note_path.parent.mkdir(parents=True, exist_ok=True)
+    note_path.write_text("# Disk Note\n\nWritten directly to disk.\n", encoding="utf-8")
+
+    first = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "notes/disk-note.md"},
+    )
+    assert first.status_code == 200
+    canonical = EntityResponseV2.model_validate(first.json())
+    assert canonical.file_path == "notes/disk-note.md"
+
+    second = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "notes/Disk-Note.md"},
+    )
+    assert second.status_code == 200
+    synced = EntityResponseV2.model_validate(second.json())
+    assert synced.file_path == "notes/disk-note.md"
+    assert synced.external_id == canonical.external_id
+
+    entities = await entity_repository.find_all()
+    assert [entity.file_path for entity in entities] == ["notes/disk-note.md"]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_rejects_non_normalized_segments(
+    client: AsyncClient, v2_project_url, test_project: Project
+):
+    """sync-file rejects './' and '//' style segments instead of indexing them verbatim."""
+    note_path = Path(test_project.path) / "notes" / "disk-note.md"
+    note_path.parent.mkdir(parents=True, exist_ok=True)
+    note_path.write_text("# Disk Note\n", encoding="utf-8")
+
+    for non_normalized in ("./notes/disk-note.md", "notes//disk-note.md"):
+        response = await client.post(
+            f"{v2_project_url}/knowledge/sync-file",
+            json={"file_path": non_normalized},
+        )
+        assert response.status_code == 400
+        assert "not normalized" in response.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_directory_returns_404(
+    client: AsyncClient, v2_project_url, test_project: Project
+):
+    """sync-file refuses a path that canonicalizes to a directory instead of a file."""
+    (Path(test_project.path) / "just-a-directory").mkdir(parents=True, exist_ok=True)
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "just-a-directory"},
+    )
+    assert response.status_code == 404
+    assert "File not found on disk" in response.json()["detail"]
+
+
+@pytest.mark.asyncio
+async def test_sync_file_path_through_file_returns_404(
+    client: AsyncClient, v2_project_url, test_project: Project
+):
+    """sync-file fails fast when a parent segment resolves to a file, not a directory."""
+    note_path = Path(test_project.path) / "notes" / "disk-note.md"
+    note_path.parent.mkdir(parents=True, exist_ok=True)
+    note_path.write_text("# Disk Note\n", encoding="utf-8")
+
+    response = await client.post(
+        f"{v2_project_url}/knowledge/sync-file",
+        json={"file_path": "notes/disk-note.md/child.md"},
+    )
+    assert response.status_code == 404
+    assert "File not found on disk" in response.json()["detail"]
+
+
 @pytest.mark.asyncio
 async def test_sync_file_rejects_non_markdown(
     client: AsyncClient, v2_project_url, test_project: Project