Merge branch 'main' into claw/cli-promo-analytics

Signed-off-by: Paul Hernandez <60959+phernandez@users.noreply.github.com>

Author: phernandez

.github/workflows/test.yml

@@ -102,6 +102,41 @@ jobs:
           uv pip install pytest pytest-cov
           just test-postgres
 
+  test-semantic:
+    name: Test Semantic (Python 3.12)
+    timeout-minutes: 45
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - uses: extractions/setup-just@v3
+
+      - name: Create virtual env
+        run: |
+          uv venv
+
+      - name: Install dependencies
+        run: |
+          uv pip install -e ".[dev,semantic]"
+
+      - name: Run tests (Semantic)
+        run: |
+          uv pip install pytest pytest-cov
+          just test-semantic
+
   coverage:
     name: Coverage Summary (combined, Python 3.12)
     timeout-minutes: 30

README.md

@@ -344,22 +344,20 @@ basic-memory sync --watch
 3. Cloud features (optional, requires subscription):
 
 ```bash
-# Authenticate with cloud (global cloud mode via OAuth)
+# Authenticate with cloud (stores OAuth token locally)
 basic-memory cloud login
 
-# Bidirectional sync with cloud
-basic-memory cloud sync
+# (Optional) install/configure rclone for file sync commands
+basic-memory cloud setup
 
-# Verify cloud integrity
-basic-memory cloud check
-
-# Mount cloud storage
-basic-memory cloud mount
+# Check cloud auth + health
+basic-memory cloud status
 ```
 
 **Per-Project Cloud Routing** (API key based):
 
-Individual projects can be routed through the cloud while others stay local. This uses an API key instead of OAuth:
+Individual projects can be routed through the cloud while others stay local. This uses an API key for routed
+project calls:
 
 ```bash
 # Save an API key (create one in the web app or via CLI)
@@ -373,25 +371,32 @@ basic-memory project set-cloud research
 # Revert a project to local mode
 basic-memory project set-local research
 
-# List projects with mode column (local/cloud)
+# List projects and route metadata
 basic-memory project list
 ```
 
-**Routing Flags** (for users with global cloud mode):
+`basic-memory cloud login` / `basic-memory cloud logout` are authentication commands. They do not change default CLI
+routing behavior.
+
+**Routing Flags**:
 
-When global cloud mode is enabled, CLI commands communicate with the cloud API by default. Use routing flags to override this:
+Use routing flags to disambiguate command targets:
 
 ```bash
-# Force local routing (useful for local MCP server while cloud mode is enabled)
+# Force local routing for this command
 basic-memory status --local
 basic-memory project list --local
+basic-memory project ls --name main --local
 
-# Force cloud routing (when cloud mode is disabled but you want cloud access)
+# Force cloud routing for this command
 basic-memory status --cloud
 basic-memory project info my-project --cloud
+basic-memory project ls --name main --cloud
 ```
 
-The local MCP server (`basic-memory mcp`) automatically uses local routing, so you can use both local Claude Desktop and cloud-based clients simultaneously.
+No-flag behavior defaults to local when no project context is present.
+
+The local MCP server (`basic-memory mcp`) always uses local routing (including `--transport stdio`).
 
 **CLI Note Editing (`tool edit-note`):**
 
@@ -493,7 +498,9 @@ Basic Memory uses [Loguru](https://github.com/Delgan/loguru) for logging. The lo
 |----------|---------|-------------|
 | `BASIC_MEMORY_LOG_LEVEL` | `INFO` | Log level: DEBUG, INFO, WARNING, ERROR |
 | `BASIC_MEMORY_CLOUD_MODE` | `false` | When `true`, API logs to stdout with structured context |
-| `BASIC_MEMORY_FORCE_LOCAL` | `false` | When `true`, forces local API routing (ignores cloud mode) |
+| `BASIC_MEMORY_FORCE_LOCAL` | `false` | When `true`, forces local API routing |
+| `BASIC_MEMORY_FORCE_CLOUD` | `false` | When `true`, forces cloud API routing |
+| `BASIC_MEMORY_EXPLICIT_ROUTING` | `false` | When `true`, marks route selection as explicit (`--local`/`--cloud`) |
 | `BASIC_MEMORY_ENV` | `dev` | Set to `test` for test mode (stderr only) |
 
 ### Examples

docs/ARCHITECTURE.md

@@ -18,7 +18,7 @@ Each entrypoint uses a **composition root** pattern to manage configuration and
 A composition root is the single place in an application where dependencies are wired together. In Basic Memory, each entrypoint has its own composition root that:
 
 1. Reads configuration from `ConfigManager`
-2. Resolves runtime mode (cloud/local/test)
+2. Resolves runtime mode (local/test)
 3. Creates and provides dependencies to downstream code
 
 **Key principle**: Only composition roots read global configuration. All other modules receive configuration explicitly.
@@ -52,10 +52,7 @@ class Container:
     def create(cls) -> "Container":
         """Create container by reading ConfigManager."""
         config = ConfigManager().config
-        mode = resolve_runtime_mode(
-            cloud_mode_enabled=config.cloud_mode_enabled,
-            is_test_env=config.is_test_env,
-        )
+        mode = resolve_runtime_mode(is_test_env=config.is_test_env)
         return cls(config=config, mode=mode)
 
     @property
@@ -99,18 +96,19 @@ class RuntimeMode(Enum):
         return self == RuntimeMode.TEST
 ```
 
-Resolution follows this precedence: **TEST > CLOUD > LOCAL**
+Resolution follows this precedence in local app flows: **TEST > LOCAL**
 
 ```python
-def resolve_runtime_mode(cloud_mode_enabled: bool, is_test_env: bool) -> RuntimeMode:
+def resolve_runtime_mode(is_test_env: bool) -> RuntimeMode:
     if is_test_env:
         return RuntimeMode.TEST
-    if cloud_mode_enabled:
-        return RuntimeMode.CLOUD
     return RuntimeMode.LOCAL
 ```
 
-**Note**: `RuntimeMode` determines global behavior (e.g., whether to start file sync). Per-project routing is orthogonal — individual projects can be set to `cloud` mode via `ProjectMode` in config, which affects client routing in `get_client(project_name=...)` without changing the global runtime mode.
+**Note**: `RuntimeMode` determines global behavior (e.g., whether to start file sync).
+Per-project routing is orthogonal: individual projects can be set to `cloud` mode via `ProjectMode`,
+which affects client routing in `get_client(project_name=...)` without changing global runtime mode.
+`RuntimeMode.CLOUD` may remain for compatibility, but standard local runtime resolution does not select it.
 
 ## Dependencies Package