feat: enhance move_note tool with cross-project detection and guidance (#161)

Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
Co-authored-by: Paul Hernandez <phernandez@users.noreply.github.com>

Author: phernandez

src/basic_memory/mcp/tools/move_note.py

@@ -7,9 +7,151 @@
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
-from basic_memory.mcp.tools.utils import call_post
+from basic_memory.mcp.tools.utils import call_post, call_get
 from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
+from basic_memory.schemas.project_info import ProjectList
+
+
+async def _detect_cross_project_move_attempt(
+    identifier: str, destination_path: str, current_project: str
+) -> Optional[str]:
+    """Detect potential cross-project move attempts and return guidance.
+    
+    Args:
+        identifier: The note identifier being moved
+        destination_path: The destination path
+        current_project: The current active project
+        
+    Returns:
+        Error message with guidance if cross-project move is detected, None otherwise
+    """
+    try:
+        # Get list of all available projects to check against
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())
+        project_names = [p.name.lower() for p in project_list.projects]
+        
+        # Check if destination path contains any project names
+        dest_lower = destination_path.lower()
+        path_parts = dest_lower.split("/")
+        
+        # Look for project names in the destination path
+        for part in path_parts:
+            if part in project_names and part != current_project.lower():
+                # Found a different project name in the path
+                matching_project = next(p.name for p in project_list.projects if p.name.lower() == part)
+                return _format_cross_project_error_response(
+                    identifier, destination_path, current_project, matching_project
+                )
+        
+        # Check if the destination path looks like it might be trying to reference another project
+        # (e.g., contains common project-like patterns)
+        if any(keyword in dest_lower for keyword in ["project", "workspace", "repo"]):
+            # This might be a cross-project attempt, but we can't be sure
+            # Return a general guidance message
+            available_projects = [p.name for p in project_list.projects if p.name != current_project]
+            if available_projects:
+                return _format_potential_cross_project_guidance(
+                    identifier, destination_path, current_project, available_projects
+                )
+    
+    except Exception as e:
+        # If we can't detect, don't interfere with normal error handling
+        logger.debug(f"Could not check for cross-project move: {e}")
+        return None
+    
+    return None
+
+
+def _format_cross_project_error_response(
+    identifier: str, destination_path: str, current_project: str, target_project: str
+) -> str:
+    """Format error response for detected cross-project move attempts."""
+    return dedent(f"""
+        # Move Failed - Cross-Project Move Not Supported
+        
+        Cannot move '{identifier}' to '{destination_path}' because it appears to reference a different project ('{target_project}').
+        
+        **Current project:** {current_project}
+        **Target project:** {target_project}
+        
+        ## Cross-project moves are not supported directly
+        
+        Notes can only be moved within the same project. To move content between projects, use this workflow:
+        
+        ### Recommended approach:
+        ```
+        # 1. Read the note content from current project
+        read_note("{identifier}")
+        
+        # 2. Switch to the target project
+        switch_project("{target_project}")
+        
+        # 3. Create the note in the target project
+        write_note("Note Title", "content from step 1", "target-folder")
+        
+        # 4. Switch back to original project (optional)
+        switch_project("{current_project}")
+        
+        # 5. Delete the original note if desired
+        delete_note("{identifier}")
+        ```
+        
+        ### Alternative: Stay in current project
+        If you want to move the note within the **{current_project}** project only:
+        ```
+        move_note("{identifier}", "new-folder/new-name.md")
+        ```
+        
+        ## Available projects:
+        Use `list_projects()` to see all available projects and `switch_project("project-name")` to change projects.
+        """).strip()
+
+
+def _format_potential_cross_project_guidance(
+    identifier: str, destination_path: str, current_project: str, available_projects: list[str]
+) -> str:
+    """Format guidance for potentially cross-project moves."""
+    other_projects = ", ".join(available_projects[:3])  # Show first 3 projects
+    if len(available_projects) > 3:
+        other_projects += f" (and {len(available_projects) - 3} others)"
+    
+    return dedent(f"""
+        # Move Failed - Check Project Context
+        
+        Cannot move '{identifier}' to '{destination_path}' within the current project '{current_project}'.
+        
+        ## If you intended to move within the current project:
+        The destination path should be relative to the project root:
+        ```
+        move_note("{identifier}", "folder/filename.md")
+        ```
+        
+        ## If you intended to move to a different project:
+        Cross-project moves require switching projects first. Available projects: {other_projects}
+        
+        ### To move to another project:
+        ```
+        # 1. Read the content
+        read_note("{identifier}")
+        
+        # 2. Switch to target project
+        switch_project("target-project-name")
+        
+        # 3. Create note in target project
+        write_note("Title", "content", "folder")
+        
+        # 4. Switch back and delete original if desired
+        switch_project("{current_project}")
+        delete_note("{identifier}")
+        ```
+        
+        ### To see all projects:
+        ```
+        list_projects()
+        ```
+        """).strip()
 
 
 def _format_move_error_response(error_message: str, identifier: str, destination_path: str) -> str:
