basic-memory 0.23.1.dev20__tar.gz → 0.23.1.dev27__tar.gz

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## Unreleased
 
+## v0.23.1 (2026-08-25)
+
+Fast-follow patch to v0.23.0 focused on PostgreSQL search parity and a
+search-destroying reindex bug. Postgres now indexes complete note bodies for
+full-text search (previously only titles and capped content stems, unlike
+SQLite), and the per-project search reindex no longer wipes every other
+project's search rows in the same database. Also adds a `#bm:links_to`
+directive for disambiguating prose wiki-links, and hardens `bm update` output
+after in-place upgrades.
+
+### Features
+
+- Added the `#bm:links_to` directive: ending a list item with `#bm:links_to`
+  forces the reference to the implicit `links_to` relation, so a single-token
+  prose prefix (`- Mother [[Alice]] #bm:links_to`) is not parsed as an
+  explicit relation type. The directive stays in the source file but is
+  stripped from indexed observation and relation content.
+
+### Bug Fixes
+
+- PostgreSQL full-text search now covers complete note bodies. Note content is
+  indexed as bounded, overlapping chunks in a new `search_index_fts_chunks`
+  table (a migration backfills existing notes), so deep content matches on
+  Postgres the way it always has on SQLite FTS5. The work includes correct
+  Boolean AND/NOT semantics across chunk boundaries, apostrophe and
+  punctuated-operand handling (`can't`, `v0.13.0b2`, `auth-service`),
+  metadata-filter composition, 100+ operand queries, and candidate
+  preselection so both GIN indexes stay in play.
+- The per-project search reindex (`POST /search/reindex`) no longer drops the
+  shared `search_index` table. Dropping it destroyed every project's search
+  rows in the same database — and on Postgres nothing outside migrations
+  recreates the table, so cloud tenants lost search entirely until manual
+  repair. The rebuild now deletes only the reindexed project's rows (chunk
+  rows cascade), and the chunks migration recreates a missing `search_index`
+  so databases hit by the old behavior migrate cleanly.
+- **#1316**: `bm update` status output no longer crashes after an in-place
+  upgrade removes the running install's files: rich's deferred Unicode width
+  table is preloaded before upgrading, and status lines fall back to plain
+  output instead of failing a completed update.
+- **#1323**: `bm doctor` no longer fails when `BASIC_MEMORY_PROJECT_ROOT`
+  points at an existing project's directory. Doctor now asks the server for a
+  disposable `doctor-*` project under the configured root — the only
+  sanctioned exception to the nested-project guard — and cleanup deletes the
+  project's directory along with its registration.
+- `bm doctor` waits for deferred note materialization before verifying the
+  API-written file, matching the accepted-write contract instead of racing it.
+
 ## v0.23.0 (2026-08-23)
 
 Semantic search grows up and concurrent writes stop deadlocking. Search gains

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: basic-memory
-Version: 0.23.1.dev20
+Version: 0.23.1.dev27
 Summary: Local-first knowledge management combining Zettelkasten with knowledge graphs
 Project-URL: Homepage, https://github.com/basicmachines-co/basic-memory
 Project-URL: Repository, https://github.com/basicmachines-co/basic-memory

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/alembic/versions/7f6a2b8c9d10_index_full_postgres_note_content.py

@@ -22,6 +22,62 @@ def upgrade() -> None:
     """Index complete note bodies as bounded PostgreSQL FTS chunks."""
     connection = op.get_bind()
     if connection.dialect.name == "postgresql":
