basic-memory 0.15.0__py3-none-any.whl → 0.15.2__py3-none-any.whl

basic_memory/cli/commands/mcp.py

@@ -20,70 +20,75 @@ from loguru import logger
 import threading
 from basic_memory.services.initialization import initialize_file_sync
 
-
-@app.command()
-def mcp(
-    transport: str = typer.Option("stdio", help="Transport type: stdio, streamable-http, or sse"),
-    host: str = typer.Option(
-        "0.0.0.0", help="Host for HTTP transports (use 0.0.0.0 to allow external connections)"
-    ),
-    port: int = typer.Option(8000, help="Port for HTTP transports"),
-    path: str = typer.Option("/mcp", help="Path prefix for streamable-http transport"),
-    project: Optional[str] = typer.Option(None, help="Restrict MCP server to single project"),
-):  # pragma: no cover
-    """Run the MCP server with configurable transport options.
-
-    This command starts an MCP server using one of three transport options:
-
-    - stdio: Standard I/O (good for local usage)
-    - streamable-http: Recommended for web deployments (default)
-    - sse: Server-Sent Events (for compatibility with existing clients)
-    """
-
-    # Validate and set project constraint if specified
-    if project:
-        config_manager = ConfigManager()
-        project_name, _ = config_manager.get_project(project)
-        if not project_name:
-            typer.echo(f"No project found named: {project}", err=True)
-            raise typer.Exit(1)
-
-        # Set env var with validated project name
-        os.environ["BASIC_MEMORY_MCP_PROJECT"] = project_name
-        logger.info(f"MCP server constrained to project: {project_name}")
-
-    app_config = ConfigManager().config
-
-    def run_file_sync():
-        """Run file sync in a separate thread with its own event loop."""
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
-        try:
-            loop.run_until_complete(initialize_file_sync(app_config))
-        except Exception as e:
-            logger.error(f"File sync error: {e}", err=True)
-        finally:
-            loop.close()
-
-    logger.info(f"Sync changes enabled: {app_config.sync_changes}")
-    if app_config.sync_changes:
-        # Start the sync thread
-        sync_thread = threading.Thread(target=run_file_sync, daemon=True)
-        sync_thread.start()
-        logger.info("Started file sync in background")
-
-    # Now run the MCP server (blocks)
-    logger.info(f"Starting MCP server with {transport.upper()} transport")
-
-    if transport == "stdio":
-        mcp_server.run(
-            transport=transport,
-        )
-    elif transport == "streamable-http" or transport == "sse":
-        mcp_server.run(
-            transport=transport,
-            host=host,
-            port=port,
-            path=path,
-            log_level="INFO",
-        )
+config = ConfigManager().config
+
+if not config.cloud_mode_enabled:
+
+    @app.command()
+    def mcp(
+        transport: str = typer.Option(
+            "stdio", help="Transport type: stdio, streamable-http, or sse"
+        ),
+        host: str = typer.Option(
+            "0.0.0.0", help="Host for HTTP transports (use 0.0.0.0 to allow external connections)"
+        ),
+        port: int = typer.Option(8000, help="Port for HTTP transports"),
+        path: str = typer.Option("/mcp", help="Path prefix for streamable-http transport"),
+        project: Optional[str] = typer.Option(None, help="Restrict MCP server to single project"),
+    ):  # pragma: no cover
+        """Run the MCP server with configurable transport options.
+
+        This command starts an MCP server using one of three transport options:
+
+        - stdio: Standard I/O (good for local usage)
+        - streamable-http: Recommended for web deployments (default)
+        - sse: Server-Sent Events (for compatibility with existing clients)
+        """
+
+        # Validate and set project constraint if specified
+        if project:
+            config_manager = ConfigManager()
+            project_name, _ = config_manager.get_project(project)
+            if not project_name:
+                typer.echo(f"No project found named: {project}", err=True)
+                raise typer.Exit(1)
+
+            # Set env var with validated project name
+            os.environ["BASIC_MEMORY_MCP_PROJECT"] = project_name
+            logger.info(f"MCP server constrained to project: {project_name}")
+
+        app_config = ConfigManager().config
+
+        def run_file_sync():
+            """Run file sync in a separate thread with its own event loop."""
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            try:
+                loop.run_until_complete(initialize_file_sync(app_config))
+            except Exception as e:
+                logger.error(f"File sync error: {e}", err=True)
+            finally:
+                loop.close()
+
+        logger.info(f"Sync changes enabled: {app_config.sync_changes}")
+        if app_config.sync_changes:
+            # Start the sync thread
+            sync_thread = threading.Thread(target=run_file_sync, daemon=True)
+            sync_thread.start()
+            logger.info("Started file sync in background")
+
+        # Now run the MCP server (blocks)
+        logger.info(f"Starting MCP server with {transport.upper()} transport")
+
+        if transport == "stdio":
+            mcp_server.run(
+                transport=transport,
+            )
+        elif transport == "streamable-http" or transport == "sse":
+            mcp_server.run(
+                transport=transport,
+                host=host,
+                port=port,
+                path=path,
+                log_level="INFO",
+            )

