basic-memory 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

basic_memory/mcp/tools/move_note.py

@@ -0,0 +1,299 @@
+"""Move note tool for Basic Memory MCP server."""
+
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+
+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.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.",
+)
+async def move_note(
+    identifier: str,
+    destination_path: str,
+    project: Optional[str] = None,
+) -> str:
+    """Move a note to a new file location within the same project.
+
+    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)
+
+    Returns:
+        Success message with move details
+
+    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")
+
+        # 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.
+
+    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
+    """
+    logger.debug(f"Moving note: {identifier} to {destination_path}")
+
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
+    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

@@ -0,0 +1,332 @@
+"""Project management tools for Basic Memory MCP server.
+
+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
+
+from basic_memory.config import get_project_config
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_session import session, add_project_metadata
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_get, call_put, call_post, call_delete
+from basic_memory.schemas import ProjectInfoResponse
+from basic_memory.schemas.project_info import ProjectList, ProjectStatusResponse, ProjectInfoRequest
+
+
+@mcp.tool()
+async def list_projects(ctx: Context | None = None) -> str:
+    """List all available projects with their status.
+
+    Shows all Basic Memory projects that are available, indicating which one
+    is currently active and which is the default.
+
+    Returns:
+        Formatted list of projects with status indicators
+
+    Example:
+        list_projects()
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info("Listing all available projects")
+
+    # Get projects from API
+    response = await call_get(client, "/projects/projects")
+    project_list = ProjectList.model_validate(response.json())
+
+    current = session.get_current_project()
+
+    result = "Available projects:\n"
+
+    for project in project_list.projects:
+        indicators = []
+        if project.name == current:
+            indicators.append("current")
+        if project.is_default:
+            indicators.append("default")
+
+        if indicators:
+            result += f"• {project.name} ({', '.join(indicators)})\n"
+        else:
+            result += f"• {project.name}\n"
+
+    return add_project_metadata(result, current)
+
+
+@mcp.tool()
+async def switch_project(project_name: str, ctx: Context | None = None) -> str:
+    """Switch to a different project context.
+
+    Changes the active project context for all subsequent tool calls.
+    Shows a project summary after switching successfully.
+
+    Args:
+        project_name: Name of the project to switch to
+
+    Returns:
+        Confirmation message with project summary
+
+    Example:
+        switch_project("work-notes")
+        switch_project("personal-journal")
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Switching to project: {project_name}")
+
+    current_project = session.get_current_project()
+    try:
+        # Validate project exists by getting project list
+        response = await call_get(client, "/projects/projects")
+        project_list = ProjectList.model_validate(response.json())
+
+        # Check if project exists
+        project_exists = any(p.name == project_name for p in project_list.projects)
+        if not project_exists:
+            available_projects = [p.name for p in project_list.projects]
+            return f"Error: Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
+
+        # Switch to the project
+        session.set_current_project(project_name)
+        current_project = session.get_current_project()
+        project_config = get_project_config(current_project)
+
+        # Get project info to show summary
+        try:
+            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"
+            result += "Project Summary:\n"
+            result += f"• {project_info.statistics.total_entities} entities\n"
+            result += f"• {project_info.statistics.total_observations} observations\n"
+            result += f"• {project_info.statistics.total_relations} relations\n"
+
+        except Exception as e:
+            # If we can't get project info, still confirm the switch
+            logger.warning(f"Could not get project info for {project_name}: {e}")
+            result = f"✓ Switched to {project_name} project\n\n"
+            result += "Project summary unavailable.\n"
+
+        return add_project_metadata(result, project_name)
+
+    except Exception as e:
+        logger.error(f"Error switching to project {project_name}: {e}")
+        # Revert to previous project on error
+        session.set_current_project(current_project)
+
+        # 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()
+async def get_current_project(ctx: Context | None = None) -> str:
+    """Show the currently active project and basic stats.
+
+    Displays which project is currently active and provides basic information
+    about it.
+
+    Returns:
+        Current project name and basic statistics
+
+    Example:
+        get_current_project()
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info("Getting current project information")
+
+    current_project = session.get_current_project()
+    project_config = get_project_config(current_project)
+    result = f"Current project: {current_project}\n\n"
+
+    # get project stats
+    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"
+    result += f"• {project_info.statistics.total_observations} observations\n"
+    result += f"• {project_info.statistics.total_relations} relations\n"
+
+    default_project = session.get_default_project()
+    if current_project != default_project:
+        result += f"• Default project: {default_project}\n"
+
+    return add_project_metadata(result, current_project)
+
+
+@mcp.tool()
+async def set_default_project(project_name: str, ctx: Context | None = None) -> str:
+    """Set default project in config. Requires restart to take effect.
+
+    Updates the configuration to use a different default project. This change
+    only takes effect after restarting the Basic Memory server.
+
+    Args:
+        project_name: Name of the project to set as default
+
+    Returns:
+        Confirmation message about config update
+
+    Example:
+        set_default_project("work-notes")
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Setting default project to: {project_name}")
+
+    # Call API to set default project
+    response = await call_put(client, f"/projects/{project_name}/default")
+    status_response = ProjectStatusResponse.model_validate(response.json())
+
+    result = f"✓ {status_response.message}\n\n"
+    result += "Restart Basic Memory for this change to take effect:\n"
+    result += "basic-memory mcp\n"
+
+    if status_response.old_project:
+        result += f"\nPrevious default: {status_response.old_project.name}\n"
+
+    return add_project_metadata(result, session.get_current_project())
+
+
+@mcp.tool()
+async def create_project(
+    project_name: str, project_path: str, set_default: bool = False, ctx: Context | None = None
+) -> str:
+    """Create a new Basic Memory project.
+
+    Creates a new project with the specified name and path. The project directory
+    will be created if it doesn't exist. Optionally sets the new project as default.
+
+    Args:
+        project_name: Name for the new project (must be unique)
+        project_path: File system path where the project will be stored
+        set_default: Whether to set this project as the default (optional, defaults to False)
+
+    Returns:
+        Confirmation message with project details
+
+    Example:
+        create_project("my-research", "~/Documents/research")
+        create_project("work-notes", "/home/user/work", set_default=True)
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Creating project: {project_name} at {project_path}")
+
+    # Create the project request
+    project_request = ProjectInfoRequest(
+        name=project_name, path=project_path, set_default=set_default
+    )
+
+    # Call API to create project
+    response = await call_post(client, "/projects/projects", json=project_request.model_dump())
+    status_response = ProjectStatusResponse.model_validate(response.json())
+
+    result = f"✓ {status_response.message}\n\n"
+
+    if status_response.new_project:
+        result += "Project Details:\n"
+        result += f"• Name: {status_response.new_project.name}\n"
+        result += f"• Path: {status_response.new_project.path}\n"
+
+        if set_default:
+            result += "• Set as default project\n"
+
+    result += "\nProject is now available for use.\n"
+
+    # If project was set as default, update session
+    if set_default:
+        session.set_current_project(project_name)
+
+    return add_project_metadata(result, session.get_current_project())
+
+
+@mcp.tool()
+async def delete_project(project_name: str, ctx: Context | None = None) -> str:
+    """Delete a Basic Memory project.
+
+    Removes a project from the configuration and database. This does NOT delete
+    the actual files on disk - only removes the project from Basic Memory's
+    configuration and database records.
+
+    Args:
+        project_name: Name of the project to delete
+
+    Returns:
+        Confirmation message about project deletion
+
+    Example:
+        delete_project("old-project")
+
+    Warning:
+        This action cannot be undone. The project will need to be re-added
+        to access its content through Basic Memory again.
+    """
+    if ctx:  # pragma: no cover
+        await ctx.info(f"Deleting project: {project_name}")
+
+    current_project = session.get_current_project()
+
+    # Check if trying to delete current project
+    if project_name == current_project:
+        raise ValueError(
+            f"Cannot delete the currently active project '{project_name}'. Switch to a different project first."
+        )
+
+    # Get project info before deletion to validate it exists
+    response = await call_get(client, "/projects/projects")
+    project_list = ProjectList.model_validate(response.json())
+
+    # Check if project exists
+    project_exists = any(p.name == project_name for p in project_list.projects)
+    if not project_exists:
+        available_projects = [p.name for p in project_list.projects]
+        raise ValueError(
+            f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
+        )
+
+    # Call API to delete project
+    response = await call_delete(client, f"/projects/{project_name}")
+    status_response = ProjectStatusResponse.model_validate(response.json())
+
+    result = f"✓ {status_response.message}\n\n"
+
+    if status_response.old_project:
+        result += "Removed project details:\n"
+        result += f"• Name: {status_response.old_project.name}\n"
+        if hasattr(status_response.old_project, "path"):
+            result += f"• Path: {status_response.old_project.path}\n"
+
+    result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
+    result += "Re-add the project to access its content again.\n"
+
+    return add_project_metadata(result, session.get_current_project())

