Merge remote-tracking branch 'origin/main' into fix/optional-semantic-dependencies

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

# Conflicts:
#	src/basic_memory/repository/openai_provider.py
#	src/basic_memory/repository/sqlite_search_repository.py

Author: phernandez

src/basic_memory/cli/app.py

@@ -50,7 +50,17 @@ def app_callback(
     # Skip for 'mcp' command - it has its own lifespan that handles initialization
     # Skip for API-using commands (status, sync, etc.) - they handle initialization via deps.py
     # Skip for 'reset' command - it manages its own database lifecycle
-    skip_init_commands = {"doctor", "mcp", "status", "sync", "project", "tool", "reset", "reindex"}
+    skip_init_commands = {
+        "doctor",
+        "mcp",
+        "status",
+        "sync",
+        "project",
+        "tool",
+        "reset",
+        "reindex",
+        "watch",
+    }
     if (
         not version
         and ctx.invoked_subcommand is not None

src/basic_memory/cli/commands/__init__.py

@@ -1,7 +1,7 @@
 """CLI commands for basic-memory."""
 
 from . import status, db, doctor, import_memory_json, mcp, import_claude_conversations
-from . import import_claude_projects, import_chatgpt, tool, project, format, schema
+from . import import_claude_projects, import_chatgpt, tool, project, format, schema, watch
 
 __all__ = [
     "status",
@@ -16,4 +16,5 @@
     "project",
     "format",
     "schema",
+    "watch",
 ]

src/basic_memory/cli/commands/watch.py

@@ -0,0 +1,97 @@
+"""Watch command - run file watcher as a standalone long-running process."""
+
+import asyncio
+import os
+import signal
+import sys
+from typing import Optional
+
+import typer
+from loguru import logger
+
+from basic_memory import db
+from basic_memory.cli.app import app
+from basic_memory.cli.container import get_container
+from basic_memory.config import ConfigManager
+from basic_memory.services.initialization import initialize_app
+from basic_memory.sync.coordinator import SyncCoordinator
+
+
+async def run_watch(project: Optional[str] = None) -> None:
+    """Run the file watcher as a long-running process.
+
+    This is the async core of the watch command. It:
+    1. Initializes the app (DB migrations + project reconciliation)
+    2. Validates and sets project constraint if --project given
+    3. Creates a SyncCoordinator with quiet=False for Rich console output
+    4. Blocks until SIGINT/SIGTERM, then shuts down cleanly
+    """
+    container = get_container()
+    config = container.config
+
+    # --- Initialization ---
+    # Wrapped in try/finally so DB resources are cleaned up on all exit paths,
+    # including early exits from invalid --project names.
+    await initialize_app(config)
+    sync_coordinator = None
+
+    try:
+        # --- Project constraint ---
+        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)
+
+            os.environ["BASIC_MEMORY_MCP_PROJECT"] = project_name
+            logger.info(f"Watch constrained to project: {project_name}")
+
+        # --- Sync coordinator ---
+        # quiet=False so file change events are printed to the terminal
+        sync_coordinator = SyncCoordinator(config=config, should_sync=True, quiet=False)
+
+        # --- Signal handling ---
+        shutdown_event = asyncio.Event()
+
+        def _signal_handler() -> None:
+            logger.info("Shutdown signal received")
+            shutdown_event.set()
+
+        loop = asyncio.get_running_loop()
+
+        # Windows ProactorEventLoop does not support add_signal_handler;
+        # fall back to the stdlib signal module which works cross-platform.
+        try:
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                loop.add_signal_handler(sig, _signal_handler)
+        except NotImplementedError:
+            for sig in (signal.SIGINT, signal.SIGTERM):
+                signal.signal(sig, lambda _signum, _frame: _signal_handler())
+
+        # --- Run ---
+        await sync_coordinator.start()
+        logger.info("Watch service running, press Ctrl+C to stop")
+        await shutdown_event.wait()
+    finally:
+        if sync_coordinator is not None:
+            await sync_coordinator.stop()
+        await db.shutdown_db()
+        logger.info("Watch service stopped")
+
+
+@app.command()
+def watch(
+    project: Optional[str] = typer.Option(None, help="Restrict watcher to a single project"),
+) -> None:
+    """Run file watcher as a long-running process (no MCP server).
+
+    Watches for file changes in project directories and syncs them to the
+    database. Useful for running Basic Memory sync alongside external tools
+    that don't use the MCP server.
+    """
+    # On Windows, use SelectorEventLoop to avoid ProactorEventLoop cleanup issues
+    if sys.platform == "win32":  # pragma: no cover
+        asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+
+    asyncio.run(run_watch(project=project))

src/basic_memory/config.py

@@ -81,7 +81,7 @@ class BasicMemoryConfig(BaseSettings):
         description="Name of the default project to use",
     )
     default_project_mode: bool = Field(
-        default=False,
+        default=True,
         description="When True, MCP tools automatically use default_project when no project parameter is specified. Enables simplified UX for single-project workflows.",
     )
 

