Add project_id parameter to MCP tools for cloud workspace disambiguation

Adds optional `project_id: Optional[str] = None` (UUID) parameter to all 14
project-scoped MCP tools so callers can address projects unambiguously across
cloud workspaces without depending on name resolution.

What changed:
- Canonicalize UUID input via str(UUID(...)) in resolve_workspace_project_identifier
  so uppercase, brace-wrapped, urn:uuid, and unhyphenated forms all match the
  stored external_id (Codex P2)
- Add project_id parameter to: read_note, write_note, search_notes, edit_note,
  delete_note, view_note, read_content, move_note, list_directory, canvas,
  recent_activity, build_context, schema_validate/infer/diff, search_notes_ui,
  read_note_ui. project_id takes precedence over project when both are passed.
- Update get_project_client to route UUID identifiers correctly in pure local
  mode. Without this, get_project_mode(uuid) defaults to CLOUD and fails for
  users without cloud credentials. Fix gates the cloud-by-default branch on
  cloud actually being available, and skips per-project routing for UUIDs in
  Step 4 (local mode routes everything via the same ASGI client; the API
  resolves the UUID via /v2/projects/resolve)
- Wire read_note._search_candidates to pass project_id=active_project.external_id
  to the inner search_notes call so workspace selection from the outer
  get_project_client is preserved across re-resolution. Without this, names
  that collide across workspaces could re-resolve to a different tenant via
  the default-workspace fallback in CLI/context=None paths (Codex P1)
- Switch resolve_project_and_path callers (read_note, read_content, search)
  to pass active_project.name instead of the raw project arg so cache hits
  even when project_id was used or project name was wrong/ambiguous

Documentation:
- AI assistant guide (live MCP resource) explains project vs project_id and
  when to prefer the UUID
- Extended guide adds a dedicated `project` vs `project_id` section
- list_memory_projects docstring points LLMs at external_id for unambiguous
  addressing
