fix(mcp): preserve local memory url fallback

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

Author: phernandez

src/basic_memory/api/app.py

@@ -33,7 +33,7 @@
 from basic_memory.workspace_context import (
     WORKSPACE_SLUG_HEADER,
     WORKSPACE_TYPE_HEADER,
-    validate_workspace_permalink_context_values,
+    workspace_permalink_context_validation_error,
     workspace_permalink_context,
 )
 
@@ -101,12 +101,11 @@ async def workspace_permalink_context_middleware(request: Request, call_next):
     workspace_slug = request.headers.get(WORKSPACE_SLUG_HEADER)
     workspace_type = request.headers.get(WORKSPACE_TYPE_HEADER)
 
-    try:
-        validate_workspace_permalink_context_values(workspace_slug, workspace_type)
-    except ValueError as exc:
+    validation_error = workspace_permalink_context_validation_error(workspace_slug, workspace_type)
+    if validation_error is not None:
         return JSONResponse(
             status_code=400,
-            content={"detail": str(exc)},
+            content={"detail": validation_error},
         )
 
     if not workspace_slug:

src/basic_memory/mcp/project_context.py

@@ -433,10 +433,13 @@ def _cloud_workspace_discovery_available(config: BasicMemoryConfig) -> bool:
     if _explicit_routing() and _force_local_mode():
         return False
 
+    # Trigger: local project config is present even though cloud credentials are saved.
+    # Why: existing local `memory://...` URLs must not depend on workspace discovery.
+    # Outcome: only factory, explicit cloud, or cloud-only sessions attempt discovery here.
     return (
         is_factory_mode()
         or (_explicit_routing() and not _force_local_mode())
-        or has_cloud_credentials(config)
+        or (not config.projects and has_cloud_credentials(config))
     )
 
 
@@ -474,15 +477,14 @@ async def resolve_workspace_qualified_memory_url(
                 "could not be loaded. Retry after workspace discovery recovers."
             )
 
