basic-memory

Instructions

Implementation Reference

• src/basic_memory/mcp/tools/move_note.py:345-556 (handler)

  The primary handler for the 'move_note' MCP tool. Decorated with @mcp.tool(), it resolves the note identifier to an entity ID, validates the destination path, detects potential cross-project moves, performs the move via the v2 API endpoint (/knowledge/entities/{entity_id}/move), handles errors with user-friendly formatted responses, and returns success details including updated permalink.

  @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,
      context: Context | None = None,
  ) -> str:
      """Move a note to a new file location within the same project.
  
      Moves a note from one location to another within the project, updating all
      database references and maintaining semantic content. Uses stateless architecture -
      project parameter optional with server resolution.
  
      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: Project name to move within. Optional - server will resolve using hierarchy.
                  If unknown, use list_memory_projects() to discover available projects.
          context: Optional FastMCP context for performance caching.
  
      Returns:
          Success message with move details and project information.
  
      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")
  
          # Move with complex path structure
          move_note("experiments/ml-results", "archive/2025/ml-experiments.md")
  
          # Explicit project specification
          move_note("My Note", "work/notes/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
  
      Raises:
          ToolError: If project doesn't exist, identifier is not found, or destination_path is invalid
  
      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
      """
      track_mcp_tool("move_note")
      async with get_client() as client:
          logger.debug(f"Moving note: {identifier} to {destination_path} in project: {project}")
  
          active_project = await get_active_project(client, project, context)
  
          # Validate destination path to prevent path traversal attacks
          project_path = active_project.home
          if not validate_project_path(destination_path, project_path):
              logger.warning(
                  "Attempted path traversal attack blocked",
                  destination_path=destination_path,
                  project=active_project.name,
              )
              return f"""# Move Failed - Security Validation Error
  
  The destination path '{destination_path}' is not allowed - paths must stay within project boundaries.
  
  ## Valid path examples:
  - `notes/my-file.md`
  - `projects/2025/meeting-notes.md`
  - `archive/old-notes.md`
  
  ## Try again with a safe path:
  ```
  move_note("{identifier}", "notes/{destination_path.split("/")[-1] if "/" in destination_path else destination_path}")
  ```"""
  
          # Check for potential cross-project move attempts
          cross_project_error = await _detect_cross_project_move_attempt(
              client, identifier, destination_path, active_project.name
          )
          if cross_project_error:
              logger.info(f"Detected cross-project move attempt: {identifier} -> {destination_path}")
              return cross_project_error
  
          # Get the source entity information for extension validation
          source_ext = "md"  # Default to .md if we can't determine source extension
          try:
              # Resolve identifier to entity ID
              entity_id = await resolve_entity_id(client, active_project.external_id, identifier)
              # Fetch source entity information to get the current file extension
              url = f"/v2/projects/{active_project.external_id}/knowledge/entities/{entity_id}"
              response = await call_get(client, url)
              source_entity = EntityResponse.model_validate(response.json())
              if "." in source_entity.file_path:
                  source_ext = source_entity.file_path.split(".")[-1]
          except Exception as e:
              # If we can't fetch the source entity, default to .md extension
              logger.debug(f"Could not fetch source entity for extension check: {e}")
  
          # Validate that destination path includes a file extension
          if "." not in destination_path or not destination_path.split(".")[-1]:
              logger.warning(f"Move failed - no file extension provided: {destination_path}")
              return dedent(f"""
                  # Move Failed - File Extension Required
  
                  The destination path '{destination_path}' must include a file extension (e.g., '.md').
  
                  ## Valid examples:
                  - `notes/my-note.md`
                  - `projects/meeting-2025.txt`
                  - `archive/old-program.sh`
  
                  ## Try again with extension:
                  ```
                  move_note("{identifier}", "{destination_path}.{source_ext}")
                  ```
  
                  All examples in Basic Memory expect file extensions to be explicitly provided.
                  """).strip()
  
          # Get the source entity to check its file extension
          try:
              # Resolve identifier to entity ID (might already be cached from above)
              entity_id = await resolve_entity_id(client, active_project.external_id, identifier)
              # Fetch source entity information
              url = f"/v2/projects/{active_project.external_id}/knowledge/entities/{entity_id}"
              response = await call_get(client, url)
              source_entity = EntityResponse.model_validate(response.json())
  
              # Extract file extensions
              source_ext = (
                  source_entity.file_path.split(".")[-1] if "." in source_entity.file_path else ""
              )
              dest_ext = destination_path.split(".")[-1] if "." in destination_path else ""
  
              # Check if extensions match
              if source_ext and dest_ext and source_ext.lower() != dest_ext.lower():
                  logger.warning(
                      f"Move failed - file extension mismatch: source={source_ext}, dest={dest_ext}"
                  )
                  return dedent(f"""
                      # Move Failed - File Extension Mismatch
  
                      The destination file extension '.{dest_ext}' does not match the source file extension '.{source_ext}'.
  
                      To preserve file type consistency, the destination must have the same extension as the source.
  
                      ## Source file:
                      - Path: `{source_entity.file_path}`
                      - Extension: `.{source_ext}`
  
                      ## Try again with matching extension:
                      ```
                      move_note("{identifier}", "{destination_path.rsplit(".", 1)[0]}.{source_ext}")
                      ```
                      """).strip()
          except Exception as e:
              # If we can't fetch the source entity, log it but continue
              # This might happen if the identifier is not yet resolved
              logger.debug(f"Could not fetch source entity for extension check: {e}")
  
          try:
              # Resolve identifier to entity ID for the move operation
              entity_id = await resolve_entity_id(client, active_project.external_id, identifier)
  
              # Prepare move request (v2 API only needs destination_path)
              move_data = {
                  "destination_path": destination_path,
              }
  
              # Call the v2 move API endpoint (PUT method, entity_id in URL)
              url = f"/v2/projects/{active_project.external_id}/knowledge/entities/{entity_id}/move"
              response = await call_put(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)

• src/basic_memory/mcp/tools/__init__.py:20-20 (registration)

  Explicit import of the move_note function from its module, which executes the @mcp.tool() decorator to register the tool with the FastMCP server instance.

  from basic_memory.mcp.tools.move_note import move_note