+        # --- Repair: recreate search_index if a destructive reindex removed it ---
+        # Trigger: search_index does not exist. Through v0.23.0, the per-project
+        # search reindex ran DROP TABLE IF EXISTS search_index, and on Postgres
+        # nothing outside migrations recreates that table.
+        # Why: the chunk backfill below reads search_index and the chunks table
+        # declares a foreign key to it, so without repair this migration fails
+        # permanently and blocks the database from ever reaching head.
+        # Outcome: healthy databases no-op on IF NOT EXISTS; a repaired database
+        # gets an empty index that the next full reindex repopulates. The DDL
+        # mirrors the current schema in models/search.py.
+        op.execute("""
+            CREATE TABLE IF NOT EXISTS search_index (
+                id INTEGER NOT NULL,
+                project_id INTEGER NOT NULL,
+                title TEXT,
+                content_stems TEXT,
+                content_snippet TEXT,
+                permalink VARCHAR,
+                file_path VARCHAR,
+                type VARCHAR,
+                from_id INTEGER,
+                to_id INTEGER,
+                relation_type VARCHAR,
+                entity_id INTEGER,
+                category VARCHAR,
+                metadata JSONB,
+                created_at TIMESTAMP WITH TIME ZONE,
+                updated_at TIMESTAMP WITH TIME ZONE,
+                textsearchable_index_col tsvector GENERATED ALWAYS AS (
+                    to_tsvector(
+                        'english',
+                        coalesce(title, '') || ' ' ||
+                        coalesce(content_stems, '')
+                    )
+                ) STORED,
+                PRIMARY KEY (id, type, project_id),
+                FOREIGN KEY (project_id) REFERENCES project(id) ON DELETE CASCADE
+            )
+        """)
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS ix_search_index_project_id
+            ON search_index (project_id)
+        """)
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_search_index_fts
+            ON search_index USING gin(textsearchable_index_col)
+        """)
+        op.execute("""
+            CREATE INDEX IF NOT EXISTS idx_search_index_metadata_gin
+            ON search_index USING gin(metadata jsonb_path_ops)
+        """)
+        op.execute("""
+            CREATE UNIQUE INDEX IF NOT EXISTS uix_search_index_permalink_project
+            ON search_index (permalink, project_id)
+            WHERE permalink IS NOT NULL
+        """)
         op.execute("""
             CREATE TABLE search_index_fts_chunks (
                 project_id INTEGER NOT NULL,

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/api/v2/routers/project_router.py

@@ -221,6 +221,28 @@ async def add_project(
         raise HTTPException(status_code=400, detail=str(e))
 
 
+@router.post("/doctor", response_model=ProjectStatusResponse, status_code=201)
+async def add_doctor_project(project_service: ProjectServiceDep) -> ProjectStatusResponse:
+    """Create a server-generated disposable project for the local doctor check."""
+    try:
+        new_project = await project_service.add_doctor_project()
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return ProjectStatusResponse(
+        message=f"Project '{new_project.name}' added successfully",
+        status="success",
+        default=new_project.is_default or False,
+        new_project=ProjectItem(
+            id=new_project.id,
+            external_id=new_project.external_id,
+            name=new_project.name,
+            path=new_project.path,
+            is_default=new_project.is_default or False,
+        ),
+    )
+
+
 @router.post("/config/sync", response_model=ProjectStatusResponse)
 async def synchronize_projects(
     project_service: ProjectServiceDep,

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/cli/commands/doctor.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import tempfile
 import uuid
 from pathlib import Path
+from typing import Protocol
 
 from loguru import logger
 from rich.console import Console
@@ -23,6 +24,14 @@ from basic_memory.schemas import ProjectIndexRunResponse
 console = Console()
 
 
+class DoctorProjectClient(Protocol):
+    """Project-client capability required to clean up doctor state."""
+
+    async def delete_project(
+        self, project_external_id: str, delete_notes: bool = False
+    ) -> object: ...
+
+
 def _is_default_project_delete_error(error: Exception) -> bool:
     """Return True only for the API guard that blocks deleting the default project."""
     error_text = str(error)
@@ -61,14 +70,14 @@ async def _delete_doctor_project_locally(project_name: str, project_id: str) ->
 
 
 async def _delete_doctor_project(
-    project_client: ProjectClient, project_name: str, project_id: str
+    project_client: DoctorProjectClient, project_name: str, project_id: str
 ) -> None:
     """Delete the generated doctor project without weakening the public API guard."""
     # Deferred: ToolError lives in FastMCP's runtime, which must not load at CLI startup (#886).
     from fastmcp.exceptions import ToolError
 
     try:
-        await project_client.delete_project(project_id)
+        await project_client.delete_project(project_id, delete_notes=True)
     except ToolError as exc:
         if not _is_default_project_delete_error(exc):
             raise
@@ -127,9 +136,16 @@ async def run_doctor() -> None:
             project_id: str | None = None
 
             try:
-                status = await project_client.create_project(project_request.model_dump())
+                from basic_memory.config import ConfigManager
+
+                status = (
+                    await project_client.create_doctor_project()
+                    if ConfigManager().config.project_root
+                    else await project_client.create_project(project_request.model_dump())
+                )
                 if not status.new_project:
                     raise ValueError("Failed to create doctor project")
+                project_name = status.new_project.name
                 project_id = status.new_project.external_id
                 # Use the resolved path from the server — when project_root is configured,
                 # the actual project directory differs from the requested temp_path

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/mcp/clients/project.py

@@ -78,6 +78,13 @@ class ProjectClient:
         )
         return ProjectStatusResponse.model_validate(response.json())
 
+    async def create_doctor_project(self) -> ProjectStatusResponse:
+        """Create the server-generated disposable project used by doctor."""
+        from basic_memory.mcp.tools.utils import call_post
+
+        response = await call_post(self.http_client, "/v2/projects/doctor")
+        return ProjectStatusResponse.model_validate(response.json())
+
     async def delete_project(
         self, project_external_id: str, delete_notes: bool = False
     ) -> ProjectStatusResponse:

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/repository/search_repository.py

@@ -129,6 +129,10 @@ class SearchRepository(Protocol):
         """Delete item by permalink."""
         ...
 
+    async def delete_project_search_rows(self) -> None:
+        """Delete every full-text search row owned by this project."""
+        ...
+
     async def delete_by_entity_id(self, entity_id: int) -> None:
         """Delete items by entity ID."""
         ...

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/repository/search_repository_base.py

@@ -1143,6 +1143,21 @@ class SearchRepositoryBase(ABC):
             )
             await session.commit()
 
+    async def delete_project_search_rows(self) -> None:
+        """Delete every full-text search row owned by this repository's project.
+
+        Shared across backends: both store rows in `search_index` keyed by
+        project_id, and a project-scoped DELETE leaves sibling projects in the
+        same database untouched. On Postgres the bounded FTS chunk rows follow
+        via their ON DELETE CASCADE foreign key.
+        """
+        async with db.scoped_session(self.session_maker) as session:
+            await session.execute(
+                text("DELETE FROM search_index WHERE project_id = :project_id"),
+                {"project_id": self.project_id},
+            )
+            await session.commit()
+
     async def execute_query(
         self,
         query: Executable,

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/services/project_service.py

@@ -4,6 +4,7 @@ import asyncio
 import json
 import os
 import shutil
+import uuid
 from collections.abc import Callable
 from datetime import datetime
 from pathlib import Path
@@ -190,7 +191,9 @@ class ProjectService:
                 # Not nested in either direction
                 return False
 
-    async def add_project(self, name: str, path: str, set_default: bool = False) -> None:
+    async def add_project(
+        self, name: str, path: str, set_default: bool = False, *, allow_nested: bool = False
+    ) -> None:
         """Add a new project to the configuration and database.
 
         Args:
@@ -240,27 +243,25 @@ class ProjectService:
                             f"In cloud mode, paths are normalized to lowercase to prevent case-sensitivity issues."
                         )  # pragma: no cover
 
