basic-memory 0.17.1__py3-none-any.whl

basic_memory/mcp/tools/move_note.py

@@ -0,0 +1,551 @@
+"""Move note tool for Basic Memory MCP server."""
+
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_get, call_put, resolve_entity_id
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.schemas import EntityResponse
+from basic_memory.schemas.project_info import ProjectList
+from basic_memory.telemetry import track_mcp_tool
+from basic_memory.utils import validate_project_path
+
+
+async def _detect_cross_project_move_attempt(
+    client, identifier: str, destination_path: str, current_project: str
+) -> Optional[str]:
+    """Detect potential cross-project move attempts and return guidance.
+
+    Args:
+        client: The AsyncClient instance
+        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
+                )
+
+        # No other cross-project patterns detected
+
+    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. Create the note in the target project
+        write_note("Note Title", "content from step 1", "target-folder", project="{target_project}")
+
+        # 3. Delete the original note if desired
+        delete_note("{identifier}", project="{current_project}")
+        
+        ```
+
+        ### 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_memory_projects()` to see all available 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. Create note in target project
+        write_note("Title", "content", "folder", project="target-project-name")
+
+        # 3. Delete original if desired
+        delete_note("{identifier}", project="{current_project}")
+        ```
+        
+        ### To see all projects:
+        ```
+        list_memory_projects()
+        ```
+        """).strip()
+
+
+def _format_move_error_response(error_message: str, identifier: str, destination_path: str) -> str:
+    """Format helpful error responses for move failures that guide users to successful moves."""
+
+    # Note not found errors
+    if "entity not found" in error_message.lower() or "not found" in error_message.lower():
+        search_term = identifier.split("/")[-1] if "/" in identifier else identifier
+        title_format = (
+            identifier.split("/")[-1].replace("-", " ").title() if "/" in identifier else identifier
+        )
+        permalink_format = identifier.lower().replace(" ", "-")
+
+        return dedent(f"""
+            # Move Failed - Note Not Found
+
+            The note '{identifier}' could not be found for moving. Move operations require an exact match (no fuzzy matching).
+
+            ## Suggestions to try:
+            1. **Search for the note first**: Use `search_notes("{search_term}")` to find it with exact identifiers
+            2. **Try different exact identifier formats**:
+               - If you used a permalink like "folder/note-title", try the exact title: "{title_format}"
+               - If you used a title, try the exact permalink format: "{permalink_format}"
+               - Use `read_note()` first to verify the note exists and get the exact identifier
+
+            3. **List available notes**: Use `list_directory("/")` to see what notes exist in the current project
+            4. **List available notes**: Use `list_directory("/")` to see what notes exist
+
+            ## Before trying again:
+            ```
+            # First, verify the note exists:
+            search_notes("{identifier}")
+
+            # Then use the exact identifier from search results:
+            move_note("correct-identifier-here", "{destination_path}")
+            ```
+            """).strip()
+
+    # Destination already exists errors
+    if "already exists" in error_message.lower() or "file exists" in error_message.lower():
+        return f"""# Move Failed - Destination Already Exists
+
+Cannot move '{identifier}' to '{destination_path}' because a file already exists at that location.
+
+## How to resolve:
+1. **Choose a different destination**: Try a different filename or folder
+   - Add timestamp: `{destination_path.rsplit(".", 1)[0] if "." in destination_path else destination_path}-backup.md`
+   - Use different folder: `archive/{destination_path}` or `backup/{destination_path}`
+
+2. **Check the existing file**: Use `read_note("{destination_path}")` to see what's already there
+3. **Remove or rename existing**: If safe to do so, move the existing file first
+
+## Try these alternatives:
+```
+# Option 1: Add timestamp to make unique
+move_note("{identifier}", "{destination_path.rsplit(".", 1)[0] if "." in destination_path else destination_path}-backup.md")
+
+# Option 2: Use archive folder  
+move_note("{identifier}", "archive/{destination_path}")
+
+# Option 3: Check what's at destination first
+read_note("{destination_path}")
+```"""
+
+    # Invalid path errors
+    if "invalid" in error_message.lower() and "path" in error_message.lower():
+        return f"""# Move Failed - Invalid Destination Path
+
+The destination path '{destination_path}' is not valid: {error_message}
+
+## Path requirements:
+1. **Relative paths only**: Don't start with `/` (use `notes/file.md` not `/notes/file.md`)
+2. **Include file extension**: Add `.md` for markdown files
+3. **Use forward slashes**: For folder separators (`folder/subfolder/file.md`)
+4. **No special characters**: Avoid `\\`, `:`, `*`, `?`, `"`, `<`, `>`, `|`
+
+## Valid path examples:
+- `notes/my-note.md`
+- `projects/2025/meeting-notes.md`
+- `archive/old-projects/legacy-note.md`
+
+## Try again with:
+```
+move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in destination_path else destination_path}")
+```"""
+
+    # Permission/access errors
+    if (
+        "permission" in error_message.lower()
+        or "access" in error_message.lower()
+        or "forbidden" in error_message.lower()
+    ):
+        return f"""# Move Failed - Permission Error
+
+You don't have permission to move '{identifier}': {error_message}
+
+## How to resolve:
+1. **Check file permissions**: Ensure you have write access to both source and destination
+2. **Verify project access**: Make sure you have edit permissions for this project
+3. **Check file locks**: The file might be open in another application
+
+## Alternative actions:
+- List available projects: `list_memory_projects()`
+- Try copying content instead: `read_note("{identifier}", project="project-name")` then `write_note()` to new location"""
+
+    # Source file not found errors
+    if "source" in error_message.lower() and (
+        "not found" in error_message.lower() or "missing" in error_message.lower()
+    ):
+        return f"""# Move Failed - Source File Missing
+
+The source file for '{identifier}' was not found on disk: {error_message}
+
+This usually means the database and filesystem are out of sync.
+
+## How to resolve:
+1. **Check if note exists in database**: `read_note("{identifier}")`
+2. **Run sync operation**: The file might need to be re-synced
+3. **Recreate the file**: If data exists in database, recreate the physical file
+
+## Troubleshooting steps:
+```
+# Check if note exists in Basic Memory
+read_note("{identifier}")
+
+# If it exists, the file is missing on disk - send a message to support@basicmachines.co
+# If it doesn't exist, use search to find the correct identifier
+search_notes("{identifier}")
+```"""
+
+    # Server/filesystem errors
+    if (
+        "server error" in error_message.lower()
+        or "filesystem" in error_message.lower()
+        or "disk" in error_message.lower()
+    ):
+        return f"""# Move Failed - System Error
+
+A system error occurred while moving '{identifier}': {error_message}
+
+## Immediate steps:
+1. **Try again**: The error might be temporary
+2. **Check disk space**: Ensure adequate storage is available
+3. **Verify filesystem permissions**: Check if the destination directory is writable
+
+## Alternative approaches:
+- Copy content to new location: Use `read_note("{identifier}")` then `write_note()` 
+- Use a different destination folder that you know works
+- Send a message to support@basicmachines.co if the problem persists
+
+## Backup approach:
+```
+# Read current content
+content = read_note("{identifier}")
+
+# Create new note at desired location  
+write_note("New Note Title", content, "{destination_path.split("/")[0] if "/" in destination_path else "notes"}")
+
+# Then delete original if successful
+delete_note("{identifier}")
+```"""
+
+    # Generic fallback
+    return f"""# Move Failed
+
+Error moving '{identifier}' to '{destination_path}': {error_message}
+
+## General troubleshooting:
+1. **Verify the note exists**: `read_note("{identifier}")` or `search_notes("{identifier}")`
+2. **Check destination path**: Ensure it's a valid relative path with `.md` extension
+3. **Verify permissions**: Make sure you can edit files in this project
+4. **Try a simpler path**: Use a basic folder structure like `notes/filename.md`
+
+## Step-by-step approach:
+```
+# 1. Confirm note exists
+read_note("{identifier}")
+
+# 2. Try a simple destination first
+move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in destination_path else destination_path}")
+
+# 3. If that works, then try your original destination
+```
+
+## Alternative approach:
+If moving continues to fail, you can copy the content manually:
+```
+# Read current content
+content = read_note("{identifier}")
+
+# Create new note
+write_note("Title", content, "target-folder") 
+
+# Delete original once confirmed
+delete_note("{identifier}")
+```"""
+
+
+@mcp.tool(
+    description="Move a note to a new location, updating database and maintaining links.",
+)
+async def move_note(
+    identifier: str,
+    destination_path: str,
+    project: Optional[str] = None,
+    context: Context | None = None,
+) -> str:
+    """Move a note to a new file location within the same project.
+
+    Moves a note from one location to another within the project, updating all
+    database references and maintaining semantic content. Uses stateless architecture -
+    project parameter optional with server resolution.
+
+    Args:
+        identifier: Exact entity identifier (title, permalink, or memory:// URL).
+                   Must be an exact match - fuzzy matching is not supported for move operations.
+                   Use search_notes() or read_note() first to find the correct identifier if uncertain.
+        destination_path: New path relative to project root (e.g., "work/meetings/2025-05-26.md")
+        project: Project name to move within. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        Success message with move details and project information.
+
+    Examples:
+        # Move to new folder (exact title match)
+        move_note("My Note", "work/notes/my-note.md")
+
+        # Move by exact permalink
+        move_note("my-note-permalink", "archive/old-notes/my-note.md")
+
+        # Move with complex path structure
+        move_note("experiments/ml-results", "archive/2025/ml-experiments.md")
+
+        # Explicit project specification
+        move_note("My Note", "work/notes/my-note.md", project="work-project")
+
+        # If uncertain about identifier, search first:
+        # search_notes("my note")  # Find available notes
+        # move_note("docs/my-note-2025", "archive/my-note.md")  # Use exact result
+
+    Raises:
+        ToolError: If project doesn't exist, identifier is not found, or destination_path is invalid
+
+    Note:
+        This operation moves notes within the specified project only. Moving notes
+        between different projects is not currently supported.
+
+    The move operation:
+    - Updates the entity's file_path in the database
+    - Moves the physical file on the filesystem
+    - Optionally updates permalinks if configured
+    - Re-indexes the entity for search
+    - Maintains all observations and relations
+    """
+    track_mcp_tool("move_note")
+    async with get_client() as client:
+        logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")
+
+        active_project = await get_active_project(client, project, context)
+
+        # Validate destination path to prevent path traversal attacks
+        project_path = active_project.home
+        if not validate_project_path(destination_path, project_path):
+            logger.warning(
+                "Attempted path traversal attack blocked",
+                destination_path=destination_path,
+                project=active_project.name,
+            )
+            return f"""# Move Failed - Security Validation Error
+
+The destination path '{destination_path}' is not allowed - paths must stay within project boundaries.
+
+## Valid path examples:
+- `notes/my-file.md`
+- `projects/2025/meeting-notes.md`
+- `archive/old-notes.md`
+
+## Try again with a safe path:
+```
+move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in destination_path else destination_path}")
+```"""
+
+        # Check for potential cross-project move attempts
+        cross_project_error = await _detect_cross_project_move_attempt(
+            client, 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
+
+        # Get the source entity information for extension validation
+        source_ext = "md"  # Default to .md if we can't determine source extension
+        try:
+            # Resolve identifier to entity ID
+            entity_id = await resolve_entity_id(client, active_project.id, identifier)
+            # Fetch source entity information to get the current file extension
+            url = f"/v2/projects/{active_project.id}/knowledge/entities/{entity_id}"
+            response = await call_get(client, url)
+            source_entity = EntityResponse.model_validate(response.json())
+            if "." in source_entity.file_path:
+                source_ext = source_entity.file_path.split(".")[-1]
+        except Exception as e:
+            # If we can't fetch the source entity, default to .md extension
+            logger.debug(f"Could not fetch source entity for extension check: {e}")
+
+        # Validate that destination path includes a file extension
+        if "." not in destination_path or not destination_path.split(".")[-1]:
+            logger.warning(f"Move failed - no file extension provided: {destination_path}")
+            return dedent(f"""
+                # Move Failed - File Extension Required
+
+                The destination path '{destination_path}' must include a file extension (e.g., '.md').
+
+                ## Valid examples:
+                - `notes/my-note.md`
+                - `projects/meeting-2025.txt`
+                - `archive/old-program.sh`
+
+                ## Try again with extension:
+                ```
+                move_note("{identifier}", "{destination_path}.{source_ext}")
+                ```
+
+                All examples in Basic Memory expect file extensions to be explicitly provided.
+                """).strip()
+
+        # Get the source entity to check its file extension
+        try:
+            # Resolve identifier to entity ID (might already be cached from above)
+            entity_id = await resolve_entity_id(client, active_project.id, identifier)
+            # Fetch source entity information
+            url = f"/v2/projects/{active_project.id}/knowledge/entities/{entity_id}"
+            response = await call_get(client, url)
+            source_entity = EntityResponse.model_validate(response.json())
+
+            # Extract file extensions
+            source_ext = (
+                source_entity.file_path.split(".")[-1] if "." in source_entity.file_path else ""
+            )
+            dest_ext = destination_path.split(".")[-1] if "." in destination_path else ""
+
+            # Check if extensions match
+            if source_ext and dest_ext and source_ext.lower() != dest_ext.lower():
+                logger.warning(
+                    f"Move failed - file extension mismatch: source={source_ext}, dest={dest_ext}"
+                )
+                return dedent(f"""
+                    # Move Failed - File Extension Mismatch
+
+                    The destination file extension '.{dest_ext}' does not match the source file extension '.{source_ext}'.
+
+                    To preserve file type consistency, the destination must have the same extension as the source.
+
+                    ## Source file:
+                    - Path: `{source_entity.file_path}`
+                    - Extension: `.{source_ext}`
+
+                    ## Try again with matching extension:
+                    ```
+                    move_note("{identifier}", "{destination_path.rsplit(".", 1)[0]}.{source_ext}")
+                    ```
+                    """).strip()
+        except Exception as e:
+            # If we can't fetch the source entity, log it but continue
+            # This might happen if the identifier is not yet resolved
+            logger.debug(f"Could not fetch source entity for extension check: {e}")
+
+        try:
+            # Resolve identifier to entity ID for the move operation
+            entity_id = await resolve_entity_id(client, active_project.id, identifier)
+
+            # Prepare move request (v2 API only needs destination_path)
+            move_data = {
+                "destination_path": destination_path,
+            }
+
+            # Call the v2 move API endpoint (PUT method, entity_id in URL)
+            url = f"/v2/projects/{active_project.id}/knowledge/entities/{entity_id}/move"
+            response = await call_put(client, url, json=move_data)
+            result = EntityResponse.model_validate(response.json())
+
+            # Build success message
+            result_lines = [
+                "✅ Note moved successfully",
+                "",
+                f"📁 **{identifier}** → **{result.file_path}**",
+                f"🔗 Permalink: {result.permalink}",
+                "📊 Database and search index updated",
+                "",
+                f"<!-- Project: {active_project.name} -->",
+            ]
+
+            # Log the operation
+            logger.info(
+                "Move note completed",
+                identifier=identifier,
+                destination_path=destination_path,
+                project=active_project.name,
+                status_code=response.status_code,
+            )
+
+            return "\n".join(result_lines)
+
+        except Exception as e:
+            logger.error(f"Move failed for '{identifier}' to '{destination_path}': {e}")
+            # Return formatted error message for better user experience
+            return _format_move_error_response(str(e), identifier, destination_path)