basic_memory/cli/commands/project.py

@@ -9,14 +9,13 @@ from rich.console import Console
 from rich.table import Table
 
 from basic_memory.cli.app import app
-from basic_memory.cli.commands.cloud import get_authenticated_headers
 from basic_memory.cli.commands.command_utils import get_project_info
 from basic_memory.config import ConfigManager
 import json
 from datetime import datetime
 
 from rich.panel import Panel
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.tools.utils import call_get
 from basic_memory.schemas.project_info import ProjectList
 from basic_memory.mcp.tools.utils import call_post
@@ -32,8 +31,6 @@ console = Console()
 project_app = typer.Typer(help="Manage multiple Basic Memory projects")
 app.add_typer(project_app, name="project")
 
-config = ConfigManager().config
-
 
 def format_path(path: str) -> str:
     """Format a path for display, using ~ for home directory."""
@@ -46,14 +43,14 @@ def format_path(path: str) -> str:
 @project_app.command("list")
 def list_projects() -> None:
     """List all Basic Memory projects."""
-    # Use API to list projects
-    try:
-        auth_headers = {}
-        if config.cloud_mode_enabled:
-            auth_headers = asyncio.run(get_authenticated_headers())
 
-        response = asyncio.run(call_get(client, "/projects/projects", headers=auth_headers))
-        result = ProjectList.model_validate(response.json())
+    async def _list_projects():
+        async with get_client() as client:
+            response = await call_get(client, "/projects/projects")
+            return ProjectList.model_validate(response.json())
+
+    try:
+        result = asyncio.run(_list_projects())
 
         table = Table(title="Basic Memory Projects")
         table.add_column("Name", style="cyan")
@@ -70,59 +67,53 @@ def list_projects() -> None:
         raise typer.Exit(1)
 
 
-if config.cloud_mode_enabled:
-
-    @project_app.command("add")
-    def add_project_cloud(
-        name: str = typer.Argument(..., help="Name of the project"),
-        set_default: bool = typer.Option(False, "--default", help="Set as default project"),
-    ) -> None:
-        """Add a new project to Basic Memory Cloud"""
-
-        try:
-            auth_headers = asyncio.run(get_authenticated_headers())
-
-            data = {"name": name, "path": generate_permalink(name), "set_default": set_default}
-
-            response = asyncio.run(
-                call_post(client, "/projects/projects", json=data, headers=auth_headers)
-            )
-            result = ProjectStatusResponse.model_validate(response.json())
-
-            console.print(f"[green]{result.message}[/green]")
-        except Exception as e:
-            console.print(f"[red]Error adding project: {str(e)}[/red]")
+@project_app.command("add")
+def add_project(
+    name: str = typer.Argument(..., help="Name of the project"),
+    path: str = typer.Argument(
+        None, help="Path to the project directory (required for local mode)"
+    ),
+    set_default: bool = typer.Option(False, "--default", help="Set as default project"),
+) -> None:
+    """Add a new project.
+
+    For cloud mode: only name is required
+    For local mode: both name and path are required
+    """
+    config = ConfigManager().config
+
+    if config.cloud_mode_enabled:
+        # Cloud mode: path not needed (auto-generated from name)
+        async def _add_project():
+            async with get_client() as client:
+                data = {"name": name, "path": generate_permalink(name), "set_default": set_default}
+                response = await call_post(client, "/projects/projects", json=data)
+                return ProjectStatusResponse.model_validate(response.json())
+    else:
+        # Local mode: path is required
+        if path is None:
+            console.print("[red]Error: path argument is required in local mode[/red]")
             raise typer.Exit(1)
 