-            # Check for nested paths with existing projects
-            for existing in existing_projects:
-                if self._check_nested_paths(resolved_path, existing.path):
-                    # Determine which path is nested within which for appropriate error message
-                    p_new = Path(resolved_path).resolve()
-                    p_existing = Path(existing.path).resolve()
-
-                    # Check if new path is nested under existing project
-                    if p_new.is_relative_to(p_existing):
-                        raise ValueError(
-                            f"Cannot create project at '{resolved_path}': "
-                            f"path is nested within existing project '{existing.name}' at '{existing.path}'. "
-                            f"Projects cannot share directory trees."
-                        )
-                    else:
-                        # Existing project is nested under new path
-                        raise ValueError(
-                            f"Cannot create project at '{resolved_path}': "
-                            f"existing project '{existing.name}' at '{existing.path}' is nested within this path. "
-                            f"Projects cannot share directory trees."
-                        )
+            # Doctor creates a disposable project inside the configured project root.
+            # It must be allowed to coexist with the existing root project.
+            if not allow_nested:
+                for existing in existing_projects:
+                    if self._check_nested_paths(resolved_path, existing.path):
+                        p_new = Path(resolved_path).resolve()
+                        p_existing = Path(existing.path).resolve()
+                        if p_new.is_relative_to(p_existing):
+                            raise ValueError(
+                                f"Cannot create project at '{resolved_path}': "
+                                f"path is nested within existing project '{existing.name}' at '{existing.path}'. "
+                                f"Projects cannot share directory trees."
+                            )
+                        else:
+                            raise ValueError(
+                                f"Cannot create project at '{resolved_path}': "
+                                f"existing project '{existing.name}' at '{existing.path}' is nested within this path. "
+                                f"Projects cannot share directory trees."
+                            )
 
             # Ensure the project directory exists on disk.
             # Trigger: project_root not set means local filesystem mode (not S3/cloud)