src/basic_memory/mcp/project_context.py

@@ -29,19 +29,17 @@ async def resolve_project_parameter(
     default_project_mode: Optional[bool] = None,
     default_project: Optional[str] = None,
 ) -> Optional[str]:
-    """Resolve project parameter using three-tier hierarchy.
+    """Resolve project parameter using unified linear priority chain.
 
     This is a thin wrapper around ProjectResolver for backwards compatibility.
     New code should consider using ProjectResolver directly for more detailed
     resolution information.
 
-    if cloud_mode:
-        project is required (unless allow_discovery=True for tools that support discovery mode)
-    else:
-        Resolution order:
-        1. Single Project Mode  (--project cli arg, or BASIC_MEMORY_MCP_PROJECT env var) - highest priority
-        2. Explicit project parameter - medium priority
-        3. Default project if default_project_mode=true - lowest priority
+    Resolution order (same for local and cloud modes):
+    1. ENV_CONSTRAINT: BASIC_MEMORY_MCP_PROJECT env var (highest priority)
+    2. EXPLICIT: project parameter passed directly
+    3. DEFAULT: default project when default_project_mode=true
+    4. Fallback: cloud → CLOUD_DISCOVERY or ValueError; local → NONE
 
     Args:
         project: Optional explicit project parameter

src/basic_memory/mcp/prompts/ai_assistant_guide.py

@@ -32,7 +32,7 @@ def ai_assistant_guide() -> str:
 
     # Add mode-specific header
     mode_info = ""
-    if config.default_project_mode:  # pragma: no cover
+    if config.default_project_mode:
         mode_info = f"""
 # 🎯 Default Project Mode Active
 

src/basic_memory/mcp/resources/ai_assistant_guide.md

@@ -43,7 +43,7 @@ await write_note("Note", "Content", "folder")
 await write_note("Note", "Content", "folder", project="main")
 ```
 
-When `default_project_mode=false` (default):
+When `default_project_mode=false`:
 ```python
 # Project required:
 await write_note("Note", "Content", "folder", project="main")  # ✓

src/basic_memory/mcp/tools/build_context.py

@@ -50,8 +50,9 @@ async def build_context(
     a rich context graph of related information.
 
     Project Resolution:
-    Server resolves projects in this order: Single Project Mode → project parameter → default project.
-    If project unknown, use list_memory_projects() or recent_activity() first.
+    Server resolves projects using a unified priority chain (same in local and cloud modes):
+    Single Project Mode → project parameter → default project.
+    Uses default project automatically. Specify `project` parameter to target a different project.
 
     Args:
         project: Project name to build context from. Optional - server will resolve using hierarchy.

src/basic_memory/mcp/tools/read_note.py

@@ -30,8 +30,9 @@ async def read_note(
     returning the raw markdown content including observations, relations, and metadata.
 
     Project Resolution:
-    Server resolves projects in this order: Single Project Mode → project parameter → default project.
-    If project unknown, use list_memory_projects() or recent_activity() first.
+    Server resolves projects using a unified priority chain (same in local and cloud modes):
+    Single Project Mode → project parameter → default project.
+    Uses default project automatically. Specify `project` parameter to target a different project.
 
     This tool will try multiple lookup strategies to find the most relevant note:
     1. Direct permalink lookup

src/basic_memory/mcp/tools/write_note.py

@@ -32,8 +32,9 @@ async def write_note(
     Creates or updates a markdown note with semantic observations and relations.
 
     Project Resolution:
-    Server resolves projects in this order: Single Project Mode → project parameter → default project.
-    If project unknown, use list_memory_projects() or recent_activity() first.
+    Server resolves projects using a unified priority chain (same in local and cloud modes):
+    Single Project Mode → project parameter → default project.
+    Uses default project automatically. Specify `project` parameter to target a different project.
 
     The content can include semantic observations and relations using markdown syntax:
 
@@ -79,12 +80,7 @@ async def write_note(
         - Session tracking metadata for project awareness
 
     Examples:
-        # Assistant flow when project is unknown
-        # 1. list_memory_projects() -> Ask user which project
-        # 2. User: "Use my-research"
-        # 3. write_note(...) and remember "my-research" for session
-
-        # Create a simple note
+        # Create a simple note (uses default project automatically)
         write_note(
             project="my-research",
             title="Meeting Notes",