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

basic_memory/mcp/tools/edit_note.py

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