@@ -332,6 +333,19 @@ class ProjectService:
 
         logger.info(f"Project '{name}' added at {resolved_path}")
 
+    async def add_doctor_project(self) -> Project:
+        """Create a server-generated disposable project under the configured root."""
+        project_root = self.config_manager.config.project_root
+        if not project_root:
+            raise ValueError("Doctor projects require BASIC_MEMORY_PROJECT_ROOT")
+
+        project_name = f"doctor-{uuid.uuid4().hex[:8]}"
+        await self.add_project(project_name, project_root, allow_nested=True)
+        project = await self.get_project(project_name)
+        if project is None:  # pragma: no cover
+            raise ValueError("Failed to retrieve doctor project")
+        return project
+
     async def remove_project(self, name: str, delete_notes: bool = False) -> None:
         """Remove a project from configuration and database.
 

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/src/basic_memory/services/search_service.py

@@ -11,7 +11,6 @@ from typing import Any, List, Optional, Set, Dict
 from dateparser import parse
 from fastapi import BackgroundTasks
 from loguru import logger
-from sqlalchemy import text
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
 
 import logfire
@@ -152,11 +151,20 @@ class SearchService:
         logger.info("Starting full reindex")
         # Trigger: a full search rebuild removes every derived row.
         # Why: vector storage may live outside SQL, so cleanup must cross the
-        # repository boundary before the full-text table is recreated.
+        # repository boundary before the full-text rows are rebuilt.
         # Outcome: built-in and extension indexes follow the same lifecycle.
         await self.repository.delete_project_vector_rows()
-        await self.repository.execute_query(text("DROP TABLE IF EXISTS search_index"), params={})
+        # Trigger: this service reindexes exactly one project, but search_index
+        # is shared by every project in the database (local SQLite consolidated
+        # into one memory.db; cloud tenants share one Postgres DB across
+        # projects). The historical DROP TABLE here dated from the one-database-
+        # per-project era and destroyed sibling projects' rows — on Postgres it
+        # also left nothing behind, since only migrations recreate the table.
+        # Why: a project-scoped DELETE clears only rows this rebuild will
+        # repopulate, and on Postgres the FTS chunk rows cascade with them.
+        # Outcome: sibling projects keep serving search while this one rebuilds.
         await self.init_search_index()
+        await self.repository.delete_project_search_rows()
 
         # Reindex all entities
         logger.debug("Indexing entities")

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/tests/api/v2/test_project_router.py

@@ -1,5 +1,6 @@
 """Tests for V2 project management API routes (ID-based endpoints)."""
 
+import os
 import tempfile
 from pathlib import Path
 
@@ -629,3 +630,47 @@ async def test_resolve_project_empty_identifier(client: AsyncClient, v2_projects
     response = await client.post(f"{v2_projects_url}/resolve", json=resolve_data)
 
     assert response.status_code == 422  # Validation error
+
+
+@pytest.mark.skipif(os.name == "nt", reason="Project root constraints only tested on POSIX systems")
+@pytest.mark.asyncio
+async def test_add_doctor_project_endpoint(
+    client: AsyncClient,
+    v2_projects_url,
+    monkeypatch,
+    tmp_path,
+):
+    """Regression #1323: the doctor endpoint creates a disposable nested project."""
+    root_path = tmp_path / "app" / "data"
+    root_path.mkdir(parents=True)
+    monkeypatch.setenv("BASIC_MEMORY_PROJECT_ROOT", str(root_path))
+    from basic_memory import config as config_module
+
+    config_module._CONFIG_CACHE = None
+    config_module._CONFIG_MTIME = None
+    config_module._CONFIG_SIZE = None
+    try:
+        response = await client.post(f"{v2_projects_url}/doctor")
+
+        assert response.status_code == 201
+        data = response.json()
+        assert data["status"] == "success"
+        assert data["new_project"]["name"].startswith("doctor-")
+        assert Path(data["new_project"]["path"]).resolve().is_relative_to(root_path.resolve())
+    finally:
+        monkeypatch.delenv("BASIC_MEMORY_PROJECT_ROOT", raising=False)
+        config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
+
+
+@pytest.mark.asyncio
+async def test_add_doctor_project_endpoint_requires_project_root(
+    client: AsyncClient,
+    v2_projects_url,
+):
+    """Without a configured project root the doctor endpoint refuses cleanly."""
+    response = await client.post(f"{v2_projects_url}/doctor")
+
+    assert response.status_code == 400
+    assert "BASIC_MEMORY_PROJECT_ROOT" in response.json()["detail"]

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/tests/cli/test_doctor_command.py

