basic-memory

Instructions

Implementation Reference

• src/basic_memory/mcp/tools/project_management.py:132-199 (handler)

  The core handler function for the 'delete_project' MCP tool. It validates the project exists, calls the API to delete it using its external_id, and returns a confirmation message. The @mcp.tool() decorator registers the tool with the FastMCP server instance and infers the input schema from the function signature (project_name: str) and docstring.

  @mcp.tool()
  async def delete_project(project_name: str, context: Context | None = None) -> str:
      """Delete a Basic Memory project.
  
      Removes a project from the configuration and database. This does NOT delete
      the actual files on disk - only removes the project from Basic Memory's
      configuration and database records.
  
      Args:
          project_name: Name of the project to delete
  
      Returns:
          Confirmation message about project deletion
  
      Example:
          delete_project("old-project")
  
      Warning:
          This action cannot be undone. The project will need to be re-added
          to access its content through Basic Memory again.
      """
      track_mcp_tool("delete_project")
      async with get_client() as client:
          # Check if server is constrained to a specific project
          constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT")
          if constrained_project:
              return f"# Error\n\nProject deletion disabled - MCP server is constrained to project '{constrained_project}'.\nUse the CLI to delete projects: `basic-memory project remove \"{project_name}\"`"
  
          if context:  # pragma: no cover
              await context.info(f"Deleting project: {project_name}")
  
          # Get project info before deletion to validate it exists
          response = await call_get(client, "/projects/projects")
          project_list = ProjectList.model_validate(response.json())
  
          # Find the project by permalink (derived from name).
          # Note: The API response uses `ProjectItem` which derives `permalink` from `name`,
          # so a separate case-insensitive name match would be redundant here.
          project_permalink = generate_permalink(project_name)
          target_project = None
          for p in project_list.projects:
              # Match by permalink (handles case-insensitive input)
              if p.permalink == project_permalink:
                  target_project = p
                  break
  
          if not target_project:
              available_projects = [p.name for p in project_list.projects]
              raise ValueError(
                  f"Project '{project_name}' not found. Available projects: {', '.join(available_projects)}"
              )
  
          # Call v2 API to delete project using project external_id
          response = await call_delete(client, f"/v2/projects/{target_project.external_id}")
          status_response = ProjectStatusResponse.model_validate(response.json())
  
          result = f"✓ {status_response.message}\n\n"
  
          if status_response.old_project:
              result += "Removed project details:\n"
              result += f"• Name: {status_response.old_project.name}\n"
              if hasattr(status_response.old_project, "path"):
                  result += f"• Path: {status_response.old_project.path}\n"
  
          result += "Files remain on disk but project is no longer tracked by Basic Memory.\n"
          result += "Re-add the project to access its content again.\n"
  
          return result

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

  Re-export of the delete_project function from project_management.py, which triggers the decorator registration when this __init__.py is imported.

  from basic_memory.mcp.tools.project_management import (
      list_memory_projects,
      create_memory_project,
      delete_project,
  )

• src/basic_memory/mcp/server.py:78-81 (registration)

  Creation of the global FastMCP server instance 'mcp' to which tools are registered via decorators.

  mcp = FastMCP(
      name="Basic Memory",
      lifespan=lifespan,
  )