basic-memory 0.17.1__py3-none-any.whl

basic_memory/mcp/tools/delete_note.py

@@ -0,0 +1,242 @@
+from textwrap import dedent
+from typing import Optional
+
+from loguru import logger
+from fastmcp import Context
+from mcp.server.fastmcp.exceptions import ToolError
+
+from basic_memory.mcp.project_context import get_active_project
+from basic_memory.mcp.tools.utils import call_delete, resolve_entity_id
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.async_client import get_client
+from basic_memory.telemetry import track_mcp_tool
+from basic_memory.schemas import DeleteEntitiesResponse
+
+
+def _format_delete_error_response(project: str, error_message: str, identifier: str) -> str:
+    """Format helpful error responses for delete failures that guide users to successful deletions."""
+
+    # 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"""
+            # Delete Failed - Note Not Found
+
+            The note '{identifier}' could not be found for deletion in {project}.
+
+            ## This might mean:
+            1. **Already deleted**: The note may have been deleted previously
+            2. **Wrong identifier**: The identifier format might be incorrect
+            3. **Different project**: The note might be in a different project
+
+            ## How to verify:
+            1. **Search for the note**: Use `search_notes("{project}", "{search_term}")` to find it
+            2. **Try different formats**:
+               - If you used a permalink like "folder/note-title", try just the title: "{title_format}"
+               - If you used a title, try the permalink format: "{permalink_format}"
+
+            3. **Check if already deleted**: Use `list_directory("/")` to see what notes exist
+            4. **List notes in project**: Use `list_directory("/")` to see what notes exist in the current project
+
+            ## If the note actually exists:
+            ```
+            # First, find the correct identifier:
+            search_notes("{project}", "{identifier}")
+
+            # Then delete using the correct identifier:
+            delete_note("{project}", "correct-identifier-from-search")
+            ```
+
+            ## If you want to delete multiple similar notes:
+            Use search to find all related notes and delete them one by one.
+            """).strip()
+
+    # Permission/access errors
+    if (
+        "permission" in error_message.lower()
+        or "access" in error_message.lower()
+        or "forbidden" in error_message.lower()
+    ):
+        return f"""# Delete Failed - Permission Error
+
+You don't have permission to delete '{identifier}': {error_message}
+
+## How to resolve:
+1. **Check permissions**: Verify you have delete/write access to this project
+2. **File locks**: The note might be open in another application
+3. **Project access**: Ensure you're in the correct project with proper permissions
+
+## Alternative actions:
+- List available projects: `list_memory_projects()`
+- Specify the correct project: `delete_note("{identifier}", project="project-name")`
+- Verify note exists first: `read_note("{identifier}", project="project-name")`
+
+## If you have read-only access:
+Ask someone with write access to delete the note."""
+
+    # Server/filesystem errors
+    if (
+        "server error" in error_message.lower()
+        or "filesystem" in error_message.lower()
+        or "disk" in error_message.lower()
+    ):
+        return f"""# Delete Failed - System Error
+
+A system error occurred while deleting '{identifier}': {error_message}
+
+## Immediate steps:
+1. **Try again**: The error might be temporary
+2. **Check file status**: Verify the file isn't locked or in use
+3. **Check disk space**: Ensure the system has adequate storage
+
+## Troubleshooting:
+- Verify note exists: `read_note("{project}","{identifier}")`
+- Try again in a few moments
+
+## If problem persists:
+Send a message to support@basicmachines.co - there may be a filesystem or database issue."""
+
+    # Database/sync errors
+    if "database" in error_message.lower() or "sync" in error_message.lower():
+        return f"""# Delete Failed - Database Error
+
+A database error occurred while deleting '{identifier}': {error_message}
+
+## This usually means:
+1. **Sync conflict**: The file system and database are out of sync
+2. **Database lock**: Another operation is accessing the database
+3. **Corrupted entry**: The database entry might be corrupted
+
+## Steps to resolve:
+1. **Try again**: Wait a moment and retry the deletion
+2. **Check note status**: `read_note("{project}","{identifier}")` to see current state
+3. **Manual verification**: Use `list_directory()` to see if file still exists
+
+## If the note appears gone but database shows it exists:
+Send a message to support@basicmachines.co - a manual database cleanup may be needed."""
+
+    # Generic fallback
+    return f"""# Delete Failed
+
+Error deleting note '{identifier}': {error_message}
+
+## General troubleshooting:
+1. **Verify the note exists**: `read_note("{project}", "{identifier}")` or `search_notes("{project}", "{identifier}")`
+2. **Check permissions**: Ensure you can edit/delete files in this project
+3. **Try again**: The error might be temporary
+4. **Check project**: Make sure you're in the correct project
+
+## Step-by-step approach:
+```
+# 1. Confirm note exists and get correct identifier
+search_notes("{project}", "{identifier}")
+
+# 2. Read the note to verify access
+read_note("{project}", "correct-identifier-from-search")
+
+# 3. Try deletion with correct identifier
+delete_note("{project}", "correct-identifier-from-search")
+```
+
+## Alternative approaches:
+- Check what notes exist: `list_directory("{project}", "/")`
+
+## Need help?
+If the note should be deleted but the operation keeps failing, send a message to support@basicmemory.com."""
+
+
+@mcp.tool(description="Delete a note by title or permalink")
+async def delete_note(
+    identifier: str, project: Optional[str] = None, context: Context | None = None
+) -> bool | str:
+    """Delete a note from the knowledge base.
+
+    Permanently removes a note from the specified project. The note is identified
+    by title or permalink. If the note doesn't exist, the operation returns False
+    without error. If deletion fails due to other issues, helpful error messages are provided.
+
+    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:
+        project: Project name to delete from. Optional - server will resolve using hierarchy.
+                If unknown, use list_memory_projects() to discover available projects.
+        identifier: Note title or permalink to delete
+                   Can be a title like "Meeting Notes" or permalink like "notes/meeting-notes"
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        True if note was successfully deleted, False if note was not found.
+        On errors, returns a formatted string with helpful troubleshooting guidance.
+
+    Examples:
+        # Delete by title
+        delete_note("my-project", "Meeting Notes: Project Planning")
+
+        # Delete by permalink
+        delete_note("work-docs", "notes/project-planning")
+
+        # Delete with exact path
+        delete_note("research", "experiments/ml-model-results")
+
+        # Common usage pattern
+        if delete_note("my-project", "old-draft"):
+            print("Note deleted successfully")
+        else:
+            print("Note not found or already deleted")
+
+    Raises:
+        HTTPError: If project doesn't exist or is inaccessible
+        SecurityError: If identifier attempts path traversal
+
+    Warning:
+        This operation is permanent and cannot be undone. The note file
+        will be removed from the filesystem and all references will be lost.
+
+    Note:
+        If the note is not found, this function provides helpful error messages
+        with suggestions for finding the correct identifier, including search
+        commands and alternative formats to try.
+    """
+    track_mcp_tool("delete_note")
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+
+        try:
+            # Resolve identifier to entity ID
+            entity_id = await resolve_entity_id(client, active_project.id, identifier)
+        except ToolError as e:
+            # If entity not found, return False (note doesn't exist)
+            if "Entity not found" in str(e) or "not found" in str(e).lower():
+                logger.warning(f"Note not found for deletion: {identifier}")
+                return False
+            # For other resolution errors, return formatted error message
+            logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
+            return _format_delete_error_response(active_project.name, str(e), identifier)
+
+        try:
+            # Call the DELETE endpoint
+            response = await call_delete(
+                client, f"/v2/projects/{active_project.id}/knowledge/entities/{entity_id}"
+            )
+            result = DeleteEntitiesResponse.model_validate(response.json())
+
+            if result.deleted:
+                logger.info(
+                    f"Successfully deleted note: {identifier} in project: {active_project.name}"
+                )
+                return True
+            else:
+                logger.warning(f"Delete operation completed but note was not deleted: {identifier}")
+                return False
+
+        except Exception as e:  # pragma: no cover
+            logger.error(f"Delete failed for '{identifier}': {e}, project: {active_project.name}")
+            # Return formatted error message for better user experience
+            return _format_delete_error_response(active_project.name, str(e), identifier)

basic_memory/mcp/tools/edit_note.py

@@ -0,0 +1,324 @@
+"""Edit note tool for Basic Memory MCP server."""
+
+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.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, resolve_entity_id
+from basic_memory.telemetry import track_mcp_tool
+from basic_memory.schemas import EntityResponse
+
+
+def _format_error_response(
+    error_message: str,
+    operation: str,
+    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."""
+
+    # Entity not found errors
+    if "Entity not found" in error_message or "entity not found" in error_message.lower():
+        return f"""# Edit Failed - Note Not Found
+
+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("{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("{project or "project-name"}", "{identifier}")` first to verify the note exists and get the exact identifier
+
+## Alternative approach:
+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":
+        if "Text to replace not found" in error_message:
+            return f"""# Edit Failed - Text Not Found
+
+The text '{find_text}' was not found in the note '{identifier}'.
+
+## Suggestions to try:
+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
+
+## Alternative approaches:
+- Use `append` or `prepend` to add new content instead
+- Use `replace_section` if you're trying to update a specific section"""
+
+        if "Expected" in error_message and "occurrences" in error_message:
+            # Extract the actual count from error message if possible
+            import re
+
+            match = re.search(r"found (\d+)", error_message)
+            actual_count = match.group(1) if match else "a different number of"
+
+            return f"""# Edit Failed - Wrong Replacement Count
+
+Expected {expected_replacements} occurrences of '{find_text}' but found {actual_count}.
+
+## How to fix:
+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("{project or "project-name"}", "{identifier}", "find_replace", "new_text", find_text="{find_text}", expected_replacements={actual_count})
+```"""
+
+    # Section replacement errors
+    if operation == "replace_section" and "Multiple sections" in error_message:
+        return f"""# Edit Failed - Duplicate Section Headers
+
+Multiple sections found with the same header in note '{identifier}'.
+
+## How to fix:
+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
+
+## Alternative approach:
+Use `find_replace` to update specific text within the duplicate sections."""
+
+    # Generic server/request errors
+    if (
+        "Invalid request" in error_message or "malformed" in error_message.lower()
+    ):  # pragma: no cover
+        return f"""# Edit Failed - Request Error
+
+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("{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("{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
+    return f"""# Edit Failed
+
+Error editing note '{identifier}': {error_message}
+
+## General troubleshooting:
+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("{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("{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"""
+
+
+@mcp.tool(
+    description="Edit an existing markdown note using various operations like append, prepend, find_replace, or replace_section.",
+)
+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,
+    context: Context | None = None,
+) -> str:
+    """Edit an existing markdown note in the knowledge base.
+
+    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.
+                   Must be an exact match - fuzzy matching is not supported for edit operations.
+                   Use search_notes() or read_note() first to find the correct identifier if uncertain.
+        operation: The editing operation to perform:
+                  - "append": Add content to the end of the note
+                  - "prepend": Add content to the beginning of the 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)
+        context: Optional FastMCP context for performance caching.
+
+    Returns:
+        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("my-project", "project-planning", "append", "\\n## New Requirements\\n- Feature X\\n- Feature Y")
+
+        # Add timestamp at beginning (frontmatter-aware)
+        edit_note("work-docs", "meeting-notes", "prepend", "## 2025-05-25 Update\\n- Progress update...\\n\\n")
+
+        # Update version number (single occurrence)
+        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("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("team-docs", "docs/guide", "find_replace", "new-api", find_text="old-api", expected_replacements=5)
+
+        # Replace implementation section
+        edit_note("specs", "api-spec", "replace_section", "New implementation approach...\\n", section="## Implementation")
+
+        # Replace subsection with more specific header
+        edit_note("docs", "docs/setup", "replace_section", "Updated install steps\\n", section="### Installation")
+
+        # Using different identifier formats (must be exact matches)
+        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("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("planning", "project-plan", "replace_section", "TBD - needs research\\n", section="## Future Work")
+
+        # Update status across document (expecting exactly 2 occurrences)
+        edit_note("reports", "status-report", "find_replace", "In Progress", find_text="Not Started", expected_replacements=2)
+
+    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.
+    """
+    track_mcp_tool("edit_note")
+    async with get_client() as client:
+        active_project = await get_active_project(client, project, context)
+
+        logger.info("MCP tool call", tool="edit_note", identifier=identifier, operation=operation)
+
+        # Validate operation
+        valid_operations = ["append", "prepend", "find_replace", "replace_section"]
+        if operation not in valid_operations:
+            raise ValueError(
+                f"Invalid operation '{operation}'. Must be one of: {', '.join(valid_operations)}"
+            )
+
+        # Validate required parameters for specific operations
+        if operation == "find_replace" and not find_text:
+            raise ValueError("find_text parameter is required for find_replace operation")
+        if operation == "replace_section" and not section:
+            raise ValueError("section parameter is required for replace_section operation")
+
+        # Use the PATCH endpoint to edit the entity
+        try:
+            # Resolve identifier to entity ID
+            entity_id = await resolve_entity_id(client, active_project.id, identifier)
+
+            # Prepare the edit request data
+            edit_data = {
+                "operation": operation,
+                "content": content,
+            }
+
+            # Add optional parameters
+            if section:
+                edit_data["section"] = section
+            if find_text:
+                edit_data["find_text"] = find_text
+            if expected_replacements != 1:  # Only send if different from default
+                edit_data["expected_replacements"] = str(expected_replacements)
+
+            # Call the PATCH endpoint
+            url = f"/v2/projects/{active_project.id}/knowledge/entities/{entity_id}"
+            response = await call_patch(client, url, json=edit_data)
+            result = EntityResponse.model_validate(response.json())
+
+            # Format summary
+            summary = [
+                f"# Edited note ({operation})",
+                f"project: {active_project.name}",
+                f"file_path: {result.file_path}",
+                f"permalink: {result.permalink}",
+                f"checksum: {result.checksum[:8] if result.checksum else 'unknown'}",
+            ]
+
+            # Add operation-specific details
+            if operation == "append":
+                lines_added = len(content.split("\n"))
+                summary.append(f"operation: Added {lines_added} lines to end of note")
+            elif operation == "prepend":
+                lines_added = len(content.split("\n"))
+                summary.append(f"operation: Added {lines_added} lines to beginning of note")
+            elif operation == "find_replace":
+                # For find_replace, we can't easily count replacements from here
+                # since we don't have the original content, but the server handled it
+                summary.append("operation: Find and replace operation completed")
+            elif operation == "replace_section":
+                summary.append(f"operation: Replaced content under section '{section}'")
+
+            # Count observations by category (reuse logic from write_note)
+            categories = {}
+            if result.observations:
+                for obs in result.observations:
+                    categories[obs.category] = categories.get(obs.category, 0) + 1
+
+                summary.append("\\n## Observations")
+                for category, count in sorted(categories.items()):
+                    summary.append(f"- {category}: {count}")
+
+            # Count resolved/unresolved relations
+            unresolved = 0
+            resolved = 0
+            if result.relations:
+                unresolved = sum(1 for r in result.relations if not r.to_id)
+                resolved = len(result.relations) - unresolved
+
+                summary.append("\\n## Relations")
+                summary.append(f"- Resolved: {resolved}")
+                if unresolved:
+                    summary.append(f"- Unresolved: {unresolved}")
+
+            logger.info(
+                "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,
+            )
+
+            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, active_project.name
+            )