fix(mcp): resolve projects by external_id, remove workspace from MCP tools (#777)

Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: phernandez

docs/ai-assistant-guide-extended.md

@@ -91,17 +91,19 @@ SQLite Database (Index)
 # List all projects
 projects = await list_memory_projects()
 
-# Response structure:
+# Response structure (each entry includes external_id you can pass as project_id):
 # [
 #   {
 #     "name": "main",
+#     "external_id": "550e8400-e29b-41d4-a716-446655440000",
 #     "path": "/Users/name/notes",
 #     "is_default": True,
 #     "note_count": 156,
 #     "last_synced": "2025-01-15T10:30:00Z"
 #   },
 #   {
 #     "name": "work",
+#     "external_id": "9f86d081-884c-42a3-b5e3-1c0c5b4c8e52",
 #     "path": "/Users/name/work-notes",
 #     "is_default": False,
 #     "note_count": 89,
@@ -164,6 +166,44 @@ active_project = "main"
 results = await search_notes(query="topic", project=active_project)
 ```
 
+### `project` vs `project_id`
+
+Every project has two identifiers:
+
+- **`project`** — human-readable name (e.g., `"main"`). Easy to use, but can collide across cloud workspaces.
+- **`project_id`** — stable `external_id` UUID. Always unambiguous; takes precedence over `project` when both are passed.
+
+**When to prefer `project_id`:**
+
+1. **Cloud multi-workspace setups.** If the user belongs to more than one workspace (personal + organization, or several organizations) and the same project name might exist in more than one of them, pass `project_id` to route to the exact project. Without it, name resolution falls back to the default workspace, which may not be the one the user means.
+2. **After `list_memory_projects()`.** Once you have the `external_id`, prefer using it — it's the same number of characters in JSON and saves a name-resolution round-trip.
+3. **When persisting a project choice across a long session.** UUIDs are stable; names can be renamed.
+
+**When `project` (name) is fine:**
+
+- Local single-workspace setups (no collision risk).
+- One-off operations where the name is clearly visible to the user (e.g., quick `search_notes(project="main", ...)`).
+- The user explicitly references a project by name in their message.
+
+**Example — cloud multi-workspace pattern:**
+
+```python
+# Discover and pick the right project for this user
+projects = await list_memory_projects()
+target = next(p for p in projects if p["name"] == "research" and p["workspace"]["slug"] == "acme")
+
+# Use the UUID for all subsequent operations — no ambiguity
+await write_note(
+    title="Meeting Notes",
+    content="...",
+    folder="meetings",
+    project_id=target["external_id"],
+)
+results = await search_notes(query="kickoff", project_id=target["external_id"])
+```
+
+**Precedence rule:** When both are passed, `project_id` wins. This lets you safely supply `project="main"` for backward compatibility while still routing precisely with `project_id`.
+
 ### Cross-Project Operations
 
 **Some tools work across all projects when project parameter omitted:**

src/basic_memory/cli/commands/db.py

@@ -99,9 +99,7 @@ def _abort_if_mcp_processes_alive() -> None:
     if not zombies:
         return
 
-    console.print(
-        "[red]Refusing to reset:[/red] basic-memory MCP processes are still running."
-    )
+    console.print("[red]Refusing to reset:[/red] basic-memory MCP processes are still running.")
     console.print(
         "[yellow]On macOS/Linux these would keep reading the deleted memory.db inode "
         "and return phantom search results (see #765).[/yellow]"
@@ -117,9 +115,7 @@ def _abort_if_mcp_processes_alive() -> None:
             "Where-Object {$_.CommandLine -like '*basic-memory*mcp*'}[/green]"
         )
     else:
-        console.print(
-            "  2. Verify nothing remains: [green]pgrep -fa 'basic-memory mcp'[/green]"
-        )
+        console.print("  2. Verify nothing remains: [green]pgrep -fa 'basic-memory mcp'[/green]")
     console.print("  3. Re-run [green]bm reset[/green].")
     raise typer.Exit(1)
 

src/basic_memory/cli/commands/tool.py

@@ -62,9 +62,12 @@ def write_note(
             help="The project to write to. If not provided, the default project will be used."
         ),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -106,7 +109,7 @@ def write_note(
                     content=content,
                     directory=folder,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     tags=tags,
                     output_format="json",
                 )
@@ -132,9 +135,12 @@ def read_note(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -156,7 +162,7 @@ def read_note(
                 mcp_read_note(
                     identifier=identifier,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     include_frontmatter=include_frontmatter,
                     output_format="json",
                 )
@@ -195,9 +201,12 @@ def edit_note(
             help="The project to edit. If not provided, the default project will be used."
         ),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -222,7 +231,7 @@ def edit_note(
                     operation=operation,
                     content=content,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     section=section,
                     find_text=find_text,
                     expected_replacements=expected_replacements,
@@ -260,9 +269,12 @@ def build_context(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -284,7 +296,7 @@ def build_context(
                 mcp_build_context(
                     url=url,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     depth=depth,
                     timeframe=timeframe,
                     page=page,
@@ -317,9 +329,12 @@ def recent_activity(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -346,7 +361,7 @@ def recent_activity(
                     page=page,
                     page_size=page_size,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     output_format="json",
                 )
             )
@@ -408,9 +423,12 @@ def search_notes(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -482,7 +500,7 @@ def search_notes(
                 mcp_search(
                     query=query or None,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     search_type=search_type,
                     output_format="json",
                     page=page,
@@ -592,9 +610,12 @@ def schema_validate(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -629,7 +650,7 @@ def schema_validate(
                     note_type=note_type,
                     identifier=identifier,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     output_format="json",
                 )
             )
@@ -660,9 +681,12 @@ def schema_infer(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -686,7 +710,7 @@ def schema_infer(
                     note_type=note_type,
                     threshold=threshold,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     output_format="json",
                 )
             )
@@ -714,9 +738,12 @@ def schema_diff(
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    workspace: Annotated[
+    project_id: Annotated[
         Optional[str],
-        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+        typer.Option(
+            "--project-id",
+            help="Project external_id (UUID). Takes precedence over --project; use to disambiguate same-named projects across cloud workspaces.",
+        ),
     ] = None,
     local: bool = typer.Option(
         False, "--local", help="Force local API routing (ignore cloud mode)"
@@ -738,7 +765,7 @@ def schema_diff(
                 mcp_schema_diff(
                     note_type=note_type,
                     project=project,
-                    workspace=workspace,
+                    project_id=project_id,
                     output_format="json",
                 )
             )