Add list_workspaces MCP tool and CLI command

[bm-clawd]

Context

From team discussion: when users have multiple workspaces (e.g. a personal plan + a team workspace), they currently need to manually configure the workspace ID in their MCP client config. This is friction we should eliminate.

Proposal

Add a list_workspaces tool (MCP + CLI) that:

1. Lists all workspaces the authenticated user has access to (personal + team)
2. Lets users specify which workspace to talk to — similar to how they currently specify a project

MCP Tool

• list_workspaces → returns available workspaces with IDs and names
• Other tools accept an optional workspace parameter (like the existing project parameter)

CLI

• bm workspaces or bm workspace list → shows available workspaces

Why

• Users with a personal plan + team workspace shouldn't have to manually set workspace IDs in config
• Reduces onboarding friction for team/multi-workspace users
• Follows the same pattern as project selection

Related

• Jope's PR giving each user a private project within team workspaces
• Current workspace ID config requirement in MCP client setup

cc @jope

[claude]

Claude finished @bm-clawd's task in 2m 22s —— View job

---

Issue Triage Complete

• Gather context and analyze issue
• Check for duplicate issues
• Review existing workspace/project patterns in codebase
• Add appropriate labels
• Provide triage summary

---

Triage Summary

Type: Feature Request — New MCP tool + CLI command
Priority: Medium — Usability improvement for multi-workspace users, not a breaking bug
Components: MCP tools, CLI, Cloud functionality
Complexity: Complex — Multi-component change with potential architectural decisions
Duplicates: None found

Labels applied: enhancement, cloud

---

Codebase Analysis

After reviewing the codebase, some important context for implementation:

Current State — No "Workspaces" Concept
Basic Memory currently uses Projects as the primary organizational unit. There is no "workspace" abstraction in the codebase. The issue's use of "workspace" appears to refer to either:

1. The cloud-side concept (e.g., a team workspace in the cloud backend), or
2. A new grouping layer above projects

Existing Patterns to Follow

The list_memory_projects() MCP tool in src/basic_memory/mcp/tools/project_management.py is the closest analog — it lists projects using get_client() (not per-project, since it's global-scoped). A list_workspaces tool would follow the same pattern.

The CLI pattern lives in src/basic_memory/cli/commands/project.py with commands like basic-memory project list.

Key Implementation Questions

1. What is a "workspace" in the cloud API? — Does the cloud backend have a workspace concept distinct from projects? If so, what does the API endpoint look like? This is the critical missing piece.

2. Is this purely a cloud feature? — Should list_workspaces only work when cloud credentials are configured? What should happen for local-only users?

3. Workspace parameter on other tools — The issue proposes adding a workspace parameter to existing MCP tools (like project). This would be a significant change affecting multiple tools. Is this needed for the MVP, or is just listing workspaces sufficient initially?

4. CLI command name — bm workspaces vs bm workspace list? The existing pattern uses subcommands (e.g., bm project list), so bm workspace list would be more consistent.

5. Relationship between workspaces and projects — Does a workspace contain projects? Can a project exist in multiple workspaces?

---

Recommended Implementation Scope (once questions are resolved)

Phase 1 (simpler):

• list_workspaces MCP tool → calls cloud API, returns workspace names/IDs
• basic-memory workspace list CLI command

Phase 2 (larger scope):

• Add workspace parameter to existing MCP tools
• Per-workspace routing (similar to per-project cloud routing)
• SPEC document for the workspace concept

Effort estimate: Phase 1 is medium complexity; Phase 2 is complex and touches many files.

---

cc @jope — Can you clarify the cloud-side workspace API and the relationship between workspaces and projects? This will help scope the implementation correctly.