edit_note
Modify existing markdown notes by appending, prepending, replacing text, or updating specific sections to maintain organized knowledge records.
Instructions
Edit an existing markdown note using various operations like append, prepend, find_replace, or replace_section.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | ||
| operation | Yes | ||
| content | Yes | ||
| project | No | ||
| section | No | ||
| find_text | No | ||
| expected_replacements | No |
Implementation Reference
- The primary handler function for the 'edit_note' MCP tool. Decorated with @mcp.tool for automatic schema generation and registration. Implements note editing operations (append, prepend, find_replace, replace_section) by calling the backend PATCH API, handles errors with helpful messages, and returns formatted summaries with observations and relations.
@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.external_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.external_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 ) - src/basic_memory/mcp/tools/__init__.py:19-19 (registration)Import statement that loads the edit_note tool function, triggering its registration on the global MCP server instance via the @mcp.tool decorator.
from basic_memory.mcp.tools.edit_note import edit_note - Helper function used by edit_note to generate user-friendly error messages with troubleshooting suggestions for various failure modes.
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"""