fix(mcp): resolve legacy workspace permalinks

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

Author: phernandez

src/basic_memory/mcp/tools/read_note.py

@@ -18,7 +18,8 @@
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.search import search_notes
 from basic_memory.schemas.memory import memory_url_path
-from basic_memory.utils import validate_project_path
+from basic_memory.utils import generate_permalink, validate_project_path
+from basic_memory.workspace_context import current_workspace_permalink_context
 
 
 def _is_exact_title_match(identifier: str, title: str) -> bool:
@@ -277,24 +278,51 @@ def _result_file_path(item: dict[str, object]) -> Optional[str]:
                 value = item.get("file_path")
                 return str(value) if value else None
 
-            try:
-                # Try to resolve identifier to entity ID
-                entity_id = await knowledge_client.resolve_entity(entity_path, strict=True)
+            def _legacy_workspace_unqualified_path(path: str) -> str | None:
+                workspace_context = current_workspace_permalink_context()
+                if workspace_context is None:
+                    return None
+
+                workspace_prefix = generate_permalink(workspace_context.workspace_slug)
+                project_prefix = active_project.permalink
+                qualified_prefix = f"{workspace_prefix}/{project_prefix}"
+                normalized_path = path.strip("/")
+                if normalized_path == qualified_prefix:
+                    return project_prefix
+                if normalized_path.startswith(f"{qualified_prefix}/"):
+                    return f"{project_prefix}/{normalized_path.removeprefix(f'{qualified_prefix}/')}"
+                return None
+
+            direct_lookup_paths = [entity_path]
+            legacy_path = _legacy_workspace_unqualified_path(entity_path)
+            if legacy_path and legacy_path not in direct_lookup_paths:
+                # Trigger: existing cloud rows may still use project-prefixed permalinks.
+                # Why: new workspace-qualified IDs should read old notes without a re-sync.
+                # Outcome: try the legacy path after the canonical workspace path misses.
+                direct_lookup_paths.append(legacy_path)
+
+            for direct_lookup_path in direct_lookup_paths:
+                try:
+                    # Try to resolve identifier to entity ID
+                    entity_id = await knowledge_client.resolve_entity(
+                        direct_lookup_path, strict=True
+                    )
 
-                # Fetch content using entity ID
-                response = await resource_client.read(entity_id)
+                    # Fetch content using entity ID
+                    response = await resource_client.read(entity_id)
 
-                # If successful, return the content
-                if response.status_code == 200:
-                    logger.info(
-                        "Returning read_note result from resource: {path}", path=entity_path
-                    )
-                    if output_format == "json":
-                        return await _read_json_payload(entity_id)
-                    return response.text
-            except Exception as e:  # pragma: no cover
-                logger.info(f"Direct lookup failed for '{entity_path}': {e}")
-                # Continue to fallback methods
+                    # If successful, return the content
+                    if response.status_code == 200:
+                        logger.info(
+                            "Returning read_note result from resource: {path}",
+                            path=direct_lookup_path,
+                        )
+                        if output_format == "json":
+                            return await _read_json_payload(entity_id)
+                        return response.text
+                except Exception as e:  # pragma: no cover
+                    logger.info(f"Direct lookup failed for '{direct_lookup_path}': {e}")
+                    # Continue to alternate direct lookup paths, then fallback methods
 
             # Fallback 1: Try title search via API
             logger.info(f"Search title for: {identifier}")

tests/mcp/test_tool_read_note.py

@@ -404,6 +404,68 @@ async def test_personal_workspace_write_stores_complete_canonical_permalink(
     assert stored.permalink == expected_permalink
 
 
+@pytest.mark.asyncio
+async def test_read_note_personal_workspace_keeps_short_project_permalink_working(
+    app,
+    test_project,
+):
+    from basic_memory.workspace_context import workspace_permalink_context
+
+    legacy_permalink = f"{test_project.name}/personal/short-personal-note"
+
+    await write_note(
+        project=test_project.name,
+        title="Short Personal Note",
+        directory="personal",
+        content="Short personal workspace content",
+    )
+
+    with workspace_permalink_context(workspace_slug="personal", workspace_type="personal"):
+        read_result = await read_note(
+            f"memory://{legacy_permalink}",
+            project=test_project.name,
+            output_format="json",
+        )
+
+    assert isinstance(read_result, dict)
+    assert read_result["permalink"] == legacy_permalink
+    assert read_result["content"].strip() == "Short personal workspace content"
+
+
+@pytest.mark.asyncio
+async def test_read_note_workspace_qualified_personal_url_finds_legacy_short_permalink(
+    app,
+    test_project,
+    entity_repository,
+):
+    from basic_memory.workspace_context import workspace_permalink_context
+
+    legacy_permalink = f"{test_project.name}/personal/legacy-personal-note"
+    qualified_permalink = f"personal/{legacy_permalink}"
+
+    await write_note(
+        project=test_project.name,
+        title="Legacy Personal Note",
+        directory="personal",
+        content="Legacy personal workspace content",
+    )
+
+    stored = await entity_repository.get_by_permalink(legacy_permalink)
+    assert stored is not None
+    assert stored.permalink == legacy_permalink
+
+    with workspace_permalink_context(workspace_slug="personal", workspace_type="personal"):
+        read_result = await read_note(
+            f"memory://{qualified_permalink}",
+            project=test_project.name,
+            output_format="json",
+        )
+
+    assert isinstance(read_result, dict)
+    assert read_result["permalink"] == legacy_permalink
+    assert read_result["content"].strip() == "Legacy personal workspace content"
+
+
 @pytest.mark.asyncio
 async def test_read_note_workspace_qualified_memory_url_uses_complete_permalink(
     app,