@@ -91,3 +91,20 @@ async def test_doctor_reports_api_note_missing_after_materialization_drain(tmp_p
             tmp_path / "doctor" / "missing.md",
             "doctor/missing.md",
         )
+
+
+@pytest.mark.asyncio
+async def test_doctor_cleanup_deletes_project_notes():
+    """Doctor cleanup removes the disposable project's canonical files."""
+
+    deleted: list[tuple[str, bool]] = []
+
+    class ProjectClient:
+        async def delete_project(
+            self, project_external_id: str, delete_notes: bool = False
+        ) -> None:
+            deleted.append((project_external_id, delete_notes))
+
+    await doctor_cmd._delete_doctor_project(ProjectClient(), "doctor-test", "project-id")
+
+    assert deleted == [("project-id", True)]

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/tests/mcp/clients/test_clients.py

@@ -527,6 +527,36 @@ class TestProjectClient:
         client = ProjectClient(mock_http)
         assert client.http_client is mock_http
 
+    @pytest.mark.asyncio
+    async def test_create_doctor_project(self, monkeypatch):
+        """Test create_doctor_project posts to the doctor endpoint."""
+
+        mock_response = MagicMock()
+        mock_response.json.return_value = {
+            "message": "Project 'doctor-abc12345' added successfully",
+            "status": "success",
+            "default": False,
+            "new_project": {
+                "id": 7,
+                "external_id": "uuid-doctor",
+                "name": "doctor-abc12345",
+                "path": "/app/data/doctor-abc12345",
+                "is_default": False,
+            },
+        }
+
+        async def mock_call_post(client, url, **kwargs):
+            assert url == "/v2/projects/doctor"
+            return mock_response
+
+        monkeypatch.setattr("basic_memory.mcp.tools.utils.call_post", mock_call_post)
+
+        mock_http = MagicMock()
+        client = ProjectClient(mock_http)
+        result = await client.create_doctor_project()
+        assert result.new_project is not None
+        assert result.new_project.name == "doctor-abc12345"
+
     @pytest.mark.asyncio
     async def test_list_projects(self, monkeypatch):
         """Test list_projects calls correct endpoint."""

{basic_memory-0.23.1.dev20 → basic_memory-0.23.1.dev27}/tests/services/test_project_service.py