- Per-tool project_id docstring is directive ("Prefer this over `project`
  when known") rather than conditional ("Use this when...")

Tests:
- 6 new unit tests in test_project_context.py covering UUID lookup, four
  normalization variants, project_id precedence, and pure-local UUID routing
- 2 new integration tests verify project_id end-to-end through MCP transport
- Tool signature contract test and telemetry tests updated for new parameter

Closes basicmachines-co/basic-memory-cloud#673

Signed-off-by: phernandez <paul@basicmachines.co>

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/mcp/project_context.py

@@ -558,9 +558,11 @@ async def resolve_workspace_project_identifier(
     index = await _ensure_workspace_project_index(context=context)
 
     # Fast path: direct lookup by external_id when the identifier is a UUID
+    # Canonicalize via str(UUID(...)) so uppercase, brace-wrapped, or urn:uuid forms
+    # all hash to the same lowercase-hyphenated key as the stored external_ids.
     try:
-        UUID(project)
-        entry = index.entries_by_external_id.get(project)
+        canonical_external_id = str(UUID(project))
+        entry = index.entries_by_external_id.get(canonical_external_id)
         if entry:
             return entry
     except ValueError:
@@ -977,6 +979,7 @@ def detect_project_from_url_prefix(identifier: str, config: BasicMemoryConfig) -
 async def get_project_client(
     project: Optional[str] = None,
     context: Optional[Context] = None,
+    project_id: Optional[str] = None,
 ) -> AsyncIterator[Tuple[AsyncClient, ProjectItem]]:
     """Resolve project, create correctly-routed client, and validate project.
 
@@ -992,8 +995,12 @@ async def get_project_client(
     4. Otherwise → local ASGI client
 
     Args:
-        project: Optional explicit project parameter (name, permalink, or external_id UUID)
+        project: Optional explicit project parameter (name or permalink)
         context: Optional FastMCP context for caching
+        project_id: Optional project external_id (UUID). When provided, takes
+            precedence over ``project`` and disambiguates the project across
+            workspaces. Use this when the same project name exists in multiple
+            cloud workspaces.
 
     Yields:
         Tuple of (client, active_project)
@@ -1010,8 +1017,12 @@ async def get_project_client(
         is_factory_mode,
     )
 
+    # When project_id (UUID) is provided, prefer it as the resolution identifier.
+    # external_id is unambiguous across workspaces; project name can collide.
+    project_identifier = project_id if project_id else project
+
     # Step 1: Resolve project name from config (no network call)
-    resolved_project = await resolve_project_parameter(project, context=context)
+    resolved_project = await resolve_project_parameter(project_identifier, context=context)
     config = ConfigManager().config
     factory_mode = is_factory_mode()
     explicit_cloud_routing = _explicit_routing() and not _force_local_mode()
@@ -1062,6 +1073,15 @@ async def get_project_client(
     project_entry = config.projects.get(resolved_project)
     project_mode = config.get_project_mode(resolved_project)
 
+    # Trigger: identifier is a UUID (project_id) but local config keys by name only
+    # Why: get_project_mode defaults to CLOUD for unknown identifiers; a UUID is
+    #   never registered in local config, so it would always falsely route cloud
+    # Outcome: in pure local mode, treat UUID identifiers as local routing; cloud
+    #   discovery still happens when factory/explicit/credentials are present
+    cloud_available = factory_mode or explicit_cloud_routing or has_cloud_credentials(config)
+    if project_id and not cloud_available:
+        project_mode = ProjectMode.LOCAL
+
     if factory_mode or project_mode == ProjectMode.CLOUD or explicit_cloud_routing:
         route_mode = "factory" if factory_mode else "cloud_proxy"
         active_ws: WorkspaceInfo | None = None
@@ -1109,6 +1129,12 @@ async def get_project_client(
         route_mode=route_mode,
     ):
         logger.debug("Using default local ASGI routing for project client")
-        async with get_client(project_name=resolved_project) as client:
+        # Trigger: UUID identifiers won't match name-keyed local config entries.
+        # Why: get_client(project_name=<uuid>) would consult get_project_mode and
+        #   default to CLOUD for unknown identifiers, breaking pure-local routing.
+        # Outcome: skip per-project routing for UUIDs — local mode routes every
+        #   project through the same ASGI client; the API resolves the UUID below.
+        client_kwargs = {} if project_id else {"project_name": resolved_project}
+        async with get_client(**client_kwargs) as client:
             active_project = await get_active_project(client, resolved_project, context)
             yield client, active_project

src/basic_memory/mcp/resources/ai_assistant_guide.md

@@ -18,13 +18,15 @@ Basic Memory creates a semantic knowledge graph from markdown files. Focus on bu
 
 **Resolution priority:**
 1. CLI constraint: `BASIC_MEMORY_MCP_PROJECT` env var (highest priority)
-2. Explicit parameter: `project="name"` in tool calls
+2. Explicit parameter: `project_id="<uuid>"` (preferred when known) or `project="name"` in tool calls
 3. Default project: `default_project` in config (fallback)
 
+**`project` vs `project_id`:** Every project has a stable `external_id` (UUID) returned by `list_memory_projects()`. Pass it as `project_id=...` to address a project unambiguously — required when the same project name exists in multiple cloud workspaces. For local single-project setups, the `project` name is fine.
+
 ### Quick Setup Check
 
 ```python
-# Discover projects
+# Discover projects (each entry includes external_id you can pass as project_id)
 projects = await list_memory_projects()
 ```
 
@@ -169,6 +171,14 @@ await write_note(
 **Multi-project users:**
 - Always specify project explicitly in tool calls
 
+**Cloud multi-workspace users:** project names can collide across workspaces. After calling `list_memory_projects()`, prefer the project's `external_id` via `project_id=...` for any subsequent tool calls — it routes to the exact project regardless of name collisions. The `project` name parameter falls back to the default workspace on ambiguity, which may not be what you want.
+
+```python
+# Cloud / multi-workspace: prefer project_id (UUID) once you've discovered it
+projects = await list_memory_projects()
+results = await search_notes(query="auth", project_id=projects[0]["external_id"])
+```
+
 **Discovery:**
 ```python
 # Start with discovery

src/basic_memory/mcp/tools/build_context.py

@@ -139,6 +139,7 @@ async def build_context(
         Field(validation_alias=AliasChoices("url", "uri", "memory_url")),
     ],
     project: Optional[str] = None,
+    project_id: Optional[str] = None,
     depth: str | int | None = 1,
     timeframe: Annotated[
         Optional[TimeFrame],
@@ -178,6 +179,9 @@ async def build_context(
     Args:
         project: Project name to build context from. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        project_id: Project external_id (UUID). Prefer this over `project` when known —
+                it routes to the exact project regardless of name collisions across cloud
+                workspaces. Takes precedence over `project`. Get from list_memory_projects().
         url: memory:// URI pointing to discussion content (e.g. memory://specs/search)
         depth: How many relation hops to traverse (1-3 recommended for performance)
         timeframe: How far back to look. Supports natural language like "2 days ago", "last week"
@@ -227,6 +231,7 @@ async def build_context(
         entrypoint="mcp",
         tool_name="build_context",
         requested_project=project,
+        requested_project_id=project_id,
         depth=depth or 1,
         timeframe=timeframe,
         page=page,
@@ -235,7 +240,10 @@ async def build_context(
         output_format=output_format,
         is_memory_url=str(url).startswith("memory://"),
     ):
-        async with get_project_client(project, context=context) as (client, active_project):
+        async with get_project_client(project, context=context, project_id=project_id) as (
+            client,
+            active_project,
+        ):
             logger.info(
                 f"MCP tool call tool=build_context project={active_project.name} "
                 f"url={url} depth={depth} timeframe={timeframe} output_format={output_format}"

src/basic_memory/mcp/tools/canvas.py

@@ -29,6 +29,7 @@ async def canvas(
         Field(validation_alias=AliasChoices("directory", "folder", "dir", "path")),
     ],
     project: Optional[str] = None,
+    project_id: Optional[str] = None,
     context: Context | None = None,
 ) -> str:
     """Create an Obsidian canvas file with the provided nodes and edges.
@@ -45,6 +46,9 @@ async def canvas(
     Args:
         project: Project name to create canvas in. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        project_id: Project external_id (UUID). Prefer this over `project` when known —
+                it routes to the exact project regardless of name collisions across cloud
+                workspaces. Takes precedence over `project`. Get from list_memory_projects().
         nodes: List of node objects following JSON Canvas 1.0 spec
         edges: List of edge objects following JSON Canvas 1.0 spec
         title: The title of the canvas (will be saved as title.canvas)
@@ -99,7 +103,10 @@ async def canvas(
     Raises:
         ToolError: If project doesn't exist or directory path is invalid
     """
-    async with get_project_client(project, context=context) as (client, active_project):
+    async with get_project_client(project, context=context, project_id=project_id) as (
+        client,
+        active_project,
+    ):
         # Ensure path has .canvas extension
         file_title = title if title.endswith(".canvas") else f"{title}.canvas"
         file_path = f"{directory}/{file_title}"

src/basic_memory/mcp/tools/delete_note.py

@@ -159,6 +159,7 @@ async def delete_note(
         Field(default=False, validation_alias=AliasChoices("is_directory", "is_dir")),
     ] = False,
     project: Optional[str] = None,
+    project_id: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",
     context: Context | None = None,
 ) -> bool | str | dict:
@@ -182,6 +183,9 @@ async def delete_note(
                      (without file extensions). Defaults to False.
         project: Project name to delete from. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        project_id: Project external_id (UUID). Prefer this over `project` when known —
+                it routes to the exact project regardless of name collisions across cloud
+                workspaces. Takes precedence over `project`. Get from list_memory_projects().
         output_format: "text" preserves existing behavior (bool/string). "json"
             returns machine-readable deletion metadata.
         context: Optional FastMCP context for performance caching.
@@ -236,7 +240,10 @@ async def delete_note(
         if detected:
             project = detected
 
-    async with get_project_client(project, context=context) as (client, active_project):
+    async with get_project_client(project, context=context, project_id=project_id) as (
+        client,
+        active_project,
+    ):
         logger.debug(
             f"Deleting {'directory' if is_directory else 'note'}: {identifier} in project: {active_project.name}"
         )

src/basic_memory/mcp/tools/edit_note.py

@@ -180,6 +180,7 @@ async def edit_note(
         ),
     ],
     project: Optional[str] = None,
+    project_id: Optional[str] = None,
     # Section/heading naming varies across tools; accept the descriptive forms.
     section: Annotated[
         Optional[str],
@@ -223,6 +224,9 @@ async def edit_note(
         content: The content to add or use for replacement
         project: Project name to edit in. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        project_id: Project external_id (UUID). Prefer this over `project` when known —
+                it routes to the exact project regardless of name collisions across cloud
+                workspaces. Takes precedence over `project`. Get from list_memory_projects().
         section: For replace_section operation - the markdown header to replace content under (e.g., "## Notes", "### Implementation")
         find_text: For find_replace operation - the text to find and replace
         expected_replacements: For find_replace operation - the expected number of replacements (validation will fail if actual doesn't match)
@@ -298,13 +302,17 @@ async def edit_note(
         entrypoint="mcp",
         tool_name="edit_note",
         requested_project=project,
+        requested_project_id=project_id,
         edit_operation=operation,
         output_format=output_format,
         has_section=bool(section),
         has_find_text=bool(find_text),
         expected_replacements=effective_replacements,
     ):
-        async with get_project_client(project, context=context) as (client, active_project):
+        async with get_project_client(project, context=context, project_id=project_id) as (
+            client,
+            active_project,
+        ):
             logger.info(
                 f"MCP tool call tool=edit_note project={active_project.name} "
                 f"identifier={identifier} operation={operation} output_format={output_format}"

src/basic_memory/mcp/tools/list_directory.py

@@ -32,6 +32,7 @@ async def list_directory(
         ),
     ] = None,
     project: Optional[str] = None,
+    project_id: Optional[str] = None,
     context: Context | None = None,
 ) -> str:
     """List directory contents from the knowledge base with optional filtering.
@@ -49,6 +50,9 @@ async def list_directory(
                        Examples: "*.md", "*meeting*", "project_*"
         project: Project name to list directory from. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        project_id: Project external_id (UUID). Prefer this over `project` when known —
+                it routes to the exact project regardless of name collisions across cloud
+                workspaces. Takes precedence over `project`. Get from list_memory_projects().
         context: Optional FastMCP context for performance caching.
 
     Returns:
@@ -76,7 +80,10 @@ async def list_directory(
     Raises:
         ToolError: If project doesn't exist or directory path is invalid
     """
-    async with get_project_client(project, context=context) as (client, active_project):
+    async with get_project_client(project, context=context, project_id=project_id) as (
+        client,
+        active_project,
+    ):
         logger.debug(
             f"Listing directory '{dir_name}' in project {project} with depth={depth}, glob='{file_name_glob}'"
         )

src/basic_memory/mcp/tools/move_note.py

@@ -371,6 +371,7 @@ async def move_note(
         Field(default=False, validation_alias=AliasChoices("is_directory", "is_dir")),
     ] = False,
     project: Optional[str] = None,
+    project_id: Optional[str] = None,
     output_format: Literal["text", "json"] = "text",
     context: Context | None = None,
 ) -> str | dict:
@@ -395,6 +396,9 @@ async def move_note(
                      (without file extensions). Defaults to False.
         project: Project name to move within. Optional - server will resolve using hierarchy.
                 If unknown, use list_memory_projects() to discover available projects.
+        project_id: Project external_id (UUID). Prefer this over `project` when known —
+                it routes to the exact project regardless of name collisions across cloud
+                workspaces. Takes precedence over `project`. Get from list_memory_projects().
         output_format: "text" returns existing markdown guidance/success text. "json"
             returns machine-readable move metadata.
         context: Optional FastMCP context for performance caching.
@@ -494,7 +498,10 @@ async def move_note(
                 "error": "DESTINATION_FOLDER_NOT_FOR_DIRECTORIES",
             }
         return f"# Move Failed - Invalid Parameters\n\n{error_msg}"
-    async with get_project_client(project, context=context) as (client, active_project):
+    async with get_project_client(project, context=context, project_id=project_id) as (
+        client,
+        active_project,
+    ):
         destination_target = destination_folder or destination_path
         logger.info(
             f"MCP tool call tool=move_note project={active_project.name} "

src/basic_memory/mcp/tools/project_management.py

@@ -264,6 +264,11 @@ async def list_memory_projects(
     Shows projects from both local and cloud sources when cloud credentials
     are available, merging by permalink to give a unified view.
 
+    Each project entry includes an `external_id` (UUID). Pass that value as the
+    `project_id` parameter on other tools to address a specific project
+    unambiguously across cloud workspaces — useful when the same project name
+    exists in more than one workspace.
+
     Args:
         output_format: "text" returns the existing human-readable project list.
             "json" returns structured project metadata.