-        # Display usage hint
-        console.print("\nTo use this project:")
-        console.print(f"  basic-memory --project={name} <command>")
-else:
-
-    @project_app.command("add")
-    def add_project(
-        name: str = typer.Argument(..., help="Name of the project"),
-        path: str = typer.Argument(..., help="Path to the project directory"),
-        set_default: bool = typer.Option(False, "--default", help="Set as default project"),
-    ) -> None:
-        """Add a new project."""
         # Resolve to absolute path
         resolved_path = Path(os.path.abspath(os.path.expanduser(path))).as_posix()
 
-        try:
-            data = {"name": name, "path": resolved_path, "set_default": set_default}
+        async def _add_project():
+            async with get_client() as client:
+                data = {"name": name, "path": resolved_path, "set_default": set_default}
+                response = await call_post(client, "/projects/projects", json=data)
+                return ProjectStatusResponse.model_validate(response.json())
 
-            response = asyncio.run(call_post(client, "/projects/projects", json=data))
-            result = ProjectStatusResponse.model_validate(response.json())
-
-            console.print(f"[green]{result.message}[/green]")
-        except Exception as e:
-            console.print(f"[red]Error adding project: {str(e)}[/red]")
-            raise typer.Exit(1)
+    try:
+        result = asyncio.run(_add_project())
+        console.print(f"[green]{result.message}[/green]")
+    except Exception as e:
+        console.print(f"[red]Error adding project: {str(e)}[/red]")
+        raise typer.Exit(1)
 
-        # Display usage hint
-        console.print("\nTo use this project:")
-        console.print(f"  basic-memory --project={name} <command>")
+    # Display usage hint
+    console.print("\nTo use this project:")
+    console.print(f"  basic-memory --project={name} <command>")
 
 
 @project_app.command("remove")
@@ -130,17 +121,15 @@ def remove_project(
     name: str = typer.Argument(..., help="Name of the project to remove"),
 ) -> None:
     """Remove a project."""
-    try:
-        auth_headers = {}
-        if config.cloud_mode_enabled:
-            auth_headers = asyncio.run(get_authenticated_headers())
 
-        project_permalink = generate_permalink(name)
-        response = asyncio.run(
-            call_delete(client, f"/projects/{project_permalink}", headers=auth_headers)
-        )
-        result = ProjectStatusResponse.model_validate(response.json())
+    async def _remove_project():
+        async with get_client() as client:
+            project_permalink = generate_permalink(name)
+            response = await call_delete(client, f"/projects/{project_permalink}")
+            return ProjectStatusResponse.model_validate(response.json())
 
+    try:
+        result = asyncio.run(_remove_project())
         console.print(f"[green]{result.message}[/green]")
     except Exception as e:
         console.print(f"[red]Error removing project: {str(e)}[/red]")