@@ -1207,6 +1207,32 @@ async def test_add_project_rejects_nested_child_path(project_service: ProjectSer
                 await project_service.remove_project(parent_project_name)
 
 
+@pytest.mark.asyncio
+async def test_add_project_rejects_doctor_prefixed_nested_child_path(
+    project_service: ProjectService,
+):
+    """A user-controlled doctor-prefixed name cannot bypass project isolation."""
+    parent_project_name = f"parent-project-{os.urandom(4).hex()}"
+    doctor_project_name = f"doctor-{os.urandom(4).hex()}"
+    with tempfile.TemporaryDirectory() as temp_dir:
+        parent_path = Path(temp_dir) / "parent"
+        parent_path.mkdir()
+
+        try:
+            await project_service.add_project(parent_project_name, parent_path.as_posix())
+
+            with pytest.raises(ValueError, match="nested within existing project"):
+                await project_service.add_project(
+                    doctor_project_name,
+                    (parent_path / "doctor").as_posix(),
+                )
+        finally:
+            if doctor_project_name in project_service.projects:
+                await project_service.remove_project(doctor_project_name)
+            if parent_project_name in project_service.projects:
+                await project_service.remove_project(parent_project_name)
+
+
 @pytest.mark.asyncio
 async def test_add_project_rejects_parent_path_over_existing_child(project_service: ProjectService):
     """Test that adding a parent project over an existing nested project fails."""
@@ -1696,3 +1722,62 @@ async def test_remove_project_rejects_database_default_in_both_modes(
                 project_service.config_manager.remove_project(test_project_name)
             except Exception:
                 pass
+
+
+@pytest.mark.skipif(os.name == "nt", reason="Project root constraints only tested on POSIX systems")
+@pytest.mark.asyncio
+async def test_add_doctor_project_allows_nested_under_configured_root(
+    project_service: ProjectService, config_manager: ConfigManager, monkeypatch
+):
+    """Regression #1323: doctor can create its disposable project under the root.
+
+    When an existing project owns BASIC_MEMORY_PROJECT_ROOT itself, the normal
+    nesting guard rejects any project beneath it. The server-generated doctor
+    project is the sanctioned exception, and cleanup removes its directory.
+    """
+    with tempfile.TemporaryDirectory() as temp_dir:
+        root_path = Path(temp_dir) / "app" / "data"
+        root_path.mkdir(parents=True, exist_ok=True)
+        owner_name = f"root-owner-{os.urandom(4).hex()}"
+
+        # The owner project claims the root itself, as in the issue's Docker setup
+        # (created before project_root constraints applied to it).
+        await project_service.add_project(owner_name, str(root_path))
+
+        monkeypatch.setenv("BASIC_MEMORY_PROJECT_ROOT", str(root_path))
+        from basic_memory import config as config_module
+
+        config_module._CONFIG_CACHE = None
+        config_module._CONFIG_MTIME = None
+        config_module._CONFIG_SIZE = None
+
+        doctor_name = None
+        try:
+            project = await project_service.add_doctor_project()
+            doctor_name = project.name
+
+            assert doctor_name.startswith("doctor-")
+            doctor_path = Path(project.path).resolve()
+            assert doctor_path.is_relative_to(root_path.resolve())
+            assert doctor_path != root_path.resolve()
+            assert doctor_path.exists()
+
+            await project_service.remove_project(doctor_name, delete_notes=True)
+            doctor_name = None
+            assert not doctor_path.exists()
+        finally:
+            if doctor_name and doctor_name in project_service.projects:
+                await project_service.remove_project(doctor_name, delete_notes=True)
+            monkeypatch.delenv("BASIC_MEMORY_PROJECT_ROOT", raising=False)
+            config_module._CONFIG_CACHE = None
+            config_module._CONFIG_MTIME = None
+            config_module._CONFIG_SIZE = None
+            if owner_name in project_service.projects:
+                await project_service.remove_project(owner_name)
+
+
+@pytest.mark.asyncio
+async def test_add_doctor_project_requires_project_root(project_service: ProjectService):
+    """Without a configured root there is no nesting problem for doctor to solve."""
+    with pytest.raises(ValueError, match="BASIC_MEMORY_PROJECT_ROOT"):
+        await project_service.add_doctor_project()