basic-memory 0.14.4__py3-none-any.whl → 0.15.0__py3-none-any.whl

basic_memory/mcp/tools/edit_note.py

@@ -3,9 +3,10 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.project_context import get_active_project, add_project_metadata
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_patch
 from basic_memory.schemas import EntityResponse
@@ -17,6 +18,7 @@ def _format_error_response(
     identifier: str,
     find_text: Optional[str] = None,
     expected_replacements: int = 1,
+    project: Optional[str] = None,
 ) -> str:
     """Format helpful error responses for edit_note failures that guide the AI to retry successfully."""
 
@@ -27,14 +29,14 @@ def _format_error_response(
 The note with identifier '{identifier}' could not be found. Edit operations require an exact match (no fuzzy matching).
 
 ## Suggestions to try:
-1. **Search for the note first**: Use `search_notes("{identifier.split("/")[-1]}")` to find similar notes with exact identifiers
+1. **Search for the note first**: Use `search_notes("{project or "project-name"}", "{identifier.split("/")[-1]}")` to find similar notes with exact identifiers
 2. **Try different exact identifier formats**:
    - If you used a permalink like "folder/note-title", try the exact title: "{identifier.split("/")[-1].replace("-", " ").title()}"
    - If you used a title, try the exact permalink format: "{identifier.lower().replace(" ", "-")}"
-   - Use `read_note()` first to verify the note exists and get the exact identifier
+   - Use `read_note("{project or "project-name"}", "{identifier}")` first to verify the note exists and get the exact identifier
 
 ## Alternative approach:
-Use `write_note()` to create the note first, then edit it."""
+Use `write_note("{project or "project-name"}", "title", "content", "folder")` to create the note first, then edit it."""
 
     # Find/replace specific errors
     if operation == "find_replace":
@@ -44,7 +46,7 @@ Use `write_note()` to create the note first, then edit it."""
 The text '{find_text}' was not found in the note '{identifier}'.
 
 ## Suggestions to try:
-1. **Read the note first**: Use `read_note("{identifier}")` to see the current content
+1. **Read the note first**: Use `read_note("{project or "project-name"}", "{identifier}")` to see the current content
 2. **Check for exact matches**: The search is case-sensitive and must match exactly
 3. **Try a broader search**: Search for just part of the text you want to replace
 4. **Use expected_replacements=0**: If you want to verify the text doesn't exist
@@ -65,13 +67,13 @@ The text '{find_text}' was not found in the note '{identifier}'.
 Expected {expected_replacements} occurrences of '{find_text}' but found {actual_count}.
 
 ## How to fix:
-1. **Read the note first**: Use `read_note("{identifier}")` to see how many times '{find_text}' appears
+1. **Read the note first**: Use `read_note("{project or "project-name"}", "{identifier}")` to see how many times '{find_text}' appears
 2. **Update expected_replacements**: Set expected_replacements={actual_count} in your edit_note call
 3. **Be more specific**: If you only want to replace some occurrences, make your find_text more specific
 
 ## Example:
 ```
-edit_note("{identifier}", "find_replace", "new_text", find_text="{find_text}", expected_replacements={actual_count})
+edit_note("{project or "project-name"}", "{identifier}", "find_replace", "new_text", find_text="{find_text}", expected_replacements={actual_count})
 ```"""
 
     # Section replacement errors
@@ -81,7 +83,7 @@ edit_note("{identifier}", "find_replace", "new_text", find_text="{find_text}", e
 Multiple sections found with the same header in note '{identifier}'.
 
 ## How to fix:
-1. **Read the note first**: Use `read_note("{identifier}")` to see the document structure
+1. **Read the note first**: Use `read_note("{project or "project-name"}", "{identifier}")` to see the document structure
 2. **Make headers unique**: Add more specific text to distinguish sections
 3. **Use append instead**: Add content at the end rather than replacing a specific section
 
@@ -97,14 +99,14 @@ Use `find_replace` to update specific text within the duplicate sections."""
 There was a problem with the edit request to note '{identifier}': {error_message}.
 
 ## Common causes and fixes:
-1. **Note doesn't exist**: Use `search_notes()` or `read_note()` to verify the note exists
+1. **Note doesn't exist**: Use `search_notes("{project or "project-name"}", "query")` or `read_note("{project or "project-name"}", "{identifier}")` to verify the note exists
 2. **Invalid identifier format**: Try different identifier formats (title vs permalink)
 3. **Empty or invalid content**: Check that your content is properly formatted
 4. **Server error**: Try the operation again, or use `read_note()` first to verify the note state
 
 ## Troubleshooting steps:
-1. Verify the note exists: `read_note("{identifier}")`
-2. If not found, search for it: `search_notes("{identifier.split("/")[-1]}")`
+1. Verify the note exists: `read_note("{project or "project-name"}", "{identifier}")`
+2. If not found, search for it: `search_notes("{project or "project-name"}", "{identifier.split("/")[-1]}")`
 3. Try again with the correct identifier from the search results"""
 
     # Fallback for other errors
@@ -113,14 +115,14 @@ There was a problem with the edit request to note '{identifier}': {error_message
 Error editing note '{identifier}': {error_message}
 
 ## General troubleshooting:
-1. **Verify the note exists**: Use `read_note("{identifier}")` to check
+1. **Verify the note exists**: Use `read_note("{project or "project-name"}", "{identifier}")` to check
 2. **Check your parameters**: Ensure all required parameters are provided correctly
-3. **Read the note content first**: Use `read_note()` to understand the current structure
+3. **Read the note content first**: Use `read_note("{project or "project-name"}", "{identifier}")` to understand the current structure
 4. **Try a simpler operation**: Start with `append` if other operations fail
 
 ## Need help?
-- Use `search_notes()` to find notes
-- Use `read_note()` to examine content before editing
+- Use `search_notes("{project or "project-name"}", "query")` to find notes
+- Use `read_note("{project or "project-name"}", "identifier")` to examine content before editing
 - Check that identifiers, section headers, and find_text match exactly"""
 
 
@@ -131,15 +133,19 @@ async def edit_note(
     identifier: str,
     operation: str,
     content: str,
+    project: Optional[str] = None,
     section: Optional[str] = None,
     find_text: Optional[str] = None,
     expected_replacements: int = 1,
-    project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """Edit an existing markdown note in the knowledge base.
 
-    This tool allows you to make targeted changes to existing notes without rewriting the entire content.
-    It supports various operations for different editing scenarios.
+    Makes targeted changes to existing notes without rewriting the entire content.
+
+    Project Resolution:
+    Server resolves projects in this order: Single Project Mode → project parameter → default project.
+    If project unknown, use list_memory_projects() or recent_activity() first.
 
     Args:
         identifier: The exact title, permalink, or memory:// URL of the note to edit.
@@ -151,56 +157,64 @@ async def edit_note(
                   - "find_replace": Replace occurrences of find_text with content
                   - "replace_section": Replace content under a specific markdown header
         content: The content to add or use for replacement
+        project: Project name to edit in. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
         section: For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation")
         find_text: For find_replace operation - the text to find and replace
         expected_replacements: For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match)
-        project: Optional project name to delete from. If not provided, uses current active project.
+        context: Optional FastMCP context for performance caching.
 
     Returns:
-        A markdown formatted summary of the edit operation and resulting semantic content
+        A markdown formatted summary of the edit operation and resulting semantic content,
+        including operation details, file path, observations, relations, and project metadata.
 
     Examples:
         # Add new content to end of note
-        edit_note("project-planning", "append", "\\n## New Requirements\\n- Feature X\\n- Feature Y")
+        edit_note("my-project", "project-planning", "append", "\\n## New Requirements\\n- Feature X\\n- Feature Y")
 
         # Add timestamp at beginning (frontmatter-aware)
-        edit_note("meeting-notes", "prepend", "## 2025-05-25 Update\\n- Progress update...\\n\\n")
+        edit_note("work-docs", "meeting-notes", "prepend", "## 2025-05-25 Update\\n- Progress update...\\n\\n")
 
         # Update version number (single occurrence)
-        edit_note("config-spec", "find_replace", "v0.13.0", find_text="v0.12.0")
+        edit_note("api-project", "config-spec", "find_replace", "v0.13.0", find_text="v0.12.0")
 
         # Update version in multiple places with validation
-        edit_note("api-docs", "find_replace", "v2.1.0", find_text="v2.0.0", expected_replacements=3)
+        edit_note("docs-project", "api-docs", "find_replace", "v2.1.0", find_text="v2.0.0", expected_replacements=3)
 
         # Replace text that appears multiple times - validate count first
-        edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5)
+        edit_note("team-docs", "docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5)
 
         # Replace implementation section
-        edit_note("api-spec", "replace_section", "New implementation approach...\\n", section="## Implementation")
+        edit_note("specs", "api-spec", "replace_section", "New implementation approach...\\n", section="## Implementation")
 
         # Replace subsection with more specific header
-        edit_note("docs/setup", "replace_section", "Updated install steps\\n", section="### Installation")
+        edit_note("docs", "docs/setup", "replace_section", "Updated install steps\\n", section="### Installation")
 
         # Using different identifier formats (must be exact matches)
-        edit_note("Meeting Notes", "append", "\\n- Follow up on action items")  # exact title
-        edit_note("docs/meeting-notes", "append", "\\n- Follow up tasks")       # exact permalink
-        edit_note("docs/Meeting Notes", "append", "\\n- Next steps")           # exact folder/title
+        edit_note("work-project", "Meeting Notes", "append", "\\n- Follow up on action items")  # exact title
+        edit_note("work-project", "docs/meeting-notes", "append", "\\n- Follow up tasks")       # exact permalink
 
         # If uncertain about identifier, search first:
-        # search_notes("meeting")  # Find available notes
-        # edit_note("docs/meeting-notes-2025", "append", "content")  # Use exact result
+        # search_notes("work-project", "meeting")  # Find available notes
+        # edit_note("work-project", "docs/meeting-notes-2025", "append", "content")  # Use exact result
 
         # Add new section to document
-        edit_note("project-plan", "replace_section", "TBD - needs research\\n", section="## Future Work")
+        edit_note("planning", "project-plan", "replace_section", "TBD - needs research\\n", section="## Future Work")
 
         # Update status across document (expecting exactly 2 occurrences)
-        edit_note("status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2)
+        edit_note("reports", "status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2)
 
-        # Replace text in a file, specifying project name
-        edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", project="my-project"))
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        ValueError: If operation is invalid or required parameters are missing
+        SecurityError: If identifier attempts path traversal
 
+    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
+        error messages with suggestions if operations fail.
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
@@ -288,16 +302,18 @@ async def edit_note(
             "MCP tool response",
             tool="edit_note",
             operation=operation,
+            project=active_project.name,
             permalink=result.permalink,
             observations_count=len(result.observations),
             relations_count=len(result.relations),
             status_code=response.status_code,
         )
 
-        return "\n".join(summary)
+        result = "\n".join(summary)
+        return add_project_metadata(result, active_project.name)
 
     except Exception as e:
         logger.error(f"Error editing note: {e}")
         return _format_error_response(
-            str(e), operation, identifier, find_text, expected_replacements
+            str(e), operation, identifier, find_text, expected_replacements, active_project.name
         )

basic_memory/mcp/tools/headers.py

@@ -0,0 +1,44 @@
+from httpx._types import (
+    HeaderTypes,
+)
+from loguru import logger
+from fastmcp.server.dependencies import get_http_headers
+
+
+def inject_auth_header(headers: HeaderTypes | None = None) -> HeaderTypes:
+    """
+    Inject JWT token from FastMCP context into headers if available.
+
+    Args:
+        headers: Existing headers dict or None
+
+    Returns:
+        Headers dict with Authorization header added if JWT is available
+    """
+    # Start with existing headers or empty dict
+    if headers is None:
+        headers = {}
+    elif not isinstance(headers, dict):
+        # Convert other header types to dict
+        headers = dict(headers)  # type: ignore
+    else:
+        # Make a copy to avoid modifying the original
+        headers = headers.copy()
+
+    http_headers = get_http_headers()
+
+    # Log only non-sensitive header keys for debugging
+    if logger.opt(lazy=True).debug:
+        sensitive_headers = {"authorization", "cookie", "x-api-key", "x-auth-token", "api-key"}
+        safe_headers = {k for k in http_headers.keys() if k.lower() not in sensitive_headers}
+        logger.debug(f"HTTP headers present: {list(safe_headers)}")
+
+    authorization = http_headers.get("Authorization") or http_headers.get("authorization")
+    if authorization:
+        headers["Authorization"] = authorization  # type: ignore
+        # Log only that auth was injected, not the token value
+        logger.debug("Injected authorization header into request")
+    else:
+        logger.debug("No authorization header found in request")
+
+    return headers

basic_memory/mcp/tools/list_directory.py

@@ -3,9 +3,10 @@
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
-from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.project_context import get_active_project
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_get
 
@@ -18,6 +19,7 @@ async def list_directory(
     depth: int = 1,
     file_name_glob: Optional[str] = None,
     project: Optional[str] = None,
+    context: Context | None = None,
 ) -> str:
     """List directory contents from the knowledge base with optional filtering.
 
@@ -32,7 +34,10 @@ async def list_directory(
                Higher values show subdirectory contents recursively
         file_name_glob: Optional glob pattern for filtering file names
                        Examples: "*.md", "*meeting*", "project_*"
-        project: Optional project name to delete from. If not provided, uses current active project.
+        project: Project name to list directory from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        context: Optional FastMCP context for performance caching.
+
     Returns:
         Formatted listing of directory contents with file metadata
 
@@ -43,8 +48,8 @@ async def list_directory(
         # List specific folder
         list_directory(dir_name="/projects")
 
-        # Find all Python files
-        list_directory(file_name_glob="*.py")
+        # Find all markdown files
+        list_directory(file_name_glob="*.md")
 
         # Deep exploration of research folder
         list_directory(dir_name="/research", depth=3)
@@ -52,10 +57,13 @@ async def list_directory(
         # Find meeting notes in projects folder
         list_directory(dir_name="/projects", file_name_glob="*meeting*")
 
-        # Find meeting notes in a specific project
-        list_directory(dir_name="/projects", file_name_glob="*meeting*", project="work-project")
+        # Explicit project specification
+        list_directory(project="work-docs", dir_name="/projects")
+
+    Raises:
+        ToolError: If project doesn't exist or directory path is invalid
     """
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     # Prepare query parameters
@@ -66,7 +74,9 @@ async def list_directory(
     if file_name_glob:
         params["file_name_glob"] = file_name_glob
 
-    logger.debug(f"Listing directory '{dir_name}' with depth={depth}, glob='{file_name_glob}'")
+    logger.debug(
+        f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
+    )
 
     # Call the API endpoint
     response = await call_get(

basic_memory/mcp/tools/move_note.py

@@ -4,11 +4,12 @@ from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
+from fastmcp import Context
 
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.tools.utils import call_post, call_get
-from basic_memory.mcp.project_session import get_active_project
+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.utils import validate_project_path
@@ -64,42 +65,37 @@ def _format_cross_project_error_response(
     """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}")
+        # 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}")
         
-        # 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.
+        Use `list_memory_projects()` to see all available projects.
         """).strip()
 
 
@@ -130,20 +126,16 @@ def _format_potential_cross_project_guidance(
         # 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}")
+        # 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_projects()
+        list_memory_projects()
         ```
         """).strip()
 
@@ -171,7 +163,7 @@ def _format_move_error_response(error_message: str, identifier: str, destination
                - 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. **Check current project**: Use `get_current_project()` to verify you're in the right project
+            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:
@@ -248,9 +240,8 @@ You don't have permission to move '{identifier}': {error_message}
 3. **Check file locks**: The file might be open in another application
 
 ## Alternative actions:
-- Check current project: `get_current_project()`
-- Switch projects if needed: `switch_project("project-name")`
-- Try copying content instead: `read_note("{identifier}")` then `write_note()` to new location"""
+- 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 (
@@ -352,18 +343,25 @@ 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: Optional project name (defaults to current session project)
+        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
+        Success message with move details and project information.
 
     Examples:
         # Move to new folder (exact title match)
@@ -372,15 +370,22 @@ async def move_note(
         # Move by exact permalink
         move_note("my-note-permalink", "archive/old-notes/my-note.md")
 
-        # Specify project with exact identifier
-        move_note("My Note", "archive/my-note.md", project="work-project")
+        # 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
 
-    Note: This operation moves notes within the specified project only. Moving notes
-    between different projects is not currently supported.
+    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
@@ -389,9 +394,9 @@ async def move_note(
     - Re-indexes the entity for search
     - Maintains all observations and relations
     """
-    logger.debug(f"Moving note: {identifier} to {destination_path}")
+    logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")
 
-    active_project = get_active_project(project)
+    active_project = await get_active_project(client, project, context)
     project_url = active_project.project_url
 
     # Validate destination path to prevent path traversal attacks
@@ -424,6 +429,79 @@ move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in dest
         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:
+        # Fetch source entity information to get the current file extension
+        url = f"{project_url}/knowledge/entities/{identifier}"
+        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:
+        # Fetch source entity information
+        url = f"{project_url}/knowledge/entities/{identifier}"
+        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:
         # Prepare move request
         move_data = {