basic-memory

Instructions

Implementation Reference

• src/basic_memory/mcp/tools/project_management.py:76-129 (handler)

  The main handler function for the 'create_memory_project' tool, decorated with @mcp.tool(). It creates a new Basic Memory project by calling the internal API, handles constrained project mode, and returns formatted confirmation.

  @mcp.tool("create_memory_project")
  async def create_memory_project(
      project_name: str, project_path: str, set_default: bool = False, context: Context | None = None
  ) -> str:
      """Create a new Basic Memory project.
  
      Creates a new project with the specified name and path. The project directory
      will be created if it doesn't exist. Optionally sets the new project as default.
  
      Args:
          project_name: Name for the new project (must be unique)
          project_path: File system path where the project will be stored
          set_default: Whether to set this project as the default (optional, defaults to False)
  
      Returns:
          Confirmation message with project details
  
      Example:
          create_memory_project("my-research", "~/Documents/research")
          create_memory_project("work-notes", "/home/user/work", set_default=True)
      """
      track_mcp_tool("create_memory_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 creation disabled - MCP server is constrained to project \'{constrained_project}\'.\nUse the CLI to create projects: `basic-memory project add "{project_name}" "{project_path}"`'
  
          if context:  # pragma: no cover
              await context.info(f"Creating project: {project_name} at {project_path}")
  
          # Create the project request
          project_request = ProjectInfoRequest(
              name=project_name, path=project_path, set_default=set_default
          )
  
          # Call API to create project
          response = await call_post(client, "/projects/projects", json=project_request.model_dump())
          status_response = ProjectStatusResponse.model_validate(response.json())
  
          result = f"✓ {status_response.message}\n\n"
  
          if status_response.new_project:
              result += "Project Details:\n"
              result += f"• Name: {status_response.new_project.name}\n"
              result += f"• Path: {status_response.new_project.path}\n"
  
              if set_default:
                  result += "• Set as default project\n"
  
          result += "\nProject is now available for use in tool calls.\n"
          result += f"Use '{project_name}' as the project parameter in MCP tool calls.\n"
  
          return result

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

  Re-exports the create_memory_project function from project_management.py, allowing easy import from basic_memory.mcp.tools in tests and other modules. Importing this module registers all tools via their decorators.

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

• src/basic_memory/mcp/tools/project_management.py:13-17 (schema)

  Imports Pydantic models used internally for project creation request/response validation: ProjectInfoRequest for input to API, ProjectStatusResponse for output parsing, and ProjectList for listing.

  from basic_memory.schemas.project_info import (
      ProjectList,
      ProjectStatusResponse,
      ProjectInfoRequest,
  )