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

CLI commands were using asyncio.run() directly instead of run_with_cleanup(),
which meant db.shutdown_db() was never called. This left SQLite/SQLAlchemy
connection threads running after commands completed. On Python 3.14, this
caused the process to hang during _thread._shutdown().

Changes:
- Update all CLI commands to use run_with_cleanup() for proper db cleanup
- Update pydantic requirement to >=2.12.0 for Python 3.14 support
- Add Python 3.14 to SQLite test matrix in CI

Fixes #504

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Signed-off-by: phernandez <paul@basicmachines.co>

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/

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",

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

@@ -6,6 +6,7 @@
 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 +65,7 @@ async def _login():
             )
             raise typer.Exit(1)
 
-    asyncio.run(_login())
+    run_with_cleanup(_login())
 
 
 @cloud_app.command()
@@ -110,7 +111,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 +157,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/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())

src/basic_memory/cli/commands/db.py

@@ -10,6 +10,7 @@
 
 from basic_memory import db
 from basic_memory.cli.app import app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager
 from basic_memory.repository import ProjectRepository
 from basic_memory.services.initialization import reconcile_projects_with_config
@@ -81,7 +82,7 @@ def reset(
 
         # Create a new empty database (preserves project configuration)
         try:
-            asyncio.run(db.run_migrations(app_config))
+            run_with_cleanup(db.run_migrations(app_config))
         except OperationalError as e:
             if "disk I/O error" in str(e) or "database is locked" in str(e):
                 console.print(
@@ -99,5 +100,7 @@ def reset(
                 console.print("[yellow]No projects configured. Skipping reindex.[/yellow]")
             else:
                 console.print(f"Rebuilding search index for {len(projects)} project(s)...")
-                asyncio.run(_reindex_projects(app_config))
+                # Note: _reindex_projects has its own cleanup, but run_with_cleanup
+                # ensures db.shutdown_db() is called even if _reindex_projects changes
+                run_with_cleanup(_reindex_projects(app_config))
                 console.print("[green]Reindex complete[/green]")

src/basic_memory/cli/commands/format.py

@@ -1,6 +1,5 @@
 """Format command for basic-memory CLI."""
 
-import asyncio
 from pathlib import Path
 from typing import Annotated, Optional
 
@@ -10,6 +9,7 @@
 from rich.progress import Progress, SpinnerColumn, TextColumn
 
 from basic_memory.cli.app import app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.file_utils import format_file
 
@@ -189,7 +189,7 @@ def format(
         basic-memory format notes/             # Format all files in directory
     """
     try:
-        asyncio.run(run_format(path, project))
+        run_with_cleanup(run_format(path, project))
     except Exception as e:
         if not isinstance(e, typer.Exit):
             logger.error(f"Error formatting files: {e}")

src/basic_memory/cli/commands/import_chatgpt.py

@@ -1,12 +1,12 @@
 """Import command for ChatGPT conversations."""
 
-import asyncio
 import json
 from pathlib import Path
 from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import import_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers import ChatGPTImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
@@ -53,7 +53,7 @@ def import_chatgpt(
             raise typer.Exit(1)
 
         # Get importer dependencies
-        markdown_processor, file_service = asyncio.run(get_importer_dependencies())
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
         config = get_project_config()
         # Process the file
         base_path = config.home / folder
@@ -63,7 +63,7 @@ def import_chatgpt(
         importer = ChatGPTImporter(config.home, markdown_processor, file_service)
         with conversations_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
-            result = asyncio.run(importer.import_data(json_data, folder))
+            result = run_with_cleanup(importer.import_data(json_data, folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -1,12 +1,12 @@
 """Import command for basic-memory CLI to import chat data from conversations2.json format."""
 
-import asyncio
 import json
 from pathlib import Path
 from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import claude_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers.claude_conversations_importer import ClaudeConversationsImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
@@ -54,7 +54,7 @@ def import_claude(
             raise typer.Exit(1)
 
         # Get importer dependencies
-        markdown_processor, file_service = asyncio.run(get_importer_dependencies())
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
         importer = ClaudeConversationsImporter(config.home, markdown_processor, file_service)
@@ -66,7 +66,7 @@ def import_claude(
         # Run the import
         with conversations_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
-            result = asyncio.run(importer.import_data(json_data, folder))
+            result = run_with_cleanup(importer.import_data(json_data, folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)

src/basic_memory/cli/commands/import_claude_projects.py

@@ -1,12 +1,12 @@
 """Import command for basic-memory CLI to import project data from Claude.ai."""
 
-import asyncio
 import json
 from pathlib import Path
 from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import claude_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers.claude_projects_importer import ClaudeProjectsImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
@@ -53,7 +53,7 @@ def import_projects(
             raise typer.Exit(1)
 
         # Get importer dependencies
-        markdown_processor, file_service = asyncio.run(get_importer_dependencies())
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
         importer = ClaudeProjectsImporter(config.home, markdown_processor, file_service)
@@ -65,7 +65,7 @@ def import_projects(
         # Run the import
         with projects_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
-            result = asyncio.run(importer.import_data(json_data, base_folder))
+            result = run_with_cleanup(importer.import_data(json_data, base_folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)

src/basic_memory/cli/commands/import_memory_json.py

@@ -1,12 +1,12 @@
 """Import command for basic-memory CLI to import from JSON memory format."""
 
-import asyncio
 import json
 from pathlib import Path
 from typing import Annotated, Tuple
 
 import typer
 from basic_memory.cli.app import import_app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
 from basic_memory.config import ConfigManager, get_project_config
 from basic_memory.importers.memory_json_importer import MemoryJsonImporter
 from basic_memory.markdown import EntityParser, MarkdownProcessor
@@ -52,7 +52,7 @@ def memory_json(
     config = get_project_config()
     try:
         # Get importer dependencies
-        markdown_processor, file_service = asyncio.run(get_importer_dependencies())
+        markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
         importer = MemoryJsonImporter(config.home, markdown_processor, file_service)
@@ -67,7 +67,7 @@ def memory_json(
             for line in file:
                 json_data = json.loads(line)
                 file_data.append(json_data)
-        result = asyncio.run(importer.import_data(file_data, destination_folder))
+        result = run_with_cleanup(importer.import_data(file_data, destination_folder))
 
         if not result.success:  # pragma: no cover
             typer.echo(f"Error during import: {result.error_message}", err=True)