fix(mcp): honor workspace canonical edge cases

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

Author: phernandez

src/basic_memory/mcp/tools/delete_note.py

@@ -155,7 +155,12 @@ def _format_delete_error_response(project: str, error_message: str, identifier:
 If the note should be deleted but the operation keeps failing, send a message to support@basicmemory.com."""
 
 
-def _directory_path_for_delete(target_identifier: str, active_project: ProjectItem) -> str:
+def _directory_path_for_delete(
+    target_identifier: str,
+    active_project: ProjectItem,
+    *,
+    include_project_prefix: bool,
+) -> str:
     """Return the project-relative directory path expected by the delete API."""
     directory = normalize_project_reference(target_identifier).strip("/")
     project_permalink = active_project.permalink
@@ -166,7 +171,8 @@ def _directory_path_for_delete(target_identifier: str, active_project: ProjectIt
         route_prefixes.append(
             f"{generate_permalink(workspace_context.workspace_slug)}/{project_permalink}"
         )
-    route_prefixes.append(project_permalink)
+    if include_project_prefix:
+        route_prefixes.append(project_permalink)
 
     for route_prefix in route_prefixes:
         if directory.startswith(f"{route_prefix}/"):
@@ -299,7 +305,11 @@ async def delete_note(
                 #   delete_directory filters by project-relative file_path prefixes.
                 # Outcome: strip only the route prefix before calling the delete API.
                 directory_identifier = (
-                    _directory_path_for_delete(target_identifier, active_project)
+                    _directory_path_for_delete(
+                        target_identifier,
+                        active_project,
+                        include_project_prefix=ConfigManager().config.permalinks_include_project,
+                    )
                     if is_memory_url
                     else target_identifier
                 )

src/basic_memory/services/entity_service.py

@@ -206,14 +206,15 @@ async def resolve_permalink(
             if self.app_config:
                 include_project = self.app_config.permalinks_include_project
 
+            workspace_permalink = workspace_slug_for_canonical_permalinks()
             project_permalink = None
-            # Trigger: project-prefixed permalinks are enabled
-            # Why: we need the project slug to build the canonical permalink
-            # Outcome: fetch and cache the project's permalink
-            if include_project:
+            # Trigger: project-prefixed permalinks are enabled, or organization workspace
+            #   context requires a complete workspace/project canonical permalink.
+            # Why: project slug is the stable middle segment for globally addressable links.
+            # Outcome: fetch and cache the project's permalink before building the canonical URL.
+            if include_project or workspace_permalink:
                 project_permalink = await self._get_project_permalink()
 
-            workspace_permalink = workspace_slug_for_canonical_permalinks()
             desired_permalink = build_canonical_permalink(
                 project_permalink,
                 file_path_str,

src/basic_memory/utils.py

@@ -240,30 +240,40 @@ def build_canonical_permalink(
         Canonical permalink string.
     """
     normalized_path = generate_permalink(file_path)
-
-    if not include_project or not project_permalink:
-        return normalized_path
-
-    normalized_project = generate_permalink(project_permalink)
     normalized_workspace = generate_permalink(workspace_permalink) if workspace_permalink else None
+
     if normalized_workspace:
+        if not project_permalink:
+            raise ValueError("workspace_permalink requires project_permalink")
+
+        normalized_project = generate_permalink(project_permalink)
         workspace_project_prefix = f"{normalized_workspace}/{normalized_project}"
         if normalized_path == workspace_project_prefix or normalized_path.startswith(
             f"{workspace_project_prefix}/"
         ):
             return normalized_path
 
+        if normalized_path == normalized_project or normalized_path.startswith(
+            f"{normalized_project}/"
+        ):
+            project_path = normalized_path
+        else:
+            project_path = f"{normalized_project}/{normalized_path}"
+
+        return f"{normalized_workspace}/{project_path}"
+
+    if not include_project or not project_permalink:
+        return normalized_path
+
+    normalized_project = generate_permalink(project_permalink)
     if normalized_path == normalized_project or normalized_path.startswith(
         f"{normalized_project}/"
     ):
         project_path = normalized_path
     else:
         project_path = f"{normalized_project}/{normalized_path}"
 
-    if not workspace_permalink:
-        return project_path
-
-    return f"{normalized_workspace}/{project_path}"
+    return project_path
 
 
 def setup_logging(

tests/mcp/test_project_context.py

@@ -829,6 +829,48 @@ async def fake_index(context=None):
     assert resolved.canonical_path == "main/notes/foo"
 
 
+@pytest.mark.asyncio
+async def test_resolve_workspace_qualified_memory_url_keeps_org_canonical_path_without_project_prefix(
+    config_manager,
+    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,
+    )
+
+    config = config_manager.load_config()
+    config.permalinks_include_project = False
+    config_manager.save_config(config)
+
+    team = _workspace(
+        tenant_id="team-tenant",
+        workspace_type="organization",
+        slug="team-paul",
+        name="Team Paul",
+        role="editor",
+    )
+    entries = (
+        WorkspaceProjectEntry(
+            workspace=team,
+            project=_project("main", id=1, external_id="team-main-id"),
+        ),
+    )
+    index = _build_workspace_project_index((team,), 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://team-paul/main/notes/foo")
+
+    assert resolved is not None
+    assert resolved.canonical_path == "team-paul/main/notes/foo"
+
+
 @pytest.mark.asyncio
 async def test_get_project_client_routes_duplicate_project_through_workspace_slug(
     config_manager,

tests/mcp/test_tool_delete_note.py

@@ -205,6 +205,50 @@ async def test_delete_directory_memory_url_strips_project_prefix(client, test_pr
     assert result["failed_deletes"] == 0
 
 
+@pytest.mark.asyncio
+async def test_delete_directory_memory_url_keeps_real_project_prefix_when_prefixes_disabled(
+    client,
+    test_project,
+    config_manager,
+):
+    """When project prefixes are disabled, resolved directory paths are already project-relative."""
+    config = config_manager.load_config()
+    config.permalinks_include_project = False
+    config_manager.save_config(config)
+
+    real_directory = f"{test_project.name}/archive"
+    await write_note(
+        project=test_project.name,
+        title="Delete Directory Real Project Prefix",
+        directory=real_directory,
+        content="# Delete Directory Real Project Prefix\nDelete target content.",
+    )
+    await write_note(
+        project=test_project.name,
+        title="Keep Directory Decoy",
+        directory="archive",
+        content="# Keep Directory Decoy\nDecoy content.",
+    )
+
+    result = await delete_note(
+        identifier=f"memory://{test_project.name}/{real_directory}",
+        is_directory=True,
+        project=test_project.name,
+        output_format="json",
+    )
+
+    assert isinstance(result, dict)
+    assert result["deleted"] is True
+    assert result["total_files"] == 1
+    assert result["successful_deletes"] == 1
+    assert result["failed_deletes"] == 0
+
+    deleted = await read_note("Delete Directory Real Project Prefix", project=test_project.name)
+    assert "Delete target content" not in deleted
+    decoy = await read_note("Keep Directory Decoy", project=test_project.name)
+    assert "Decoy content" in decoy
+
+
 @pytest.mark.asyncio
 async def test_delete_directory_workspace_memory_url_strips_route_prefix(client, test_project):
     """Workspace-qualified memory:// directory deletes still hit project-relative files."""

tests/mcp/test_tool_read_note.py

@@ -328,6 +328,46 @@ async def test_team_workspace_write_stores_complete_canonical_permalink(
     assert read_result["content"].strip() == "Team canonical content"
 
 
+@pytest.mark.asyncio
+async def test_team_workspace_write_stores_complete_permalink_when_project_prefixes_disabled(
+    app,
+    test_project,
+    entity_repository,
+    config_manager,
+):
+    from basic_memory.workspace_context import workspace_permalink_context
+
+    config = config_manager.load_config()
+    config.permalinks_include_project = False
+    config_manager.save_config(config)
+
+    expected_permalink = f"team-paul/{test_project.name}/team/team-no-project-prefix-note"
+
+    with workspace_permalink_context(workspace_slug="team-paul", workspace_type="organization"):
+        write_result = await write_note(
+            project=test_project.name,
+            title="Team No Project Prefix Note",
+            directory="team",
+            content="Team canonical content without project-prefix config",
+        )
+
+    assert f"permalink: {expected_permalink}" in write_result
+
+    stored = await entity_repository.get_by_permalink(expected_permalink)
+    assert stored is not None
+    assert stored.permalink == expected_permalink
+
+    read_result = await read_note(
+        f"memory://{expected_permalink}",
+        project=test_project.name,
+        output_format="json",
+    )
+
+    assert isinstance(read_result, dict)
+    assert read_result["permalink"] == expected_permalink
+    assert read_result["content"].strip() == "Team canonical content without project-prefix config"
+
+
 @pytest.mark.asyncio
 async def test_personal_workspace_write_keeps_project_scoped_permalink(
     app,

tests/utils/test_permalink_formatting.py

@@ -8,6 +8,7 @@
 from basic_memory.services import EntityService
 from basic_memory.sync.sync_service import SyncService
 from basic_memory.utils import build_canonical_permalink, generate_permalink
+from basic_memory.workspace_context import workspace_permalink_context
 
 
 async def create_test_file(path: Path, content: str = "test content") -> None:
@@ -148,3 +149,32 @@ def test_build_canonical_permalink_preserves_complete_workspace_prefix():
         )
         == "team-paul/main/notes/foo"
     )
+
+
+def test_build_canonical_permalink_workspace_prefix_ignores_project_prefix_flag():
+    """Organization workspace canonical permalinks always include workspace and project."""
+    assert (
+        build_canonical_permalink(
+            "main",
+            "notes/foo.md",
+            include_project=False,
+            workspace_permalink="team-paul",
+        )
+        == "team-paul/main/notes/foo"
+    )
+
+
+@pytest.mark.asyncio
+async def test_entity_service_workspace_permalink_uses_project_when_prefixes_disabled(
+    entity_service: EntityService,
+    project_config: ProjectConfig,
+):
+    """Workspace note creation uses complete canonical shape even without local project prefixes."""
+    assert entity_service.app_config is not None
+    entity_service.app_config.permalinks_include_project = False
+
+    with workspace_permalink_context("team-paul", "organization"):
+        permalink = await entity_service.resolve_permalink("team/no-project-prefix-service.md")
+
+    project_permalink = generate_permalink(project_config.name)
+    assert permalink == f"team-paul/{project_permalink}/team/no-project-prefix-service"