fix cloud workspace routing and incremental sync

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

Author: phernandez

src/basic_memory/cli/commands/cloud/cloud_utils.py

@@ -2,6 +2,7 @@
 
 from basic_memory.cli.commands.cloud.api_client import make_api_request
 from basic_memory.config import ConfigManager
+from basic_memory.mcp.async_client import resolve_configured_workspace
 from basic_memory.schemas.cloud import (
     CloudProjectList,
     CloudProjectCreateRequest,
@@ -16,8 +17,25 @@ class CloudUtilsError(Exception):
     pass
 
 
+def _workspace_headers(
+    *,
+    project_name: str | None = None,
+    workspace: str | None = None,
+) -> dict[str, str]:
+    """Build optional workspace headers using the CLI config resolution chain."""
+    resolved_workspace = resolve_configured_workspace(
+        project_name=project_name,
+        workspace=workspace,
+    )
+    if resolved_workspace is None:
+        return {}
+    return {"X-Workspace-ID": resolved_workspace}
+
+
 async def fetch_cloud_projects(
     *,
+    project_name: str | None = None,
+    workspace: str | None = None,
     api_request=make_api_request,
 ) -> CloudProjectList:
     """Fetch list of projects from cloud API.
@@ -30,7 +48,11 @@ async def fetch_cloud_projects(
         config = config_manager.config
         host_url = config.cloud_host.rstrip("/")
 
-        response = await api_request(method="GET", url=f"{host_url}/proxy/v2/projects/")
+        response = await api_request(
+            method="GET",
+            url=f"{host_url}/proxy/v2/projects/",
+            headers=_workspace_headers(project_name=project_name, workspace=workspace),
+        )
 
         return CloudProjectList.model_validate(response.json())
     except Exception as e:
@@ -40,6 +62,7 @@ async def fetch_cloud_projects(
 async def create_cloud_project(
     project_name: str,
     *,
+    workspace: str | None = None,
     api_request=make_api_request,
 ) -> CloudProjectCreateResponse:
     """Create a new project on cloud.
@@ -67,7 +90,10 @@ async def create_cloud_project(
         response = await api_request(
             method="POST",
             url=f"{host_url}/proxy/v2/projects/",
-            headers={"Content-Type": "application/json"},
+            headers={
+                "Content-Type": "application/json",
+                **_workspace_headers(project_name=project_name, workspace=workspace),
+            },
             json_data=project_data.model_dump(),
         )
 
@@ -91,7 +117,12 @@ async def sync_project(project_name: str, force_full: bool = False) -> None:
         raise CloudUtilsError(f"Failed to sync project '{project_name}': {e}") from e
 
 
-async def project_exists(project_name: str, *, api_request=make_api_request) -> bool:
+async def project_exists(
+    project_name: str,
+    *,
+    workspace: str | None = None,
+    api_request=make_api_request,
+) -> bool:
     """Check if a project exists on cloud.
 
     Args:
@@ -101,7 +132,11 @@ async def project_exists(project_name: str, *, api_request=make_api_request) ->
         True if project exists, False otherwise
     """
     try:
-        projects = await fetch_cloud_projects(api_request=api_request)
+        projects = await fetch_cloud_projects(
+            project_name=project_name,
+            workspace=workspace,
+            api_request=api_request,
+        )
         project_names = {p.name for p in projects.projects}
         return project_name in project_names
     except Exception:

src/basic_memory/cli/commands/cloud/project_sync.py

@@ -54,7 +54,7 @@ def _require_cloud_credentials(config) -> None:
 
 async def _get_cloud_project(name: str) -> ProjectItem | None:
     """Fetch a project by name from the cloud API."""
-    async with get_client() as client:
+    async with get_client(project_name=name) as client:
         projects_list = await ProjectClient(client).list_projects()
         for proj in projects_list.projects:
             if generate_permalink(proj.name) == generate_permalink(name):
@@ -129,9 +129,9 @@ def sync_project_command(
             if not dry_run:
 
                 async def _trigger_db_sync():
-                    async with get_client() as client:
+                    async with get_client(project_name=name) as client:
                         return await ProjectClient(client).sync(
-                            project_data.external_id, force_full=True
+                            project_data.external_id, force_full=False
                         )
 
                 try:
@@ -204,9 +204,9 @@ def bisync_project_command(
             if not dry_run:
 
                 async def _trigger_db_sync():
-                    async with get_client() as client:
+                    async with get_client(project_name=name) as client:
                         return await ProjectClient(client).sync(
-                            project_data.external_id, force_full=True
+                            project_data.external_id, force_full=False
                         )
 
                 try:
@@ -320,7 +320,7 @@ def setup_project_sync(
 
     async def _verify_project_exists():
         """Verify the project exists on cloud by listing all projects."""
-        async with get_client() as client:
+        async with get_client(project_name=name) as client:
             projects_list = await ProjectClient(client).list_projects()
             project_names = [p.name for p in projects_list.projects]
             if name not in project_names:

src/basic_memory/cli/commands/cloud/upload_command.py

@@ -1,5 +1,6 @@
 """Upload CLI commands for basic-memory projects."""
 
+from functools import partial
 from pathlib import Path
 
 import typer
@@ -13,7 +14,10 @@
     sync_project,
 )
 from basic_memory.cli.commands.cloud.upload import upload_path
-from basic_memory.mcp.async_client import get_cloud_control_plane_client
+from basic_memory.mcp.async_client import (
+    get_cloud_control_plane_client,
+    resolve_configured_workspace,
+)
 
 console = Console()
 
@@ -73,12 +77,14 @@ def upload(
     """
 
     async def _upload():
+        resolved_workspace = resolve_configured_workspace(project_name=project)
+
         # Check if project exists
-        if not await project_exists(project):
+        if not await project_exists(project, workspace=resolved_workspace):
             if create_project:
                 console.print(f"[blue]Creating cloud project '{project}'...[/blue]")
                 try:
-                    await create_cloud_project(project)
+                    await create_cloud_project(project, workspace=resolved_workspace)
                     console.print(f"[green]Created project '{project}'[/green]")
                 except Exception as e:
                     console.print(f"[red]Failed to create project: {e}[/red]")
@@ -106,7 +112,10 @@ async def _upload():
             verbose=verbose,
             use_gitignore=not no_gitignore,
             dry_run=dry_run,
-            client_cm_factory=get_cloud_control_plane_client,
+            client_cm_factory=partial(
+                get_cloud_control_plane_client,
+                workspace=resolved_workspace,
+            ),
         )
         if not success:
             console.print("[red]Upload failed[/red]")

src/basic_memory/mcp/async_client.py

@@ -66,6 +66,27 @@ async def _resolve_cloud_token(config) -> str:
         )
 
 
+def resolve_configured_workspace(
+    *,
+    config=None,
+    project_name: Optional[str] = None,
+    workspace: Optional[str] = None,
+) -> Optional[str]:
+    """Resolve workspace from explicit input, per-project config, then global default."""
+    if workspace is not None:
+        return workspace
+
+    if config is None:
+        config = ConfigManager().config
+
+    if project_name is not None:
+        project_entry = config.projects.get(project_name)
+        if project_entry and project_entry.workspace_id:
+            return project_entry.workspace_id
+
+    return config.default_workspace
+
+
 @asynccontextmanager
 async def _cloud_client(
     config,
@@ -88,15 +109,20 @@ async def _cloud_client(
 
 
 @asynccontextmanager
-async def get_cloud_control_plane_client() -> AsyncIterator[AsyncClient]:
+async def get_cloud_control_plane_client(
+    workspace: Optional[str] = None,
+) -> AsyncIterator[AsyncClient]:
     """Create a control-plane cloud client for endpoints outside /proxy."""
     config = ConfigManager().config
     timeout = _build_timeout()
     token = await _resolve_cloud_token(config)
+    headers = {"Authorization": f"Bearer {token}"}
+    if workspace:
+        headers["X-Workspace-ID"] = workspace
     logger.info(f"Creating HTTP client for cloud control plane at: {config.cloud_host}")
     async with AsyncClient(
         base_url=config.cloud_host,
-        headers={"Authorization": f"Bearer {token}"},
+        headers=headers,
         timeout=timeout,
     ) as client:
         yield client
@@ -167,7 +193,12 @@ async def get_client(
 
         if _force_cloud_mode():
             logger.debug("Explicit cloud routing enabled - using cloud proxy client")
-            async with _cloud_client(config, timeout, workspace=workspace) as client:
+            effective_workspace = resolve_configured_workspace(
+                config=config,
+                project_name=project_name,
+                workspace=workspace,
+            )
+            async with _cloud_client(config, timeout, workspace=effective_workspace) as client:
                 yield client
             return
 
@@ -179,8 +210,13 @@ async def get_client(
         project_mode = config.get_project_mode(project_name)
         if project_mode == ProjectMode.CLOUD:
             logger.debug(f"Project '{project_name}' is cloud mode - using cloud proxy client")
+            effective_workspace = resolve_configured_workspace(
+                config=config,
+                project_name=project_name,
+                workspace=workspace,
+            )
             try:
-                async with _cloud_client(config, timeout, workspace=workspace) as client:
+                async with _cloud_client(config, timeout, workspace=effective_workspace) as client:
                     yield client
             except RuntimeError as exc:
                 raise RuntimeError(

tests/cli/cloud/test_cloud_api_client_and_utils.py

@@ -14,6 +14,7 @@
     fetch_cloud_projects,
     project_exists,
 )
+from basic_memory.config import ProjectMode
 
 
 @pytest.mark.asyncio
@@ -165,6 +166,56 @@ async def api_request(**kwargs):
     assert seen["create_payload"]["path"] == "my-project"
 
 
+@pytest.mark.asyncio
+async def test_cloud_utils_use_configured_workspace_headers(config_home, config_manager):
+    """Workspace-aware cloud helpers should prefer project workspace over global default."""
+    config = config_manager.load_config()
+    config.cloud_host = "https://cloud.example.test"
+    config.default_workspace = "default-workspace"
+    config.set_project_mode("alpha", ProjectMode.CLOUD)
+    config.projects["alpha"].workspace_id = "project-workspace"
+    config_manager.save_config(config)
+
+    seen: list[tuple[str, str | None]] = []
+
+    async def api_request(**kwargs):
+        seen.append(
+            (
+                kwargs["method"],
+                (kwargs.get("headers") or {}).get("X-Workspace-ID"),
+            )
+        )
+
+        if kwargs["method"] == "GET":
+            return httpx.Response(
+                200,
+                json={
+                    "projects": [{"id": 1, "name": "alpha", "path": "alpha", "is_default": True}]
+                },
+            )
+
+        return httpx.Response(
+            200,
+            json={
+                "message": "created",
+                "status": "success",
+                "default": False,
+                "old_project": None,
+                "new_project": {"name": "alpha", "path": "alpha"},
+            },
+        )
+
+    assert await project_exists("alpha", api_request=api_request) is True
+    await create_cloud_project("alpha", api_request=api_request)
+    await fetch_cloud_projects(project_name="missing", api_request=api_request)
+
+    assert seen == [
+        ("GET", "project-workspace"),
+        ("POST", "project-workspace"),
+        ("GET", "default-workspace"),
+    ]
+
+
 @pytest.mark.asyncio
 async def test_make_api_request_prefers_api_key_over_oauth(config_home, config_manager):
     """API key in config should be used without needing an OAuth token on disk."""