feat: add per-project local/cloud routing with API key auth (#555)

Signed-off-by: phernandez <paul@basicmachines.co>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: phernandez

.github/workflows/test.yml

@@ -37,10 +37,11 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just (Linux/macOS)
+      - name: Install just (Linux)
         if: runner.os != 'Windows'
         run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+          sudo apt-get update
+          sudo apt-get install -y just
 
       - name: Install just (Windows)
         if: runner.os == 'Windows'
@@ -97,7 +98,8 @@ jobs:
 
       - name: Install just
         run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+          sudo apt-get update
+          sudo apt-get install -y just
 
       - name: Create virtual env
         run: |
@@ -133,7 +135,8 @@ jobs:
 
       - name: Install just
         run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+          sudo apt-get update
+          sudo apt-get install -y just
 
       - name: Create virtual env
         run: |

AGENTS.md

@@ -189,27 +189,46 @@ Flow: MCP Tool → Typed Client → HTTP API → Router → Service → Reposito
 
 ### Async Client Pattern (Important!)
 
-**All MCP tools and CLI commands use the context manager pattern for HTTP clients:**
+**MCP tools use `get_project_client()` for per-project routing:**
+
+```python
+from basic_memory.mcp.project_context import get_project_client
+
+@mcp.tool()
+async def my_tool(project: str | None = None, context: Context | None = None):
+    async with get_project_client(project, context) as (client, active_project):
+        # client is routed based on project's mode (local ASGI or cloud HTTP)
+        response = await call_get(client, "/path")
+        return response
+```
+
+**CLI commands and non-project-scoped code use `get_client()` directly:**
 
 ```python
 from basic_memory.mcp.async_client import get_client
 
-async def my_mcp_tool():
+async def my_cli_command():
     async with get_client() as client:
-        # Use client for API calls
         response = await call_get(client, "/path")
         return response
+
+# Per-project routing (when project name is known):
+async with get_client(project_name="research") as client:
+    ...
 ```
 
 **Do NOT use:**
 - ❌ `from basic_memory.mcp.async_client import client` (deprecated module-level client)
 - ❌ Manual auth header management
 - ❌ `inject_auth_header()` (deleted)
+- ❌ Separate `get_client()` + `get_active_project()` in MCP tools (use `get_project_client()` instead)
 
 **Key principles:**
 - Auth happens at client creation, not per-request
 - Proper resource management via context managers
-- Supports three modes: Local (ASGI), CLI cloud (HTTP + auth), Cloud app (factory injection)
+- Per-project routing: each project can be LOCAL or CLOUD independently
+- Cloud projects use API key (`cloud_api_key` in config) as Bearer token
+- Routing priority: factory injection > force-local > per-project cloud > global cloud > local ASGI
 - Factory pattern enables dependency injection for cloud consolidation
 
 **For cloud app integration:**
@@ -250,15 +269,19 @@ See SPEC-16 for full context manager refactor details.
 - List projects: `basic-memory project list`
 - Add project: `basic-memory project add "name" ~/path`
 - Project info: `basic-memory project info`
+- Set cloud mode: `basic-memory project set-cloud "name"`
+- Set local mode: `basic-memory project set-local "name"`
 - One-way sync (local -> cloud): `basic-memory project sync`
 - Bidirectional sync: `basic-memory project bisync`
 - Integrity check: `basic-memory project check`
 
 **Cloud Commands (requires subscription):**
-- Authenticate: `basic-memory cloud login`
-- Logout: `basic-memory cloud logout`
+- Authenticate (global): `basic-memory cloud login`
+- Logout (global): `basic-memory cloud logout`
 - Check cloud status: `basic-memory cloud status`
 - Setup cloud sync: `basic-memory cloud setup`
+- Save API key: `basic-memory cloud set-key bmc_...`
+- Create API key: `basic-memory cloud create-key "name"`
 - Manage snapshots: `basic-memory cloud snapshot [create|list|delete|show|browse]`
 - Restore from snapshot: `basic-memory cloud restore <path> --snapshot <id>`
 
@@ -329,9 +352,22 @@ Basic Memory now supports cloud synchronization and storage (requires active sub
 - Background relation resolution (non-blocking startup)
 - API performance optimizations (SPEC-11)
 
-**CLI Routing Flags:**
+**Per-Project Cloud Routing:**
+
+Individual projects can be routed through the cloud while others stay local, using an API key:
+
+```bash
+# Save API key and set project to cloud mode
+basic-memory cloud set-key bmc_abc123...
+basic-memory project set-cloud research    # route through cloud
+basic-memory project set-local research    # revert to local
+```
+
+MCP tools use `get_project_client()` which automatically routes based on the project's mode. Cloud projects use the `cloud_api_key` from config as Bearer token.
+
+**CLI Routing Flags (Global Cloud Mode):**
 
-When cloud mode is enabled, CLI commands route to the cloud API by default. Use `--local` and `--cloud` flags to override:
+When global cloud mode is enabled, CLI commands route to the cloud API by default. Use `--local` and `--cloud` flags to override:
 
 ```bash
 # Force local routing (ignore cloud mode)
@@ -348,6 +384,7 @@ Key behaviors:
 - This allows simultaneous use of local Claude Desktop and cloud-based clients
 - Some commands (like `project default`, `project sync-config`, `project move`) require `--local` in cloud mode since they modify local configuration
 - Environment variable `BASIC_MEMORY_FORCE_LOCAL=true` forces local routing globally
+- Per-project cloud routing via API key works independently of global cloud mode
 
 ## AI-Human Collaborative Development
 

README.md

@@ -344,7 +344,7 @@ basic-memory sync --watch
 3. Cloud features (optional, requires subscription):
 
 ```bash
-# Authenticate with cloud
+# Authenticate with cloud (global cloud mode via OAuth)
 basic-memory cloud login
 
 # Bidirectional sync with cloud
@@ -357,9 +357,29 @@ basic-memory cloud check
 basic-memory cloud mount
 ```
 
-**Routing Flags** (for users with cloud subscriptions):
+**Per-Project Cloud Routing** (API key based):
 
-When cloud mode is enabled, CLI commands communicate with the cloud API by default. Use routing flags to override this:
+Individual projects can be routed through the cloud while others stay local. This uses an API key instead of OAuth:
+
+```bash
+# Save an API key (create one in the web app or via CLI)
+basic-memory cloud set-key bmc_abc123...
+# Or create one via CLI (requires OAuth login first)
+basic-memory cloud create-key "my-laptop"
+
+# Set a project to route through cloud
+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)
+basic-memory project list
+```
+
+**Routing Flags** (for users with global cloud mode):
+
+When global cloud mode is enabled, CLI commands communicate with the cloud API by default. Use routing flags to override this:
 
 ```bash
 # Force local routing (useful for local MCP server while cloud mode is enabled)

docs/ARCHITECTURE.md

@@ -110,6 +110,8 @@ def resolve_runtime_mode(cloud_mode_enabled: bool, is_test_env: bool) -> Runtime
     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.
+
 ## Dependencies Package
 
 ### Structure
@@ -221,9 +223,7 @@ async def search_notes(
     tags: list[str] | None = None,
     status: str | None = None,
 ) -> SearchResponse:
-    async with get_client() as client:
-        active_project = await get_active_project(client, project)
-
+    async with get_project_client(project, context) as (client, active_project):
         # Import client inside function to avoid circular imports
         from basic_memory.mcp.clients import SearchClient
         from basic_memory.schemas.search import SearchQuery
@@ -238,6 +238,25 @@ async def search_notes(
         return await search_client.search(search_query.model_dump())
 ```
 
+### Per-Project Client Routing
+
+`get_project_client()` from `mcp/project_context.py` is an async context manager that:
+1. Resolves the project name from config (no network call)
+2. Creates the correctly-routed client based on the project's mode (local ASGI or cloud HTTP with API key)
+3. Validates the project via the API
+4. Yields `(client, active_project)` tuple
+
+This solves the bootstrap problem: you need the project name to choose the right client (local vs cloud), but you need the client to validate the project exists.
+
+```python
+from basic_memory.mcp.project_context import get_project_client
+
+async with get_project_client(project, context) as (client, active_project):
+    # client is routed based on project's mode (local or cloud)
+    # active_project is validated via the API
+    ...
+```
+
 ## Sync Coordination
 
 ### SyncCoordinator