@@ -150,76 +139,107 @@ def remove_project(
     console.print("[yellow]Note: The project files have not been deleted from disk.[/yellow]")
 
 
-if not config.cloud_mode_enabled:
+@project_app.command("default")
+def set_default_project(
+    name: str = typer.Argument(..., help="Name of the project to set as CLI default"),
+) -> None:
+    """Set the default project when 'config.default_project_mode' is set.
 
-    @project_app.command("default")
-    def set_default_project(
-        name: str = typer.Argument(..., help="Name of the project to set as CLI default"),
-    ) -> None:
-        """Set the default project when 'config.default_project_mode' is set."""
-        try:
+    Note: This command is only available in local mode.
+    """
+    config = ConfigManager().config
+
+    if config.cloud_mode_enabled:
+        console.print("[red]Error: 'default' command is not available in cloud mode[/red]")
+        raise typer.Exit(1)
+
+    async def _set_default():
+        async with get_client() as client:
             project_permalink = generate_permalink(name)
-            response = asyncio.run(call_put(client, f"/projects/{project_permalink}/default"))
-            result = ProjectStatusResponse.model_validate(response.json())
+            response = await call_put(client, f"/projects/{project_permalink}/default")
+            return ProjectStatusResponse.model_validate(response.json())
 
-            console.print(f"[green]{result.message}[/green]")
-        except Exception as e:
-            console.print(f"[red]Error setting default project: {str(e)}[/red]")
-            raise typer.Exit(1)
+    try:
+        result = asyncio.run(_set_default())
+        console.print(f"[green]{result.message}[/green]")
+    except Exception as e:
+        console.print(f"[red]Error setting default project: {str(e)}[/red]")
+        raise typer.Exit(1)
 
-    @project_app.command("sync-config")
-    def synchronize_projects() -> None:
-        """Synchronize project config between configuration file and database."""
-        # Call the API to synchronize projects
 
-        try:
-            response = asyncio.run(call_post(client, "/projects/config/sync"))
-            result = ProjectStatusResponse.model_validate(response.json())
+@project_app.command("sync-config")
+def synchronize_projects() -> None:
+    """Synchronize project config between configuration file and database.
 
-            console.print(f"[green]{result.message}[/green]")
-        except Exception as e:  # pragma: no cover
-            console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
-            raise typer.Exit(1)
+    Note: This command is only available in local mode.
+    """
+    config = ConfigManager().config
 
-    @project_app.command("move")
-    def move_project(
-        name: str = typer.Argument(..., help="Name of the project to move"),
-        new_path: str = typer.Argument(..., help="New absolute path for the project"),
-    ) -> None:
-        """Move a project to a new location."""
-        # Resolve to absolute path
-        resolved_path = Path(os.path.abspath(os.path.expanduser(new_path))).as_posix()
+    if config.cloud_mode_enabled:
+        console.print("[red]Error: 'sync-config' command is not available in cloud mode[/red]")
+        raise typer.Exit(1)
 
-        try:
-            data = {"path": resolved_path}
+    async def _sync_config():
+        async with get_client() as client:
+            response = await call_post(client, "/projects/config/sync")
+            return ProjectStatusResponse.model_validate(response.json())
 
+    try:
+        result = asyncio.run(_sync_config())
+        console.print(f"[green]{result.message}[/green]")
+    except Exception as e:  # pragma: no cover
+        console.print(f"[red]Error synchronizing projects: {str(e)}[/red]")
+        raise typer.Exit(1)
+
+
+@project_app.command("move")
+def move_project(
+    name: str = typer.Argument(..., help="Name of the project to move"),
+    new_path: str = typer.Argument(..., help="New absolute path for the project"),
+) -> None:
+    """Move a project to a new location.
+
+    Note: This command is only available in local mode.
+    """
+    config = ConfigManager().config
+
+    if config.cloud_mode_enabled:
+        console.print("[red]Error: 'move' command is not available in cloud mode[/red]")
+        raise typer.Exit(1)
+
+    # Resolve to absolute path
+    resolved_path = Path(os.path.abspath(os.path.expanduser(new_path))).as_posix()
+
+    async def _move_project():
+        async with get_client() as client:
+            data = {"path": resolved_path}
             project_permalink = generate_permalink(name)
 
             # TODO fix route to use ProjectPathDep
-            response = asyncio.run(
-                call_patch(client, f"/{name}/project/{project_permalink}", json=data)
-            )
-            result = ProjectStatusResponse.model_validate(response.json())
+            response = await call_patch(client, f"/{name}/project/{project_permalink}", json=data)
+            return ProjectStatusResponse.model_validate(response.json())
 
-            console.print(f"[green]{result.message}[/green]")
+    try:
+        result = asyncio.run(_move_project())
+        console.print(f"[green]{result.message}[/green]")
 
-            # Show important file movement reminder
-            console.print()  # Empty line for spacing
-            console.print(
-                Panel(
-                    "[bold red]IMPORTANT:[/bold red] Project configuration updated successfully.\n\n"
-                    "[yellow]You must manually move your project files from the old location to:[/yellow]\n"
-                    f"[cyan]{resolved_path}[/cyan]\n\n"
-                    "[dim]Basic Memory has only updated the configuration - your files remain in their original location.[/dim]",
-                    title="⚠️  Manual File Movement Required",
-                    border_style="yellow",
-                    expand=False,
-                )
+        # Show important file movement reminder
+        console.print()  # Empty line for spacing
+        console.print(
+            Panel(
+                "[bold red]IMPORTANT:[/bold red] Project configuration updated successfully.\n\n"
+                "[yellow]You must manually move your project files from the old location to:[/yellow]\n"
+                f"[cyan]{resolved_path}[/cyan]\n\n"
+                "[dim]Basic Memory has only updated the configuration - your files remain in their original location.[/dim]",
+                title="⚠️  Manual File Movement Required",
+                border_style="yellow",
+                expand=False,
             )
+        )
 
-        except Exception as e:
-            console.print(f"[red]Error moving project: {str(e)}[/red]")
-            raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error moving project: {str(e)}[/red]")
+        raise typer.Exit(1)
 
 
 @project_app.command("info")

basic_memory/cli/commands/status.py

@@ -12,8 +12,7 @@ from rich.panel import Panel
 from rich.tree import Tree
 
 from basic_memory.cli.app import app
-from basic_memory.cli.commands.cloud import get_authenticated_headers
-from basic_memory.mcp.async_client import client
+from basic_memory.mcp.async_client import get_client
 from basic_memory.mcp.tools.utils import call_post
 from basic_memory.schemas import SyncReportResponse
 from basic_memory.mcp.project_context import get_active_project
@@ -130,20 +129,12 @@ async def run_status(project: Optional[str] = None, verbose: bool = False):  # p
     """Check sync status of files vs database."""
 
     try:
-        from basic_memory.config import ConfigManager
+        async with get_client() as client:
+            project_item = await get_active_project(client, project, None)
+            response = await call_post(client, f"{project_item.project_url}/project/status")
+            sync_report = SyncReportResponse.model_validate(response.json())
 
-        config = ConfigManager().config
-        auth_headers = {}
-        if config.cloud_mode_enabled:
-            auth_headers = await get_authenticated_headers()
-
-        project_item = await get_active_project(client, project, None)
-        response = await call_post(
-            client, f"{project_item.project_url}/project/status", headers=auth_headers
-        )
-        sync_report = SyncReportResponse.model_validate(response.json())
-
-        display_changes(project_item.name, "Status", sync_report, verbose)
+            display_changes(project_item.name, "Status", sync_report, verbose)
 
     except (ValueError, ToolError) as e:
         console.print(f"[red]✗ Error: {e}[/red]")

basic_memory/config.py

@@ -103,10 +103,10 @@ class BasicMemoryConfig(BaseSettings):
         description="Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.",
     )
 
-    # API connection configuration
-    api_url: Optional[str] = Field(
+    # Project path constraints
+    project_root: Optional[str] = Field(
         default=None,
-        description="URL of remote Basic Memory API. If set, MCP will connect to this API instead of using local ASGI transport.",
+        description="If set, all projects must be created underneath this directory. Paths will be sanitized and constrained to this root. If not set, projects can be created anywhere (default behavior).",
     )
 
     # Cloud configuration
@@ -232,6 +232,10 @@ class BasicMemoryConfig(BaseSettings):
         return Path.home() / DATA_DIR_NAME
 
 
+# Module-level cache for configuration
+_CONFIG_CACHE: Optional[BasicMemoryConfig] = None
+
+
 class ConfigManager:
     """Manages Basic Memory configuration."""
 
@@ -241,7 +245,12 @@ class ConfigManager:
         if isinstance(home, str):
             home = Path(home)
 
-        self.config_dir = home / DATA_DIR_NAME
+        # Allow override via environment variable
+        if config_dir := os.getenv("BASIC_MEMORY_CONFIG_DIR"):
+            self.config_dir = Path(config_dir)
+        else:
+            self.config_dir = home / DATA_DIR_NAME
+
         self.config_file = self.config_dir / CONFIG_FILE_NAME
 
         # Ensure config directory exists
@@ -253,12 +262,45 @@ class ConfigManager:
         return self.load_config()
 
     def load_config(self) -> BasicMemoryConfig:
-        """Load configuration from file or create default."""
+        """Load configuration from file or create default.
+
+        Environment variables take precedence over file config values,
+        following Pydantic Settings best practices.
+
+        Uses module-level cache for performance across ConfigManager instances.
+        """
+        global _CONFIG_CACHE
+
+        # Return cached config if available
+        if _CONFIG_CACHE is not None:
+            return _CONFIG_CACHE
 
         if self.config_file.exists():
             try:
-                data = json.loads(self.config_file.read_text(encoding="utf-8"))
-                return BasicMemoryConfig(**data)
+                file_data = json.loads(self.config_file.read_text(encoding="utf-8"))
+
+                # First, create config from environment variables (Pydantic will read them)
+                # Then overlay with file data for fields that aren't set via env vars
+                # This ensures env vars take precedence
+
+                # Get env-based config fields that are actually set
+                env_config = BasicMemoryConfig()
+                env_dict = env_config.model_dump()
+
+                # Merge: file data as base, but only use it for fields not set by env
+                # We detect env-set fields by comparing to default values
+                merged_data = file_data.copy()
+
+                # For fields that have env var overrides, use those instead of file values
+                # The env_prefix is "BASIC_MEMORY_" so we check those
+                for field_name in BasicMemoryConfig.model_fields.keys():
+                    env_var_name = f"BASIC_MEMORY_{field_name.upper()}"
+                    if env_var_name in os.environ:
+                        # Environment variable is set, use it
+                        merged_data[field_name] = env_dict[field_name]
+
+                _CONFIG_CACHE = BasicMemoryConfig(**merged_data)
+                return _CONFIG_CACHE
             except Exception as e:  # pragma: no cover
                 logger.exception(f"Failed to load config: {e}")
                 raise e
@@ -268,8 +310,11 @@ class ConfigManager:
             return config
 
     def save_config(self, config: BasicMemoryConfig) -> None:
-        """Save configuration to file."""
+        """Save configuration to file and invalidate cache."""
+        global _CONFIG_CACHE
         save_basic_memory_config(self.config_file, config)
+        # Invalidate cache so next load_config() reads fresh data
+        _CONFIG_CACHE = None
 
     @property
     def projects(self) -> Dict[str, str]:
@@ -309,7 +354,8 @@ class ConfigManager:
         if project_name == config.default_project:  # pragma: no cover
             raise ValueError(f"Cannot remove the default project '{name}'")
 
-        del config.projects[name]
+        # Use the found project_name (which may differ from input name due to permalink matching)
+        del config.projects[project_name]
         self.save_config(config)
 
     def set_default_project(self, name: str) -> None: