fix: prevent CLI commands from hanging on exit (Python 3.14) (#505)

Signed-off-by: phernandez <[email protected]>
Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: phernandez

.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: [ "3.12", "3.13" ]
+        python-version: [ "3.12", "3.13", "3.14" ]
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -75,7 +75,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.12", "3.13" ]
+        python-version: [ "3.12", "3.13", "3.14" ]
     runs-on: ubuntu-latest
 
     # Note: No services section needed - testcontainers handles Postgres in Docker
@@ -164,4 +164,4 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: htmlcov
-          path: htmlcov/
+          path: htmlcov/

.python-version

@@ -1 +1 @@
-3.12
+3.14

pyproject.toml

@@ -14,7 +14,7 @@ dependencies = [
     "typer>=0.9.0",
     "aiosqlite>=0.20.0",
     "greenlet>=3.1.1",
-    "pydantic[email,timezone]>=2.10.3",
+    "pydantic[email,timezone]>=2.12.0",
     "mcp>=1.23.1",
     "pydantic-settings>=2.6.1",
     "loguru>=0.7.3",
@@ -29,7 +29,7 @@ dependencies = [
     "alembic>=1.14.1",
     "pillow>=11.1.0",
     "pybars3>=0.9.7",
-    "fastmcp==2.12.3",  # Pinned - 2.14.x breaks MCP tools visibility (issue #463)
+    "fastmcp==2.12.3", # Pinned - 2.14.x breaks MCP tools visibility (issue #463)
     "pyjwt>=2.10.1",
     "python-dotenv>=1.1.0",
     "pytest-aio>=1.9.0",
@@ -41,7 +41,10 @@ dependencies = [
     "mdformat>=0.7.22",
     "mdformat-gfm>=0.3.7",
     "mdformat-frontmatter>=2.0.8",
-    "openpanel>=0.0.1",  # Anonymous usage telemetry (Homebrew-style opt-out)
+    "openpanel>=0.0.1", # Anonymous usage telemetry (Homebrew-style opt-out)
+    "sniffio>=1.3.1",
+    "anyio>=4.10.0",
+    "httpx>=0.28.0",
 ]
 
 
@@ -88,6 +91,7 @@ dev = [
     "freezegun>=1.5.5",
     "testcontainers[postgres]>=4.0.0",
     "psycopg>=3.2.0",
+    "pyright>=1.1.408",
 ]
 
 [tool.hatch.version]

src/basic_memory/alembic/env.py

@@ -5,14 +5,18 @@
 from logging.config import fileConfig
 
 # Allow nested event loops (needed for pytest-asyncio and other async contexts)
-# Note: nest_asyncio doesn't work with uvloop, so we handle that case separately
-try:
-    import nest_asyncio
-
-    nest_asyncio.apply()
-except (ImportError, ValueError):
-    # nest_asyncio not available or can't patch this loop type (e.g., uvloop)
-    pass
+# Note: nest_asyncio doesn't work with uvloop or Python 3.14+, so we handle those cases separately
+import sys
+
+if sys.version_info < (3, 14):
+    try:
+        import nest_asyncio
+
+        nest_asyncio.apply()
+    except (ImportError, ValueError):
+        # nest_asyncio not available or can't patch this loop type (e.g., uvloop)
+        pass
+# For Python 3.14+, we rely on the thread-based fallback in run_migrations_online()
 
 from sqlalchemy import engine_from_config, pool
 from sqlalchemy.ext.asyncio import AsyncEngine, create_async_engine

src/basic_memory/alembic/versions/6830751f5fb6_merge_multiple_heads.py

@@ -5,13 +5,13 @@
 Create Date: 2025-12-29 12:46:46.476268
 
 """
-from typing import Sequence, Union
 
+from typing import Sequence, Union
 
 
 # revision identifiers, used by Alembic.
-revision: str = '6830751f5fb6'
-down_revision: Union[str, Sequence[str], None] = ('a2b3c4d5e6f7', 'g9a0b3c4d5e6')
+revision: str = "6830751f5fb6"
+down_revision: Union[str, Sequence[str], None] = ("a2b3c4d5e6f7", "g9a0b3c4d5e6")
 branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 

src/basic_memory/api/v2/routers/knowledge_router.py

@@ -414,9 +414,7 @@ async def move_entity(
 
         result = EntityResponseV2.model_validate(moved_entity)
 
-        logger.info(
-            f"API v2 response: moved external_id={entity_id} to '{data.destination_path}'"
-        )
+        logger.info(f"API v2 response: moved external_id={entity_id} to '{data.destination_path}'")
 
         return result
 

src/basic_memory/api/v2/routers/project_router.py

@@ -264,9 +264,7 @@ async def delete_project_by_id(
         # Use is_default from database, not ConfigManager (which doesn't work in cloud mode)
         if old_project.is_default:
             available_projects = await project_service.list_projects()
-            other_projects = [
-                p.name for p in available_projects if p.external_id != project_id
-            ]
+            other_projects = [p.name for p in available_projects if p.external_id != project_id]
             detail = f"Cannot delete default project '{old_project.name}'. "
             if other_projects:
                 detail += (  # pragma: no cover

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

@@ -1,11 +1,10 @@
 """Core cloud commands for Basic Memory CLI."""
 
-import asyncio
-
 import typer
 from rich.console import Console
 
 from basic_memory.cli.app import cloud_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.auth import CLIAuth
 from basic_memory.config import ConfigManager
 from basic_memory.cli.commands.cloud.api_client import (
@@ -64,7 +63,7 @@ async def _login():
             )
             raise typer.Exit(1)
 
-    asyncio.run(_login())
+    run_with_cleanup(_login())
 
 
 @cloud_app.command()
@@ -110,7 +109,7 @@ def status() -> None:
         console.print("\n[blue]Checking cloud instance health...[/blue]")
 
         # Make API request to check health
-        response = asyncio.run(
+        response = run_with_cleanup(
             make_api_request(method="GET", url=f"{host_url}/proxy/health", headers=headers)
         )
 
@@ -156,12 +155,12 @@ def setup() -> None:
 
         # Step 2: Get tenant info
         console.print("\n[blue]Step 2: Getting tenant information...[/blue]")
-        tenant_info = asyncio.run(get_mount_info())
+        tenant_info = run_with_cleanup(get_mount_info())
         console.print(f"[green]Found tenant: {tenant_info.tenant_id}[/green]")
 
         # Step 3: Generate credentials
         console.print("\n[blue]Step 3: Generating sync credentials...[/blue]")
-        creds = asyncio.run(generate_mount_credentials(tenant_info.tenant_id))
+        creds = run_with_cleanup(generate_mount_credentials(tenant_info.tenant_id))
         console.print("[green]Generated secure credentials[/green]")
 
         # Step 4: Configure rclone remote

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

@@ -27,6 +27,7 @@
 # Minimum rclone version for --create-empty-src-dirs support
 MIN_RCLONE_VERSION_EMPTY_DIRS = (1, 64, 0)
 
+
 class RunResult(Protocol):
     returncode: int
     stdout: str

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

@@ -1,12 +1,12 @@
 """Upload CLI commands for basic-memory projects."""
 
-import asyncio
 from pathlib import Path
 
 import typer
 from rich.console import Console
 
 from basic_memory.cli.app import cloud_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.cli.commands.cloud.cloud_utils import (
     create_cloud_project,
     project_exists,
@@ -121,4 +121,4 @@ async def _upload():
                 console.print(f"[yellow]Warning: Sync failed: {e}[/yellow]")
                 console.print("[dim]Files uploaded but may not be indexed yet[/dim]")
 
-    asyncio.run(_upload())
+    run_with_cleanup(_upload())