basic-memory 0.12.3__py3-none-any.whl → 0.13.0b1__py3-none-any.whl

basic_memory/mcp/tools/edit_note.py

@@ -0,0 +1,297 @@
+"""Edit note tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_patch
+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,
+) -> 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.
+
+## Suggestions to try:
+1. **Search for the note first**: Use `search_notes("{identifier.split("/")[-1]}")` to find similar notes
+2. **Try different identifier formats**:
+   - If you used a permalink like "folder/note-title", try just the title: "{identifier.split("/")[-1].replace("-", " ").title()}"
+   - If you used a title, try the permalink format: "{identifier.lower().replace(" ", "-")}"
+   - Use `read_note()` first to verify the note exists and get the correct identifiers
+
+## Alternative approach:
+Use `write_note()` 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("{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("{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})
+```"""
+
+    # 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("{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()` or `read_note()` 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]}")`
+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("{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
+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
+- 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,
+    section: Optional[str] = None,
+    find_text: Optional[str] = None,
+    expected_replacements: int = 1,
+    project: Optional[str] = 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.
+
+    Args:
+        identifier: The title, permalink, or memory:// URL of the note to edit
+        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
+        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.
+
+    Returns:
+        A markdown formatted summary of the edit operation and resulting semantic content
+
+    Examples:
+        # Add new content to end of note
+        edit_note("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")
+
+        # Update version number (single occurrence)
+        edit_note("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)
+
+        # Replace text that appears multiple times - validate count first
+        edit_note("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")
+
+        # Replace subsection with more specific header
+        edit_note("docs/setup", "replace_section", "Updated install steps\\n", section="### Installation")
+
+        # Using different identifier formats
+        edit_note("Meeting Notes", "append", "\\n- Follow up on action items")  # title
+        edit_note("docs/meeting-notes", "append", "\\n- Follow up tasks")       # permalink
+        edit_note("docs/Meeting Notes", "append", "\\n- Next steps")           # folder/title
+
+        # Add new section to document
+        edit_note("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)
+
+        # Replace text in a file, specifying project name
+        edit_note("docs/guide", "find_replace", "new-api", find_text="old-api", project="my-project"))
+
+    """
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
+    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:
+        # 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"{project_url}/knowledge/entities/{identifier}"
+        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,
+            permalink=result.permalink,
+            observations_count=len(result.observations),
+            relations_count=len(result.relations),
+            status_code=response.status_code,
+        )
+
+        return "\n".join(summary)
+
+    except Exception as e:
+        logger.error(f"Error editing note: {e}")
+        return _format_error_response(
+            str(e), operation, identifier, find_text, expected_replacements
+        )

basic_memory/mcp/tools/list_directory.py

@@ -0,0 +1,154 @@
+"""List directory tool for Basic Memory MCP server."""
+
+from typing import Optional
+
+from loguru import logger
+
+from basic_memory.mcp.async_client import client
+from basic_memory.mcp.project_session import get_active_project
+from basic_memory.mcp.server import mcp
+from basic_memory.mcp.tools.utils import call_get
+
+
+@mcp.tool(
+    description="List directory contents with filtering and depth control.",
+)
+async def list_directory(
+    dir_name: str = "/",
+    depth: int = 1,
+    file_name_glob: Optional[str] = None,
+    project: Optional[str] = None,
+) -> str:
+    """List directory contents from the knowledge base with optional filtering.
+
+    This tool provides 'ls' functionality for browsing the knowledge base directory structure.
+    It can list immediate children or recursively explore subdirectories with depth control,
+    and supports glob pattern filtering for finding specific files.
+
+    Args:
+        dir_name: Directory path to list (default: root "/")
+                 Examples: "/", "/projects", "/research/ml"
+        depth: Recursion depth (1-10, default: 1 for immediate children only)
+               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.
+    Returns:
+        Formatted listing of directory contents with file metadata
+
+    Examples:
+        # List root directory contents
+        list_directory()
+
+        # List specific folder
+        list_directory(dir_name="/projects")
+
+        # Find all Python files
+        list_directory(file_name_glob="*.py")
+
+        # Deep exploration of research folder
+        list_directory(dir_name="/research", depth=3)
+
+        # 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")
+    """
+    active_project = get_active_project(project)
+    project_url = active_project.project_url
+
+    # Prepare query parameters
+    params = {
+        "dir_name": dir_name,
+        "depth": str(depth),
+    }
+    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}'")
+
+    # Call the API endpoint
+    response = await call_get(
+        client,
+        f"{project_url}/directory/list",
+        params=params,
+    )
+
+    nodes = response.json()
+
+    if not nodes:
+        filter_desc = ""
+        if file_name_glob:
+            filter_desc = f" matching '{file_name_glob}'"
+        return f"No files found in directory '{dir_name}'{filter_desc}"
+
+    # Format the results
+    output_lines = []
+    if file_name_glob:
+        output_lines.append(f"Files in '{dir_name}' matching '{file_name_glob}' (depth {depth}):")
+    else:
+        output_lines.append(f"Contents of '{dir_name}' (depth {depth}):")
+    output_lines.append("")
+
+    # Group by type and sort
+    directories = [n for n in nodes if n["type"] == "directory"]
+    files = [n for n in nodes if n["type"] == "file"]
+
+    # Sort by name
+    directories.sort(key=lambda x: x["name"])
+    files.sort(key=lambda x: x["name"])
+
+    # Display directories first
+    for node in directories:
+        path_display = node["directory_path"]
+        output_lines.append(f"📁 {node['name']:<30} {path_display}")
+
+    # Add separator if we have both directories and files
+    if directories and files:
+        output_lines.append("")
+
+    # Display files with metadata
+    for node in files:
+        path_display = node["directory_path"]
+        title = node.get("title", "")
+        updated = node.get("updated_at", "")
+
+        # Remove leading slash if present, requesting the file via read_note does not use the beginning slash'
+        if path_display.startswith("/"):
+            path_display = path_display[1:]
+
+        # Format date if available
+        date_str = ""
+        if updated:
+            try:
+                from datetime import datetime
+
+                dt = datetime.fromisoformat(updated.replace("Z", "+00:00"))
+                date_str = dt.strftime("%Y-%m-%d")
+            except Exception:  # pragma: no cover
+                date_str = updated[:10] if len(updated) >= 10 else ""
+
+        # Create formatted line
+        file_line = f"📄 {node['name']:<30} {path_display}"
+        if title and title != node["name"]:
+            file_line += f" | {title}"
+        if date_str:
+            file_line += f" | {date_str}"
+
+        output_lines.append(file_line)
+
+    # Add summary
+    output_lines.append("")
+    total_count = len(directories) + len(files)
+    summary_parts = []
+    if directories:
+        summary_parts.append(
+            f"{len(directories)} director{'y' if len(directories) == 1 else 'ies'}"
+        )
+    if files:
+        summary_parts.append(f"{len(files)} file{'s' if len(files) != 1 else ''}")
+
+    output_lines.append(f"Total: {total_count} items ({', '.join(summary_parts)})")
+
+    return "\n".join(output_lines)

basic_memory/mcp/tools/move_note.py

@@ -0,0 +1,87 @@
+"""Move note tool for Basic Memory MCP server."""
+
+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
+
+
+@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: Entity identifier (title, permalink, or memory:// URL)
+        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: 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")
+
+    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
+
+    # 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