@@ -258,6 +400,14 @@ async def move_note(
     active_project = get_active_project(project)
     project_url = active_project.project_url
 
+    # Check for potential cross-project move attempts
+    cross_project_error = await _detect_cross_project_move_attempt(
+        identifier, destination_path, active_project.name
+    )
+    if cross_project_error:
+        logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
+        return cross_project_error
+
     try:
         # Prepare move request
         move_data = {

test-int/mcp/test_move_note_integration.py

@@ -507,3 +507,136 @@ async def test_move_note_using_different_identifier_formats(mcp_server, app):
 
         read3 = await client.call_tool("read_note", {"identifier": "moved/folder-title-moved.md"})
         assert "Move by folder/title" in read3[0].text
+
+
+@pytest.mark.asyncio
+async def test_move_note_cross_project_detection(mcp_server, app):
+    """Test cross-project move detection and helpful error messages."""
+
+    async with Client(mcp_server) as client:
+        # Create a test project to simulate cross-project scenario
+        await client.call_tool(
+            "create_memory_project",
+            {
+                "project_name": "test-project-b",
+                "project_path": "/tmp/test-project-b", 
+                "set_default": False,
+            },
+        )
+
+        # Create a note in the default project
+        await client.call_tool(
+            "write_note",
+            {
+                "title": "Cross Project Test Note",
+                "folder": "source",
+                "content": "# Cross Project Test Note\n\nThis note is in the default project.",
+                "tags": "test,cross-project",
+            },
+        )
+
+        # Try to move to a path that contains the other project name
+        move_result = await client.call_tool(
+            "move_note",
+            {
+                "identifier": "Cross Project Test Note",
+                "destination_path": "test-project-b/moved-note.md",
+            },
+        )
+
+        # Should detect cross-project attempt and provide helpful guidance
+        assert len(move_result) == 1
+        error_message = move_result[0].text
+        assert "Cross-Project Move Not Supported" in error_message
+        assert "test-project-b" in error_message
+        assert "switch_project" in error_message
+        assert "read_note" in error_message
+        assert "write_note" in error_message
+
+
+@pytest.mark.asyncio
+async def test_move_note_potential_cross_project_guidance(mcp_server, app):
+    """Test guidance for potentially cross-project moves with project-like keywords."""
+
+    async with Client(mcp_server) as client:
+        # Create another test project
+        await client.call_tool(
+            "create_memory_project",
+            {
+                "project_name": "workspace-docs",
+                "project_path": "/tmp/workspace-docs",
+                "set_default": False,
+            },
+        )
+
+        # Create a note in the default project
+        await client.call_tool(
+            "write_note",
+            {
+                "title": "Potential Cross Project Note",
+                "folder": "source",
+                "content": "# Potential Cross Project Note\n\nThis might be moved cross-project.",
+                "tags": "test,potential-cross-project",
+            },
+        )
+
+        # Try to move to a path that contains project-like keywords but not exact project names
+        move_result = await client.call_tool(
+            "move_note",
+            {
+                "identifier": "Potential Cross Project Note",
+                "destination_path": "project-archive/moved-note.md",
+            },
+        )
+
+        # Should provide guidance for potential cross-project moves
+        assert len(move_result) == 1
+        error_message = move_result[0].text
+        assert "Check Project Context" in error_message
+        assert "workspace-docs" in error_message  # Should mention other available projects
+        assert "list_projects" in error_message
+        assert "switch_project" in error_message
+
+
+@pytest.mark.asyncio 
+async def test_move_note_normal_moves_still_work(mcp_server, app):
+    """Test that normal within-project moves still work after cross-project detection."""
+
+    async with Client(mcp_server) as client:
+        # Create a note
+        await client.call_tool(
+            "write_note",
+            {
+                "title": "Normal Move Note",
+                "folder": "source",
+                "content": "# Normal Move Note\n\nThis should move normally.",
+                "tags": "test,normal-move",
+            },
+        )
+
+        # Try a normal move that should work
+        move_result = await client.call_tool(
+            "move_note",
+            {
+                "identifier": "Normal Move Note",
+                "destination_path": "destination/normal-moved.md",
+            },
+        )
+
+        # Should work normally
+        assert len(move_result) == 1
+        move_text = move_result[0].text
+        assert "✅ Note moved successfully" in move_text
+        assert "Normal Move Note" in move_text
+        assert "destination/normal-moved.md" in move_text
+
+        # Verify the note can be read from its new location
+        read_result = await client.call_tool(
+            "read_note",
+            {
+                "identifier": "destination/normal-moved.md",
+            },
+        )
+
+        content = read_result[0].text
+        assert "This should move normally" in content