-        available = ", ".join(
-            entry.qualified_name
-            for entry in index.entries
-            if entry.workspace.tenant_id == workspace.tenant_id
-        )
-        raise ValueError(
-            f"Project '{project_identifier}' was not found in workspace "
-            f"'{workspace.name}' ({workspace.slug}). Available projects: {available}"
-        )
+        # Trigger: first segment matches a workspace slug but the second does not
+        #   match a project in that workspace.
+        # Why: workspace-qualified URLs require both route segments to match; otherwise
+        #   existing project-prefixed URLs like `memory://main/notes/foo` can collide
+        #   with a workspace slug named `main`.
+        # Outcome: treat this as not workspace-qualified and let the caller use
+        #   the existing project-prefix/default-project resolver.
+        return None
     if len(matches) > 1:
         details = ", ".join(
             f"{entry.qualified_name} ({entry.project.external_id})" for entry in matches
@@ -1121,6 +1123,10 @@ async def detect_project_from_memory_url_prefix(
     if not identifier.strip().startswith("memory://"):
         return None
 
+    local_project = detect_project_from_url_prefix(identifier, config)
+    if local_project is not None:
+        return local_project
+
     if _cloud_workspace_discovery_available(config):
         resolution = await resolve_workspace_qualified_memory_url(
             identifier,
@@ -1129,7 +1135,7 @@ async def detect_project_from_memory_url_prefix(
         if resolution is not None:
             return resolution.project_identifier
 
-    return detect_project_from_url_prefix(identifier, config)
+    return None
 
 
 @asynccontextmanager

src/basic_memory/workspace_context.py

@@ -40,18 +40,30 @@ def validate_workspace_permalink_context_values(
     workspace_type: str | None,
 ) -> None:
     """Validate workspace permalink metadata before it can affect stored permalinks."""
+    validation_error = workspace_permalink_context_validation_error(workspace_slug, workspace_type)
+    if validation_error is not None:
+        raise ValueError(validation_error)
+
+
+def workspace_permalink_context_validation_error(
+    workspace_slug: str | None,
+    workspace_type: str | None,
+) -> str | None:
+    """Return the validation error for workspace permalink metadata, if any."""
     if bool(workspace_slug) != bool(workspace_type):
-        raise ValueError("workspace_slug and workspace_type must be provided together")
+        return "workspace_slug and workspace_type must be provided together"
 
     if not workspace_slug or not workspace_type:
-        return
+        return None
 
     if _WORKSPACE_SLUG_PATTERN.fullmatch(workspace_slug) is None:
-        raise ValueError(f"{WORKSPACE_SLUG_HEADER} must match [a-z0-9_-]+")
+        return f"{WORKSPACE_SLUG_HEADER} must match [a-z0-9_-]+"
 
     if workspace_type not in _WORKSPACE_TYPES:
         allowed = ", ".join(sorted(_WORKSPACE_TYPES))
-        raise ValueError(f"{WORKSPACE_TYPE_HEADER} must be one of: {allowed}")
+        return f"{WORKSPACE_TYPE_HEADER} must be one of: {allowed}"
+
+    return None
 
 
 @contextmanager

tests/mcp/test_project_context.py

@@ -663,6 +663,90 @@ async def fake_index(context=None):
     assert resolved == "team-paul/main"
 
 
+@pytest.mark.asyncio
+async def test_detect_project_from_memory_url_prefix_prefers_local_project_prefix(
+    monkeypatch,
+):
+    import basic_memory.mcp.project_context as project_context
+    from basic_memory.config import BasicMemoryConfig, ProjectEntry
+    from basic_memory.mcp.project_context import detect_project_from_memory_url_prefix
+
+    async def fail_if_called(context=None):  # pragma: no cover
+        raise AssertionError("Local project-prefixed memory URLs must not discover workspaces")
+
+    monkeypatch.setattr(project_context, "_ensure_workspace_project_index", fail_if_called)
+
+    resolved = await detect_project_from_memory_url_prefix(
+        "memory://main/notes/foo",
+        BasicMemoryConfig(
+            projects={"main": ProjectEntry(path="/tmp/main")},
+            cloud_api_key="bmc_test123",
+        ),
+    )
+
+    assert resolved == "main"
+
+
+@pytest.mark.asyncio
+async def test_detect_project_from_memory_url_prefix_skips_workspace_discovery_for_local_config(
+    monkeypatch,
+):
+    import basic_memory.mcp.project_context as project_context
+    from basic_memory.config import BasicMemoryConfig, ProjectEntry
+    from basic_memory.mcp.project_context import detect_project_from_memory_url_prefix
+
+    async def fail_if_called(context=None):  # pragma: no cover
+        raise AssertionError("Saved cloud credentials must not force local workspace discovery")
+
+    monkeypatch.setattr(project_context, "_ensure_workspace_project_index", fail_if_called)
+
+    resolved = await detect_project_from_memory_url_prefix(
+        "memory://notes/foo/bar",
+        BasicMemoryConfig(
+            projects={"main": ProjectEntry(path="/tmp/main")},
+            cloud_api_key="bmc_test123",
+        ),
+    )
+
+    assert resolved is None
+
+
+@pytest.mark.asyncio
+async def test_resolve_workspace_qualified_memory_url_ignores_workspace_project_miss(
+    monkeypatch,
+):
+    import basic_memory.mcp.project_context as project_context
+    from basic_memory.mcp.project_context import (
+        WorkspaceProjectEntry,
+        _build_workspace_project_index,
+        resolve_workspace_qualified_memory_url,
+    )
+
+    workspace = _workspace(
+        tenant_id="main-tenant",
+        workspace_type="organization",
+        slug="main",
+        name="Main Workspace",
+        role="editor",
+    )
+    entries = (
+        WorkspaceProjectEntry(
+            workspace=workspace,
+            project=_project("research", id=1, external_id="research-project-id"),
+        ),
+    )
+    index = _build_workspace_project_index((workspace,), entries)
+
+    async def fake_index(context=None):
+        return index
+
+    monkeypatch.setattr(project_context, "_ensure_workspace_project_index", fake_index)
+
+    resolved = await resolve_workspace_qualified_memory_url("memory://main/notes/foo")
+
+    assert resolved is None
+
+
 @pytest.mark.asyncio
 async def test_resolve_workspace_qualified_memory_url_fails_on_duplicate_project_permalink(
     monkeypatch,