basic-memory 0.13.0b4__py3-none-any.whl → 0.13.0b5__py3-none-any.whl

basic_memory/mcp/tools/move_note.py

@@ -1,5 +1,6 @@
 """Move note tool for Basic Memory MCP server."""
 
+from textwrap import dedent
 from typing import Optional
 
 from loguru import logger
@@ -11,6 +12,203 @@ from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas import EntityResponse
 
 
+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. **Check current project**: Use `get_current_project()` to verify you're in the right 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:
+- 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"""
+
+    # 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.",
 )
@@ -22,7 +220,9 @@ async def move_note(
     """Move a note to a new file location within the same project.
 
     Args:
-        identifier: Entity identifier (title, permalink, or memory:// URL)
+        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)
 
@@ -30,9 +230,18 @@ async def move_note(
         Success message with move details
 
     Examples:
-        - Move to new folder: move_note("My Note", "work/notes/my-note.md")
-        - Move by permalink: move_note("my-note-permalink", "archive/old-notes/my-note.md")
-        - Specify project: move_note("My Note", "archive/my-note.md", project="work-project")
+        # 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")
+
+        # Specify project with exact identifier
+        move_note("My Note", "archive/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.
@@ -49,39 +258,42 @@ async def move_note(
     active_project = get_active_project(project)
     project_url = active_project.project_url
 
-    # Prepare move request
-    move_data = {
-        "identifier": identifier,
-        "destination_path": destination_path,
-        "project": active_project.name,
-    }
-
-    # Call the move API endpoint
-    url = f"{project_url}/knowledge/move"
-    response = await call_post(client, url, json=move_data)
-    result = EntityResponse.model_validate(response.json())
-
-    # 10. 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} -->",
-    ]
-
-    # Return the response text which contains the formatted success message
-    result = "\n".join(result_lines)
-
-    # Log the operation
-    logger.info(
-        "Move note completed",
-        identifier=identifier,
-        destination_path=destination_path,
-        project=active_project.name,
-        status_code=response.status_code,
-    )
-
-    return result
+    try:
+        # Prepare move request
+        move_data = {
+            "identifier": identifier,
+            "destination_path": destination_path,
+            "project": active_project.name,
+        }
+
+        # Call the move API endpoint
+        url = f"{project_url}/knowledge/move"
+        response = await call_post(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)

basic_memory/mcp/tools/project_management.py

@@ -4,6 +4,8 @@ These tools allow users to switch between projects, list available projects,
 and manage project context during conversations.
 """
 
+from textwrap import dedent
+
 from fastmcp import Context
 from loguru import logger
 
@@ -94,7 +96,11 @@ async def switch_project(project_name: str, ctx: Context | None = None) -> str:
 
         # Get project info to show summary
         try:
-            response = await call_get(client, f"{project_config.project_url}/project/info")
+            response = await call_get(
+                client,
+                f"{project_config.project_url}/project/info",
+                params={"project_name": project_name},
+            )
             project_info = ProjectInfoResponse.model_validate(response.json())
 
             result = f"✓ Switched to {project_name} project\n\n"
@@ -115,7 +121,29 @@ async def switch_project(project_name: str, ctx: Context | None = None) -> str:
         logger.error(f"Error switching to project {project_name}: {e}")
         # Revert to previous project on error
         session.set_current_project(current_project)
-        raise e
+
+        # Return user-friendly error message instead of raising exception
+        return dedent(f"""
+            # Project Switch Failed
+
+            Could not switch to project '{project_name}': {str(e)}
+
+            ## Current project: {current_project}
+            Your session remains on the previous project.
+
+            ## Troubleshooting:
+            1. **Check available projects**: Use `list_projects()` to see valid project names
+            2. **Verify spelling**: Ensure the project name is spelled correctly
+            3. **Check permissions**: Verify you have access to the requested project
+            4. **Try again**: The error might be temporary
+
+            ## Available options:
+            - See all projects: `list_projects()`
+            - Stay on current project: `get_current_project()`
+            - Try different project: `switch_project("correct-project-name")`
+
+            If the project should exist but isn't listed, send a message to support@basicmachines.co.
+            """).strip()
 
 
 @mcp.tool()
@@ -139,7 +167,11 @@ async def get_current_project(ctx: Context | None = None) -> str:
     result = f"Current project: {current_project}\n\n"
 
     # get project stats
-    response = await call_get(client, f"{project_config.project_url}/project/info")
+    response = await call_get(
+        client,
+        f"{project_config.project_url}/project/info",
+        params={"project_name": current_project},
+    )
     project_info = ProjectInfoResponse.model_validate(response.json())
 
     result += f"• {project_info.statistics.total_entities} entities\n"

basic_memory/mcp/tools/read_note.py

@@ -52,6 +52,13 @@ async def read_note(
         read_note("Meeting Notes", project="work-project")
     """
 
+    # Check migration status and wait briefly if needed
+    from basic_memory.mcp.tools.utils import wait_for_migration_or_return_status
+
+    migration_status = await wait_for_migration_or_return_status(timeout=5.0)
+    if migration_status:  # pragma: no cover
+        return f"# System Status\n\n{migration_status}\n\nPlease wait for migration to complete before reading notes."
+
     active_project = get_active_project(project)
     project_url = active_project.project_url
 
@@ -114,7 +121,7 @@ def format_not_found_message(identifier: str) -> str:
     return dedent(f"""
         # Note Not Found: "{identifier}"
         
-        I couldn't find any notes matching "{identifier}". Here are some suggestions:
+        I searched for "{identifier}" using multiple methods (direct lookup, title search, and text search) but couldn't find any matching notes. Here are some suggestions:
         
         ## Check Identifier Type
         - If you provided a title, try using the exact permalink instead
@@ -160,7 +167,7 @@ def format_related_results(identifier: str, results) -> str:
     message = dedent(f"""
         # Note Not Found: "{identifier}"
         
-        I couldn't find an exact match for "{identifier}", but I found some related notes:
+        I searched for "{identifier}" using direct lookup and title search but couldn't find an exact match. However, I found some related notes through text search:
         
         """)
 

basic_memory/mcp/tools/search.py

@@ -1,5 +1,6 @@
 """Search tools for Basic Memory MCP server."""
 
+from textwrap import dedent
 from typing import List, Optional
 
 from loguru import logger
@@ -11,6 +12,162 @@ from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.search import SearchItemType, SearchQuery, SearchResponse
 
 
+def _format_search_error_response(error_message: str, query: str, search_type: str = "text") -> str:
+    """Format helpful error responses for search failures that guide users to successful searches."""
+
+    # FTS5 syntax errors
+    if "syntax error" in error_message.lower() or "fts5" in error_message.lower():
+        clean_query = (
+            query.replace('"', "")
+            .replace("(", "")
+            .replace(")", "")
+            .replace("+", "")
+            .replace("*", "")
+        )
+        return dedent(f"""
+            # Search Failed - Invalid Syntax
+
+            The search query '{query}' contains invalid syntax that the search engine cannot process.
+
+            ## Common syntax issues:
+            1. **Special characters**: Characters like `+`, `*`, `"`, `(`, `)` have special meaning in search
+            2. **Unmatched quotes**: Make sure quotes are properly paired
+            3. **Invalid operators**: Check AND, OR, NOT operators are used correctly
+
+            ## How to fix:
+            1. **Simplify your search**: Try using simple words instead: `{clean_query}`
+            2. **Remove special characters**: Use alphanumeric characters and spaces
+            3. **Use basic boolean operators**: `word1 AND word2`, `word1 OR word2`, `word1 NOT word2`
+
+            ## Examples of valid searches:
+            - Simple text: `project planning`
+            - Boolean AND: `project AND planning`
+            - Boolean OR: `meeting OR discussion`
+            - Boolean NOT: `project NOT archived`
+            - Grouped: `(project OR planning) AND notes`
+
+            ## Try again with:
+            ```
+            search_notes("INSERT_CLEAN_QUERY_HERE")
+            ```
+
+            Replace INSERT_CLEAN_QUERY_HERE with your simplified search terms.
+            """).strip()
+
+    # Project not found errors (check before general "not found")
+    if "project not found" in error_message.lower():
+        return dedent(f"""
+            # Search Failed - Project Not Found
+
+            The current project is not accessible or doesn't exist: {error_message}
+
+            ## How to resolve:
+            1. **Check available projects**: `list_projects()`
+            2. **Switch to valid project**: `switch_project("valid-project-name")`
+            3. **Verify project setup**: Ensure your project is properly configured
+
+            ## Current session info:
+            - Check current project: `get_current_project()`
+            - See available projects: `list_projects()`
+            """).strip()
+
+    # No results found
+    if "no results" in error_message.lower() or "not found" in error_message.lower():
+        simplified_query = (
+            " ".join(query.split()[:2])
+            if len(query.split()) > 2
+            else query.split()[0]
+            if query.split()
+            else "notes"
+        )
+        return dedent(f"""
+            # Search Complete - No Results Found
+
+            No content found matching '{query}' in the current project.
+
+            ## Suggestions to try:
+            1. **Broaden your search**: Try fewer or more general terms
+               - Instead of: `{query}`
+               - Try: `{simplified_query}`
+
+            2. **Check spelling**: Verify terms are spelled correctly
+            3. **Try different search types**:
+               - Text search: `search_notes("{query}", search_type="text")`
+               - Title search: `search_notes("{query}", search_type="title")`
+               - Permalink search: `search_notes("{query}", search_type="permalink")`
+
+            4. **Use boolean operators**:
+               - Try OR search for broader results
+
+            ## Check what content exists:
+            - Recent activity: `recent_activity(timeframe="7d")`
+            - List files: `list_directory("/")`
+            - Browse by folder: `list_directory("/notes")` or `list_directory("/docs")`
+            """).strip()
+
+    # Server/API errors
+    if "server error" in error_message.lower() or "internal" in error_message.lower():
+        return dedent(f"""
+            # Search Failed - Server Error
+
+            The search service encountered an error while processing '{query}': {error_message}
+
+            ## Immediate steps:
+            1. **Try again**: The error might be temporary
+            2. **Simplify the query**: Use simpler search terms
+            3. **Check project status**: Ensure your project is properly synced
+
+            ## Alternative approaches:
+            - Browse files directly: `list_directory("/")`
+            - Check recent activity: `recent_activity(timeframe="7d")`
+            - Try a different search type: `search_notes("{query}", search_type="title")`
+
+            ## If the problem persists:
+            The search index might need to be rebuilt. Send a message to support@basicmachines.co or check the project sync status.
+            """).strip()
+
+    # Permission/access errors
+    if (
+        "permission" in error_message.lower()
+        or "access" in error_message.lower()
+        or "forbidden" in error_message.lower()
+    ):
+        return f"""# Search Failed - Access Error
+
+You don't have permission to search in the current project: {error_message}
+
+## How to resolve:
+1. **Check your project access**: Verify you have read permissions for this project
+2. **Switch projects**: Try searching in a different project you have access to
+3. **Check authentication**: You might need to re-authenticate
+
+## Alternative actions:
+- List available projects: `list_projects()`
+- Switch to accessible project: `switch_project("project-name")`
+- Check current project: `get_current_project()`"""
+
+    # Generic fallback
+    return f"""# Search Failed
+
+Error searching for '{query}': {error_message}
+
+## General troubleshooting:
+1. **Check your query**: Ensure it uses valid search syntax
+2. **Try simpler terms**: Use basic words without special characters
+3. **Verify project access**: Make sure you can access the current project
+4. **Check recent activity**: `recent_activity(timeframe="7d")` to see if content exists
+
+## Alternative approaches:
+- Browse files: `list_directory("/")`
+- Try different search type: `search_notes("{query}", search_type="title")`
+- Search with filters: `search_notes("{query}", types=["entity"])`
+
+## Need help?
+- View recent changes: `recent_activity()`
+- List projects: `list_projects()` 
+- Check current project: `get_current_project()`"""
+
+
 @mcp.tool(
     description="Search across all content in the knowledge base.",
 )
@@ -23,7 +180,7 @@ async def search_notes(
     entity_types: Optional[List[str]] = None,
     after_date: Optional[str] = None,
     project: Optional[str] = None,
-) -> SearchResponse:
+) -> SearchResponse | str:
     """Search across all content in the knowledge base.
 
     This tool searches the knowledge base using full-text search, pattern matching,
@@ -113,10 +270,25 @@ async def search_notes(
     project_url = active_project.project_url
 
     logger.info(f"Searching for {search_query}")
-    response = await call_post(
-        client,
-        f"{project_url}/search/",
-        json=search_query.model_dump(),
-        params={"page": page, "page_size": page_size},
-    )
-    return SearchResponse.model_validate(response.json())
+
+    try:
+        response = await call_post(
+            client,
+            f"{project_url}/search/",
+            json=search_query.model_dump(),
+            params={"page": page, "page_size": page_size},
+        )
+        result = SearchResponse.model_validate(response.json())
+
+        # Check if we got no results and provide helpful guidance
+        if not result.results:
+            logger.info(f"Search returned no results for query: {query}")
+            # Don't treat this as an error, but the user might want guidance
+            # We return the empty result as normal - the user can decide if they need help
+
+        return result
+
+    except Exception as e:
+        logger.error(f"Search failed for query '{query}': {e}")
+        # Return formatted error message as string for better user experience
+        return _format_search_error_response(str(e), query, search_type)