basic_memory/mcp/tools/read_content.py

@@ -5,17 +5,19 @@ supporting various file types including text, images, and other binary files.
 Files are read directly without any knowledge graph processing.
 """
 
+from typing import Optional
+import base64
+import io
+
 from loguru import logger
+from PIL import Image as PILImage
 
 from basic_memory.mcp.server import mcp
 from basic_memory.mcp.async_client import client
 from basic_memory.mcp.tools.utils import call_get
+from basic_memory.mcp.project_session import get_active_project
 from basic_memory.schemas.memory import memory_url_path
 
-import base64
-import io
-from PIL import Image as PILImage
-
 
 def calculate_target_params(content_length):
     """Calculate initial quality and size based on input file size"""
@@ -144,7 +146,7 @@ def optimize_image(img, content_length, max_output_bytes=350000):
 
 
 @mcp.tool(description="Read a file's raw content by path or permalink")
-async def read_content(path: str) -> dict:
+async def read_content(path: str, project: Optional[str] = None) -> dict:
     """Read a file's raw content by path or permalink.
 
     This tool provides direct access to file content in the knowledge base,
@@ -158,6 +160,7 @@ async def read_content(path: str) -> dict:
             - A regular file path (docs/example.md)
             - A memory URL (memory://docs/example)
             - A permalink (docs/example)
+        project: Optional project name to read from. If not provided, uses current active project.
 
     Returns:
         A dictionary with the file content and metadata:
@@ -175,11 +178,17 @@ async def read_content(path: str) -> dict:
 
         # Read using memory URL
         content = await read_file("memory://docs/architecture")
+
+        # Read from specific project
+        content = await read_content("docs/example.md", project="work-project")
     """
     logger.info("Reading file", path=path)
 
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
     url = memory_url_path(path)
-    response = await call_get(client, f"/resource/{url}")
+    response = await call_get(client, f"{project_url}/resource/{url}")
     content_type = response.headers.get("content-type", "application/octet-stream")
     content_length = int(response.headers.get("content-length", 0))