basic-memory

Instructions

Implementation Reference

• src/basic_memory/mcp/tools/project_management.py:21-71 (handler)

  The handler function for the 'list_memory_projects' MCP tool. It fetches the list of projects from the internal API, handles constrained project mode, and returns a formatted string listing available projects with usage guidance.
  @mcp.tool("list_memory_projects") async def list_memory_projects(context: Context | None = None) -> str: """List all available projects with their status. Shows all Basic Memory projects that are available for MCP operations. Use this tool to discover projects when you need to know which project to use. Use this tool: - At conversation start when project is unknown - When user asks about available projects - Before any operation requiring a project After calling: - Ask user which project to use - Remember their choice for the session Returns: Formatted list of projects with session management guidance Example: list_memory_projects() """ async with get_client() as client: if context: # pragma: no cover await context.info("Listing all available projects") # Check if server is constrained to a specific project constrained_project = os.environ.get("BASIC_MEMORY_MCP_PROJECT") # Get projects from API response = await call_get(client, "/projects/projects") project_list = ProjectList.model_validate(response.json()) if constrained_project: result = f"Project: {constrained_project}\n\n" result += "Note: This MCP server is constrained to a single project.\n" result += "All operations will automatically use this project." else: # Show all projects with session guidance result = "Available projects:\n" for project in project_list.projects: result += f"• {project.name}\n" result += "\n" + "─" * 40 + "\n" result += "Next: Ask which project to use for this session.\n" result += "Example: 'Which project should I use for this task?'\n\n" result += "Session reminder: Track the selected project for all subsequent operations in this conversation.\n" result += "The user can say 'switch to [project]' to change projects." return result
• src/basic_memory/mcp/tools/__init__.py:21-25 (registration)

  Import of the list_memory_projects handler in tools/__init__.py, which triggers registration of the tool via the @mcp.tool decorator when the module is imported by the MCP server.
  from basic_memory.mcp.tools.project_management import ( list_memory_projects, create_memory_project, delete_project, )
• src/basic_memory/schemas/project_info.py:194-199 (schema)

  Pydantic schema ProjectList used by the handler to validate the JSON response from the /projects/projects API endpoint.
  class ProjectList(BaseModel): """Response model for listing projects.""" projects: List[ProjectItem] default_project: str