chore: update version to 0.19.1 for v0.19.1 release

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

.claude/settings.json

@@ -1,5 +1,3 @@
 {
-  "enabledPlugins": {
-    "basic-memory@basicmachines": true
-  }
+  "enabledPlugins": {}
 }

.github/workflows/test.yml

@@ -1,25 +1,70 @@
 name: Tests
 
+concurrency:
+  group: bm-ci-${{ github.workflow }}-${{ github.repository }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
-  # pull_request_target runs on the BASE of the PR, not the merge result.
-  # It has write permissions and access to secrets.
-  # It's useful for PRs from forks or automated PRs but requires careful use for security reasons.
-  # See: https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target
-  pull_request_target:
-    branches: [ "main" ]
 
 jobs:
-  test-sqlite:
-    name: Test SQLite (${{ matrix.os }}, Python ${{ matrix.python-version }})
+  static-checks:
+    name: Static Checks (Python 3.12)
+    timeout-minutes: 20
+    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]"
+
+      - name: Run type checks
+        run: |
+          just typecheck
+
+      - name: Run linting
+        run: |
+          just lint
+
+  test-sqlite-unit:
+    name: Test SQLite Unit (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    timeout-minutes: 30
+    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
-        python-version: [ "3.12", "3.13", "3.14" ]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
+          - os: windows-latest
+            python-version: "3.12"
     runs-on: ${{ matrix.os }}
 
     steps:
@@ -37,17 +82,7 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just (Linux/macOS)
-        if: runner.os != 'Windows'
-        run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
-
-      - name: Install just (Windows)
-        if: runner.os == 'Windows'
-        run: |
-          # Install just using Chocolatey (pre-installed on GitHub Actions Windows runners)
-          choco install just --yes
-        shell: pwsh
+      - uses: extractions/setup-just@v3
 
       - name: Create virtual env
         run: |
@@ -55,27 +90,70 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv pip install -e .[dev]
+          uv pip install -e ".[dev]"
 
-      - name: Run type checks
+      - name: Run tests
         run: |
-          just typecheck
+          just test-unit-sqlite
 
-      - name: Run linting
-        run: |
-          just lint
-
-      - name: Run tests (SQLite)
-        run: |
-          uv pip install pytest pytest-cov
-          just test-sqlite
-
-  test-postgres:
-    name: Test Postgres (Python ${{ matrix.python-version }})
+  test-sqlite-integration:
+    name: Test SQLite Integration (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    timeout-minutes: 45
+    needs: [static-checks]
     strategy:
       fail-fast: false
       matrix:
-        python-version: [ "3.12", "3.13", "3.14" ]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.12"
+          - os: ubuntu-latest
+            python-version: "3.13"
+          - os: ubuntu-latest
+            python-version: "3.14"
+          - os: windows-latest
+            python-version: "3.12"
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          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]"
+
+      - name: Run tests
+        run: |
+          just test-int-sqlite
+
+  test-postgres-unit:
+    name: Test Postgres Unit (Python ${{ matrix.python-version }})
+    timeout-minutes: 30
+    needs: [static-checks]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.12"
+          - python-version: "3.13"
+          - python-version: "3.14"
     runs-on: ubuntu-latest
 
     # Note: No services section needed - testcontainers handles Postgres in Docker
@@ -95,9 +173,7 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just
-        run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+      - uses: extractions/setup-just@v3
 
       - name: Create virtual env
         run: |
@@ -105,15 +181,60 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv pip install -e .[dev]
+          uv pip install -e ".[dev]"
 
-      - name: Run tests (Postgres via testcontainers)
+      - name: Run tests
         run: |
-          uv pip install pytest pytest-cov
-          just test-postgres
+          just test-unit-postgres
 
-  coverage:
-    name: Coverage Summary (combined, Python 3.12)
+  test-postgres-integration:
+    name: Test Postgres Integration (Python ${{ matrix.python-version }})
+    timeout-minutes: 45
+    needs: [static-checks]
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - python-version: "3.12"
+          - python-version: "3.13"
+          - python-version: "3.14"
+    runs-on: ubuntu-latest
+
+    # Note: No services section needed - testcontainers handles Postgres in Docker
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          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]"
+
+      - name: Run tests
+        run: |
+          just test-int-postgres
+
+  test-semantic:
+    name: Test Semantic (Python 3.12)
+    timeout-minutes: 45
+    needs: [static-checks]
     runs-on: ubuntu-latest
 
     steps:
@@ -131,9 +252,7 @@ jobs:
         run: |
           pip install uv
 
-      - name: Install just
-        run: |
-          curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin
+      - uses: extractions/setup-just@v3
 
       - name: Create virtual env
         run: |
@@ -141,27 +260,8 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv pip install -e .[dev]
+          uv pip install -e ".[dev]"
 
-      - name: Run combined coverage (SQLite + Postgres)
+      - name: Run tests
         run: |
-          uv pip install pytest pytest-cov
-          just coverage
-
-      - name: Add coverage report to job summary
-        if: always()
-        run: |
-          {
-            echo "## Coverage"
-            echo ""
-            echo '```'
-            uv run coverage report -m
-            echo '```'
-          } >> "$GITHUB_STEP_SUMMARY"
-
-      - name: Upload HTML coverage report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: htmlcov
-          path: htmlcov/
+          just test-semantic

.gitignore

@@ -1,6 +1,7 @@
 *.py[cod]
 __pycache__/
 .pytest_cache/
+.testmondata*
 .coverage
 htmlcov/
 
@@ -55,3 +56,5 @@ claude-output
 **/.claude/settings.local.json
 .mcp.json
 .mcpregistry_*
+/.testmondata
+.benchmarks/

AGENTS.md

@@ -0,0 +1,446 @@
+# AGENTS.md - Basic Memory Project Guide
+
+## Project Overview
+
+Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables
+bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can
+be traversed using links between documents.
+
+## CODEBASE DEVELOPMENT
+
+### Project information
+
+See the [README.md](README.md) file for a project overview.
+
+### Build and Test Commands
+
+- Install: `just install` or `pip install -e ".[dev]"`
+- Run all tests (SQLite + Postgres): `just test`
+- Run all tests against SQLite: `just test-sqlite`
+- Run all tests against Postgres: `just test-postgres` (uses testcontainers)
+- Run unit tests (SQLite): `just test-unit-sqlite`
+- Run unit tests (Postgres): `just test-unit-postgres`
+- Run integration tests (SQLite): `just test-int-sqlite`
+- Run integration tests (Postgres): `just test-int-postgres`
+- Run impacted tests: `just testmon` (pytest-testmon)
+- Run MCP smoke test: `just test-smoke`
+- Fast local loop: `just fast-check`
+- Local consistency check: `just doctor`
+- Generate HTML coverage: `just coverage`
+- Single test: `pytest tests/path/to/test_file.py::test_function_name`
+- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
+- Lint: `just lint` or `ruff check . --fix`
+- Type check: `just typecheck` or `uv run pyright`
+- Type check (supplemental): `just typecheck-ty` or `uv run ty check src/`
+- Format: `just format` or `uv run ruff format .`
+- Run all code checks: `just check` (runs lint, format, typecheck, test)
+- Create db migration: `just migration "Your migration message"`
+- Run development MCP Inspector: `just run-inspector`
+
+**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)
+
+**Postgres Testing:** Uses [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.
+
+**Doctor Note:** `just doctor` runs with a temporary HOME/config so it won't touch your local Basic Memory settings. It leaves temp dirs in `/tmp` (safe to ignore or remove).
+
+**Testmon Note:** When no files have changed, `just testmon` may collect 0 tests. That's expected and means no impacted tests were detected.
+
+### Code/Test/Verify Loop (fast path)
+
+1) **Code:** make changes.
+2) **Test:** `just fast-check` (lint/format/typecheck + impacted tests + MCP smoke).
+3) **Verify:** `just doctor` (end-to-end file ↔ DB loop in a temp project).
+4) **Full gate (when needed):** `just test` or `just check` for SQLite + Postgres.
+
+If testmon is “cold,” the first run may be long. Subsequent runs get much faster.
+
+### Test Structure
+
+- `tests/` - Unit tests for individual components (mocked, fast)
+- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)
+- Both directories are covered by unified coverage reporting
+- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`
+- Slow tests are marked with `@pytest.mark.slow`
+- Smoke tests are marked with `@pytest.mark.smoke`
+
+### Code Style Guidelines
+
+- Line length: 100 characters max
+- Python 3.12+ with full type annotations (uses type parameters and type aliases)
+- Format with ruff (consistent styling)
+- Import order: standard lib, third-party, local imports
+- Naming: snake_case for functions/variables, PascalCase for classes
+- Prefer async patterns with SQLAlchemy 2.0
+- Use Pydantic v2 for data validation and schemas
+- CLI uses Typer for command structure
+- API uses FastAPI for endpoints
+- Follow the repository pattern for data access
+- Tools communicate to api routers via the httpx ASGI client (in process)
+
+### Code Change Guidelines
+
+- **Full file read before edits**: Before editing any file, read it in full first to ensure complete context; partial reads lead to corrupted edits
+- **Minimize diffs**: Prefer the smallest change that satisfies the request. Avoid unrelated refactors or style rewrites unless necessary for correctness
+- **No speculative getattr**: Never use `getattr(obj, "attr", default)` when unsure about attribute names. Check the class definition or source code first
+- **Fail fast**: Write code with fail-fast logic by default. Do not swallow exceptions with errors or warnings
+- **No fallback logic**: Do not add fallback logic unless explicitly told to and agreed with the user
+- **No guessing**: Do not say "The issue is..." before you actually know what the issue is. Investigate first.
+
+### Literate Programming Style
+
+Code should tell a story. Comments must explain the "why" and narrative flow, not just the "what".
+
+**Section Headers:**
+For files with multiple phases of logic, add section headers so the control flow reads like chapters:
+```python
+# --- Authentication ---
+# ... auth logic ...
+
+# --- Data Validation ---
+# ... validation logic ...
+
+# --- Business Logic ---
+# ... core logic ...
+```
+
+**Decision Point Comments:**
+For conditionals that materially change behavior (gates, fallbacks, retries, feature flags), add comments with:
+- **Trigger**: what condition causes this branch
+- **Why**: the rationale (cost, correctness, UX, determinism)
+- **Outcome**: what changes downstream
+
+```python
+# Trigger: project has no active sync watcher
+# Why: avoid duplicate file system watchers consuming resources
+# Outcome: starts new watcher, registers in active_watchers dict
+if project_id not in active_watchers:
+    start_watcher(project_id)
+```
+
+**Constraint Comments:**
+If code exists because of a constraint (async requirements, rate limits, schema compatibility), explain the constraint near the code:
+```python
+# SQLite requires WAL mode for concurrent read/write access
+connection.execute("PRAGMA journal_mode=WAL")
+```
+
+**What NOT to Comment:**
+Avoid comments that restate obvious code:
+```python
+# Bad - restates code
+counter += 1  # increment counter
+
+# Good - explains why
+counter += 1  # track retries for backoff calculation
+```
+
+### Codebase Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture documentation.
+
+**Directory Structure:**
+- `/alembic` - Alembic db migrations
+- `/api` - FastAPI REST endpoints + `container.py` composition root
+- `/cli` - Typer CLI + `container.py` composition root
+- `/deps` - Feature-scoped FastAPI dependencies (config, db, projects, repositories, services, importers)
+- `/importers` - Import functionality for Claude, ChatGPT, and other sources
+- `/markdown` - Markdown parsing and processing
+- `/mcp` - MCP server + `container.py` composition root + `clients/` typed API clients
+- `/models` - SQLAlchemy ORM models
+- `/repository` - Data access layer
+- `/schemas` - Pydantic models for validation
+- `/services` - Business logic layer
+- `/sync` - File synchronization services + `coordinator.py` for lifecycle management
+
+**Composition Roots:**
+Each entrypoint (API, MCP, CLI) has a composition root that:
+- Reads `ConfigManager` (the only place that reads global config)
+- Resolves runtime mode via `RuntimeMode` enum (TEST > CLOUD > LOCAL)
+- Provides dependencies to downstream code explicitly
+
+**Typed API Clients (MCP):**
+MCP tools use typed clients in `mcp/clients/` to communicate with the API:
+- `KnowledgeClient` - Entity CRUD operations
+- `SearchClient` - Search operations
+- `MemoryClient` - Context building
+- `DirectoryClient` - Directory listing
+- `ResourceClient` - Resource reading
+- `ProjectClient` - Project management
+
+Flow: MCP Tool → Typed Client → HTTP API → Router → Service → Repository
+
+### Development Notes
+
+- MCP tools are defined in src/basic_memory/mcp/tools/
+- MCP prompts are defined in src/basic_memory/mcp/prompts/
+- MCP tools should be atomic, composable operations
+- Use `textwrap.dedent()` for multi-line string formatting in prompts and tools
+- MCP Prompts are used to invoke tools and format content with instructions for an LLM
+- Schema changes require Alembic migrations
+- SQLite is used for indexing and full text search, files are source of truth
+- Testing uses pytest with asyncio support (strict mode)
+- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations
+- By default, tests run against SQLite (fast, no Docker needed)
+- Set `BASIC_MEMORY_TEST_POSTGRES=1` to run against Postgres (uses testcontainers - Docker required)
+- Each test runs in a standalone environment with isolated database and tmp_path directory
+- CI runs SQLite and Postgres tests in parallel for faster feedback
+- Performance benchmarks are in `test-int/test_sync_performance_benchmark.py`
+- Use pytest markers: `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
+- **Coverage must stay at 100%**: Write tests for new code. Only use `# pragma: no cover` when tests would require excessive mocking (e.g., TYPE_CHECKING blocks, error handlers that need failure injection, runtime-mode-dependent code paths)
+
+### Async Client Pattern (Important!)
+
+**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_cli_command():
+    async with get_client() as client:
+        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
+- 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:**
+```python
+from basic_memory.mcp import async_client
+
+# Set custom factory before importing tools
+async_client.set_client_factory(your_custom_factory)
+```
+
+See SPEC-16 for full context manager refactor details.
+
+## BASIC MEMORY PRODUCT USAGE
+
+### Knowledge Structure
+
+- Entity: Any concept, document, or idea represented as a markdown file
+- Observation: A categorized fact about an entity (`- [category] content`)
+- Relation: A directional link between entities (`- relation_type [[Target]]`)
+- Frontmatter: YAML metadata at the top of markdown files
+- Knowledge representation follows precise markdown format:
+    - Observations with [category] prefixes
+    - Relations with WikiLinks [[Entity]]
+    - Frontmatter with metadata
+
+### Basic Memory Commands
+
+**Local Commands:**
+- Check sync status: `basic-memory status`
+- Doctor check (file <-> DB loop): `basic-memory doctor`
+- Import from Claude: `basic-memory import claude conversations`
+- Import from ChatGPT: `basic-memory import chatgpt`
+- Import from Memory JSON: `basic-memory import memory-json`
+- Tool access: `basic-memory tool` (provides CLI access to MCP tools)
+    - Continue: `basic-memory tool continue-conversation --topic="search"`
+
+**Project Management:**
+- 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 (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>`
+
+### MCP Capabilities
+
+- Basic Memory exposes these MCP tools to LLMs:
+
+  **Content Management:**
+    - `write_note(title, content, directory, tags)` - Create/update markdown notes with semantic observations and relations
+    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness
+    - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
+    - `view_note(identifier, page, page_size)` - View notes as formatted artifacts for better readability
+    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, replace_section)
+    - `move_note(identifier, destination_path, is_directory)` - Move notes or directories to new locations, updating database and maintaining links
+    - `delete_note(identifier, is_directory)` - Delete notes or directories from the knowledge base
+
+  **Knowledge Graph Navigation:**
+    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity
+    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")
+    - `list_directory(dir_name, depth, file_name_glob)` - Browse directory contents with filtering and depth control
+
+  **Search & Discovery:**
+    - `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options
+
+  **Project Management:**
+    - `list_memory_projects()` - List all available projects with their status
+    - `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects
+    - `delete_project(project_name)` - Delete a project from configuration
+
+  **Visualization:**
+    - `canvas(nodes, edges, title, directory)` - Generate Obsidian canvas files for knowledge graph visualization
+
+  **ChatGPT-Compatible Tools:**
+    - `search(query)` - Search across knowledge base (OpenAI actions compatible)
+    - `fetch(id)` - Fetch full content of a search result document
+
+- MCP Prompts for better AI interaction:
+    - `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants
+    - `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context
+    - `search(query, after_date)` - Search with detailed, formatted results for better context understanding
+    - `recent_activity(timeframe)` - View recently changed items with formatted output
+
+### Cloud Features (v0.15.0+)
+
+Basic Memory now supports cloud synchronization and storage (requires active subscription):
+
+**Authentication:**
+- JWT-based authentication with subscription validation
+- Secure session management with token refresh
+- Support for multiple cloud projects
+
+**Bidirectional Sync:**
+- rclone bisync integration for two-way synchronization
+- Conflict resolution and integrity verification
+- Real-time sync with change detection
+- Mount/unmount cloud storage for direct file access
+
+**Cloud Project Management:**
+- Create and manage projects in the cloud
+- Toggle between local and cloud modes
+- Per-project sync configuration
+- Subscription-based access control
+
+**Security & Performance:**
+- Removed .env file loading for improved security
+- .gitignore integration (respects gitignored files)
+- WAL mode for SQLite performance
+- Background relation resolution (non-blocking startup)
+- API performance optimizations (SPEC-11)
+
+**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 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)
+basic-memory status --local
+basic-memory project list --local
+
+# Force cloud routing (when cloud mode is disabled)
+basic-memory status --cloud
+basic-memory project info my-project --cloud
+```
+
+Key behaviors:
+- The local MCP server (`basic-memory mcp`) automatically uses local routing
+- 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
+
+Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead
+of using AI just for code generation, we've developed a true collaborative workflow:
+
+1. AI (LLM) writes initial implementation based on specifications and context
+2. Human reviews, runs tests, and commits code with any necessary adjustments
+3. Knowledge persists across conversations using Basic Memory's knowledge graph
+4. Development continues seamlessly across different AI sessions with consistent context
+5. Results improve through iterative collaboration and shared understanding
+
+This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
+could achieve independently.
+
+**Problem-Solving Guidance:**
+- If a solution isn't working after reasonable effort, suggest alternative approaches
+- Don't persist with a problematic library or pattern when better alternatives exist
+- Example: When py-pglite caused cascading test failures, switching to testcontainers-postgres was the right call
+
+## GitHub Integration
+
+Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:
+
+### GitHub MCP Tools
+
+Using the GitHub Model Context Protocol server, Claude can now:
+
+- **Repository Management**:
+  - View repository files and structure
+  - Read file contents
+  - Create new branches
+  - Create and update files
+
+- **Issue Management**:
+  - Create new issues
+  - Comment on existing issues
+  - Close and update issues
+  - Search across issues
+
+- **Pull Request Workflow**:
+  - Create pull requests
+  - Review code changes
+  - Add comments to PRs
+
+This integration enables Claude to participate as a full team member in the development process, not just as a code generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic Machines organization with direct contributor access to the codebase.
+
+### Collaborative Development Process
+
+With GitHub integration, the development workflow includes:
+
+1. **Direct code review** - Claude can analyze PRs and provide detailed feedback
+2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
+3. **Branch management** - Claude can create feature branches for implementations
+4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
+5. **Code Commits**: ALWAYS sign off commits with `git commit -s`
+
+This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

CHANGELOG.md

@@ -1,5 +1,269 @@
 # CHANGELOG
 
+## Unreleased
+
+## v0.19.1 (2026-03-08)
+
+### Bug Fixes
+
+- **#649**: Enforce strict entity resolution in destructive MCP tools (`edit_note`, `move_note`, `delete_note`)
+  - Prevents fuzzy-match fallback from silently editing/moving/deleting the wrong note
+  - DST-related timeframe validation fix (round instead of truncate days)
+
+### Features
+
+- **#648**: Add `insert_before_section` and `insert_after_section` edit operations
+- Add `GET /knowledge/graph` endpoint for full graph visualization
+
+### Dependencies
+
+- Bump authlib from 1.6.6 to 1.6.7
+
+## v0.19.0 (2026-03-07)
+
+### Highlights
+
+- **Semantic vector search** for SQLite and Postgres with FastEmbed embeddings
+- **Schema system** for validating and inferring knowledge base structure
+- **Per-project cloud routing** with API key authentication
+- **Upgraded to FastMCP 3.0** with tool annotations
+- **CLI overhaul** with JSON output, workspace awareness, and project dashboard
+
+### Features
+
+- **#550**: Add semantic vector search for SQLite and Postgres
+  - FastEmbed-based embeddings with automatic backfill
+  - Hybrid search combining full-text and vector similarity
+  - Score-based fusion replacing RRF for better ranking
+  - `min_similarity` override for tuning search precision
+  - Semantic dependencies are now default, with optional extras fallback
+
+- **#549**: Schema system for Basic Memory
+  - `schema_infer` — infer schema from existing notes
+  - `schema_validate` — validate notes against a schema definition
+  - `schema_diff` — compare schemas across projects
+  - Frontmatter validation support (#597)
+  - Read schema definitions from file instead of stale DB metadata (#635)
+
+- **#555**: Per-project local/cloud routing with API key auth
+  - Individual projects route through cloud while others stay local
+  - `basic-memory cloud set-key` and `basic-memory project set-cloud/set-local`
+  - Stdio MCP honors per-project cloud routing (#590)
+
+- **#598**: Upgrade FastMCP 2.12.3 to 3.0.1 with tool annotations
+
+- **#585**: Add JSON output mode for MCP tools (default text)
+  - `--json` output for CLI commands for scripting and CI
+
+- **#576**: Add workspace selection flow for MCP and CLI
+  - Workspace-aware cloud project listing
+  - CLI refactoring for workspace support
+
+- **#544**: Project-prefixed permalinks and memory URL routing
+
+- **#632**: Add overwrite guard to `write_note` tool
+
+- **#614**: `edit_note` append/prepend auto-creates note if not found
+
+- **#609**: Richer content context in search results
+  - Return matched chunk text in search results (#601)
+  - Improved content hit rate
+
+- **#602**: Add `created_by` and `last_updated_by` user tracking to Entity
+
+- **#600**: Rename `entity_type` to `note_type` across codebase
+
+- **#574**: Add `display_name` and `is_private` to ProjectItem
+
+- **#569**: Expose `external_id` in EntityResponse and link resolver
+
+- **#567**: Isolate default SQLite DB by config dir
+
+- **#560**: Enable `default_project_mode` by default
+
+- **#559**: Add `basic-memory watch` CLI command
+
+- **#546**: Add cloud discovery touchpoints to CLI and MCP
+
+- **#572**: CLI analytics via Umami event collector
+
+- Replace project info with htop-inspired dashboard
+
+- Merge `search_by_metadata` into `search_notes` with optional query
+
+- Add `--strip-frontmatter` to `basic-memory tool read-note`
+
+- Add `destination_folder` parameter to `move_note` tool
+
+### Bug Fixes
+
+- **#644**: Fix default project resolution in cloud mode
+  - ChatGPT search/fetch tools broken in cloud mode
+  - `resolve_project_parameter` falls back to projects API
+
+- **#638**: Restore API backward compatibility for v0.18.x clients
+
+- **#637**: Create backup before config migration overwrites old format
+
+- **#636**: `list_workspaces` bypasses factory pattern on cloud MCP server
+
+- **#631**: `build_context` related_results schema validation failure
+
+- **#613**: Reduce excessive log volume by demoting per-request noise to DEBUG
+
+- **#612**: Handle quoted picoschema enum strings in YAML frontmatter
+
+- **#607**: Guard against closed streams in promo and missing vector tables
+
+- **#606**: Accept null for `expected_replacements` in `edit_note`
+
+- **#595**: `recent_activity` dedup and pagination across MCP tools
+
+- **#593**: Backend-specific distance-to-similarity conversion
+
+- **#582**: Use LinkResolver fallback in `build_context` for flexible identifier matching
+
+- **#577**: Replace RRF with score-based fusion in hybrid search
+
+- **#575**: Remove hardcoded "main" default from `default_project`
+
+- **#534**: Speed up `bm --version` startup
+
+- Fix semantic embeddings not generated on fresh DB or upgrade
+
+- Clarify `search_notes` parameter naming and fix `note_types` case sensitivity
+
+- Parse `tag:` prefix at MCP tool level to avoid hybrid search failure
+
+- Cap sqlite-vec knn k parameter at 4096 limit
+
+- Parameterize SQL queries in search repository type filters
+
+- Coerce list frontmatter values to strings for title and type fields
+
+- Avoid `Post(**metadata)` crash when frontmatter contains 'content' or 'handler' keys
+
+- Upgrade cryptography and python-multipart for security advisories
+
+### Internal
+
+- **#594**: Add `ty` as supplemental type checker
+- Batched vector sync orchestration across repositories
+- FastEmbed parallel guardrails and provider caching
+- Improved cloud CLI status and error messages
+- CI coverage and Postgres test fixes
+
+## v0.18.5 (2026-02-13)
+
+### Bug Fixes
+
+- Strip NUL bytes from content before PostgreSQL search indexing
+  ([`ec9b2c4`](https://github.com/basicmachines-co/basic-memory/commit/ec9b2c4))
+
+## v0.18.4 (2026-02-12)
+
+### Bug Fixes
+
+- Use global `--header` flag for Tigris consistency on all rclone transactions
+  ([`0eae0e1`](https://github.com/basicmachines-co/basic-memory/commit/0eae0e1))
+  - `--header-download` / `--header-upload` only apply to GET/PUT requests, missing S3
+    ListObjectsV2 calls that bisync issues first. Non-US users saw stale edge-cached metadata.
+  - `--header` applies to ALL HTTP transactions (list, download, upload), fixing bisync for
+    users outside the Tigris origin region.
+
+## v0.18.2 (2026-02-11)
+
+### Bug Fixes
+
+- **#562**: Use VIRTUAL instead of STORED columns in SQLite migration
+  ([`344e651`](https://github.com/basicmachines-co/basic-memory/commit/344e651))
+  - Fixes compatibility issue with SQLite STORED generated columns
+
+## v0.18.1 (2026-02-11)
+
+### Features
+
+- **#552**: Add `--format json` to CLI tool commands
+  ([`a47c9c0`](https://github.com/basicmachines-co/basic-memory/commit/a47c9c0))
+  - CLI tool commands now support `--format json` for machine-readable output
+
+- **#535**: Support `tag:` query shorthand in search
+  ([`f1d50c2`](https://github.com/basicmachines-co/basic-memory/commit/f1d50c2))
+  - Use `tag:mytag` as a convenient shorthand in search queries
+
+- **#532**: Fast edit entities, refactors for webui, enhanced search
+  ([`530cbac`](https://github.com/basicmachines-co/basic-memory/commit/530cbac))
+  - Performance improvements for entity editing and search operations
+
+### Bug Fixes
+
+- **#558**: Add X-Tigris-Consistent headers to all rclone commands
+  ([`8489a3d`](https://github.com/basicmachines-co/basic-memory/commit/8489a3d))
+  - Ensures consistent reads from Tigris object storage during sync
+
+- **#541**: Handle EntityCreationError as conflict
+  ([`343a6e1`](https://github.com/basicmachines-co/basic-memory/commit/343a6e1))
+
+- **#536**: Stabilize metadata filters on Postgres
+  ([`009e849`](https://github.com/basicmachines-co/basic-memory/commit/009e849))
+
+- **#533**: Fix recent_activity prompt defaults
+  ([`24ca5f6`](https://github.com/basicmachines-co/basic-memory/commit/24ca5f6))
+
+- **#530**: Prevent spurious `metadata: {}` in frontmatter output
+  ([`e3ced49`](https://github.com/basicmachines-co/basic-memory/commit/e3ced49))
+
+- Add POST legacy compat routes for v0.18.0 CLI
+  ([`c46d7a6`](https://github.com/basicmachines-co/basic-memory/commit/c46d7a6))
+
+- Restore legacy `/projects/projects` endpoint for older CLI versions
+  ([`a0e754b`](https://github.com/basicmachines-co/basic-memory/commit/a0e754b))
+
+### Internal
+
+- **#538**: Add fast feedback loop tooling (`just fast-check`, `just doctor`, `just testmon`)
+  ([`8072449`](https://github.com/basicmachines-co/basic-memory/commit/8072449))
+
+## v0.18.0 (2026-01-28)
+
+### Features
+
+- **#527**: Add context-aware wiki link resolution with source_path support
+  ([`0023e73`](https://github.com/basicmachines-co/basic-memory/commit/0023e73))
+  - Add `source_path` parameter to `resolve_link()` for context-aware resolution
+  - Relative path resolution: `[[nested/note]]` from `folder/file.md` → `folder/nested/note.md`
+  - Proximity-based resolution for duplicate titles (prefers notes in same folder)
+  - Strict mode to disable fuzzy search fallback for wiki links
+
+- **#518**: Add directory support to move_note and delete_note tools
+  ([`0b20801`](https://github.com/basicmachines-co/basic-memory/commit/0b20801))
+  - Add `is_directory` parameter to `move_note` and `delete_note` MCP tools
+  - New `POST /move-directory` and delete directory API endpoints
+  - Rename `folder` → `directory` parameter across codebase for consistency
+
+- **#522**: Local MCP cloud mode routing
+  ([`8730067`](https://github.com/basicmachines-co/basic-memory/commit/8730067))
+  - Add `--local` and `--cloud` CLI routing flags
+  - Local MCP server (`basic-memory mcp`) automatically uses local routing
+  - Enables simultaneous use of local Claude Desktop and cloud-based clients
+  - Environment variable `BASIC_MEMORY_FORCE_LOCAL=true` for global override
+
+### Bug Fixes
+
+- **#524**: Fix MCP prompt rendering errors
+  ([`e14ba92`](https://github.com/basicmachines-co/basic-memory/commit/e14ba92))
+  - Fix "Error rendering prompt recent_activity" error
+  - Change `TimeFrame` to `str` in prompt type annotations for FastMCP compatibility
+
+## v0.17.9 (2026-01-24)
+
+### Bug Fixes
+
+- **#523**: Fix `remove_project()` checking stale config in cloud mode
+  ([`17c0e0a`](https://github.com/basicmachines-co/basic-memory/commit/17c0e0a))
+  - In cloud mode, only check database `is_default` field (source of truth)
+  - Config file can become stale when users set default project via v2 API
+
 ## v0.17.8 (2026-01-24)
 
 ### Bug Fixes

CLAUDE.md

@@ -1,369 +0,0 @@
-# CLAUDE.md - Basic Memory Project Guide
-
-## Project Overview
-
-Basic Memory is a local-first knowledge management system built on the Model Context Protocol (MCP). It enables
-bidirectional communication between LLMs (like Claude) and markdown files, creating a personal knowledge graph that can
-be traversed using links between documents.
-
-## CODEBASE DEVELOPMENT
-
-### Project information
-
-See the [README.md](README.md) file for a project overview.
-
-### Build and Test Commands
-
-- Install: `just install` or `pip install -e ".[dev]"`
-- Run all tests (SQLite + Postgres): `just test`
-- Run all tests against SQLite: `just test-sqlite`
-- Run all tests against Postgres: `just test-postgres` (uses testcontainers)
-- Run unit tests (SQLite): `just test-unit-sqlite`
-- Run unit tests (Postgres): `just test-unit-postgres`
-- Run integration tests (SQLite): `just test-int-sqlite`
-- Run integration tests (Postgres): `just test-int-postgres`
-- Generate HTML coverage: `just coverage`
-- Single test: `pytest tests/path/to/test_file.py::test_function_name`
-- Run benchmarks: `pytest test-int/test_sync_performance_benchmark.py -v -m "benchmark and not slow"`
-- Lint: `just lint` or `ruff check . --fix`
-- Type check: `just typecheck` or `uv run pyright`
-- Format: `just format` or `uv run ruff format .`
-- Run all code checks: `just check` (runs lint, format, typecheck, test)
-- Create db migration: `just migration "Your migration message"`
-- Run development MCP Inspector: `just run-inspector`
-
-**Note:** Project requires Python 3.12+ (uses type parameter syntax and `type` aliases introduced in 3.12)
-
-**Postgres Testing:** Uses [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.
-
-### Test Structure
-
-- `tests/` - Unit tests for individual components (mocked, fast)
-- `test-int/` - Integration tests for real-world scenarios (no mocks, realistic)
-- Both directories are covered by unified coverage reporting
-- Benchmark tests in `test-int/` are marked with `@pytest.mark.benchmark`
-- Slow tests are marked with `@pytest.mark.slow`
-
-### Code Style Guidelines
-
-- Line length: 100 characters max
-- Python 3.12+ with full type annotations (uses type parameters and type aliases)
-- Format with ruff (consistent styling)
-- Import order: standard lib, third-party, local imports
-- Naming: snake_case for functions/variables, PascalCase for classes
-- Prefer async patterns with SQLAlchemy 2.0
-- Use Pydantic v2 for data validation and schemas
-- CLI uses Typer for command structure
-- API uses FastAPI for endpoints
-- Follow the repository pattern for data access
-- Tools communicate to api routers via the httpx ASGI client (in process)
-
-### Code Change Guidelines
-
-- **Full file read before edits**: Before editing any file, read it in full first to ensure complete context; partial reads lead to corrupted edits
-- **Minimize diffs**: Prefer the smallest change that satisfies the request. Avoid unrelated refactors or style rewrites unless necessary for correctness
-- **No speculative getattr**: Never use `getattr(obj, "attr", default)` when unsure about attribute names. Check the class definition or source code first
-- **Fail fast**: Write code with fail-fast logic by default. Do not swallow exceptions with errors or warnings
-- **No fallback logic**: Do not add fallback logic unless explicitly told to and agreed with the user
-- **No guessing**: Do not say "The issue is..." before you actually know what the issue is. Investigate first.
-
-### Literate Programming Style
-
-Code should tell a story. Comments must explain the "why" and narrative flow, not just the "what".
-
-**Section Headers:**
-For files with multiple phases of logic, add section headers so the control flow reads like chapters:
-```python
-# --- Authentication ---
-# ... auth logic ...
-
-# --- Data Validation ---
-# ... validation logic ...
-
-# --- Business Logic ---
-# ... core logic ...
-```
-
-**Decision Point Comments:**
-For conditionals that materially change behavior (gates, fallbacks, retries, feature flags), add comments with:
-- **Trigger**: what condition causes this branch
-- **Why**: the rationale (cost, correctness, UX, determinism)
-- **Outcome**: what changes downstream
-
-```python
-# Trigger: project has no active sync watcher
-# Why: avoid duplicate file system watchers consuming resources
-# Outcome: starts new watcher, registers in active_watchers dict
-if project_id not in active_watchers:
-    start_watcher(project_id)
-```
-
-**Constraint Comments:**
-If code exists because of a constraint (async requirements, rate limits, schema compatibility), explain the constraint near the code:
-```python
-# SQLite requires WAL mode for concurrent read/write access
-connection.execute("PRAGMA journal_mode=WAL")
-```
-
-**What NOT to Comment:**
-Avoid comments that restate obvious code:
-```python
-# Bad - restates code
-counter += 1  # increment counter
-
-# Good - explains why
-counter += 1  # track retries for backoff calculation
-```
-
-### Codebase Architecture
-
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture documentation.
-
-**Directory Structure:**
-- `/alembic` - Alembic db migrations
-- `/api` - FastAPI REST endpoints + `container.py` composition root
-- `/cli` - Typer CLI + `container.py` composition root
-- `/deps` - Feature-scoped FastAPI dependencies (config, db, projects, repositories, services, importers)
-- `/importers` - Import functionality for Claude, ChatGPT, and other sources
-- `/markdown` - Markdown parsing and processing
-- `/mcp` - MCP server + `container.py` composition root + `clients/` typed API clients
-- `/models` - SQLAlchemy ORM models
-- `/repository` - Data access layer
-- `/schemas` - Pydantic models for validation
-- `/services` - Business logic layer
-- `/sync` - File synchronization services + `coordinator.py` for lifecycle management
-
-**Composition Roots:**
-Each entrypoint (API, MCP, CLI) has a composition root that:
-- Reads `ConfigManager` (the only place that reads global config)
-- Resolves runtime mode via `RuntimeMode` enum (TEST > CLOUD > LOCAL)
-- Provides dependencies to downstream code explicitly
-
-**Typed API Clients (MCP):**
-MCP tools use typed clients in `mcp/clients/` to communicate with the API:
-- `KnowledgeClient` - Entity CRUD operations
-- `SearchClient` - Search operations
-- `MemoryClient` - Context building
-- `DirectoryClient` - Directory listing
-- `ResourceClient` - Resource reading
-- `ProjectClient` - Project management
-
-Flow: MCP Tool → Typed Client → HTTP API → Router → Service → Repository
-
-### Development Notes
-
-- MCP tools are defined in src/basic_memory/mcp/tools/
-- MCP prompts are defined in src/basic_memory/mcp/prompts/
-- MCP tools should be atomic, composable operations
-- Use `textwrap.dedent()` for multi-line string formatting in prompts and tools
-- MCP Prompts are used to invoke tools and format content with instructions for an LLM
-- Schema changes require Alembic migrations
-- SQLite is used for indexing and full text search, files are source of truth
-- Testing uses pytest with asyncio support (strict mode)
-- Unit tests (`tests/`) use mocks when necessary; integration tests (`test-int/`) use real implementations
-- By default, tests run against SQLite (fast, no Docker needed)
-- Set `BASIC_MEMORY_TEST_POSTGRES=1` to run against Postgres (uses testcontainers - Docker required)
-- Each test runs in a standalone environment with isolated database and tmp_path directory
-- CI runs SQLite and Postgres tests in parallel for faster feedback
-- Performance benchmarks are in `test-int/test_sync_performance_benchmark.py`
-- Use pytest markers: `@pytest.mark.benchmark` for benchmarks, `@pytest.mark.slow` for slow tests
-- **Coverage must stay at 100%**: Write tests for new code. Only use `# pragma: no cover` when tests would require excessive mocking (e.g., TYPE_CHECKING blocks, error handlers that need failure injection, runtime-mode-dependent code paths)
-
-### Async Client Pattern (Important!)
-
-**All MCP tools and CLI commands use the context manager pattern for HTTP clients:**
-
-```python
-from basic_memory.mcp.async_client import get_client
-
-async def my_mcp_tool():
-    async with get_client() as client:
-        # Use client for API calls
-        response = await call_get(client, "/path")
-        return response
-```
-
-**Do NOT use:**
-- ❌ `from basic_memory.mcp.async_client import client` (deprecated module-level client)
-- ❌ Manual auth header management
-- ❌ `inject_auth_header()` (deleted)
-
-**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)
-- Factory pattern enables dependency injection for cloud consolidation
-
-**For cloud app integration:**
-```python
-from basic_memory.mcp import async_client
-
-# Set custom factory before importing tools
-async_client.set_client_factory(your_custom_factory)
-```
-
-See SPEC-16 for full context manager refactor details.
-
-## BASIC MEMORY PRODUCT USAGE
-
-### Knowledge Structure
-
-- Entity: Any concept, document, or idea represented as a markdown file
-- Observation: A categorized fact about an entity (`- [category] content`)
-- Relation: A directional link between entities (`- relation_type [[Target]]`)
-- Frontmatter: YAML metadata at the top of markdown files
-- Knowledge representation follows precise markdown format:
-    - Observations with [category] prefixes
-    - Relations with WikiLinks [[Entity]]
-    - Frontmatter with metadata
-
-### Basic Memory Commands
-
-**Local Commands:**
-- Check sync status: `basic-memory status`
-- Import from Claude: `basic-memory import claude conversations`
-- Import from ChatGPT: `basic-memory import chatgpt`
-- Import from Memory JSON: `basic-memory import memory-json`
-- Tool access: `basic-memory tool` (provides CLI access to MCP tools)
-    - Continue: `basic-memory tool continue-conversation --topic="search"`
-
-**Project Management:**
-- List projects: `basic-memory project list`
-- Add project: `basic-memory project add "name" ~/path`
-- Project info: `basic-memory project info`
-- 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`
-- Check cloud status: `basic-memory cloud status`
-- Setup cloud sync: `basic-memory cloud setup`
-- Manage snapshots: `basic-memory cloud snapshot [create|list|delete|show|browse]`
-- Restore from snapshot: `basic-memory cloud restore <path> --snapshot <id>`
-
-### MCP Capabilities
-
-- Basic Memory exposes these MCP tools to LLMs:
-
-  **Content Management:**
-    - `write_note(title, content, folder, tags)` - Create/update markdown notes with semantic observations and relations
-    - `read_note(identifier, page, page_size)` - Read notes by title, permalink, or memory:// URL with knowledge graph awareness
-    - `read_content(path)` - Read raw file content (text, images, binaries) without knowledge graph processing
-    - `view_note(identifier, page, page_size)` - View notes as formatted artifacts for better readability
-    - `edit_note(identifier, operation, content)` - Edit notes incrementally (append, prepend, find/replace, replace_section)
-    - `move_note(identifier, destination_path)` - Move notes to new locations, updating database and maintaining links
-    - `delete_note(identifier)` - Delete notes from the knowledge base
-
-  **Knowledge Graph Navigation:**
-    - `build_context(url, depth, timeframe)` - Navigate the knowledge graph via memory:// URLs for conversation continuity
-    - `recent_activity(type, depth, timeframe)` - Get recently updated information with specified timeframe (e.g., "1d", "1 week")
-    - `list_directory(dir_name, depth, file_name_glob)` - Browse directory contents with filtering and depth control
-
-  **Search & Discovery:**
-    - `search_notes(query, page, page_size, search_type, types, entity_types, after_date)` - Full-text search across all content with advanced filtering options
-
-  **Project Management:**
-    - `list_memory_projects()` - List all available projects with their status
-    - `create_memory_project(project_name, project_path, set_default)` - Create new Basic Memory projects
-    - `delete_project(project_name)` - Delete a project from configuration
-
-  **Visualization:**
-    - `canvas(nodes, edges, title, folder)` - Generate Obsidian canvas files for knowledge graph visualization
-
-  **ChatGPT-Compatible Tools:**
-    - `search(query)` - Search across knowledge base (OpenAI actions compatible)
-    - `fetch(id)` - Fetch full content of a search result document
-
-- MCP Prompts for better AI interaction:
-    - `ai_assistant_guide()` - Guidance on effectively using Basic Memory tools for AI assistants
-    - `continue_conversation(topic, timeframe)` - Continue previous conversations with relevant historical context
-    - `search(query, after_date)` - Search with detailed, formatted results for better context understanding
-    - `recent_activity(timeframe)` - View recently changed items with formatted output
-
-### Cloud Features (v0.15.0+)
-
-Basic Memory now supports cloud synchronization and storage (requires active subscription):
-
-**Authentication:**
-- JWT-based authentication with subscription validation
-- Secure session management with token refresh
-- Support for multiple cloud projects
-
-**Bidirectional Sync:**
-- rclone bisync integration for two-way synchronization
-- Conflict resolution and integrity verification
-- Real-time sync with change detection
-- Mount/unmount cloud storage for direct file access
-
-**Cloud Project Management:**
-- Create and manage projects in the cloud
-- Toggle between local and cloud modes
-- Per-project sync configuration
-- Subscription-based access control
-
-**Security & Performance:**
-- Removed .env file loading for improved security
-- .gitignore integration (respects gitignored files)
-- WAL mode for SQLite performance
-- Background relation resolution (non-blocking startup)
-- API performance optimizations (SPEC-11)
-
-## AI-Human Collaborative Development
-
-Basic Memory emerged from and enables a new kind of development process that combines human and AI capabilities. Instead
-of using AI just for code generation, we've developed a true collaborative workflow:
-
-1. AI (LLM) writes initial implementation based on specifications and context
-2. Human reviews, runs tests, and commits code with any necessary adjustments
-3. Knowledge persists across conversations using Basic Memory's knowledge graph
-4. Development continues seamlessly across different AI sessions with consistent context
-5. Results improve through iterative collaboration and shared understanding
-
-This approach has allowed us to tackle more complex challenges and build a more robust system than either humans or AI
-could achieve independently.
-
-**Problem-Solving Guidance:**
-- If a solution isn't working after reasonable effort, suggest alternative approaches
-- Don't persist with a problematic library or pattern when better alternatives exist
-- Example: When py-pglite caused cascading test failures, switching to testcontainers-postgres was the right call
-
-## GitHub Integration
-
-Basic Memory has taken AI-Human collaboration to the next level by integrating Claude directly into the development workflow through GitHub:
-
-### GitHub MCP Tools
-
-Using the GitHub Model Context Protocol server, Claude can now:
-
-- **Repository Management**:
-  - View repository files and structure
-  - Read file contents
-  - Create new branches
-  - Create and update files
-
-- **Issue Management**:
-  - Create new issues
-  - Comment on existing issues
-  - Close and update issues
-  - Search across issues
-
-- **Pull Request Workflow**:
-  - Create pull requests
-  - Review code changes
-  - Add comments to PRs
-
-This integration enables Claude to participate as a full team member in the development process, not just as a code generation tool. Claude's GitHub account ([bm-claudeai](https://github.com/bm-claudeai)) is a member of the Basic Machines organization with direct contributor access to the codebase.
-
-### Collaborative Development Process
-
-With GitHub integration, the development workflow includes:
-
-1. **Direct code review** - Claude can analyze PRs and provide detailed feedback
-2. **Contribution tracking** - All of Claude's contributions are properly attributed in the Git history
-3. **Branch management** - Claude can create feature branches for implementations
-4. **Documentation maintenance** - Claude can keep documentation updated as the code evolves
-5. **Code Commits**: ALWAYS sign off commits with `git commit -s`
-
-This level of integration represents a new paradigm in AI-human collaboration, where the AI assistant becomes a full-fledged team member rather than just a tool for generating code snippets.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

NOTE-FORMAT.md

@@ -0,0 +1,494 @@
+# Note Format Reference
+
+Every document in Basic Memory is a plain Markdown file. Files are the source of truth — changes to files automatically update the knowledge graph in the database. You maintain complete ownership, files work with git, and knowledge persists independently of any AI conversation.
+
+## Document Structure
+
+A note has three parts: YAML frontmatter, content (observations), and relations.
+
+```markdown
+---
+title: Coffee Brewing Methods
+type: note
+tags: [coffee, brewing]
+permalink: coffee-brewing-methods
+---
+
+# Coffee Brewing Methods
+
+## Observations
+- [method] Pour over provides more flavor clarity than French press
+- [technique] Water temperature at 205°F extracts optimal compounds #brewing
+- [preference] Ethiopian beans work well with lighter roasts (personal experience)
+
+## Relations
+- relates_to [[Coffee Bean Origins]]
+- requires [[Proper Grinding Technique]]
+- contrasts_with [[Tea Brewing Methods]]
+```
+
+The `## Observations` and `## Relations` headings are conventional but not required — the parser detects observations and relations by their syntax patterns anywhere in the document.
+
+## Frontmatter
+
+YAML metadata between `---` fences at the top of the file.
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `title` | No | filename stem | Used for linking and references. Auto-set from filename if missing. |
+| `type` | No | `note` | Entity type. Used for schema resolution and filtering. |
+| `tags` | No | `[]` | List or comma-separated string. Used for organization and search. |
+| `permalink` | No | generated from title | Stable identifier. Persists even if the file moves. |
+| `schema` | No | none | Schema attachment — dict (inline), string (reference), or omitted (implicit). |
+
+Custom fields are allowed. Any key not in the standard set is stored as `entity_metadata` and indexed for search and filtering.
+
+```yaml
+---
+title: Paul Graham
+type: Person
+tags: [startups, essays, lisp]
+permalink: paul-graham
+status: active
+source: wikipedia
+---
+```
+
+Here `status` and `source` are custom fields stored in `entity_metadata`.
+
+### Frontmatter Value Handling
+
+YAML automatically converts some values to native types. Basic Memory normalizes them:
+
+- Date strings (`2025-10-24`) → kept as ISO format strings
+- Numbers (`1.0`) → converted to strings
+- Booleans (`true`) → converted to strings (`"True"`)
+- Lists and dicts → preserved, items normalized recursively
+
+This prevents errors when downstream code expects string values.
+
+## Observations
+
+An observation is a categorized fact about the entity. Written as a Markdown list item.
+
+**Syntax:**
+
+```
+- [category] content text #tag1 #tag2 (context)
+```
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `[category]` | Yes | Classification in square brackets. Any text except `[]()` chars. |
+| content | Yes | The fact or statement. |
+| `#tags` | No | Inline tags. Space-separated, each starting with `#`. |
+| `(context)` | No | Parenthesized text at end of line. Supporting details or source. |
+
+### Examples
+
+```markdown
+- [tech] Uses SQLite for storage #database
+- [design] Follows local-first architecture #architecture
+- [decision] Selected bcrypt for passwords #security (based on OWASP audit)
+- [name] Paul Graham
+- [expertise] Startups
+- [expertise] Lisp
+- [expertise] Essay writing
+```
+
+Array-like fields use repeated categories — multiple `[expertise]` observations above.
+
+### What Is Not an Observation
+
+The parser excludes these list item patterns:
+
+| Pattern | Example | Reason |
+|---------|---------|--------|
+| Checkboxes | `- [ ] Todo item`, `- [x] Done`, `- [-] Cancelled` | Task list syntax |
+| Markdown links | `- [text](url)` | URL link syntax |
+| Bare wiki links | `- [[Target]]` | Treated as a relation instead |
+
+A list item with `#tags` but no `[category]` is still parsed — the tags are extracted and the category defaults to `Note`.
+
+## Relations
+
+Relations connect documents to form the knowledge graph. There are two kinds.
+
+### Explicit Relations
+
+Written as list items with a relation type and a `[[wiki link]]` target.
+
+**Syntax:**
+
+```
+- relation_type [[Target Entity]] (context)
+```
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `relation_type` | No | Text before `[[`. Defaults to `relates_to` if omitted. |
+| `[[Target]]` | Yes | Wiki link to the target entity. Matched by title or permalink. |
+| `(context)` | No | Parenthesized text after `]]`. Supporting details. |
+
+### Examples
+
+```markdown
+- implements [[Search Design]]
+- depends_on [[Database Schema]]
+- works_at [[Y Combinator]] (co-founder)
+- [[Some Entity]]
+```
+
+The last example — a bare `[[wiki link]]` in a list item — gets relation type `relates_to`.
+
+Common relation types:
+- `implements`, `depends_on`, `relates_to`, `inspired_by`
+- `extends`, `part_of`, `contains`, `pairs_with`
+- `works_at`, `authored`, `collaborated_with`
+
+Any text works as a relation type. These are conventions, not a fixed set.
+
+### Inline References
+
+Wiki links appearing in regular prose (not as list items) create implicit `links_to` relations.
+
+```markdown
+This builds on [[Core Design]] and uses [[Utility Functions]].
+```
+
+This creates two relations: `links_to [[Core Design]]` and `links_to [[Utility Functions]]`.
+
+### Forward References
+
+Relations can link to entities that don't exist yet. Basic Memory resolves them when the target is created.
+
+## Permalinks and memory:// URLs
+
+Every document has a unique **permalink** — a stable identifier derived from its title. You can set one explicitly in frontmatter, or let the system generate it.
+
+```yaml
+permalink: auth-approaches-2024
+```
+
+Permalinks form the basis of `memory://` URLs:
+
+```
+memory://auth-approaches-2024        # By permalink
+memory://Authentication Approaches   # By title (auto-resolves)
+memory://project/auth-approaches     # By path
+```
+
+Pattern matching is supported:
+
+```
+memory://auth*                       # Starts with "auth"
+memory://*/approaches                # Ends with "approaches"
+memory://project/*/requirements      # Nested wildcard
+```
+
+## Schemas
+
+Schemas declare the expected structure of a note — which observation categories and relation types a well-formed note should have. They use Picoschema, a compact notation from Google's Dotprompt that fits naturally in YAML frontmatter.
+
+### Picoschema Syntax
+
+```yaml
+schema:
+  name: string, full name              # required field with description
+  email?: string, contact email        # ? = optional
+  role?: string, job title
+  works_at?: Organization, employer    # capitalized type = entity reference
+  tags?(array): string, categories     # array of type
+  status?(enum): [active, inactive]    # enum with allowed values
+  metadata?(object):                   # nested object
+    updated_at?: string
+    source?: string
+```
+
+| Notation | Meaning | Example |
+|----------|---------|---------|
+| `field: type` | Required field | `name: string` |
+| `field?: type` | Optional field | `role?: string` |
+| `field(array): type` | Array of values | `expertise(array): string` |
+| `field?(enum): [vals]` | Enum with allowed values | `status?(enum): [active, inactive]` |
+| `field?(object):` | Nested object with sub-fields | `metadata?(object):` |
+| `, description` | Description after comma | `name: string, full name` |
+| `EntityName` | Capitalized type = entity reference | `works_at?: Organization` |
+
+**Scalar types:** `string`, `integer`, `number`, `boolean`, `any`
+
+Any type not in that set whose first letter is uppercase is treated as an entity reference (a relation target).
+
+### Schema-to-Note Mapping
+
+Schemas validate against existing observation/relation syntax. Note authors don't learn new syntax.
+
+| Schema Declaration | Maps To | Example in Note |
+|--------------------|---------|-----------------|
+| `field: string` | Observation `[field] value` | `- [name] Paul Graham` |
+| `field?(array): string` | Multiple `[field]` observations | `- [expertise] Lisp` (repeated) |
+| `field?: EntityType` | Relation `field [[Target]]` | `- works_at [[Y Combinator]]` |
+| `field?(array): EntityType` | Multiple `field` relations | `- authored [[Book]]` (repeated) |
+| `tags` | Frontmatter `tags` array | `tags: [startups, essays]` |
+| `field?(enum): [vals]` | Observation `[field] value` where value is in the set | `- [status] active` |
+
+Observations and relations not covered by the schema are valid — schemas describe a subset, not a straitjacket.
+
+### Schema Attachment
+
+Three ways to attach a schema to a note, resolved in priority order:
+
+**1. Inline schema** — `schema` is a dict in frontmatter:
+
+```yaml
+---
+title: Team Standup 2024-01-15
+type: meeting
+schema:
+  attendees(array): string, who was there
+  decisions(array): string, what was decided
+  action_items(array): string, follow-ups
+  blockers?(array): string, anything stuck
+---
+```
+
+Good for one-off structured notes or prototyping a schema before extracting it.
+
+**2. Explicit reference** — `schema` is a string naming a schema note:
+
+```yaml
+---
+title: Basic Memory
+schema: SoftwareProject
+---
+```
+
+or by permalink:
+
+```yaml
+---
+title: LLM Memory Patterns
+schema: schema/research-project
+---
+```
+
+Use when the note's `type` differs from the schema it should validate against, or when multiple schema variants exist.
+
+**3. Implicit by type** — no `schema` field, resolved by matching `type`:
+
+```yaml
+---
+title: Paul Graham
+type: Person
+---
+```
+
+The system looks up a schema note where `entity: Person`. If found, it applies. If not, no validation occurs.
+
+**4. No schema** — perfectly fine. Most notes don't need one.
+
+### Schema Notes
+
+A schema is itself a Basic Memory note with `type: schema`. It lives anywhere (though `schema/` is the conventional directory).
+
+```yaml
+# schema/Person.md
+---
+title: Person
+type: schema
+entity: Person
+version: 1
+schema:
+  name: string, full name
+  role?: string, job title or position
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+settings:
+  validation: warn
+---
+
+# Person
+
+A human individual in the knowledge graph.
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Must be `schema` |
+| `entity` | Yes | The entity type this schema describes (e.g., `Person`) |
+| `version` | No | Schema version number (default: `1`) |
+| `schema` | Yes | Picoschema dict defining the fields |
+| `settings.validation` | No | Validation mode (default: `warn`) |
+
+Schema notes are regular notes — they show up in search, can have observations and relations, and participate in the knowledge graph.
+
+### Validation Modes
+
+| Mode | Behavior |
+|------|----------|
+| `warn` | Warnings in output, doesn't block (default) |
+| `strict` | Errors that block sync, for CI/CD enforcement |
+| `off` | No validation |
+
+### Validation Output
+
+```
+$ bm schema validate people/ada-lovelace.md
+
+⚠ Person schema validation:
+  - Missing required field: name (expected [name] observation)
+  - Missing optional field: role
+  - Missing optional field: works_at (no relation found)
+
+ℹ Unmatched observations: [fact] ×2, [born] ×1
+ℹ Unmatched relations: collaborated_with
+```
+
+"Unmatched" items are informational — observations and relations the schema doesn't cover.
+
+### Schema Inference
+
+Generate schemas from existing notes by analyzing observation and relation frequency:
+
+```
+$ bm schema infer Person
+
+Analyzing 30 notes with type: Person...
+
+Observations found:
+  [name]        30/30  100%  → name: string
+  [role]        27/30   90%  → role?: string
+  [expertise]   18/30   60%  → expertise?(array): string
+  [email]        8/30   27%  → email?: string
+
+Relations found:
+  works_at      22/30   73%  → works_at?: Organization
+
+Suggested schema:
+  name: string, full name
+  role?: string, job title
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+  works_at?: Organization, employer
+
+Save to schema/Person.md? [y/n]
+```
+
+Frequency thresholds:
+- **100% present** → required field
+- **25%+ present** → optional field
+- **Below 25%** → excluded from suggestion
+
+### Schema Drift Detection
+
+Track how usage patterns shift over time:
+
+```
+$ bm schema diff Person
+
+Schema drift detected:
+
++ expertise: now in 81% of notes (was 12%)
+- department: dropped to 3% of notes
+~ works_at: cardinality changed (one → many)
+
+Update schema? [y/n/review]
+```
+
+## Complete Examples
+
+### Simple Note (No Schema)
+
+```markdown
+---
+title: Project Ideas
+type: note
+tags: [ideas, brainstorm]
+---
+
+# Project Ideas
+
+## Observations
+- [idea] Build a CLI tool for markdown linting #tooling
+- [idea] Create a recipe knowledge base #cooking
+- [priority] Focus on developer tools first (Q1 goal)
+
+## Relations
+- inspired_by [[Developer Workflow Research]]
+- part_of [[Q1 Planning]]
+```
+
+### Schema-Validated Note
+
+Schema at `schema/Person.md`:
+
+```yaml
+---
+title: Person
+type: schema
+entity: Person
+version: 1
+schema:
+  name: string, full name
+  role?: string, job title or position
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+settings:
+  validation: warn
+---
+
+# Person
+
+A human individual in the knowledge graph.
+```
+
+Note at `people/paul-graham.md`:
+
+```markdown
+---
+title: Paul Graham
+type: Person
+tags: [startups, essays, lisp]
+---
+
+# Paul Graham
+
+## Observations
+- [name] Paul Graham
+- [role] Essayist and investor
+- [expertise] Startups
+- [expertise] Lisp
+- [expertise] Essay writing
+- [fact] Created Viaweb, the first web app
+
+## Relations
+- works_at [[Y Combinator]]
+- authored [[Hackers and Painters]]
+```
+
+The `[fact]` observation and `authored` relation are not in the schema — they're valid, just unmatched. The schema only checks that `[name]` exists (required) and looks for optional fields like `[role]`, `[expertise]`, and `works_at`.
+
+### Inline Schema Note
+
+```markdown
+---
+title: Team Standup 2024-01-15
+type: meeting
+schema:
+  attendees(array): string, who was there
+  decisions(array): string, what was decided
+  action_items(array): string, follow-ups
+  blockers?(array): string, anything stuck
+---
+
+# Team Standup 2024-01-15
+
+## Observations
+- [attendees] Paul
+- [attendees] Sarah
+- [decisions] Ship v2 by Friday
+- [action_items] Paul to review PR #42
+- [blockers] Waiting on API credentials
+```

README.md

@@ -9,11 +9,11 @@
 
 ## 🚀 Basic Memory Cloud is Live!
 
-- **Cross-device and multi-platform support is here.** Your knowledge graph now works on desktop, web, and mobile - seamlessly synced across all your AI tools (Claude, ChatGPT, Gemini, Claude Code, and Codex) 
-- **Early Supporter Pricing:** Early users get 25% off forever. 
-The open source project continues as always. Cloud just makes it work everywhere.
+- **Cross-device and multi-platform support is here.** Your knowledge graph now works on desktop, web, and mobile.
+- **Cloud is optional.** The local-first open-source workflow continues as always.
+- **OSS discount:** use code `BMFOSS` for 20% off for 3 months.
 
-[Sign up now →](https://basicmemory.com)
+[Sign up now →](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
 
 with a 7 day free trial
 
@@ -23,8 +23,21 @@ Basic Memory lets you build persistent knowledge through natural conversations w
 Claude, while keeping everything in simple Markdown files on your computer. It uses the Model Context Protocol (MCP) to
 enable any compatible LLM to read and write to your local knowledge base.
 
-- Website: https://basicmemory.com
-- Documentation: https://docs.basicmemory.com
+## What's New in v0.19.0
+
+- **Semantic Vector Search** — find notes by meaning, not just keywords. Combines full-text and vector similarity for hybrid search with FastEmbed embeddings.
+- **Schema System** — infer, validate, and diff the structure of your knowledge base with `schema_infer`, `schema_validate`, and `schema_diff` tools.
+- **Per-Project Cloud Routing** — route individual projects through the cloud while others stay local, using API key authentication (`basic-memory project set-cloud`).
+- **FastMCP 3.0** — upgraded to FastMCP 3.0 with tool annotations for better client integration.
+- **CLI Overhaul** — JSON output mode (`--json`) for scripting, workspace-aware commands, and an htop-inspired project dashboard.
+- **Smarter Editing** — `edit_note` append/prepend auto-creates notes if they don't exist; `write_note` has an overwrite guard to prevent accidental data loss.
+- **Richer Search Results** — matched chunk text returned in search results for better context.
+
+See the full [CHANGELOG](CHANGELOG.md) for details.
+
+- Website: [basicmemory.com](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
+- Documentation: [docs.basicmemory.com](https://docs.basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme)
+- Community: [Discord](https://discord.gg/tyvKNccgqN?utm_source=github&utm_medium=referral&utm_campaign=readme)
 
 ## Pick up your conversation right where you left off
 
@@ -344,52 +357,120 @@ basic-memory sync --watch
 3. Cloud features (optional, requires subscription):
 
 ```bash
-# Authenticate with cloud
+# 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
+# Check cloud auth + health
+basic-memory cloud status
+```
 
-# Mount cloud storage
-basic-memory cloud mount
+**Per-Project Cloud Routing** (API key based):
+
+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)
+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 and route metadata
+basic-memory project list
+```
+
+`basic-memory cloud login` / `basic-memory cloud logout` are authentication commands. They do not change default CLI
+routing behavior.
+
+**Routing Flags**:
+
+Use routing flags to disambiguate command targets:
+
+```bash
+# 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 for this command
+basic-memory status --cloud
+basic-memory project info my-project --cloud
+basic-memory project ls --name main --cloud
+```
+
+No-flag behavior defaults to local when no project context is present.
+
+The local MCP server routes per transport: `--transport stdio` honors per-project routing
+(local or cloud), while `--transport streamable-http` and `--transport sse` always route locally.
+
+**CLI Note Editing (`tool edit-note`):**
+
+```bash
+# Append content
+basic-memory tool edit-note project-plan --operation append --content $'\n## Next Steps\n- Finalize rollout'
+
+# Find/replace with replacement count validation
+basic-memory tool edit-note docs/api --operation find_replace --find-text "v0.14.0" --content "v0.15.0" --expected-replacements 2
+
+# Replace a section body
+basic-memory tool edit-note docs/setup --operation replace_section --section "## Installation" --content $'Updated install steps\n- Run just install'
+
+# JSON metadata output for integrations
+basic-memory tool edit-note docs/setup --operation append --content $'\n- Added note' --format json
 ```
 
 4. In Claude Desktop, the LLM can now use these tools:
 
 **Content Management:**
 ```
-write_note(title, content, folder, tags) - Create or update notes
-read_note(identifier, page, page_size) - Read notes by title or permalink
+write_note(title, content, folder, tags, output_format="text"|"json") - Create or update notes
+read_note(identifier, page, page_size, output_format="text"|"json") - Read notes by title or permalink
 read_content(path) - Read raw file content (text, images, binaries)
 view_note(identifier) - View notes as formatted artifacts
-edit_note(identifier, operation, content) - Edit notes incrementally
-move_note(identifier, destination_path) - Move notes with database consistency
-delete_note(identifier) - Delete notes from knowledge base
+edit_note(identifier, operation, content, output_format="text"|"json") - Edit notes incrementally
+move_note(identifier, destination_path, output_format="text"|"json") - Move notes with database consistency
+delete_note(identifier, output_format="text"|"json") - Delete notes from knowledge base
 ```
 
 **Knowledge Graph Navigation:**
 ```
-build_context(url, depth, timeframe) - Navigate knowledge graph via memory:// URLs
-recent_activity(type, depth, timeframe) - Find recently updated information
+build_context(url, depth, timeframe, output_format="json"|"text") - Navigate knowledge graph via memory:// URLs
+recent_activity(type, depth, timeframe, output_format="text"|"json") - Find recently updated information
 list_directory(dir_name, depth) - Browse directory contents with filtering
 ```
 
 **Search & Discovery:**
 ```
 search(query, page, page_size) - Search across your knowledge base
+search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, project) - Search with filters (query is optional for filter-only searches)
 ```
 
 **Project Management:**
 ```
-list_memory_projects() - List all available projects
-create_memory_project(project_name, project_path) - Create new projects
+list_memory_projects(output_format="text"|"json") - List all available projects
+create_memory_project(project_name, project_path, output_format="text"|"json") - Create new projects
 get_current_project() - Show current project stats
 sync_status() - Check synchronization status
 ```
 
+`output_format` defaults to `"text"` for these tools, preserving current human-readable responses.
+`build_context` defaults to `"json"` and can be switched to `"text"` when compact markdown output is preferred.
+
+**Cloud Discovery (opt-in):**
+```
+cloud_info() - Show optional Cloud overview and setup guidance
+release_notes() - Show latest release notes
+```
+
 **Visualization:**
 ```
 canvas(nodes, edges, title, folder) - Generate knowledge visualizations
@@ -407,13 +488,38 @@ canvas(nodes, edges, title, folder) - Generate knowledge visualizations
 
 ## Futher info
 
-See the [Documentation](https://docs.basicmemory.com) for more info, including:
+See the [Documentation](https://docs.basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme) for more info, including:
 
-- [Complete User Guide](https://docs.basicmemory.com/user-guide/)
-- [CLI tools](https://docs.basicmemory.com/guides/cli-reference/)
-- [Cloud CLI and Sync](https://docs.basicmemory.com/guides/cloud-cli/)
-- [Managing multiple Projects](https://docs.basicmemory.com/guides/cli-reference/#project)
-- [Importing data from OpenAI/Claude Projects](https://docs.basicmemory.com/guides/cli-reference/#import)
+- [Complete User Guide](https://docs.basicmemory.com/user-guide/?utm_source=github&utm_medium=referral&utm_campaign=readme)
+- [CLI tools](https://docs.basicmemory.com/guides/cli-reference/?utm_source=github&utm_medium=referral&utm_campaign=readme)
+- [Cloud CLI and Sync](https://docs.basicmemory.com/guides/cloud-cli/?utm_source=github&utm_medium=referral&utm_campaign=readme)
+- [Managing multiple Projects](https://docs.basicmemory.com/guides/cli-reference/?utm_source=github&utm_medium=referral&utm_campaign=readme#project)
+- [Importing data from OpenAI/Claude Projects](https://docs.basicmemory.com/guides/cli-reference/?utm_source=github&utm_medium=referral&utm_campaign=readme#import)
+
+## Telemetry
+
+Basic Memory collects anonymous, minimal usage events to understand how the CLI-to-cloud conversion funnel performs. This helps us prioritize features and improve the product.
+
+**What we collect:**
+- Cloud promo impressions (when the promo banner is shown)
+- Cloud login attempts and outcomes
+- Promo opt-out events
+
+**What we do NOT collect:**
+- No file contents, note titles, or knowledge base data
+- No personally identifiable information (PII)
+- No IP address tracking or fingerprinting
+- No per-command or per-tool-call tracking
+
+Events are sent to our [Umami Cloud](https://umami.is) instance, an open-source, privacy-focused analytics platform. Events are fire-and-forget on a background thread — analytics never blocks or slows the CLI.
+
+**Opt out** by setting the environment variable:
+
+```bash
+export BASIC_MEMORY_NO_PROMOS=1
+```
+
+This disables both promo messages and all telemetry events.
 
 ## Logging
 
@@ -433,7 +539,11 @@ 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 |
+| `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) |
+| `BASIC_MEMORY_NO_PROMOS` | `false` | When `true`, disables cloud promo messages and telemetry |
 
 ### Examples
 
@@ -477,27 +587,47 @@ just test
 - `just test-int-postgres` - Run integration tests against Postgres
 - `just test-windows` - Run Windows-specific tests (auto-skips on other platforms)
 - `just test-benchmark` - Run performance benchmark tests
+- `just testmon` - Run tests impacted by recent changes (pytest-testmon)
+- `just test-smoke` - Run fast MCP end-to-end smoke test
+- `just fast-check` - Run fix/format/typecheck + impacted tests + smoke test
+- `just doctor` - Run local file <-> DB consistency checks with temp config
 
 **Postgres Testing:**
 
 Postgres tests use [testcontainers](https://testcontainers-python.readthedocs.io/) which automatically spins up a Postgres instance in Docker. No manual database setup required - just have Docker running.
 
+**Testmon Note:** When no files have changed, `just testmon` may collect 0 tests. That's expected and means no impacted tests were detected.
+
 **Test Markers:**
 
 Tests use pytest markers for selective execution:
 - `windows` - Windows-specific database optimizations
 - `benchmark` - Performance tests (excluded from default runs)
+- `smoke` - Fast MCP end-to-end smoke tests
 
 **Other Development Commands:**
 ```bash
 just install          # Install with dev dependencies
 just lint             # Run linting checks
 just typecheck        # Run type checking
+just typecheck-ty     # Run ty type checking (incremental supplement to pyright)
 just format           # Format code with ruff
+just fast-check       # Fast local loop (fix/format/typecheck + testmon + smoke)
+just doctor           # Local consistency check (temp config)
 just check            # Run all quality checks
 just migration "msg"  # Create database migration
 ```
 
+**Type Checking Strategy:**
+- `just typecheck` (Pyright) remains the primary, blocking type checker.
+- `just typecheck-ty` (Astral `ty`) is available as a supplemental checker while rules are adopted incrementally.
+- We recommend running both locally while reducing `ty` diagnostics over time.
+
+**Local Consistency Check:**
+```bash
+basic-memory doctor   # Verifies file <-> database sync in a temp project
+```
+
 See the [justfile](justfile) for the complete list of development commands.
 
 ## License
@@ -517,4 +647,4 @@ and submitting PRs.
  </picture>
 </a>
 
-Built with ♥️ by Basic Machines
+Built with ♥️ by [Basic Machines](https://basicmachines.co?utm_source=github&utm_medium=referral&utm_campaign=readme)

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,17 +96,20 @@ 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`,
+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
 
 ### Structure
@@ -214,15 +214,45 @@ Example tool using typed client:
 
 ```python
 @mcp.tool()
-async def search_notes(query: str, project: str | None = None) -> SearchResponse:
-    async with get_client() as client:
-        active_project = await get_active_project(client, project)
-
+async def search_notes(
+    query: str,
+    project: str | None = None,
+    metadata_filters: dict | None = None,
+    tags: list[str] | None = None,
+    status: str | None = None,
+) -> SearchResponse:
+    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
 
+        search_query = SearchQuery(
+            text=query,
+            metadata_filters=metadata_filters,
+            tags=tags,
+            status=status,
+        )
         search_client = SearchClient(client, active_project.external_id)
-        return await search_client.search(query)
+        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

docs/NOTE-FORMAT.md

@@ -0,0 +1,494 @@
+# Note Format Reference
+
+Every document in Basic Memory is a plain Markdown file. Files are the source of truth — changes to files automatically update the knowledge graph in the database. You maintain complete ownership, files work with git, and knowledge persists independently of any AI conversation.
+
+## Document Structure
+
+A note has three parts: YAML frontmatter, content (observations), and relations.
+
+```markdown
+---
+title: Coffee Brewing Methods
+type: note
+tags: [coffee, brewing]
+permalink: coffee-brewing-methods
+---
+
+# Coffee Brewing Methods
+
+## Observations
+- [method] Pour over provides more flavor clarity than French press
+- [technique] Water temperature at 205°F extracts optimal compounds #brewing
+- [preference] Ethiopian beans work well with lighter roasts (personal experience)
+
+## Relations
+- relates_to [[Coffee Bean Origins]]
+- requires [[Proper Grinding Technique]]
+- contrasts_with [[Tea Brewing Methods]]
+```
+
+The `## Observations` and `## Relations` headings are conventional but not required — the parser detects observations and relations by their syntax patterns anywhere in the document.
+
+## Frontmatter
+
+YAML metadata between `---` fences at the top of the file.
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `title` | No | filename stem | Used for linking and references. Auto-set from filename if missing. |
+| `type` | No | `note` | Entity type. Used for schema resolution and filtering. |
+| `tags` | No | `[]` | List or comma-separated string. Used for organization and search. |
+| `permalink` | No | generated from title | Stable identifier. Persists even if the file moves. |
+| `schema` | No | none | Schema attachment — dict (inline), string (reference), or omitted (implicit). |
+
+Custom fields are allowed. Any key not in the standard set is stored as `entity_metadata` and indexed for search and filtering.
+
+```yaml
+---
+title: Paul Graham
+type: Person
+tags: [startups, essays, lisp]
+permalink: paul-graham
+status: active
+source: wikipedia
+---
+```
+
+Here `status` and `source` are custom fields stored in `entity_metadata`.
+
+### Frontmatter Value Handling
+
+YAML automatically converts some values to native types. Basic Memory normalizes them:
+
+- Date strings (`2025-10-24`) → kept as ISO format strings
+- Numbers (`1.0`) → converted to strings
+- Booleans (`true`) → converted to strings (`"True"`)
+- Lists and dicts → preserved, items normalized recursively
+
+This prevents errors when downstream code expects string values.
+
+## Observations
+
+An observation is a categorized fact about the entity. Written as a Markdown list item.
+
+**Syntax:**
+
+```
+- [category] content text #tag1 #tag2 (context)
+```
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `[category]` | Yes | Classification in square brackets. Any text except `[]()` chars. |
+| content | Yes | The fact or statement. |
+| `#tags` | No | Inline tags. Space-separated, each starting with `#`. |
+| `(context)` | No | Parenthesized text at end of line. Supporting details or source. |
+
+### Examples
+
+```markdown
+- [tech] Uses SQLite for storage #database
+- [design] Follows local-first architecture #architecture
+- [decision] Selected bcrypt for passwords #security (based on OWASP audit)
+- [name] Paul Graham
+- [expertise] Startups
+- [expertise] Lisp
+- [expertise] Essay writing
+```
+
+Array-like fields use repeated categories — multiple `[expertise]` observations above.
+
+### What Is Not an Observation
+
+The parser excludes these list item patterns:
+
+| Pattern | Example | Reason |
+|---------|---------|--------|
+| Checkboxes | `- [ ] Todo item`, `- [x] Done`, `- [-] Cancelled` | Task list syntax |
+| Markdown links | `- [text](url)` | URL link syntax |
+| Bare wiki links | `- [[Target]]` | Treated as a relation instead |
+
+A list item with `#tags` but no `[category]` is still parsed — the tags are extracted and the category defaults to `Note`.
+
+## Relations
+
+Relations connect documents to form the knowledge graph. There are two kinds.
+
+### Explicit Relations
+
+Written as list items with a relation type and a `[[wiki link]]` target.
+
+**Syntax:**
+
+```
+- relation_type [[Target Entity]] (context)
+```
+
+| Part | Required | Description |
+|------|----------|-------------|
+| `relation_type` | No | Text before `[[`. Defaults to `relates_to` if omitted. |
+| `[[Target]]` | Yes | Wiki link to the target entity. Matched by title or permalink. |
+| `(context)` | No | Parenthesized text after `]]`. Supporting details. |
+
+### Examples
+
+```markdown
+- implements [[Search Design]]
+- depends_on [[Database Schema]]
+- works_at [[Y Combinator]] (co-founder)
+- [[Some Entity]]
+```
+
+The last example — a bare `[[wiki link]]` in a list item — gets relation type `relates_to`.
+
+Common relation types:
+- `implements`, `depends_on`, `relates_to`, `inspired_by`
+- `extends`, `part_of`, `contains`, `pairs_with`
+- `works_at`, `authored`, `collaborated_with`
+
+Any text works as a relation type. These are conventions, not a fixed set.
+
+### Inline References
+
+Wiki links appearing in regular prose (not as list items) create implicit `links_to` relations.
+
+```markdown
+This builds on [[Core Design]] and uses [[Utility Functions]].
+```
+
+This creates two relations: `links_to [[Core Design]]` and `links_to [[Utility Functions]]`.
+
+### Forward References
+
+Relations can link to entities that don't exist yet. Basic Memory resolves them when the target is created.
+
+## Permalinks and memory:// URLs
+
+Every document has a unique **permalink** — a stable identifier derived from its title. You can set one explicitly in frontmatter, or let the system generate it.
+
+```yaml
+permalink: auth-approaches-2024
+```
+
+Permalinks form the basis of `memory://` URLs:
+
+```
+memory://auth-approaches-2024        # By permalink
+memory://Authentication Approaches   # By title (auto-resolves)
+memory://project/auth-approaches     # By path
+```
+
+Pattern matching is supported:
+
+```
+memory://auth*                       # Starts with "auth"
+memory://*/approaches                # Ends with "approaches"
+memory://project/*/requirements      # Nested wildcard
+```
+
+## Schemas
+
+Schemas declare the expected structure of a note — which observation categories and relation types a well-formed note should have. They use Picoschema, a compact notation from Google's Dotprompt that fits naturally in YAML frontmatter.
+
+### Picoschema Syntax
+
+```yaml
+schema:
+  name: string, full name              # required field with description
+  email?: string, contact email        # ? = optional
+  role?: string, job title
+  works_at?: Organization, employer    # capitalized type = entity reference
+  tags?(array): string, categories     # array of type
+  status?(enum): [active, inactive]    # enum with allowed values
+  metadata?(object):                   # nested object
+    updated_at?: string
+    source?: string
+```
+
+| Notation | Meaning | Example |
+|----------|---------|---------|
+| `field: type` | Required field | `name: string` |
+| `field?: type` | Optional field | `role?: string` |
+| `field(array): type` | Array of values | `expertise(array): string` |
+| `field?(enum): [vals]` | Enum with allowed values | `status?(enum): [active, inactive]` |
+| `field?(object):` | Nested object with sub-fields | `metadata?(object):` |
+| `, description` | Description after comma | `name: string, full name` |
+| `EntityName` | Capitalized type = entity reference | `works_at?: Organization` |
+
+**Scalar types:** `string`, `integer`, `number`, `boolean`, `any`
+
+Any type not in that set whose first letter is uppercase is treated as an entity reference (a relation target).
+
+### Schema-to-Note Mapping
+
+Schemas validate against existing observation/relation syntax. Note authors don't learn new syntax.
+
+| Schema Declaration | Maps To | Example in Note |
+|--------------------|---------|-----------------|
+| `field: string` | Observation `[field] value` | `- [name] Paul Graham` |
+| `field?(array): string` | Multiple `[field]` observations | `- [expertise] Lisp` (repeated) |
+| `field?: EntityType` | Relation `field [[Target]]` | `- works_at [[Y Combinator]]` |
+| `field?(array): EntityType` | Multiple `field` relations | `- authored [[Book]]` (repeated) |
+| `tags` | Frontmatter `tags` array | `tags: [startups, essays]` |
+| `field?(enum): [vals]` | Observation `[field] value` where value is in the set | `- [status] active` |
+
+Observations and relations not covered by the schema are valid — schemas describe a subset, not a straitjacket.
+
+### Schema Attachment
+
+Three ways to attach a schema to a note, resolved in priority order:
+
+**1. Inline schema** — `schema` is a dict in frontmatter:
+
+```yaml
+---
+title: Team Standup 2024-01-15
+type: meeting
+schema:
+  attendees(array): string, who was there
+  decisions(array): string, what was decided
+  action_items(array): string, follow-ups
+  blockers?(array): string, anything stuck
+---
+```
+
+Good for one-off structured notes or prototyping a schema before extracting it.
+
+**2. Explicit reference** — `schema` is a string naming a schema note:
+
+```yaml
+---
+title: Basic Memory
+schema: SoftwareProject
+---
+```
+
+or by permalink:
+
+```yaml
+---
+title: LLM Memory Patterns
+schema: schema/research-project
+---
+```
+
+Use when the note's `type` differs from the schema it should validate against, or when multiple schema variants exist.
+
+**3. Implicit by type** — no `schema` field, resolved by matching `type`:
+
+```yaml
+---
+title: Paul Graham
+type: Person
+---
+```
+
+The system looks up a schema note where `entity: Person`. If found, it applies. If not, no validation occurs.
+
+**4. No schema** — perfectly fine. Most notes don't need one.
+
+### Schema Notes
+
+A schema is itself a Basic Memory note with `type: schema`. It lives anywhere (though `schema/` is the conventional directory).
+
+```yaml
+# schema/Person.md
+---
+title: Person
+type: schema
+entity: Person
+version: 1
+schema:
+  name: string, full name
+  role?: string, job title or position
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+settings:
+  validation: warn
+---
+
+# Person
+
+A human individual in the knowledge graph.
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | Must be `schema` |
+| `entity` | Yes | The entity type this schema describes (e.g., `Person`) |
+| `version` | No | Schema version number (default: `1`) |
+| `schema` | Yes | Picoschema dict defining the fields |
+| `settings.validation` | No | Validation mode (default: `warn`) |
+
+Schema notes are regular notes — they show up in search, can have observations and relations, and participate in the knowledge graph.
+
+### Validation Modes
+
+| Mode | Behavior |
+|------|----------|
+| `warn` | Warnings in output, doesn't block (default) |
+| `strict` | Errors that block sync, for CI/CD enforcement |
+| `off` | No validation |
+
+### Validation Output
+
+```
+$ bm schema validate people/ada-lovelace.md
+
+⚠ Person schema validation:
+  - Missing required field: name (expected [name] observation)
+  - Missing optional field: role
+  - Missing optional field: works_at (no relation found)
+
+ℹ Unmatched observations: [fact] ×2, [born] ×1
+ℹ Unmatched relations: collaborated_with
+```
+
+"Unmatched" items are informational — observations and relations the schema doesn't cover.
+
+### Schema Inference
+
+Generate schemas from existing notes by analyzing observation and relation frequency:
+
+```
+$ bm schema infer Person
+
+Analyzing 30 notes with type: Person...
+
+Observations found:
+  [name]        30/30  100%  → name: string
+  [role]        27/30   90%  → role?: string
+  [expertise]   18/30   60%  → expertise?(array): string
+  [email]        8/30   27%  → email?: string
+
+Relations found:
+  works_at      22/30   73%  → works_at?: Organization
+
+Suggested schema:
+  name: string, full name
+  role?: string, job title
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+  works_at?: Organization, employer
+
+Save to schema/Person.md? [y/n]
+```
+
+Frequency thresholds:
+- **100% present** → required field
+- **25%+ present** → optional field
+- **Below 25%** → excluded from suggestion
+
+### Schema Drift Detection
+
+Track how usage patterns shift over time:
+
+```
+$ bm schema diff Person
+
+Schema drift detected:
+
++ expertise: now in 81% of notes (was 12%)
+- department: dropped to 3% of notes
+~ works_at: cardinality changed (one → many)
+
+Update schema? [y/n/review]
+```
+
+## Complete Examples
+
+### Simple Note (No Schema)
+
+```markdown
+---
+title: Project Ideas
+type: note
+tags: [ideas, brainstorm]
+---
+
+# Project Ideas
+
+## Observations
+- [idea] Build a CLI tool for markdown linting #tooling
+- [idea] Create a recipe knowledge base #cooking
+- [priority] Focus on developer tools first (Q1 goal)
+
+## Relations
+- inspired_by [[Developer Workflow Research]]
+- part_of [[Q1 Planning]]
+```
+
+### Schema-Validated Note
+
+Schema at `schema/Person.md`:
+
+```yaml
+---
+title: Person
+type: schema
+entity: Person
+version: 1
+schema:
+  name: string, full name
+  role?: string, job title or position
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+settings:
+  validation: warn
+---
+
+# Person
+
+A human individual in the knowledge graph.
+```
+
+Note at `people/paul-graham.md`:
+
+```markdown
+---
+title: Paul Graham
+type: Person
+tags: [startups, essays, lisp]
+---
+
+# Paul Graham
+
+## Observations
+- [name] Paul Graham
+- [role] Essayist and investor
+- [expertise] Startups
+- [expertise] Lisp
+- [expertise] Essay writing
+- [fact] Created Viaweb, the first web app
+
+## Relations
+- works_at [[Y Combinator]]
+- authored [[Hackers and Painters]]
+```
+
+The `[fact]` observation and `authored` relation are not in the schema — they're valid, just unmatched. The schema only checks that `[name]` exists (required) and looks for optional fields like `[role]`, `[expertise]`, and `works_at`.
+
+### Inline Schema Note
+
+```markdown
+---
+title: Team Standup 2024-01-15
+type: meeting
+schema:
+  attendees(array): string, who was there
+  decisions(array): string, what was decided
+  action_items(array): string, follow-ups
+  blockers?(array): string, anything stuck
+---
+
+# Team Standup 2024-01-15
+
+## Observations
+- [attendees] Paul
+- [attendees] Sarah
+- [decisions] Ship v2 by Friday
+- [action_items] Paul to review PR #42
+- [blockers] Waiting on API credentials
+```

docs/SPEC-PER-PROJECT-ROUTING.md

@@ -0,0 +1,147 @@
+# Simplified Local/Cloud Routing
+
+## Context
+
+Basic Memory now uses explicit, project-aware routing without a global cloud-mode toggle.
+Routing is determined by command-level flags and project mode, not by a global `cloud_mode` state.
+
+This document is the canonical contract for local/cloud routing behavior in CLI, MCP, and API-adjacent clients.
+
+## Goals
+
+1. Remove global `cloud_mode` from runtime/routing semantics.
+2. Keep MCP HTTP/SSE local-only; let stdio honor per-project routing.
+3. Make CLI routing explicit and easy to reason about.
+4. Support projects that exist in both local and cloud without ambiguity.
+
+## Routing Contract
+
+Routing is resolved in this order:
+
+1. Injected client factory (for composition/integration contexts)
+2. Explicit routing override (`--local` / `--cloud` or env vars below)
+3. Project-scoped routing (`project.mode`) when a project is known
+4. Default local routing
+
+### Routing Environment Variables
+
+- `BASIC_MEMORY_FORCE_LOCAL=true`: force local transport
+- `BASIC_MEMORY_FORCE_CLOUD=true`: force cloud proxy transport
+- `BASIC_MEMORY_EXPLICIT_ROUTING=true`: marks routing as explicitly chosen for this command
+
+When explicit routing is active, project mode does not override the selected route.
+
+## Config Semantics
+
+- `project.mode` is the only config-based routing signal for project-scoped operations.
+- Legacy `cloud_mode` values may be encountered during migration/loading but are not used for routing behavior.
+- Normalization saves remove stale `cloud_mode` from `~/.basic-memory/config.json`.
+
+### Example Config
+
+```json
+{
+  "projects": {
+    "main": {
+      "path": "/Users/me/basic-memory",
+      "mode": "local",
+      "local_sync_path": null,
+      "bisync_initialized": false,
+      "last_sync": null
+    },
+    "specs": {
+      "path": "specs",
+      "mode": "cloud",
+      "local_sync_path": "/Users/me/dev/specs",
+      "bisync_initialized": true,
+      "last_sync": "2026-02-06T17:36:38.544153"
+    }
+  },
+  "default_project": "main",
+  "cloud_api_key": "bmc_abc123...",
+  "cloud_host": "https://cloud.basicmemory.com"
+}
+```
+
+## Cloud Commands Are Auth-Only
+
+`bm cloud login`, `bm cloud logout`, and `bm cloud status` manage authentication state.
+
+- `bm cloud login`
+  - performs OAuth device flow
+  - stores/refreshes token material
+  - may verify cloud health/subscription
+  - does not change routing defaults
+- `bm cloud logout`
+  - removes stored OAuth session tokens
+  - does not change routing defaults
+- `bm cloud status`
+  - reports auth state (API key, OAuth token validity)
+  - runs health checks only when credentials are available
+
+## MCP Transport Routing
+
+### Stdio (default)
+
+`bm mcp --transport stdio` uses natural per-project routing.
+
+- Local-mode projects route through the in-process ASGI transport.
+- Cloud-mode projects route to the cloud proxy with Bearer auth (API key).
+- No explicit routing env vars are injected by the CLI command.
+- Externally-set env vars are honored (e.g. `BASIC_MEMORY_FORCE_CLOUD=true` for cloud deployments).
+- Users who need all projects forced local can set `BASIC_MEMORY_FORCE_LOCAL=true` externally.
+
+### HTTP and SSE Transports
+
+`bm mcp --transport streamable-http` and `bm mcp --transport sse` always route locally.
+
+These transports set explicit local routing (`BASIC_MEMORY_FORCE_LOCAL=true` and
+`BASIC_MEMORY_EXPLICIT_ROUTING=true`) before starting the server. This prevents cloud
+routing regardless of project mode, since HTTP/SSE serve as local API endpoints.
+
+## Project List UX for Dual Presence
+
+Projects may exist in both local and cloud. `bm project list` should display that clearly in one row per logical
+project identity, with explicit source/target signals.
+
+Recommended display contract:
+
+1. Keep one row per normalized project name/permalink.
+2. Show both local and cloud presence as separate columns/indicators.
+3. Show an explicit `MCP (stdio)` target column that always resolves to `local`.
+4. Keep CLI route semantics explicit:
+   - no flags: default local for non-project commands
+   - `--cloud`: force cloud
+   - `--local`: force local
+
+## Project LS Targeting
+
+`bm project ls` should clearly identify which project instance is being listed.
+
+Targeting rules:
+
+1. No routing flags: list local project files.
+2. `--cloud`: list cloud project files.
+3. `--local`: list local project files (explicit override).
+4. Output should label the active target (`LOCAL` or `CLOUD`) in heading or status line.
+
+## Runtime Mode
+
+Runtime mode is no longer a cloud/local routing switch for local app flows.
+
+- `resolve_runtime_mode(is_test_env)` resolves to:
+  - `TEST` when running in test environment
+  - `LOCAL` otherwise
+- `RuntimeMode.CLOUD` may remain for compatibility with existing tests/call sites but is not selected by normal local
+  runtime resolution.
+
+## Verification Checklist
+
+1. Loading config with legacy `cloud_mode` succeeds.
+2. Saving config strips legacy `cloud_mode`.
+3. `--local/--cloud` always override per-project mode for that command.
+4. No-project + no-flags commands route local by default.
+5. `bm cloud login/logout` do not toggle routing behavior.
+6. `bm mcp` stdio routes per-project mode; HTTP/SSE remain local-forced.
+7. `bm project list` communicates dual local/cloud presence without ambiguity.
+8. `bm project ls` output identifies route target explicitly.

docs/ai-assistant-guide-extended.md

@@ -427,6 +427,8 @@ await write_note(
 )
 ```
 
+> **Important**: `write_note` errors if the note already exists. Use `edit_note` for incremental changes, or pass `overwrite=True` to replace.
+
 **Well-structured note**:
 
 ```python
@@ -760,6 +762,9 @@ notes = await read_note(
     identifier="memory://specs/*",
     project="main"
 )
+
+# Cross-project URL (auto-routes to the correct project)
+note = await read_note(identifier="memory://research/specs/api-design")
 ```
 
 ```python
@@ -1038,9 +1043,41 @@ recent_decisions = await search_notes(
 )
 ```
 
+**Structured frontmatter filters**:
+
+```python
+# Filter by tags and status
+results = await search_notes(
+    query="authentication",
+    tags=["security"],
+    status="in-progress",
+    project="main"
+)
+
+# Complex metadata filters (supports $in, $gt, $gte, $lt, $lte, $between)
+results = await search_notes(
+    query="api design",
+    metadata_filters={
+        "type": "spec",
+        "priority": {"$in": ["high", "critical"]},
+        "tags": ["architecture"]
+    },
+    project="main"
+)
+
+# Metadata-only search (no query needed)
+results = await search_notes(
+    metadata_filters={"type": "spec", "status": "in-progress"},
+    project="main"
+)
+```
+
 ### Search Types
 
-**Text search (default)**:
+Available types: `"text"`, `"title"`, `"permalink"`, `"vector"`/`"semantic"`, `"hybrid"`.
+Default is `"hybrid"` when semantic search is enabled, `"text"` otherwise.
+
+**Text search**:
 
 ```python
 # Full-text search across all content
@@ -1051,15 +1088,50 @@ results = await search_notes(
 )
 ```
 
-**Semantic search**:
+**Title and permalink search**:
+
+```python
+# Search by title only
+results = await search_notes(query="API Design", search_type="title", project="main")
+
+# Search by permalink
+results = await search_notes(query="specs/api-design", search_type="permalink", project="main")
+```
+
+**Semantic/vector search**:
 
 ```python
 # Semantic/vector search (if enabled)
 results = await search_notes(
     query="user login security",
-    search_type="semantic",
+    search_type="semantic",  # or "vector"
     project="main"
 )
+
+# Override similarity threshold
+results = await search_notes(
+    query="user login security",
+    search_type="semantic",
+    min_similarity=0.5,
+    project="main"
+)
+```
+
+**Hybrid search** (combines text + semantic):
+
+```python
+results = await search_notes(
+    query="authentication best practices",
+    search_type="hybrid",
+    project="main"
+)
+```
+
+**Tag shorthand in query**:
+
+```python
+# Use tag: prefix as shorthand
+results = await search_notes(query="tag:security", project="main")
 ```
 
 ### Search Response
@@ -2132,6 +2204,31 @@ active_project = projects[0]["name"]
 results = await search_notes(query="test", project=active_project)
 ```
 
+### Note Already Exists
+
+**Error**: `write_note` called for a note that already exists
+
+**Solution**:
+
+```python
+# Preferred: use edit_note for incremental updates
+await edit_note(
+    identifier="Existing Topic",
+    operation="append",
+    content="\n- [update] new information",
+    project="main"
+)
+
+# Alternative: replace the entire note
+await write_note(
+    title="Existing Topic",
+    content="# Existing Topic\n...",
+    folder="notes",
+    overwrite=True,
+    project="main"
+)
+```
+
 ### Entity Not Found
 
 **Error**: Note doesn't exist
@@ -2687,14 +2784,15 @@ await write_note(
 
 ### Content Management
 
-**write_note(title, content, folder, tags, note_type, project)**
-- Create or update markdown notes
+**write_note(title, content, folder, tags, note_type, overwrite, project)**
+- Create new markdown notes (errors if note already exists unless overwrite=True)
 - Parameters:
   - `title` (required): Note title
   - `content` (required): Markdown content
   - `folder` (required): Destination folder
   - `tags` (optional): List of tags
   - `note_type` (optional): Type of note (stored in frontmatter). Can be "note", "person", "meeting", "guide", etc.
+  - `overwrite` (optional): Set to True to replace an existing note (default: error if exists)
   - `project` (required unless default_project_mode): Target project
 - Returns: Created/updated entity with permalink
 - Example:
@@ -2861,16 +2959,20 @@ contents = await list_directory(
 
 ### Search & Discovery
 
-**search_notes(query, page, page_size, search_type, types, entity_types, after_date, project)**
+**search_notes(query, page, page_size, search_type, types, entity_types, after_date, metadata_filters, tags, status, min_similarity, project)**
 - Search across knowledge base
 - Parameters:
-  - `query` (required): Search query
+  - `query` (optional): Search query (not required for filter-only searches)
   - `page` (optional): Page number (default: 1)
   - `page_size` (optional): Results per page (default: 10)
-  - `search_type` (optional): "text" or "semantic"
+  - `search_type` (optional): "text", "title", "permalink", "vector"/"semantic", "hybrid" (default: "hybrid" when semantic enabled, "text" otherwise)
   - `types` (optional): Entity type filter
   - `entity_types` (optional): Observation category filter
   - `after_date` (optional): Date filter (ISO format)
+  - `metadata_filters` (optional): Structured frontmatter filters (dict, supports `$in`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` operators)
+  - `tags` (optional): Frontmatter tags filter (list); also available via `tag:` query shorthand
+  - `status` (optional): Frontmatter status filter (string)
+  - `min_similarity` (optional): Override similarity threshold for vector/hybrid search
   - `project` (required unless default_project_mode): Target project
 - Returns: Matching entities with scores
 - Example:
@@ -2883,6 +2985,15 @@ results = await search_notes(
 )
 ```
 
+**Metadata-only search (via search_notes)**
+- Use `search_notes` with `metadata_filters` and no `query` for metadata-only searches:
+```python
+results = await search_notes(
+    metadata_filters={"type": "spec", "status": "in-progress"},
+    project="main"
+)
+```
+
 ### Project Management
 
 **list_memory_projects()**
@@ -2930,6 +3041,15 @@ await delete_project(project_name="old-project")
 status = await sync_status(project="main")
 ```
 
+**list_workspaces()**
+- List available workspaces (cloud)
+- Parameters: None
+- Returns: List of workspaces with metadata
+- Example:
+```python
+workspaces = await list_workspaces()
+```
+
 ### Visualization
 
 **canvas(nodes, edges, title, folder, project)**
@@ -3198,8 +3318,8 @@ await edit_note(
     project="main"
 )
 
-# Avoid: Complete rewrite
-# (unless necessary for major restructuring)
+# When full rewrite is needed, use overwrite=True
+await write_note(title="Note", content="...", folder="notes", overwrite=True)
 ```
 
 ### 14. Tagging Strategy

docs/cloud-cli.md

@@ -5,7 +5,7 @@ The Basic Memory Cloud CLI provides seamless integration between local and cloud
 ## Overview
 
 The cloud CLI enables you to:
-- **Toggle cloud mode** - All regular `bm` commands work with cloud when enabled
+- **Authenticate cloud access** - OAuth/API key credentials are stored locally for cloud operations
 - **Project-scoped sync** - Each project independently manages its sync configuration
 - **Explicit operations** - Sync only what you want, when you want
 - **Bidirectional sync** - Keep local and cloud in sync with rclone bisync
@@ -17,6 +17,8 @@ Before using Basic Memory Cloud, you need:
 
 - **Active Subscription**: An active Basic Memory Cloud subscription is required to access cloud features
 - **Subscribe**: Visit [https://basicmemory.com/subscribe](https://basicmemory.com/subscribe) to sign up
+- **Optional**: Cloud is optional. Local-first open-source usage continues without cloud.
+- **OSS Discount**: Use code `{{OSS_DISCOUNT_CODE}}` for 20% off for 3 months.
 
 If you attempt to log in without an active subscription, you'll receive a "Subscription Required" error with a link to subscribe.
 
@@ -38,7 +40,7 @@ If you attempt to log in without an active subscription, you'll receive a "Subsc
 
 1. **Cloud-only** - Project exists on cloud, no local copy
 2. **Cloud + Local (synced)** - Project has a local working directory that syncs
-3. **Local-only** - Project exists locally (when cloud mode is disabled)
+3. **Local-only** - Project exists locally and is not routed to cloud
 
 **Example:**
 
@@ -48,9 +50,9 @@ If you attempt to log in without an active subscription, you'll receive a "Subsc
 # - work: wants local sync at ~/work-notes
 # - temp: cloud-only, no local sync needed
 
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work-notes
-bm project add temp  # No local sync
+bm project add research --cloud --local-path ~/Documents/research
+bm project add work --cloud --local-path ~/work-notes
+bm project add temp --cloud  # No local sync
 
 # Now you can sync individually (after initial --resync):
 bm project bisync --name research
@@ -66,9 +68,9 @@ bm project bisync --name work
 
 ## Quick Start
 
-### 1. Enable Cloud Mode
+### 1. Authenticate Cloud Access
 
-Authenticate and enable cloud mode:
+Authenticate with cloud:
 
 ```bash
 bm cloud login
@@ -76,11 +78,12 @@ bm cloud login
 
 **What this does:**
 1. Opens browser to Basic Memory Cloud authentication page
-2. Stores authentication token in `~/.basic-memory/auth/token`
-3. **Enables cloud mode** - all CLI commands now work against cloud
-4. Validates your subscription status
+2. Stores authentication tokens in `~/.basic-memory/basic-memory-cloud.json`
+3. Validates your subscription status
+4. Leaves routing behavior unchanged (auth only)
 
-**Result:** All `bm project`, `bm tools` commands now work with cloud.
+**Result:** Cloud credentials are available for cloud-routed commands.
+Apply OSS discount code `{{OSS_DISCOUNT_CODE}}` during checkout to receive 20% off for 3 months.
 
 ### 2. Set Up Sync
 
@@ -104,10 +107,10 @@ Create projects with optional local sync paths:
 
 ```bash
 # Create cloud project without local sync
-bm project add research
+bm project add research --cloud
 
 # Create cloud project WITH local sync
-bm project add research --local-path ~/Documents/research
+bm project add research --cloud --local-path ~/Documents/research
 
 # Or configure sync for existing project
 bm project sync-setup research ~/Documents/research
@@ -117,7 +120,7 @@ bm project sync-setup research ~/Documents/research
 
 When you add a project with `--local-path`:
 1. Project created on cloud at `/app/data/research`
-2. Local path stored in config: `cloud_projects.research.local_path = "~/Documents/research"`
+2. Local path stored in config for that project (`local_sync_path`)
 3. Local directory created if it doesn't exist
 4. Bisync state directory created at `~/.basic-memory/bisync-state/research/`
 
@@ -179,7 +182,8 @@ bm cloud status
 ```
 
 You should see:
-- `Mode: Cloud (enabled)`
+- `OAuth: token valid` (or missing/expired)
+- `API Key: configured` (or not set)
 - `Cloud instance is healthy`
 - Instructions for project sync commands
 
@@ -187,16 +191,16 @@ You should see:
 
 ### Understanding Project Commands
 
-**Key concept:** When cloud mode is enabled, use regular `bm project` commands (not `bm cloud project`).
+**Key concept:** Use regular `bm project` commands (not `bm cloud project`).
 
 ```bash
-# In cloud mode:
-bm project list              # Lists cloud projects
-bm project add research      # Creates cloud project
+# Local route
+bm project list --local
+bm project add research ~/Documents/research
 
-# In local mode:
-bm project list              # Lists local projects
-bm project add research ~/Documents/research  # Creates local project
+# Cloud route
+bm project list --cloud
+bm project add research --cloud
 ```
 
 ### Creating Projects
@@ -204,7 +208,7 @@ bm project add research ~/Documents/research  # Creates local project
 **Use case 1: Cloud-only project (no local sync)**
 
 ```bash
-bm project add temp-notes
+bm project add temp-notes --cloud
 ```
 
 **What this does:**
@@ -217,7 +221,7 @@ bm project add temp-notes
 **Use case 2: Cloud project with local sync**
 
 ```bash
-bm project add research --local-path ~/Documents/research
+bm project add research --cloud --local-path ~/Documents/research
 ```
 
 **What this does:**
@@ -251,11 +255,35 @@ bm project list
 ```
 
 **What you see:**
-- All projects in cloud (when cloud mode enabled)
+- Local projects always
+- Cloud projects when credentials are available
 - Default project marked
-- Project paths shown
+- Route-related metadata (for example, local/cloud presence and sync info)
 
-**Future:** Will show sync status (synced/not synced, last sync time).
+Example shape (single row for dual-presence projects):
+
+```text
+Name   Path            Local Path           Cloud Path   CLI Default   MCP (stdio)
+main   /basic-memory   ~/basic-memory       /basic-memory   local       local
+specs  /specs          ~/dev/specs          /specs          cloud       local
+```
+
+### When a Project Exists in Both Local and Cloud
+
+Use routing flags to disambiguate command targets:
+
+```bash
+# Force local target for this command
+bm project info main --local
+bm project ls --name main --local
+
+# Force cloud target for this command
+bm project info main --cloud
+bm project ls --name main --cloud
+```
+
+Default behavior for no-project, no-flag commands is local.
+For MCP stdio, routing is always local.
 
 ## File Synchronization
 
@@ -363,24 +391,28 @@ bm project bisync --name research --dry-run
 
 **Result:** Safe preview of sync operations.
 
-### Advanced: List Remote Files
+### Advanced: List Project Files by Route
 
-**Use case:** See what files exist on cloud without syncing.
+**Use case:** Inspect local or cloud project files explicitly.
 
 ```bash
-# List all files in project
+# List local project files (default target when no route flag is given)
 bm project ls --name research
+bm project ls --name research --local
+
+# List cloud project files
+bm project ls --name research --cloud
 
 # List files in subdirectory
-bm project ls --name research --path subfolder
+bm project ls --name research --cloud --path subfolder
 ```
 
 **What happens:**
-1. Connects to cloud via rclone
-2. Lists files in remote project path
+1. Resolves route from flags (or local default when no route is given)
+2. Lists files for the chosen project instance
 3. No files transferred
 
-**Result:** See cloud file listing.
+**Result:** See file listing for the target route.
 
 ## Multiple Projects
 
@@ -390,9 +422,9 @@ bm project ls --name research --path subfolder
 
 ```bash
 # Setup multiple projects
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work-notes
-bm project add personal --local-path ~/personal
+bm project add research --cloud --local-path ~/Documents/research
+bm project add work --cloud --local-path ~/work-notes
+bm project add personal --cloud --local-path ~/personal
 
 # Establish baselines
 bm project bisync --name research --resync
@@ -417,12 +449,12 @@ bm project bisync --all  # Coming soon
 
 ```bash
 # Projects with sync
-bm project add research --local-path ~/Documents/research
-bm project add work --local-path ~/work
+bm project add research --cloud --local-path ~/Documents/research
+bm project add work --cloud --local-path ~/work
 
 # Cloud-only projects
-bm project add archive
-bm project add temp-notes
+bm project add archive --cloud
+bm project add temp-notes --cloud
 
 # Sync only the configured ones
 bm project bisync --name research
@@ -433,20 +465,101 @@ bm project bisync --name work
 
 **Result:** Fine-grained control over what syncs.
 
-## Disable Cloud Mode
+## Per-Project Cloud Routing (API Key)
 
-Return to local mode:
+Route individual projects through cloud using an API key. This lets you keep some projects local while others route through cloud.
+
+### Setting Up API Key Auth
+
+**Option A: Create a key in the web app, then save it locally:**
+
+```bash
+bm cloud set-key bmc_abc123...
+```
+
+**Option B: Create a key via CLI (requires OAuth login first):**
+
+```bash
+bm cloud login                     # One-time OAuth login
+bm cloud create-key "my-laptop"    # Creates key and saves it locally
+```
+
+The API key is account-level — it grants access to all your cloud projects. It's stored in `~/.basic-memory/config.json` as `cloud_api_key`.
+
+### Setting Project Modes
+
+```bash
+# Route a project through cloud
+bm project set-cloud research
+
+# Revert to local mode
+bm project set-local research
+
+# View project modes
+bm project list
+```
+
+**What happens:**
+- `set-cloud`: validates the API key exists, then sets the project mode to `cloud` in config
+- `set-local`: reverts the project to local mode (removes the mode entry from config)
+- MCP tools and CLI commands for that project will route to `cloud_host/proxy` with the API key as Bearer token
+
+### How It Works
+
+When an MCP tool or CLI command runs for a cloud-mode project:
+
+1. `get_client(project_name="research")` checks the project's mode in config
+2. If mode is `cloud`, creates an HTTP client pointed at `cloud_host/proxy` with `Authorization: Bearer bmc_...`
+3. If mode is `local` (default), uses the in-process ASGI transport as usual
+
+**Routing priority** (highest to lowest):
+1. Factory injection (cloud app, tests)
+2. Explicit route override (`--local` / `--cloud`)
+3. Per-project cloud mode (API key)
+4. Local ASGI transport (default)
+
+Route override environment variables:
+- `BASIC_MEMORY_FORCE_LOCAL=true`
+- `BASIC_MEMORY_FORCE_CLOUD=true`
+- `BASIC_MEMORY_EXPLICIT_ROUTING=true`
+
+No-project, no-flag CLI commands default to local routing.
+
+### Configuration Example
+
+```json
+{
+  "projects": {
+    "personal": "/Users/me/notes",
+    "research": "/Users/me/research"
+  },
+  "project_modes": {
+    "research": "cloud"
+  },
+  "cloud_api_key": "bmc_abc123...",
+  "cloud_host": "https://cloud.basicmemory.com",
+  "default_project": "personal"
+}
+```
+
+In this example, `personal` stays local and `research` routes through cloud. Projects not listed in `project_modes` default to local.
+
+### Sync Behavior
+
+Cloud-mode projects are automatically skipped during local file sync (background sync and file watching). Their files live on the cloud instance, not locally.
+
+## OAuth Logout
 
 ```bash
 bm cloud logout
 ```
 
 **What this does:**
-1. Disables cloud mode in config
-2. All commands now work locally
-3. Auth token remains (can re-enable with login)
+1. Removes stored OAuth token(s)
+2. Does not change per-project route configuration
+3. Does not change command routing defaults
 
-**Result:** All `bm` commands work with local projects again.
+**Result:** OAuth session is cleared. API-key-based routing still works if `cloud_api_key` is configured.
 
 ## Filter Configuration
 
@@ -653,12 +766,20 @@ If instance is down, wait a few minutes and retry.
 
 ## Command Reference
 
-### Cloud Mode Management
+### Cloud Authentication
 
 ```bash
-bm cloud login              # Authenticate and enable cloud mode
-bm cloud logout             # Disable cloud mode
-bm cloud status             # Check cloud mode and instance health
+bm cloud login              # Authenticate and store OAuth credentials
+bm cloud logout             # Remove stored OAuth credentials
+bm cloud status             # Check auth state and instance health
+bm cloud promo --off        # Disable CLI cloud promo notices
+```
+
+### API Key Management
+
+```bash
+bm cloud set-key <key>      # Save a cloud API key (bmc_ prefixed)
+bm cloud create-key <name>  # Create API key via cloud API (requires OAuth login)
 ```
 
 ### Setup
@@ -669,16 +790,22 @@ bm cloud setup              # Install rclone and configure credentials
 
 ### Project Management
 
-When cloud mode is enabled:
-
 ```bash
-bm project list                           # List cloud projects
-bm project add <name>                     # Create cloud project (no sync)
-bm project add <name> --local-path <path> # Create with local sync
+bm project list --local                   # Local project list
+bm project list --cloud                   # Cloud project list
+bm project add <name> --cloud             # Create cloud project (no sync)
+bm project add <name> --cloud --local-path <path> # Create with local sync
 bm project sync-setup <name> <path>       # Add sync to existing project
 bm project rm <name>                      # Delete project
 ```
 
+### Per-Project Routing
+
+```bash
+bm project set-cloud <name>  # Route project through cloud (requires API key)
+bm project set-local <name>  # Revert project to local mode
+```
+
 ### File Synchronization
 
 ```bash
@@ -697,18 +824,20 @@ bm project bisync --name <project> --verbose
 bm project check --name <project>
 bm project check --name <project> --one-way
 
-# List remote files
-bm project ls --name <project>
-bm project ls --name <project> --path <subpath>
+# List project files by route
+bm project ls --name <project>          # Default target: local
+bm project ls --name <project> --local
+bm project ls --name <project> --cloud
+bm project ls --name <project> --cloud --path <subpath>
 ```
 
 ## Summary
 
 **Basic Memory Cloud uses project-scoped sync:**
 
-1. **Enable cloud mode** - `bm cloud login`
+1. **Authenticate cloud access** - `bm cloud login`
 2. **Install rclone** - `bm cloud setup`
-3. **Add projects with sync** - `bm project add research --local-path ~/Documents/research`
+3. **Add projects with sync** - `bm project add research --cloud --local-path ~/Documents/research`
 4. **Preview first sync** - `bm project bisync --name research --resync --dry-run`
 5. **Establish baseline** - `bm project bisync --name research --resync`
 6. **Daily workflow** - `bm project bisync --name research`

docs/cloud-semantic-search-value.md

@@ -0,0 +1,91 @@
+# Cloud Semantic Search Value (Customer-Facing Technical Story)
+
+This document explains why teams should buy cloud semantic search even when local search exists.
+
+## Core Promise
+
+Markdown files remain the source of truth in both local and cloud modes.
+
+- Files are portable.
+- Search indexes are derived and rebuildable.
+- You never get locked into proprietary document storage.
+
+## The Customer Problem
+
+Teams paying for cloud are usually not optimizing for "can this run locally." They are optimizing for:
+
+- finding the right note the first time,
+- keeping retrieval quality high as note volume grows,
+- avoiding search slowdowns while content is actively changing,
+- getting consistent results across users, agents, and sessions.
+
+## Why Cloud Is the Aspirin
+
+Cloud semantic search is the immediate pain reliever because it fixes the problems users feel right now.
+
+### 1) Better hit rate on real queries
+
+Cloud uses stronger managed embeddings than the default local model, which improves semantic recall for paraphrases and vague questions.
+
+Customer outcome:
+
+- fewer "I know this exists but search missed it" moments,
+- less query rewording,
+- faster time to answer.
+
+### 2) Better behavior under active workloads
+
+Cloud indexing runs out of band in workers, so indexing does not compete with interactive read/write traffic.
+
+Customer outcome:
+
+- stable search responsiveness during heavy updates,
+- fresher semantic results shortly after edits,
+- less user-visible performance variance.
+
+### 3) Better consistency for shared knowledge
+
+Cloud retrieval runs against a centralized tenant index, so teams and agents resolve against the same semantic state.
+
+Customer outcome:
+
+- fewer "works on my machine" search differences,
+- more predictable agent behavior across environments,
+- easier cross-user collaboration on large knowledge bases.
+
+### 4) Better quality at higher scale
+
+With Postgres + `pgvector` per tenant, cloud can sustain larger note collections and higher query volumes than typical local setups.
+
+Customer outcome:
+
+- confidence as repositories grow to tens of thousands of notes,
+- less need for user-side tuning,
+- fewer quality regressions as usage increases.
+
+## Local Is the Vitamin
+
+Local semantic search still matters and should stay strong.
+
+- offline use,
+- privacy-first operation,
+- no cloud dependency,
+- user-controlled runtime.
+
+It compounds long-term ownership and resilience, but does not remove the immediate pain points cloud solves for teams at scale.
+
+## Recommended Messaging
+
+One-liner:
+
+"Cloud semantic search is the aspirin: it fixes retrieval quality and performance pain now. Local semantic search is the vitamin: it builds long-term control and resilience."
+
+Long form:
+
+"Basic Memory keeps markdown as the source of truth everywhere. Local gives privacy and offline control. Cloud adds immediate, measurable improvements in search quality, consistency, and responsiveness for teams and agents running at scale."
+
+## Packaging Guidance
+
+- Base: local FTS plus optional local semantic search.
+- Cloud value: higher semantic quality, stable performance under load, and consistent team-wide retrieval.
+- Keep interfaces pluggable (`EmbeddingProvider`, vector backend protocol) so implementation can evolve without changing user workflows.

docs/mcp-ui-bakeoff-instructions.md

@@ -0,0 +1,138 @@
+# MCP UI Bakeoff - Instructions & Test Plan
+
+Last updated: 2026-02-02
+
+## Scope
+
+Compare three presentation paths for Basic Memory MCP tools:
+
+1. **Tool‑UI (React)** via MCP App resources.
+2. **MCP‑UI Python SDK** embedded UI resources (legacy host path).
+3. **ASCII/ANSI** output for TUI clients.
+
+This doc is the running instruction set and test plan. Update as implementation progresses.
+
+---
+
+## Prerequisites
+
+- Repo: `basic-memory` (worktree: `basic-memory-mcp-ui-poc`)
+- Node for tool‑ui build (already used for POC)
+- Python 3.12+ with `uv`
+
+Optional (for MCP‑UI Python SDK path):
+
+- Local repo: `/Users/phernandez/dev/mcp-ui`
+- Install the server SDK into the Basic Memory venv:
+  - `uv pip install -e /Users/phernandez/dev/mcp-ui/sdks/python/server`
+
+---
+
+## Build / Refresh Steps
+
+### Tool‑UI React bundle
+
+```bash
+cd ui/tool-ui-react
+npm install
+npm run build
+```
+
+This regenerates:
+
+- `src/basic_memory/mcp/ui/html/search-results-tool-ui.html`
+- `src/basic_memory/mcp/ui/html/note-preview-tool-ui.html`
+
+---
+
+## How to Run the MCP Server
+
+```bash
+basic-memory mcp --transport stdio
+```
+
+Optional to pick UI variant for MCP App resources:
+
+```bash
+export BASIC_MEMORY_MCP_UI_VARIANT=tool-ui   # or vanilla | mcp-ui
+```
+
+---
+
+## Test Cases
+
+### 1) MCP App Resource UI (tool‑ui / vanilla / mcp‑ui)
+
+Tools:
+- `search_notes`
+- `read_note`
+
+Expect:
+- Tool meta points to `ui://basic-memory/search-results` and `ui://basic-memory/note-preview`
+- Resource content differs by `BASIC_MEMORY_MCP_UI_VARIANT`
+- Variant‑specific URIs also available:
+  - `ui://basic-memory/search-results/vanilla`
+  - `ui://basic-memory/search-results/tool-ui`
+  - `ui://basic-memory/search-results/mcp-ui`
+  - `ui://basic-memory/note-preview/vanilla`
+  - `ui://basic-memory/note-preview/tool-ui`
+  - `ui://basic-memory/note-preview/mcp-ui`
+
+Manual check:
+- Trigger tool in MCP‑App‑capable host and confirm UI renders.
+
+---
+
+### 2) Text / JSON Output Modes
+
+Tools:
+- `search_notes(output_format="text" | "json")`
+- `read_note(output_format="text" | "json")`
+- `write_note(output_format="text" | "json")`
+- `edit_note(output_format="text" | "json")`
+- `recent_activity(output_format="text" | "json")`
+- `list_memory_projects(output_format="text" | "json")`
+- `create_memory_project(output_format="text" | "json")`
+- `delete_note(output_format="text" | "json")`
+- `move_note(output_format="text" | "json")`
+- `build_context(output_format="json" | "text")`
+
+Expect:
+- `text` mode preserves existing human-readable responses.
+- `json` mode returns structured dict/list payloads for machine-readable clients.
+
+Automated:
+- `uv run pytest test-int/mcp/test_output_format_json_integration.py`
+
+---
+
+### 3) MCP‑UI Python SDK (embedded UI resource)
+
+Tools (embedded resource responses):
+- `search_notes_ui` (MCP‑UI SDK)
+- `read_note_ui` (MCP‑UI SDK)
+
+Expected output:
+- Tool response content contains an EmbeddedResource (`type: "resource"`)
+- `mimeType` is `text/html`
+- `_meta` includes:
+  - `mcpui.dev/ui-preferred-frame-size`
+  - `mcpui.dev/ui-initial-render-data`
+
+Manual check:
+- Render tool responses using `UIResourceRenderer` (legacy host flow).
+
+Automated (if SDK installed):
+- `uv run pytest test-int/mcp/test_ui_sdk_integration.py`
+
+---
+
+## Bakeoff Notes Template
+
+Fill in after running:
+
+- Tool‑UI (React): __
+- MCP‑UI SDK (embedded): __
+- Text/JSON modes: __
+
+Decision + rationale: __

docs/metadata-search.md

@@ -0,0 +1,260 @@
+# Metadata Search Reference
+
+Basic Memory automatically indexes custom frontmatter fields so you can query them with structured filters. Any YAML key in a note's frontmatter beyond the standard set (`title`, `type`, `tags`, `permalink`, `schema`) is stored as `entity_metadata` and becomes searchable.
+
+## Querying with `search_notes`
+
+`search_notes` is the single search tool for all queries — text, metadata filters, or both. The `query` parameter is optional, so you can use metadata filters alone without passing an empty string.
+
+## Filter Syntax
+
+Filters are a JSON dictionary where each key targets a frontmatter field and the value specifies the match condition. Multiple keys combine with **AND** logic — every filter must match.
+
+### Equality
+
+Match a single value exactly.
+
+```json
+{"status": "active"}
+```
+
+Finds notes whose frontmatter contains `status: active`.
+
+### Array Contains (all)
+
+Pass a list to require **all** listed values to be present in the field.
+
+```json
+{"tags": ["security", "oauth"]}
+```
+
+Finds notes tagged with both `security` and `oauth`.
+
+### `$in` (any of)
+
+Match if the field equals **any** value in the list.
+
+```json
+{"priority": {"$in": ["high", "critical"]}}
+```
+
+### `$gt`, `$gte`, `$lt`, `$lte`
+
+Numeric and text comparisons. Numeric values use numeric comparison; strings use lexicographic comparison.
+
+```json
+{"confidence": {"$gt": 0.7}}
+{"score": {"$lte": 100}}
+```
+
+### `$between`
+
+Range filter (inclusive). Takes a `[min, max]` pair.
+
+```json
+{"score": {"$between": [0.3, 0.8]}}
+```
+
+### Nested Access (dot notation)
+
+Access nested frontmatter values using dots.
+
+```json
+{"schema.version": "2"}
+```
+
+This queries the `version` key inside a `schema` object in frontmatter.
+
+### Summary Table
+
+| Operator | Syntax | Example |
+|----------|--------|---------|
+| Equality | `{"field": "value"}` | `{"status": "active"}` |
+| Array contains (all) | `{"field": ["a", "b"]}` | `{"tags": ["security", "oauth"]}` |
+| `$in` (any of) | `{"field": {"$in": [...]}}` | `{"priority": {"$in": ["high", "critical"]}}` |
+| `$gt` / `$gte` | `{"field": {"$gt": N}}` | `{"confidence": {"$gt": 0.7}}` |
+| `$lt` / `$lte` | `{"field": {"$lt": N}}` | `{"score": {"$lt": 0.5}}` |
+| `$between` | `{"field": {"$between": [min, max]}}` | `{"score": {"$between": [0.3, 0.8]}}` |
+| Nested access | `{"a.b": "value"}` | `{"schema.version": "2"}` |
+
+**Key rules:**
+- Filter keys must match `[A-Za-z0-9_-]+` (dots separate nesting levels).
+- Each operator dict must contain exactly one operator.
+- `$in` and array-contains require non-empty lists.
+- `$between` requires exactly two values `[min, max]`.
+
+## MCP Tool — `search_notes`
+
+`search_notes` is the single search tool for text queries, metadata filters, or both. The `query` parameter is optional.
+
+**Relevant parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string (optional) | Text search query. Omit for filter-only searches. |
+| `metadata_filters` | dict | Structured filter dict (see syntax above) |
+| `tags` | list[str] | Convenience shorthand — merged into `metadata_filters["tags"]` |
+| `status` | string | Convenience shorthand — merged into `metadata_filters["status"]` |
+
+**Merging rules:** `tags` and `status` are convenience shortcuts. They are merged into `metadata_filters` using `setdefault` — if the same key already exists in `metadata_filters`, the explicit filter wins.
+
+**Examples:**
+
+```python
+# Text search filtered by metadata
+await search_notes("authentication", metadata_filters={"status": "draft"})
+
+# Filter-only search (no query needed)
+await search_notes(metadata_filters={"type": "spec"})
+
+# Combine text, tags shortcut, and metadata
+await search_notes(
+    "oauth flow",
+    tags=["security"],
+    metadata_filters={"confidence": {"$gt": 0.7}},
+)
+
+# Convenience shortcuts
+await search_notes("planning", status="active")
+await search_notes(tags=["tier1", "alpha"])
+```
+
+## Tag Search Shortcuts
+
+The `tag:` prefix in a search query is a shorthand for tag-based metadata filtering. When `search_notes` receives a query starting with `tag:`, it converts the query into a `tags` filter and clears the text query.
+
+```python
+# These are equivalent:
+await search_notes("tag:tier1")
+await search_notes("", tags=["tier1"])
+
+# Multiple tags (comma or space separated) — all must be present:
+await search_notes("tag:tier1,alpha")
+await search_notes("tag:tier1 alpha")
+```
+
+## CLI Access
+
+The `bm tool search-notes` command exposes metadata filtering via `--meta` and `--filter` flags.
+
+### `--meta` — simple key=value filters
+
+Repeatable flag for equality filters on frontmatter fields.
+
+```bash
+# Single filter
+bm tool search-notes "my query" --meta status=draft
+
+# Multiple filters (AND logic)
+bm tool search-notes "" --meta status=active --meta priority=high
+```
+
+### `--filter` — advanced JSON filters
+
+Pass a full JSON filter dictionary for operator-based queries.
+
+```bash
+# Range filter
+bm tool search-notes "" --filter '{"score": {"$between": [0.3, 0.8]}}'
+
+# $in filter
+bm tool search-notes "" --filter '{"priority": {"$in": ["high", "critical"]}}'
+```
+
+### `--tag` and `--status` — convenience shortcuts
+
+```bash
+bm tool search-notes "query" --tag security --tag oauth
+bm tool search-notes "" --status draft
+```
+
+### Combined example
+
+```bash
+bm tool search-notes "authentication" --tag security --meta status=draft --type spec
+```
+
+## Practical Examples
+
+### Example notes with custom frontmatter
+
+**`specs/auth-design.md`:**
+
+```markdown
+---
+title: Auth Design
+type: spec
+tags: [security, oauth]
+status: in-progress
+priority: high
+confidence: 0.85
+---
+
+# Auth Design
+
+## Observations
+- [decision] Use OAuth 2.1 with PKCE for all client types #security
+- [requirement] Token refresh must be transparent to the user
+
+## Relations
+- implements [[Security Requirements]]
+```
+
+**`specs/search-redesign.md`:**
+
+```markdown
+---
+title: Search Redesign
+type: spec
+tags: [search, performance]
+status: draft
+priority: medium
+confidence: 0.6
+---
+
+# Search Redesign
+
+## Observations
+- [goal] Sub-100ms search response times #performance
+- [approach] Hybrid FTS + vector retrieval
+
+## Relations
+- depends_on [[Database Schema]]
+```
+
+### Queries that find them
+
+```python
+# Find all in-progress specs
+await search_notes(metadata_filters={"status": "in-progress", "type": "spec"})
+# → Auth Design
+
+# Find high-confidence specs
+await search_notes(metadata_filters={"confidence": {"$gt": 0.7}})
+# → Auth Design (confidence: 0.85)
+
+# Find specs with priority high or medium
+await search_notes(metadata_filters={"priority": {"$in": ["high", "medium"]}})
+# → Auth Design, Search Redesign
+
+# Find specs in a confidence range
+await search_notes(metadata_filters={"confidence": {"$between": [0.5, 0.9]}})
+# → Auth Design (0.85), Search Redesign (0.6)
+
+# Find notes tagged with security
+await search_notes("tag:security")
+# → Auth Design
+
+# Combined: text search + metadata filter
+await search_notes("OAuth", metadata_filters={"status": "in-progress"})
+# → Auth Design
+```
+
+### CLI equivalents
+
+```bash
+bm tool search-notes "" --meta status=in-progress --type spec
+bm tool search-notes "" --filter '{"confidence": {"$gt": 0.7}}'
+bm tool search-notes "OAuth" --meta status=in-progress
+bm tool search-notes --tag security
+```

docs/post-v0.18.0-test-plan.md

@@ -0,0 +1,344 @@
+# Post-v0.18.0 Test Plan and Acceptance Criteria
+
+## Goal
+
+Define a complete validation plan for all major features merged after `v0.18.0`, combining:
+
+- Coverage-gap-driven automated tests
+- Real MCP server integration tests (no mocks for target flows)
+- Manual MCP verification via LLM-driven tool calls
+
+This plan is based on commits in `v0.18.0..HEAD` and the latest `just check` coverage output.
+
+## Scope Window
+
+- Start tag: `v0.18.0` (2026-01-28)
+- End: current `main`
+- Change volume: 12 feature commits + 14 bug-fix commits (+ release chores/hotfixes)
+
+## Execution Strategy
+
+1. Stabilize all feature-level acceptance criteria in automated tests first.
+2. Add black-box MCP integration tests for semantic search + schema (real server startup).
+3. Run manual MCP tool-call verification to confirm real UX and routing behavior.
+4. Re-run full gate: `just check` + targeted integration packs.
+
+## Global Quality Gates
+
+- Feature criteria below must all pass.
+- No regressions in existing suites.
+- Coverage improves in targeted low-coverage feature modules.
+- SQLite and Postgres parity for search/semantic features.
+
+## Priority Coverage Gaps (from latest run)
+
+These are the most important post-`v0.18.0` feature modules currently under-covered:
+
+- `src/basic_memory/mcp/tools/schema.py` (27%)
+- `src/basic_memory/mcp/clients/schema.py` (36%)
+- `src/basic_memory/mcp/tools/ui_sdk.py` (43%)
+- `src/basic_memory/mcp/tools/search.py` (73%)
+- `src/basic_memory/repository/postgres_search_repository.py` (63%)
+- `src/basic_memory/mcp/async_client.py` (82%)
+- `src/basic_memory/api/v2/routers/schema_router.py` (80%)
+
+## Feature Acceptance Criteria and Test Plan
+
+### 1) Schema System (`c97733d`) — DONE
+
+### Acceptance criteria
+
+- `schema_validate`, `schema_infer`, and `schema_diff` produce consistent outcomes across CLI/API/MCP for the same fixture set.
+- Strict validation fails deterministically on required-field/type violations.
+- Validation warnings are stable and machine-readable in non-strict mode.
+- Inference output is deterministic for unchanged input corpus.
+- Drift diff output is deterministic and identifies missing/extra/type-mismatch fields correctly.
+
+### Existing coverage anchor points
+
+- `tests/schema/*`
+- `tests/api/v2/test_schema_router.py`
+- `test-int/test_schema/*`
+
+### Gaps to close — DONE
+
+- ~~MCP schema tool branches (`src/basic_memory/mcp/tools/schema.py`)~~ — 18 tests in `tests/mcp/test_tool_schema.py`
+- ~~MCP schema client behavior (`src/basic_memory/mcp/clients/schema.py`)~~ — `tests/mcp/test_client_schema.py`
+- ~~Schema router error-path branches (`src/basic_memory/api/v2/routers/schema_router.py`)~~ — `tests/api/v2/test_schema_router.py`
+
+### Planned additions — DONE
+
+- ~~Add MCP tool tests for `schema_validate` strict + non-strict result shapes.~~ **DONE**
+- ~~Add MCP tool tests for `schema_infer` with explicit `entity_type` and inferred type fallback.~~ **DONE**
+- ~~Add MCP tool tests for `schema_diff` empty-diff and non-empty-diff paths.~~ **DONE**
+- ~~Add API tests for schema router invalid payload/edge error handling.~~ **DONE**
+- Add integration test that starts MCP server and calls schema tools end-to-end on fixture notes. — deferred to backlog item 4.
+
+### 2) Semantic Search (`0777879`, `1428d18`, `344e651`) — DONE
+
+### Acceptance criteria
+
+- `search_type=text|vector|hybrid` returns expected ranked results on canonical semantic corpus.
+- Missing semantic dependencies fail fast with actionable install guidance.
+- Reindex and provider/model changes produce valid vectors without dimension mismatch.
+- SQLite and Postgres produce equivalent behavior for semantic modes on the same dataset.
+- Generated-column migration path is valid on SQLite environments in use.
+
+### Existing coverage anchor points
+
+- `tests/repository/test_sqlite_vector_search_repository.py`
+- `tests/repository/test_postgres_search_repository.py`
+- `tests/services/test_semantic_search.py`
+- `tests/mcp/test_tool_search.py`
+- `test-int/test_search_performance_benchmark.py`
+
+### Gaps to close — DONE
+
+- ~~Uncovered Postgres vector/hybrid branches~~ — 20 tests in `tests/repository/test_postgres_search_repository_unit.py` + 5 integration tests in `test-int/semantic/test_semantic_coverage.py`
+- ~~MCP search semantic/output branches~~ — expanded `tests/mcp/test_tool_search.py`
+
+### Planned additions — DONE
+
+- ~~Expand Postgres repository tests for vector query composition edge cases.~~ **DONE**
+- ~~Expand Postgres repository tests for hybrid fusion ranking and pagination branches.~~ **DONE**
+- ~~Expand Postgres repository tests for embedding/provider error handling branches.~~ **DONE**
+- ~~Expand MCP search tool tests for vector/hybrid output formatting branches.~~ **DONE**
+- ~~Expand MCP search tool tests for semantic-disabled and missing-dependency failures.~~ **DONE**
+- Add MCP integration tests that start server and execute semantic `search_notes` tool calls. — deferred to backlog item 4.
+
+### Semantic search quality benchmarks (NEW)
+
+Full benchmark suite in `test-int/semantic/` covering 5 backend×provider combinations:
+- `sqlite-fts`, `sqlite-fastembed`, `postgres-fts`, `postgres-fastembed`, `postgres-openai`
+- Quality metrics: hit@1, recall@5, MRR@10 with per-query timing
+- Realistic corpus with cross-topic vocabulary overlap (240 notes, 4 topics)
+- Rich CLI viewer: `just semantic-report`
+- JSON artifact output: `just test-semantic-report`
+
+Key finding: **FastEmbed (384-d local ONNX) matches or exceeds OpenAI (1536-d) quality at 30x lower latency.** Recommending FastEmbed as default for both local and cloud deployments.
+
+### 3) Per-Project Local/Cloud Routing + API Key Auth (`d84708c`, `ed94877`, `312662f`) — DONE
+
+### Acceptance criteria
+
+- Project mode (`local`/`cloud`) persists and displays correctly.
+- Routing selects ASGI for local projects and HTTP+Bearer for cloud projects.
+- Cloud project without key fails with explicit remediation (`cloud set-key`/`cloud create-key`).
+- Resolution precedence is correct (factory > force-local > per-project cloud > global fallback > local).
+- Watch/sync only run for local projects.
+
+### Existing coverage anchor points
+
+- `tests/mcp/test_async_client_modes.py`
+- `tests/cli/test_project_set_cloud_local.py`
+- `tests/mcp/test_project_context.py`
+- `tests/test_project_resolver.py`
+- `tests/sync/test_watch_service_reload.py`
+
+### Gaps to close — DONE
+
+- ~~Cloud routing branch gaps in `src/basic_memory/mcp/async_client.py`~~ — expanded `tests/mcp/test_async_client_modes.py`
+
+### Planned additions — DONE
+
+- ~~Add branch-focused tests for all unresolved routing branches in `get_client()`.~~ **DONE**
+- Add MCP integration scenario with mixed local/cloud project config — deferred to backlog item 4.
+
+### 4) Project-Prefixed Permalinks + Memory URL Routing (`545804f`) — DONE
+
+### Acceptance criteria
+
+- Project-prefixed permalinks are generated consistently on create/update/import flows.
+- Memory URLs resolve to the correct project/entity even with duplicate note titles.
+- `read_note`, `search`, `build_context`, write/edit/move flows preserve project identity correctly.
+- Link resolution remains correct for context-aware wikilinks.
+
+### Existing coverage anchor points
+
+- `tests/utils/test_permalink_formatting.py`
+- `tests/mcp/test_tool_read_note.py`
+- `tests/mcp/test_tool_search.py`
+- `tests/services/test_context_service.py`
+- `test-int/mcp/test_read_note_integration.py`
+
+### Gaps to close
+
+- No major coverage alarm in report, but keep as regression-critical due broad impact surface.
+
+### Planned additions — DONE
+
+- ~~Add one integration test with colliding titles across two projects and assert URL routing invariants.~~ **DONE** — `test-int/mcp/test_permalink_collision_integration.py` (2 tests: collision across projects + memory:// URL routing with project prefix)
+
+### 5) MCP UI Variants + TUI Output (`8bc03d1`) — DONE
+
+### Acceptance criteria
+
+- UI resource variant selection (`tool-ui`, `vanilla`, `mcp-ui`) follows env configuration.
+- `search_notes` and `read_note` expose expected resource metadata for UI hosts.
+- `ascii`/`ansi` outputs are deterministic and stable for terminal clients.
+
+### Existing coverage anchor points
+
+- `tests/mcp/test_tool_contracts.py`
+- `test-int/mcp/test_output_format_json_integration.py`
+- `test-int/mcp/test_ui_sdk_integration.py`
+
+### Gaps to close — DONE
+
+- ~~`src/basic_memory/mcp/tools/ui_sdk.py` branch coverage~~ — `tests/mcp/test_ui_sdk.py`
+- ~~`src/basic_memory/mcp/ui/sdk.py` and `src/basic_memory/mcp/ui/templates.py` branch coverage~~ — `tests/mcp/test_ui_templates.py` + `tests/mcp/test_ui_resources.py`
+
+### Planned additions — DONE
+
+- ~~Add unit tests for UI SDK metadata generation and template selection branches.~~ **DONE** — 31 tests
+- ~~Add integration assertion for variant-specific resource URIs and metadata payload shape.~~ **DONE**
+
+### 6) Watch Command (`8df88e4`) — DONE
+
+### Acceptance criteria
+
+- `basic-memory watch` starts and processes create/update/delete events.
+- Watch restart/reload path does not duplicate watchers.
+- Cloud-mode projects are excluded from active watcher set.
+
+### Existing coverage anchor points
+
+- `tests/cli/test_watch.py`
+- `tests/sync/test_coordinator.py`
+- `tests/sync/test_watch_service_reload.py`
+
+### Planned additions — DONE
+
+- ~~Add one stress-style integration test for rapid file changes and watcher stability.~~ **DONE** — `tests/sync/test_watch_service_stress.py` (3 tests: 50-file batch, mixed add/modify/delete batch, rapid modifications to same file)
+
+### 7) CLI JSON Output (`a47c9c0`) — DONE
+
+### Acceptance criteria
+
+- `--format json` returns valid JSON with stable keys for success paths.
+- Error paths also return JSON-shaped output with correct non-zero exits.
+- Default human output remains unchanged.
+
+### Existing coverage anchor points
+
+- `tests/cli/test_cli_tool_json_output.py`
+- `test-int/cli/test_cli_tool_json_integration.py`
+
+### Planned additions — DONE
+
+- ~~Add one failure-path integration test per high-use tool command.~~ **DONE** — `test-int/cli/test_cli_tool_json_failure_integration.py` (4 tests: read-note not found, write-note missing content, write→read roundtrip, recent-activity empty project)
+
+### 8) Search/Edit and Metadata Fixes (`530cbac`, `f1d50c2`, `8838571`, `009e849`) — DONE
+
+### Acceptance criteria
+
+- Metadata filters produce consistent results on SQLite and Postgres.
+- `tag:` shorthand works alone and with mixed query terms.
+- Fast write/edit paths preserve `external_id` and metadata integrity.
+
+### Existing coverage anchor points
+
+- `tests/repository/test_metadata_filters.py`
+- `tests/repository/test_search_repository.py`
+- `tests/services/test_search_service.py`
+
+### Planned additions — DONE
+
+- ~~Add Postgres-specific metadata filter edge-case tests to mirror SQLite assertions exactly.~~ **DONE** — `tests/repository/test_metadata_filters_edge_cases.py` (6 tests: missing field, AND logic, contains single-element array, nested path missing intermediate, $gte/$lte boundaries, $between inclusive — all pass on both SQLite and Postgres)
+
+### 9) Compatibility and Hotfix Regression Pack (`c46d7a6`, `a0e754b`, `343a6e1`, `24ca5f6`, `e3ced49`, `8489a3d`, `b609c4e`, `f6e0a5b`, `7624a20`)
+
+### Acceptance criteria
+
+- Legacy endpoints required by older CLI versions function without `405` (`GET /projects/projects`, `POST /projects/projects`, `POST /projects/config/sync`).
+- Entity creation conflicts map to conflict status (not 500).
+- `recent_activity` prompt defaults are correct.
+- No spurious `metadata: {}` in serialized frontmatter.
+- Tigris/rclone uses global consistency headers for all transaction types.
+- `bm --version` fast path avoids heavy import path and remains responsive.
+- Default SQLite DB path is isolated by config dir.
+
+### Gaps to close
+
+- ~~Commits with no direct tests added (`c46d7a6`, `344e651`, `f6e0a5b`) need explicit regression tests.~~ **DONE**
+
+### Planned additions — DONE
+
+- ~~Add API compat test covering all legacy endpoint methods and payloads.~~ **DONE** — `test_legacy_v1_add_project_endpoint`, `test_legacy_v1_sync_config_endpoint`
+- ~~Add CLI fast-path test for `--version` import behavior/performance guard.~~ **DONE** — `test_bm_version_does_not_import_heavy_modules`
+- ~~Add empty metadata serialization regression test.~~ **DONE** — `test_schema_to_markdown_empty_metadata_no_metadata_key`
+- Add migration safety test for SQLite generated columns (`VIRTUAL` expectation) — deferred, low risk.
+
+## MCP Manual Verification Plan (LLM Tool Calls)
+
+Run after automated tests pass.
+
+### Setup
+
+- Start MCP server: `basic-memory mcp --transport stdio`
+- Use an MCP-capable client and issue tool calls directly.
+
+### Manual scenarios
+
+- Schema: call `schema_validate`, `schema_infer`, and `schema_diff` on known fixtures.
+- Schema: verify error and success payloads match acceptance criteria.
+- Semantic search: call `search_notes` with `search_type=text|vector|hybrid`.
+- Semantic search: verify ranking relevance on semantic fixture queries.
+- Routing: call tools with explicit project on mixed local/cloud setup.
+- Routing: verify success/failure paths with and without API key.
+- Permalink routing: read/write/search notes across projects with colliding titles.
+- Permalink routing: verify memory URL routing correctness.
+- UI/TUI: call `search_notes` and `read_note` with UI variants and `output_format=text|json`.
+- UI/TUI: verify payload/resource format and metadata completeness.
+
+## Implementation Backlog (Ordered)
+
+1. ~~Fill schema MCP/client/router coverage gaps.~~ **DONE** — 18 tests in `test_tool_schema.py` + `test_client_schema.py`
+2. ~~Fill semantic search MCP + Postgres repository gaps.~~ **DONE** — 20 tests in `test_postgres_search_repository_unit.py` + `test_tool_search.py`
+3. ~~Add compatibility regression tests (legacy endpoints, migration, version fast path).~~ **DONE** — 5 tests across 3 files (see below)
+4. ~~Add feature-level integration tests (permalinks, watch, CLI JSON, metadata filters).~~ **DONE** — 15 tests across 4 files (see items 4, 6, 7, 8 above)
+5. ~~Expand UI SDK and template branch tests.~~ **DONE** — 31 tests in `test_ui_templates.py` + `test_ui_sdk.py` + `test_ui_resources.py`
+6. ~~Run full gate and capture results in a short release readiness summary.~~ **DONE** — see results below
+
+### Full Gate Results (`just check`)
+
+| Phase | Result |
+|-------|--------|
+| lint | PASS |
+| format | PASS |
+| typecheck | PASS |
+| Unit tests (SQLite) | 1788 passed, 15 skipped |
+| Integration tests (SQLite) | 243 passed, 4 skipped, 10 deselected |
+| Unit tests (Postgres) | 1760 passed, 28 skipped |
+| Integration tests (Postgres) | 234 passed, 13 skipped, 10 deselected |
+
+**0 failures. 10 deselected = semantic benchmark tests (run separately via `just test-semantic`).**
+
+### Item 3 Details — Compatibility Regression Tests
+
+| Test | File | What it covers |
+|------|------|----------------|
+| `test_legacy_v1_add_project_endpoint` | `tests/api/v2/test_project_router.py` | POST `/projects/projects` legacy route reachable (idempotent path) |
+| `test_legacy_v1_sync_config_endpoint` | `tests/api/v2/test_project_router.py` | POST `/projects/config/sync` legacy route reachable |
+| `test_bm_version_does_not_import_heavy_modules` | `tests/cli/test_cli_exit.py` | `bm --version` fast path does not load `basic_memory.mcp` |
+| `test_schema_to_markdown_empty_metadata_no_metadata_key` | `tests/markdown/test_entity_parser_error_handling.py` | `schema_to_markdown()` with `entity_metadata={}` emits no `metadata:` key |
+| `test_legacy_v1_list_projects_endpoint` | `tests/api/v2/test_project_router.py` | (pre-existing) GET `/projects/projects` legacy route |
+
+**Suite totals after item 3: 1764 passed, 15 skipped, 0 failures.**
+
+## Suggested Commands
+
+- Full suite: `just check`
+- Fast loop: `just fast-check`
+- E2E consistency: `just doctor`
+- SQLite focused: `just test-sqlite`
+- Postgres focused: `just test-postgres`
+- Schema integration: `pytest test-int/test_schema -q`
+- Semantic + repo focus: `pytest tests/repository/test_postgres_search_repository.py tests/mcp/test_tool_search.py tests/services/test_semantic_search.py -q`
+- MCP integration focus: `pytest test-int/mcp -q`
+
+## Exit Criteria for This Plan
+
+- All feature acceptance criteria above are validated.
+- All identified high-priority coverage gaps are addressed or explicitly documented as intentional.
+- Manual MCP verification scenarios complete with no P0/P1 findings.

docs/releases/v0.19.0.md

@@ -0,0 +1,318 @@
+# v0.19.0 Release Notes
+
+## Overview
+
+v0.19.0 is a major release that introduces semantic vector search, a schema validation system,
+project-prefixed permalinks, per-project cloud routing, and a significant upgrade to FastMCP 3.0.
+It includes 90+ commits since v0.18.0 spanning new features, architectural improvements, and
+stability fixes across both SQLite and Postgres backends.
+
+---
+
+## Major Features
+
+### Semantic Vector Search
+
+Full vector and hybrid search for SQLite (via sqlite-vec) and Postgres (via pgvector).
+
+- **Hybrid search mode** combines full-text search (FTS) with vector similarity for best results
+- **Score-based fusion** replaces RRF for hybrid ranking — `max(vec, fts) + 0.3 * min(vec, fts)` preserves dominant signals and rewards dual-source agreement (#577)
+- **Default search mode** is now `hybrid` when semantic search is enabled, `text` when disabled
+- Embedding providers: FastEmbed (local, default) or OpenAI API
+- Configurable similarity threshold via `semantic_min_similarity` (default 0.55)
+- Per-query `min_similarity` override on `search_notes` tool
+- Auto-backfill: existing entities get embeddings generated on first startup
+- Backend-specific distance-to-similarity conversion (cosine for SQLite, inner product for Postgres)
+- FTS fallback: if semantic dependencies are missing, search gracefully degrades to text-only
+- sqlite-vec knn `k` parameter capped at 4096 to prevent backend errors
+
+**Configuration:**
+```json
+{
+  "semantic_search_enabled": true,
+  "semantic_embedding_provider": "fastembed",
+  "semantic_embedding_model": "bge-small-en-v1.5",
+  "semantic_min_similarity": 0.55
+}
+```
+
+**Usage:**
+```
+search_notes("machine learning concepts", search_type="hybrid")
+search_notes("similar to my notes on coffee", search_type="vector")
+search_notes("exact phrase match", search_type="text")
+search_notes("broad search", min_similarity=0.3)  # lower threshold for more results
+```
+
+### Schema System
+
+Validate note structure against user-defined schemas with frontmatter-based rules.
+
+- Define schemas as YAML in note frontmatter with field types, required fields, and constraints
+- Frontmatter validation during sync — malformed notes get clear error messages
+- Schema inference from existing notes to bootstrap schemas from your content
+- Schema diff to compare two schemas and see changes
+- Available via MCP tools and CLI
+
+### Project-Prefixed Permalinks
+
+Permalinks now include the project name for unambiguous cross-project references.
+
+- Memory URLs like `memory://project-name/folder/note` route to the correct project
+- Existing non-prefixed permalinks continue to work (backwards compatible)
+- Controlled by `permalinks_include_project` config (default: true)
+- `build_context` and `search_notes` auto-detect project from URL prefix
+
+### Per-Project Cloud Routing
+
+Individual projects can be routed through the cloud while others stay local.
+
+- Set a project to cloud mode: `bm project set-cloud research`
+- Revert to local: `bm project set-local research`
+- Uses API key authentication: `bm cloud set-key bmc_abc123...`
+- MCP tools automatically route based on each project's mode
+- Local MCP server (`bm mcp`) still uses local routing for all projects by default
+- `--local` and `--cloud` CLI flags override per-command
+
+### Workspace Selection
+
+Cloud projects can target specific workspaces for multi-tenant environments.
+
+- `workspace` parameter on MCP tools for explicit workspace targeting
+- CLI workspace-aware project listing with `bm project list`
+- Spinner feedback while fetching cloud projects
+
+---
+
+## New Tools and Capabilities
+
+### Dashboard (`bm project info`)
+
+`bm project info` now displays an htop-inspired compact dashboard with:
+
+- Horizontal bar charts for note types (top 5)
+- Embedding coverage bar with Unicode block characters
+- Colored status dots for at-a-glance health
+- `EmbeddingStatus` schema and `get_embedding_status()` service method for programmatic access
+
+### Unified Metadata Search
+
+`search_by_metadata` has been merged into `search_notes` — one tool for all searches.
+`query` is now optional, so you can search purely by frontmatter metadata.
+
+```
+search_notes(metadata_filters={"status": "in-progress"})
+search_notes(metadata_filters={"tags": ["security", "oauth"]})
+search_notes(metadata_filters={"priority": {"$in": ["high", "critical"]}})
+search_notes(metadata_filters={"schema.confidence": {"$gt": 0.7}})
+search_notes(tags=["security"])  # convenience shorthand
+search_notes(status="draft")     # convenience shorthand
+```
+
+### JSON Output Mode
+
+All MCP tools now support `output_format="json"` for machine-readable responses.
+
+- Default remains `"text"` for human-readable output (no breaking changes)
+- `build_context` defaults to `"json"` with slimmed payloads (redundant fields stripped)
+- CLI tool commands support `--format json` flag
+
+### `tag:` Search Shorthand
+
+Search by tag using convenient shorthand syntax.
+
+```
+search_notes("tag:security")
+search_notes("tag:coffee AND tag:brewing")
+```
+
+### Entity User Tracking
+
+Entities now track `created_by` and `last_updated_by` fields for attribution.
+
+### Improved Search Result Content (#609)
+
+Search results now surface more relevant context:
+
+- `matched_chunk_text` populated for FTS-only hybrid results (no more fallback to truncated content)
+- `TOP_CHUNKS_PER_RESULT` increased from 3 to 5, catching answers deeper in large notes (~2700 → ~4500 chars)
+- `CONTENT_DISPLAY_LIMIT` doubled from 2000 to 4000 chars for results without matched chunks
+
+### `write_note` Overwrite Guard (#632)
+
+`write_note` is now non-idempotent by default. If a note already exists, the tool returns an
+error instead of silently overwriting. Pass `overwrite=True` to replace, or use `edit_note`
+for incremental updates. Config option `write_note_overwrite_default` restores the old upsert
+behavior.
+
+---
+
+## Architecture Changes
+
+### Score-Based Hybrid Fusion (#577)
+
+RRF (Reciprocal Rank Fusion) compressed all fused scores to ~0.016, destroying ranking
+differentiation. The new formula `max(vec, fts) + FUSION_BONUS * min(vec, fts)` preserves
+dominant signals and rewards dual-source agreement. Zero-score results now produce zero
+fused score instead of receiving a 0.1 weight floor.
+
+### FastMCP 3.0 Upgrade
+
+Upgraded from FastMCP 2.12.3 to 3.0.1.
+
+- Tool annotations (`readOnlyHint`, `openWorldHint`) for better client integration
+- Improved MCP protocol compliance
+- Better error handling and context management
+
+### Prompts Call MCP Tools Directly
+
+MCP prompts (`search`, `continue_conversation`) now call MCP tools directly instead of
+going through API endpoints. This fixes empty results in discovery mode and ensures prompts
+use the same resolution logic as tools (including LinkResolver fallback).
+
+### build_context LinkResolver Fallback
+
+`build_context` now falls back to LinkResolver when an exact permalink lookup returns empty.
+This uses the same 7-strategy resolution pipeline as `read_note`, so callers no longer get
+empty results for valid note identifiers that don't match exact permalinks.
+
+### Sync Handles Semantic Dependency Errors Gracefully
+
+When sqlite-vec or another embedding provider is unavailable, `sync_file` now catches
+`SemanticDependenciesMissingError` separately. The entity is created and FTS-indexed
+successfully — only vector embeddings are skipped, with a clear warning:
+
+```
+WARNING: Semantic search dependencies missing — vector embeddings skipped for path=note.md.
+Run 'bm reindex --embeddings' after resolving the dependency issue.
+```
+
+### Unified Project Path
+
+Cloud projects with bisync now store the local filesystem path in `path` (not the Docker
+container path). Config migration automatically promotes `local_sync_path` → `path` for
+existing configs.
+
+---
+
+## CLI Improvements
+
+### Status and Doctor Default to Local Routing
+
+`bm status` and `bm doctor` now default to local routing since they scan the local filesystem.
+Previously, cloud-mode projects would route these commands to the cloud API, which returned
+Docker-internal paths that don't exist locally.
+
+### `--format json` for CLI Tool Commands
+
+All `bm tool` subcommands support `--format json` for machine-readable output, enabling
+integration with scripts and plugins.
+
+### `--json` for Top-Level CLI Commands
+
+Five additional CLI commands now support `--json` for machine-readable output:
+
+- `bm status --json` — sync report with new/modified/deleted/moved files and skipped files
+- `bm project list --json` — structured project list with name, paths, routing mode, and defaults
+- `bm schema validate --json` — validation report with per-note pass/fail, warnings, and errors
+- `bm schema infer --json` — field frequency analysis and suggested schema definition
+- `bm schema diff --json` — drift report with new fields, dropped fields, and cardinality changes
+
+This complements the existing `bm project info --json` and `bm tool --format json` support,
+making all major CLI commands scriptable for CI pipelines and automation.
+
+### Cloud Promo and Analytics
+
+- Cloud promo panel shown on first run or version bump with OSS discount code
+- Anonymous usage telemetry via Umami Cloud (promo/login funnel events only)
+- Opt out with `BASIC_MEMORY_NO_PROMOS=1`
+- No PII, no file contents, no per-command tracking
+- See [Telemetry](https://github.com/basicmachines-co/basic-memory#telemetry) in README
+
+---
+
+## Bug Fixes
+
+- **#577**: RRF fusion compressed all hybrid scores to ~0.016, destroying ranking differentiation
+- **#582**: build_context returns empty results on valid note identifiers
+- **#575**: Remove hardcoded "main" default from default_project
+- **#595**: recent_activity dedup and pagination across MCP tools
+- **#593**: Backend-specific distance-to-similarity conversion
+- **#592**: Strip NUL bytes from content before PostgreSQL search indexing
+- **#562**: Use VIRTUAL instead of STORED columns in SQLite migration
+- **#558**: Add X-Tigris-Consistent headers to all rclone commands
+- **#541**: Handle EntityCreationError as conflict
+- **#536**: Stabilize metadata filters on Postgres
+- **#533**: Fix recent_activity prompt defaults
+- **#530**: Prevent spurious `metadata: {}` in frontmatter output
+- **#601**: Return matched chunk text in search results
+- **#606**: Accept `null` for `expected_replacements` in `edit_note`
+- **#579, #607**: Guard against closed streams in promo panel and missing vector tables on shutdown
+- **#609**: FTS-only hybrid results missing `matched_chunk_text`; content limits too conservative
+- **#631**: `build_context` related_results schema validation failure — replaced fragile `_slim_context()` stripping with Pydantic `exclude=True` field config
+- **#630**: Skip workspace resolution when client factory is active — prevents 401 errors in cloud MCP server mode
+- **#30**: `tag:` prefix query fails with hybrid search — moved tag prefix parsing to MCP tool level so it works with all search modes
+- **#31**: `search_notes` returns cluttered observation/relation-level results — now defaults to entity-level results
+- **#28**: `schema_infer` and `schema_diff` return raw Pydantic models as "undefined" in LLM output — added markdown formatters
+- Fix `schema_validate` identifier resolution (now uses LinkResolver) and text rendering (markdown formatter)
+- **#634**: `schema_validate` and `schema_diff` use stale database metadata instead of reading schema definitions from file — now reads frontmatter directly from the file with fallback to database metadata
+- Fix `Post(**metadata)` crash when frontmatter contains `content` or `handler` keys
+- Fix list-valued frontmatter fields (`title`, `type`) crashing on `.strip()` — now coerced to strings
+- Cap sqlite-vec knn `k` parameter at 4096 to prevent backend errors
+- Parameterize SQL queries in search repository type filters
+- Double-default display in project list
+- `ensure_frontmatter_on_sync` default changed to `True`
+- Status/doctor commands fail with cloud-mode projects (Docker path error)
+- Prompts return "0 projects" in discovery mode
+
+---
+
+## Security
+
+- Upgrade `cryptography` for CVE advisory
+- Upgrade `python-multipart` for security advisory
+
+---
+
+## Internal / Developer
+
+- **#598**: Upgrade FastMCP 2.12.3 → 3.0.1 with tool annotations
+- **#594**: Add `ty` as supplemental type checker
+- **#538**: Add fast feedback loop tooling (`just fast-check`, `just doctor`, `just testmon`)
+- **#600**: Rename `entity_type` to `note_type` for consistency
+- **#596**: Fix CLI runtime defects and audit regressions
+- CLI refactoring and workspace-aware cloud project listing
+- Split and speed up PR test matrix in CI
+- Fix CI: collect coverage from test jobs instead of re-running all tests
+- Create `search_vector_chunks` in test fixtures for Postgres compatibility
+
+---
+
+## Configuration Changes
+
+| Setting | Old Default | New Default | Notes |
+|---------|-------------|-------------|-------|
+| `semantic_search_enabled` | `false` | `true` | Semantic search on by default |
+| `ensure_frontmatter_on_sync` | `false` | `true` | Frontmatter added during sync |
+| `permalinks_include_project` | `false` | `true` | Project prefix in permalinks |
+
+---
+
+## Upgrade Notes
+
+- **Semantic search dependencies** are now included by default. If sqlite-vec fails to load,
+  search gracefully falls back to FTS. Run `bm reindex --embeddings` to generate embeddings
+  for existing content.
+- **Hybrid search scoring** has changed from RRF to score-based fusion. Search result ordering
+  may differ — results should be more accurate with better score differentiation.
+- **`search_by_metadata`** is removed as a standalone tool. Use `search_notes` with
+  `metadata_filters` instead (same parameters, same behavior).
+- **Project-prefixed permalinks** are enabled by default. Existing notes keep their current
+  permalinks until modified. Set `permalinks_include_project: false` to disable.
+- **Frontmatter on sync** is now enabled by default. Files without frontmatter will have it
+  added on next sync. Set `ensure_frontmatter_on_sync: false` to preserve old behavior.
+- **Config migration** runs automatically for cloud projects with bisync — `local_sync_path`
+  is promoted to `path` so filesystem operations work correctly.
+- **`write_note` is no longer idempotent** — calls to `write_note` for existing notes now
+  return an error unless `overwrite=True` is passed. Use `edit_note` for incremental changes,
+  or set `write_note_overwrite_default: true` in config to restore the old behavior.

docs/semantic-search-test-log.md

@@ -0,0 +1,209 @@
+# Semantic Search Manual Test Log
+
+## Overview
+
+Manual test session for semantic (vector) search on the main project.
+- Date: 2026-02-15
+- Database: ~/.basic-memory/memory.db (SQLite)
+- Entities: 456 embedded, 2714 vector chunks
+- Search index: 2390 FTS entries
+- Embedding model: default (384-dim, sqlite-vec)
+
+## Test Plan
+
+1. **Search Type Routing** — verify vector/hybrid/text dispatch, invalid search_type handling
+2. **Conceptual Queries** — natural language where vector should beat FTS
+3. **Keyword Queries** — exact terms where FTS should be strong
+4. **Hybrid Ranking** — queries where both FTS and vector contribute
+5. **Result Types** — entities, observations, relations in vector results
+6. **Filters + Vector** — combine vector with types/entity_types/after_date
+7. **Edge Cases** — short queries, long queries, empty, special chars, no-match
+8. **Pagination** — page > 1, page_size respected
+
+---
+
+## Test Results
+
+### Test 1: Search Type Routing
+
+#### 1a: search_type="semantic" (invalid value)
+- **Input:** query="how does the knowledge graph work", search_type="semantic"
+- **Expected:** error or explicit fallback
+- **Actual:** Silently falls through to text search (else branch in search.py:430)
+- **Verdict:** BUG — should either be a recognized alias for "vector" or return an error
+
+#### 1b: search_type="vector"
+- **Input:** query="keeping AI context between sessions", search_type="vector"
+- **Actual:** 5 results, scores ~0.58-0.59, found "Maintaining context across conversation boundaries" observation
+- **Verdict:** PASS
+
+#### 1c: search_type="text" with conceptual query
+- **Input:** query="keeping AI context between sessions", search_type="text"
+- **Actual:** 0 results (no exact keyword match)
+- **Verdict:** PASS (expected — FTS requires token overlap)
+
+#### 1d: search_type="hybrid" with conceptual query
+- **Input:** query="keeping AI context between sessions", search_type="hybrid"
+- **Actual:** 5 results, same ranking as vector (FTS contributed nothing here)
+- **Verdict:** PASS
+
+#### 1e: search_type="text" with keyword query
+- **Input:** query="OAuth authentication", search_type="text"
+- **Actual:** 3 results — AUTH.md Supabase OAuth, OAuth Rip-and-Replace, OAuth Integration Analysis
+- **Verdict:** PASS
+
+#### 1f: search_type="vector" with keyword query
+- **Input:** query="OAuth authentication", search_type="vector"
+- **Actual:** Same top results as text (keyword-rich content also scores well in vector space)
+- **Verdict:** PASS
+
+---
+
+### Test 2: Conceptual Queries (vector advantage)
+
+#### 2a: Natural language question
+- **Input:** query="why do AI assistants forget things", search_type="vector"
+- **Actual:** 5 results — Manual Testing Session, "Balance security and usability" observation, "Tools should match thought patterns" observation. Scores ~0.56-0.57
+- **Vector advantage:** Found conceptually related content despite no exact keyword overlap
+- **Verdict:** PASS
+
+#### 2b: Same query, text search
+- **Input:** query="why do AI assistants forget things", search_type="text"
+- **Actual:** 1 result — "What is Basic Memory?" (likely matched on "AI" token)
+- **Verdict:** PASS (demonstrates vector advantage — text barely matched)
+
+#### 2c: Domain concept with no jargon
+- **Input:** query="pricing strategy for cloud product", search_type="vector"
+- **Actual:** 3 results — SPEC-16 MCP Cloud Service Consolidation, knowledge architecture observation, Visual Knowledge Spaces relation. Scores ~0.56-0.57
+- **Verdict:** PASS (found cloud-related content conceptually)
+
+#### 2d: Technical concept, long query
+- **Input:** query="SQLite performance optimization WAL mode concurrent writes", search_type="vector"
+- **Actual:** 3 results — SPEC-11 API Performance Optimization, Real-Time Updates with WebSockets, marketing status update. Scores ~0.55-0.58
+- **Verdict:** PASS (found performance-related content)
+
+---
+
+### Test 3: Keyword Queries (FTS strength)
+
+#### 3a: Exact term match — "OAuth authentication"
+- **Text:** 3 results with high relevance (exact matches in titles)
+- **Vector:** Same top results (keyword overlap helps vector too)
+- **Verdict:** PASS — FTS and vector converge on keyword-rich queries
+
+#### 3b: "OAuth" single keyword, hybrid mode
+- **Input:** query="OAuth", search_type="hybrid"
+- **Actual:** 5 results — Basic Memory Coding Guide, AI Collaboration Examples, SPEC-18, daily note, Manual Testing Session. FTS + vector blended. Scores ~0.016-0.032
+- **Note:** Top hybrid result is "Basic Memory Coding Guide" not an OAuth-specific doc — suggests hybrid scoring may dilute strong FTS matches
+- **Verdict:** PASS but hybrid ranking questionable for single-keyword queries
+
+---
+
+### Test 4: Hybrid Ranking
+
+#### 4a: Hybrid vs vector on "OAuth authentication"
+- **Hybrid with entity_types=["entity"]:** 5 results — RLS Implementation Lessons, Cloud Readiness Assessment, AUTH.md OAuth, Core Service Implementation, OAuth Rip-and-Replace. Scores ~0.016-0.023
+- **Vector with entity_types=["entity"]:** 5 results — Core Service Implementation, SPEC-13 CLI Auth, Coding Guide, Authentication Service, ADR Production Auth. Scores ~0.55-0.60
+- **Observation:** Hybrid surfaces different top results than vector-only. Hybrid found RLS and Cloud Readiness docs that vector didn't prioritize. Different ranking is expected from RRF fusion.
+- **Verdict:** PASS — hybrid produces meaningfully different ranking
+
+---
+
+### Test 5: Result Types
+
+#### 5a: Vector returns all result types
+- **Input:** query="keeping AI context between sessions", search_type="vector"
+- **Entities:** SPEC-18 AI Memory Management Tool (type=entity)
+- **Relations:** Prompt Builder integrates_with (type=relation)
+- **Observations:** "Translation layer is key" (type=observation), "Maintaining context across conversation boundaries" (type=observation)
+- **Verdict:** PASS — all three types appear in vector results
+
+#### 5b: Observations carry metadata
+- **Observation result:** category="challenge", content="Maintaining context across conversation boundaries", from_entity="research/ai-knowledge-management-research"
+- **Verdict:** PASS — category, content, from_entity, tags all present
+
+#### 5c: Relations carry link info
+- **Relation result:** relation_type="integrates_with", from_entity="development/features/prompt-builder...", to_entity (present but truncated in some)
+- **Verdict:** PASS — relation metadata present
+
+---
+
+### Test 6: Filters + Vector Search
+
+#### 6a: entity_types=["entity"] with vector
+- **Input:** query="OAuth authentication", search_type="vector", entity_types=["entity"]
+- **Actual:** 5 results, all type="entity" (Core Service Implementation, SPEC-13, Coding Guide, Authentication Service, ADR Auth)
+- **Verdict:** PASS — filter correctly restricts to entities only
+
+#### 6b: types=["note"] with vector
+- **Input:** query="OAuth authentication", search_type="vector", types=["note"]
+- **Actual:** Same 5 results (all have entity_type="note" in metadata)
+- **Verdict:** PASS — types filter works with vector search
+
+#### 6c: after_date with vector
+- **Input:** query="OAuth authentication", search_type="vector", after_date="2025-06-01"
+- **Actual:** 3 results — Core Service Implementation, Cloud Web App analysis observation, SPEC-13. Filtered out older OAuth docs.
+- **Verdict:** PASS — date filter applied correctly
+
+#### 6d: entity_types=["entity"] with hybrid
+- **Input:** query="OAuth authentication", search_type="hybrid", entity_types=["entity"]
+- **Actual:** 5 results, all type="entity" — RLS lessons, Cloud Readiness, AUTH.md OAuth, Core Service, OAuth Rip-and-Replace
+- **Verdict:** PASS — filter works with hybrid mode too
+
+#### 6e: types=["entity"] with vector (WRONG filter name)
+- **Input:** query="OAuth authentication", search_type="vector", types=["entity"]
+- **Actual:** 0 results
+- **Note:** `types` filters by entity_type metadata (e.g., "note", "person"), NOT by SearchItemType. Using types=["entity"] looks for entity_type="entity" which few/no notes have. This is a UX confusion point — the param names are ambiguous.
+- **Verdict:** PASS (correct behavior) but USABILITY ISSUE — easy to confuse types vs entity_types
+
+---
+
+### Test 7: Edge Cases
+
+#### 7a: Single character query
+- **Input:** query="x", search_type="vector"
+- **Actual:** 3 results — "Self-contained application bundle" observation, Non-Markdown File Support relation, quick-win-tools entity. Scores ~0.57-0.59
+- **Note:** Single character still produces an embedding and returns results. Quality is low/random as expected.
+- **Verdict:** PASS (no crash, returns results)
+
+#### 7b: Whitespace-only query
+- **Input:** query="   ", search_type="vector"
+- **Actual:** 0 results
+- **Verdict:** PASS (handled gracefully — _check_vector_eligible strips and rejects empty)
+
+#### 7c: Query with no relevant content
+- **Input:** query="quantum computing blockchain", search_type="vector"
+- **Actual:** 3 results — Inter-Agent Communication relation, Self-contained bundle observation, JSON-LD interop observation. Scores ~0.54
+- **Note:** Still returns results because vector search always finds nearest neighbors. Scores are lower (~0.54) than relevant queries (~0.58-0.60). No relevance threshold applied.
+- **Verdict:** PASS (expected behavior) but NOTE — no relevance cutoff means irrelevant queries always return something
+
+---
+
+### Test 8: Pagination
+
+#### 8a: Vector search page 2
+- **Input:** query="keeping AI context between sessions", search_type="vector", page=2, page_size=3
+- **Actual:** 3 results on page 2, current_page=2. Different results from page 1. Top: "Maintaining context across conversation boundaries" observation (score 0.587)
+- **Note:** Interestingly, page 2 had a higher-scoring result than some page 1 results. This may indicate pagination doesn't sort globally — it might be paginating within a pre-scored set.
+- **Verdict:** PASS (pagination works) but POSSIBLE ISSUE — result ordering across pages needs investigation
+
+---
+
+## Summary
+
+### Passing Tests: 20/21
+
+### Bugs Found
+1. **search_type="semantic" silently falls through** (Test 1a) — Invalid search_type values fall to the `else` branch and default to text search without any warning. Should either alias "semantic" to "vector" or raise an error.
+
+### Usability Issues
+2. **types vs entity_types confusion** (Test 6e) — `types` filters by entity_type metadata (note, person, etc.) while `entity_types` filters by SearchItemType (entity, observation, relation). The naming is ambiguous and easy to mix up.
+3. **No relevance threshold** (Test 7c) — Vector search always returns nearest neighbors even for completely irrelevant queries. Consider adding a minimum score threshold or at least documenting expected score ranges.
+4. **Hybrid ranking for single keywords** (Test 3b) — Hybrid mode on simple keyword queries produced less intuitive rankings than pure FTS or pure vector. The RRF fusion may dilute strong FTS signals.
+
+### Observations
+- Vector search successfully finds conceptually related content that FTS misses entirely
+- Score ranges: relevant queries ~0.56-0.60, irrelevant queries ~0.54 (narrow spread)
+- All three result types (entity, observation, relation) appear correctly in vector results
+- Filters (entity_types, types, after_date) all work correctly with vector and hybrid modes
+- Pagination works but cross-page ordering may need investigation

docs/semantic-search.md

@@ -0,0 +1,270 @@
+# Semantic Search
+
+This guide covers Basic Memory's semantic (vector) search feature, which adds meaning-based retrieval alongside the existing full-text search.
+
+## Overview
+
+Basic Memory's search supports both full-text search (FTS) and semantic retrieval. Semantic search adds vector embeddings that capture the *meaning* of your content, enabling:
+
+- **Paraphrase matching**: Find "authentication flow" when searching for "login process"
+- **Conceptual queries**: Search for "ways to improve performance" and find notes about caching, indexing, and optimization
+- **Hybrid retrieval**: Combine the precision of keyword search with the recall of semantic similarity
+
+Semantic search is enabled by default when semantic dependencies are available at runtime. It works on both SQLite (local) and Postgres (cloud) backends.
+
+## Installation
+
+Semantic search dependencies (fastembed, sqlite-vec, openai) are included in the default `basic-memory` install.
+
+```bash
+pip install basic-memory
+```
+
+You can always override with `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true|false`.
+
+### Platform Compatibility
+
+| Platform | FastEmbed (local) | OpenAI (API) |
+|---|---|---|
+| macOS ARM64 (Apple Silicon) | Yes | Yes |
+| macOS x86_64 (Intel Mac) | No — see workaround below | Yes |
+| Linux x86_64 | Yes | Yes |
+| Linux ARM64 | Yes | Yes |
+| Windows x86_64 | Yes | Yes |
+
+#### Intel Mac Workaround
+
+The default install includes FastEmbed, which depends on ONNX Runtime. ONNX Runtime dropped Intel Mac (x86_64) wheels starting in v1.24, so install with a compatible ONNX Runtime pin first:
+
+```bash
+pip install basic-memory 'onnxruntime<1.24'
+```
+
+After installation, Intel Mac users have two runtime options:
+
+**Option 1: Use OpenAI embeddings (recommended)**
+
+```bash
+export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
+export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai
+export OPENAI_API_KEY=sk-...
+```
+
+**Option 2: Use FastEmbed locally**
+
+Keep the same pinned installation and use FastEmbed (default provider):
+
+```bash
+export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
+export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=fastembed
+```
+
+## Quick Start
+
+1. Install Basic Memory:
+
+```bash
+pip install basic-memory
+```
+
+2. (Optional) Explicitly enable semantic search:
+
+```bash
+export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
+```
+
+3. Build vector embeddings for your existing content:
+
+```bash
+bm reindex --embeddings
+```
+
+4. Search using semantic modes:
+
+```python
+# Pure vector similarity
+search_notes("login process", search_type="vector")
+
+# Hybrid: combines FTS precision with vector recall (recommended)
+search_notes("login process", search_type="hybrid")
+
+# Explicit full-text search
+search_notes("login process", search_type="text")
+```
+
+## Configuration Reference
+
+All settings are fields on `BasicMemoryConfig` and can be set via environment variables (prefixed with `BASIC_MEMORY_`).
+
+| Config Field | Env Var | Default | Description |
+|---|---|---|---|
+| `semantic_search_enabled` | `BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED` | Auto (`true` when semantic deps are available) | Enable semantic search. Required before vector/hybrid modes work. |
+| `semantic_embedding_provider` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER` | `"fastembed"` | Embedding provider: `"fastembed"` (local) or `"openai"` (API). |
+| `semantic_embedding_model` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL` | `"bge-small-en-v1.5"` | Model identifier. Auto-adjusted per provider if left at default. |
+| `semantic_embedding_dimensions` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_DIMENSIONS` | Auto-detected | Vector dimensions. 384 for FastEmbed, 1536 for OpenAI. Override only if using a non-default model. |
+| `semantic_embedding_batch_size` | `BASIC_MEMORY_SEMANTIC_EMBEDDING_BATCH_SIZE` | `64` | Number of texts to embed per batch. |
+| `semantic_vector_k` | `BASIC_MEMORY_SEMANTIC_VECTOR_K` | `100` | Candidate count for vector nearest-neighbour retrieval. Higher values improve recall at the cost of latency. |
+
+## Embedding Providers
+
+### FastEmbed (default)
+
+FastEmbed runs entirely locally using ONNX models — no API key, no network calls, no cost.
+
+- **Model**: `BAAI/bge-small-en-v1.5`
+- **Dimensions**: 384
+- **Tradeoff**: Smaller model, fast inference, good quality for most use cases
+
+```bash
+# Install basic-memory and enable semantic search
+pip install basic-memory
+export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
+```
+
+### OpenAI
+
+Uses OpenAI's embeddings API for higher-dimensional vectors. Requires an API key.
+
+- **Model**: `text-embedding-3-small`
+- **Dimensions**: 1536
+- **Tradeoff**: Higher quality embeddings, requires API calls and an OpenAI key
+
+```bash
+export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
+export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai
+export OPENAI_API_KEY=sk-...
+```
+
+When switching from FastEmbed to OpenAI (or vice versa), you must rebuild embeddings since the vector dimensions differ:
+
+```bash
+bm reindex --embeddings
+```
+
+## Search Modes
+
+### `text` (default)
+
+Full-text keyword search using FTS5 (SQLite) or tsvector (Postgres). Supports boolean operators (`AND`, `OR`, `NOT`), phrase matching, and prefix wildcards.
+
+```python
+search_notes("project AND planning", search_type="text")
+```
+
+This is the existing default and does not require semantic search to be enabled.
+
+### `vector`
+
+Pure semantic similarity search. Embeds your query and finds the nearest content vectors. Good for conceptual or paraphrase queries where exact keywords may not appear in the content.
+
+```python
+search_notes("how to speed up the app", search_type="vector")
+```
+
+Returns results ranked by cosine similarity. Individual observations and relations surface as first-class results, not collapsed into parent entities.
+
+### `hybrid`
+
+Combines FTS and vector results using score-based fusion. This is generally the best mode when you want both keyword precision and semantic recall.
+
+```python
+search_notes("authentication security", search_type="hybrid")
+```
+
+Score-based fusion uses the formula `max(vec, fts) + bonus * min(vec, fts)` to preserve the dominant signal while rewarding results found by both methods.
+
+### When to Use Which
+
+| Mode | Best For |
+|---|---|
+| `text` | Exact keyword matching, boolean queries, tag/category searches |
+| `vector` | Conceptual queries, paraphrase matching, exploratory searches |
+| `hybrid` | General-purpose search combining precision and recall |
+
+## The Reindex Command
+
+The `bm reindex` command rebuilds search indexes without dropping the database.
+
+```bash
+# Rebuild everything (FTS + embeddings if semantic is enabled)
+bm reindex
+
+# Only rebuild vector embeddings
+bm reindex --embeddings
+
+# Only rebuild the full-text search index
+bm reindex --search
+
+# Target a specific project
+bm reindex -p my-project
+```
+
+### When You Need to Reindex
+
+- **Upgrade note**: Migration now performs a one-time automatic embedding backfill on upgrade.
+- **Manual enable case**: If you explicitly had `semantic_search_enabled=false` and then turn it on
+- **Provider change**: After switching between `fastembed` and `openai`
+- **Model change**: After changing `semantic_embedding_model`
+- **Dimension change**: After changing `semantic_embedding_dimensions`
+
+The reindex command shows progress with embedded/skipped/error counts:
+
+```
+Project: main
+  Building vector embeddings...
+  ✓ Embeddings complete: 142 entities embedded, 0 skipped, 0 errors
+
+Reindex complete!
+```
+
+## How It Works
+
+### Chunking
+
+Each entity in the search index is split into semantic chunks before embedding:
+
+- **Headers**: Markdown headers (`#`, `##`, etc.) start new chunks
+- **Bullets**: Each bullet item (`-`, `*`) becomes its own chunk for granular fact retrieval
+- **Prose sections**: Non-bullet text is merged up to ~900 characters per chunk
+- **Long sections**: Oversized content is split with ~120 character overlap to preserve context at boundaries
+
+Each search index item type (entity, observation, relation) is chunked independently, so observations and relations are embeddable as discrete facts.
+
+### Deduplication
+
+Each chunk has a `source_hash` (SHA-256 of the chunk text). On re-sync, unchanged chunks skip re-embedding entirely. This makes incremental updates fast — only modified content triggers API calls or model inference.
+
+### Hybrid Fusion
+
+Hybrid search uses score-based fusion to merge FTS and vector results:
+
+1. Run FTS search to get keyword-ranked results; normalize scores to [0, 1]
+2. Run vector search to get similarity-ranked results (already [0, 1])
+3. For each result, compute: `fused = max(vec_score, fts_score) + 0.3 * min(vec_score, fts_score)`
+4. Sort by fused score
+
+The dominant signal (whichever source scored higher) is preserved, and dual-source agreement adds a bonus. Unlike rank-based fusion, this approach retains score magnitude — a strong vector match stays strong even without an FTS hit.
+
+### Observation-Level Results
+
+Vector and hybrid modes return individual observations and relations as first-class search results, not just parent entities. This means a search for "water temperature for brewing" can surface the specific observation about 205°F without returning the entire "Coffee Brewing Methods" entity.
+
+## Database Backends
+
+### SQLite (local)
+
+- **Vector storage**: [sqlite-vec](https://github.com/asg017/sqlite-vec) virtual table
+- **Table creation**: At runtime when semantic search is first used — no migration needed
+- **Embedding table**: `search_vector_embeddings` using `vec0(embedding float[N])` where N is the configured dimensions
+- **Chunk metadata**: `search_vector_chunks` table stores chunk text, keys, and source hashes
+
+The sqlite-vec extension is loaded per-connection. Vector tables are created lazily on first use.
+
+### Postgres (cloud)
+
+- **Vector storage**: [pgvector](https://github.com/pgvector/pgvector) with HNSW indexing
+- **Chunk metadata table**: Created via Alembic migration (`search_vector_chunks` with `BIGSERIAL` primary key)
+- **Embedding table**: `search_vector_embeddings` created at runtime (dimension-dependent, same pattern as SQLite)
+- **Index**: HNSW index on the embedding column for fast approximate nearest-neighbour queries
+
+The Alembic migration creates the dimension-independent chunks table. The embeddings table and HNSW index are deferred to runtime because they depend on the configured vector dimensions.

docs/specs/SPEC-LOCAL-PLUS-PUBLISH.md

@@ -0,0 +1,225 @@
+# SPEC-LOCAL-PLUS-PUBLISH: Local+ Published Notes and Privacy Tiers
+
+**Status:** Draft  
+**Date:** 2026-02-14  
+**Owner:** Basic Memory
+
+## Summary
+
+Add a paid Local+ feature that lets users publish selected notes to shareable URLs while keeping the
+main knowledge base local-first. Use this as a product wedge for users who do not want full cloud
+hosting but do want collaboration and distribution features.
+
+This spec also captures a practical position on "zero knowledge" for Local+.
+
+## Context
+
+Basic Memory already has strong local-first primitives and optional cloud routing/sync. A recurring
+request is:
+
+- keep knowledge local by default,
+- pay for selective value-add,
+- share specific outputs externally.
+
+Published Notes fits this model: explicit per-note opt-in, reversible, and easy to understand.
+
+## Goals
+
+1. Provide an Obsidian Publish-style sharing experience for selected notes.
+2. Keep local markdown files as source of truth.
+3. Make sharing compatible with current cloud/auth/billing primitives.
+4. Define clear Local+ packaging that does not degrade OSS local workflows.
+5. Document zero-knowledge constraints so product decisions are explicit.
+
+## Non-Goals
+
+1. Full hosted editing for all notes (Cloud Full remains separate).
+2. Public website builder/CMS features.
+3. Strict cryptographic zero-knowledge server processing for MCP/search in v1.
+
+## Local+ Feature Catalog (Sellable)
+
+Core Local+ candidates:
+
+1. Published Notes (share URL, revoke, expiry, password).
+2. Snapshot Time Machine (point-in-time restore for local projects).
+3. Recovery Drill Reports (automated restore verification).
+4. Device/API Key Governance (per-device keys, revocation, audit trail).
+5. BYO Storage Orchestration (managed setup for user-owned object storage).
+6. Semantic Boost Add-on (higher quality retrieval options while files remain source-of-truth).
+
+Team-oriented add-ons:
+
+1. Team-owned shared links and domain branding.
+2. Role-based publish permissions.
+3. Shared workspace policies for what can be published.
+
+## Proposed MVP: Published Notes
+
+### User Experience
+
+Per note actions:
+
+1. Publish.
+2. Unpublish.
+3. Copy URL.
+4. Regenerate URL.
+5. Set visibility and controls.
+
+Controls:
+
+1. Visibility: `unlisted` (default) or `public`.
+2. Optional password gate.
+3. Optional expiration datetime.
+4. Optional "disable indexing" flag for public mode.
+
+Behavior:
+
+1. Source note remains local markdown.
+2. Publish is explicit opt-in per note.
+3. Unpublish removes public access immediately.
+4. Republish creates a new URL token unless user chooses to keep current URL.
+
+### URL Model
+
+1. Unlisted share URL: high-entropy token path.
+2. Public URL: slug path (optional, later phase).
+3. Team plans can support custom domain mapping in later phase.
+
+### Content Model
+
+v1 published page includes:
+
+1. Rendered markdown body.
+2. Optional metadata (title, updated_at).
+
+v1 excludes:
+
+1. Full graph traversal expansion.
+2. Related note auto-discovery on public pages.
+
+### Sync Model
+
+1. Local file remains canonical.
+2. Publish stores a rendered snapshot plus metadata in cloud.
+3. Update path:
+   - manual "update published version", or
+   - optional auto-update on note change (plan-gated).
+
+## Architecture (v1)
+
+### High-Level Flow
+
+1. Client selects a note to publish.
+2. Client sends publish request with note identifier and policy.
+3. Service resolves note content (local sync artifact or explicit upload payload).
+4. Service stores published artifact and returns share URL.
+
+### Data Model
+
+`published_notes`
+
+1. `id` (uuid)
+2. `tenant_id` or `workspace_id`
+3. `project_id`
+4. `entity_permalink` (or stable external_id)
+5. `share_token` (hashed in DB)
+6. `visibility` (`unlisted`|`public`)
+7. `password_hash` (nullable)
+8. `expires_at` (nullable)
+9. `is_active`
+10. `published_content` (rendered snapshot or reference)
+11. `published_at`
+12. `updated_at`
+
+### API Shape (Draft)
+
+1. `POST /api/published-notes`
+2. `GET /api/published-notes`
+3. `GET /api/published-notes/{id}`
+4. `PATCH /api/published-notes/{id}`
+5. `DELETE /api/published-notes/{id}` (unpublish)
+6. `POST /api/published-notes/{id}/regenerate-url`
+7. `GET /p/{token}` (public resolver)
+
+### CLI Shape (Draft)
+
+1. `bm cloud publish <identifier>`
+2. `bm cloud publish list`
+3. `bm cloud publish update <id>`
+4. `bm cloud publish unpublish <id>`
+5. `bm cloud publish rotate-url <id>`
+
+### Security
+
+1. Default to unlisted URLs.
+2. Store only hashed share tokens.
+3. Passwords hashed server-side.
+4. Enforce expiration at request time.
+5. Log publish/unpublish/rotate events for auditability.
+
+## Packaging and Pricing Direction
+
+Suggested split:
+
+1. OSS Local: no publish URLs.
+2. Local+ Solo: publish URLs + snapshots + recovery.
+3. Local+ Team: solo features + team governance and branding.
+4. Cloud Full: hosted app + full cloud workflows.
+
+Key message:
+"Keep everything local. Publish only what you choose."
+
+## Rollout Plan
+
+1. Phase 1: Unlisted publish URLs + unpublish + regenerate URL.
+2. Phase 2: Password/expiry controls.
+3. Phase 3: Auto-update on note change and basic analytics.
+4. Phase 4: Team branding/domains/policies.
+
+## Zero-Knowledge Position
+
+### Strict Zero-Knowledge Definition
+
+Strict zero-knowledge means the server cannot decrypt note content at all.
+
+### Why This Conflicts with MCP and Search
+
+If server cannot decrypt:
+
+1. MCP tool execution against cloud content cannot read/write semantic content.
+2. Full-text search cannot index plaintext content.
+3. Semantic/vector search cannot generate or query embeddings on plaintext.
+4. Server-side relation resolution and context building become severely limited.
+
+This matches earlier findings: strict zero-knowledge materially handicaps MCP-driven behavior and
+search quality.
+
+### Viable Alternatives (Not Strict Zero-Knowledge)
+
+1. Encryption at rest/in transit with server-side decrypt in trusted runtime.
+   - Preserves MCP/search quality.
+   - Not zero-knowledge cryptographically.
+
+2. Client-side retrieval mode.
+   - Keep MCP/search local; cloud is sync/share/backup relay.
+   - Best for privacy-first users.
+   - Requires local agent availability for advanced retrieval.
+
+3. Limited encrypted indexing.
+   - Blind indexes for exact keywords only.
+   - No high-quality semantic search.
+   - Usually poor UX for natural-language memory recall.
+
+### Recommendation
+
+For Local+:
+
+1. Do not promise strict zero-knowledge for cloud MCP/search paths.
+2. Offer a privacy-first local mode where advanced retrieval stays local.
+3. Clearly label tradeoffs:
+   - "Local private mode" (best privacy, best local retrieval).
+   - "Cloud-assisted mode" (best cross-device/MCP consistency, trusted-runtime decrypt).
+
+This keeps messaging honest and avoids repeating the known incompatibility.
+

docs/specs/SPEC-SCHEMA-IMPL.md

@@ -0,0 +1,368 @@
+# SPEC-SCHEMA-IMPL: Schema System Implementation Plan
+
+**Status:** Draft
+**Created:** 2025-02-06
+**Branch:** `feature/schema-system`
+**Depends on:** [SPEC-SCHEMA](SPEC-SCHEMA.md)
+
+## Overview
+
+Implementation plan for the Basic Memory Schema System. The system is entirely programmatic —
+no LLM agent runtime or API key required. The LLM already in the user's session (Claude Code,
+Claude Desktop, etc.) provides the intelligence layer by reading schema notes via existing
+MCP tools.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│                   Entry Points                   │
+│  CLI (bm schema ...)  │  MCP (schema_validate)  │
+└──────────┬────────────┴──────────┬──────────────┘
+           │                       │
+           ▼                       ▼
+┌─────────────────────────────────────────────────┐
+│              Schema Service Layer                │
+│  resolve_schema · validate · infer · diff        │
+└──────────┬────────────────────────┬──────────────┘
+           │                       │
+           ▼                       ▼
+┌──────────────────────┐ ┌────────────────────────┐
+│   Picoschema Parser  │ │   Note/Entity Access   │
+│  YAML → SchemaModel  │ │  (existing repository) │
+└──────────────────────┘ └────────────────────────┘
+```
+
+No new database tables. Schemas are notes with `type: schema` — they're already indexed.
+Validation reads observations and relations from existing data.
+
+## Components
+
+### 1. Picoschema Parser
+
+**Location:** `src/basic_memory/schema/parser.py`
+
+Parses Picoschema YAML into an internal representation.
+
+```python
+@dataclass
+class SchemaField:
+    name: str
+    type: str                    # string, integer, number, boolean, any, or EntityName
+    required: bool               # True unless field name ends with ?
+    is_array: bool               # True if (array) notation
+    is_enum: bool                # True if (enum) notation
+    enum_values: list[str]       # Populated for enums
+    description: str | None      # Text after comma
+    is_entity_ref: bool          # True if type is capitalized (entity reference)
+    children: list[SchemaField]  # For (object) types
+
+
+@dataclass
+class SchemaDefinition:
+    entity: str                  # The entity type this schema describes
+    version: int                 # Schema version
+    fields: list[SchemaField]    # Parsed fields
+    validation_mode: str         # "warn" | "strict" | "off"
+    frontmatter_fields: list[SchemaField]  # From settings.frontmatter (default: [])
+
+
+def parse_picoschema(yaml_dict: dict) -> list[SchemaField]:
+    """Parse a Picoschema YAML dict into a list of SchemaField objects."""
+
+
+def parse_schema_note(frontmatter: dict) -> SchemaDefinition:
+    """Parse a full schema note's frontmatter into a SchemaDefinition."""
+```
+
+**Input/Output:**
+```yaml
+# Input (YAML dict from frontmatter)
+schema:
+  name: string, full name
+  role?: string, job title
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+```
+
+```python
+# Output
+[
+    SchemaField(name="name", type="string", required=True, description="full name", ...),
+    SchemaField(name="role", type="string", required=False, description="job title", ...),
+    SchemaField(name="works_at", type="Organization", required=False, is_entity_ref=True, ...),
+    SchemaField(name="expertise", type="string", required=False, is_array=True, ...),
+]
+```
+
+### 2. Schema Resolver
+
+**Location:** `src/basic_memory/schema/resolver.py`
+
+Finds the applicable schema for a note using the resolution order.
+
+```python
+async def resolve_schema(
+    note_frontmatter: dict,
+    search_fn: Callable,          # injected search capability
+) -> SchemaDefinition | None:
+    """Resolve schema for a note.
+
+    Resolution order:
+    1. Inline schema (frontmatter['schema'] is a dict)
+    2. Explicit reference (frontmatter['schema'] is a string)
+    3. Implicit by type (frontmatter['type'] → schema note with matching entity)
+    4. No schema (returns None)
+    """
+```
+
+### 3. Schema Validator
+
+**Location:** `src/basic_memory/schema/validator.py`
+
+Validates a note's observations and relations against a resolved schema.
+
+```python
+@dataclass
+class FieldResult:
+    field: SchemaField
+    status: str                  # "present" | "missing" | "type_mismatch"
+    values: list[str]            # Matched observation values or relation targets
+    message: str | None          # Human-readable detail
+
+
+@dataclass
+class ValidationResult:
+    note_identifier: str
+    schema_entity: str
+    passed: bool                 # True if no errors (warnings are OK)
+    field_results: list[FieldResult]
+    unmatched_observations: dict[str, int]   # category → count
+    unmatched_relations: list[str]           # relation types not in schema
+    warnings: list[str]
+    errors: list[str]
+
+
+async def validate_note(
+    note: Note,
+    schema: SchemaDefinition,
+    frontmatter: dict | None = None,
+) -> ValidationResult:
+    """Validate a note against a schema definition.
+
+    Mapping rules:
+    - field: string              → observation [field] exists
+    - field?(array): type        → multiple [field] observations
+    - field?: EntityType         → relation 'field [[...]]' exists
+    - field?(enum): [v]          → observation [field] value ∈ enum values
+    - settings.frontmatter field → frontmatter key presence/value
+    """
+```
+
+### 4. Schema Inference Engine
+
+**Location:** `src/basic_memory/schema/inference.py`
+
+Analyzes notes of a given type and suggests a schema based on usage frequency.
+
+```python
+@dataclass
+class FieldFrequency:
+    name: str
+    source: str                  # "observation" | "relation"
+    count: int                   # notes containing this field
+    total: int                   # total notes analyzed
+    percentage: float
+    sample_values: list[str]     # representative values
+    is_array: bool               # True if typically appears multiple times per note
+    target_type: str | None      # For relations, the most common target entity type
+
+
+@dataclass
+class InferenceResult:
+    entity_type: str
+    notes_analyzed: int
+    field_frequencies: list[FieldFrequency]
+    suggested_schema: dict       # Ready-to-use Picoschema YAML dict
+    suggested_required: list[str]
+    suggested_optional: list[str]
+    excluded: list[str]          # Below threshold
+
+
+async def infer_schema(
+    entity_type: str,
+    notes: list[Note],
+    required_threshold: float = 0.95,   # 95%+ = required
+    optional_threshold: float = 0.25,   # 25%+ = optional
+) -> InferenceResult:
+    """Analyze notes and suggest a Picoschema definition."""
+```
+
+### 5. Schema Diff
+
+**Location:** `src/basic_memory/schema/diff.py`
+
+Compares current note usage against an existing schema definition.
+
+```python
+@dataclass
+class SchemaDrift:
+    new_fields: list[FieldFrequency]       # Fields not in schema but common in notes
+    dropped_fields: list[FieldFrequency]   # Fields in schema but rare in notes
+    cardinality_changes: list[str]         # one → many or many → one
+    type_mismatches: list[str]             # observation values don't match declared type
+
+
+async def diff_schema(
+    schema: SchemaDefinition,
+    notes: list[Note],
+) -> SchemaDrift:
+    """Compare a schema against actual note usage to detect drift."""
+```
+
+## Entry Points
+
+### CLI Commands
+
+**Location:** `src/basic_memory/cli/schema.py`
+
+```python
+import typer
+
+schema_app = typer.Typer(name="schema", help="Schema management commands")
+
+@schema_app.command()
+async def validate(
+    target: str = typer.Argument(None, help="Note path or entity type"),
+    strict: bool = typer.Option(False, help="Override to strict mode"),
+):
+    """Validate notes against their schemas."""
+
+@schema_app.command()
+async def infer(
+    entity_type: str = typer.Argument(..., help="Entity type to analyze"),
+    threshold: float = typer.Option(0.25, help="Minimum frequency for optional fields"),
+    save: bool = typer.Option(False, help="Save to schema/ directory"),
+):
+    """Infer schema from existing notes of a type."""
+
+@schema_app.command()
+async def diff(
+    entity_type: str = typer.Argument(..., help="Entity type to diff"),
+):
+    """Show drift between schema and actual usage."""
+```
+
+Registered as subcommand: `bm schema validate`, `bm schema infer`, `bm schema diff`.
+
+### MCP Tools
+
+**Location:** `src/basic_memory/mcp/tools/schema.py`
+
+```python
+@mcp_tool
+async def schema_validate(
+    entity_type: str | None = None,
+    identifier: str | None = None,
+    project: str | None = None,
+) -> str:
+    """Validate notes against their resolved schema."""
+
+@mcp_tool
+async def schema_infer(
+    entity_type: str,
+    threshold: float = 0.25,
+    project: str | None = None,
+) -> str:
+    """Analyze existing notes and suggest a schema definition."""
+```
+
+### API Endpoints
+
+**Location:** `src/basic_memory/api/schema_router.py`
+
+```python
+router = APIRouter(prefix="/schema", tags=["schema"])
+
+@router.post("/validate")
+async def validate_schema(...) -> ValidationReport: ...
+
+@router.post("/infer")
+async def infer_schema(...) -> InferenceResult: ...
+
+@router.get("/diff/{entity_type}")
+async def diff_schema(...) -> SchemaDrift: ...
+```
+
+MCP tools call these endpoints via the typed client pattern (consistent with existing
+architecture).
+
+## Implementation Phases
+
+### Phase 1: Parser + Resolver
+
+Build the foundation — can parse Picoschema and find schemas for notes.
+
+**Deliverables:**
+- `schema/parser.py` — Picoschema YAML → `SchemaDefinition`
+- `schema/resolver.py` — Resolution order (inline → explicit ref → implicit by type → none)
+- Unit tests for all Picoschema syntax variations
+- Unit tests for resolution order
+
+**No external dependencies.** Pure Python parsing of YAML dicts. Can develop and test
+in isolation.
+
+### Phase 2: Validator
+
+Connect schemas to notes and produce validation results.
+
+**Deliverables:**
+- `schema/validator.py` — Validate note observations/relations against schema fields
+- API endpoint: `POST /schema/validate`
+- MCP tool: `schema_validate`
+- CLI command: `bm schema validate`
+- Integration tests with real notes and schemas
+
+**Depends on:** Phase 1 (parser + resolver)
+
+### Phase 3: Inference
+
+Analyze existing notes to suggest schemas.
+
+**Deliverables:**
+- `schema/inference.py` — Frequency analysis across notes of a type
+- API endpoint: `POST /schema/infer`
+- MCP tool: `schema_infer`
+- CLI command: `bm schema infer`
+- Option to save inferred schema as a note via `write_note`
+
+**Depends on:** Phase 1 (parser for output format)
+
+### Phase 4: Diff
+
+Compare schemas against current usage.
+
+**Deliverables:**
+- `schema/diff.py` — Drift detection between schema and actual notes
+- API endpoint: `GET /schema/diff/{entity_type}`
+- CLI command: `bm schema diff`
+
+**Depends on:** Phase 1 (parser), Phase 3 (inference, for frequency analysis)
+
+## Testing Strategy
+
+- **Unit tests** (`tests/schema/`): Parser edge cases, resolution logic, validation mapping,
+  inference thresholds
+- **Integration tests** (`test-int/schema/`): End-to-end with real markdown files, schema notes
+  on disk, CLI invocation
+- Coverage target: 100% (consistent with project standard)
+
+## What This Does NOT Include
+
+- No new database tables or migrations
+- No new markdown syntax (schemas validate existing observations/relations)
+- No LLM agent runtime or API key management
+- No hook integration (deferred)
+- No schema composition/inheritance (deferred)
+- No OWL/RDF export (deferred)
+- No built-in templates (deferred)

docs/specs/SPEC-SCHEMA.md

@@ -0,0 +1,492 @@
+# SPEC-SCHEMA: Basic Memory Schema System
+
+**Status:** Draft
+**Created:** 2025-02-06
+**Branch:** `feature/schema-system`
+
+## Summary
+
+A schema system for Basic Memory that uses [Picoschema](https://genkit.dev/docs/dotprompt/)
+syntax in YAML frontmatter. Schemas validate notes against their existing observation/relation
+structure — no new data model, no migration, just a declarative lens over what's already there.
+
+## Core Principles
+
+1. **Schemas are just notes** — A schema is a note with `type: schema`, lives anywhere
+2. **Use prior art** — Picoschema syntax in YAML frontmatter, no custom notation
+3. **Validation maps to existing format** — Observations and relations, not a parallel data model
+4. **Validation is soft** — Warnings by default, not blocking errors
+5. **Inference over prescription** — Schemas describe reality, emerge from usage
+6. **No built-in agent** — Programmatic core; the LLM already in the session provides intelligence
+
+## Picoschema Syntax
+
+Picoschema is a compact schema notation from Google's Dotprompt that fits naturally in YAML
+frontmatter.
+
+### Supported Types
+
+| Type | Description |
+|------|-------------|
+| `string` | Text value |
+| `integer` | Whole number |
+| `number` | Decimal number |
+| `boolean` | True/false |
+| `any` | Any scalar type |
+| `EntityName` | Reference to another entity (capitalized = entity reference) |
+
+### Syntax Rules
+
+```yaml
+schema:
+  name: string, full name                # required field with description
+  email?: string, contact email           # ? = optional
+  role?: string, job title
+  works_at?: Organization, employer       # capitalized type = entity reference
+  tags?(array): string, categories        # array of type
+  status?(enum): [active, inactive]       # enum with allowed values
+  metadata?(object):                      # nested object
+    updated_at?: string
+    source?: string
+```
+
+- `field: type` — required field
+- `field?: type` — optional field
+- `field(array): type` — array of values
+- `field?(enum): [values]` — enumeration
+- `field?(object):` — nested object with sub-fields
+- `, description` — description after comma
+- `EntityName` as type (capitalized) — reference to another entity
+
+## Schema-to-Note Mapping
+
+Schemas validate against the existing Basic Memory note format. No new syntax for note
+authors to learn.
+
+### Mapping Rules
+
+| Schema Declaration | Grounded In | Example Match |
+|--------------------|-------------|---------------|
+| `field: string` | Observation `[field] value` | `- [name] Paul Graham` |
+| `field?(array): string` | Multiple `[field]` observations | `- [expertise] Lisp` (×N) |
+| `field?: EntityType` | Relation `field [[Target]]` | `- works_at [[Y Combinator]]` |
+| `field?(array): EntityType` | Multiple `field` relations | `- authored [[Book]]` (×N) |
+| `tags` | Frontmatter `tags` array | `tags: [startups, essays]` |
+| `field?(enum): [values]` | Observation `[field] value` where value ∈ set | `- [status] active` |
+| `settings.frontmatter` field | Frontmatter key presence/value | `tags: [python, ai]` |
+
+### Key Insight
+
+Schemas don't introduce a new way to store data. They describe the patterns already present
+in observations and relations. A note doesn't have to change how it's written — the schema
+just says "a good Person note has a `[name]` observation and a `works_at` relation."
+
+## Schema Definition
+
+### As a Dedicated Schema Note
+
+```yaml
+# schema/Person.md
+---
+title: Person
+type: schema
+entity: Person
+version: 1
+schema:
+  name: string, full name
+  email?: string, contact email
+  role?: string, job title
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+settings:
+  validation: warn    # warn | strict | off
+  frontmatter:
+    tags?(array): string, note categories
+    status?(enum): [draft, review, published]
+---
+
+# Person
+
+A human individual in the knowledge graph.
+
+Any documentation about this entity type goes here as prose.
+```
+
+Schema notes are regular Basic Memory notes. They show up in search, can have their own
+observations and relations, and can be organized in any folder (though `schema/` is
+the suggested convention).
+
+### Inline Schema in a Note
+
+Notes can carry their own schema directly:
+
+```yaml
+# meetings/2024-01-15-standup.md
+---
+title: Team Standup 2024-01-15
+type: meeting
+schema:
+  attendees(array): string, who was there
+  decisions(array): string, what was decided
+  action_items(array): string, follow-ups
+  blockers?(array): string, anything stuck
+---
+
+# Team Standup 2024-01-15
+
+## Observations
+- [attendees] Paul
+- [attendees] Sarah
+- [decisions] Ship v2 by Friday
+- [action_items] Paul to review PR #42
+- [blockers] Waiting on API credentials
+```
+
+Good for one-off structured notes or prototyping a schema before extracting it.
+
+### Explicit Schema Reference
+
+A note can reference a schema by entity name or permalink:
+
+```yaml
+# projects/basic-memory.md
+---
+title: Basic Memory
+schema: SoftwareProject         # by entity name
+---
+
+# research/llm-memory-patterns.md
+---
+title: LLM Memory Patterns
+schema: schema/research-project  # by permalink
+---
+```
+
+Use cases:
+- Note's `type` differs from the schema it should validate against
+- Multiple schema variants exist for the same domain
+- Applying structure to existing notes without changing their type
+
+## Schema Resolution
+
+When validating a note, schemas resolve in priority order:
+
+```
+1. Inline schema     →  schema: { ... }        (dict in frontmatter)
+2. Explicit ref      →  schema: Person          (string in frontmatter)
+3. Implicit by type  →  type: Person            (lookup schema note with entity: Person)
+4. No schema         →  no validation           (perfectly fine)
+```
+
+```python
+async def resolve_schema(note: Note) -> Schema | None:
+    schema_value = note.frontmatter.get('schema')
+
+    # 1. Inline schema (dict)
+    if isinstance(schema_value, dict):
+        return parse_picoschema(schema_value)
+
+    # 2. Explicit reference (string)
+    if isinstance(schema_value, str):
+        schema_note = await find_schema_note(schema_value)
+        if schema_note:
+            return parse_picoschema(schema_note.frontmatter['schema'])
+
+    # 3. Implicit by type
+    note_type = note.frontmatter.get('type')
+    if note_type:
+        results = await search_notes(f"type:schema entity:{note_type}")
+        if results:
+            return parse_picoschema(results[0].frontmatter['schema'])
+
+    # 4. No schema
+    return None
+```
+
+## Validation
+
+### Modes
+
+Configured in the schema's `settings.validation`:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | No validation |
+| `warn` | Warnings in output, doesn't block (default) |
+| `strict` | Errors that block sync, for CI/CD enforcement |
+
+### Validation Output
+
+For a note missing required fields:
+
+```
+$ bm schema validate people/ada-lovelace.md
+
+⚠ Person schema validation:
+  - Missing required field: name (expected [name] observation)
+  - Missing optional field: role
+  - Missing optional field: works_at (no relation found)
+
+ℹ Unmatched observations: [fact] ×2, [born] ×1
+ℹ Unmatched relations: collaborated_with
+```
+
+"Unmatched" items are informational — observations and relations the schema doesn't cover.
+They're valid. Schemas are a subset, not a straitjacket.
+
+### Frontmatter Validation
+
+Schema notes can declare validation rules for frontmatter keys under `settings.frontmatter`
+using the same Picoschema syntax as the `schema` block:
+
+```yaml
+settings:
+  validation: warn
+  frontmatter:
+    tags?(array): string
+    status?(enum): [draft, review, published]
+```
+
+- Frontmatter rules use the same Picoschema key syntax (`?` for optional, `(enum)`, `(array)`)
+- Only available on schema notes (inline schemas skip frontmatter validation)
+- Checks key presence (required vs optional) and enum value membership
+- Unmatched frontmatter keys not in the schema are silently ignored
+- Missing required frontmatter keys produce a warning (or error in strict mode)
+
+Example output for a missing required frontmatter key:
+
+```
+⚠ Person schema validation:
+  - Missing required frontmatter key: status
+```
+
+### Batch Validation
+
+```
+$ bm schema validate Person
+
+Validating 30 notes against Person schema...
+
+✓ people/paul-graham.md         — all fields present
+✓ people/rich-hickey.md         — all fields present
+⚠ people/ada-lovelace.md        — missing: name
+⚠ people/alan-kay.md            — missing: name, role
+✓ people/linus-torvalds.md      — all fields present
+...
+
+Summary: 22/30 valid, 8 warnings, 0 errors
+```
+
+## Emerging Schemas
+
+### The Problem with Traditional Schemas
+
+Most schema systems require: define schema → create conforming content → fight the schema
+when reality doesn't match. This is backwards. Knowledge grows organically.
+
+### The Basic Memory Approach
+
+```
+Write notes freely → Patterns emerge → Crystallize into schema → Validate future notes
+```
+
+### Schema Inference
+
+Generate schemas from existing notes by analyzing observation and relation frequency:
+
+```
+$ bm schema infer Person
+
+Analyzing 30 notes with type: Person...
+
+Observations found:
+  [name]        30/30  100%  → name: string
+  [role]        27/30   90%  → role?: string
+  [fact]        25/30   83%  (generic — no single field)
+  [expertise]   18/30   60%  → expertise?(array): string
+  [email]        8/30   27%  → email?: string
+  [born]         6/30   20%  (below threshold)
+
+Relations found:
+  works_at      22/30   73%  → works_at?: Organization
+  authored      11/30   37%  → authored?(array): string
+
+Suggested schema:
+  name: string, full name
+  role?: string, job title
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+  works_at?: Organization, employer
+
+Save to schema/Person.md? [y/n]
+```
+
+Frequency thresholds:
+- 100% present → required field
+- 25%+ present → optional field
+- Below 25% → excluded from suggestion (but noted)
+
+### Schema Drift Detection
+
+Track how usage patterns shift over time:
+
+```
+$ bm schema diff Person
+
+Schema drift detected:
+
++ expertise: now in 81% of notes (was 12%)
+- department: dropped to 3% of notes
+~ works_at: cardinality changed (one → many)
+
+Update schema? [y/n/review]
+```
+
+## LLM Integration (AI Guidance)
+
+No agent runtime or API key required. The LLM already in the session uses schemas as
+context for note creation.
+
+### Flow
+
+1. User asks LLM to "write a note about Rich Hickey"
+2. LLM determines `type: Person` is appropriate
+3. LLM calls `search_notes("type:schema entity:Person")` → finds schema
+4. LLM reads schema fields: required `name`, optional `role`, `works_at`, `expertise`
+5. LLM calls `write_note` with observations and relations that satisfy the schema
+
+The schema acts as a creation template. The LLM knows what a "complete" note looks like
+without any custom agent infrastructure.
+
+### MCP Tools
+
+```python
+@mcp_tool
+async def schema_validate(
+    entity_type: str | None = None,
+    identifier: str | None = None,
+    project: str | None = None,
+) -> ValidationReport:
+    """Validate notes against their resolved schema.
+
+    Validates a specific note (by identifier) or all notes of a given type.
+    Returns warnings/errors based on the schema's validation mode.
+    """
+
+@mcp_tool
+async def schema_infer(
+    entity_type: str,
+    threshold: float = 0.25,
+    project: str | None = None,
+) -> SuggestedSchema:
+    """Analyze existing notes and suggest a schema definition.
+
+    Examines observation categories and relation types across all notes
+    of the given type. Returns frequency analysis and suggested Picoschema.
+    """
+```
+
+## CLI Commands
+
+```bash
+# Validate a specific note
+bm schema validate people/ada-lovelace.md
+
+# Validate all notes of a type
+bm schema validate Person
+
+# Validate everything with a schema
+bm schema validate
+
+# Infer schema from existing notes
+bm schema infer Person
+
+# Show schema drift from current definition
+bm schema diff Person
+
+# List all schema notes
+bm search "type:schema"
+```
+
+## Examples
+
+### Complete Person Workflow
+
+**Schema:**
+```yaml
+# schema/Person.md
+---
+title: Person
+type: schema
+entity: Person
+version: 1
+schema:
+  name: string, full name
+  role?: string, job title or position
+  works_at?: Organization, employer
+  expertise?(array): string, areas of knowledge
+  email?: string, contact email
+settings:
+  validation: warn
+---
+
+# Person
+
+A human individual in the knowledge graph.
+```
+
+**Valid note:**
+```yaml
+# people/paul-graham.md
+---
+title: Paul Graham
+type: Person
+tags: [startups, essays, lisp]
+---
+
+# Paul Graham
+
+## Observations
+- [name] Paul Graham
+- [role] Essayist and investor
+- [expertise] Startups
+- [expertise] Lisp
+- [expertise] Essay writing
+- [fact] Created Viaweb, the first web app
+
+## Relations
+- works_at [[Y Combinator]]
+- authored [[Hackers and Painters]]
+```
+
+**Note with warnings:**
+```yaml
+# people/ada-lovelace.md
+---
+title: Ada Lovelace
+type: Person
+---
+
+# Ada Lovelace
+
+## Observations
+- [fact] Wrote the first computer program
+- [born] 1815
+
+## Relations
+- collaborated_with [[Charles Babbage]]
+```
+
+Validation: warns about missing required `[name]` observation. Everything else is optional
+or unmatched (which is fine).
+
+## Future Considerations (Deferred)
+
+These are interesting but out of scope for the initial implementation:
+
+- **Multiple schema inheritance** — `schema: [Person, Author]`
+- **Hook integration** — Pre-write validation via the hooks system
+- **OWL/RDF export** — `bm schema export --format owl`
+- **SPARQL queries** — Schema-aware graph queries
+- **Built-in templates** — `bm schema use gtd`, `bm schema use zettelkasten`
+- **Schema versioning/migration** — Tracking breaking changes across versions

justfile

@@ -2,7 +2,6 @@
 
 # Install dependencies
 install:
-    uv pip install -e ".[dev]"
     uv sync
     @echo ""
     @echo "💡 Remember to activate the virtual environment by running: source .venv/bin/activate"
@@ -43,9 +42,9 @@ test-unit-sqlite:
 test-unit-postgres:
     BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov tests
 
-# Run integration tests against SQLite
+# Run integration tests against SQLite (excludes semantic benchmarks — use just test-semantic)
 test-int-sqlite:
-    uv run pytest -p pytest_mock -v --no-cov test-int
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m "not semantic" test-int
 
 # Run integration tests against Postgres
 # Note: Uses timeout due to FastMCP Client + asyncpg cleanup hang (tests pass, process hangs on exit)
@@ -56,12 +55,28 @@ test-int-postgres:
     # Use gtimeout (macOS/Homebrew) or timeout (Linux)
     TIMEOUT_CMD=$(command -v gtimeout || command -v timeout || echo "")
     if [[ -n "$TIMEOUT_CMD" ]]; then
-        $TIMEOUT_CMD --signal=KILL 600 bash -c 'BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov test-int' || test $? -eq 137
+        $TIMEOUT_CMD --signal=KILL 600 bash -c 'BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov -m "not semantic" test-int' || test $? -eq 137
     else
         echo "⚠️  No timeout command found, running without timeout..."
-        BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov test-int
+        BASIC_MEMORY_ENV=test BASIC_MEMORY_TEST_POSTGRES=1 uv run pytest -p pytest_mock -v --no-cov -m "not semantic" test-int
     fi
 
+# Run tests impacted by recent changes (requires pytest-testmon)
+testmon *args:
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov --testmon --testmon-forceselect {{args}}
+
+# Run MCP smoke test (fast end-to-end loop)
+test-smoke:
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m smoke test-int/mcp/test_smoke_integration.py
+
+# Fast local loop: lint, format, typecheck, impacted tests
+fast-check:
+    just fix
+    just format
+    just typecheck
+    just testmon
+    just test-smoke
+
 # Reset Postgres test database (drops and recreates schema)
 # Useful when Alembic migration state gets out of sync during development
 # Uses credentials from docker-compose-postgres.yml
@@ -83,18 +98,43 @@ postgres-migrate:
 # These tests verify Windows-specific database optimizations (locking mode, NullPool)
 # Will be skipped automatically on non-Windows platforms
 test-windows:
-    uv run pytest -p pytest_mock -v --no-cov -m windows tests test-int
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m windows tests test-int
 
 # Run benchmark tests only (performance testing)
 # These are slow tests that measure sync performance with various file counts
 # Excluded from default test runs to keep CI fast
 test-benchmark:
-    uv run pytest -p pytest_mock -v --no-cov -m benchmark tests test-int
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m benchmark tests test-int
+
+# Run semantic search quality benchmarks (all combos)
+test-semantic:
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m semantic test-int/semantic/
+
+# Run semantic benchmarks with JSON artifact output, then show report
+test-semantic-report:
+    BASIC_MEMORY_ENV=test BASIC_MEMORY_BENCHMARK_OUTPUT=.benchmarks/semantic-quality.jsonl uv run pytest -p pytest_mock -v -s --no-cov -m semantic test-int/semantic/
+    uv run python test-int/semantic/report.py .benchmarks/semantic-quality.jsonl
+
+# Run semantic benchmarks (Postgres combos only)
+test-semantic-postgres:
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov -m semantic -k postgres test-int/semantic/
+
+# View semantic benchmark results (rich formatted table)
+# Usage: just semantic-report [--filter-combo sqlite] [--filter-suite paraphrase] [--sort-by avg_latency_ms]
+semantic-report *args:
+    uv run python test-int/semantic/report.py .benchmarks/semantic-quality.jsonl {{args}}
+
+# Compare two search benchmark JSONL outputs
+# Usage:
+#   just benchmark-compare .benchmarks/search-baseline.jsonl .benchmarks/search-candidate.jsonl
+#   just benchmark-compare .benchmarks/search-baseline.jsonl .benchmarks/search-candidate.jsonl --format markdown --show-missing
+benchmark-compare baseline candidate *args:
+    uv run python test-int/compare_search_benchmarks.py "{{baseline}}" "{{candidate}}" --format table {{args}}
 
 # Run all tests including Windows, Postgres, and Benchmarks (for CI/comprehensive testing)
 # Use this before releasing to ensure everything works across all backends and platforms
 test-all:
-    uv run pytest -p pytest_mock -v --no-cov tests test-int
+    BASIC_MEMORY_ENV=test uv run pytest -p pytest_mock -v --no-cov tests test-int
 
 # Generate HTML coverage report
 coverage:
@@ -130,10 +170,14 @@ lint: fix
 fix:
     uv run ruff check --fix --unsafe-fixes src tests test-int
 
-# Type check code
+# Type check code (pyright)
 typecheck:
     uv run pyright
 
+# Type check code (ty)
+typecheck-ty:
+    uv run ty check src/
+
 # Clean build artifacts and cache files
 clean:
     find . -type f -name '*.pyc' -delete
@@ -149,6 +193,18 @@ format:
 run-inspector:
     npx @modelcontextprotocol/inspector
 
+# Run doctor checks in an isolated temp home/config
+doctor:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    TMP_HOME=$(mktemp -d)
+    TMP_CONFIG=$(mktemp -d)
+    HOME="$TMP_HOME" \
+    BASIC_MEMORY_ENV=test \
+    BASIC_MEMORY_HOME="$TMP_HOME/basic-memory" \
+    BASIC_MEMORY_CONFIG_DIR="$TMP_CONFIG" \
+    ./.venv/bin/python -m basic_memory.cli.main doctor --local
+
 
 # Update all dependencies to latest versions
 update-deps:
@@ -157,6 +213,9 @@ update-deps:
 # Run all code quality checks and tests
 check: lint format typecheck test
 
+# Run all code quality checks and all test suites, including semantic benchmarks
+check-all: lint format typecheck test test-semantic
+
 # Generate Alembic migration with descriptive message
 migration message:
     cd src/basic_memory/alembic && alembic revision --autogenerate -m "{{message}}"

pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
     "alembic>=1.14.1",
     "pillow>=11.1.0",
     "pybars3>=0.9.7",
-    "fastmcp==2.12.3", # Pinned - 2.14.x breaks MCP tools visibility (issue #463)
+    "fastmcp>=3.0.1,<4",
     "pyjwt>=2.10.1",
     "python-dotenv>=1.1.0",
     "pytest-aio>=1.9.0",
@@ -44,9 +44,11 @@ dependencies = [
     "sniffio>=1.3.1",
     "anyio>=4.10.0",
     "httpx>=0.28.0",
+    "fastembed>=0.7.4",
+    "sqlite-vec>=0.1.6",
+    "openai>=1.100.2",
 ]
 
-
 [project.urls]
 Homepage = "https://github.com/basicmachines-co/basic-memory"
 Repository = "https://github.com/basicmachines-co/basic-memory"
@@ -71,6 +73,8 @@ markers = [
     "slow: Slow-running tests (deselect with '-m \"not slow\"')",
     "postgres: Tests that run against Postgres backend (deselect with '-m \"not postgres\"')",
     "windows: Windows-specific tests (deselect with '-m \"not windows\"')",
+    "smoke: Fast end-to-end smoke tests for MCP flows",
+    "semantic: Tests requiring semantic dependencies (fastembed, sqlite-vec, openai)",
 ]
 
 [tool.ruff]
@@ -91,6 +95,10 @@ dev = [
     "testcontainers[postgres]>=4.0.0",
     "psycopg>=3.2.0",
     "pyright>=1.1.408",
+    "pytest-testmon>=2.2.0",
+    "ty>=0.0.18",
+    "cst-lsp>=0.1.3",
+    "libcst>=1.8.6",
 ]
 
 [tool.hatch.version]
@@ -109,6 +117,7 @@ ignore = ["test/"]
 defineConstant = { DEBUG = true }
 reportMissingImports = "error"
 reportMissingTypeStubs = false
+reportUnusedImport = "none"
 pythonVersion = "3.12"
 
 

server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/basicmachines-co/basic-memory.git",
     "source": "github"
   },
-  "version": "0.17.8",
+  "version": "0.19.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "basic-memory",
-      "version": "0.17.8",
+      "version": "0.19.1",
       "runtimeHint": "uvx",
       "runtimeArguments": [
         {"type": "positional", "value": "basic-memory"},

src/basic_memory/__init__.py

@@ -1,7 +1,7 @@
 """basic-memory - Local-first knowledge management combining Zettelkasten with knowledge graphs"""
 
 # Package version - updated by release automation
-__version__ = "0.17.8"
+__version__ = "0.19.1"
 
 # API version for FastAPI - independent of package version
 __api_version__ = "v0"

src/basic_memory/alembic/versions/d7e8f9a0b1c2_add_structured_metadata_indexes.py

@@ -0,0 +1,154 @@
+"""Add structured metadata indexes for entity frontmatter
+
+Revision ID: d7e8f9a0b1c2
+Revises: g9a0b3c4d5e6
+Create Date: 2026-01-31 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import text
+
+
+def column_exists(connection, table: str, column: str) -> bool:
+    """Check if a column exists in a table (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text(
+                "SELECT 1 FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = :column"
+            ),
+            {"table": table, "column": column},
+        )
+        return result.fetchone() is not None
+    # SQLite
+    result = connection.execute(text(f"PRAGMA table_info({table})"))
+    columns = [row[1] for row in result]
+    return column in columns
+
+
+def index_exists(connection, index_name: str) -> bool:
+    """Check if an index exists (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+    # SQLite
+    result = connection.execute(
+        text("SELECT 1 FROM sqlite_master WHERE type='index' AND name = :index_name"),
+        {"index_name": index_name},
+    )
+    return result.fetchone() is not None
+
+
+# revision identifiers, used by Alembic.
+revision: str = "d7e8f9a0b1c2"
+down_revision: Union[str, None] = "6830751f5fb6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Add JSONB/GiN indexes for Postgres and generated columns for SQLite."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if dialect == "postgresql":
+        # Ensure JSONB for efficient indexing
+        result = connection.execute(
+            text(
+                "SELECT data_type FROM information_schema.columns "
+                "WHERE table_name = 'entity' AND column_name = 'entity_metadata'"
+            )
+        ).fetchone()
+        if result and result[0] != "jsonb":
+            op.execute(
+                "ALTER TABLE entity ALTER COLUMN entity_metadata "
+                "TYPE jsonb USING entity_metadata::jsonb"
+            )
+
+        # General JSONB GIN index
+        op.execute(
+            "CREATE INDEX IF NOT EXISTS idx_entity_metadata_gin "
+            "ON entity USING GIN (entity_metadata jsonb_path_ops)"
+        )
+
+        # Common field indexes
+        op.execute(
+            "CREATE INDEX IF NOT EXISTS idx_entity_tags_json "
+            "ON entity USING GIN ((entity_metadata -> 'tags'))"
+        )
+        op.execute(
+            "CREATE INDEX IF NOT EXISTS idx_entity_frontmatter_type "
+            "ON entity ((entity_metadata ->> 'type'))"
+        )
+        op.execute(
+            "CREATE INDEX IF NOT EXISTS idx_entity_frontmatter_status "
+            "ON entity ((entity_metadata ->> 'status'))"
+        )
+        return
+
+    # SQLite: add generated columns for common frontmatter fields
+    # Constraint: SQLite ALTER TABLE ADD COLUMN only supports VIRTUAL generated columns,
+    # not STORED. json_extract is deterministic so VIRTUAL columns can still be indexed.
+    if not column_exists(connection, "entity", "tags_json"):
+        op.add_column(
+            "entity",
+            sa.Column(
+                "tags_json",
+                sa.Text(),
+                sa.Computed("json_extract(entity_metadata, '$.tags')", persisted=False),
+            ),
+        )
+    if not column_exists(connection, "entity", "frontmatter_status"):
+        op.add_column(
+            "entity",
+            sa.Column(
+                "frontmatter_status",
+                sa.Text(),
+                sa.Computed("json_extract(entity_metadata, '$.status')", persisted=False),
+            ),
+        )
+    if not column_exists(connection, "entity", "frontmatter_type"):
+        op.add_column(
+            "entity",
+            sa.Column(
+                "frontmatter_type",
+                sa.Text(),
+                sa.Computed("json_extract(entity_metadata, '$.type')", persisted=False),
+            ),
+        )
+
+    # Index generated columns
+    if not index_exists(connection, "idx_entity_tags_json"):
+        op.create_index("idx_entity_tags_json", "entity", ["tags_json"])
+    if not index_exists(connection, "idx_entity_frontmatter_status"):
+        op.create_index("idx_entity_frontmatter_status", "entity", ["frontmatter_status"])
+    if not index_exists(connection, "idx_entity_frontmatter_type"):
+        op.create_index("idx_entity_frontmatter_type", "entity", ["frontmatter_type"])
+
+
+def downgrade() -> None:
+    """Best-effort downgrade (drop indexes, revert JSONB on Postgres)."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if dialect == "postgresql":
+        op.execute("DROP INDEX IF EXISTS idx_entity_frontmatter_status")
+        op.execute("DROP INDEX IF EXISTS idx_entity_frontmatter_type")
+        op.execute("DROP INDEX IF EXISTS idx_entity_tags_json")
+        op.execute("DROP INDEX IF EXISTS idx_entity_metadata_gin")
+        op.execute(
+            "ALTER TABLE entity ALTER COLUMN entity_metadata TYPE json USING entity_metadata::json"
+        )
+        return
+
+    # SQLite: drop indexes (dropping generated columns requires table rebuild)
+    op.execute("DROP INDEX IF EXISTS idx_entity_frontmatter_status")
+    op.execute("DROP INDEX IF EXISTS idx_entity_frontmatter_type")
+    op.execute("DROP INDEX IF EXISTS idx_entity_tags_json")

src/basic_memory/alembic/versions/h1b2c3d4e5f6_add_postgres_vector_search_tables.py

@@ -0,0 +1,68 @@
+"""Add Postgres semantic vector search tables (pgvector-aware, optional)
+
+Revision ID: h1b2c3d4e5f6
+Revises: d7e8f9a0b1c2
+Create Date: 2026-02-07 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "h1b2c3d4e5f6"
+down_revision: Union[str, None] = "d7e8f9a0b1c2"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Create Postgres vector chunk metadata table.
+
+    Trigger: database backend is PostgreSQL.
+    Why: search_vector_chunks stores text metadata with no vector-dimension
+    dependency, so it's safe in a migration.  search_vector_embeddings (which
+    requires pgvector and a provider-specific dimension) is created at runtime
+    by PostgresSearchRepository._ensure_vector_tables(), mirroring the SQLite
+    pattern where vector tables are created dynamically.
+    Outcome: creates the dimension-independent chunks table.  The embeddings
+    table + HNSW index are deferred to runtime.
+    """
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute(
+        """
+        CREATE TABLE IF NOT EXISTS search_vector_chunks (
+            id BIGSERIAL PRIMARY KEY,
+            entity_id INTEGER NOT NULL,
+            project_id INTEGER NOT NULL,
+            chunk_key TEXT NOT NULL,
+            chunk_text TEXT NOT NULL,
+            source_hash TEXT NOT NULL,
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+            UNIQUE (project_id, entity_id, chunk_key)
+        )
+        """
+    )
+    op.execute(
+        """
+        CREATE INDEX IF NOT EXISTS idx_search_vector_chunks_project_entity
+        ON search_vector_chunks (project_id, entity_id)
+        """
+    )
+
+
+def downgrade() -> None:
+    """Remove Postgres vector chunk/embedding tables.
+
+    Does not drop pgvector extension because other schema objects may depend on it.
+    """
+    connection = op.get_bind()
+    if connection.dialect.name != "postgresql":
+        return
+
+    op.execute("DROP TABLE IF EXISTS search_vector_embeddings")
+    op.execute("DROP TABLE IF EXISTS search_vector_chunks")

src/basic_memory/alembic/versions/i2c3d4e5f6g7_auto_backfill_semantic_embeddings.py

@@ -0,0 +1,29 @@
+"""Trigger automatic semantic embedding backfill during migration.
+
+Revision ID: i2c3d4e5f6g7
+Revises: h1b2c3d4e5f6
+Create Date: 2026-02-19 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+# revision identifiers, used by Alembic.
+revision: str = "i2c3d4e5f6g7"
+down_revision: Union[str, None] = "h1b2c3d4e5f6"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """No schema change.
+
+    Trigger: this revision is newly applied.
+    Why: db.run_migrations() detects this revision transition and runs the existing
+    sync_entity_vectors() pipeline to backfill semantic embeddings automatically.
+    Outcome: users no longer need to run `bm reindex --embeddings` after upgrading.
+    """
+
+
+def downgrade() -> None:
+    """No-op downgrade."""

src/basic_memory/alembic/versions/j3d4e5f6g7h8_rename_entity_type_to_note_type.py

@@ -0,0 +1,164 @@
+"""Rename entity_type column to note_type
+
+Revision ID: j3d4e5f6g7h8
+Revises: i2c3d4e5f6g7
+Create Date: 2026-02-22 12:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+from sqlalchemy import text
+
+# revision identifiers, used by Alembic.
+revision: str = "j3d4e5f6g7h8"
+down_revision: Union[str, None] = "i2c3d4e5f6g7"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def table_exists(connection, table_name: str) -> bool:
+    """Check if a table exists (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text("SELECT 1 FROM information_schema.tables WHERE table_name = :table_name"),
+            {"table_name": table_name},
+        )
+        return result.fetchone() is not None
+    # SQLite
+    result = connection.execute(
+        text("SELECT 1 FROM sqlite_master WHERE type='table' AND name = :table_name"),
+        {"table_name": table_name},
+    )
+    return result.fetchone() is not None
+
+
+def index_exists(connection, index_name: str) -> bool:
+    """Check if an index exists (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text("SELECT 1 FROM pg_indexes WHERE indexname = :index_name"),
+            {"index_name": index_name},
+        )
+        return result.fetchone() is not None
+    # SQLite
+    result = connection.execute(
+        text("SELECT 1 FROM sqlite_master WHERE type='index' AND name = :index_name"),
+        {"index_name": index_name},
+    )
+    return result.fetchone() is not None
+
+
+def column_exists(connection, table: str, column: str) -> bool:
+    """Check if a column exists in a table (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text(
+                "SELECT 1 FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = :column"
+            ),
+            {"table": table, "column": column},
+        )
+        return result.fetchone() is not None
+    # SQLite
+    result = connection.execute(text(f"PRAGMA table_info({table})"))
+    columns = [row[1] for row in result]
+    return column in columns
+
+
+def upgrade() -> None:
+    """Rename entity_type → note_type on the entity table."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    # Skip if already migrated (idempotent)
+    if column_exists(connection, "entity", "note_type"):
+        return
+
+    if dialect == "postgresql":
+        # Postgres supports direct column rename
+        op.execute("ALTER TABLE entity RENAME COLUMN entity_type TO note_type")
+
+        # Recreate the index with new name
+        op.execute("DROP INDEX IF EXISTS ix_entity_type")
+        op.execute("CREATE INDEX ix_note_type ON entity (note_type)")
+    else:
+        # SQLite 3.25.0+ supports ALTER TABLE RENAME COLUMN directly.
+        # Avoids batch_alter_table which fails on tables with generated columns
+        # (duplicate column name error when recreating the table).
+        op.execute("ALTER TABLE entity RENAME COLUMN entity_type TO note_type")
+
+        # Recreate the index with new name
+        if index_exists(connection, "ix_entity_type"):
+            op.drop_index("ix_entity_type", table_name="entity")
+        op.create_index("ix_note_type", "entity", ["note_type"])
+
+    # Update search index metadata: rename entity_type → note_type in JSON
+    # This updates the stored metadata so search results use the new field name
+    # Guard: search_index may not exist on a fresh DB (created by an earlier migration)
+    if not table_exists(connection, "search_index"):
+        return
+
+    if dialect == "postgresql":
+        op.execute(
+            text("""
+                UPDATE search_index
+                SET metadata = metadata - 'entity_type' || jsonb_build_object('note_type', metadata->'entity_type')
+                WHERE metadata ? 'entity_type'
+            """)
+        )
+    else:
+        op.execute(
+            text("""
+                UPDATE search_index
+                SET metadata = json_set(
+                    json_remove(metadata, '$.entity_type'),
+                    '$.note_type',
+                    json_extract(metadata, '$.entity_type')
+                )
+                WHERE json_extract(metadata, '$.entity_type') IS NOT NULL
+            """)
+        )
+
+
+def downgrade() -> None:
+    """Rename note_type → entity_type on the entity table."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if dialect == "postgresql":
+        op.execute("ALTER TABLE entity RENAME COLUMN note_type TO entity_type")
+        op.execute("DROP INDEX IF EXISTS ix_note_type")
+        op.execute("CREATE INDEX ix_entity_type ON entity (entity_type)")
+    else:
+        op.execute("ALTER TABLE entity RENAME COLUMN note_type TO entity_type")
+
+        if index_exists(connection, "ix_note_type"):
+            op.drop_index("ix_note_type", table_name="entity")
+        op.create_index("ix_entity_type", "entity", ["entity_type"])
+
+    # Revert search index metadata
+    if not table_exists(connection, "search_index"):
+        return
+
+    if dialect == "postgresql":
+        op.execute(
+            text("""
+                UPDATE search_index
+                SET metadata = metadata - 'note_type' || jsonb_build_object('entity_type', metadata->'note_type')
+                WHERE metadata ? 'note_type'
+            """)
+        )
+    else:
+        op.execute(
+            text("""
+                UPDATE search_index
+                SET metadata = json_set(
+                    json_remove(metadata, '$.note_type'),
+                    '$.entity_type',
+                    json_extract(metadata, '$.note_type')
+                )
+                WHERE json_extract(metadata, '$.note_type') IS NOT NULL
+            """)
+        )

src/basic_memory/alembic/versions/k4e5f6g7h8i9_add_created_by_and_last_updated_by_to_entity.py

@@ -0,0 +1,74 @@
+"""Add created_by and last_updated_by columns to entity table.
+
+Revision ID: k4e5f6g7h8i9
+Revises: j3d4e5f6g7h8
+Create Date: 2026-02-23 00:00:00.000000
+
+These columns track which cloud user created and last modified each entity.
+Both are nullable — NULL for local/CLI usage and existing entities.
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy import text
+
+# revision identifiers, used by Alembic.
+revision: str = "k4e5f6g7h8i9"
+down_revision: Union[str, None] = "j3d4e5f6g7h8"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def column_exists(connection, table: str, column: str) -> bool:
+    """Check if a column exists in a table (idempotent migration support)."""
+    if connection.dialect.name == "postgresql":
+        result = connection.execute(
+            text(
+                "SELECT 1 FROM information_schema.columns "
+                "WHERE table_name = :table AND column_name = :column"
+            ),
+            {"table": table, "column": column},
+        )
+        return result.fetchone() is not None
+    else:
+        # SQLite
+        result = connection.execute(text(f"PRAGMA table_info({table})"))
+        columns = [row[1] for row in result]
+        return column in columns
+
+
+def upgrade() -> None:
+    """Add created_by and last_updated_by columns to entity table.
+
+    Both columns are nullable strings that store cloud user_profile_id UUIDs.
+    No data backfill — existing rows get NULL.
+    """
+    connection = op.get_bind()
+
+    if not column_exists(connection, "entity", "created_by"):
+        op.add_column("entity", sa.Column("created_by", sa.String(), nullable=True))
+
+    if not column_exists(connection, "entity", "last_updated_by"):
+        op.add_column("entity", sa.Column("last_updated_by", sa.String(), nullable=True))
+
+
+def downgrade() -> None:
+    """Remove created_by and last_updated_by columns from entity table."""
+    connection = op.get_bind()
+    dialect = connection.dialect.name
+
+    if column_exists(connection, "entity", "last_updated_by"):
+        if dialect == "postgresql":
+            op.drop_column("entity", "last_updated_by")
+        else:
+            with op.batch_alter_table("entity") as batch_op:
+                batch_op.drop_column("last_updated_by")
+
+    if column_exists(connection, "entity", "created_by"):
+        if dialect == "postgresql":
+            op.drop_column("entity", "created_by")
+        else:
+            with op.batch_alter_table("entity") as batch_op:
+                batch_op.drop_column("created_by")

src/basic_memory/api/app.py

@@ -2,23 +2,13 @@
 
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Request
 from fastapi.exception_handlers import http_exception_handler
+from fastapi.routing import APIRouter
 from loguru import logger
 
 from basic_memory import __version__ as version
 from basic_memory.api.container import ApiContainer, set_container
-from basic_memory.api.routers import (
-    directory_router,
-    importer_router,
-    knowledge,
-    management,
-    memory,
-    project,
-    resource,
-    search,
-    prompt_router,
-)
 from basic_memory.api.v2.routers import (
     knowledge_router as v2_knowledge,
     project_router as v2_project,
@@ -28,8 +18,15 @@ from basic_memory.api.v2.routers import (
     directory_router as v2_directory,
     prompt_router as v2_prompt,
     importer_router as v2_importer,
+    schema_router as v2_schema,
+)
+from basic_memory.api.v2.routers.project_router import (
+    add_project,
+    list_projects,
+    synchronize_projects,
 )
 from basic_memory.config import init_api_logging
+from basic_memory.services.exceptions import EntityAlreadyExistsError
 from basic_memory.services.initialization import initialize_app
 
 
@@ -88,21 +85,44 @@ app.include_router(v2_resource, prefix="/v2/projects/{project_id}")
 app.include_router(v2_directory, prefix="/v2/projects/{project_id}")
 app.include_router(v2_prompt, prefix="/v2/projects/{project_id}")
 app.include_router(v2_importer, prefix="/v2/projects/{project_id}")
+app.include_router(v2_schema, prefix="/v2/projects/{project_id}")
 app.include_router(v2_project, prefix="/v2")
 
-# Include v1 routers (/{project} is a catch-all, must come after specific prefixes)
-app.include_router(knowledge.router, prefix="/{project}")
-app.include_router(memory.router, prefix="/{project}")
-app.include_router(resource.router, prefix="/{project}")
-app.include_router(search.router, prefix="/{project}")
-app.include_router(project.project_router, prefix="/{project}")
-app.include_router(directory_router.router, prefix="/{project}")
-app.include_router(prompt_router.router, prefix="/{project}")
-app.include_router(importer_router.router, prefix="/{project}")
+# Legacy web app proxy paths (compat with /proxy/projects/projects)
+app.include_router(v2_project, prefix="/proxy/projects")
 
-# Project resource router works across projects
-app.include_router(project.project_resource_router)
-app.include_router(management.router)
+# Legacy v1 compat: older CLI versions (v0.18.0 and earlier) call /projects/...
+# Using router mount causes 307 redirect which proxy doesn't follow, so add explicit routes
+legacy_router = APIRouter(tags=["legacy"])
+legacy_router.add_api_route("/projects/projects", list_projects, methods=["GET"])
+legacy_router.add_api_route("/projects/projects", add_project, methods=["POST"])
+legacy_router.add_api_route("/projects/config/sync", synchronize_projects, methods=["POST"])
+app.include_router(legacy_router)
+
+# V2 routers are the only public API surface
+
+
+@app.exception_handler(EntityAlreadyExistsError)
+async def entity_already_exists_error_handler(request: Request, exc: EntityAlreadyExistsError):
+    """Handle entity creation conflicts (e.g., file already exists).
+
+    This is expected behavior when users try to create notes that exist,
+    so log at INFO level instead of ERROR.
+    """
+    logger.info(
+        "Entity already exists",
+        url=str(request.url),
+        method=request.method,
+        path=request.url.path,
+        error=str(exc),
+    )
+    return await http_exception_handler(
+        request,
+        HTTPException(
+            status_code=409,
+            detail="Note already exists. Use edit_note to modify it, or delete it first.",
+        ),
+    )
 
 
 @app.exception_handler(Exception)

src/basic_memory/api/container.py

@@ -47,7 +47,6 @@ class ApiContainer:
         """
         config = ConfigManager().config
         mode = resolve_runtime_mode(
-            cloud_mode_enabled=config.cloud_mode_enabled,
             is_test_env=config.is_test_env,
         )
         return cls(config=config, mode=mode)

src/basic_memory/api/routers/__init__.py

@@ -1,11 +0,0 @@
-"""API routers."""
-
-from . import knowledge_router as knowledge
-from . import management_router as management
-from . import memory_router as memory
-from . import project_router as project
-from . import resource_router as resource
-from . import search_router as search
-from . import prompt_router as prompt
-
-__all__ = ["knowledge", "management", "memory", "project", "resource", "search", "prompt"]

src/basic_memory/api/routers/directory_router.py

@@ -1,84 +0,0 @@
-"""Router for directory tree operations."""
-
-from typing import List, Optional
-
-from fastapi import APIRouter, Query
-
-from basic_memory.deps import DirectoryServiceDep, ProjectIdDep
-from basic_memory.schemas.directory import DirectoryNode
-
-router = APIRouter(prefix="/directory", tags=["directory"])
-
-
-@router.get("/tree", response_model=DirectoryNode, response_model_exclude_none=True)
-async def get_directory_tree(
-    directory_service: DirectoryServiceDep,
-    project_id: ProjectIdDep,
-):
-    """Get hierarchical directory structure from the knowledge base.
-
-    Args:
-        directory_service: Service for directory operations
-        project_id: ID of the current project
-
-    Returns:
-        DirectoryNode representing the root of the hierarchical tree structure
-    """
-    # Get a hierarchical directory tree for the specific project
-    tree = await directory_service.get_directory_tree()
-
-    # Return the hierarchical tree
-    return tree
-
-
-@router.get("/structure", response_model=DirectoryNode, response_model_exclude_none=True)
-async def get_directory_structure(
-    directory_service: DirectoryServiceDep,
-    project_id: ProjectIdDep,
-):
-    """Get folder structure for navigation (no files).
-
-    Optimized endpoint for folder tree navigation. Returns only directory nodes
-    without file metadata. For full tree with files, use /directory/tree.
-
-    Args:
-        directory_service: Service for directory operations
-        project_id: ID of the current project
-
-    Returns:
-        DirectoryNode tree containing only folders (type="directory")
-    """
-    structure = await directory_service.get_directory_structure()
-    return structure
-
-
-@router.get("/list", response_model=List[DirectoryNode], response_model_exclude_none=True)
-async def list_directory(
-    directory_service: DirectoryServiceDep,
-    project_id: ProjectIdDep,
-    dir_name: str = Query("/", description="Directory path to list"),
-    depth: int = Query(1, ge=1, le=10, description="Recursion depth (1-10)"),
-    file_name_glob: Optional[str] = Query(
-        None, description="Glob pattern for filtering file names"
-    ),
-):
-    """List directory contents with filtering and depth control.
-
-    Args:
-        directory_service: Service for directory operations
-        project_id: ID of the current project
-        dir_name: Directory path to list (default: root "/")
-        depth: Recursion depth (1-10, default: 1 for immediate children only)
-        file_name_glob: Optional glob pattern for filtering file names (e.g., "*.md", "*meeting*")
-
-    Returns:
-        List of DirectoryNode objects matching the criteria
-    """
-    # Get directory listing with filtering
-    nodes = await directory_service.list_directory(
-        dir_name=dir_name,
-        depth=depth,
-        file_name_glob=file_name_glob,
-    )
-
-    return nodes

src/basic_memory/api/routers/importer_router.py

@@ -1,152 +0,0 @@
-"""Import router for Basic Memory API."""
-
-import json
-import logging
-
-from fastapi import APIRouter, Form, HTTPException, UploadFile, status
-
-from basic_memory.deps import (
-    ChatGPTImporterDep,
-    ClaudeConversationsImporterDep,
-    ClaudeProjectsImporterDep,
-    MemoryJsonImporterDep,
-)
-from basic_memory.importers import Importer
-from basic_memory.schemas.importer import (
-    ChatImportResult,
-    EntityImportResult,
-    ProjectImportResult,
-)
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter(prefix="/import", tags=["import"])
-
-
-@router.post("/chatgpt", response_model=ChatImportResult)
-async def import_chatgpt(
-    importer: ChatGPTImporterDep,
-    file: UploadFile,
-    folder: str = Form("conversations"),
-) -> ChatImportResult:
-    """Import conversations from ChatGPT JSON export.
-
-    Args:
-        file: The ChatGPT conversations.json file.
-        folder: The folder to place the files in.
-        markdown_processor: MarkdownProcessor instance.
-
-    Returns:
-        ChatImportResult with import statistics.
-
-    Raises:
-        HTTPException: If import fails.
-    """
-    return await import_file(importer, file, folder)
-
-
-@router.post("/claude/conversations", response_model=ChatImportResult)
-async def import_claude_conversations(
-    importer: ClaudeConversationsImporterDep,
-    file: UploadFile,
-    folder: str = Form("conversations"),
-) -> ChatImportResult:
-    """Import conversations from Claude conversations.json export.
-
-    Args:
-        file: The Claude conversations.json file.
-        folder: The folder to place the files in.
-        markdown_processor: MarkdownProcessor instance.
-
-    Returns:
-        ChatImportResult with import statistics.
-
-    Raises:
-        HTTPException: If import fails.
-    """
-    return await import_file(importer, file, folder)
-
-
-@router.post("/claude/projects", response_model=ProjectImportResult)
-async def import_claude_projects(
-    importer: ClaudeProjectsImporterDep,
-    file: UploadFile,
-    folder: str = Form("projects"),
-) -> ProjectImportResult:
-    """Import projects from Claude projects.json export.
-
-    Args:
-        file: The Claude projects.json file.
-        base_folder: The base folder to place the files in.
-        markdown_processor: MarkdownProcessor instance.
-
-    Returns:
-        ProjectImportResult with import statistics.
-
-    Raises:
-        HTTPException: If import fails.
-    """
-    return await import_file(importer, file, folder)
-
-
-@router.post("/memory-json", response_model=EntityImportResult)
-async def import_memory_json(
-    importer: MemoryJsonImporterDep,
-    file: UploadFile,
-    folder: str = Form("conversations"),
-) -> EntityImportResult:
-    """Import entities and relations from a memory.json file.
-
-    Args:
-        file: The memory.json file.
-        destination_folder: Optional destination folder within the project.
-        markdown_processor: MarkdownProcessor instance.
-
-    Returns:
-        EntityImportResult with import statistics.
-
-    Raises:
-        HTTPException: If import fails.
-    """
-    try:
-        file_data = []
-        file_bytes = await file.read()
-        file_str = file_bytes.decode("utf-8")
-        for line in file_str.splitlines():
-            json_data = json.loads(line)
-            file_data.append(json_data)
-
-        result = await importer.import_data(file_data, folder)
-        if not result.success:  # pragma: no cover
-            raise HTTPException(
-                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                detail=result.error_message or "Import failed",
-            )
-    except Exception as e:
-        logger.exception("Import failed")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Import failed: {str(e)}",
-        )
-    return result
-
-
-async def import_file(importer: Importer, file: UploadFile, destination_folder: str):
-    try:
-        # Process file
-        json_data = json.load(file.file)
-        result = await importer.import_data(json_data, destination_folder)
-        if not result.success:  # pragma: no cover
-            raise HTTPException(
-                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-                detail=result.error_message or "Import failed",
-            )
-
-        return result
-
-    except Exception as e:
-        logger.exception("Import failed")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Import failed: {str(e)}",
-        )

src/basic_memory/api/routers/knowledge_router.py

@@ -1,319 +0,0 @@
-"""Router for knowledge graph operations.
-
-⚠️ DEPRECATED: This v1 API is deprecated and will be removed on June 30, 2026.
-Please migrate to /v2/{project}/knowledge endpoints which use entity IDs instead
-of path-based identifiers for improved performance and stability.
-
-Migration guide: See docs/migration/v1-to-v2.md
-"""
-
-from typing import Annotated
-
-from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends, Query, Response
-from loguru import logger
-
-from basic_memory.deps import (
-    EntityServiceDep,
-    get_search_service,
-    SearchServiceDep,
-    LinkResolverDep,
-    ProjectPathDep,
-    FileServiceDep,
-    ProjectConfigDep,
-    AppConfigDep,
-    SyncServiceDep,
-)
-from basic_memory.schemas import (
-    EntityListResponse,
-    EntityResponse,
-    DeleteEntitiesResponse,
-    DeleteEntitiesRequest,
-)
-from basic_memory.schemas.request import EditEntityRequest, MoveEntityRequest
-from basic_memory.schemas.base import Permalink, Entity
-
-router = APIRouter(
-    prefix="/knowledge",
-    tags=["knowledge"],
-    deprecated=True,  # Marks entire router as deprecated in OpenAPI docs
-)
-
-
-async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
-    """Background task to resolve relations for a specific entity.
-
-    This runs asynchronously after the API response is sent, preventing
-    long delays when creating entities with many relations.
-    """
-    try:
-        # Only resolve relations for the newly created entity
-        await sync_service.resolve_relations(entity_id=entity_id)
-        logger.debug(
-            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
-        )
-    except Exception as e:  # pragma: no cover
-        # Log but don't fail - this is a background task.
-        # Avoid forcing synthetic failures just for coverage.
-        logger.warning(  # pragma: no cover
-            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
-        )
-
-
-## Create endpoints
-
-
-@router.post("/entities", response_model=EntityResponse)
-async def create_entity(
-    data: Entity,
-    background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service: SearchServiceDep,
-) -> EntityResponse:
-    """Create an entity."""
-    logger.info(
-        "API request", endpoint="create_entity", entity_type=data.entity_type, title=data.title
-    )
-
-    entity = await entity_service.create_entity(data)
-
-    # reindex
-    await search_service.index_entity(entity, background_tasks=background_tasks)
-    result = EntityResponse.model_validate(entity)
-
-    logger.info(
-        f"API response: endpoint='create_entity' title={result.title}, permalink={result.permalink}, status_code=201"
-    )
-    return result
-
-
-@router.put("/entities/{permalink:path}", response_model=EntityResponse)
-async def create_or_update_entity(
-    project: ProjectPathDep,
-    permalink: Permalink,
-    data: Entity,
-    response: Response,
-    background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service: SearchServiceDep,
-    file_service: FileServiceDep,
-    sync_service: SyncServiceDep,
-) -> EntityResponse:
-    """Create or update an entity. If entity exists, it will be updated, otherwise created."""
-    logger.info(
-        f"API request: create_or_update_entity for {project=}, {permalink=}, {data.entity_type=}, {data.title=}"
-    )
-
-    # Validate permalink matches
-    if data.permalink != permalink:
-        logger.warning(
-            f"API validation error: creating/updating entity with permalink mismatch - url={permalink}, data={data.permalink}",
-        )
-        raise HTTPException(
-            status_code=400,
-            detail=f"Entity permalink {data.permalink} must match URL path: '{permalink}'",
-        )
-
-    # Try create_or_update operation
-    entity, created = await entity_service.create_or_update_entity(data)
-    response.status_code = 201 if created else 200
-
-    # reindex
-    await search_service.index_entity(entity, background_tasks=background_tasks)
-
-    # Schedule relation resolution as a background task for new entities
-    # This prevents blocking the API response while resolving potentially many relations
-    if created:
-        background_tasks.add_task(
-            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
-        )
-
-    result = EntityResponse.model_validate(entity)
-
-    logger.info(
-        f"API response: {result.title=}, {result.permalink=}, {created=}, status_code={response.status_code}"
-    )
-    return result
-
-
-@router.patch("/entities/{identifier:path}", response_model=EntityResponse)
-async def edit_entity(
-    identifier: str,
-    data: EditEntityRequest,
-    background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service: SearchServiceDep,
-) -> EntityResponse:
-    """Edit an existing entity using various operations like append, prepend, find_replace, or replace_section.
-
-    This endpoint allows for targeted edits without requiring the full entity content.
-    """
-    logger.info(
-        f"API request: endpoint='edit_entity', identifier='{identifier}', operation='{data.operation}'"
-    )
-
-    try:
-        # Edit the entity using the service
-        entity = await entity_service.edit_entity(
-            identifier=identifier,
-            operation=data.operation,
-            content=data.content,
-            section=data.section,
-            find_text=data.find_text,
-            expected_replacements=data.expected_replacements,
-        )
-
-        # Reindex the updated entity
-        await search_service.index_entity(entity, background_tasks=background_tasks)
-
-        # Return the updated entity response
-        result = EntityResponse.model_validate(entity)
-
-        logger.info(
-            "API response",
-            endpoint="edit_entity",
-            identifier=identifier,
-            operation=data.operation,
-            permalink=result.permalink,
-            status_code=200,
-        )
-
-        return result
-
-    except Exception as e:
-        logger.error(f"Error editing entity: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-@router.post("/move")
-async def move_entity(
-    data: MoveEntityRequest,
-    background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    project_config: ProjectConfigDep,
-    app_config: AppConfigDep,
-    search_service: SearchServiceDep,
-) -> EntityResponse:
-    """Move an entity to a new file location with project consistency.
-
-    This endpoint moves a note to a different path while maintaining project
-    consistency and optionally updating permalinks based on configuration.
-    """
-    logger.info(
-        f"API request: endpoint='move_entity', identifier='{data.identifier}', destination='{data.destination_path}'"
-    )
-
-    try:
-        # Move the entity using the service
-        moved_entity = await entity_service.move_entity(
-            identifier=data.identifier,
-            destination_path=data.destination_path,
-            project_config=project_config,
-            app_config=app_config,
-        )
-
-        # Get the moved entity to reindex it
-        entity = await entity_service.link_resolver.resolve_link(data.destination_path)
-        if entity:
-            await search_service.index_entity(entity, background_tasks=background_tasks)
-
-        logger.info(
-            "API response",
-            endpoint="move_entity",
-            identifier=data.identifier,
-            destination=data.destination_path,
-            status_code=200,
-        )
-        result = EntityResponse.model_validate(moved_entity)
-        return result
-
-    except Exception as e:
-        logger.error(f"Error moving entity: {e}")
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-## Read endpoints
-
-
-@router.get("/entities/{identifier:path}", response_model=EntityResponse)
-async def get_entity(
-    entity_service: EntityServiceDep,
-    link_resolver: LinkResolverDep,
-    identifier: str,
-) -> EntityResponse:
-    """Get a specific entity by file path or permalink..
-
-    Args:
-        identifier: Entity file path or permalink
-        :param entity_service: EntityService
-        :param link_resolver: LinkResolver
-    """
-    logger.info(f"request: get_entity with identifier={identifier}")
-    entity = await link_resolver.resolve_link(identifier)
-    if not entity:
-        raise HTTPException(status_code=404, detail=f"Entity {identifier} not found")
-
-    result = EntityResponse.model_validate(entity)
-    return result
-
-
-@router.get("/entities", response_model=EntityListResponse)
-async def get_entities(
-    entity_service: EntityServiceDep,
-    permalink: Annotated[list[str] | None, Query()] = None,
-) -> EntityListResponse:
-    """Open specific entities"""
-    logger.info(f"request: get_entities with permalinks={permalink}")
-
-    entities = await entity_service.get_entities_by_permalinks(permalink) if permalink else []
-    result = EntityListResponse(
-        entities=[EntityResponse.model_validate(entity) for entity in entities]
-    )
-    return result
-
-
-## Delete endpoints
-
-
-@router.delete("/entities/{identifier:path}", response_model=DeleteEntitiesResponse)
-async def delete_entity(
-    identifier: str,
-    background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    link_resolver: LinkResolverDep,
-    search_service=Depends(get_search_service),
-) -> DeleteEntitiesResponse:
-    """Delete a single entity and remove from search index."""
-    logger.info(f"request: delete_entity with identifier={identifier}")
-
-    entity = await link_resolver.resolve_link(identifier)
-    if entity is None:
-        return DeleteEntitiesResponse(deleted=False)
-
-    # Delete the entity
-    deleted = await entity_service.delete_entity(entity.permalink or entity.id)
-
-    # Remove from search index (entity, observations, and relations)
-    background_tasks.add_task(search_service.handle_delete, entity)
-
-    result = DeleteEntitiesResponse(deleted=deleted)
-    return result
-
-
-@router.post("/entities/delete", response_model=DeleteEntitiesResponse)
-async def delete_entities(
-    data: DeleteEntitiesRequest,
-    background_tasks: BackgroundTasks,
-    entity_service: EntityServiceDep,
-    search_service=Depends(get_search_service),
-) -> DeleteEntitiesResponse:
-    """Delete entities and remove from search index."""
-    logger.info(f"request: delete_entities with data={data}")
-    deleted = False
-
-    # Remove each deleted entity from search index
-    for permalink in data.permalinks:
-        deleted = await entity_service.delete_entity(permalink)
-        background_tasks.add_task(search_service.delete_by_permalink, permalink)
-
-    result = DeleteEntitiesResponse(deleted=deleted)
-    return result

src/basic_memory/api/routers/management_router.py

@@ -1,80 +0,0 @@
-"""Management router for basic-memory API."""
-
-import asyncio
-
-from fastapi import APIRouter, Request
-from loguru import logger
-from pydantic import BaseModel
-
-from basic_memory.config import ConfigManager
-from basic_memory.deps import SyncServiceDep, ProjectRepositoryDep
-
-router = APIRouter(prefix="/management", tags=["management"])
-
-
-class WatchStatusResponse(BaseModel):
-    """Response model for watch status."""
-
-    running: bool
-    """Whether the watch service is currently running."""
-
-
-@router.get("/watch/status", response_model=WatchStatusResponse)
-async def get_watch_status(request: Request) -> WatchStatusResponse:
-    """Get the current status of the watch service."""
-    return WatchStatusResponse(
-        running=request.app.state.watch_task is not None and not request.app.state.watch_task.done()
-    )
-
-
-@router.post("/watch/start", response_model=WatchStatusResponse)
-async def start_watch_service(
-    request: Request, project_repository: ProjectRepositoryDep, sync_service: SyncServiceDep
-) -> WatchStatusResponse:
-    """Start the watch service if it's not already running."""
-
-    # needed because of circular imports from sync -> app
-    from basic_memory.sync import WatchService
-    from basic_memory.sync.background_sync import create_background_sync_task
-
-    if request.app.state.watch_task is not None and not request.app.state.watch_task.done():
-        # Watch service is already running
-        return WatchStatusResponse(running=True)
-
-    app_config = ConfigManager().config
-
-    # Create and start a new watch service
-    logger.info("Starting watch service via management API")
-
-    # Get services needed for the watch task
-    watch_service = WatchService(
-        app_config=app_config,
-        project_repository=project_repository,
-    )
-
-    # Create and store the task
-    watch_task = create_background_sync_task(sync_service, watch_service)
-    request.app.state.watch_task = watch_task
-
-    return WatchStatusResponse(running=True)
-
-
-@router.post("/watch/stop", response_model=WatchStatusResponse)
-async def stop_watch_service(request: Request) -> WatchStatusResponse:  # pragma: no cover
-    """Stop the watch service if it's running."""
-    if request.app.state.watch_task is None or request.app.state.watch_task.done():
-        # Watch service is not running
-        return WatchStatusResponse(running=False)
-
-    # Cancel the running task
-    logger.info("Stopping watch service via management API")
-    request.app.state.watch_task.cancel()
-
-    # Wait for it to be properly cancelled
-    try:
-        await request.app.state.watch_task
-    except asyncio.CancelledError:
-        pass
-
-    request.app.state.watch_task = None
-    return WatchStatusResponse(running=False)

src/basic_memory/api/routers/memory_router.py

@@ -1,90 +0,0 @@
-"""Routes for memory:// URI operations."""
-
-from typing import Annotated, Optional
-
-from fastapi import APIRouter, Query
-from loguru import logger
-
-from basic_memory.deps import ContextServiceDep, EntityRepositoryDep
-from basic_memory.schemas.base import TimeFrame, parse_timeframe
-from basic_memory.schemas.memory import (
-    GraphContext,
-    normalize_memory_url,
-)
-from basic_memory.schemas.search import SearchItemType
-from basic_memory.api.routers.utils import to_graph_context
-
-router = APIRouter(prefix="/memory", tags=["memory"])
-
-
-@router.get("/recent", response_model=GraphContext)
-async def recent(
-    context_service: ContextServiceDep,
-    entity_repository: EntityRepositoryDep,
-    type: Annotated[list[SearchItemType] | None, Query()] = None,
-    depth: int = 1,
-    timeframe: TimeFrame = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
-) -> GraphContext:
-    # return all types by default
-    types = (
-        [SearchItemType.ENTITY, SearchItemType.RELATION, SearchItemType.OBSERVATION]
-        if not type
-        else type
-    )
-
-    logger.debug(
-        f"Getting recent context: `{types}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
-    )
-    # Parse timeframe
-    since = parse_timeframe(timeframe)
-    limit = page_size
-    offset = (page - 1) * page_size
-
-    # Build context
-    context = await context_service.build_context(
-        types=types, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
-    )
-    recent_context = await to_graph_context(
-        context, entity_repository=entity_repository, page=page, page_size=page_size
-    )
-    logger.debug(f"Recent context: {recent_context.model_dump_json()}")
-    return recent_context
-
-
-# get_memory_context needs to be declared last so other paths can match
-
-
-@router.get("/{uri:path}", response_model=GraphContext)
-async def get_memory_context(
-    context_service: ContextServiceDep,
-    entity_repository: EntityRepositoryDep,
-    uri: str,
-    depth: int = 1,
-    timeframe: Optional[TimeFrame] = None,
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
-) -> GraphContext:
-    """Get rich context from memory:// URI."""
-    # add the project name from the config to the url as the "host
-    # Parse URI
-    logger.debug(
-        f"Getting context for URI: `{uri}` depth: `{depth}` timeframe: `{timeframe}` page: `{page}` page_size: `{page_size}` max_related: `{max_related}`"
-    )
-    memory_url = normalize_memory_url(uri)
-
-    # Parse timeframe
-    since = parse_timeframe(timeframe) if timeframe else None
-    limit = page_size
-    offset = (page - 1) * page_size
-
-    # Build context
-    context = await context_service.build_context(
-        memory_url, depth=depth, since=since, limit=limit, offset=offset, max_related=max_related
-    )
-    return await to_graph_context(
-        context, entity_repository=entity_repository, page=page, page_size=page_size
-    )

src/basic_memory/api/routers/project_router.py

@@ -1,472 +0,0 @@
-"""Router for project management."""
-
-import os
-from fastapi import APIRouter, HTTPException, Path, Body, BackgroundTasks, Response, Query
-from typing import Optional
-from loguru import logger
-
-from basic_memory.deps import (
-    ProjectConfigDep,
-    ProjectServiceDep,
-    ProjectPathDep,
-    SyncServiceDep,
-)
-from basic_memory.schemas import ProjectInfoResponse, SyncReportResponse
-from basic_memory.schemas.project_info import (
-    ProjectList,
-    ProjectItem,
-    ProjectInfoRequest,
-    ProjectStatusResponse,
-)
-from basic_memory.utils import normalize_project_path
-
-# Router for resources in a specific project
-# The ProjectPathDep is used in the path as a prefix, so the request path is like /{project}/project/info
-project_router = APIRouter(prefix="/project", tags=["project"])
-
-# Router for managing project resources
-project_resource_router = APIRouter(prefix="/projects", tags=["project_management"])
-
-
-@project_router.get("/info", response_model=ProjectInfoResponse)
-async def get_project_info(
-    project_service: ProjectServiceDep,
-    project: ProjectPathDep,
-) -> ProjectInfoResponse:
-    """Get comprehensive information about the specified Basic Memory project."""
-    return await project_service.get_project_info(project)
-
-
-@project_router.get("/item", response_model=ProjectItem)
-async def get_project(
-    project_service: ProjectServiceDep,
-    project: ProjectPathDep,
-) -> ProjectItem:
-    """Get bassic info about the specified Basic Memory project."""
-    found_project = await project_service.get_project(project)
-    if not found_project:
-        raise HTTPException(
-            status_code=404, detail=f"Project: '{project}' does not exist"
-        )  # pragma: no cover
-
-    return ProjectItem(
-        id=found_project.id,
-        external_id=found_project.external_id,
-        name=found_project.name,
-        path=normalize_project_path(found_project.path),
-        is_default=found_project.is_default or False,
-    )
-
-
-# Update a project
-@project_router.patch("/{name}", response_model=ProjectStatusResponse)
-async def update_project(
-    project_service: ProjectServiceDep,
-    name: str = Path(..., description="Name of the project to update"),
-    path: Optional[str] = Body(None, description="New absolute path for the project"),
-    is_active: Optional[bool] = Body(None, description="Status of the project (active/inactive)"),
-) -> ProjectStatusResponse:
-    """Update a project's information in configuration and database.
-
-    Args:
-        name: The name of the project to update
-        path: Optional new absolute path for the project
-        is_active: Optional status update for the project
-
-    Returns:
-        Response confirming the project was updated
-    """
-    try:
-        # Validate that path is absolute if provided
-        if path and not os.path.isabs(path):
-            raise HTTPException(status_code=400, detail="Path must be absolute")
-
-        # Get original project info for the response
-        old_project = await project_service.get_project(name)
-        if not old_project:
-            raise HTTPException(
-                status_code=400, detail=f"Project '{name}' not found in configuration"
-            )
-
-        old_project_info = ProjectItem(
-            id=old_project.id,
-            external_id=old_project.external_id,
-            name=old_project.name,
-            path=old_project.path,
-            is_default=old_project.is_default or False,
-        )
-
-        if path:
-            await project_service.move_project(name, path)
-        elif is_active is not None:
-            await project_service.update_project(name, is_active=is_active)
-
-        # Get updated project info
-        updated_project = await project_service.get_project(name)
-        if not updated_project:
-            raise HTTPException(  # pragma: no cover
-                status_code=404, detail=f"Project '{name}' not found after update"
-            )
-
-        return ProjectStatusResponse(
-            message=f"Project '{name}' updated successfully",
-            status="success",
-            default=(name == project_service.default_project),
-            old_project=old_project_info,
-            new_project=ProjectItem(
-                id=updated_project.id,
-                external_id=updated_project.external_id,
-                name=updated_project.name,
-                path=updated_project.path,
-                is_default=updated_project.is_default or False,
-            ),
-        )
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))  # pragma: no cover
-
-
-# Sync project filesystem
-@project_router.post("/sync")
-async def sync_project(
-    background_tasks: BackgroundTasks,
-    sync_service: SyncServiceDep,
-    project_config: ProjectConfigDep,
-    force_full: bool = Query(
-        False, description="Force full scan, bypassing watermark optimization"
-    ),
-    run_in_background: bool = Query(True, description="Run in background"),
-):
-    """Force project filesystem sync to database.
-
-    Scans the project directory and updates the database with any new or modified files.
-
-    Args:
-        background_tasks: FastAPI background tasks
-        sync_service: Sync service for this project
-        project_config: Project configuration
-        force_full: If True, force a full scan even if watermark exists
-        run_in_background: If True, run sync in background and return immediately
-
-    Returns:
-        Response confirming sync was initiated (background) or SyncReportResponse (foreground)
-    """
-    if run_in_background:
-        background_tasks.add_task(
-            sync_service.sync, project_config.home, project_config.name, force_full=force_full
-        )
-        logger.info(
-            f"Filesystem sync initiated for project: {project_config.name} (force_full={force_full})"
-        )
-
-        return {
-            "status": "sync_started",
-            "message": f"Filesystem sync initiated for project '{project_config.name}'",
-        }
-    else:
-        report = await sync_service.sync(
-            project_config.home, project_config.name, force_full=force_full
-        )
-        logger.info(
-            f"Filesystem sync completed for project: {project_config.name} (force_full={force_full})"
-        )
-        return SyncReportResponse.from_sync_report(report)
-
-
-@project_router.post("/status", response_model=SyncReportResponse)
-async def project_sync_status(
-    sync_service: SyncServiceDep,
-    project_config: ProjectConfigDep,
-) -> SyncReportResponse:
-    """Scan directory for changes compared to database state.
-
-    Args:
-        sync_service: Sync service for this project
-        project_config: Project configuration
-
-    Returns:
-        Scan report with details on files that need syncing
-    """
-    logger.info(f"Scanning filesystem for project: {project_config.name}")  # pragma: no cover
-    sync_report = await sync_service.scan(project_config.home)  # pragma: no cover
-
-    return SyncReportResponse.from_sync_report(sync_report)  # pragma: no cover
-
-
-# List all available projects
-@project_resource_router.get("/projects", response_model=ProjectList)
-async def list_projects(
-    project_service: ProjectServiceDep,
-) -> ProjectList:
-    """List all configured projects.
-
-    Returns:
-        A list of all projects with metadata
-    """
-    projects = await project_service.list_projects()
-    default_project = project_service.default_project
-
-    project_items = [
-        ProjectItem(
-            id=project.id,
-            external_id=project.external_id,
-            name=project.name,
-            path=normalize_project_path(project.path),
-            is_default=project.is_default or False,
-        )
-        for project in projects
-    ]
-
-    return ProjectList(
-        projects=project_items,
-        default_project=default_project,
-    )
-
-
-# Add a new project
-@project_resource_router.post("/projects", response_model=ProjectStatusResponse, status_code=201)
-async def add_project(
-    response: Response,
-    project_data: ProjectInfoRequest,
-    project_service: ProjectServiceDep,
-) -> ProjectStatusResponse:
-    """Add a new project to configuration and database.
-
-    Args:
-        project_data: The project name and path, with option to set as default
-
-    Returns:
-        Response confirming the project was added
-    """
-    # Check if project already exists before attempting to add
-    existing_project = await project_service.get_project(project_data.name)
-    if existing_project:
-        # Project exists - check if paths match for true idempotency
-        # Normalize paths for comparison (resolve symlinks, etc.)
-        from pathlib import Path
-
-        requested_path = Path(project_data.path).resolve()
-        existing_path = Path(existing_project.path).resolve()
-
-        if requested_path == existing_path:
-            # Same name, same path - return 200 OK (idempotent)
-            response.status_code = 200
-            return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
-                message=f"Project '{project_data.name}' already exists",
-                status="success",
-                default=existing_project.is_default or False,
-                new_project=ProjectItem(
-                    id=existing_project.id,
-                    external_id=existing_project.external_id,
-                    name=existing_project.name,
-                    path=existing_project.path,
-                    is_default=existing_project.is_default or False,
-                ),
-            )
-        else:
-            # Same name, different path - this is an error
-            raise HTTPException(
-                status_code=400,
-                detail=f"Project '{project_data.name}' already exists with different path. Existing: {existing_project.path}, Requested: {project_data.path}",
-            )
-
-    try:  # pragma: no cover
-        # The service layer now handles cloud mode validation and path sanitization
-        await project_service.add_project(
-            project_data.name, project_data.path, set_default=project_data.set_default
-        )
-
-        # Fetch the newly created project to get its ID
-        new_project = await project_service.get_project(project_data.name)
-        if not new_project:
-            raise HTTPException(status_code=500, detail="Failed to retrieve newly created project")
-
-        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
-            message=f"Project '{new_project.name}' added successfully",
-            status="success",
-            default=project_data.set_default,
-            new_project=ProjectItem(
-                id=new_project.id,
-                external_id=new_project.external_id,
-                name=new_project.name,
-                path=new_project.path,
-                is_default=new_project.is_default or False,
-            ),
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Remove a project
-@project_resource_router.delete("/{name}", response_model=ProjectStatusResponse)
-async def remove_project(
-    project_service: ProjectServiceDep,
-    name: str = Path(..., description="Name of the project to remove"),
-    delete_notes: bool = Query(
-        False, description="If True, delete project directory from filesystem"
-    ),
-) -> ProjectStatusResponse:
-    """Remove a project from configuration and database.
-
-    Args:
-        name: The name of the project to remove
-        delete_notes: If True, delete the project directory from the filesystem
-
-    Returns:
-        Response confirming the project was removed
-    """
-    try:
-        old_project = await project_service.get_project(name)
-        if not old_project:  # pragma: no cover
-            raise HTTPException(
-                status_code=404, detail=f"Project: '{name}' does not exist"
-            )  # pragma: no cover
-
-        # Check if trying to delete the default project
-        # In cloud mode, database is source of truth; in local mode, check config
-        config_default = project_service.default_project
-        db_default = await project_service.repository.get_default_project()
-
-        # Use database default if available, otherwise fall back to config default
-        default_project_name = db_default.name if db_default else config_default
-
-        if name == default_project_name:
-            available_projects = await project_service.list_projects()
-            other_projects = [p.name for p in available_projects if p.name != name]
-            detail = f"Cannot delete default project '{name}'. "
-            if other_projects:
-                detail += (
-                    f"Set another project as default first. Available: {', '.join(other_projects)}"
-                )
-            else:
-                detail += "This is the only project in your configuration."
-            raise HTTPException(status_code=400, detail=detail)
-
-        await project_service.remove_project(name, delete_notes=delete_notes)
-
-        return ProjectStatusResponse(
-            message=f"Project '{old_project.name}' removed successfully",
-            status="success",
-            default=False,
-            old_project=ProjectItem(
-                id=old_project.id,
-                external_id=old_project.external_id,
-                name=old_project.name,
-                path=old_project.path,
-                is_default=old_project.is_default or False,
-            ),
-            new_project=None,
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Set a project as default
-@project_resource_router.put("/{name}/default", response_model=ProjectStatusResponse)
-async def set_default_project(
-    project_service: ProjectServiceDep,
-    name: str = Path(..., description="Name of the project to set as default"),
-) -> ProjectStatusResponse:
-    """Set a project as the default project.
-
-    Args:
-        name: The name of the project to set as default
-
-    Returns:
-        Response confirming the project was set as default
-    """
-    try:
-        # Get the old default project
-        default_name = project_service.default_project
-        default_project = await project_service.get_project(default_name)
-        if not default_project:  # pragma: no cover
-            raise HTTPException(  # pragma: no cover
-                status_code=404, detail=f"Default Project: '{default_name}' does not exist"
-            )
-
-        # get the new project
-        new_default_project = await project_service.get_project(name)
-        if not new_default_project:  # pragma: no cover
-            raise HTTPException(
-                status_code=404, detail=f"Project: '{name}' does not exist"
-            )  # pragma: no cover
-
-        await project_service.set_default_project(name)
-
-        return ProjectStatusResponse(
-            message=f"Project '{name}' set as default successfully",
-            status="success",
-            default=True,
-            old_project=ProjectItem(
-                id=default_project.id,
-                external_id=default_project.external_id,
-                name=default_name,
-                path=default_project.path,
-                is_default=False,
-            ),
-            new_project=ProjectItem(
-                id=new_default_project.id,
-                external_id=new_default_project.external_id,
-                name=name,
-                path=new_default_project.path,
-                is_default=True,
-            ),
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# Get the default project
-@project_resource_router.get("/default", response_model=ProjectItem)
-async def get_default_project(
-    project_service: ProjectServiceDep,
-) -> ProjectItem:
-    """Get the default project.
-
-    Returns:
-        Response with project default information
-    """
-    # Get the default project
-    # In cloud mode, database is source of truth; in local mode, check config
-    config_default = project_service.default_project
-    db_default = await project_service.repository.get_default_project()
-
-    # Use database default if available, otherwise fall back to config default
-    default_name = db_default.name if db_default else config_default
-    default_project = await project_service.get_project(default_name)
-    if not default_project:  # pragma: no cover
-        raise HTTPException(  # pragma: no cover
-            status_code=404, detail=f"Default Project: '{default_name}' does not exist"
-        )
-
-    return ProjectItem(
-        id=default_project.id,
-        external_id=default_project.external_id,
-        name=default_project.name,
-        path=default_project.path,
-        is_default=True,
-    )
-
-
-# Synchronize projects between config and database
-@project_resource_router.post("/config/sync", response_model=ProjectStatusResponse)
-async def synchronize_projects(
-    project_service: ProjectServiceDep,
-) -> ProjectStatusResponse:
-    """Synchronize projects between configuration file and database.
-
-    Ensures that all projects in the configuration file exist in the database
-    and vice versa.
-
-    Returns:
-        Response confirming synchronization was completed
-    """
-    try:  # pragma: no cover
-        await project_service.synchronize_projects()
-
-        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
-            message="Projects synchronized successfully between configuration and database",
-            status="success",
-            default=False,
-        )
-    except ValueError as e:  # pragma: no cover
-        raise HTTPException(status_code=400, detail=str(e))

src/basic_memory/api/routers/prompt_router.py

@@ -1,260 +0,0 @@
-"""Router for prompt-related operations.
-
-This router is responsible for rendering various prompts using Handlebars templates.
-It centralizes all prompt formatting logic that was previously in the MCP prompts.
-"""
-
-from datetime import datetime, timezone
-from fastapi import APIRouter, HTTPException, status
-from loguru import logger
-
-from basic_memory.api.routers.utils import to_graph_context, to_search_results
-from basic_memory.api.template_loader import template_loader
-from basic_memory.schemas.base import parse_timeframe
-from basic_memory.deps import (
-    ContextServiceDep,
-    EntityRepositoryDep,
-    SearchServiceDep,
-    EntityServiceDep,
-)
-from basic_memory.schemas.prompt import (
-    ContinueConversationRequest,
-    SearchPromptRequest,
-    PromptResponse,
-    PromptMetadata,
-)
-from basic_memory.schemas.search import SearchItemType, SearchQuery
-
-router = APIRouter(prefix="/prompt", tags=["prompt"])
-
-
-@router.post("/continue-conversation", response_model=PromptResponse)
-async def continue_conversation(
-    search_service: SearchServiceDep,
-    entity_service: EntityServiceDep,
-    context_service: ContextServiceDep,
-    entity_repository: EntityRepositoryDep,
-    request: ContinueConversationRequest,
-) -> PromptResponse:
-    """Generate a prompt for continuing a conversation.
-
-    This endpoint takes a topic and/or timeframe and generates a prompt with
-    relevant context from the knowledge base.
-
-    Args:
-        request: The request parameters
-
-    Returns:
-        Formatted continuation prompt with context
-    """
-    logger.info(
-        f"Generating continue conversation prompt, topic: {request.topic}, timeframe: {request.timeframe}"
-    )
-
-    since = parse_timeframe(request.timeframe) if request.timeframe else None
-
-    # Initialize search results
-    search_results = []
-
-    # Get data needed for template
-    if request.topic:
-        query = SearchQuery(text=request.topic, after_date=request.timeframe)
-        results = await search_service.search(query, limit=request.search_items_limit)
-        search_results = await to_search_results(entity_service, results)
-
-        # Build context from results
-        all_hierarchical_results = []
-        for result in search_results:
-            if hasattr(result, "permalink") and result.permalink:
-                # Get hierarchical context using the new dataclass-based approach
-                context_result = await context_service.build_context(
-                    result.permalink,
-                    depth=request.depth,
-                    since=since,
-                    max_related=request.related_items_limit,
-                    include_observations=True,  # Include observations for entities
-                )
-
-                # Process results into the schema format
-                graph_context = await to_graph_context(
-                    context_result, entity_repository=entity_repository
-                )
-
-                # Add results to our collection (limit to top results for each permalink)
-                if graph_context.results:
-                    all_hierarchical_results.extend(graph_context.results[:3])
-
-        # Limit to a reasonable number of total results
-        all_hierarchical_results = all_hierarchical_results[:10]
-
-        template_context = {
-            "topic": request.topic,
-            "timeframe": request.timeframe,
-            "hierarchical_results": all_hierarchical_results,
-            "has_results": len(all_hierarchical_results) > 0,
-        }
-    else:
-        # If no topic, get recent activity
-        context_result = await context_service.build_context(
-            types=[SearchItemType.ENTITY],
-            depth=request.depth,
-            since=since,
-            max_related=request.related_items_limit,
-            include_observations=True,
-        )
-        recent_context = await to_graph_context(context_result, entity_repository=entity_repository)
-
-        hierarchical_results = recent_context.results[:5]  # Limit to top 5 recent items
-
-        template_context = {
-            "topic": f"Recent Activity from ({request.timeframe})",
-            "timeframe": request.timeframe,
-            "hierarchical_results": hierarchical_results,
-            "has_results": len(hierarchical_results) > 0,
-        }
-
-    try:
-        # Render template
-        rendered_prompt = await template_loader.render(
-            "prompts/continue_conversation.hbs", template_context
-        )
-
-        # Calculate metadata
-        # Count items of different types
-        observation_count = 0
-        relation_count = 0
-        entity_count = 0
-
-        # Get the hierarchical results from the template context
-        hierarchical_results_for_count = template_context.get("hierarchical_results", [])
-
-        # For topic-based search
-        if request.topic:
-            for item in hierarchical_results_for_count:
-                if hasattr(item, "observations"):
-                    observation_count += len(item.observations) if item.observations else 0
-
-                if hasattr(item, "related_results"):
-                    for related in item.related_results or []:
-                        if hasattr(related, "type"):
-                            if related.type == "relation":
-                                relation_count += 1
-                            elif related.type == "entity":  # pragma: no cover
-                                entity_count += 1  # pragma: no cover
-        # For recent activity
-        else:
-            for item in hierarchical_results_for_count:
-                if hasattr(item, "observations"):
-                    observation_count += len(item.observations) if item.observations else 0
-
-                if hasattr(item, "related_results"):
-                    for related in item.related_results or []:
-                        if hasattr(related, "type"):
-                            if related.type == "relation":
-                                relation_count += 1
-                            elif related.type == "entity":  # pragma: no cover
-                                entity_count += 1  # pragma: no cover
-
-        # Build metadata
-        metadata = {
-            "query": request.topic,
-            "timeframe": request.timeframe,
-            "search_count": len(search_results)
-            if request.topic
-            else 0,  # Original search results count
-            "context_count": len(hierarchical_results_for_count),
-            "observation_count": observation_count,
-            "relation_count": relation_count,
-            "total_items": (
-                len(hierarchical_results_for_count)
-                + observation_count
-                + relation_count
-                + entity_count
-            ),
-            "search_limit": request.search_items_limit,
-            "context_depth": request.depth,
-            "related_limit": request.related_items_limit,
-            "generated_at": datetime.now(timezone.utc).isoformat(),
-        }
-
-        prompt_metadata = PromptMetadata(**metadata)
-
-        return PromptResponse(
-            prompt=rendered_prompt, context=template_context, metadata=prompt_metadata
-        )
-    except Exception as e:
-        logger.error(f"Error rendering continue conversation template: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Error rendering prompt template: {str(e)}",
-        )
-
-
-@router.post("/search", response_model=PromptResponse)
-async def search_prompt(
-    search_service: SearchServiceDep,
-    entity_service: EntityServiceDep,
-    request: SearchPromptRequest,
-    page: int = 1,
-    page_size: int = 10,
-) -> PromptResponse:
-    """Generate a prompt for search results.
-
-    This endpoint takes a search query and formats the results into a helpful
-    prompt with context and suggestions.
-
-    Args:
-        request: The search parameters
-        page: The page number for pagination
-        page_size: The number of results per page, defaults to 10
-
-    Returns:
-        Formatted search results prompt with context
-    """
-    logger.info(f"Generating search prompt, query: {request.query}, timeframe: {request.timeframe}")
-
-    limit = page_size
-    offset = (page - 1) * page_size
-
-    query = SearchQuery(text=request.query, after_date=request.timeframe)
-    results = await search_service.search(query, limit=limit, offset=offset)
-    search_results = await to_search_results(entity_service, results)
-
-    template_context = {
-        "query": request.query,
-        "timeframe": request.timeframe,
-        "results": search_results,
-        "has_results": len(search_results) > 0,
-        "result_count": len(search_results),
-    }
-
-    try:
-        # Render template
-        rendered_prompt = await template_loader.render("prompts/search.hbs", template_context)
-
-        # Build metadata
-        metadata = {
-            "query": request.query,
-            "timeframe": request.timeframe,
-            "search_count": len(search_results),
-            "context_count": len(search_results),
-            "observation_count": 0,  # Search results don't include observations
-            "relation_count": 0,  # Search results don't include relations
-            "total_items": len(search_results),
-            "search_limit": limit,
-            "context_depth": 0,  # No context depth for basic search
-            "related_limit": 0,  # No related items for basic search
-            "generated_at": datetime.now(timezone.utc).isoformat(),
-        }
-
-        prompt_metadata = PromptMetadata(**metadata)
-
-        return PromptResponse(
-            prompt=rendered_prompt, context=template_context, metadata=prompt_metadata
-        )
-    except Exception as e:
-        logger.error(f"Error rendering search template: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Error rendering prompt template: {str(e)}",
-        )

src/basic_memory/api/routers/resource_router.py

@@ -1,252 +0,0 @@
-"""Routes for getting entity content."""
-
-import tempfile
-import uuid
-from pathlib import Path
-from typing import Annotated, Union
-
-from fastapi import APIRouter, HTTPException, BackgroundTasks, Body, Response
-from fastapi.responses import FileResponse, JSONResponse
-from loguru import logger
-
-from basic_memory.deps import (
-    ProjectConfigDep,
-    LinkResolverDep,
-    SearchServiceDep,
-    EntityServiceDep,
-    FileServiceDep,
-    EntityRepositoryDep,
-)
-from basic_memory.repository.search_repository import SearchIndexRow
-from basic_memory.schemas.memory import normalize_memory_url
-from basic_memory.schemas.search import SearchQuery, SearchItemType
-from basic_memory.models.knowledge import Entity as EntityModel
-from datetime import datetime
-
-router = APIRouter(prefix="/resource", tags=["resources"])
-
-
-def _mtime_to_datetime(entity: EntityModel) -> datetime:
-    """Convert entity mtime (file modification time) to datetime.
-
-    Returns the file's actual modification time, falling back to updated_at
-    if mtime is not available.
-    """
-    if entity.mtime:  # pragma: no cover
-        return datetime.fromtimestamp(entity.mtime).astimezone()  # pragma: no cover
-    return entity.updated_at
-
-
-def get_entity_ids(item: SearchIndexRow) -> set[int]:
-    match item.type:
-        case SearchItemType.ENTITY:
-            return {item.id}
-        case SearchItemType.OBSERVATION:
-            return {item.entity_id}  # pyright: ignore [reportReturnType]
-        case SearchItemType.RELATION:
-            from_entity = item.from_id
-            to_entity = item.to_id  # pyright: ignore [reportReturnType]
-            return {from_entity, to_entity} if to_entity else {from_entity}  # pyright: ignore [reportReturnType]
-        case _:  # pragma: no cover
-            raise ValueError(f"Unexpected type: {item.type}")
-
-
-@router.get("/{identifier:path}", response_model=None)
-async def get_resource_content(
-    config: ProjectConfigDep,
-    link_resolver: LinkResolverDep,
-    search_service: SearchServiceDep,
-    entity_service: EntityServiceDep,
-    file_service: FileServiceDep,
-    background_tasks: BackgroundTasks,
-    identifier: str,
-    page: int = 1,
-    page_size: int = 10,
-) -> Union[Response, FileResponse]:
-    """Get resource content by identifier: name or permalink."""
-    logger.debug(f"Getting content for: {identifier}")
-
-    # Find single entity by permalink
-    entity = await link_resolver.resolve_link(identifier)
-    results = [entity] if entity else []
-
-    # pagination for multiple results
-    limit = page_size
-    offset = (page - 1) * page_size
-
-    # search using the identifier as a permalink
-    if not results:
-        # if the identifier contains a wildcard, use GLOB search
-        query = (
-            SearchQuery(permalink_match=identifier)
-            if "*" in identifier
-            else SearchQuery(permalink=identifier)
-        )
-        search_results = await search_service.search(query, limit, offset)
-        if not search_results:
-            raise HTTPException(status_code=404, detail=f"Resource not found: {identifier}")
-
-        # get the deduplicated entities related to the search results
-        entity_ids = {id for result in search_results for id in get_entity_ids(result)}
-        results = await entity_service.get_entities_by_id(list(entity_ids))
-
-    # return single response
-    if len(results) == 1:
-        entity = results[0]
-        # Check file exists via file_service (for cloud compatibility)
-        if not await file_service.exists(entity.file_path):
-            raise HTTPException(
-                status_code=404,
-                detail=f"File not found: {entity.file_path}",
-            )
-        # Read content via file_service as bytes (works with both local and S3)
-        content = await file_service.read_file_bytes(entity.file_path)
-        content_type = file_service.content_type(entity.file_path)
-        return Response(content=content, media_type=content_type)
-
-    # for multiple files, initialize a temporary file for writing the results
-    with tempfile.NamedTemporaryFile(delete=False, mode="w", suffix=".md") as tmp_file:
-        temp_file_path = tmp_file.name
-
-        for result in results:
-            # Read content for each entity
-            content = await file_service.read_entity_content(result)
-            memory_url = normalize_memory_url(result.permalink)
-            modified_date = _mtime_to_datetime(result).isoformat()
-            checksum = result.checksum[:8] if result.checksum else ""
-
-            # Prepare the delimited content
-            response_content = f"--- {memory_url} {modified_date} {checksum}\n"
-            response_content += f"\n{content}\n"
-            response_content += "\n"
-
-            # Write content directly to the temporary file in append mode
-            tmp_file.write(response_content)
-
-        # Ensure all content is written to disk
-        tmp_file.flush()
-
-    # Schedule the temporary file to be deleted after the response
-    background_tasks.add_task(cleanup_temp_file, temp_file_path)
-
-    # Return the file response
-    return FileResponse(path=temp_file_path)
-
-
-def cleanup_temp_file(file_path: str):
-    """Delete the temporary file."""
-    try:
-        Path(file_path).unlink()  # Deletes the file
-        logger.debug(f"Temporary file deleted: {file_path}")
-    except Exception as e:  # pragma: no cover
-        logger.error(f"Error deleting temporary file {file_path}: {e}")
-
-
-@router.put("/{file_path:path}")
-async def write_resource(
-    config: ProjectConfigDep,
-    file_service: FileServiceDep,
-    entity_repository: EntityRepositoryDep,
-    search_service: SearchServiceDep,
-    file_path: str,
-    content: Annotated[str, Body()],
-) -> JSONResponse:
-    """Write content to a file in the project.
-
-    This endpoint allows writing content directly to a file in the project.
-    Also creates an entity record and indexes the file for search.
-
-    Args:
-        file_path: Path to write to, relative to project root
-        request: Contains the content to write
-
-    Returns:
-        JSON response with file information
-    """
-    try:
-        # Get content from request body
-
-        # Defensive type checking: ensure content is a string
-        # FastAPI should validate this, but if a dict somehow gets through
-        # (e.g., via JSON body parsing), we need to catch it here
-        if isinstance(content, dict):
-            logger.error(  # pragma: no cover
-                f"Error writing resource {file_path}: "
-                f"content is a dict, expected string. Keys: {list(content.keys())}"
-            )
-            raise HTTPException(  # pragma: no cover
-                status_code=400,
-                detail="content must be a string, not a dict. "
-                "Ensure request body is sent as raw string content, not JSON object.",
-            )
-
-        # Ensure it's UTF-8 string content
-        if isinstance(content, bytes):  # pragma: no cover
-            content_str = content.decode("utf-8")
-        else:
-            content_str = str(content)
-
-        # Cloud compatibility: do not assume a local filesystem path structure.
-        # Delegate directory creation + writes to the configured FileService (local or S3).
-        await file_service.ensure_directory(Path(file_path).parent)
-        checksum = await file_service.write_file(file_path, content_str)
-
-        # Get file info
-        file_metadata = await file_service.get_file_metadata(file_path)
-
-        # Determine file details
-        file_name = Path(file_path).name
-        content_type = file_service.content_type(file_path)
-
-        entity_type = "canvas" if file_path.endswith(".canvas") else "file"
-
-        # Check if entity already exists
-        existing_entity = await entity_repository.get_by_file_path(file_path)
-
-        if existing_entity:
-            # Update existing entity
-            entity = await entity_repository.update(
-                existing_entity.id,
-                {
-                    "title": file_name,
-                    "entity_type": entity_type,
-                    "content_type": content_type,
-                    "file_path": file_path,
-                    "checksum": checksum,
-                    "updated_at": file_metadata.modified_at,
-                },
-            )
-            status_code = 200
-        else:
-            # Create a new entity model
-            # Explicitly set external_id to ensure NOT NULL constraint is satisfied (fixes #512)
-            entity = EntityModel(
-                external_id=str(uuid.uuid4()),
-                title=file_name,
-                entity_type=entity_type,
-                content_type=content_type,
-                file_path=file_path,
-                checksum=checksum,
-                created_at=file_metadata.created_at,
-                updated_at=file_metadata.modified_at,
-            )
-            entity = await entity_repository.add(entity)
-            status_code = 201
-
-        # Index the file for search
-        await search_service.index_entity(entity)  # pyright: ignore
-
-        # Return success response
-        return JSONResponse(
-            status_code=status_code,
-            content={
-                "file_path": file_path,
-                "checksum": checksum,
-                "size": file_metadata.size,
-                "created_at": file_metadata.created_at.timestamp(),
-                "modified_at": file_metadata.modified_at.timestamp(),
-            },
-        )
-    except Exception as e:  # pragma: no cover
-        logger.error(f"Error writing resource {file_path}: {e}")
-        raise HTTPException(status_code=500, detail=f"Failed to write resource: {str(e)}")

src/basic_memory/api/routers/search_router.py

@@ -1,36 +0,0 @@
-"""Router for search operations."""
-
-from fastapi import APIRouter, BackgroundTasks
-
-from basic_memory.api.routers.utils import to_search_results
-from basic_memory.schemas.search import SearchQuery, SearchResponse
-from basic_memory.deps import SearchServiceDep, EntityServiceDep
-
-router = APIRouter(prefix="/search", tags=["search"])
-
-
-@router.post("/", response_model=SearchResponse)
-async def search(
-    query: SearchQuery,
-    search_service: SearchServiceDep,
-    entity_service: EntityServiceDep,
-    page: int = 1,
-    page_size: int = 10,
-):
-    """Search across all knowledge and documents."""
-    limit = page_size
-    offset = (page - 1) * page_size
-    results = await search_service.search(query, limit=limit, offset=offset)
-    search_results = await to_search_results(entity_service, results)
-    return SearchResponse(
-        results=search_results,
-        current_page=page,
-        page_size=page_size,
-    )
-
-
-@router.post("/reindex")
-async def reindex(background_tasks: BackgroundTasks, search_service: SearchServiceDep):
-    """Recreate and populate the search index."""
-    await search_service.reindex_all(background_tasks=background_tasks)
-    return {"status": "ok", "message": "Reindex initiated"}

src/basic_memory/api/v2/routers/__init__.py

@@ -8,6 +8,7 @@ from basic_memory.api.v2.routers.resource_router import router as resource_route
 from basic_memory.api.v2.routers.directory_router import router as directory_router
 from basic_memory.api.v2.routers.prompt_router import router as prompt_router
 from basic_memory.api.v2.routers.importer_router import router as importer_router
+from basic_memory.api.v2.routers.schema_router import router as schema_router
 
 __all__ = [
     "knowledge_router",
@@ -18,4 +19,5 @@ __all__ = [
     "directory_router",
     "prompt_router",
     "importer_router",
+    "schema_router",
 ]

src/basic_memory/api/v2/routers/importer_router.py

@@ -32,14 +32,14 @@ async def import_chatgpt(
     importer: ChatGPTImporterV2ExternalDep,
     file: UploadFile,
     project_id: str = Path(..., description="Project external UUID"),
-    folder: str = Form("conversations"),
+    directory: str = Form("conversations"),
 ) -> ChatImportResult:
     """Import conversations from ChatGPT JSON export.
 
     Args:
         project_id: Project external UUID from URL path
         file: The ChatGPT conversations.json file.
-        folder: The folder to place the files in.
+        directory: The directory to place the files in.
         importer: ChatGPT importer instance.
 
     Returns:
@@ -49,7 +49,7 @@ async def import_chatgpt(
         HTTPException: If import fails.
     """
     logger.info(f"V2 Importing ChatGPT conversations for project {project_id}")
-    return await import_file(importer, file, folder)
+    return await import_file(importer, file, directory)
 
 
 @router.post("/claude/conversations", response_model=ChatImportResult)
@@ -57,14 +57,14 @@ async def import_claude_conversations(
     importer: ClaudeConversationsImporterV2ExternalDep,
     file: UploadFile,
     project_id: str = Path(..., description="Project external UUID"),
-    folder: str = Form("conversations"),
+    directory: str = Form("conversations"),
 ) -> ChatImportResult:
     """Import conversations from Claude conversations.json export.
 
     Args:
         project_id: Project external UUID from URL path
         file: The Claude conversations.json file.
-        folder: The folder to place the files in.
+        directory: The directory to place the files in.
         importer: Claude conversations importer instance.
 
     Returns:
@@ -74,7 +74,7 @@ async def import_claude_conversations(
         HTTPException: If import fails.
     """
     logger.info(f"V2 Importing Claude conversations for project {project_id}")
-    return await import_file(importer, file, folder)
+    return await import_file(importer, file, directory)
 
 
 @router.post("/claude/projects", response_model=ProjectImportResult)
@@ -82,14 +82,14 @@ async def import_claude_projects(
     importer: ClaudeProjectsImporterV2ExternalDep,
     file: UploadFile,
     project_id: str = Path(..., description="Project external UUID"),
-    folder: str = Form("projects"),
+    directory: str = Form("projects"),
 ) -> ProjectImportResult:
     """Import projects from Claude projects.json export.
 
     Args:
         project_id: Project external UUID from URL path
         file: The Claude projects.json file.
-        folder: The base folder to place the files in.
+        directory: The base directory to place the files in.
         importer: Claude projects importer instance.
 
     Returns:
@@ -99,7 +99,7 @@ async def import_claude_projects(
         HTTPException: If import fails.
     """
     logger.info(f"V2 Importing Claude projects for project {project_id}")
-    return await import_file(importer, file, folder)
+    return await import_file(importer, file, directory)
 
 
 @router.post("/memory-json", response_model=EntityImportResult)
@@ -107,14 +107,14 @@ async def import_memory_json(
     importer: MemoryJsonImporterV2ExternalDep,
     file: UploadFile,
     project_id: str = Path(..., description="Project external UUID"),
-    folder: str = Form("conversations"),
+    directory: str = Form("conversations"),
 ) -> EntityImportResult:
     """Import entities and relations from a memory.json file.
 
     Args:
         project_id: Project external UUID from URL path
         file: The memory.json file.
-        folder: Optional destination folder within the project.
+        directory: Optional destination directory within the project.
         importer: Memory JSON importer instance.
 
     Returns:
@@ -132,7 +132,7 @@ async def import_memory_json(
             json_data = json.loads(line)
             file_data.append(json_data)
 
-        result = await importer.import_data(file_data, folder)
+        result = await importer.import_data(file_data, directory)
         if not result.success:  # pragma: no cover
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
@@ -147,13 +147,13 @@ async def import_memory_json(
     return result
 
 
-async def import_file(importer: Importer, file: UploadFile, destination_folder: str):
+async def import_file(importer: Importer, file: UploadFile, destination_directory: str):
     """Helper function to import a file using an importer instance.
 
     Args:
         importer: The importer instance to use
         file: The file to import
-        destination_folder: Destination folder for imported content
+        destination_directory: Destination directory for imported content
 
     Returns:
         Import result from the importer
@@ -164,7 +164,7 @@ async def import_file(importer: Importer, file: UploadFile, destination_folder:
     try:
         # Process file
         json_data = json.load(file.file)
-        result = await importer.import_data(json_data, destination_folder)
+        result = await importer.import_data(json_data, destination_directory)
         if not result.success:  # pragma: no cover
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,

src/basic_memory/api/v2/routers/knowledge_router.py

@@ -10,7 +10,7 @@ Key improvements:
 - Simplified caching strategies
 """
 
-from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends, Response, Path
+from fastapi import APIRouter, HTTPException, BackgroundTasks, Depends, Response, Path, Query
 from loguru import logger
 
 from basic_memory.deps import (
@@ -19,9 +19,11 @@ from basic_memory.deps import (
     LinkResolverV2ExternalDep,
     ProjectConfigV2ExternalDep,
     AppConfigDep,
-    SyncServiceV2ExternalDep,
     EntityRepositoryV2ExternalDep,
+    RelationRepositoryV2ExternalDep,
     ProjectExternalIdPathDep,
+    TaskSchedulerDep,
+    FileServiceV2ExternalDep,
 )
 from basic_memory.schemas import DeleteEntitiesResponse
 from basic_memory.schemas.base import Entity
@@ -30,29 +32,76 @@ from basic_memory.schemas.v2 import (
     EntityResolveRequest,
     EntityResolveResponse,
     EntityResponseV2,
+    GraphEdge,
+    GraphNode,
+    GraphResponse,
     MoveEntityRequestV2,
+    MoveDirectoryRequestV2,
+    DeleteDirectoryRequestV2,
 )
+from basic_memory.schemas.response import DirectoryMoveResult, DirectoryDeleteResult
 
 router = APIRouter(prefix="/knowledge", tags=["knowledge-v2"])
 
 
-async def resolve_relations_background(sync_service, entity_id: int, entity_permalink: str) -> None:
-    """Background task to resolve relations for a specific entity.
+def _schedule_vector_sync_if_enabled(
+    *,
+    task_scheduler,
+    app_config,
+    entity_id: int,
+    project_id: int,
+) -> None:
+    """Schedule out-of-band vector sync only when semantic search is enabled."""
+    if app_config.semantic_search_enabled:
+        task_scheduler.schedule(
+            "sync_entity_vectors",
+            entity_id=entity_id,
+            project_id=project_id,
+        )
 
-    This runs asynchronously after the API response is sent, preventing
-    long delays when creating entities with many relations.
+
+## Graph endpoint
+
+
+@router.get("/graph", response_model=GraphResponse)
+async def get_graph(
+    project_id: ProjectExternalIdPathDep,
+    entity_repository: EntityRepositoryV2ExternalDep,
+    relation_repository: RelationRepositoryV2ExternalDep,
+) -> GraphResponse:
+    """Return all entities and resolved relations for knowledge graph visualization.
+
+    Returns a flat node/edge structure optimized for rendering with graph libraries.
+    Only includes resolved relations (where to_id is not null).
     """
-    try:  # pragma: no cover
-        # Only resolve relations for the newly created entity
-        await sync_service.resolve_relations(entity_id=entity_id)  # pragma: no cover
-        logger.debug(  # pragma: no cover
-            f"Background: Resolved relations for entity {entity_permalink} (id={entity_id})"
+    logger.info("API v2 request: get_graph")
+
+    # Fetch all entities for this project
+    entities = await entity_repository.find_all(use_load_options=False)
+    nodes = [
+        GraphNode(
+            external_id=entity.external_id,
+            title=entity.title,
+            note_type=entity.note_type,
+            file_path=entity.file_path,
         )
-    except Exception as e:  # pragma: no cover
-        # Log but don't fail - this is a background task
-        logger.warning(  # pragma: no cover
-            f"Background: Failed to resolve relations for entity {entity_permalink}: {e}"
+        for entity in entities
+    ]
+
+    # Fetch all resolved relations (to_id is not null) with eager-loaded entities
+    relations = await relation_repository.find_all()
+    edges = [
+        GraphEdge(
+            from_id=relation.from_entity.external_id,
+            to_id=relation.to_entity.external_id,
+            relation_type=relation.relation_type,
         )
+        for relation in relations
+        if relation.to_entity is not None
+    ]
+
+    logger.info(f"API v2 response: graph with {len(nodes)} nodes and {len(edges)} edges")
+    return GraphResponse(nodes=nodes, edges=edges)
 
 
 ## Resolution endpoint
@@ -100,8 +149,12 @@ async def resolve_identifier(
     resolution_method = "external_id" if entity else "search"
 
     # If not found by external_id, try other resolution methods
+    # Pass source_path for context-aware resolution (prefers notes closer to source)
+    # Pass strict to control fuzzy search fallback (default False allows fuzzy matching)
     if not entity:
-        entity = await link_resolver.resolve_link(data.identifier)
+        entity = await link_resolver.resolve_link(
+            data.identifier, source_path=data.source_path, strict=data.strict
+        )
         if entity:
             # Determine resolution method
             if entity.permalink == data.identifier:
@@ -125,7 +178,7 @@ async def resolve_identifier(
         resolution_method=resolution_method,
     )
 
-    logger.info(
+    logger.debug(
         f"API v2 response: resolved '{data.identifier}' to external_id={result.external_id} via {resolution_method}"
     )
 
@@ -179,24 +232,50 @@ async def create_entity(
     background_tasks: BackgroundTasks,
     entity_service: EntityServiceV2ExternalDep,
     search_service: SearchServiceV2ExternalDep,
+    task_scheduler: TaskSchedulerDep,
+    file_service: FileServiceV2ExternalDep,
+    app_config: AppConfigDep,
+    fast: bool = Query(
+        True, description="If true, write quickly and defer indexing to background tasks."
+    ),
 ) -> EntityResponseV2:
     """Create a new entity.
 
     Args:
         data: Entity data to create
+        fast: If True, defer indexing to background tasks
 
     Returns:
-        Created entity with generated external_id (UUID)
+        Created entity with generated external_id (UUID) and file content
     """
     logger.info(
-        "API v2 request", endpoint="create_entity", entity_type=data.entity_type, title=data.title
+        "API v2 request", endpoint="create_entity", note_type=data.note_type, title=data.title
     )
 
-    entity = await entity_service.create_entity(data)
+    if fast:
+        entity = await entity_service.fast_write_entity(data)
+        task_scheduler.schedule(
+            "reindex_entity",
+            entity_id=entity.id,
+            project_id=project_id,
+        )
+    else:
+        entity = await entity_service.create_entity(data)
+        await search_service.index_entity(entity)
+        _schedule_vector_sync_if_enabled(
+            task_scheduler=task_scheduler,
+            app_config=app_config,
+            entity_id=entity.id,
+            project_id=project_id,
+        )
 
-    # reindex
-    await search_service.index_entity(entity, background_tasks=background_tasks)
     result = EntityResponseV2.model_validate(entity)
+    if fast:
+        result = result.model_copy(update={"observations": [], "relations": []})
+
+    # Always read and return file content
+    content = await file_service.read_file_content(entity.file_path)
+    result = result.model_copy(update={"content": content})
 
     logger.info(
         f"API v2 response: endpoint='create_entity' external_id={entity.external_id}, title={result.title}, permalink={result.permalink}, status_code=201"
@@ -215,9 +294,14 @@ async def update_entity_by_id(
     project_id: ProjectExternalIdPathDep,
     entity_service: EntityServiceV2ExternalDep,
     search_service: SearchServiceV2ExternalDep,
-    sync_service: SyncServiceV2ExternalDep,
     entity_repository: EntityRepositoryV2ExternalDep,
+    task_scheduler: TaskSchedulerDep,
+    file_service: FileServiceV2ExternalDep,
+    app_config: AppConfigDep,
     entity_id: str = Path(..., description="Entity external ID (UUID)"),
+    fast: bool = Query(
+        True, description="If true, write quickly and defer indexing to background tasks."
+    ),
 ) -> EntityResponseV2:
     """Update an entity by external ID.
 
@@ -226,30 +310,61 @@ async def update_entity_by_id(
     Args:
         entity_id: External ID (UUID string)
         data: Updated entity data
+        fast: If True, defer indexing to background tasks
 
     Returns:
-        Updated entity
+        Updated entity with file content
     """
     logger.info(f"API v2 request: update_entity_by_id entity_id={entity_id}")
 
-    # Check if entity exists
+    # Check if entity exists (external_id is the source of truth for v2)
     existing = await entity_repository.get_by_external_id(entity_id)
     created = existing is None
 
-    # Perform update or create
-    entity, _ = await entity_service.create_or_update_entity(data)
-    response.status_code = 201 if created else 200
+    if fast:
+        entity = await entity_service.fast_write_entity(data, external_id=entity_id)
+        response.status_code = 200 if existing else 201
+        task_scheduler.schedule(
+            "reindex_entity",
+            entity_id=entity.id,
+            project_id=project_id,
+            resolve_relations=created,
+        )
+    else:
+        if existing:
+            # Update the existing entity in-place to avoid path-based duplication
+            entity = await entity_service.update_entity(existing, data)
+            response.status_code = 200
+        else:
+            # Create new entity, then bind external_id to the requested UUID
+            entity = await entity_service.create_entity(data)
+            if entity.external_id != entity_id:
+                entity = await entity_repository.update(
+                    entity.id,
+                    {"external_id": entity_id},
+                )
+                if not entity:
+                    raise HTTPException(
+                        status_code=404,
+                        detail=f"Entity with external_id '{entity_id}' not found",
+                    )
+            response.status_code = 201
 
-    # reindex
-    await search_service.index_entity(entity, background_tasks=background_tasks)
-
-    # Schedule relation resolution for new entities
-    if created:
-        background_tasks.add_task(  # pragma: no cover
-            resolve_relations_background, sync_service, entity.id, entity.permalink or ""
+        await search_service.index_entity(entity)
+        _schedule_vector_sync_if_enabled(
+            task_scheduler=task_scheduler,
+            app_config=app_config,
+            entity_id=entity.id,
+            project_id=project_id,
         )
 
     result = EntityResponseV2.model_validate(entity)
+    if fast:
+        result = result.model_copy(update={"observations": [], "relations": []})
+
+    # Always read and return file content
+    content = await file_service.read_file_content(entity.file_path)
+    result = result.model_copy(update={"content": content})
 
     logger.info(
         f"API v2 response: external_id={entity_id}, created={created}, status_code={response.status_code}"
@@ -265,16 +380,23 @@ async def edit_entity_by_id(
     entity_service: EntityServiceV2ExternalDep,
     search_service: SearchServiceV2ExternalDep,
     entity_repository: EntityRepositoryV2ExternalDep,
+    task_scheduler: TaskSchedulerDep,
+    file_service: FileServiceV2ExternalDep,
+    app_config: AppConfigDep,
     entity_id: str = Path(..., description="Entity external ID (UUID)"),
+    fast: bool = Query(
+        True, description="If true, write quickly and defer indexing to background tasks."
+    ),
 ) -> EntityResponseV2:
     """Edit an existing entity by external ID using operations like append, prepend, etc.
 
     Args:
         entity_id: External ID (UUID string)
         data: Edit operation details
+        fast: If True, defer indexing to background tasks
 
     Returns:
-        Updated entity
+        Updated entity with file content
 
     Raises:
         HTTPException: 404 if entity not found, 400 if edit fails
@@ -291,21 +413,47 @@ async def edit_entity_by_id(
         )
 
     try:
-        # Edit using the entity's permalink or path
-        identifier = entity.permalink or entity.file_path
-        updated_entity = await entity_service.edit_entity(
-            identifier=identifier,
-            operation=data.operation,
-            content=data.content,
-            section=data.section,
-            find_text=data.find_text,
-            expected_replacements=data.expected_replacements,
-        )
+        if fast:
+            updated_entity = await entity_service.fast_edit_entity(
+                entity=entity,
+                operation=data.operation,
+                content=data.content,
+                section=data.section,
+                find_text=data.find_text,
+                expected_replacements=data.expected_replacements,
+            )
+            task_scheduler.schedule(
+                "reindex_entity",
+                entity_id=updated_entity.id,
+                project_id=project_id,
+            )
+        else:
+            # Edit using the entity's permalink or path
+            identifier = entity.permalink or entity.file_path
+            updated_entity = await entity_service.edit_entity(
+                identifier=identifier,
+                operation=data.operation,
+                content=data.content,
+                section=data.section,
+                find_text=data.find_text,
+                expected_replacements=data.expected_replacements,
+            )
 
-        # Reindex
-        await search_service.index_entity(updated_entity, background_tasks=background_tasks)
+            await search_service.index_entity(updated_entity)
+            _schedule_vector_sync_if_enabled(
+                task_scheduler=task_scheduler,
+                app_config=app_config,
+                entity_id=updated_entity.id,
+                project_id=project_id,
+            )
 
         result = EntityResponseV2.model_validate(updated_entity)
+        if fast:
+            result = result.model_copy(update={"observations": [], "relations": []})
+
+        # Always read and return file content
+        content = await file_service.read_file_content(updated_entity.file_path)
+        result = result.model_copy(update={"content": content})
 
         logger.info(
             f"API v2 response: external_id={entity_id}, operation='{data.operation}', status_code=200"
@@ -372,6 +520,7 @@ async def move_entity(
     project_config: ProjectConfigV2ExternalDep,
     app_config: AppConfigDep,
     search_service: SearchServiceV2ExternalDep,
+    task_scheduler: TaskSchedulerDep,
     entity_id: str = Path(..., description="Entity external ID (UUID)"),
 ) -> EntityResponseV2:
     """Move an entity to a new file location.
@@ -410,7 +559,13 @@ async def move_entity(
         # Reindex at new location
         reindexed_entity = await entity_service.link_resolver.resolve_link(data.destination_path)
         if reindexed_entity:
-            await search_service.index_entity(reindexed_entity, background_tasks=background_tasks)
+            await search_service.index_entity(reindexed_entity)
+            _schedule_vector_sync_if_enabled(
+                task_scheduler=task_scheduler,
+                app_config=app_config,
+                entity_id=reindexed_entity.id,
+                project_id=project_id,
+            )
 
         result = EntityResponseV2.model_validate(moved_entity)
 
@@ -423,3 +578,107 @@ async def move_entity(
     except Exception as e:
         logger.error(f"Error moving entity: {e}")
         raise HTTPException(status_code=400, detail=str(e))
+
+
+## Move directory endpoint
+
+
+@router.post("/move-directory", response_model=DirectoryMoveResult)
+async def move_directory(
+    data: MoveDirectoryRequestV2,
+    background_tasks: BackgroundTasks,
+    project_id: ProjectExternalIdPathDep,
+    entity_service: EntityServiceV2ExternalDep,
+    project_config: ProjectConfigV2ExternalDep,
+    app_config: AppConfigDep,
+    search_service: SearchServiceV2ExternalDep,
+    task_scheduler: TaskSchedulerDep,
+) -> DirectoryMoveResult:
+    """Move all entities in a directory to a new location.
+
+    V2 API uses project external_id in the URL path for stable references.
+    Moves all files within a source directory to a destination directory,
+    updating database records and optionally updating permalinks.
+
+    Args:
+        project_id: Project external ID from URL path
+        data: Move request with source and destination directories
+
+    Returns:
+        DirectoryMoveResult with counts and details of moved files
+    """
+    logger.info(
+        f"API v2 request: move_directory source='{data.source_directory}', destination='{data.destination_directory}'"
+    )
+
+    try:
+        # Move the directory using the service
+        result = await entity_service.move_directory(
+            source_directory=data.source_directory,
+            destination_directory=data.destination_directory,
+            project_config=project_config,
+            app_config=app_config,
+        )
+
+        # Reindex moved entities
+        for file_path in result.moved_files:
+            entity = await entity_service.link_resolver.resolve_link(file_path)
+            if entity:
+                await search_service.index_entity(entity)
+                _schedule_vector_sync_if_enabled(
+                    task_scheduler=task_scheduler,
+                    app_config=app_config,
+                    entity_id=entity.id,
+                    project_id=project_id,
+                )
+
+        logger.info(
+            f"API v2 response: move_directory "
+            f"total={result.total_files}, success={result.successful_moves}, failed={result.failed_moves}"
+        )
+        return result
+
+    except Exception as e:
+        logger.error(f"Error moving directory: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+## Delete directory endpoint
+
+
+@router.post("/delete-directory", response_model=DirectoryDeleteResult)
+async def delete_directory(
+    data: DeleteDirectoryRequestV2,
+    project_id: ProjectExternalIdPathDep,
+    entity_service: EntityServiceV2ExternalDep,
+) -> DirectoryDeleteResult:
+    """Delete all entities in a directory.
+
+    V2 API uses project external_id in the URL path for stable references.
+    Deletes all files within a directory, updating database records and
+    removing files from the filesystem.
+
+    Args:
+        project_id: Project external ID from URL path
+        data: Delete request with directory path
+
+    Returns:
+        DirectoryDeleteResult with counts and details of deleted files
+    """
+    logger.info(f"API v2 request: delete_directory directory='{data.directory}'")
+
+    try:
+        # Delete the directory using the service
+        result = await entity_service.delete_directory(
+            directory=data.directory,
+        )
+
+        logger.info(
+            f"API v2 response: delete_directory "
+            f"total={result.total_files}, success={result.successful_deletes}, failed={result.failed_deletes}"
+        )
+        return result
+
+    except Exception as e:
+        logger.error(f"Error deleting directory: {e}")
+        raise HTTPException(status_code=400, detail=str(e))

src/basic_memory/api/v2/routers/memory_router.py

@@ -16,7 +16,7 @@ from basic_memory.schemas.memory import (
     normalize_memory_url,
 )
 from basic_memory.schemas.search import SearchItemType
-from basic_memory.api.routers.utils import to_graph_context
+from basic_memory.api.v2.utils import to_graph_context
 
 # Note: No prefix here - it's added during registration as /v2/{project_id}/memory
 router = APIRouter(tags=["memory"])

src/basic_memory/api/v2/routers/project_router.py

@@ -19,9 +19,17 @@ from loguru import logger
 from basic_memory.deps import (
     ProjectServiceDep,
     ProjectRepositoryDep,
+    ProjectConfigV2ExternalDep,
+    SyncServiceV2ExternalDep,
+    TaskSchedulerDep,
+    ProjectExternalIdPathDep,
 )
+from basic_memory.schemas import SyncReportResponse
 from basic_memory.schemas.project_info import (
     ProjectItem,
+    ProjectList,
+    ProjectInfoRequest,
+    ProjectInfoResponse,
     ProjectStatusResponse,
 )
 from basic_memory.schemas.v2 import ProjectResolveRequest, ProjectResolveResponse
@@ -30,6 +38,175 @@ from basic_memory.utils import normalize_project_path, generate_permalink
 router = APIRouter(prefix="/projects", tags=["project_management-v2"])
 
 
+@router.get("/", response_model=ProjectList)
+async def list_projects(
+    project_service: ProjectServiceDep,
+) -> ProjectList:
+    """List all configured projects.
+
+    Returns:
+        A list of all projects with metadata
+    """
+    projects = await project_service.list_projects()
+    default_project = await project_service.get_default_project_name()
+
+    project_items = [
+        ProjectItem(
+            id=project.id,
+            external_id=project.external_id,
+            name=project.name,
+            path=normalize_project_path(project.path),
+            is_default=project.is_default or False,
+        )
+        for project in projects
+    ]
+
+    return ProjectList(
+        projects=project_items,
+        default_project=default_project,
+    )
+
+
+@router.post("/", response_model=ProjectStatusResponse, status_code=201)
+async def add_project(
+    project_data: ProjectInfoRequest,
+    project_service: ProjectServiceDep,
+) -> ProjectStatusResponse:
+    """Add a new project to configuration and database.
+
+    Args:
+        project_data: The project name and path, with option to set as default
+
+    Returns:
+        Response confirming the project was added
+    """
+    # Check if project already exists before attempting to add
+    existing_project = await project_service.get_project(project_data.name)
+    if existing_project:
+        # Project exists - check if paths match for true idempotency
+        # Normalize paths for comparison (resolve symlinks, etc.)
+        requested_path = os.path.abspath(os.path.expanduser(project_data.path))
+        existing_path = os.path.abspath(os.path.expanduser(existing_project.path))
+
+        if requested_path == existing_path:
+            # Same name, same path - return 200 OK (idempotent)
+            return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
+                message=f"Project '{project_data.name}' already exists",
+                status="success",
+                default=existing_project.is_default or False,
+                new_project=ProjectItem(
+                    id=existing_project.id,
+                    external_id=existing_project.external_id,
+                    name=existing_project.name,
+                    path=existing_project.path,
+                    is_default=existing_project.is_default or False,
+                ),
+            )
+        else:
+            # Same name, different path - this is an error
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"Project '{project_data.name}' already exists with different path. "
+                    f"Existing: {existing_project.path}, Requested: {project_data.path}"
+                ),
+            )
+
+    try:  # pragma: no cover
+        # The service layer handles cloud mode validation and path sanitization
+        await project_service.add_project(
+            project_data.name, project_data.path, set_default=project_data.set_default
+        )
+
+        # Fetch the newly created project to get its ID
+        new_project = await project_service.get_project(project_data.name)
+        if not new_project:
+            raise HTTPException(status_code=500, detail="Failed to retrieve newly created project")
+
+        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
+            message=f"Project '{new_project.name}' added successfully",
+            status="success",
+            default=project_data.set_default,
+            new_project=ProjectItem(
+                id=new_project.id,
+                external_id=new_project.external_id,
+                name=new_project.name,
+                path=new_project.path,
+                is_default=new_project.is_default or False,
+            ),
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/config/sync", response_model=ProjectStatusResponse)
+async def synchronize_projects(
+    project_service: ProjectServiceDep,
+) -> ProjectStatusResponse:
+    """Synchronize projects between configuration file and database."""
+    try:  # pragma: no cover
+        await project_service.synchronize_projects()
+
+        return ProjectStatusResponse(  # pyright: ignore [reportCallIssue]
+            message="Projects synchronized successfully between configuration and database",
+            status="success",
+            default=False,
+        )
+    except ValueError as e:  # pragma: no cover
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@router.post("/{project_id}/sync")
+async def sync_project(
+    sync_service: SyncServiceV2ExternalDep,
+    project_config: ProjectConfigV2ExternalDep,
+    task_scheduler: TaskSchedulerDep,
+    project_internal_id: ProjectExternalIdPathDep,
+    force_full: bool = Query(
+        False, description="Force full scan, bypassing watermark optimization"
+    ),
+    run_in_background: bool = Query(True, description="Run in background"),
+):
+    """Force project filesystem sync to database."""
+    if run_in_background:
+        task_scheduler.schedule(
+            "sync_project",
+            project_id=project_internal_id,
+            force_full=force_full,
+        )
+        logger.info(
+            f"Filesystem sync initiated for project: {project_config.name} (force_full={force_full})"
+        )
+
+        return {
+            "status": "sync_started",
+            "message": f"Filesystem sync initiated for project '{project_config.name}'",
+        }
+
+    report = await sync_service.sync(
+        project_config.home, project_config.name, force_full=force_full
+    )
+    logger.info(
+        f"Filesystem sync completed for project: {project_config.name} (force_full={force_full})"
+    )
+    return SyncReportResponse.from_sync_report(report)
+
+
+@router.post("/{project_id}/status", response_model=SyncReportResponse)
+async def get_project_status(
+    sync_service: SyncServiceV2ExternalDep,
+    project_config: ProjectConfigV2ExternalDep,
+    project_id: str = Path(..., description="Project external ID (UUID)"),
+    force_full: bool = Query(
+        False, description="Force full scan, bypassing watermark optimization"
+    ),
+) -> SyncReportResponse:
+    """Get sync status of files vs database for a project."""
+    logger.info(f"API v2 request: get_project_status for project_id={project_id}")
+    report = await sync_service.scan(project_config.home, force_full=force_full)
+    return SyncReportResponse.from_sync_report(report)
+
+
 @router.post("/resolve", response_model=ProjectResolveResponse)
 async def resolve_project_identifier(
     data: ProjectResolveRequest,
@@ -147,6 +324,22 @@ async def get_project_by_id(
     )
 
 
+@router.get("/{project_id}/info", response_model=ProjectInfoResponse)
+async def get_project_info_by_id(
+    project_service: ProjectServiceDep,
+    project_repository: ProjectRepositoryDep,
+    project_id: str = Path(..., description="Project external ID (UUID)"),
+) -> ProjectInfoResponse:
+    """Get detailed project information by external ID."""
+    logger.info(f"API v2 request: get_project_info_by_id for project_id={project_id}")
+    project = await project_repository.get_by_external_id(project_id)
+    if not project:
+        raise HTTPException(
+            status_code=404, detail=f"Project with external_id '{project_id}' not found"
+        )
+    return await project_service.get_project_info(project.name)
+
+
 @router.patch("/{project_id}", response_model=ProjectStatusResponse)
 async def update_project_by_id(
     project_service: ProjectServiceDep,

src/basic_memory/api/v2/routers/prompt_router.py

@@ -9,7 +9,7 @@ from datetime import datetime, timezone
 from fastapi import APIRouter, HTTPException, status, Path
 from loguru import logger
 
-from basic_memory.api.routers.utils import to_graph_context, to_search_results
+from basic_memory.api.v2.utils import to_graph_context, to_search_results
 from basic_memory.api.template_loader import template_loader
 from basic_memory.schemas.base import parse_timeframe
 from basic_memory.deps import (

src/basic_memory/api/v2/routers/resource_router.py

@@ -145,14 +145,14 @@ async def create_resource(
         # Determine file details
         file_name = PathLib(data.file_path).name
         content_type = file_service.content_type(data.file_path)
-        entity_type = "canvas" if data.file_path.endswith(".canvas") else "file"
+        note_type = "canvas" if data.file_path.endswith(".canvas") else "file"
 
         # Create a new entity model
         # Explicitly set external_id to ensure NOT NULL constraint is satisfied (fixes #512)
         entity = EntityModel(
             external_id=str(uuid.uuid4()),
             title=file_name,
-            entity_type=entity_type,
+            note_type=note_type,
             content_type=content_type,
             file_path=data.file_path,
             checksum=checksum,
@@ -253,14 +253,14 @@ async def update_resource(
         # Determine file details
         file_name = PathLib(target_file_path).name
         content_type = file_service.content_type(target_file_path)
-        entity_type = "canvas" if target_file_path.endswith(".canvas") else "file"
+        note_type = "canvas" if target_file_path.endswith(".canvas") else "file"
 
         # Update entity using internal ID
         updated_entity = await entity_repository.update(
             entity.id,
             {
                 "title": file_name,
-                "entity_type": entity_type,
+                "note_type": note_type,
                 "content_type": content_type,
                 "file_path": target_file_path,
                 "checksum": checksum,

src/basic_memory/api/v2/routers/schema_router.py

@@ -0,0 +1,412 @@
+"""V2 router for schema operations.
+
+Provides endpoints for schema validation, inference, and drift detection.
+The schema system validates notes against Picoschema definitions without
+introducing any new data model -- it works entirely with existing
+observations and relations.
+
+Flow: Entity loaded with eager observations/relations -> convert to tuples -> core functions.
+"""
+
+from pathlib import Path as FilePath
+
+import frontmatter
+from fastapi import APIRouter, Path, Query
+from loguru import logger
+
+from basic_memory.deps import (
+    EntityRepositoryV2ExternalDep,
+    FileServiceV2ExternalDep,
+    LinkResolverV2ExternalDep,
+)
+from basic_memory.models.knowledge import Entity
+from basic_memory.schemas.schema import (
+    ValidationReport,
+    InferenceReport,
+    DriftReport,
+    NoteValidationResponse,
+    FieldResultResponse,
+    FieldFrequencyResponse,
+    DriftFieldResponse,
+)
+from basic_memory.schema.resolver import resolve_schema
+from basic_memory.schema.validator import validate_note
+from basic_memory.schema.inference import infer_schema, NoteData, ObservationData, RelationData
+from basic_memory.schema.diff import diff_schema
+from basic_memory.utils import generate_permalink
+
+# Note: No prefix here -- it's added during registration as /v2/{project_id}/schema
+router = APIRouter(tags=["schema"])
+
+
+# --- ORM to core data conversion ---
+
+
+def _entity_observations(entity: Entity) -> list[ObservationData]:
+    """Extract ObservationData from an entity's observations."""
+    return [ObservationData(obs.category, obs.content) for obs in entity.observations]
+
+
+def _entity_relations(entity: Entity) -> list[RelationData]:
+    """Extract RelationData from an entity's outgoing relations.
+
+    Carries the target entity's type on each relation so the inference engine
+    can suggest correct types (e.g. works_at -> Organization, not the source type).
+    """
+    return [
+        RelationData(
+            relation_type=rel.relation_type,
+            target_name=rel.to_name,
+            target_note_type=rel.to_entity.note_type if rel.to_entity else None,
+        )
+        for rel in entity.outgoing_relations
+    ]
+
+
+def _entity_to_note_data(entity: Entity) -> NoteData:
+    """Convert an ORM Entity to a NoteData for inference/diff analysis."""
+    return NoteData(
+        identifier=entity.permalink or entity.file_path,
+        observations=_entity_observations(entity),
+        relations=_entity_relations(entity),
+    )
+
+
+def _entity_frontmatter(entity: Entity) -> dict:
+    """Build a frontmatter dict from an entity's database metadata.
+
+    Used for the notes being validated — their type and schema ref are
+    unlikely to change between syncs.
+    """
+    fm = dict(entity.entity_metadata) if entity.entity_metadata else {}
+    if entity.note_type:
+        fm.setdefault("type", entity.note_type)
+    return fm
+
+
+async def _schema_frontmatter_from_file(
+    file_service: FileServiceV2ExternalDep,
+    entity: Entity,
+) -> dict:
+    """Read a schema entity's frontmatter directly from its file.
+
+    Schema definitions (field declarations, validation mode) are the source
+    of truth for validation. Reading from the file ensures schema-validate
+    always uses the latest settings, even when the file watcher hasn't
+    synced changes to entity_metadata in the database.
+    """
+    try:
+        content = await file_service.read_file_content(entity.file_path)
+        post = frontmatter.loads(content)
+        metadata = dict(post.metadata)
+
+        # Trigger: file is mid-edit and missing required schema fields
+        # Why: parse_schema_note() raises ValueError for missing entity/schema,
+        #   which would turn validation into a 500 response
+        # Outcome: fall back to last-known-good database metadata
+        if not metadata.get("entity") or not isinstance(metadata.get("schema"), dict):
+            logger.warning(
+                "Schema file has incomplete frontmatter, falling back to database metadata",
+                file_path=entity.file_path,
+            )
+            return _entity_frontmatter(entity)
+
+        return metadata
+    except Exception:
+        # Trigger: file is missing, unreadable, or has malformed frontmatter
+        # Why: fall back to database metadata rather than failing validation entirely
+        # Outcome: behaves like before this change — uses potentially stale data
+        logger.warning(
+            "Failed to read schema file, falling back to database metadata",
+            file_path=entity.file_path,
+        )
+        return _entity_frontmatter(entity)
+
+
+# --- Validation ---
+
+
+@router.post("/schema/validate", response_model=ValidationReport)
+async def validate_schema(
+    entity_repository: EntityRepositoryV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+    link_resolver: LinkResolverV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    note_type: str | None = Query(None, description="Note type to validate"),
+    identifier: str | None = Query(None, description="Specific note identifier"),
+):
+    """Validate notes against their resolved schemas.
+
+    Validates a specific note (by identifier) or all notes of a given type.
+    Returns warnings/errors based on the schema's validation mode.
+
+    Schema definitions are read directly from their files to ensure the
+    latest settings (validation mode, field declarations) are always used,
+    even when file changes haven't been synced to the database yet.
+    """
+    results: list[NoteValidationResponse] = []
+
+    # --- Single note validation ---
+    if identifier:
+        # Resolve identifier flexibly (permalink, title, path, fuzzy)
+        # to match how read_note and other tools resolve identifiers
+        entity = await link_resolver.resolve_link(identifier)
+        if not entity:
+            return ValidationReport(note_type=note_type, total_notes=0, total_entities=0)
+
+        frontmatter = _entity_frontmatter(entity)
+        schema_ref = frontmatter.get("schema")
+
+        async def search_fn(query: str) -> list[dict]:
+            entities = await _find_schema_entities(
+                entity_repository,
+                query,
+                allow_reference_match=isinstance(schema_ref, str) and query == schema_ref,
+            )
+            return [await _schema_frontmatter_from_file(file_service, e) for e in entities]
+
+        schema_def = await resolve_schema(frontmatter, search_fn)
+        if schema_def:
+            result = validate_note(
+                entity.title or entity.permalink or identifier,
+                schema_def,
+                _entity_observations(entity),
+                _entity_relations(entity),
+                frontmatter=frontmatter,
+            )
+            results.append(_to_note_validation_response(result))
+
+        return ValidationReport(
+            note_type=note_type or entity.note_type,
+            total_notes=len(results),
+            total_entities=1,
+            valid_count=1 if (results and results[0].passed) else 0,
+            warning_count=sum(len(r.warnings) for r in results),
+            error_count=sum(len(r.errors) for r in results),
+            results=results,
+        )
+
+    # --- Batch validation by note type ---
+    entities = await _find_by_note_type(entity_repository, note_type) if note_type else []
+
+    for entity in entities:
+        frontmatter = _entity_frontmatter(entity)
+        schema_ref = frontmatter.get("schema")
+
+        async def search_fn(query: str) -> list[dict]:
+            entities = await _find_schema_entities(
+                entity_repository,
+                query,
+                allow_reference_match=isinstance(schema_ref, str) and query == schema_ref,
+            )
+            return [await _schema_frontmatter_from_file(file_service, e) for e in entities]
+
+        schema_def = await resolve_schema(frontmatter, search_fn)
+        if schema_def:
+            result = validate_note(
+                entity.title or entity.permalink or entity.file_path,
+                schema_def,
+                _entity_observations(entity),
+                _entity_relations(entity),
+                frontmatter=frontmatter,
+            )
+            results.append(_to_note_validation_response(result))
+
+    valid = sum(1 for r in results if r.passed)
+    return ValidationReport(
+        note_type=note_type,
+        total_notes=len(results),
+        total_entities=len(entities),
+        valid_count=valid,
+        warning_count=sum(len(r.warnings) for r in results),
+        error_count=sum(len(r.errors) for r in results),
+        results=results,
+    )
+
+
+# --- Inference ---
+
+
+@router.post("/schema/infer", response_model=InferenceReport)
+async def infer_schema_endpoint(
+    entity_repository: EntityRepositoryV2ExternalDep,
+    project_id: str = Path(..., description="Project external UUID"),
+    note_type: str = Query(..., description="Note type to analyze"),
+    threshold: float = Query(0.25, description="Minimum frequency for optional fields"),
+):
+    """Infer a schema from existing notes of a given type.
+
+    Examines observation categories and relation types across all notes
+    of the given type. Returns frequency analysis and suggested Picoschema.
+    """
+    entities = await _find_by_note_type(entity_repository, note_type)
+    notes_data = [_entity_to_note_data(entity) for entity in entities]
+
+    result = infer_schema(note_type, notes_data, optional_threshold=threshold)
+
+    return InferenceReport(
+        note_type=result.note_type,
+        notes_analyzed=result.notes_analyzed,
+        field_frequencies=[
+            FieldFrequencyResponse(
+                name=f.name,
+                source=f.source,
+                count=f.count,
+                total=f.total,
+                percentage=f.percentage,
+                sample_values=f.sample_values,
+                is_array=f.is_array,
+                target_type=f.target_type,
+            )
+            for f in result.field_frequencies
+        ],
+        suggested_schema=result.suggested_schema,
+        suggested_required=result.suggested_required,
+        suggested_optional=result.suggested_optional,
+        excluded=result.excluded,
+    )
+
+
+# --- Drift Detection ---
+
+
+@router.get("/schema/diff/{note_type}", response_model=DriftReport)
+async def diff_schema_endpoint(
+    entity_repository: EntityRepositoryV2ExternalDep,
+    file_service: FileServiceV2ExternalDep,
+    note_type: str = Path(..., description="Note type to check for drift"),
+    project_id: str = Path(..., description="Project external UUID"),
+):
+    """Show drift between a schema definition and actual note usage.
+
+    Compares the existing schema for an entity type against how notes
+    of that type are actually structured. Identifies new fields, dropped
+    fields, and cardinality changes.
+    """
+
+    async def search_fn(query: str) -> list[dict]:
+        entities = await _find_schema_entities(entity_repository, query)
+        return [await _schema_frontmatter_from_file(file_service, e) for e in entities]
+
+    # Resolve schema by note type
+    schema_frontmatter = {"type": note_type}
+    schema_def = await resolve_schema(schema_frontmatter, search_fn)
+
+    if not schema_def:
+        return DriftReport(note_type=note_type, schema_found=False)
+
+    # Collect all notes of this type
+    entities = await _find_by_note_type(entity_repository, note_type)
+    notes_data = [_entity_to_note_data(entity) for entity in entities]
+
+    result = diff_schema(schema_def, notes_data)
+
+    return DriftReport(
+        note_type=note_type,
+        new_fields=[
+            DriftFieldResponse(
+                name=f.name,
+                source=f.source,
+                count=f.count,
+                total=f.total,
+                percentage=f.percentage,
+            )
+            for f in result.new_fields
+        ],
+        dropped_fields=[
+            DriftFieldResponse(
+                name=f.name,
+                source=f.source,
+                count=f.count,
+                total=f.total,
+                percentage=f.percentage,
+            )
+            for f in result.dropped_fields
+        ],
+        cardinality_changes=result.cardinality_changes,
+    )
+
+
+# --- Helpers ---
+
+
+async def _find_by_note_type(
+    entity_repository: EntityRepositoryV2ExternalDep,
+    note_type: str,
+) -> list[Entity]:
+    """Find all entities of a given type using the repository's select pattern."""
+    query = entity_repository.select().where(Entity.note_type == note_type)
+    result = await entity_repository.execute_query(query)
+    return list(result.scalars().all())
+
+
+async def _find_schema_entities(
+    entity_repository: EntityRepositoryV2ExternalDep,
+    target_note_type: str,
+    *,
+    allow_reference_match: bool = False,
+) -> list[Entity]:
+    """Find schema entities for resolver lookups.
+
+    Resolution strategy:
+    1) Always try exact entity_metadata['entity'] match (for implicit type lookup
+       and explicit references that use entity names)
+    2) Only when allow_reference_match=True and no entity match was found, try
+       exact reference matching by title/permalink (explicit schema references)
+    """
+    query = entity_repository.select().where(Entity.note_type == "schema")
+    result = await entity_repository.execute_query(query)
+    entities = list(result.scalars().all())
+
+    normalized_target = generate_permalink(target_note_type)
+
+    entity_matches = [
+        e
+        for e in entities
+        if e.entity_metadata
+        and isinstance(e.entity_metadata.get("entity"), str)
+        and generate_permalink(e.entity_metadata["entity"]) == normalized_target
+    ]
+    if entity_matches:
+        return entity_matches
+
+    if not allow_reference_match:
+        return []
+
+    reference_matches: list[Entity] = []
+    for entity in entities:
+        candidate_refs: list[str] = []
+        if entity.title:
+            candidate_refs.append(entity.title)
+        if entity.permalink:
+            candidate_refs.append(entity.permalink)
+            candidate_refs.append(FilePath(entity.permalink).name)
+
+        if any(generate_permalink(ref) == normalized_target for ref in candidate_refs):
+            reference_matches.append(entity)
+
+    return reference_matches
+
+
+def _to_note_validation_response(result) -> NoteValidationResponse:
+    """Convert a core ValidationResult to a Pydantic response model."""
+    return NoteValidationResponse(
+        note_identifier=result.note_identifier,
+        schema_entity=result.schema_entity,
+        passed=result.passed,
+        field_results=[
+            FieldResultResponse(
+                field_name=fr.field.name,
+                field_type=fr.field.type,
+                required=fr.field.required,
+                status=fr.status,
+                values=fr.values,
+                message=fr.message,
+            )
+            for fr in result.field_results
+        ],
+        unmatched_observations=result.unmatched_observations,
+        unmatched_relations=result.unmatched_relations,
+        warnings=result.warnings,
+        errors=result.errors,
+    )

src/basic_memory/api/v2/routers/search_router.py

@@ -4,11 +4,20 @@ This router uses external_id UUIDs for stable, API-friendly routing.
 V1 uses string-based project names which are less efficient and less stable.
 """
 
-from fastapi import APIRouter, BackgroundTasks, Path
+from fastapi import APIRouter, HTTPException, Path
 
-from basic_memory.api.routers.utils import to_search_results
+from basic_memory.api.v2.utils import to_search_results
+from basic_memory.repository.semantic_errors import (
+    SemanticDependenciesMissingError,
+    SemanticSearchDisabledError,
+)
 from basic_memory.schemas.search import SearchQuery, SearchResponse
-from basic_memory.deps import SearchServiceV2ExternalDep, EntityServiceV2ExternalDep
+from basic_memory.deps import (
+    SearchServiceV2ExternalDep,
+    EntityServiceV2ExternalDep,
+    TaskSchedulerDep,
+    ProjectExternalIdPathDep,
+)
 
 # Note: No prefix here - it's added during registration as /v2/{project_id}/search
 router = APIRouter(tags=["search"])
@@ -38,22 +47,35 @@ async def search(
     Returns:
         SearchResponse with paginated search results
     """
-    limit = page_size
     offset = (page - 1) * page_size
-    results = await search_service.search(query, limit=limit, offset=offset)
+    # Fetch one extra item to detect whether more pages exist (N+1 trick)
+    fetch_limit = page_size + 1
+    try:
+        results = await search_service.search(query, limit=fetch_limit, offset=offset)
+    except SemanticSearchDisabledError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except SemanticDependenciesMissingError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    has_more = len(results) > page_size
+    if has_more:
+        results = results[:page_size]
+
     search_results = await to_search_results(entity_service, results)
     return SearchResponse(
         results=search_results,
         current_page=page,
         page_size=page_size,
+        has_more=has_more,
     )
 
 
 @router.post("/search/reindex")
 async def reindex(
-    background_tasks: BackgroundTasks,
-    search_service: SearchServiceV2ExternalDep,
-    project_id: str = Path(..., description="Project external UUID"),
+    task_scheduler: TaskSchedulerDep,
+    project_id: ProjectExternalIdPathDep,
 ):
     """Recreate and populate the search index for a project.
 
@@ -63,11 +85,10 @@ async def reindex(
 
     Args:
         project_id: Project external UUID from URL path
-        background_tasks: FastAPI background tasks handler
-        search_service: Search service scoped to project
+        task_scheduler: Task scheduler for background work
 
     Returns:
         Status message indicating reindex has been initiated
     """
-    await search_service.reindex_all(background_tasks=background_tasks)
+    task_scheduler.schedule("reindex_project", project_id=project_id)
     return {"status": "ok", "message": "Reindex initiated"}

src/basic_memory/api/v2/utils.py

@@ -24,29 +24,42 @@ async def to_graph_context(
     page: Optional[int] = None,
     page_size: Optional[int] = None,
 ):
-    # First pass: collect all entity IDs needed for relations
+    # First pass: collect all entity IDs needed for external_id lookup
+    # This includes: entity primary results, observation parent entities, relation from/to entities
     entity_ids_needed: set[int] = set()
     for context_item in context_result.results:
         for item in (
             [context_item.primary_result] + context_item.observations + context_item.related_results
         ):
-            if item.type == SearchItemType.RELATION:
+            if item.type == SearchItemType.ENTITY:
+                # Entity's own ID for its external_id
+                entity_ids_needed.add(item.id)
+            elif item.type == SearchItemType.OBSERVATION:
+                # Parent entity ID for entity_external_id
+                if item.entity_id:  # pyright: ignore
+                    entity_ids_needed.add(item.entity_id)  # pyright: ignore
+            elif item.type == SearchItemType.RELATION:
+                # Source and target entity IDs for external_ids
                 if item.from_id:  # pyright: ignore
                     entity_ids_needed.add(item.from_id)  # pyright: ignore
                 if item.to_id:
                     entity_ids_needed.add(item.to_id)
 
-    # Batch fetch all entities at once
-    entity_lookup: dict[int, str] = {}
+    # Batch fetch all entities at once - get both title and external_id
+    entity_title_lookup: dict[int, str] = {}
+    entity_external_id_lookup: dict[int, str] = {}
     if entity_ids_needed:
         entities = await entity_repository.find_by_ids(list(entity_ids_needed))
-        entity_lookup = {e.id: e.title for e in entities}
+        for e in entities:
+            entity_title_lookup[e.id] = e.title
+            entity_external_id_lookup[e.id] = e.external_id
 
     # Helper function to convert items to summaries
     def to_summary(item: SearchIndexRow | ContextResultRow):
         match item.type:
             case SearchItemType.ENTITY:
                 return EntitySummary(
+                    external_id=entity_external_id_lookup.get(item.id, ""),
                     entity_id=item.id,
                     title=item.title,  # pyright: ignore
                     permalink=item.permalink,
@@ -55,10 +68,14 @@ async def to_graph_context(
                     created_at=item.created_at,
                 )
             case SearchItemType.OBSERVATION:
+                entity_ext_id = None
+                if item.entity_id:  # pyright: ignore
+                    entity_ext_id = entity_external_id_lookup.get(item.entity_id)  # pyright: ignore
                 return ObservationSummary(
                     observation_id=item.id,
                     entity_id=item.entity_id,  # pyright: ignore
-                    title=item.title,  # pyright: ignore
+                    entity_external_id=entity_ext_id,
+                    title=entity_title_lookup.get(item.entity_id),  # pyright: ignore
                     file_path=item.file_path,
                     category=item.category,  # pyright: ignore
                     content=item.content,  # pyright: ignore
@@ -66,8 +83,10 @@ async def to_graph_context(
                     created_at=item.created_at,
                 )
             case SearchItemType.RELATION:
-                from_title = entity_lookup.get(item.from_id) if item.from_id else None  # pyright: ignore
-                to_title = entity_lookup.get(item.to_id) if item.to_id else None
+                from_title = entity_title_lookup.get(item.from_id) if item.from_id else None  # pyright: ignore
+                to_title = entity_title_lookup.get(item.to_id) if item.to_id else None
+                from_ext_id = entity_external_id_lookup.get(item.from_id) if item.from_id else None  # pyright: ignore
+                to_ext_id = entity_external_id_lookup.get(item.to_id) if item.to_id else None
                 return RelationSummary(
                     relation_id=item.id,
                     entity_id=item.entity_id,  # pyright: ignore
@@ -77,8 +96,10 @@ async def to_graph_context(
                     relation_type=item.relation_type,  # pyright: ignore
                     from_entity=from_title,
                     from_entity_id=item.from_id,  # pyright: ignore
+                    from_entity_external_id=from_ext_id,
                     to_entity=to_title,
                     to_entity_id=item.to_id,
+                    to_entity_external_id=to_ext_id,
                     created_at=item.created_at,
                 )
             case _:  # pragma: no cover
@@ -125,6 +146,7 @@ async def to_graph_context(
         metadata=metadata,
         page=page,
         page_size=page_size,
+        has_more=context_result.metadata.has_more,
     )
 
 
@@ -155,6 +177,7 @@ async def to_search_results(entity_service: EntityService, results: List[SearchI
                 score=r.score,  # pyright: ignore
                 entity=entities[0].permalink if entities else None,
                 content=r.content,
+                matched_chunk=r.matched_chunk_text,
                 file_path=r.file_path,
                 metadata=r.metadata,
                 entity_id=entity_id,

src/basic_memory/cli/analytics.py

@@ -0,0 +1,114 @@
+"""Lightweight CLI analytics via Umami event collector.
+
+Sends anonymous, non-blocking usage events to help understand how the
+CLI-to-cloud conversion funnel performs. No PII, no fingerprinting,
+no cookies. Respects the same opt-out mechanisms as promo messaging.
+
+Events are fire-and-forget — analytics never blocks or breaks the CLI.
+
+Defaults point to the Basic Memory Umami Cloud instance. Override via:
+    BASIC_MEMORY_UMAMI_HOST     — Custom Umami instance URL
+    BASIC_MEMORY_UMAMI_SITE_ID  — Custom Website ID
+Opt out entirely with BASIC_MEMORY_NO_PROMOS=1.
+"""
+
+import json
+import os
+import threading
+import urllib.request
+from typing import Optional
+
+import basic_memory
+
+
+# ---------------------------------------------------------------------------
+# Configuration — defaults baked in, overridable via environment
+# ---------------------------------------------------------------------------
+
+_DEFAULT_UMAMI_HOST = "https://api-gateway.umami.dev"
+_DEFAULT_UMAMI_SITE_ID = "f6479898-ebaf-4e60-bce2-6dc60a3f6c5c"
+
+
+def _umami_host() -> Optional[str]:
+    return os.getenv("BASIC_MEMORY_UMAMI_HOST", "").strip() or _DEFAULT_UMAMI_HOST
+
+
+def _umami_site_id() -> Optional[str]:
+    return os.getenv("BASIC_MEMORY_UMAMI_SITE_ID", "").strip() or _DEFAULT_UMAMI_SITE_ID
+
+
+def _analytics_disabled() -> bool:
+    """True when analytics should not fire."""
+    value = os.getenv("BASIC_MEMORY_NO_PROMOS", "").strip().lower()
+    return value in {"1", "true", "yes"}
+
+
+def _is_configured() -> bool:
+    """True when both host and site ID are available."""
+    return _umami_host() is not None and _umami_site_id() is not None
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+# Well-known event names for the promo/cloud funnel
+EVENT_PROMO_SHOWN = "cli-promo-shown"
+EVENT_PROMO_OPTED_OUT = "cli-promo-opted-out"
+EVENT_CLOUD_LOGIN_STARTED = "cli-cloud-login-started"
+EVENT_CLOUD_LOGIN_SUCCESS = "cli-cloud-login-success"
+EVENT_CLOUD_LOGIN_SUB_REQUIRED = "cli-cloud-login-sub-required"
+
+
+def track(event_name: str, data: Optional[dict] = None) -> None:
+    """Send an analytics event to Umami. Non-blocking, silent on failure.
+
+    Parameters
+    ----------
+    event_name:
+        Short kebab-case name (e.g. "cli-promo-shown").
+    data:
+        Optional dict of event properties (all values should be strings/numbers).
+    """
+    if _analytics_disabled() or not _is_configured():
+        return
+
+    host = _umami_host()
+    site_id = _umami_site_id()
+
+    # Umami v2 /api/send requires "type" at top level alongside "payload"
+    payload = {
+        "type": "event",
+        "payload": {
+            "hostname": "cli.basicmemory.com",
+            "language": "en",
+            "url": f"/cli/{event_name}",
+            "website": site_id,
+            "name": event_name,
+            "data": {
+                "version": basic_memory.__version__,
+                **(data or {}),
+            },
+        },
+    }
+
+    def _send():
+        try:
+            req = urllib.request.Request(
+                f"{host}/api/send",
+                data=json.dumps(payload).encode("utf-8"),
+                headers={
+                    "Content-Type": "application/json",
+                    # Umami's bot detection rejects non-browser User-Agents
+                    "User-Agent": "Mozilla/5.0 (compatible; BasicMemoryCLI/"
+                    f"{basic_memory.__version__})",
+                },
+            )
+            urllib.request.urlopen(req, timeout=3)
+        except Exception:
+            pass  # Never break the CLI for analytics
+
+    # Non-daemon so the process waits for the request to complete.
+    # The 3s urllib timeout caps the worst-case exit delay.
+    t = threading.Thread(target=_send)
+    t.start()

src/basic_memory/cli/app.py

@@ -9,6 +9,7 @@ from typing import Optional  # noqa: E402
 import typer  # noqa: E402
 
 from basic_memory.cli.container import CliContainer, set_container  # noqa: E402
+from basic_memory.cli.promo import maybe_show_cloud_promo, maybe_show_init_line  # noqa: E402
 from basic_memory.config import init_cli_logging  # noqa: E402
 
 
@@ -46,11 +47,31 @@ def app_callback(
     container = CliContainer.create()
     set_container(container)
 
+    # Trigger: first-run init confirmation before command output.
+    # Why: informational "initialized" message belongs above command results, not in the upsell panel.
+    # Outcome: one-time plain line printed before the subcommand runs.
+    maybe_show_init_line(ctx.invoked_subcommand)
+
+    # Trigger: register promo as a post-command callback.
+    # Why: promo output should appear after the command's own output, not before.
+    # Outcome: promo panel renders below the command results (status tree, table, etc.).
+    ctx.call_on_close(lambda: maybe_show_cloud_promo(ctx.invoked_subcommand))
+
     # Run initialization for commands that don't use the API
     # 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 = {"mcp", "status", "sync", "project", "tool", "reset"}
+    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,11 +1,19 @@
 """CLI commands for basic-memory."""
 
-from . import status, db, import_memory_json, mcp, import_claude_conversations
-from . import import_claude_projects, import_chatgpt, tool, project, format
+from . import status, db, doctor, import_memory_json, mcp, import_claude_conversations
+from . import (
+    import_claude_projects,
+    import_chatgpt,
+    tool,
+    project,
+    format,
+    schema,
+)
 
 __all__ = [
     "status",
     "db",
+    "doctor",
     "import_memory_json",
     "mcp",
     "import_claude_conversations",
@@ -14,4 +22,5 @@ __all__ = [
     "tool",
     "project",
     "format",
+    "schema",
 ]

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

@@ -6,11 +6,14 @@ from basic_memory.cli.app import cloud_app
 from basic_memory.cli.commands.cloud.core_commands import *  # noqa: F401,F403
 from basic_memory.cli.commands.cloud.api_client import get_authenticated_headers, get_cloud_config  # noqa: F401
 from basic_memory.cli.commands.cloud.upload_command import *  # noqa: F401,F403
+from basic_memory.cli.commands.cloud.project_sync import *  # noqa: F401,F403
 
 # Register snapshot sub-command group
 from basic_memory.cli.commands.cloud.snapshot import snapshot_app
+from basic_memory.cli.commands.cloud.workspace import workspace_app
 
 cloud_app.add_typer(snapshot_app, name="snapshot")
+cloud_app.add_typer(workspace_app, name="workspace")
 
 # Register restore command (directly on cloud_app via decorator)
 from basic_memory.cli.commands.cloud.restore import restore  # noqa: F401, E402

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

@@ -52,7 +52,7 @@ async def get_authenticated_headers(auth: CLIAuth | None = None) -> dict[str, st
     auth_obj = auth or CLIAuth(client_id=client_id, authkit_domain=domain)
     token = await auth_obj.get_valid_token()
     if not token:
-        console.print("[red]Not authenticated. Please run 'basic-memory cloud login' first.[/red]")
+        console.print("[red]Not authenticated. Please run 'bm cloud login' first.[/red]")
         raise typer.Exit(1)
 
     return {"Authorization": f"Bearer {token}"}

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

@@ -30,7 +30,7 @@ async def fetch_cloud_projects(
         config = config_manager.config
         host_url = config.cloud_host.rstrip("/")
 
-        response = await api_request(method="GET", url=f"{host_url}/proxy/projects/projects")
+        response = await api_request(method="GET", url=f"{host_url}/proxy/v2/projects/")
 
         return CloudProjectList.model_validate(response.json())
     except Exception as e:
@@ -66,7 +66,7 @@ async def create_cloud_project(
 
         response = await api_request(
             method="POST",
-            url=f"{host_url}/proxy/projects/projects",
+            url=f"{host_url}/proxy/v2/projects/",
             headers={"Content-Type": "application/json"},
             json_data=project_data.model_dump(),
         )

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

@@ -6,6 +6,14 @@ 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.cli.analytics import (
+    track,
+    EVENT_CLOUD_LOGIN_STARTED,
+    EVENT_CLOUD_LOGIN_SUCCESS,
+    EVENT_CLOUD_LOGIN_SUB_REQUIRED,
+    EVENT_PROMO_OPTED_OUT,
+)
+from basic_memory.cli.promo import OSS_DISCOUNT_CODE
 from basic_memory.config import ConfigManager
 from basic_memory.cli.commands.cloud.api_client import (
     CloudAPIError,
@@ -29,9 +37,10 @@ console = Console()
 
 @cloud_app.command()
 def login():
-    """Authenticate with WorkOS using OAuth Device Authorization flow and enable cloud mode."""
+    """Authenticate with WorkOS using OAuth Device Authorization flow."""
 
     async def _login():
+        track(EVENT_CLOUD_LOGIN_STARTED)
         client_id, domain, host_url = get_cloud_config()
         auth = CLIAuth(client_id=client_id, authkit_domain=domain)
 
@@ -45,18 +54,17 @@ def login():
             console.print("[dim]Verifying subscription access...[/dim]")
             await make_api_request("GET", f"{host_url.rstrip('/')}/proxy/health")
 
-            # Enable cloud mode after successful login and subscription validation
-            config_manager = ConfigManager()
-            config = config_manager.load_config()
-            config.cloud_mode = True
-            config_manager.save_config(config)
-
-            console.print("[green]Cloud mode enabled[/green]")
-            console.print(f"[dim]All CLI commands now work against {host_url}[/dim]")
+            track(EVENT_CLOUD_LOGIN_SUCCESS)
+            console.print("[green]Cloud authentication successful[/green]")
+            console.print(f"[dim]Cloud host ready: {host_url}[/dim]")
 
         except SubscriptionRequiredError as e:
+            track(EVENT_CLOUD_LOGIN_SUB_REQUIRED)
             console.print("\n[red]Subscription Required[/red]\n")
             console.print(f"[yellow]{e.args[0]}[/yellow]\n")
+            console.print(
+                f"OSS discount code: [bold]{OSS_DISCOUNT_CODE}[/bold] (20% off for 3 months)\n"
+            )
             console.print(f"Subscribe at: [blue underline]{e.subscribe_url}[/blue underline]\n")
             console.print(
                 "[dim]Once you have an active subscription, run [bold]bm cloud login[/bold] again.[/dim]"
@@ -68,71 +76,56 @@ def login():
 
 @cloud_app.command()
 def logout():
-    """Disable cloud mode and return to local mode."""
-
-    # Disable cloud mode
-    config_manager = ConfigManager()
-    config = config_manager.load_config()
-    config.cloud_mode = False
-    config_manager.save_config(config)
-
-    console.print("[green]Cloud mode disabled[/green]")
-    console.print("[dim]All CLI commands now work locally[/dim]")
+    """Remove stored OAuth tokens."""
+    config = ConfigManager().config
+    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+    auth.logout()
+    console.print("[dim]API key (if configured) remains available for cloud project routing.[/dim]")
 
 
 @cloud_app.command("status")
 def status() -> None:
-    """Check cloud mode status and cloud instance health."""
-    # Check cloud mode
+    """Check cloud authentication and connection status."""
     config_manager = ConfigManager()
     config = config_manager.load_config()
+    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+    tokens = auth.load_tokens()
 
-    console.print("[bold blue]Cloud Mode Status[/bold blue]")
-    if config.cloud_mode:
-        console.print("  Mode: [green]Cloud (enabled)[/green]")
-        console.print(f"  Host: {config.cloud_host}")
-        console.print("  [dim]All CLI commands work against cloud[/dim]")
-    else:
-        console.print("  Mode: [yellow]Local (disabled)[/yellow]")
-        console.print("  [dim]All CLI commands work locally[/dim]")
-        console.print("\n[dim]To enable cloud mode, run: bm cloud login[/dim]")
+    console.print("[bold blue]Cloud Status[/bold blue]")
+    console.print(f"  Host: {config.cloud_host}")
+    console.print(
+        f"  API Key: {'[green]configured[/green]' if config.cloud_api_key else '[yellow]not set[/yellow]'}"
+    )
+
+    oauth_status = "[yellow]not logged in[/yellow]"
+    if tokens:
+        if auth.is_token_valid(tokens):
+            oauth_status = "[green]token valid[/green]"
+        else:
+            oauth_status = "[yellow]token expired[/yellow]"
+    console.print(f"  OAuth: {oauth_status}")
+
+    has_credentials = bool(config.cloud_api_key) or tokens is not None
+    if not has_credentials:
+        console.print(
+            "\n[dim]No cloud credentials found. Run: bm cloud login or bm cloud api-key save <key>[/dim]"
+        )
         return
 
-    # Get cloud configuration
+    # Quick connection check — just verify we can reach the cloud
     _, _, host_url = get_cloud_config()
     host_url = host_url.rstrip("/")
 
-    # Prepare headers
-    headers = {}
-
     try:
-        console.print("\n[blue]Checking cloud instance health...[/blue]")
-
-        # Make API request to check health
-        response = run_with_cleanup(
-            make_api_request(method="GET", url=f"{host_url}/proxy/health", headers=headers)
+        run_with_cleanup(make_api_request(method="GET", url=f"{host_url}/proxy/health"))
+        console.print("\n[green]Cloud connected[/green]")
+    except CloudAPIError:
+        console.print("\n[yellow]Cloud not connected[/yellow]")
+        console.print(
+            "[dim]Try re-authenticating with 'bm cloud login' or 'bm cloud api-key save'.[/dim]"
         )
-
-        health_data = response.json()
-
-        console.print("[green]Cloud instance is healthy[/green]")
-
-        # Display status details
-        if "status" in health_data:
-            console.print(f"  Status: {health_data['status']}")
-        if "version" in health_data:
-            console.print(f"  Version: {health_data['version']}")
-        if "timestamp" in health_data:
-            console.print(f"  Timestamp: {health_data['timestamp']}")
-
-        console.print("\n[dim]To sync projects, use: bm project bisync --name <project>[/dim]")
-
-    except CloudAPIError as e:
-        console.print(f"[red]Error checking cloud health: {e}[/red]")
-        raise typer.Exit(1)
-    except Exception as e:
-        console.print(f"[red]Unexpected error: {e}[/red]")
-        raise typer.Exit(1)
+    except Exception:
+        console.print("\n[yellow]Cloud not connected[/yellow]")
 
 
 @cloud_app.command("setup")
@@ -140,7 +133,7 @@ def setup() -> None:
     """Set up cloud sync by installing rclone and configuring credentials.
 
     After setup, use project commands for syncing:
-      bm project add <name> <path> --local-path ~/projects/<name>
+      bm project add <name> --cloud --local-path ~/projects/<name>
       bm project bisync --name <name> --resync  # First time
       bm project bisync --name <name>            # Subsequent syncs
     """
@@ -172,7 +165,7 @@ def setup() -> None:
         console.print("\n[bold green]Cloud setup completed successfully![/bold green]")
         console.print("\n[bold]Next steps:[/bold]")
         console.print("1. Add a project with local sync path:")
-        console.print("   bm project add research --local-path ~/Documents/research")
+        console.print("   bm project add research --cloud --local-path ~/Documents/research")
         console.print("\n   Or configure sync for an existing project:")
         console.print("   bm project sync-setup research ~/Documents/research")
         console.print("\n2. Preview the initial sync (recommended):")
@@ -191,3 +184,98 @@ def setup() -> None:
     except Exception as e:
         console.print(f"\n[red]Unexpected error during setup: {e}[/red]")
         raise typer.Exit(1)
+
+
+@cloud_app.command("promo")
+def promo(enabled: bool = typer.Option(True, "--on/--off", help="Enable or disable CLI promos.")):
+    """Enable or disable CLI cloud promo messages."""
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+    config.cloud_promo_opt_out = not enabled
+    config_manager.save_config(config)
+
+    if enabled:
+        console.print("[green]Cloud promo messages enabled[/green]")
+    else:
+        track(EVENT_PROMO_OPTED_OUT)
+        console.print("[yellow]Cloud promo messages disabled[/yellow]")
+
+
+# --- API key management subcommand group ---
+
+api_key_app = typer.Typer(help="Manage cloud API keys")
+cloud_app.add_typer(api_key_app, name="api-key")
+
+
+@api_key_app.command("save")
+def api_key_save(
+    api_key: str = typer.Argument(..., help="API key (bmc_ prefixed) for cloud access"),
+) -> None:
+    """Save an existing API key to local config.
+
+    Use when you already have an API key (e.g., from the web app).
+
+    Example:
+      bm cloud api-key save bmc_abc123...
+    """
+    if not api_key.startswith("bmc_"):
+        console.print("[red]Error: API key must start with 'bmc_'[/red]")
+        raise typer.Exit(1)
+
+    config_manager = ConfigManager()
+    config = config_manager.load_config()
+    config.cloud_api_key = api_key
+    config_manager.save_config(config)
+
+    console.print("[green]API key saved[/green]")
+    console.print("[dim]Projects set to cloud mode will use this key for authentication[/dim]")
+    console.print("[dim]Set a project to cloud mode: bm project set-cloud <name>[/dim]")
+
+
+@api_key_app.command("create")
+def api_key_create(
+    name: str = typer.Argument(..., help="Human-readable name for the API key"),
+) -> None:
+    """Create a new API key via the cloud API and save it locally.
+
+    Requires active OAuth session (run 'bm cloud login' first).
+
+    Example:
+      bm cloud api-key create "my-laptop"
+    """
+
+    async def _create_key():
+        _, _, host_url = get_cloud_config()
+        host_url = host_url.rstrip("/")
+
+        console.print(f"[dim]Creating API key '{name}'...[/dim]")
+        response = await make_api_request(
+            method="POST",
+            url=f"{host_url}/api/keys",
+            json_data={"name": name},
+        )
+
+        key_data = response.json()
+        api_key = key_data.get("key")
+        if not api_key:
+            console.print("[red]Error: No key returned from API[/red]")
+            raise typer.Exit(1)
+
+        # Save to config
+        config_manager = ConfigManager()
+        config = config_manager.load_config()
+        config.cloud_api_key = api_key
+        config_manager.save_config(config)
+
+        console.print(f"[green]API key '{name}' created and saved[/green]")
+        console.print("[dim]Projects set to cloud mode will use this key for authentication[/dim]")
+        console.print("[dim]Set a project to cloud mode: bm project set-cloud <name>[/dim]")
+
+    try:
+        run_with_cleanup(_create_key())
+    except CloudAPIError as e:
+        console.print(f"[red]Error creating API key: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Unexpected error: {e}[/red]")
+        raise typer.Exit(1)

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

@@ -0,0 +1,372 @@
+"""Cloud sync commands for Basic Memory projects.
+
+Commands for syncing, bisyncing, and checking integrity between local and cloud
+project instances. These were previously in project.py but belong here since
+they are cloud-specific operations.
+"""
+
+import os
+from datetime import datetime
+
+import typer
+from rich.console import Console
+
+from basic_memory.cli.app import cloud_app
+from basic_memory.cli.commands.cloud.bisync_commands import get_mount_info
+from basic_memory.cli.commands.cloud.rclone_commands import (
+    RcloneError,
+    SyncProject,
+    get_project_bisync_state,
+    project_bisync,
+    project_check,
+    project_sync,
+)
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.cli.commands.routing import force_routing
+from basic_memory.config import ConfigManager, ProjectEntry
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.clients import ProjectClient
+from basic_memory.schemas.project_info import ProjectItem
+from basic_memory.utils import generate_permalink, normalize_project_path
+
+console = Console()
+
+
+# --- Shared helpers ---
+
+
+def _has_cloud_credentials(config) -> bool:
+    """Return whether cloud credentials are available (API key or OAuth token)."""
+    from basic_memory.config import has_cloud_credentials
+
+    return has_cloud_credentials(config)
+
+
+def _require_cloud_credentials(config) -> None:
+    """Exit with actionable guidance when cloud credentials are missing."""
+    if _has_cloud_credentials(config):
+        return
+
+    console.print("[red]Error: cloud credentials are required for this command[/red]")
+    console.print("[dim]Run 'bm cloud login' or 'bm cloud api-key save <key>' first[/dim]")
+    raise typer.Exit(1)
+
+
+async def _get_cloud_project(name: str) -> ProjectItem | None:
+    """Fetch a project by name from the cloud API."""
+    async with get_client() as client:
+        projects_list = await ProjectClient(client).list_projects()
+        for proj in projects_list.projects:
+            if generate_permalink(proj.name) == generate_permalink(name):
+                return proj
+        return None
+
+
+def _get_sync_project(
+    name: str, config, project_data: ProjectItem
+) -> tuple[SyncProject, str | None]:
+    """Build a SyncProject and resolve local_sync_path from config.
+
+    Returns (sync_project, local_sync_path). Exits if no local_sync_path configured.
+    """
+    sync_entry = config.projects.get(name)
+    # Support both new (path) and legacy (local_sync_path) configs
+    local_sync_path = (sync_entry.local_sync_path or sync_entry.path) if sync_entry else None
+
+    if not local_sync_path or not os.path.isabs(local_sync_path):
+        console.print(f"[red]Error: Project '{name}' has no local sync path configured[/red]")
+        console.print(f"\nConfigure sync with: bm cloud sync-setup {name} ~/path/to/local")
+        raise typer.Exit(1)
+
+    sync_project = SyncProject(
+        name=project_data.name,
+        path=normalize_project_path(project_data.path),
+        local_sync_path=local_sync_path,
+    )
+    return sync_project, local_sync_path
+
+
+# --- Commands ---
+
+
+@cloud_app.command("sync")
+def sync_project_command(
+    name: str = typer.Option(..., "--name", help="Project name to sync"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without syncing"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """One-way sync: local -> cloud (make cloud identical to local).
+
+    Example:
+      bm cloud sync --name research
+      bm cloud sync --name research --dry-run
+    """
+    config = ConfigManager().config
+    _require_cloud_credentials(config)
+
+    try:
+        # Get tenant info for bucket name
+        tenant_info = run_with_cleanup(get_mount_info())
+        bucket_name = tenant_info.bucket_name
+
+        # Get project info
+        with force_routing(cloud=True):
+            project_data = run_with_cleanup(_get_cloud_project(name))
+        if not project_data:
+            console.print(f"[red]Error: Project '{name}' not found[/red]")
+            raise typer.Exit(1)
+
+        sync_project, local_sync_path = _get_sync_project(name, config, project_data)
+
+        # Run sync
+        console.print(f"[blue]Syncing {name} (local -> cloud)...[/blue]")
+        success = project_sync(sync_project, bucket_name, dry_run=dry_run, verbose=verbose)
+
+        if success:
+            console.print(f"[green]{name} synced successfully[/green]")
+
+            # Trigger database sync if not a dry run
+            if not dry_run:
+
+                async def _trigger_db_sync():
+                    async with get_client() as client:
+                        return await ProjectClient(client).sync(
+                            project_data.external_id, force_full=True
+                        )
+
+                try:
+                    with force_routing(cloud=True):
+                        result = run_with_cleanup(_trigger_db_sync())
+                    console.print(f"[dim]Database sync initiated: {result.get('message')}[/dim]")
+                except Exception as e:
+                    console.print(f"[yellow]Warning: Could not trigger database sync: {e}[/yellow]")
+        else:
+            console.print(f"[red]{name} sync failed[/red]")
+            raise typer.Exit(1)
+
+    except RcloneError as e:
+        console.print(f"[red]Sync error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("bisync")
+def bisync_project_command(
+    name: str = typer.Option(..., "--name", help="Project name to bisync"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Preview changes without syncing"),
+    resync: bool = typer.Option(False, "--resync", help="Force new baseline"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed output"),
+) -> None:
+    """Two-way sync: local <-> cloud (bidirectional sync).
+
+    Examples:
+      bm cloud bisync --name research --resync  # First time
+      bm cloud bisync --name research           # Subsequent syncs
+      bm cloud bisync --name research --dry-run # Preview changes
+    """
+    config = ConfigManager().config
+    _require_cloud_credentials(config)
+
+    try:
+        # Get tenant info for bucket name
+        tenant_info = run_with_cleanup(get_mount_info())
+        bucket_name = tenant_info.bucket_name
+
+        # Get project info
+        with force_routing(cloud=True):
+            project_data = run_with_cleanup(_get_cloud_project(name))
+        if not project_data:
+            console.print(f"[red]Error: Project '{name}' not found[/red]")
+            raise typer.Exit(1)
+
+        sync_project, local_sync_path = _get_sync_project(name, config, project_data)
+
+        # Run bisync
+        console.print(f"[blue]Bisync {name} (local <-> cloud)...[/blue]")
+        success = project_bisync(
+            sync_project, bucket_name, dry_run=dry_run, resync=resync, verbose=verbose
+        )
+
+        if success:
+            console.print(f"[green]{name} bisync completed successfully[/green]")
+
+            # Update config — sync_entry is guaranteed non-None because
+            # _get_sync_project validated local_sync_path (which comes from sync_entry)
+            sync_entry = config.projects.get(name)
+            assert sync_entry is not None
+            sync_entry.last_sync = datetime.now()
+            sync_entry.bisync_initialized = True
+            ConfigManager().save_config(config)
+
+            # Trigger database sync if not a dry run
+            if not dry_run:
+
+                async def _trigger_db_sync():
+                    async with get_client() as client:
+                        return await ProjectClient(client).sync(
+                            project_data.external_id, force_full=True
+                        )
+
+                try:
+                    with force_routing(cloud=True):
+                        result = run_with_cleanup(_trigger_db_sync())
+                    console.print(f"[dim]Database sync initiated: {result.get('message')}[/dim]")
+                except Exception as e:
+                    console.print(f"[yellow]Warning: Could not trigger database sync: {e}[/yellow]")
+        else:
+            console.print(f"[red]{name} bisync failed[/red]")
+            raise typer.Exit(1)
+
+    except RcloneError as e:
+        console.print(f"[red]Bisync error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("check")
+def check_project_command(
+    name: str = typer.Option(..., "--name", help="Project name to check"),
+    one_way: bool = typer.Option(False, "--one-way", help="Check one direction only (faster)"),
+) -> None:
+    """Verify file integrity between local and cloud.
+
+    Example:
+      bm cloud check --name research
+    """
+    config = ConfigManager().config
+    _require_cloud_credentials(config)
+
+    try:
+        # Get tenant info for bucket name
+        tenant_info = run_with_cleanup(get_mount_info())
+        bucket_name = tenant_info.bucket_name
+
+        # Get project info
+        with force_routing(cloud=True):
+            project_data = run_with_cleanup(_get_cloud_project(name))
+        if not project_data:
+            console.print(f"[red]Error: Project '{name}' not found[/red]")
+            raise typer.Exit(1)
+
+        sync_project, local_sync_path = _get_sync_project(name, config, project_data)
+
+        # Run check
+        console.print(f"[blue]Checking {name} integrity...[/blue]")
+        match = project_check(sync_project, bucket_name, one_way=one_way)
+
+        if match:
+            console.print(f"[green]{name} files match[/green]")
+        else:
+            console.print(f"[yellow]!{name} has differences[/yellow]")
+
+    except RcloneError as e:
+        console.print(f"[red]Check error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("bisync-reset")
+def bisync_reset(
+    name: str = typer.Argument(..., help="Project name to reset bisync state for"),
+) -> None:
+    """Clear bisync state for a project.
+
+    This removes the bisync metadata files, forcing a fresh --resync on next bisync.
+    Useful when bisync gets into an inconsistent state or when remote path changes.
+    """
+    import shutil
+
+    try:
+        state_path = get_project_bisync_state(name)
+
+        if not state_path.exists():
+            console.print(f"[yellow]No bisync state found for project '{name}'[/yellow]")
+            return
+
+        # Remove the entire state directory
+        shutil.rmtree(state_path)
+        console.print(f"[green]Cleared bisync state for project '{name}'[/green]")
+        console.print("\nNext steps:")
+        console.print(f"  1. Preview: bm cloud bisync --name {name} --resync --dry-run")
+        console.print(f"  2. Sync: bm cloud bisync --name {name} --resync")
+
+    except Exception as e:
+        console.print(f"[red]Error clearing bisync state: {str(e)}[/red]")
+        raise typer.Exit(1)
+
+
+@cloud_app.command("sync-setup")
+def setup_project_sync(
+    name: str = typer.Argument(..., help="Project name"),
+    local_path: str = typer.Argument(..., help="Local sync directory"),
+) -> None:
+    """Configure local sync for an existing cloud project.
+
+    Example:
+      bm cloud sync-setup research ~/Documents/research
+    """
+    import os
+    from pathlib import Path
+
+    config_manager = ConfigManager()
+    config = config_manager.config
+    _require_cloud_credentials(config)
+
+    async def _verify_project_exists():
+        """Verify the project exists on cloud by listing all projects."""
+        async with get_client() as client:
+            projects_list = await ProjectClient(client).list_projects()
+            project_names = [p.name for p in projects_list.projects]
+            if name not in project_names:
+                raise ValueError(f"Project '{name}' not found on cloud")
+            return True
+
+    try:
+        # Verify project exists on cloud
+        with force_routing(cloud=True):
+            run_with_cleanup(_verify_project_exists())
+
+        # Resolve and create local path
+        resolved_path = Path(os.path.abspath(os.path.expanduser(local_path)))
+        resolved_path.mkdir(parents=True, exist_ok=True)
+
+        # Update project entry with sync path — path is always the local directory
+        entry = config.projects.get(name)
+        if entry:
+            entry.path = resolved_path.as_posix()
+            entry.local_sync_path = resolved_path.as_posix()
+            entry.bisync_initialized = False
+            entry.last_sync = None
+        else:
+            config.projects[name] = ProjectEntry(
+                path=resolved_path.as_posix(),
+                local_sync_path=resolved_path.as_posix(),
+            )
+        config_manager.save_config(config)
+
+        # Create the project in the local DB so the MCP server can immediately use it
+        async def _create_local_project():
+            async with get_client() as client:
+                data = {"name": name, "path": resolved_path.as_posix(), "set_default": False}
+                return await ProjectClient(client).create_project(data)
+
+        with force_routing(local=True):
+            try:
+                run_with_cleanup(_create_local_project())
+            except Exception:
+                pass  # Project may already exist locally; reconcile on next startup
+
+        console.print(f"[green]Sync configured for project '{name}'[/green]")
+        console.print(f"\nLocal sync path: {resolved_path}")
+        console.print("\nNext steps:")
+        console.print(f"  1. Preview: bm cloud bisync --name {name} --resync --dry-run")
+        console.print(f"  2. Sync: bm cloud bisync --name {name} --resync")
+    except Exception as e:
+        console.print(f"[red]Error configuring sync: {str(e)}[/red]")
+        raise typer.Exit(1)

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

@@ -27,6 +27,16 @@ console = Console()
 # Minimum rclone version for --create-empty-src-dirs support
 MIN_RCLONE_VERSION_EMPTY_DIRS = (1, 64, 0)
 
+# Tigris edge caching returns stale data for users outside the origin region (iad).
+# --header is rclone's global flag that applies to ALL HTTP transactions (list, download,
+# upload). This is critical because bisync starts with S3 ListObjectsV2, which is neither
+# a download nor upload — so --header-download/--header-upload would miss list requests.
+# See: https://www.tigrisdata.com/docs/objects/consistency/
+TIGRIS_CONSISTENCY_HEADERS = [
+    "--header",
+    "X-Tigris-Consistent: true",
+]
+
 
 class RunResult(Protocol):
     returncode: int
@@ -210,8 +220,12 @@ def project_sync(
         "sync",
         str(local_path),
         remote_path,
+        *TIGRIS_CONSISTENCY_HEADERS,
         "--filter-from",
         str(filter_path),
+        # Prevent NUL byte padding on virtual filesystems (e.g. Google Drive File Stream)
+        # See: rclone/rclone#6801
+        "--local-no-preallocate",
     ]
 
     if verbose:
@@ -279,6 +293,7 @@ def project_bisync(
         "bisync",
         str(local_path),
         remote_path,
+        *TIGRIS_CONSISTENCY_HEADERS,
         "--resilient",
         "--conflict-resolve=newer",
         "--max-delete=25",
@@ -287,6 +302,9 @@ def project_bisync(
         str(filter_path),
         "--workdir",
         str(state_path),
+        # Prevent NUL byte padding on virtual filesystems (e.g. Google Drive File Stream)
+        # See: rclone/rclone#6801
+        "--local-no-preallocate",
     ]
 
     # Add --create-empty-src-dirs if rclone version supports it (v1.64+)
@@ -354,6 +372,7 @@ def project_check(
         "check",
         str(local_path),
         remote_path,
+        *TIGRIS_CONSISTENCY_HEADERS,
         "--filter-from",
         str(filter_path),
     ]
@@ -393,6 +412,6 @@ def project_ls(
     if path:
         remote_path = f"{remote_path}/{path}"
 
-    cmd = ["rclone", "ls", remote_path]
+    cmd = ["rclone", "ls", *TIGRIS_CONSISTENCY_HEADERS, remote_path]
     result = run(cmd, capture_output=True, text=True, check=True)
     return result.stdout.splitlines()

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

@@ -10,7 +10,6 @@ import httpx
 
 from basic_memory.ignore_utils import load_gitignore_patterns, should_ignore_path
 from basic_memory.mcp.async_client import get_client
-from basic_memory.mcp.tools.utils import call_put
 
 # Archive file extensions that should be skipped during upload
 ARCHIVE_EXTENSIONS = {".zip", ".tar", ".gz", ".bz2", ".xz", ".7z", ".rar", ".tgz", ".tbz2"}
@@ -24,7 +23,7 @@ async def upload_path(
     dry_run: bool = False,
     *,
     client_cm_factory: Callable[[], AbstractAsyncContextManager[httpx.AsyncClient]] | None = None,
-    put_func=call_put,
+    put_func: Callable | None = None,
 ) -> bool:
     """
     Upload a file or directory to cloud project via WebDAV.
@@ -117,9 +116,20 @@ async def upload_path(
 
                     # Upload via HTTP PUT to WebDAV endpoint with mtime header
                     # Using X-OC-Mtime (ownCloud/Nextcloud standard)
-                    response = await put_func(
-                        client, remote_path, content=content, headers={"X-OC-Mtime": str(mtime)}
-                    )
+                    if put_func is not None:
+                        # Test injection path
+                        response = await put_func(
+                            client,
+                            remote_path,
+                            content=content,
+                            headers={"X-OC-Mtime": str(mtime)},
+                        )
+                    else:
+                        response = await client.put(
+                            remote_path,
+                            content=content,
+                            headers={"X-OC-Mtime": str(mtime)},
+                        )
                     response.raise_for_status()
 
         # Format total size based on magnitude

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

@@ -13,6 +13,7 @@ from basic_memory.cli.commands.cloud.cloud_utils import (
     sync_project,
 )
 from basic_memory.cli.commands.cloud.upload import upload_path
+from basic_memory.mcp.async_client import get_cloud_control_plane_client
 
 console = Console()
 
@@ -86,7 +87,7 @@ def upload(
                 console.print(
                     f"[red]Project '{project}' does not exist.[/red]\n"
                     f"[yellow]Options:[/yellow]\n"
-                    f"  1. Create it first: bm project add {project}\n"
+                    f"  1. Create it first: bm project add {project} --cloud\n"
                     f"  2. Use --create-project flag to create automatically"
                 )
                 raise typer.Exit(1)
@@ -100,7 +101,12 @@ def upload(
             console.print(f"[blue]Uploading {path} to project '{project}'...[/blue]")
 
         success = await upload_path(
-            path, project, verbose=verbose, use_gitignore=not no_gitignore, dry_run=dry_run
+            path,
+            project,
+            verbose=verbose,
+            use_gitignore=not no_gitignore,
+            dry_run=dry_run,
+            client_cm_factory=get_cloud_control_plane_client,
         )
         if not success:
             console.print("[red]Upload failed[/red]")

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

@@ -0,0 +1,113 @@
+"""Workspace commands for Basic Memory cloud workspaces."""
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.project_context import (
+    _workspace_choices,
+    _workspace_matches_identifier,
+    get_available_workspaces,
+)
+
+console = Console()
+
+workspace_app = typer.Typer(help="Manage cloud workspaces")
+
+
+@workspace_app.command("list")
+def list_workspaces() -> None:
+    """List cloud workspaces available to the current OAuth session."""
+
+    async def _list():
+        return await get_available_workspaces()
+
+    try:
+        workspaces = run_with_cleanup(_list())
+    except RuntimeError as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        raise typer.Exit(1)
+    except Exception as exc:  # pragma: no cover
+        console.print(f"[red]Error listing workspaces: {exc}[/red]")
+        raise typer.Exit(1)
+
+    if not workspaces:
+        console.print("[yellow]No accessible workspaces found.[/yellow]")
+        return
+
+    config = ConfigManager().config
+    default_ws = config.default_workspace
+
+    table = Table(title="Available Workspaces")
+    table.add_column("Name", style="cyan")
+    table.add_column("Type", style="blue")
+    table.add_column("Role", style="green")
+    table.add_column("Tenant ID", style="yellow")
+    table.add_column("Default", style="magenta")
+
+    for workspace in workspaces:
+        is_default = "[X]" if workspace.tenant_id == default_ws else ""
+        table.add_row(
+            workspace.name,
+            workspace.workspace_type,
+            workspace.role,
+            workspace.tenant_id,
+            is_default,
+        )
+
+    console.print(table)
+
+
+@workspace_app.command("set-default")
+def set_default_workspace(
+    identifier: str = typer.Argument(..., help="Workspace name or tenant_id to set as default"),
+) -> None:
+    """Set the default cloud workspace.
+
+    The default workspace is used as fallback when no per-project workspace
+    is configured. Resolves the identifier against available workspaces.
+
+    Examples:
+      bm cloud workspace set-default Personal
+      bm cloud workspace set-default 11111111-1111-1111-1111-111111111111
+    """
+
+    async def _list():
+        return await get_available_workspaces()
+
+    try:
+        workspaces = run_with_cleanup(_list())
+    except RuntimeError as exc:
+        console.print(f"[red]Error: {exc}[/red]")
+        raise typer.Exit(1)
+
+    if not workspaces:
+        console.print("[yellow]No accessible workspaces found.[/yellow]")
+        raise typer.Exit(1)
+
+    matches = [ws for ws in workspaces if _workspace_matches_identifier(ws, identifier)]
+
+    if not matches:
+        console.print(f"[red]Error: Workspace '{identifier}' not found[/red]")
+        console.print(f"[dim]Available:\n{_workspace_choices(workspaces)}[/dim]")
+        raise typer.Exit(1)
+
+    if len(matches) > 1:
+        console.print(
+            f"[red]Error: Workspace name '{identifier}' matches multiple workspaces. "
+            f"Use tenant_id instead.[/red]"
+        )
+        console.print(f"[dim]Available:\n{_workspace_choices(workspaces)}[/dim]")
+        raise typer.Exit(1)
+
+    selected = matches[0]
+    config_manager = ConfigManager()
+    config = config_manager.config
+    config.default_workspace = selected.tenant_id
+    config_manager.save_config(config)
+
+    console.print(
+        f"[green]Default workspace set to '{selected.name}' ({selected.tenant_id})[/green]"
+    )

src/basic_memory/cli/commands/command_utils.py

@@ -9,11 +9,10 @@ import typer
 from rich.console import Console
 
 from basic_memory import db
+from basic_memory.config import ConfigManager
 from basic_memory.mcp.async_client import get_client
-
-from basic_memory.mcp.tools.utils import call_post, call_get
+from basic_memory.mcp.clients import ProjectClient
 from basic_memory.mcp.project_context import get_active_project
-from basic_memory.schemas import ProjectInfoResponse
 
 console = Console()
 
@@ -55,19 +54,18 @@ async def run_sync(
         run_in_background: If True, return immediately; if False, wait for completion
     """
 
+    # Resolve default project so get_client() can route per-project
+    project = project or ConfigManager().default_project
+
     try:
-        async with get_client() as client:
+        async with get_client(project_name=project) as client:
             project_item = await get_active_project(client, project, None)
-            url = f"{project_item.project_url}/project/sync"
-            params = []
-            if force_full:
-                params.append("force_full=true")
-            if not run_in_background:
-                params.append("run_in_background=false")
-            if params:
-                url += "?" + "&".join(params)
-            response = await call_post(client, url)
-            data = response.json()
+            project_client = ProjectClient(client)
+            data = await project_client.sync(
+                project_item.external_id,
+                force_full=force_full,
+                run_in_background=run_in_background,
+            )
             # Background mode returns {"message": "..."}, foreground returns SyncReportResponse
             if "message" in data:
                 console.print(f"[green]{data['message']}[/green]")
@@ -88,12 +86,24 @@ async def run_sync(
 
 async def get_project_info(project: str):
     """Get project information via API endpoint."""
-
     try:
-        async with get_client() as client:
+        async with get_client(project_name=project) as client:
             project_item = await get_active_project(client, project, None)
-            response = await call_get(client, f"{project_item.project_url}/project/info")
-            return ProjectInfoResponse.model_validate(response.json())
+            return await ProjectClient(client).get_info(project_item.external_id)
     except (ToolError, ValueError) as e:
-        console.print(f"[red]Sync failed: {e}[/red]")
+        error_text = str(e)
+        if "internal proxy error" in error_text.lower() and "not found in configuration" in (
+            error_text.lower()
+        ):
+            console.print(
+                "[red]Project info failed: cloud returned an internal configuration error for "
+                "this project.[/red]"
+            )
+            console.print(
+                "[yellow]This is a cloud backend issue for detailed info lookups. "
+                "Use `bm project list --cloud` for project metadata until the service is updated."
+                "[/yellow]"
+            )
+        else:
+            console.print(f"[red]Project info failed: {e}[/red]")
         raise typer.Exit(1)

src/basic_memory/cli/commands/db.py

@@ -5,12 +5,13 @@ from pathlib import Path
 import typer
 from loguru import logger
 from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TaskProgressColumn
 from sqlalchemy.exc import OperationalError
 
 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.config import ConfigManager, ProjectMode
 from basic_memory.repository import ProjectRepository
 from basic_memory.services.initialization import reconcile_projects_with_config
 from basic_memory.sync.sync_service import get_sync_service
@@ -103,3 +104,127 @@ def reset(
                 # ensures db.shutdown_db() is called even if _reindex_projects changes
                 run_with_cleanup(_reindex_projects(app_config))
                 console.print("[green]Reindex complete[/green]")
+
+
+@app.command()
+def reindex(
+    embeddings: bool = typer.Option(
+        False, "--embeddings", "-e", help="Rebuild vector embeddings (requires semantic search)"
+    ),
+    search: bool = typer.Option(False, "--search", "-s", help="Rebuild full-text search index"),
+    project: str = typer.Option(
+        None, "--project", "-p", help="Reindex a specific project (default: all)"
+    ),
+):  # pragma: no cover
+    """Rebuild search indexes and/or vector embeddings without dropping the database.
+
+    By default rebuilds everything (search + embeddings if semantic is enabled).
+    Use --search or --embeddings to rebuild only one.
+
+    Examples:
+        bm reindex                  # Rebuild everything
+        bm reindex --embeddings     # Only rebuild vector embeddings
+        bm reindex --search         # Only rebuild FTS index
+        bm reindex -p claw          # Reindex only the 'claw' project
+    """
+    # If neither flag is set, do both
+    if not embeddings and not search:
+        embeddings = True
+        search = True
+
+    config_manager = ConfigManager()
+    app_config = config_manager.config
+
+    if embeddings and not app_config.semantic_search_enabled:
+        console.print(
+            "[yellow]Semantic search is not enabled.[/yellow] "
+            "Set [cyan]semantic_search_enabled: true[/cyan] in config to use embeddings."
+        )
+        embeddings = False
+        if not search:
+            raise typer.Exit(0)
+
+    run_with_cleanup(_reindex(app_config, search=search, embeddings=embeddings, project=project))
+
+
+async def _reindex(app_config, search: bool, embeddings: bool, project: str | None):
+    """Run reindex operations."""
+    from basic_memory.repository import EntityRepository
+    from basic_memory.repository.search_repository import create_search_repository
+    from basic_memory.services.search_service import SearchService
+    from basic_memory.services.file_service import FileService
+    from basic_memory.markdown.markdown_processor import MarkdownProcessor
+    from basic_memory.markdown.entity_parser import EntityParser
+
+    try:
+        await reconcile_projects_with_config(app_config)
+
+        _, session_maker = await db.get_or_create_db(
+            db_path=app_config.database_path,
+            db_type=db.DatabaseType.FILESYSTEM,
+        )
+        project_repository = ProjectRepository(session_maker)
+        projects = await project_repository.get_active_projects()
+
+        if project:
+            projects = [p for p in projects if p.name == project]
+            if not projects:
+                # Check if it's a cloud-only project — those can't be reindexed locally
+                project_mode = app_config.get_project_mode(project)
+                if project_mode == ProjectMode.CLOUD:
+                    console.print(
+                        f"[yellow]Project '{project}' is a cloud project.[/yellow]\n"
+                        "Reindexing is a local operation — cloud projects are "
+                        "indexed on the server."
+                    )
+                else:
+                    console.print(f"[red]Project '{project}' not found.[/red]")
+                raise typer.Exit(1)
+
+        for proj in projects:
+            console.print(f"\n[bold]Project: [cyan]{proj.name}[/cyan][/bold]")
+
+            if search:
+                console.print("  Rebuilding full-text search index...")
+                sync_service = await get_sync_service(proj)
+                sync_dir = Path(proj.path)
+                await sync_service.sync(sync_dir, project_name=proj.name)
+                console.print("  [green]✓[/green] Full-text search index rebuilt")
+
+            if embeddings:
+                console.print("  Building vector embeddings...")
+                entity_repository = EntityRepository(session_maker, project_id=proj.id)
+                search_repository = create_search_repository(
+                    session_maker, project_id=proj.id, app_config=app_config
+                )
+                project_path = Path(proj.path)
+                entity_parser = EntityParser(project_path)
+                markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+                file_service = FileService(project_path, markdown_processor, app_config=app_config)
+                search_service = SearchService(search_repository, entity_repository, file_service)
+
+                with Progress(
+                    SpinnerColumn(),
+                    TextColumn("[progress.description]{task.description}"),
+                    BarColumn(),
+                    TaskProgressColumn(),
+                    console=console,
+                ) as progress:
+                    task = progress.add_task("  Embedding entities...", total=None)
+
+                    def on_progress(entity_id, index, total):
+                        progress.update(task, total=total, completed=index)
+
+                    stats = await search_service.reindex_vectors(progress_callback=on_progress)
+                    progress.update(task, completed=stats["total_entities"])
+
+                console.print(
+                    f"  [green]✓[/green] Embeddings complete: "
+                    f"{stats['embedded']} entities embedded, "
+                    f"{stats['skipped']} skipped, "
+                    f"{stats['errors']} errors"
+                )
+
+        console.print("\n[green]Reindex complete![/green]")
+    finally:
+        await db.shutdown_db()

src/basic_memory/cli/commands/doctor.py

@@ -0,0 +1,153 @@
+"""Doctor command for local consistency checks."""
+
+from __future__ import annotations
+
+import tempfile
+import uuid
+from pathlib import Path
+
+from loguru import logger
+from mcp.server.fastmcp.exceptions import ToolError
+from rich.console import Console
+import typer
+
+from basic_memory.cli.app import app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
+from basic_memory.markdown.entity_parser import EntityParser
+from basic_memory.markdown.markdown_processor import MarkdownProcessor
+from basic_memory.markdown.schemas import EntityFrontmatter, EntityMarkdown
+from basic_memory.mcp.async_client import get_client
+from basic_memory.mcp.clients import KnowledgeClient, ProjectClient, SearchClient
+from basic_memory.schemas.base import Entity
+from basic_memory.schemas.project_info import ProjectInfoRequest
+from basic_memory.schemas.search import SearchQuery
+from basic_memory.schemas import SyncReportResponse
+
+console = Console()
+
+
+async def run_doctor() -> None:
+    """Run local consistency checks for file <-> database flows."""
+    console.print("[blue]Running Basic Memory doctor checks...[/blue]")
+
+    project_name = f"doctor-{uuid.uuid4().hex[:8]}"
+    api_note_title = "Doctor API Note"
+    manual_note_title = "Doctor Manual Note"
+    manual_permalink = "doctor/manual-note"
+
+    with tempfile.TemporaryDirectory() as temp_dir:
+        temp_path = Path(temp_dir)
+
+        async with get_client() as client:
+            project_client = ProjectClient(client)
+            project_request = ProjectInfoRequest(
+                name=project_name,
+                path=str(temp_path),
+                set_default=False,
+            )
+
+            project_id: str | None = None
+
+            try:
+                status = await project_client.create_project(project_request.model_dump())
+                if not status.new_project:
+                    raise ValueError("Failed to create doctor project")
+                project_id = status.new_project.external_id
+                console.print(f"[green]OK[/green] Created doctor project: {project_name}")
+
+                # --- DB -> File: create an entity via API ---
+                knowledge_client = KnowledgeClient(client, project_id)
+                api_note = Entity(
+                    title=api_note_title,
+                    directory="doctor",
+                    note_type="note",
+                    content_type="text/markdown",
+                    content=f"# {api_note_title}\n\n- [note] API to file check",
+                    entity_metadata={"tags": ["doctor"]},
+                )
+                api_result = await knowledge_client.create_entity(api_note.model_dump(), fast=False)
+
+                api_file = temp_path / api_result.file_path
+                if not api_file.exists():
+                    raise ValueError(f"API note file missing: {api_result.file_path}")
+
+                api_text = api_file.read_text(encoding="utf-8")
+                if api_note_title not in api_text:
+                    raise ValueError("API note content missing from file")
+
+                console.print("[green]OK[/green] API write created file")
+
+                # --- File -> DB: write markdown file directly, then sync ---
+                parser = EntityParser(temp_path)
+                processor = MarkdownProcessor(parser)
+                manual_markdown = EntityMarkdown(
+                    frontmatter=EntityFrontmatter(
+                        metadata={
+                            "title": manual_note_title,
+                            "type": "note",
+                            "permalink": manual_permalink,
+                            "tags": ["doctor"],
+                        }
+                    ),
+                    content=f"# {manual_note_title}\n\n- [note] File to DB check",
+                )
+
+                manual_path = temp_path / "doctor" / "manual-note.md"
+                await processor.write_file(manual_path, manual_markdown)
+                console.print("[green]OK[/green] Manual file written")
+
+                sync_data = await project_client.sync(
+                    project_id, force_full=True, run_in_background=False
+                )
+                sync_report = SyncReportResponse.model_validate(sync_data)
+                if sync_report.total == 0:
+                    raise ValueError("Sync did not detect any changes")
+
+                console.print("[green]OK[/green] Sync indexed manual file")
+
+                search_client = SearchClient(client, project_id)
+                search_query = SearchQuery(title=manual_note_title)
+                search_results = await search_client.search(
+                    search_query.model_dump(), page=1, page_size=5
+                )
+                if not any(result.title == manual_note_title for result in search_results.results):
+                    raise ValueError("Manual note not found in search index")
+
+                console.print("[green]OK[/green] Search confirmed manual file")
+
+                status_report = await project_client.get_status(project_id)
+                if status_report.total != 0:
+                    raise ValueError("Project status not clean after sync")
+
+                console.print("[green]OK[/green] Status clean after sync")
+
+            finally:
+                if project_id:
+                    await project_client.delete_project(project_id)
+
+    console.print("[green]Doctor checks passed.[/green]")
+
+
+@app.command()
+def doctor(
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+) -> None:
+    """Run local consistency checks to verify file/database sync."""
+    try:
+        validate_routing_flags(local, cloud)
+        # Doctor runs local filesystem checks — always default to local routing
+        if not local and not cloud:
+            local = True
+        with force_routing(local=local, cloud=cloud):
+            run_with_cleanup(run_doctor())
+    except (ToolError, ValueError) as e:
+        console.print(f"[red]Doctor failed: {e}[/red]")
+        raise typer.Exit(code=1)
+    except Exception as e:
+        logger.error(f"Doctor failed: {e}")
+        typer.echo(f"Doctor failed: {e}", err=True)
+        raise typer.Exit(code=1)  # pragma: no cover

src/basic_memory/cli/commands/format.py

@@ -183,10 +183,10 @@ def format(
     By default, formats all .md, .json, and .canvas files in the current project.
 
     Examples:
-        basic-memory format                    # Format all files in current project
-        basic-memory format --project research # Format files in specific project
-        basic-memory format notes/meeting.md   # Format a specific file
-        basic-memory format notes/             # Format all files in directory
+        bm format                    # Format all files in current project
+        bm format --project research # Format files in specific project
+        bm format notes/meeting.md   # Format a specific file
+        bm format notes/             # Format all files in directory
     """
     try:
         run_with_cleanup(run_format(path, project))

src/basic_memory/cli/commands/import_chatgpt.py

@@ -44,7 +44,7 @@ def import_chatgpt(
     2. Convert them to linear markdown conversations
     3. Save as clean, readable markdown files
 
-    After importing, run 'basic-memory sync' to index the new files.
+    After importing, run 'bm reindex --search' to index the new files.
     """
 
     try:
@@ -60,7 +60,9 @@ def import_chatgpt(
         console.print(f"\nImporting chats from {conversations_json}...writing to {base_path}")
 
         # Create importer and run import
-        importer = ChatGPTImporter(config.home, markdown_processor, file_service)
+        importer = ChatGPTImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
         with conversations_json.open("r", encoding="utf-8") as file:
             json_data = json.load(file)
             result = run_with_cleanup(importer.import_data(json_data, folder))
@@ -79,7 +81,7 @@ def import_chatgpt(
             )
         )
 
-        console.print("\nRun 'basic-memory sync' to index the new files.")
+        console.print("\nRun 'bm reindex --search' to index the new files.")
 
     except Exception as e:
         logger.error("Import failed")

src/basic_memory/cli/commands/import_claude_conversations.py

@@ -44,7 +44,7 @@ def import_claude(
     2. Create markdown files for each conversation
     3. Format content in clean, readable markdown
 
-    After importing, run 'basic-memory sync' to index the new files.
+    After importing, run 'bm reindex --search' to index the new files.
     """
 
     config = get_project_config()
@@ -57,7 +57,9 @@ def import_claude(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = ClaudeConversationsImporter(config.home, markdown_processor, file_service)
+        importer = ClaudeConversationsImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
 
         # Process the file
         base_path = config.home / folder
@@ -82,7 +84,7 @@ def import_claude(
             )
         )
 
-        console.print("\nRun 'basic-memory sync' to index the new files.")
+        console.print("\nRun 'bm reindex --search' to index the new files.")
 
     except Exception as e:
         logger.error("Import failed")

src/basic_memory/cli/commands/import_claude_projects.py

@@ -44,7 +44,7 @@ def import_projects(
     2. Store docs in a docs/ subdirectory
     3. Place prompt template in project root
 
-    After importing, run 'basic-memory sync' to index the new files.
+    After importing, run 'bm reindex --search' to index the new files.
     """
     config = get_project_config()
     try:
@@ -56,7 +56,9 @@ def import_projects(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = ClaudeProjectsImporter(config.home, markdown_processor, file_service)
+        importer = ClaudeProjectsImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
 
         # Process the file
         base_path = config.home / base_folder if base_folder else config.home
@@ -81,7 +83,7 @@ def import_projects(
             )
         )
 
-        console.print("\nRun 'basic-memory sync' to index the new files.")
+        console.print("\nRun 'bm reindex --search' to index the new files.")
 
     except Exception as e:
         logger.error("Import failed")

src/basic_memory/cli/commands/import_memory_json.py

@@ -55,7 +55,9 @@ def memory_json(
         markdown_processor, file_service = run_with_cleanup(get_importer_dependencies())
 
         # Create the importer
-        importer = MemoryJsonImporter(config.home, markdown_processor, file_service)
+        importer = MemoryJsonImporter(
+            config.home, markdown_processor, file_service, project_name=config.name
+        )
 
         # Process the file
         base_path = config.home if not destination_folder else config.home / destination_folder

src/basic_memory/cli/commands/mcp.py

@@ -1,76 +1,98 @@
 """MCP server command with streamable HTTP transport."""
 
 import os
+from typing import Any, Optional
+
 import typer
-from typing import Optional
+from loguru import logger
 
 from basic_memory.cli.app import app
 from basic_memory.config import ConfigManager, init_mcp_logging
 
-# Import mcp instance (has lifespan that handles initialization and file sync)
-from basic_memory.mcp.server import mcp as mcp_server  # pragma: no cover
 
-# Import mcp tools to register them
-import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
+class _DeferredMcpServer:
+    def run(self, *args: Any, **kwargs: Any) -> None:  # pragma: no cover
+        from basic_memory.mcp.server import mcp as live_mcp_server
 
-# Import prompts to register them
-import basic_memory.mcp.prompts  # noqa: F401  # pragma: no cover
-from loguru import logger
+        live_mcp_server.run(*args, **kwargs)
 
-config = ConfigManager().config
 
-if not config.cloud_mode_enabled:
+# Keep module-level attribute for tests/monkeypatching while deferring heavy import.
+mcp_server = _DeferredMcpServer()
 
-    @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:
+@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.
 
-        - stdio: Standard I/O (good for local usage)
-        - streamable-http: Recommended for web deployments (default)
-        - sse: Server-Sent Events (for compatibility with existing clients)
+    This command starts an MCP server using one of three transport options:
 
-        Initialization, file sync, and cleanup are handled by the MCP server's lifespan.
-        """
-        # Initialize logging for MCP (file only, stdout breaks protocol)
-        init_mcp_logging()
+    - stdio: Standard I/O (good for local usage)
+    - streamable-http: Recommended for web deployments
+    - 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)
+    Initialization, file sync, and cleanup are handled by the MCP server's lifespan.
 
-            # 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}")
+    Note: This command is available regardless of cloud mode setting.
+    Users who have cloud mode enabled can still use local MCP for Claude Code
+    and Claude Desktop while using cloud MCP for web and mobile access.
+    """
+    # --- Routing setup ---
+    # Trigger: MCP server command invocation.
+    # Why: HTTP/SSE transports serve as local API endpoints and must never
+    #      route through cloud. Stdio is a client-facing protocol that
+    #      should honor per-project routing (local or cloud).
+    # Outcome: HTTP/SSE get explicit local override; stdio passes through
+    #          whatever env vars are already set (honoring external overrides)
+    #          and defaults to per-project routing resolution.
+    if transport in ("streamable-http", "sse"):
+        os.environ["BASIC_MEMORY_FORCE_LOCAL"] = "true"
+        os.environ.pop("BASIC_MEMORY_FORCE_CLOUD", None)
+        os.environ["BASIC_MEMORY_EXPLICIT_ROUTING"] = "true"
+    # stdio: no env var manipulation — per-project routing applies by default,
+    # and externally-set env vars (e.g. BASIC_MEMORY_FORCE_CLOUD) are honored.
 
-        # Run the MCP server (blocks)
-        # Lifespan handles: initialization, migrations, file sync, cleanup
-        logger.info(f"Starting MCP server with {transport.upper()} transport")
+    # Import mcp tools/prompts to register them with the server
+    import basic_memory.mcp.tools  # noqa: F401  # pragma: no cover
+    import basic_memory.mcp.prompts  # noqa: F401  # pragma: no cover
+    import basic_memory.mcp.resources  # noqa: F401  # pragma: no cover
 
-        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",
-            )
+    # Initialize logging for MCP (file only, stdout breaks protocol)
+    init_mcp_logging()
+
+    # 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}")
+
+    # Run the MCP server (blocks)
+    # Lifespan handles: initialization, migrations, file sync, cleanup
+    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",
+        )

src/basic_memory/cli/commands/routing.py

@@ -0,0 +1,91 @@
+"""CLI routing utilities for --local/--cloud flag handling.
+
+This module provides utilities for CLI commands to override default routing.
+This allows users to force local or cloud routing per-command.
+
+The routing is controlled via environment variables:
+- BASIC_MEMORY_FORCE_LOCAL: When "true", forces local ASGI transport
+- BASIC_MEMORY_FORCE_CLOUD: When "true", forces cloud proxy transport
+- BASIC_MEMORY_EXPLICIT_ROUTING: When "true", signals that --local/--cloud
+  was explicitly passed, overriding per-project routing in get_client()
+- These are checked in basic_memory.mcp.async_client.get_client()
+"""
+
+import os
+from contextlib import contextmanager
+from typing import Generator
+
+
+@contextmanager
+def force_routing(local: bool = False, cloud: bool = False) -> Generator[None, None, None]:
+    """Context manager to temporarily override routing mode.
+
+    Sets environment variables that are checked by get_client() to determine
+    whether to use local ASGI transport or cloud proxy transport.
+
+    When either flag is set, BASIC_MEMORY_EXPLICIT_ROUTING is also set so
+    that get_client() skips per-project routing and honors the flag directly.
+    This only affects CLI commands — the MCP server sets FORCE_LOCAL directly
+    (without EXPLICIT_ROUTING), so per-project routing still works for MCP tools.
+
+    Args:
+        local: If True, force local ASGI transport
+        cloud: If True, force cloud proxy transport
+
+    Usage:
+        with force_routing(local=True):
+            # All API calls will use local ASGI transport
+            await some_api_call()
+
+    Raises:
+        ValueError: If both local and cloud are True
+    """
+    if local and cloud:
+        raise ValueError("Cannot specify both --local and --cloud")
+
+    # Save original values
+    original_force_local = os.environ.get("BASIC_MEMORY_FORCE_LOCAL")
+    original_force_cloud = os.environ.get("BASIC_MEMORY_FORCE_CLOUD")
+    original_explicit = os.environ.get("BASIC_MEMORY_EXPLICIT_ROUTING")
+
+    try:
+        if local:
+            os.environ["BASIC_MEMORY_FORCE_LOCAL"] = "true"
+            os.environ.pop("BASIC_MEMORY_FORCE_CLOUD", None)
+            os.environ["BASIC_MEMORY_EXPLICIT_ROUTING"] = "true"
+        elif cloud:
+            os.environ.pop("BASIC_MEMORY_FORCE_LOCAL", None)
+            os.environ["BASIC_MEMORY_FORCE_CLOUD"] = "true"
+            os.environ["BASIC_MEMORY_EXPLICIT_ROUTING"] = "true"
+        # If neither is set, don't change anything (use default behavior)
+        yield
+    finally:
+        # Restore original values
+        if original_force_local is None:
+            os.environ.pop("BASIC_MEMORY_FORCE_LOCAL", None)
+        else:
+            os.environ["BASIC_MEMORY_FORCE_LOCAL"] = original_force_local
+
+        if original_force_cloud is None:
+            os.environ.pop("BASIC_MEMORY_FORCE_CLOUD", None)
+        else:
+            os.environ["BASIC_MEMORY_FORCE_CLOUD"] = original_force_cloud
+
+        if original_explicit is None:
+            os.environ.pop("BASIC_MEMORY_EXPLICIT_ROUTING", None)
+        else:
+            os.environ["BASIC_MEMORY_EXPLICIT_ROUTING"] = original_explicit
+
+
+def validate_routing_flags(local: bool, cloud: bool) -> None:
+    """Validate that --local and --cloud flags are not both specified.
+
+    Args:
+        local: Value of --local flag
+        cloud: Value of --cloud flag
+
+    Raises:
+        ValueError: If both flags are True
+    """
+    if local and cloud:
+        raise ValueError("Cannot specify both --local and --cloud flags")

src/basic_memory/cli/commands/schema.py

@@ -0,0 +1,391 @@
+"""Schema management CLI commands for Basic Memory.
+
+Provides CLI access to schema validation, inference, and drift detection.
+Registered as a subcommand group: `bm schema validate`, `bm schema infer`, `bm schema diff`.
+
+Each command calls the corresponding MCP tool with output_format="json" and
+renders the result as Rich tables — same code path as `bm tool schema-*` but
+with human-friendly formatting.
+"""
+
+import json
+from typing import Annotated, Optional
+
+import typer
+from loguru import logger
+from rich.console import Console
+from rich.table import Table
+
+from basic_memory.cli.app import app
+from basic_memory.cli.commands.command_utils import run_with_cleanup
+from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
+from basic_memory.config import ConfigManager
+from basic_memory.mcp.tools import schema_diff as mcp_schema_diff
+from basic_memory.mcp.tools import schema_infer as mcp_schema_infer
+from basic_memory.mcp.tools import schema_validate as mcp_schema_validate
+
+console = Console()
+
+schema_app = typer.Typer(help="Schema management commands")
+app.add_typer(schema_app, name="schema")
+
+
+def _resolve_project_name(project: Optional[str]) -> Optional[str]:
+    """Resolve project name from CLI argument or config default."""
+    config_manager = ConfigManager()
+    if project is not None:
+        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)
+        return project_name
+    return config_manager.default_project
+
+
+# --- Rendering helpers ---
+
+
+def _render_validate_table(data: dict) -> None:
+    """Render a validation report dict as a Rich table."""
+    note_type = data.get("note_type")
+    title_label = note_type or "all"
+
+    table = Table(title=f"Schema Validation: {title_label}")
+    table.add_column("Note", style="cyan")
+    table.add_column("Status", justify="center")
+    table.add_column("Warnings", justify="right")
+    table.add_column("Errors", justify="right")
+
+    for result in data.get("results", []):
+        warnings = result.get("warnings", [])
+        errors = result.get("errors", [])
+        passed = result.get("passed", True)
+
+        if passed and not warnings:
+            status = "[green]pass[/green]"
+        elif passed:
+            status = "[yellow]warn[/yellow]"
+        else:
+            status = "[red]fail[/red]"
+
+        table.add_row(
+            result.get("note_identifier", ""),
+            status,
+            str(len(warnings)),
+            str(len(errors)),
+        )
+
+    console.print(table)
+    console.print(
+        f"\nSummary: {data.get('valid_count', 0)}/{data.get('total_notes', 0)} valid, "
+        f"{data.get('warning_count', 0)} warnings, {data.get('error_count', 0)} errors"
+    )
+
+
+def _render_infer_table(data: dict) -> None:
+    """Render an inference report dict as a Rich table."""
+    note_type = data.get("note_type", "")
+    notes_analyzed = data.get("notes_analyzed", 0)
+    suggested_required = data.get("suggested_required", [])
+    suggested_optional = data.get("suggested_optional", [])
+
+    console.print(f"\n[bold]Analyzing {notes_analyzed} notes with type: {note_type}...[/bold]\n")
+
+    table = Table(title="Field Frequencies")
+    table.add_column("Field", style="cyan")
+    table.add_column("Source")
+    table.add_column("Count", justify="right")
+    table.add_column("Percentage", justify="right")
+    table.add_column("Suggested")
+
+    for freq in data.get("field_frequencies", []):
+        pct = f"{freq.get('percentage', 0):.0%}"
+        name = freq.get("name", "")
+        if name in suggested_required:
+            suggested = "[green]required[/green]"
+        elif name in suggested_optional:
+            suggested = "[yellow]optional[/yellow]"
+        else:
+            suggested = "[dim]excluded[/dim]"
+
+        table.add_row(
+            name,
+            freq.get("source", ""),
+            str(freq.get("count", 0)),
+            pct,
+            suggested,
+        )
+
+    console.print(table)
+
+    suggested_schema = data.get("suggested_schema", {})
+    if suggested_schema:
+        console.print("\n[bold]Suggested schema:[/bold]")
+        console.print(json.dumps(suggested_schema, indent=2))
+
+
+def _render_diff_output(data: dict) -> None:
+    """Render a drift report dict as Rich output."""
+    note_type = data.get("note_type", "")
+    new_fields = data.get("new_fields", [])
+    dropped_fields = data.get("dropped_fields", [])
+    cardinality_changes = data.get("cardinality_changes", [])
+
+    has_drift = new_fields or dropped_fields or cardinality_changes
+
+    if not has_drift:
+        console.print(f"[green]No drift detected for {note_type} schema.[/green]")
+        return
+
+    console.print(f"\n[bold]Schema drift detected for {note_type}:[/bold]\n")
+
+    if new_fields:
+        console.print("[green]+ New fields (common in notes, not in schema):[/green]")
+        for f in new_fields:
+            console.print(
+                f"  + {f['name']}: {f.get('percentage', 0):.0%} of notes ({f.get('source', '')})"
+            )
+
+    if dropped_fields:
+        console.print("[red]- Dropped fields (in schema, rare in notes):[/red]")
+        for f in dropped_fields:
+            console.print(
+                f"  - {f['name']}: {f.get('percentage', 0):.0%} of notes ({f.get('source', '')})"
+            )
+
+    if cardinality_changes:
+        console.print("[yellow]~ Cardinality changes:[/yellow]")
+        for change in cardinality_changes:
+            console.print(f"  ~ {change}")
+
+
+# --- Commands ---
+
+
+@schema_app.command()
+def validate(
+    target: Annotated[
+        Optional[str],
+        typer.Argument(help="Note path or note type to validate"),
+    ] = None,
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project name."),
+    ] = None,
+    strict: bool = typer.Option(False, "--strict", help="Exit with error on validation failures"),
+    json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Validate notes against their schemas.
+
+    TARGET can be a note path (e.g., people/ada-lovelace.md) or a note type
+    (e.g., person). If omitted, validates all notes that have schemas.
+
+    Use --json for machine-readable output.
+    Use --strict to exit with error code 1 if any validation errors are found.
+    Use --local to force local routing when cloud mode is enabled.
+    Use --cloud to force cloud routing when cloud mode is disabled.
+    """
+    try:
+        validate_routing_flags(local, cloud)
+        project_name = _resolve_project_name(project)
+
+        # Heuristic: if target contains / or ., treat as identifier; otherwise as note type
+        note_type, identifier = None, None
+        if target:
+            if "/" in target or "." in target:
+                identifier = target
+            else:
+                note_type = target
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_schema_validate(
+                    note_type=note_type,
+                    identifier=identifier,
+                    project=project_name,
+                    output_format="json",
+                )
+            )
+
+        # Handle error responses
+        if isinstance(result, dict) and "error" in result:
+            if json_output:
+                print(json.dumps(result, indent=2, default=str))
+            else:
+                console.print(f"[yellow]{result['error']}[/yellow]")
+            return
+
+        # output_format="json" guarantees a dict return
+        assert isinstance(result, dict)
+
+        if json_output:
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            _render_validate_table(result)
+
+        if strict and result.get("error_count", 0) > 0:
+            raise typer.Exit(1)
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        if not isinstance(e, typer.Exit):
+            logger.error(f"Error during schema validate: {e}")
+            typer.echo(f"Error during schema validate: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@schema_app.command()
+def infer(
+    note_type: Annotated[
+        str,
+        typer.Argument(help="Note type to analyze (e.g., person, meeting)"),
+    ],
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project name."),
+    ] = None,
+    threshold: float = typer.Option(
+        0.25, "--threshold", help="Minimum frequency for optional fields (0-1)"
+    ),
+    save: bool = typer.Option(False, "--save", help="Save inferred schema to schema/ directory"),
+    json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Infer schema from existing notes of a type.
+
+    Analyzes all notes with the given type and suggests a Picoschema
+    definition based on observation and relation frequency.
+
+    Fields present in 95%+ of notes become required. Fields above the
+    threshold (default 25%) become optional. Fields below threshold are excluded.
+
+    Use --json for machine-readable output.
+    Use --local to force local routing when cloud mode is enabled.
+    Use --cloud to force cloud routing when cloud mode is disabled.
+    """
+    try:
+        validate_routing_flags(local, cloud)
+        project_name = _resolve_project_name(project)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_schema_infer(
+                    note_type=note_type,
+                    threshold=threshold,
+                    project=project_name,
+                    output_format="json",
+                )
+            )
+
+        # Handle error responses
+        if isinstance(result, dict) and "error" in result:
+            if json_output:
+                print(json.dumps(result, indent=2, default=str))
+            else:
+                console.print(f"[yellow]{result['error']}[/yellow]")
+            return
+
+        # output_format="json" guarantees a dict return
+        assert isinstance(result, dict)
+
+        # Handle zero notes
+        if result.get("notes_analyzed", 0) == 0:
+            if json_output:
+                print(json.dumps(result, indent=2, default=str))
+            else:
+                console.print(f"[yellow]No notes found with type: {note_type}[/yellow]")
+            return
+
+        if json_output:
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            _render_infer_table(result)
+
+        if save:
+            console.print(
+                f"\n[yellow]--save not yet implemented. "
+                f"Copy the schema above into schema/{note_type}.md[/yellow]"
+            )
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        if not isinstance(e, typer.Exit):
+            logger.error(f"Error during schema infer: {e}")
+            typer.echo(f"Error during schema infer: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+@schema_app.command()
+def diff(
+    note_type: Annotated[
+        str,
+        typer.Argument(help="Note type to check for drift"),
+    ],
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project name."),
+    ] = None,
+    json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Show drift between schema and actual usage.
+
+    Compares the existing schema definition against how notes of that type
+    are actually structured. Identifies new fields,
+    dropped fields, and cardinality changes.
+
+    Use --json for machine-readable output.
+    Use --local to force local routing when cloud mode is enabled.
+    Use --cloud to force cloud routing when cloud mode is disabled.
+    """
+    try:
+        validate_routing_flags(local, cloud)
+        project_name = _resolve_project_name(project)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_schema_diff(
+                    note_type=note_type,
+                    project=project_name,
+                    output_format="json",
+                )
+            )
+
+        # Handle error responses
+        if isinstance(result, dict) and "error" in result:
+            if json_output:
+                print(json.dumps(result, indent=2, default=str))
+            else:
+                console.print(f"[yellow]{result['error']}[/yellow]")
+            return
+
+        # output_format="json" guarantees a dict return
+        assert isinstance(result, dict)
+
+        if json_output:
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            _render_diff_output(result)
+    except ValueError as e:
+        console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(1)
+    except Exception as e:
+        if not isinstance(e, typer.Exit):
+            logger.error(f"Error during schema diff: {e}")
+            typer.echo(f"Error during schema diff: {e}", err=True)
+            raise typer.Exit(1)
+        raise

src/basic_memory/cli/commands/status.py

@@ -1,5 +1,6 @@
 """Status command for basic-memory CLI."""
 
+import json
 from typing import Set, Dict
 from typing import Annotated, Optional
 
@@ -11,8 +12,10 @@ from rich.panel import Panel
 from rich.tree import Tree
 
 from basic_memory.cli.app import app
+from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
+from basic_memory.config import ConfigManager
 from basic_memory.mcp.async_client import get_client
-from basic_memory.mcp.tools.utils import call_post
+from basic_memory.mcp.clients import ProjectClient
 from basic_memory.schemas import SyncReportResponse
 from basic_memory.mcp.project_context import get_active_project
 
@@ -139,20 +142,20 @@ def display_changes(
     console.print(Panel(tree, expand=False))
 
 
-async def run_status(project: Optional[str] = None, verbose: bool = False):  # pragma: no cover
-    """Check sync status of files vs database."""
+async def run_status(
+    project: Optional[str] = None,
+) -> tuple[str, SyncReportResponse]:
+    """Fetch sync status of files vs database.
 
-    try:
-        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())
+    Returns (project_name, sync_report) for the caller to render.
+    """
+    # Resolve default project so get_client() can route per-project
+    project = project or ConfigManager().default_project
 
-            display_changes(project_item.name, "Status", sync_report, verbose)
-
-    except (ValueError, ToolError) as e:
-        console.print(f"[red]Error: {e}[/red]")
-        raise typer.Exit(1)
+    async with get_client(project_name=project) as client:
+        project_item = await get_active_project(client, project, None)
+        sync_report = await ProjectClient(client).get_status(project_item.external_id)
+        return project_item.name, sync_report
 
 
 @app.command()
@@ -162,13 +165,48 @@ def status(
         typer.Option(help="The project name."),
     ] = None,
     verbose: bool = typer.Option(False, "--verbose", "-v", help="Show detailed file information"),
+    json_output: bool = typer.Option(False, "--json", help="Output in JSON format"),
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Show sync status between files and database."""
+    """Show sync status between files and database.
+
+    Use --json for machine-readable output.
+    Use --local to force local routing when cloud mode is enabled.
+    Use --cloud to force cloud routing when cloud mode is disabled.
+    """
     from basic_memory.cli.commands.command_utils import run_with_cleanup
 
     try:
-        run_with_cleanup(run_status(project, verbose))  # pragma: no cover
+        validate_routing_flags(local, cloud)
+        # Trigger: no explicit routing flag provided
+        # Why: status scans the local filesystem — cloud routing would use the
+        #      Docker-internal path stored in the cloud database, which doesn't
+        #      exist locally.
+        # Outcome: default to local routing unless --cloud was explicitly requested.
+        if not local and not cloud:
+            local = True
+        with force_routing(local=local, cloud=cloud):
+            project_name, sync_report = run_with_cleanup(run_status(project))
+
+        if json_output:
+            print(json.dumps(sync_report.model_dump(mode="json"), indent=2, default=str))
+        else:
+            display_changes(project_name, "Status", sync_report, verbose)
+    except (ValueError, ToolError) as e:
+        if json_output:
+            print(json.dumps({"error": str(e)}, indent=2))
+        else:
+            console.print(f"[red]Error: {e}[/red]")
+        raise typer.Exit(code=1)
+    except typer.Exit:
+        raise
     except Exception as e:
         logger.error(f"Error checking status: {e}")
-        typer.echo(f"Error checking status: {e}", err=True)
+        if json_output:
+            print(json.dumps({"error": str(e)}, indent=2))
+        else:
+            typer.echo(f"Error checking status: {e}", err=True)
         raise typer.Exit(code=1)  # pragma: no cover

src/basic_memory/cli/commands/tool.py

@@ -1,116 +1,120 @@
-"""CLI tool commands for Basic Memory."""
+"""CLI tool commands for Basic Memory.
 
+Every command calls its MCP tool with output_format="json" and prints the result.
+No text formatting, no separate code paths, no duplicate data fetching.
+"""
+
+import json
 import sys
-from typing import Annotated, List, Optional
+from typing import Annotated, Any, Dict, List, Optional
 
 import typer
 from loguru import logger
-from rich import print as rprint
 
 from basic_memory.cli.app import app
 from basic_memory.cli.commands.command_utils import run_with_cleanup
-from basic_memory.config import ConfigManager
-
-# Import prompts
-from basic_memory.mcp.prompts.continue_conversation import (
-    continue_conversation as mcp_continue_conversation,
-)
-from basic_memory.mcp.prompts.recent_activity import (
-    recent_activity_prompt as recent_activity_prompt,
-)
+from basic_memory.cli.commands.routing import force_routing, validate_routing_flags
 from basic_memory.mcp.tools import build_context as mcp_build_context
+from basic_memory.mcp.tools import edit_note as mcp_edit_note
+from basic_memory.mcp.tools import list_memory_projects as mcp_list_projects
+from basic_memory.mcp.tools import list_workspaces as mcp_list_workspaces
 from basic_memory.mcp.tools import read_note as mcp_read_note
 from basic_memory.mcp.tools import recent_activity as mcp_recent_activity
+from basic_memory.mcp.tools import schema_diff as mcp_schema_diff
+from basic_memory.mcp.tools import schema_infer as mcp_schema_infer
+from basic_memory.mcp.tools import schema_validate as mcp_schema_validate
 from basic_memory.mcp.tools import search_notes as mcp_search
 from basic_memory.mcp.tools import write_note as mcp_write_note
-from basic_memory.schemas.base import TimeFrame
-from basic_memory.schemas.memory import MemoryUrl
-from basic_memory.schemas.search import SearchItemType
 
 tool_app = typer.Typer()
 app.add_typer(tool_app, name="tool", help="Access to MCP tools via CLI")
 
+VALID_EDIT_OPERATIONS = ["append", "prepend", "find_replace", "replace_section"]
+
+
+# --- Shared helpers ---
+
+
+def _print_json(result: Any) -> None:
+    """Print a result as formatted JSON."""
+    print(json.dumps(result, indent=2, ensure_ascii=True, default=str))
+
+
+# --- Commands ---
+
 
 @tool_app.command()
 def write_note(
     title: Annotated[str, typer.Option(help="The title of the note")],
     folder: Annotated[str, typer.Option(help="The folder to create the note in")],
+    content: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The content of the note. If not provided, content will be read from stdin."
+        ),
+    ] = None,
+    tags: Annotated[
+        Optional[List[str]], typer.Option(help="A list of tags to apply to the note")
+    ] = None,
     project: Annotated[
         Optional[str],
         typer.Option(
             help="The project to write to. If not provided, the default project will be used."
         ),
     ] = None,
-    content: Annotated[
+    workspace: Annotated[
         Optional[str],
-        typer.Option(
-            help="The content of the note. If not provided, content will be read from stdin. This allows piping content from other commands, e.g.: cat file.md | basic-memory tools write-note"
-        ),
-    ] = None,
-    tags: Annotated[
-        Optional[List[str]], typer.Option(help="A list of tags to apply to the note")
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
     ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Create or update a markdown note. Content can be provided as an argument or read from stdin.
-
-    Content can be provided in two ways:
-    1. Using the --content parameter
-    2. Piping content through stdin (if --content is not provided)
+    """Create or update a markdown note. Content can be provided via --content or stdin.
 
     Examples:
 
-    # Using content parameter
-    basic-memory tools write-note --title "My Note" --folder "notes" --content "Note content"
-
-    # Using stdin pipe
-    echo "# My Note Content" | basic-memory tools write-note --title "My Note" --folder "notes"
-
-    # Using heredoc
-    cat << EOF | basic-memory tools write-note --title "My Note" --folder "notes"
-    # My Document
-
-    This is my document content.
-
-    - Point 1
-    - Point 2
-    EOF
-
-    # Reading from a file
-    cat document.md | basic-memory tools write-note --title "Document" --folder "docs"
+    bm tool write-note --title "My Note" --folder "notes" --content "Note content"
+    echo "content" | bm tool write-note --title "My Note" --folder "notes"
+    bm tool write-note --title "My Note" --folder "notes" --local
     """
     try:
+        validate_routing_flags(local, cloud)
+
         # If content is not provided, read from stdin
         if content is None:
-            # Check if we're getting data from a pipe or redirect
             if not sys.stdin.isatty():
                 content = sys.stdin.read()
             else:  # pragma: no cover
-                # If stdin is a terminal (no pipe/redirect), inform the user
                 typer.echo(
                     "No content provided. Please provide content via --content or by piping to stdin.",
                     err=True,
                 )
                 raise typer.Exit(1)
 
-        # Also check for empty content
         if content is not None and not content.strip():
             typer.echo("Empty content provided. Please provide non-empty content.", err=True)
             raise typer.Exit(1)
 
-        # look for the project in the config
-        config_manager = ConfigManager()
-        project_name = None
-        if project is not None:
-            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)
+        assert content is not None
 
-        # use the project name, or the default from the config
-        project_name = project_name or config_manager.default_project
-
-        note = run_with_cleanup(mcp_write_note.fn(title, content, folder, project_name, tags))
-        rprint(note)
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_write_note(
+                    title=title,
+                    content=content,
+                    directory=folder,
+                    project=project,
+                    workspace=workspace,
+                    tags=tags,
+                    output_format="json",
+                )
+            )
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during write_note: {e}", err=True)
@@ -121,32 +125,51 @@ def write_note(
 @tool_app.command()
 def read_note(
     identifier: str,
+    include_frontmatter: bool = typer.Option(
+        False, "--include-frontmatter", help="Include YAML frontmatter in output"
+    ),
+    page: int = typer.Option(1, "--page", help="Page number for pagination"),
+    page_size: int = typer.Option(10, "--page-size", help="Number of results per page"),
     project: Annotated[
         Optional[str],
-        typer.Option(
-            help="The project to use for the note. If not provided, the default project will be used."
-        ),
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    page: int = 1,
-    page_size: int = 10,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Read a markdown note from the knowledge base."""
+    """Read a markdown note from the knowledge base.
 
-    # look for the project in the config
-    config_manager = ConfigManager()
-    project_name = None
-    if project is not None:
-        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)
-
-    # use the project name, or the default from the config
-    project_name = project_name or config_manager.default_project
+    Examples:
 
+    bm tool read-note my-note
+    bm tool read-note my-note --include-frontmatter
+    bm tool read-note my-note --page 2 --page-size 5
+    """
     try:
-        note = run_with_cleanup(mcp_read_note.fn(identifier, project_name, page, page_size))
-        rprint(note)
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_read_note(
+                    identifier=identifier,
+                    project=project,
+                    workspace=workspace,
+                    page=page,
+                    page_size=page_size,
+                    include_frontmatter=include_frontmatter,
+                    output_format="json",
+                )
+            )
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during read_note: {e}", err=True)
@@ -154,50 +177,131 @@ def read_note(
         raise
 
 
+@tool_app.command()
+def edit_note(
+    identifier: str,
+    operation: Annotated[str, typer.Option("--operation", help="Edit operation to apply")],
+    content: Annotated[str, typer.Option("--content", help="Content for the edit operation")],
+    find_text: Annotated[
+        Optional[str], typer.Option("--find-text", help="Text to find for find_replace operation")
+    ] = None,
+    section: Annotated[
+        Optional[str],
+        typer.Option("--section", help="Section heading for replace_section operation"),
+    ] = None,
+    expected_replacements: int = typer.Option(
+        1,
+        "--expected-replacements",
+        help="Expected replacement count for find_replace operation",
+    ),
+    project: Annotated[
+        Optional[str],
+        typer.Option(
+            help="The project to edit. If not provided, the default project will be used."
+        ),
+    ] = None,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Edit an existing markdown note using append/prepend/find_replace/replace_section.
+
+    Examples:
+
+    bm tool edit-note my-note --operation append --content "new content"
+    bm tool edit-note my-note --operation find_replace --find-text "old" --content "new"
+    bm tool edit-note my-note --operation replace_section --section "## Notes" --content "updated"
+    """
+    try:
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_edit_note(
+                    identifier=identifier,
+                    operation=operation,
+                    content=content,
+                    project=project,
+                    workspace=workspace,
+                    section=section,
+                    find_text=find_text,
+                    expected_replacements=expected_replacements,
+                    output_format="json",
+                )
+            )
+
+        # MCP tool returns error field on failure in JSON mode
+        if isinstance(result, dict) and result.get("error"):
+            typer.echo(f"Error: {result['error']}", err=True)
+            raise typer.Exit(1)
+
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during edit_note: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
 @tool_app.command()
 def build_context(
-    url: MemoryUrl,
+    url: str,
+    depth: Optional[int] = typer.Option(1, "--depth", help="Depth of context to build"),
+    timeframe: Optional[str] = typer.Option(
+        "7d", "--timeframe", help="Timeframe filter (e.g., '7d', '1 week')"
+    ),
+    page: int = typer.Option(1, "--page", help="Page number for pagination"),
+    page_size: int = typer.Option(10, "--page-size", help="Number of results per page"),
+    max_related: int = typer.Option(10, "--max-related", help="Maximum related items to return"),
     project: Annotated[
         Optional[str],
         typer.Option(help="The project to use. If not provided, the default project will be used."),
     ] = None,
-    depth: Optional[int] = 1,
-    timeframe: Optional[TimeFrame] = "7d",
-    page: int = 1,
-    page_size: int = 10,
-    max_related: int = 10,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Get context needed to continue a discussion."""
+    """Get context needed to continue a discussion.
 
-    # look for the project in the config
-    config_manager = ConfigManager()
-    project_name = None
-    if project is not None:
-        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)
-
-    # use the project name, or the default from the config
-    project_name = project_name or config_manager.default_project
+    Examples:
 
+    bm tool build-context memory://specs/search
+    bm tool build-context specs/search --depth 2 --timeframe 30d
+    """
     try:
-        context = run_with_cleanup(
-            mcp_build_context.fn(
-                project=project_name,
-                url=url,
-                depth=depth,
-                timeframe=timeframe,
-                page=page,
-                page_size=page_size,
-                max_related=max_related,
-            )
-        )
-        # Use json module for more controlled serialization
-        import json
+        validate_routing_flags(local, cloud)
 
-        context_dict = context.model_dump(exclude_none=True)
-        print(json.dumps(context_dict, indent=2, ensure_ascii=True, default=str))
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_build_context(
+                    url=url,
+                    project=project,
+                    workspace=workspace,
+                    depth=depth,
+                    timeframe=timeframe,
+                    page=page,
+                    page_size=page_size,
+                    max_related=max_related,
+                    output_format="json",
+                )
+            )
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during build_context: {e}", err=True)
@@ -207,21 +311,54 @@ def build_context(
 
 @tool_app.command()
 def recent_activity(
-    type: Annotated[Optional[List[SearchItemType]], typer.Option()] = None,
-    depth: Optional[int] = 1,
-    timeframe: Optional[TimeFrame] = "7d",
+    type: Annotated[Optional[List[str]], typer.Option(help="Filter by item type")] = None,
+    depth: Optional[int] = typer.Option(1, "--depth", help="Depth of context to build"),
+    timeframe: Optional[str] = typer.Option(
+        "7d", "--timeframe", help="Timeframe filter (e.g., '7d', '1 week')"
+    ),
+    page: int = typer.Option(1, "--page", help="Page number for pagination"),
+    page_size: int = typer.Option(50, "--page-size", help="Number of results per page"),
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Get recent activity across the knowledge base."""
+    """Get recent activity across the knowledge base.
+
+    Examples:
+
+    bm tool recent-activity
+    bm tool recent-activity --timeframe 30d --page-size 20
+    bm tool recent-activity --type entity --type observation
+    """
     try:
-        result = run_with_cleanup(
-            mcp_recent_activity.fn(
-                type=type,  # pyright: ignore [reportArgumentType]
-                depth=depth,
-                timeframe=timeframe,
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_recent_activity(
+                    type=type,  # pyright: ignore[reportArgumentType]
+                    depth=depth if depth is not None else 1,
+                    timeframe=timeframe if timeframe is not None else "7d",
+                    page=page,
+                    page_size=page_size,
+                    project=project,
+                    workspace=workspace,
+                    output_format="json",
+                )
             )
-        )
-        # The tool now returns a formatted string directly
-        print(result)
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             typer.echo(f"Error during recent_activity: {e}", err=True)
@@ -231,69 +368,148 @@ def recent_activity(
 
 @tool_app.command("search-notes")
 def search_notes(
-    query: str,
+    query: Annotated[
+        Optional[str],
+        typer.Argument(help="Search query string (optional when using metadata filters)"),
+    ] = "",
     permalink: Annotated[bool, typer.Option("--permalink", help="Search permalink values")] = False,
     title: Annotated[bool, typer.Option("--title", help="Search title values")] = False,
-    project: Annotated[
-        Optional[str],
-        typer.Option(
-            help="The project to use for the note. If not provided, the default project will be used."
-        ),
-    ] = None,
+    vector: Annotated[bool, typer.Option("--vector", help="Use vector retrieval")] = False,
+    hybrid: Annotated[bool, typer.Option("--hybrid", help="Use hybrid retrieval")] = False,
     after_date: Annotated[
         Optional[str],
         typer.Option("--after_date", help="Search results after date, eg. '2d', '1 week'"),
     ] = None,
-    page: int = 1,
-    page_size: int = 10,
+    tags: Annotated[
+        Optional[List[str]],
+        typer.Option("--tag", help="Filter by frontmatter tag (repeatable)"),
+    ] = None,
+    status: Annotated[
+        Optional[str],
+        typer.Option("--status", help="Filter by frontmatter status"),
+    ] = None,
+    note_types: Annotated[
+        Optional[List[str]],
+        typer.Option("--type", help="Filter by frontmatter type (repeatable)"),
+    ] = None,
+    entity_types: Annotated[
+        Optional[List[str]],
+        typer.Option(
+            "--entity-type",
+            help="Filter by search item type: entity, observation, relation (repeatable)",
+        ),
+    ] = None,
+    meta: Annotated[
+        Optional[List[str]],
+        typer.Option("--meta", help="Filter by frontmatter key=value (repeatable)"),
+    ] = None,
+    filter_json: Annotated[
+        Optional[str],
+        typer.Option("--filter", help="JSON metadata filter (advanced)"),
+    ] = None,
+    page: int = typer.Option(1, "--page", help="Page number for pagination"),
+    page_size: int = typer.Option(10, "--page-size", help="Number of results per page"),
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Search across all content in the knowledge base."""
+    """Search across all content in the knowledge base.
 
-    # look for the project in the config
-    config_manager = ConfigManager()
-    project_name = None
-    if project is not None:
-        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)
-
-    # use the project name, or the default from the config
-    project_name = project_name or config_manager.default_project
-
-    if permalink and title:  # pragma: no cover
-        print("Cannot search both permalink and title")
-        raise typer.Abort()
+    Examples:
 
+    bm tool search-notes "my query"
+    bm tool search-notes --permalink "specs/*"
+    bm tool search-notes --tag python --tag async
+    bm tool search-notes --meta status=draft
+    """
     try:
-        if permalink and title:  # pragma: no cover
+        validate_routing_flags(local, cloud)
+
+        mode_flags = [permalink, title, vector, hybrid]
+        if sum(1 for enabled in mode_flags if enabled) > 1:  # pragma: no cover
             typer.echo(
-                "Use either --permalink or --title, not both. Exiting.",
+                "Use only one mode flag: --permalink, --title, --vector, or --hybrid. Exiting.",
                 err=True,
             )
             raise typer.Exit(1)
 
-        # set search type
-        search_type = ("permalink" if permalink else None,)
-        search_type = ("permalink_match" if permalink and "*" in query else None,)
-        search_type = ("title" if title else None,)
-        search_type = "text" if search_type is None else search_type
+        # --- Build metadata filters from --filter and --meta ---
+        metadata_filters: Dict[str, Any] | None = {}
+        if filter_json:
+            try:
+                metadata_filters = json.loads(filter_json)
+                if not isinstance(metadata_filters, dict):
+                    raise ValueError("Metadata filter JSON must be an object")
+            except json.JSONDecodeError as e:
+                typer.echo(f"Invalid JSON for --filter: {e}", err=True)
+                raise typer.Exit(1)
 
-        results = run_with_cleanup(
-            mcp_search.fn(
-                query,
-                project_name,
-                search_type=search_type,
-                page=page,
-                after_date=after_date,
-                page_size=page_size,
+        if meta:
+            for item in meta:
+                if "=" not in item:
+                    typer.echo(
+                        f"Invalid --meta entry '{item}'. Use key=value format.",
+                        err=True,
+                    )
+                    raise typer.Exit(1)
+                key, value = item.split("=", 1)
+                key = key.strip()
+                if not key:
+                    typer.echo(f"Invalid --meta entry '{item}'.", err=True)
+                    raise typer.Exit(1)
+                metadata_filters[key] = value
+
+        if not metadata_filters:
+            metadata_filters = None
+
+        # --- Determine search type from mode flags ---
+        search_type: str | None = None
+        if permalink:
+            search_type = "permalink"
+        if title:
+            search_type = "title"
+        if vector:
+            search_type = "vector"
+        if hybrid:
+            search_type = "hybrid"
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_search(
+                    query=query or None,
+                    project=project,
+                    workspace=workspace,
+                    search_type=search_type,
+                    output_format="json",
+                    page=page,
+                    after_date=after_date,
+                    page_size=page_size,
+                    note_types=note_types,
+                    entity_types=entity_types,
+                    metadata_filters=metadata_filters,
+                    tags=tags,
+                    status=status,
+                )
             )
-        )
-        # Use json module for more controlled serialization
-        import json
 
-        results_dict = results.model_dump(exclude_none=True)
-        print(json.dumps(results_dict, indent=2, ensure_ascii=True, default=str))
+        # MCP tool may return a string error message
+        if isinstance(result, str):
+            typer.echo(result, err=True)
+            raise typer.Exit(1)
+
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
             logger.exception("Error during search", e)
@@ -302,40 +518,241 @@ def search_notes(
         raise
 
 
-@tool_app.command(name="continue-conversation")
-def continue_conversation(
-    topic: Annotated[Optional[str], typer.Option(help="Topic or keyword to search for")] = None,
-    timeframe: Annotated[
-        Optional[str], typer.Option(help="How far back to look for activity")
-    ] = None,
+# --- list-projects ---
+
+
+@tool_app.command("list-projects")
+def list_projects(
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
 ):
-    """Prompt to continue a previous conversation or work session."""
+    """List all available projects with their status (JSON output).
+
+    Examples:
+
+    bm tool list-projects
+    bm tool list-projects --local
+    """
     try:
-        # Prompt functions return formatted strings directly
-        session = run_with_cleanup(mcp_continue_conversation.fn(topic=topic, timeframe=timeframe))  # type: ignore
-        rprint(session)
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(mcp_list_projects(output_format="json"))
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
     except Exception as e:  # pragma: no cover
         if not isinstance(e, typer.Exit):
-            logger.exception("Error continuing conversation", e)
-            typer.echo(f"Error continuing conversation: {e}", err=True)
+            typer.echo(f"Error during list_projects: {e}", err=True)
             raise typer.Exit(1)
         raise
 
 
-# @tool_app.command(name="show-recent-activity")
-# def show_recent_activity(
-#     timeframe: Annotated[
-#         str, typer.Option(help="How far back to look for activity")
-#     ] = "7d",
-# ):
-#     """Prompt to show recent activity."""
-#     try:
-#         # Prompt functions return formatted strings directly
-#         session = asyncio.run(recent_activity_prompt(timeframe=timeframe))
-#         rprint(session)
-#     except Exception as e:  # pragma: no cover
-#         if not isinstance(e, typer.Exit):
-#             logger.exception("Error continuing conversation", e)
-#             typer.echo(f"Error continuing conversation: {e}", err=True)
-#             raise typer.Exit(1)
-#         raise
+# --- list-workspaces ---
+
+
+@tool_app.command("list-workspaces")
+def list_workspaces(
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """List available cloud workspaces (JSON output).
+
+    Examples:
+
+    bm tool list-workspaces
+    bm tool list-workspaces --cloud
+    """
+    try:
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(mcp_list_workspaces(output_format="json"))
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during list_workspaces: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+# --- schema-validate ---
+
+
+@tool_app.command("schema-validate")
+def schema_validate(
+    target: Annotated[
+        Optional[str],
+        typer.Argument(help="Note path or note type to validate"),
+    ] = None,
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Validate notes against their schemas (JSON output).
+
+    TARGET can be a note path (e.g., people/ada-lovelace.md) or a note type
+    (e.g., person). If omitted, validates all notes that have schemas.
+
+    Examples:
+
+    bm tool schema-validate person
+    bm tool schema-validate people/ada-lovelace.md
+    bm tool schema-validate --project research
+    """
+    try:
+        validate_routing_flags(local, cloud)
+
+        # Heuristic: if target contains / or ., treat as identifier; otherwise as note type
+        note_type, identifier = None, None
+        if target:
+            if "/" in target or "." in target:
+                identifier = target
+            else:
+                note_type = target
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_schema_validate(
+                    note_type=note_type,
+                    identifier=identifier,
+                    project=project,
+                    workspace=workspace,
+                    output_format="json",
+                )
+            )
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during schema_validate: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+# --- schema-infer ---
+
+
+@tool_app.command("schema-infer")
+def schema_infer(
+    note_type: Annotated[
+        str,
+        typer.Argument(help="Note type to analyze (e.g., person, meeting)"),
+    ],
+    threshold: float = typer.Option(
+        0.25, "--threshold", help="Minimum frequency for optional fields (0-1)"
+    ),
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Infer schema from existing notes of a type (JSON output).
+
+    Examples:
+
+    bm tool schema-infer person
+    bm tool schema-infer meeting --threshold 0.5
+    bm tool schema-infer person --project research
+    """
+    try:
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_schema_infer(
+                    note_type=note_type,
+                    threshold=threshold,
+                    project=project,
+                    workspace=workspace,
+                    output_format="json",
+                )
+            )
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during schema_infer: {e}", err=True)
+            raise typer.Exit(1)
+        raise
+
+
+# --- schema-diff ---
+
+
+@tool_app.command("schema-diff")
+def schema_diff(
+    note_type: Annotated[
+        str,
+        typer.Argument(help="Note type to check for drift"),
+    ],
+    project: Annotated[
+        Optional[str],
+        typer.Option(help="The project to use. If not provided, the default project will be used."),
+    ] = None,
+    workspace: Annotated[
+        Optional[str],
+        typer.Option(help="Cloud workspace tenant ID or unique name to route this request."),
+    ] = None,
+    local: bool = typer.Option(
+        False, "--local", help="Force local API routing (ignore cloud mode)"
+    ),
+    cloud: bool = typer.Option(False, "--cloud", help="Force cloud API routing"),
+):
+    """Show drift between schema and actual usage (JSON output).
+
+    Examples:
+
+    bm tool schema-diff person
+    bm tool schema-diff person --project research
+    """
+    try:
+        validate_routing_flags(local, cloud)
+
+        with force_routing(local=local, cloud=cloud):
+            result = run_with_cleanup(
+                mcp_schema_diff(
+                    note_type=note_type,
+                    project=project,
+                    workspace=workspace,
+                    output_format="json",
+                )
+            )
+        _print_json(result)
+    except ValueError as e:
+        typer.echo(f"Error: {e}", err=True)
+        raise typer.Exit(1)
+    except Exception as e:  # pragma: no cover
+        if not isinstance(e, typer.Exit):
+            typer.echo(f"Error during schema_diff: {e}", err=True)
+            raise typer.Exit(1)
+        raise

src/basic_memory/cli/container.py

@@ -35,7 +35,6 @@ class CliContainer:
         """
         config = ConfigManager().config
         mode = resolve_runtime_mode(
-            cloud_mode_enabled=config.cloud_mode_enabled,
             is_test_env=config.is_test_env,
         )
         return cls(config=config, mode=mode)

src/basic_memory/cli/main.py

@@ -1,24 +1,34 @@
 """Main CLI entry point for basic-memory."""  # pragma: no cover
 
+import sys
+import warnings
+
 from basic_memory.cli.app import app  # pragma: no cover
 
-# Register commands
-from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
-    cloud,
-    db,
-    import_chatgpt,
-    import_claude_conversations,
-    import_claude_projects,
-    import_memory_json,
-    mcp,
-    project,
-    status,
-    tool,
-)
 
-# Re-apply warning filter AFTER all imports
-# (authlib adds a DeprecationWarning filter that overrides ours)
-import warnings  # pragma: no cover
+def _version_only_invocation(argv: list[str]) -> bool:
+    # Trigger: invocation is exactly `bm --version` or `bm -v`
+    # Why: avoid importing command modules on the hot version path
+    # Outcome: eager version callback exits quickly with minimal startup work
+    return len(argv) == 1 and argv[0] in {"--version", "-v"}
+
+
+if not _version_only_invocation(sys.argv[1:]):
+    # Register commands only when not short-circuiting for --version
+    from basic_memory.cli.commands import (  # noqa: F401  # pragma: no cover
+        cloud,
+        db,
+        doctor,
+        import_chatgpt,
+        import_claude_conversations,
+        import_claude_projects,
+        import_memory_json,
+        mcp,
+        project,
+        schema,
+        status,
+        tool,
+    )
 
 warnings.filterwarnings("ignore")  # pragma: no cover
 

src/basic_memory/cli/promo.py

@@ -0,0 +1,130 @@
+"""Cloud promo messaging for CLI entrypoint."""
+
+import os
+import sys
+
+from rich.console import Console
+from rich.panel import Panel
+
+import basic_memory
+from basic_memory.cli.analytics import track, EVENT_PROMO_SHOWN
+from basic_memory.config import ConfigManager
+
+OSS_DISCOUNT_CODE = "BMFOSS"
+CLOUD_LEARN_MORE_URL = (
+    "https://basicmemory.com?utm_source=bm-foss&utm_medium=promo&utm_campaign=cloud-upsell"
+)
+
+
+def _promos_disabled_by_env() -> bool:
+    """Check environment-level kill switch for promo output."""
+    value = os.getenv("BASIC_MEMORY_NO_PROMOS", "").strip().lower()
+    return value in {"1", "true", "yes"}
+
+
+def _is_interactive_session() -> bool:
+    """Return whether stdin/stdout are interactive terminals."""
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except ValueError:
+        # Trigger: stdin/stdout already closed (e.g., MCP stdio transport shutdown)
+        # Why: isatty() raises ValueError on closed file descriptors
+        # Outcome: treat as non-interactive, suppressing promo output
+        return False
+
+
+def _build_cloud_promo_message() -> str:
+    """Build benefit-led cloud upsell copy with Rich markup."""
+    return (
+        "☁️ [bold]Your knowledge, everywhere.[/bold] ✨\n"
+        "Stop losing context when you switch machines.\n"
+        "Basic Memory Cloud syncs your memory across every device, including mobile and web.\n"
+        "Try it free for 7 days.\n"
+        f"Use [bold cyan]{OSS_DISCOUNT_CODE}[/bold cyan] for 20% off when you subscribe.\n"
+        "[bold green]→ bm cloud login[/bold green]"
+    )
+
+
+def maybe_show_init_line(
+    invoked_subcommand: str | None,
+    *,
+    config_manager: ConfigManager | None = None,
+    is_interactive: bool | None = None,
+    console: Console | None = None,
+) -> None:
+    """Show a one-time init confirmation line before command output."""
+    manager = config_manager or ConfigManager()
+    config = manager.load_config()
+
+    interactive = _is_interactive_session() if is_interactive is None else is_interactive
+
+    # Same gates as the cloud promo — suppress in non-interactive, env kill-switch,
+    # mcp/root-help contexts, or when already shown.
+    if _promos_disabled_by_env() or not interactive:
+        return
+
+    if invoked_subcommand in {None, "mcp"}:
+        return
+
+    if config.cloud_promo_first_run_shown:
+        return
+
+    out = console or Console()
+    out.print("Basic Memory initialized ✓")
+
+
+def maybe_show_cloud_promo(
+    invoked_subcommand: str | None,
+    *,
+    config_manager: ConfigManager | None = None,
+    is_interactive: bool | None = None,
+    console: Console | None = None,
+) -> None:
+    """Show cloud promo copy when discovery gates are satisfied."""
+    manager = config_manager or ConfigManager()
+    config = manager.load_config()
+    from basic_memory.cli.auth import CLIAuth
+
+    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+    has_cloud_access = bool(config.cloud_api_key) or auth.load_tokens() is not None
+
+    interactive = _is_interactive_session() if is_interactive is None else is_interactive
+
+    # Trigger: environment-level promo suppression or non-interactive execution.
+    # Why: avoid polluting scripts/CI output and support a hard opt-out.
+    # Outcome: skip all promo copy for this invocation.
+    if _promos_disabled_by_env() or not interactive:
+        return
+
+    # Trigger: command context where cloud promo is not actionable.
+    # Why: mcp/stdin protocol and root help flows should stay noise-free.
+    # Outcome: command continues without promo messaging.
+    if invoked_subcommand in {None, "mcp"}:
+        return
+
+    if has_cloud_access or config.cloud_promo_opt_out:
+        return
+
+    show_first_run = not config.cloud_promo_first_run_shown
+    show_version_notice = config.cloud_promo_last_version_shown != basic_memory.__version__
+    if not show_first_run and not show_version_notice:
+        return
+
+    out = console or Console()
+    out.print(
+        Panel(
+            _build_cloud_promo_message(),
+            title="Basic Memory Cloud",
+            border_style="cyan",
+            expand=False,
+        )
+    )
+    out.print(f"Learn more at [link={CLOUD_LEARN_MORE_URL}]{CLOUD_LEARN_MORE_URL}[/link]")
+    out.print("[dim]Disable with: bm cloud promo --off[/dim]")
+
+    trigger = "first_run" if show_first_run else "version_bump"
+    track(EVENT_PROMO_SHOWN, {"trigger": trigger})
+
+    config.cloud_promo_first_run_shown = True
+    config.cloud_promo_last_version_shown = basic_memory.__version__
+    manager.save_config(config)

src/basic_memory/config.py

@@ -1,7 +1,9 @@
 """Configuration management for basic-memory."""
 
+import importlib.util
 import json
 import os
+import shutil
 from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
@@ -9,7 +11,7 @@ from typing import Any, Dict, Literal, Optional, List, Tuple
 from enum import Enum
 
 from loguru import logger
-from pydantic import BaseModel, Field, model_validator
+from pydantic import AliasChoices, BaseModel, Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from basic_memory.utils import setup_logging, generate_permalink
@@ -24,6 +26,13 @@ WATCH_STATUS_JSON = "watch-status.json"
 Environment = Literal["test", "dev", "user"]
 
 
+class ProjectMode(str, Enum):
+    """Per-project routing mode."""
+
+    LOCAL = "local"
+    CLOUD = "cloud"
+
+
 class DatabaseBackend(str, Enum):
     """Supported database backends."""
 
@@ -31,12 +40,21 @@ class DatabaseBackend(str, Enum):
     POSTGRES = "postgres"
 
 
+def _default_semantic_search_enabled() -> bool:
+    """Enable semantic search by default when required local semantic dependencies exist."""
+    required_modules = ("fastembed", "sqlite_vec")
+    return all(
+        importlib.util.find_spec(module_name) is not None for module_name in required_modules
+    )
+
+
 @dataclass
 class ProjectConfig:
     """Configuration for a specific basic-memory project."""
 
     name: str
     home: Path
+    mode: ProjectMode = ProjectMode.LOCAL
 
     @property
     def project(self):
@@ -52,6 +70,9 @@ class CloudProjectConfig(BaseModel):
 
     This tracks the local working directory and sync state for a project
     that is synced with Basic Memory Cloud.
+
+    DEPRECATED: Kept for backward-compatible migration only. New code should
+    use ProjectEntry fields (cloud_sync_path, bisync_initialized, last_sync).
     """
 
     local_path: str = Field(description="Local working directory path for this cloud project")
@@ -63,26 +84,57 @@ class CloudProjectConfig(BaseModel):
     )
 
 
+class ProjectEntry(BaseModel):
+    """Unified project configuration entry.
+
+    Replaces the old triple of projects (Dict[str, str]), project_modes
+    (Dict[str, ProjectMode]), and cloud_projects (Dict[str, CloudProjectConfig])
+    with a single structure per project.
+    """
+
+    path: str = Field(description="Local filesystem path for the project")
+    mode: ProjectMode = Field(
+        default=ProjectMode.LOCAL,
+        description="Routing mode: local (in-process ASGI) or cloud (remote API)",
+    )
+    workspace_id: Optional[str] = Field(
+        default=None,
+        description="Cloud workspace tenant_id. Set by 'bm project set-cloud --workspace'.",
+    )
+    # Cloud sync state (replaces CloudProjectConfig)
+    local_sync_path: Optional[str] = Field(
+        default=None,
+        description="Local working directory for bisync",
+        validation_alias=AliasChoices("local_sync_path", "cloud_sync_path"),
+    )
+    bisync_initialized: bool = Field(
+        default=False,
+        description="Whether rclone bisync baseline has been established",
+    )
+    last_sync: Optional[datetime] = Field(
+        default=None,
+        description="Timestamp of last successful sync operation",
+    )
+
+
 class BasicMemoryConfig(BaseSettings):
     """Pydantic model for Basic Memory global configuration."""
 
     env: Environment = Field(default="dev", description="Environment name")
 
-    projects: Dict[str, str] = Field(
+    projects: Dict[str, ProjectEntry] = Field(
         default_factory=lambda: {
-            "main": str(Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")))
+            "main": ProjectEntry(
+                path=str(Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")))
+            )
         }
         if os.getenv("BASIC_MEMORY_HOME")
         else {},
-        description="Mapping of project names to their filesystem paths",
+        description="Mapping of project names to their ProjectEntry configuration",
     )
-    default_project: str = Field(
-        default="main",
-        description="Name of the default project to use",
-    )
-    default_project_mode: bool = Field(
-        default=False,
-        description="When True, MCP tools automatically use default_project when no project parameter is specified. Enables simplified UX for single-project workflows.",
+    default_project: Optional[str] = Field(
+        default=None,
+        description="Name of the default project to use. When set, acts as fallback when no project parameter is specified. Set to null to disable automatic project resolution.",
     )
 
     # overridden by ~/.basic-memory/config.json
@@ -99,6 +151,59 @@ class BasicMemoryConfig(BaseSettings):
         description="Database connection URL. For Postgres, use postgresql+asyncpg://user:pass@host:port/db. If not set, SQLite will use default path.",
     )
 
+    # Semantic search configuration
+    semantic_search_enabled: bool = Field(
+        default_factory=_default_semantic_search_enabled,
+        description="Enable semantic search (vector/hybrid retrieval). Works on both SQLite and Postgres backends. Requires semantic dependencies (included by default).",
+    )
+    semantic_embedding_provider: str = Field(
+        default="fastembed",
+        description="Embedding provider for local semantic indexing/search.",
+    )
+    semantic_embedding_model: str = Field(
+        default="bge-small-en-v1.5",
+        description="Embedding model identifier used by the local provider.",
+    )
+    semantic_embedding_dimensions: int | None = Field(
+        default=None,
+        description="Embedding vector dimensions. Auto-detected from provider if not set (384 for FastEmbed, 1536 for OpenAI).",
+    )
+    semantic_embedding_batch_size: int = Field(
+        default=64,
+        description="Batch size for embedding generation.",
+        gt=0,
+    )
+    semantic_embedding_sync_batch_size: int = Field(
+        default=64,
+        description="Batch size for vector sync orchestration flushes.",
+        gt=0,
+    )
+    semantic_embedding_cache_dir: str | None = Field(
+        default=None,
+        description="Optional cache directory for FastEmbed model artifacts.",
+    )
+    semantic_embedding_threads: int | None = Field(
+        default=None,
+        description="Optional FastEmbed runtime thread count override.",
+        gt=0,
+    )
+    semantic_embedding_parallel: int | None = Field(
+        default=None,
+        description="Optional FastEmbed embed() parallelism override.",
+        gt=0,
+    )
+    semantic_vector_k: int = Field(
+        default=100,
+        description="Vector candidate count for vector and hybrid retrieval.",
+        gt=0,
+    )
+    semantic_min_similarity: float = Field(
+        default=0.55,
+        description="Minimum similarity score for vector search results. Results below this threshold are filtered out. 0.0 disables filtering.",
+        ge=0.0,
+        le=1.0,
+    )
+
     # Database connection pool configuration (Postgres only)
     db_pool_size: int = Field(
         default=20,
@@ -160,6 +265,26 @@ class BasicMemoryConfig(BaseSettings):
         description="Disable automatic permalink generation in frontmatter. When enabled, new notes won't have permalinks added and sync won't update permalinks. Existing permalinks will still work for reading.",
     )
 
+    write_note_overwrite_default: bool = Field(
+        default=False,
+        description=(
+            "Default value for write_note's overwrite parameter. "
+            "When False (default), write_note errors if note already exists. "
+            "Set to True to restore pre-v0.20 upsert behavior. "
+            "Env: BASIC_MEMORY_WRITE_NOTE_OVERWRITE_DEFAULT"
+        ),
+    )
+
+    ensure_frontmatter_on_sync: bool = Field(
+        default=True,
+        description="Ensure markdown files have frontmatter during sync by adding derived title/type/permalink when missing. When combined with disable_permalinks=True, this setting takes precedence for missing-frontmatter files and still writes permalinks.",
+    )
+
+    permalinks_include_project: bool = Field(
+        default=True,
+        description="When True, generated permalinks are prefixed with the project slug (e.g., 'specs/search'). Existing permalinks remain unchanged unless explicitly updated.",
+    )
+
     skip_initialization_sync: bool = Field(
         default=False,
         description="Skip expensive initialization synchronization. Useful for cloud/stateless deployments where project reconciliation is not needed.",
@@ -211,16 +336,117 @@ class BasicMemoryConfig(BaseSettings):
         description="Basic Memory Cloud host URL",
     )
 
-    cloud_mode: bool = Field(
+    cloud_promo_opt_out: bool = Field(
         default=False,
-        description="Enable cloud mode - all requests go to cloud instead of local (config file value)",
+        description="Disable CLI cloud promo messages when true.",
     )
 
-    cloud_projects: Dict[str, CloudProjectConfig] = Field(
-        default_factory=dict,
-        description="Cloud project sync configuration mapping project names to their local paths and sync state",
+    cloud_promo_first_run_shown: bool = Field(
+        default=False,
+        description="Tracks whether the first-run cloud promo message has been shown.",
     )
 
+    cloud_promo_last_version_shown: Optional[str] = Field(
+        default=None,
+        description="Most recent cloud promo version shown in CLI.",
+    )
+
+    cloud_api_key: Optional[str] = Field(
+        default=None,
+        description="API key for cloud access (bmc_ prefixed). Account-level, not per-project.",
+    )
+
+    default_workspace: Optional[str] = Field(
+        default=None,
+        description="Default cloud workspace tenant_id. Set by 'bm cloud workspace set-default'.",
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_legacy_projects(cls, data: Any) -> Any:
+        """Migrate old-format config (Dict[str, str]) to new ProjectEntry format.
+
+        Old format stored projects as three separate dicts:
+          projects:      {"name": "/path"}
+          project_modes: {"name": "cloud"}
+          cloud_projects: {"name": {"local_path": "...", ...}}
+
+        New format unifies them into:
+          projects: {"name": {"path": "/path", "mode": "cloud", ...}}
+
+        Also removes stale keys (default_project_mode, permalinks_include_project)
+        that are no longer part of the config model.
+        """
+        if not isinstance(data, dict):
+            return data
+
+        # --- Remove stale keys from old config versions ---
+        data.pop("default_project_mode", None)
+        data.pop("cloud_mode", None)
+
+        projects = data.get("projects", {})
+        if not projects:
+            return data
+
+        # Check if already in new format — peek at first value
+        first_value = next(iter(projects.values()), None)
+        if isinstance(first_value, str):
+            # Old format: {"name": "/path"} → convert
+            project_modes = data.pop("project_modes", {})
+            cloud_projects = data.pop("cloud_projects", {})
+            new_projects: Dict[str, Any] = {}
+            for name, path in projects.items():
+                entry: Dict[str, Any] = {"path": path}
+                if name in project_modes:
+                    entry["mode"] = project_modes[name]
+                if name in cloud_projects:
+                    cp = cloud_projects[name]
+                    if isinstance(cp, dict):
+                        entry["local_sync_path"] = cp.get("local_path")
+                        entry["bisync_initialized"] = cp.get("bisync_initialized", False)
+                        entry["last_sync"] = cp.get("last_sync")
+                    else:
+                        # Already a CloudProjectConfig-like object
+                        entry["local_sync_path"] = getattr(cp, "local_path", None)
+                        entry["bisync_initialized"] = getattr(cp, "bisync_initialized", False)
+                        entry["last_sync"] = getattr(cp, "last_sync", None)
+                new_projects[name] = entry
+
+            # Pick up cloud_projects entries not already in projects
+            # These are cloud-only projects — path should be the local working
+            # directory (if one exists), local_path goes into local_sync_path for bisync
+            for name, cp in cloud_projects.items():
+                if name not in new_projects:
+                    if isinstance(cp, dict):
+                        local_path = cp.get("local_path", "")
+                        new_projects[name] = {
+                            "path": local_path or "",
+                            "mode": project_modes.get(name, "cloud"),
+                            "local_sync_path": local_path,
+                            "bisync_initialized": cp.get("bisync_initialized", False),
+                            "last_sync": cp.get("last_sync"),
+                        }
+
+            data["projects"] = new_projects
+        else:
+            # New format or dict-based — just clean up stale keys
+            data.pop("project_modes", None)
+            data.pop("cloud_projects", None)
+
+        # --- Promote local_sync_path into path for cloud projects with slug paths ---
+        # Trigger: project entry has local_sync_path set but path is a cloud slug (not absolute)
+        # Why: path must always be the local filesystem path; the cloud remote is derivable
+        # Outcome: path becomes the local directory, local_sync_path kept for backwards compat
+        projects = data.get("projects", {})
+        for name, entry in projects.items():
+            if isinstance(entry, dict):
+                lsp = entry.get("local_sync_path")
+                path = entry.get("path", "")
+                if lsp and not os.path.isabs(path):
+                    entry["path"] = lsp
+
+        return data
+
     @property
     def is_test_env(self) -> bool:
         """Check if running in a test environment.
@@ -238,27 +464,33 @@ class BasicMemoryConfig(BaseSettings):
             or os.getenv("PYTEST_CURRENT_TEST") is not None
         )
 
-    @property
-    def cloud_mode_enabled(self) -> bool:
-        """Check if cloud mode is enabled.
+    def get_project_mode(self, project_name: str) -> ProjectMode:
+        """Get the routing mode for a project.
 
-        Priority:
-        1. BASIC_MEMORY_CLOUD_MODE environment variable
-        2. Config file value (cloud_mode)
+        Returns the per-project mode if set.
+        Unknown projects (not in local config) default to CLOUD —
+        local projects are always registered in config.
         """
-        env_value = os.environ.get("BASIC_MEMORY_CLOUD_MODE", "").lower()
-        if env_value in ("true", "1", "yes"):
-            return True
-        elif env_value in ("false", "0", "no"):
-            return False
-        # Fall back to config file value
-        return self.cloud_mode
+        entry = self.projects.get(project_name)
+        return entry.mode if entry else ProjectMode.CLOUD
+
+    def set_project_mode(self, project_name: str, mode: ProjectMode) -> None:
+        """Set the routing mode for a project.
+
+        Creates a minimal ProjectEntry if the project doesn't already exist,
+        preserving backward compatibility with code that sets mode before
+        adding a full project entry.
+        """
+        if project_name in self.projects:
+            self.projects[project_name].mode = mode
+        else:
+            self.projects[project_name] = ProjectEntry(path="", mode=mode)
 
     @classmethod
     def for_cloud_tenant(
         cls,
         database_url: str,
-        projects: Optional[Dict[str, str]] = None,
+        projects: Optional[Dict[str, "ProjectEntry"]] = None,
     ) -> "BasicMemoryConfig":
         """Create config for cloud tenant - no config.json, database is source of truth.
 
@@ -280,7 +512,6 @@ class BasicMemoryConfig(BaseSettings):
             database_backend=DatabaseBackend.POSTGRES,
             database_url=database_url,
             projects=projects or {},
-            cloud_mode=True,
             skip_initialization_sync=True,
         )
 
@@ -296,7 +527,7 @@ class BasicMemoryConfig(BaseSettings):
         if name not in self.projects:
             raise ValueError(f"Project '{name}' not found in configuration")
 
-        return Path(self.projects[name])
+        return Path(self.projects[name].path)
 
     def model_post_init(self, __context: Any) -> None:
         """Ensure configuration is valid after initialization."""
@@ -304,15 +535,25 @@ class BasicMemoryConfig(BaseSettings):
         if self.database_backend == DatabaseBackend.POSTGRES:  # pragma: no cover
             return  # pragma: no cover
 
-        # Ensure at least one project exists; if none exist then create main
-        if not self.projects:  # pragma: no cover
-            self.projects["main"] = str(
-                Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory"))
+        # Trigger: no projects configured (fresh install or empty config)
+        # Why: every config needs at least one project to be functional
+        # Outcome: creates "main" project using BASIC_MEMORY_HOME or ~/basic-memory
+        if not self.projects:
+            self.projects["main"] = ProjectEntry(
+                path=str(Path(os.getenv("BASIC_MEMORY_HOME", Path.home() / "basic-memory")))
             )
 
-        # Ensure default project is valid (i.e. points to an existing project)
-        if self.default_project not in self.projects:  # pragma: no cover
-            # Set default to first available project
+        # Trigger: default_project was not explicitly provided in the input data
+        #          (config file omitted the key, or BasicMemoryConfig() called with no args)
+        # Why: callers like get_project_config() expect a valid project name;
+        #      but explicit None (discovery mode) must be preserved
+        # Outcome: sets default_project to the first available project
+        if "default_project" not in self.model_fields_set:
+            self.default_project = next(iter(self.projects.keys()))
+        # Trigger: default_project was explicitly set but references a non-existent project
+        # Why: project may have been removed or renamed since config was saved
+        # Outcome: corrects to the first available project
+        elif self.default_project is not None and self.default_project not in self.projects:
             self.default_project = next(iter(self.projects.keys()))
 
     @property
@@ -321,8 +562,11 @@ class BasicMemoryConfig(BaseSettings):
 
         This is the single database that will store all knowledge data
         across all projects.
+
+        Uses BASIC_MEMORY_CONFIG_DIR when set so each process/worktree can
+        isolate both config and database state.
         """
-        database_path = Path.home() / DATA_DIR_NAME / APP_DATABASE_NAME
+        database_path = self.data_dir_path / APP_DATABASE_NAME
         if not database_path.exists():  # pragma: no cover
             database_path.parent.mkdir(parents=True, exist_ok=True)
             database_path.touch()
@@ -344,7 +588,10 @@ class BasicMemoryConfig(BaseSettings):
     @property
     def project_list(self) -> List[ProjectConfig]:  # pragma: no cover
         """Get all configured projects as ProjectConfig objects."""
-        return [ProjectConfig(name=name, home=Path(path)) for name, path in self.projects.items()]
+        return [
+            ProjectConfig(name=name, home=Path(entry.path), mode=entry.mode)
+            for name, entry in self.projects.items()
+        ]
 
     @model_validator(mode="after")
     def ensure_project_paths_exists(self) -> "BasicMemoryConfig":  # pragma: no cover
@@ -357,8 +604,11 @@ class BasicMemoryConfig(BaseSettings):
         if self.database_backend == DatabaseBackend.POSTGRES:
             return self
 
-        for name, path_value in self.projects.items():
-            path = Path(path_value)
+        for name, entry in self.projects.items():
+            path = Path(entry.path)
+            # Skip cloud-only projects whose path is a slug, not a local directory
+            if not path.is_absolute():
+                continue
             if not path.exists():
                 try:
                     path.mkdir(parents=True)
@@ -368,8 +618,13 @@ class BasicMemoryConfig(BaseSettings):
         return self
 
     @property
-    def data_dir_path(self):
-        return Path.home() / DATA_DIR_NAME
+    def data_dir_path(self) -> Path:
+        """Get app state directory for config and default SQLite database."""
+        if config_dir := os.getenv("BASIC_MEMORY_CONFIG_DIR"):
+            return Path(config_dir)
+
+        home = os.getenv("HOME", Path.home())
+        return Path(home) / DATA_DIR_NAME
 
 
 # Module-level cache for configuration
@@ -419,6 +674,33 @@ class ConfigManager:
             try:
                 file_data = json.loads(self.config_file.read_text(encoding="utf-8"))
 
+                # Detect legacy format before model validators strip stale keys
+                _STALE_KEYS = {
+                    "default_project_mode",
+                    "project_modes",
+                    "cloud_projects",
+                    "cloud_mode",
+                }
+                needs_resave = bool(_STALE_KEYS & file_data.keys())
+
+                # Check if projects dict uses old string-value format
+                projects_raw = file_data.get("projects", {})
+                if projects_raw:
+                    first_val = next(iter(projects_raw.values()), None)
+                    if isinstance(first_val, str):
+                        needs_resave = True
+
+                # Check if any project has local_sync_path set but path is a cloud slug
+                # (will be migrated by migrate_legacy_projects validator)
+                if not needs_resave:
+                    for entry_data in projects_raw.values():
+                        if isinstance(entry_data, dict):
+                            lsp = entry_data.get("local_sync_path")
+                            p = entry_data.get("path", "")
+                            if lsp and not os.path.isabs(p):
+                                needs_resave = True
+                                break
+
                 # 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
@@ -440,10 +722,30 @@ class ConfigManager:
                         merged_data[field_name] = env_dict[field_name]
 
                 _CONFIG_CACHE = BasicMemoryConfig(**merged_data)
+
+                # Re-save to normalize legacy config into current format
+                if needs_resave:
+                    # Create backup before overwriting so users can revert if needed
+                    backup_path = self.config_file.with_suffix(".json.bak")
+                    shutil.copy2(self.config_file, backup_path)
+                    logger.info(f"Migrating config to current format (backup: {backup_path})")
+                    save_basic_memory_config(self.config_file, _CONFIG_CACHE)
+
                 return _CONFIG_CACHE
+            except json.JSONDecodeError as e:  # pragma: no cover
+                logger.error(f"Invalid JSON in config file {self.config_file}: {e}")
+                raise SystemExit(
+                    f"Error: config file is not valid JSON: {self.config_file}\n"
+                    f"  {e}\n"
+                    f"Fix or delete the file and re-run."
+                )
             except Exception as e:  # pragma: no cover
-                logger.exception(f"Failed to load config: {e}")
-                raise e
+                logger.error(f"Failed to load config from {self.config_file}: {e}")
+                raise SystemExit(
+                    f"Error: failed to load config from {self.config_file}\n"
+                    f"  {e}\n"
+                    f"Fix or delete the file and re-run."
+                )
         else:
             config = BasicMemoryConfig()
             self.save_config(config)
@@ -458,11 +760,15 @@ class ConfigManager:
 
     @property
     def projects(self) -> Dict[str, str]:
-        """Get all configured projects."""
-        return self.config.projects.copy()
+        """Get all configured projects as name -> path mapping.
+
+        Returns the legacy Dict[str, str] format for backward compatibility
+        with code that expects project name -> filesystem path.
+        """
+        return {name: entry.path for name, entry in self.config.projects.items()}
 
     @property
-    def default_project(self) -> str:
+    def default_project(self) -> Optional[str]:
         """Get the default project name."""
         return self.config.default_project
 
@@ -472,13 +778,10 @@ class ConfigManager:
         if project_name:  # pragma: no cover
             raise ValueError(f"Project '{name}' already exists")
 
-        # Ensure the path exists
-        project_path = Path(path)
-        project_path.mkdir(parents=True, exist_ok=True)  # pragma: no cover
-
         # Load config, modify it, and save it
+        project_path = Path(path)
         config = self.load_config()
-        config.projects[name] = str(project_path)
+        config.projects[name] = ProjectEntry(path=str(project_path))
         self.save_config(config)
         return ProjectConfig(name=name, home=project_path)
 
@@ -510,12 +813,15 @@ class ConfigManager:
         self.save_config(config)
 
     def get_project(self, name: str) -> Tuple[str, str] | Tuple[None, None]:
-        """Look up a project from the configuration by name or permalink"""
+        """Look up a project from the configuration by name or permalink.
+
+        Returns (project_name, path_string) for backward compatibility.
+        """
         project_permalink = generate_permalink(name)
         app_config = self.config
-        for project_name, path in app_config.projects.items():
+        for project_name, entry in app_config.projects.items():
             if project_permalink == generate_permalink(project_name):
-                return project_name, path
+                return project_name, entry.path
         return None, None
 
 
@@ -550,14 +856,28 @@ def get_project_config(project_name: Optional[str] = None) -> ProjectConfig:
 
     project_permalink = generate_permalink(actual_project_name)
 
-    for name, path in app_config.projects.items():
+    for name, entry in app_config.projects.items():
         if project_permalink == generate_permalink(name):
-            return ProjectConfig(name=name, home=Path(path))
+            return ProjectConfig(name=name, home=Path(entry.path))
 
     # otherwise raise error
     raise ValueError(f"Project '{actual_project_name}' not found")  # pragma: no cover
 
 
+def has_cloud_credentials(config: BasicMemoryConfig) -> bool:
+    """Check if cloud credentials are available (API key or OAuth token).
+
+    Shared utility used by both MCP tools and CLI commands to determine
+    whether cloud project discovery is possible.
+    """
+    if config.cloud_api_key:
+        return True
+    from basic_memory.cli.auth import CLIAuth
+
+    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+    return auth.load_tokens() is not None
+
+
 def save_basic_memory_config(file_path: Path, config: BasicMemoryConfig) -> None:
     """Save configuration to file."""
     try:

src/basic_memory/db.py

@@ -44,6 +44,101 @@ _engine: Optional[AsyncEngine] = None
 _session_maker: Optional[async_sessionmaker[AsyncSession]] = None
 
 
+async def _needs_semantic_embedding_backfill(
+    app_config: BasicMemoryConfig,
+    session_maker: async_sessionmaker[AsyncSession],
+) -> bool:
+    """Check if entities exist but vector embeddings are empty.
+
+    This is the reliable way to detect that embeddings need to be generated,
+    regardless of how migrations were applied (fresh DB, upgrade, reset, etc.).
+    """
+    if not app_config.semantic_search_enabled:
+        return False
+
+    try:
+        async with scoped_session(session_maker) as session:
+            entity_count = (
+                await session.execute(text("SELECT COUNT(*) FROM entity"))
+            ).scalar() or 0
+            if entity_count == 0:
+                return False
+
+            # Check if vector chunks table exists and is empty
+            embedding_count = (
+                await session.execute(text("SELECT COUNT(*) FROM search_vector_chunks"))
+            ).scalar() or 0
+
+            return embedding_count == 0
+    except Exception as exc:
+        # Table might not exist yet (pre-migration)
+        logger.debug(f"Could not check embedding status: {exc}")
+        return False
+
+
+async def _run_semantic_embedding_backfill(
+    app_config: BasicMemoryConfig,
+    session_maker: async_sessionmaker[AsyncSession],
+) -> None:
+    """Backfill semantic embeddings for all active projects/entities."""
+    if not app_config.semantic_search_enabled:
+        logger.info("Skipping automatic semantic embedding backfill: semantic search is disabled.")
+        return
+
+    async with scoped_session(session_maker) as session:
+        project_result = await session.execute(
+            text("SELECT id, name FROM project WHERE is_active = :is_active ORDER BY id"),
+            {"is_active": True},
+        )
+        projects = [(int(row[0]), str(row[1])) for row in project_result.fetchall()]
+
+    if not projects:
+        logger.info("Skipping automatic semantic embedding backfill: no active projects found.")
+        return
+
+    repository_class = (
+        PostgresSearchRepository
+        if app_config.database_backend == DatabaseBackend.POSTGRES
+        else SQLiteSearchRepository
+    )
+
+    total_entities = 0
+    for project_id, project_name in projects:
+        async with scoped_session(session_maker) as session:
+            entity_result = await session.execute(
+                text("SELECT id FROM entity WHERE project_id = :project_id ORDER BY id"),
+                {"project_id": project_id},
+            )
+            entity_ids = [int(row[0]) for row in entity_result.fetchall()]
+
+        if not entity_ids:
+            continue
+
+        total_entities += len(entity_ids)
+        logger.info(
+            "Automatic semantic embedding backfill: "
+            f"project={project_name}, entities={len(entity_ids)}"
+        )
+
+        search_repository = repository_class(
+            session_maker,
+            project_id=project_id,
+            app_config=app_config,
+        )
+        batch_result = await search_repository.sync_entity_vectors_batch(entity_ids)
+        if batch_result.entities_failed > 0:
+            logger.warning(
+                "Automatic semantic embedding backfill encountered entity failures: "
+                f"project={project_name}, failed={batch_result.entities_failed}, "
+                f"failed_entity_ids={batch_result.failed_entity_ids}"
+            )
+
+    logger.info(
+        "Automatic semantic embedding backfill complete: "
+        f"projects={len(projects)}, entities={total_entities}"
+    )
+
+
 class DatabaseType(Enum):
     """Types of supported databases."""
 
@@ -344,24 +439,33 @@ async def engine_session_factory(
 
     global _engine, _session_maker
 
-    # Use the same helper function as production code
-    _engine, _session_maker = _create_engine_and_session(db_path, db_type, config)
+    # Use the same helper function as production code.
+    #
+    # Keep local references so teardown can deterministically dispose the
+    # specific engine created by this context manager, even if other code calls
+    # shutdown_db() and mutates module-level globals mid-test.
+    created_engine, created_session_maker = _create_engine_and_session(db_path, db_type, config)
+    _engine, _session_maker = created_engine, created_session_maker
 
     try:
         # Verify that engine and session maker are initialized
-        if _engine is None:  # pragma: no cover
+        if created_engine is None:  # pragma: no cover
             logger.error("Database engine is None in engine_session_factory")
             raise RuntimeError("Database engine initialization failed")
 
-        if _session_maker is None:  # pragma: no cover
+        if created_session_maker is None:  # pragma: no cover
             logger.error("Session maker is None in engine_session_factory")
             raise RuntimeError("Session maker initialization failed")
 
-        yield _engine, _session_maker
+        yield created_engine, created_session_maker
     finally:
-        if _engine:
-            await _engine.dispose()
+        await created_engine.dispose()
+
+        # Only clear module-level globals if they still point to this context's
+        # engine/session. This avoids clobbering newer globals from other callers.
+        if _engine is created_engine:
             _engine = None
+        if _session_maker is created_session_maker:
             _session_maker = None
 
 
@@ -374,6 +478,7 @@ async def run_migrations(
     so it's safe to call this multiple times - it will only run pending migrations.
     """
     logger.info("Running database migrations...")
+    temp_engine: AsyncEngine | None = None
     try:
         # Get the absolute path to the alembic directory relative to this file
         alembic_dir = Path(__file__).parent / "alembic"
@@ -398,7 +503,9 @@ async def run_migrations(
 
         # Get session maker - ensure we don't trigger recursive migration calls
         if _session_maker is None:
-            _, session_maker = _create_engine_and_session(app_config.database_path, database_type)
+            temp_engine, session_maker = _create_engine_and_session(
+                app_config.database_path, database_type, app_config
+            )
         else:
             session_maker = _session_maker
 
@@ -413,6 +520,23 @@ async def run_migrations(
             await PostgresSearchRepository(session_maker, 1).init_search_index()
         else:
             await SQLiteSearchRepository(session_maker, 1).init_search_index()
+
+        # Check if backfill is needed — actual backfill runs in background
+        # from the MCP server lifespan to avoid blocking startup.
+        if await _needs_semantic_embedding_backfill(app_config, session_maker):
+            logger.info(
+                "Semantic embeddings missing — backfill will run in background after startup"
+            )
+        else:
+            logger.info("Semantic embeddings: up to date")
     except Exception as e:  # pragma: no cover
         logger.error(f"Error running migrations: {e}")
         raise
+    finally:
+        # Trigger: run_migrations() created a temporary engine while module-level
+        # session maker was not initialized.
+        # Why: temporary aiosqlite worker threads can outlive CLI command execution
+        # and block process shutdown if the engine is not disposed.
+        # Outcome: always dispose temporary engines after migration work completes.
+        if temp_engine is not None:
+            await temp_engine.dispose()

src/basic_memory/deps/__init__.py

@@ -91,6 +91,8 @@ from basic_memory.deps.services import (
     FileServiceV2Dep,
     get_file_service_v2_external,
     FileServiceV2ExternalDep,
+    get_task_scheduler,
+    TaskSchedulerDep,
     get_search_service,
     SearchServiceDep,
     get_search_service_v2,
@@ -227,6 +229,8 @@ __all__ = [
     "FileServiceV2Dep",
     "get_file_service_v2_external",
     "FileServiceV2ExternalDep",
+    "get_task_scheduler",
+    "TaskSchedulerDep",
     "get_search_service",
     "SearchServiceDep",
     "get_search_service_v2",

src/basic_memory/deps/importers.py

@@ -41,7 +41,12 @@ async def get_chatgpt_importer(
     file_service: FileServiceDep,
 ) -> ChatGPTImporter:
     """Create ChatGPTImporter with dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+    return ChatGPTImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ChatGPTImporterDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer)]
@@ -53,7 +58,12 @@ async def get_chatgpt_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> ChatGPTImporter:
     """Create ChatGPTImporter with v2 dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+    return ChatGPTImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ChatGPTImporterV2Dep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer_v2)]
@@ -65,7 +75,12 @@ async def get_chatgpt_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> ChatGPTImporter:
     """Create ChatGPTImporter with v2 external_id dependencies."""
-    return ChatGPTImporter(project_config.home, markdown_processor, file_service)
+    return ChatGPTImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ChatGPTImporterV2ExternalDep = Annotated[ChatGPTImporter, Depends(get_chatgpt_importer_v2_external)]
@@ -80,7 +95,12 @@ async def get_claude_conversations_importer(
     file_service: FileServiceDep,
 ) -> ClaudeConversationsImporter:
     """Create ClaudeConversationsImporter with dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeConversationsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeConversationsImporterDep = Annotated[
@@ -94,7 +114,12 @@ async def get_claude_conversations_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> ClaudeConversationsImporter:
     """Create ClaudeConversationsImporter with v2 dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeConversationsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeConversationsImporterV2Dep = Annotated[
@@ -108,7 +133,12 @@ async def get_claude_conversations_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> ClaudeConversationsImporter:
     """Create ClaudeConversationsImporter with v2 external_id dependencies."""
-    return ClaudeConversationsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeConversationsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeConversationsImporterV2ExternalDep = Annotated[
@@ -125,7 +155,12 @@ async def get_claude_projects_importer(
     file_service: FileServiceDep,
 ) -> ClaudeProjectsImporter:
     """Create ClaudeProjectsImporter with dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeProjectsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeProjectsImporterDep = Annotated[ClaudeProjectsImporter, Depends(get_claude_projects_importer)]
@@ -137,7 +172,12 @@ async def get_claude_projects_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> ClaudeProjectsImporter:
     """Create ClaudeProjectsImporter with v2 dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeProjectsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeProjectsImporterV2Dep = Annotated[
@@ -151,7 +191,12 @@ async def get_claude_projects_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> ClaudeProjectsImporter:
     """Create ClaudeProjectsImporter with v2 external_id dependencies."""
-    return ClaudeProjectsImporter(project_config.home, markdown_processor, file_service)
+    return ClaudeProjectsImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 ClaudeProjectsImporterV2ExternalDep = Annotated[
@@ -168,7 +213,12 @@ async def get_memory_json_importer(
     file_service: FileServiceDep,
 ) -> MemoryJsonImporter:
     """Create MemoryJsonImporter with dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+    return MemoryJsonImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 MemoryJsonImporterDep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer)]
@@ -180,7 +230,12 @@ async def get_memory_json_importer_v2(  # pragma: no cover
     file_service: FileServiceV2Dep,
 ) -> MemoryJsonImporter:
     """Create MemoryJsonImporter with v2 dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+    return MemoryJsonImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 MemoryJsonImporterV2Dep = Annotated[MemoryJsonImporter, Depends(get_memory_json_importer_v2)]
@@ -192,7 +247,12 @@ async def get_memory_json_importer_v2_external(
     file_service: FileServiceV2ExternalDep,
 ) -> MemoryJsonImporter:
     """Create MemoryJsonImporter with v2 external_id dependencies."""
-    return MemoryJsonImporter(project_config.home, markdown_processor, file_service)
+    return MemoryJsonImporter(
+        project_config.home,
+        markdown_processor,
+        file_service,
+        project_name=project_config.name,
+    )
 
 
 MemoryJsonImporterV2ExternalDep = Annotated[

src/basic_memory/deps/repositories.py

@@ -13,6 +13,7 @@ from typing import Annotated
 
 from fastapi import Depends
 
+from basic_memory.deps.config import AppConfigDep
 from basic_memory.deps.db import SessionMakerDep
 from basic_memory.deps.projects import (
     ProjectIdDep,
@@ -147,13 +148,14 @@ RelationRepositoryV2ExternalDep = Annotated[
 async def get_search_repository(
     session_maker: SessionMakerDep,
     project_id: ProjectIdDep,
+    app_config: AppConfigDep,
 ) -> SearchRepository:
     """Create a backend-specific SearchRepository instance for the current project.
 
     Uses factory function to return SQLiteSearchRepository or PostgresSearchRepository
     based on database backend configuration.
     """
-    return create_search_repository(session_maker, project_id=project_id)
+    return create_search_repository(session_maker, project_id=project_id, app_config=app_config)
 
 
 SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)]
@@ -162,9 +164,10 @@ SearchRepositoryDep = Annotated[SearchRepository, Depends(get_search_repository)
 async def get_search_repository_v2(  # pragma: no cover
     session_maker: SessionMakerDep,
     project_id: ProjectIdPathDep,
+    app_config: AppConfigDep,
 ) -> SearchRepository:
     """Create a SearchRepository instance for v2 API."""
-    return create_search_repository(session_maker, project_id=project_id)
+    return create_search_repository(session_maker, project_id=project_id, app_config=app_config)
 
 
 SearchRepositoryV2Dep = Annotated[SearchRepository, Depends(get_search_repository_v2)]
@@ -173,9 +176,10 @@ SearchRepositoryV2Dep = Annotated[SearchRepository, Depends(get_search_repositor
 async def get_search_repository_v2_external(
     session_maker: SessionMakerDep,
     project_id: ProjectExternalIdPathDep,
+    app_config: AppConfigDep,
 ) -> SearchRepository:
     """Create a SearchRepository instance for v2 API (uses external_id)."""
-    return create_search_repository(session_maker, project_id=project_id)
+    return create_search_repository(session_maker, project_id=project_id, app_config=app_config)
 
 
 SearchRepositoryV2ExternalDep = Annotated[

src/basic_memory/deps/services.py

@@ -7,7 +7,10 @@ This module provides service-layer dependencies:
 - SyncService, ProjectService, DirectoryService
 """
 
-from typing import Annotated
+import asyncio
+import os
+from pathlib import Path
+from typing import Annotated, Any, Callable, Coroutine, Mapping, Protocol
 
 from fastapi import Depends
 from loguru import logger
@@ -43,7 +46,6 @@ from basic_memory.services.link_resolver import LinkResolver
 from basic_memory.services.search_service import SearchService
 from basic_memory.sync import SyncService
 
-
 # --- Entity Parser ---
 
 
@@ -307,11 +309,13 @@ async def get_context_service(
     search_repository: SearchRepositoryDep,
     entity_repository: EntityRepositoryDep,
     observation_repository: ObservationRepositoryDep,
+    link_resolver: LinkResolverDep,
 ) -> ContextService:
     return ContextService(
         search_repository=search_repository,
         entity_repository=entity_repository,
         observation_repository=observation_repository,
+        link_resolver=link_resolver,
     )
 
 
@@ -322,12 +326,14 @@ async def get_context_service_v2(  # pragma: no cover
     search_repository: SearchRepositoryV2Dep,
     entity_repository: EntityRepositoryV2Dep,
     observation_repository: ObservationRepositoryV2Dep,
+    link_resolver: LinkResolverV2Dep,
 ) -> ContextService:
     """Create ContextService for v2 API."""
     return ContextService(
         search_repository=search_repository,
         entity_repository=entity_repository,
         observation_repository=observation_repository,
+        link_resolver=link_resolver,
     )
 
 
@@ -338,12 +344,14 @@ async def get_context_service_v2_external(
     search_repository: SearchRepositoryV2ExternalDep,
     entity_repository: EntityRepositoryV2ExternalDep,
     observation_repository: ObservationRepositoryV2ExternalDep,
+    link_resolver: LinkResolverV2ExternalDep,
 ) -> ContextService:
     """Create ContextService for v2 API (uses external_id)."""
     return ContextService(
         search_repository=search_repository,
         entity_repository=entity_repository,
         observation_repository=observation_repository,
+        link_resolver=link_resolver,
     )
 
 
@@ -430,14 +438,133 @@ async def get_sync_service_v2_external(
 SyncServiceV2ExternalDep = Annotated[SyncService, Depends(get_sync_service_v2_external)]
 
 
+# --- Background Task Scheduler ---
+
+
+class TaskScheduler(Protocol):
+    def schedule(self, task_name: str, **payload: Any) -> None:
+        """Schedule a background task by name."""
+
+
+def _log_task_failure(completed: asyncio.Task) -> None:
+    try:
+        completed.result()
+    except Exception as exc:  # pragma: no cover
+        logger.exception("Background task failed", error=str(exc))
+
+
+class LocalTaskScheduler:
+    """Default scheduler that runs tasks in-process via asyncio.create_task.
+
+    In test mode (BASIC_MEMORY_ENV=test), tasks run as no-ops to avoid
+    background asyncio tasks racing against test teardown and causing
+    SQLite 'cannot commit transaction' errors.
+    """
+
+    def __init__(
+        self,
+        handlers: Mapping[str, Callable[..., Coroutine[Any, Any, None]]],
+        test_mode: bool | None = None,
+    ) -> None:
+        self._handlers = handlers
+        self._test_mode = (
+            test_mode if test_mode is not None else os.environ.get("BASIC_MEMORY_ENV") == "test"
+        )
+
+    def schedule(self, task_name: str, **payload: Any) -> None:
+        handler = self._handlers.get(task_name)
+        # Trigger: task name is not registered
+        # Why: avoid silently dropping background work
+        # Outcome: fail fast to surface misconfiguration
+        if not handler:
+            raise ValueError(f"Unknown task name: {task_name}")
+
+        # Trigger: running inside pytest (BASIC_MEMORY_ENV=test)
+        # Why: background create_task() outlives test fixtures and races
+        #      against engine disposal, causing flaky SQLite errors
+        # Outcome: skip background scheduling; tests exercise the sync
+        #          codepaths directly when they need to
+        if self._test_mode:
+            return
+
+        task = asyncio.create_task(handler(**payload))
+        task.add_done_callback(_log_task_failure)
+
+
+async def get_task_scheduler(
+    entity_service: EntityServiceV2ExternalDep,
+    sync_service: SyncServiceV2ExternalDep,
+    search_service: SearchServiceV2ExternalDep,
+    project_config: ProjectConfigV2ExternalDep,
+    app_config: AppConfigDep,
+) -> TaskScheduler:
+    """Create a scheduler that maps task specs to coroutines."""
+
+    scheduler: LocalTaskScheduler | None = None
+
+    async def _reindex_entity(
+        entity_id: int,
+        resolve_relations: bool = False,
+        **_: Any,
+    ) -> None:
+        await entity_service.reindex_entity(entity_id)
+        # Trigger: caller requests relation resolution
+        # Why: resolve forward references created before the entity existed
+        # Outcome: updates unresolved relations pointing to this entity
+        if resolve_relations:
+            await sync_service.resolve_relations(entity_id=entity_id)
+        # Trigger: semantic search enabled in local config.
+        # Why: vector chunks are derived and should refresh after canonical reindex completes.
+        # Outcome: schedules out-of-band vector sync without extending write latency.
+        if app_config.semantic_search_enabled and scheduler is not None:
+            scheduler.schedule("sync_entity_vectors", entity_id=entity_id)
+
+    async def _resolve_relations(entity_id: int, **_: Any) -> None:
+        await sync_service.resolve_relations(entity_id=entity_id)
+
+    async def _sync_entity_vectors(entity_id: int, **_: Any) -> None:
+        await search_service.sync_entity_vectors(entity_id)
+
+    async def _sync_project(force_full: bool = False, **_: Any) -> None:
+        await sync_service.sync(
+            project_config.home,
+            project_config.name,
+            force_full=force_full,
+        )
+
+    async def _reindex_project(**_: Any) -> None:
+        await search_service.reindex_all()
+
+    scheduler = LocalTaskScheduler(
+        {
+            "reindex_entity": _reindex_entity,
+            "resolve_relations": _resolve_relations,
+            "sync_entity_vectors": _sync_entity_vectors,
+            "sync_project": _sync_project,
+            "reindex_project": _reindex_project,
+        },
+        test_mode=app_config.is_test_env,
+    )
+    return scheduler
+
+
+TaskSchedulerDep = Annotated[TaskScheduler, Depends(get_task_scheduler)]
+
+
 # --- Project Service ---
 
 
 async def get_project_service(
     project_repository: ProjectRepositoryDep,
+    app_config: AppConfigDep,
 ) -> ProjectService:
-    """Create ProjectService with repository."""
-    return ProjectService(repository=project_repository)
+    """Create ProjectService with repository and a system-level FileService for directory operations."""
+    # A system-level FileService for project directory creation (no project-specific base_path needed).
+    # ensure_directory() accepts absolute paths and ignores base_path for those, so Path.home() is safe.
+    entity_parser = EntityParser(Path.home())
+    markdown_processor = MarkdownProcessor(entity_parser, app_config=app_config)
+    file_service = FileService(Path.home(), markdown_processor, app_config=app_config)
+    return ProjectService(repository=project_repository, file_service=file_service)
 
 
 ProjectServiceDep = Annotated[ProjectService, Depends(get_project_service)]

src/basic_memory/file_utils.py

@@ -450,16 +450,16 @@ def sanitize_for_filename(text: str, replacement: str = "-") -> str:
     return text.strip(replacement)
 
 
-def sanitize_for_folder(folder: str) -> str:
+def sanitize_for_directory(directory: str) -> str:
     """
-    Sanitize folder path to be safe for use in file system paths.
+    Sanitize directory path to be safe for use in file system paths.
     Removes leading/trailing whitespace, compresses multiple slashes,
     and removes special characters except for /, -, and _.
     """
-    if not folder:
+    if not directory:
         return ""
 
-    sanitized = folder.strip()
+    sanitized = directory.strip()
 
     if sanitized.startswith("./"):
         sanitized = sanitized[2:]

src/basic_memory/importers/base.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any, Optional, TypeVar
 from basic_memory.markdown.markdown_processor import MarkdownProcessor
 from basic_memory.markdown.schemas import EntityMarkdown
 from basic_memory.schemas.importer import ImportResult
+from basic_memory.utils import build_canonical_permalink, generate_permalink
 
 if TYPE_CHECKING:  # pragma: no cover
     from basic_memory.services.file_service import FileService
@@ -29,6 +30,7 @@ class Importer[T: ImportResult]:
         base_path: Path,
         markdown_processor: MarkdownProcessor,
         file_service: "FileService",
+        project_name: Optional[str] = None,
     ):
         """Initialize the import service.
 
@@ -40,6 +42,8 @@ class Importer[T: ImportResult]:
         self.base_path = base_path.resolve()  # Get absolute path
         self.markdown_processor = markdown_processor
         self.file_service = file_service
+        self.project_name = project_name
+        self.project_permalink = generate_permalink(project_name) if project_name else None
 
     @abstractmethod
     async def import_data(self, source_data, destination_folder: str, **kwargs: Any) -> T:
@@ -73,6 +77,26 @@ class Importer[T: ImportResult]:
         # FileService.write_file handles directory creation and returns checksum
         return await self.file_service.write_file(file_path, content)
 
+    def canonical_permalink(self, path: str) -> str:
+        """Build a canonical permalink for imported content."""
+        include_project = True
+        # Trigger: importer has app config with permalink prefixing flag
+        # Why: imported notes should align with canonical permalink format
+        # Outcome: include project prefix when enabled
+        if self.file_service.app_config is not None:
+            include_project = self.file_service.app_config.permalinks_include_project
+
+        return build_canonical_permalink(
+            self.project_permalink,
+            path,
+            include_project=include_project,
+        )
+
+    def build_import_paths(self, path: str) -> tuple[str, str]:
+        """Return (permalink, file_path) for an imported entity."""
+        permalink = self.canonical_permalink(path)
+        return permalink, f"{path}.md"
+
     async def ensure_folder_exists(self, folder: str) -> None:
         """Ensure folder exists using FileService.
 

src/basic_memory/importers/chatgpt_importer.py

@@ -51,11 +51,20 @@ class ChatGPTImporter(Importer[ChatImportResult]):
             chats_imported = 0
 
             for chat in conversations:
+                created_at = chat["create_time"]
+                date_prefix = datetime.fromtimestamp(created_at).astimezone().strftime("%Y%m%d")
+                clean_title = clean_filename(chat["title"])
+                relative_path = (
+                    f"{destination_folder}/{date_prefix}-{clean_title}"
+                    if destination_folder
+                    else f"{date_prefix}-{clean_title}"
+                )
+                permalink, file_path = self.build_import_paths(relative_path)
+
                 # Convert to entity
-                entity = self._format_chat_content(destination_folder, chat)
+                entity = self._format_chat_content(chat, permalink)
 
                 # Write file using relative path - FileService handles base_path
-                file_path = f"{entity.frontmatter.metadata['permalink']}.md"
                 await self.write_entity(entity, file_path)
 
                 # Count messages
@@ -83,7 +92,7 @@ class ChatGPTImporter(Importer[ChatImportResult]):
             return self.handle_error("Failed to import ChatGPT conversations", e)
 
     def _format_chat_content(
-        self, folder: str, conversation: Dict[str, Any]
+        self, conversation: Dict[str, Any], permalink: str
     ) -> EntityMarkdown:  # pragma: no cover
         """Convert chat conversation to Basic Memory entity.
 
@@ -105,10 +114,6 @@ class ChatGPTImporter(Importer[ChatImportResult]):
                 root_id = node_id
                 break
 
-        # Generate permalink
-        date_prefix = datetime.fromtimestamp(created_at).astimezone().strftime("%Y%m%d")
-        clean_title = clean_filename(conversation["title"])
-
         # Format content
         content = self._format_chat_markdown(
             title=conversation["title"],
@@ -126,7 +131,7 @@ class ChatGPTImporter(Importer[ChatImportResult]):
                     "title": conversation["title"],
                     "created": format_timestamp(created_at),
                     "modified": format_timestamp(modified_at),
-                    "permalink": f"{folder}/{date_prefix}-{clean_title}",
+                    "permalink": permalink,
                 }
             ),
             content=content,

src/basic_memory/importers/claude_conversations_importer.py

@@ -54,18 +54,27 @@ class ClaudeConversationsImporter(Importer[ChatImportResult]):
             for chat in conversations:
                 # Get name, providing default for unnamed conversations
                 chat_name = chat.get("name") or f"Conversation {chat.get('uuid', 'untitled')}"
+                date_prefix = datetime.fromisoformat(
+                    chat["created_at"].replace("Z", "+00:00")
+                ).strftime("%Y%m%d")
+                clean_title = clean_filename(chat_name)
+                relative_path = (
+                    f"{destination_folder}/{date_prefix}-{clean_title}"
+                    if destination_folder
+                    else f"{date_prefix}-{clean_title}"
+                )
+                permalink, file_path = self.build_import_paths(relative_path)
 
                 # Convert to entity
                 entity = self._format_chat_content(
-                    folder=destination_folder,
                     name=chat_name,
                     messages=chat["chat_messages"],
                     created_at=chat["created_at"],
                     modified_at=chat["updated_at"],
+                    permalink=permalink,
                 )
 
                 # Write file using relative path - FileService handles base_path
-                file_path = f"{entity.frontmatter.metadata['permalink']}.md"
                 await self.write_entity(entity, file_path)
 
                 chats_imported += 1
@@ -84,11 +93,11 @@ class ClaudeConversationsImporter(Importer[ChatImportResult]):
 
     def _format_chat_content(
         self,
-        folder: str,
         name: str,
         messages: List[Dict[str, Any]],
         created_at: str,
         modified_at: str,
+        permalink: str,
     ) -> EntityMarkdown:
         """Convert chat messages to Basic Memory entity format.
 
@@ -102,11 +111,6 @@ class ClaudeConversationsImporter(Importer[ChatImportResult]):
         Returns:
             EntityMarkdown instance representing the conversation.
         """
-        # Generate permalink using folder name (relative path)
-        date_prefix = datetime.fromisoformat(created_at.replace("Z", "+00:00")).strftime("%Y%m%d")
-        clean_title = clean_filename(name)
-        permalink = f"{folder}/{date_prefix}-{clean_title}"
-
         # Format content
         content = self._format_chat_markdown(
             name=name,

src/basic_memory/importers/claude_projects_importer.py

@@ -63,17 +63,28 @@ class ClaudeProjectsImporter(Importer[ProjectImportResult]):
                 await self.file_service.ensure_directory(docs_dir)
 
                 # Import prompt template if it exists
-                if prompt_entity := self._format_prompt_markdown(project, destination_folder):
-                    # Write file using relative path - FileService handles base_path
-                    file_path = f"{prompt_entity.frontmatter.metadata['permalink']}.md"
-                    await self.write_entity(prompt_entity, file_path)
+                if project.get("prompt_template"):
+                    prompt_path = (
+                        f"{destination_folder}/{project_dir}/prompt-template"
+                        if destination_folder
+                        else f"{project_dir}/prompt-template"
+                    )
+                    permalink, file_path = self.build_import_paths(prompt_path)
+                    prompt_entity = self._format_prompt_markdown(project, permalink)
+                    if prompt_entity:
+                        await self.write_entity(prompt_entity, file_path)
                     prompts_imported += 1
 
                 # Import project documents
                 for doc in project.get("docs", []):
-                    entity = self._format_project_markdown(project, doc, destination_folder)
-                    # Write file using relative path - FileService handles base_path
-                    file_path = f"{entity.frontmatter.metadata['permalink']}.md"
+                    doc_file = clean_filename(doc["filename"])
+                    doc_path = (
+                        f"{destination_folder}/{project_dir}/docs/{doc_file}"
+                        if destination_folder
+                        else f"{project_dir}/docs/{doc_file}"
+                    )
+                    permalink, file_path = self.build_import_paths(doc_path)
+                    entity = self._format_project_markdown(project, doc, permalink)
                     await self.write_entity(entity, file_path)
                     docs_imported += 1
 
@@ -89,7 +100,7 @@ class ClaudeProjectsImporter(Importer[ProjectImportResult]):
             return self.handle_error("Failed to import Claude projects", e)
 
     def _format_project_markdown(
-        self, project: Dict[str, Any], doc: Dict[str, Any], destination_folder: str = ""
+        self, project: Dict[str, Any], doc: Dict[str, Any], permalink: str
     ) -> EntityMarkdown:
         """Format a project document as a Basic Memory entity.
 
@@ -105,17 +116,6 @@ class ClaudeProjectsImporter(Importer[ProjectImportResult]):
         created_at = doc.get("created_at") or project["created_at"]
         modified_at = project["updated_at"]
 
-        # Generate clean names for organization
-        project_dir = clean_filename(project["name"])
-        doc_file = clean_filename(doc["filename"])
-
-        # Build permalink with optional destination folder prefix
-        permalink = (
-            f"{destination_folder}/{project_dir}/docs/{doc_file}"
-            if destination_folder
-            else f"{project_dir}/docs/{doc_file}"
-        )
-
         # Create entity
         entity = EntityMarkdown(
             frontmatter=EntityFrontmatter(
@@ -136,7 +136,7 @@ class ClaudeProjectsImporter(Importer[ProjectImportResult]):
         return entity
 
     def _format_prompt_markdown(
-        self, project: Dict[str, Any], destination_folder: str = ""
+        self, project: Dict[str, Any], permalink: str
     ) -> Optional[EntityMarkdown]:
         """Format project prompt template as a Basic Memory entity.
 
@@ -155,16 +155,6 @@ class ClaudeProjectsImporter(Importer[ProjectImportResult]):
         created_at = project["created_at"]
         modified_at = project["updated_at"]
 
-        # Generate clean project directory name
-        project_dir = clean_filename(project["name"])
-
-        # Build permalink with optional destination folder prefix
-        permalink = (
-            f"{destination_folder}/{project_dir}/prompt-template"
-            if destination_folder
-            else f"{project_dir}/prompt-template"
-        )
-
         # Create entity
         entity = EntityMarkdown(
             frontmatter=EntityFrontmatter(

src/basic_memory/importers/memory_json_importer.py

@@ -80,11 +80,12 @@ class MemoryJsonImporter(Importer[EntityImportResult]):
                 entity_type = entity_data.get("entityType") or entity_data.get("type") or "entity"
 
                 # Build permalink with optional destination folder prefix
-                permalink = (
+                relative_path = (
                     f"{destination_folder}/{entity_type}/{name}"
                     if destination_folder
                     else f"{entity_type}/{name}"
                 )
+                permalink, file_path = self.build_import_paths(relative_path)
 
                 # Ensure entity type directory exists using FileService with relative path
                 entity_type_dir = (
@@ -109,7 +110,6 @@ class MemoryJsonImporter(Importer[EntityImportResult]):
                 )
 
                 # Write file using relative path - FileService handles base_path
-                file_path = f"{entity.frontmatter.metadata['permalink']}.md"
                 await self.write_entity(entity, file_path)
                 entities_created += 1
 

src/basic_memory/markdown/entity_parser.py

@@ -88,6 +88,22 @@ def normalize_frontmatter_value(value: Any) -> Any:
     return value
 
 
+def _coerce_to_string(value: Any) -> str:
+    """Coerce a frontmatter value to a string.
+
+    YAML can parse scalar-looking fields as lists when the author uses block
+    sequence syntax.  For fields like ``title`` and ``type`` that *must* be
+    strings, this helper converts lists to a comma-separated string and any
+    other non-string type via ``str()``.
+    """
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        # Join list items, converting each to string first
+        return ", ".join(str(item) for item in value)
+    return str(value)
+
+
 def normalize_frontmatter_metadata(metadata: dict) -> dict:
     """Normalize all values in frontmatter metadata dict.
 
@@ -233,28 +249,43 @@ class EntityParser:
 
         content = strip_bom(content)
 
-        # Parse frontmatter with proper error handling for malformed YAML
+        # Parse frontmatter with proper error handling for malformed YAML.
+        # We use frontmatter.parse() instead of frontmatter.loads() because
+        # loads() does Post(content, handler, **metadata), which crashes when
+        # the YAML contains reserved keys like 'content' or 'handler'.
+        # See basic-memory-cloud#375.
         try:
-            post = frontmatter.loads(content)
+            fm_metadata, fm_content = frontmatter.parse(content)
+            post = frontmatter.Post(fm_content)
+            post.metadata.update(fm_metadata)
         except yaml.YAMLError as e:
             logger.warning(
                 f"Failed to parse YAML frontmatter in {file_path}: {e}. "
                 f"Treating file as plain markdown without frontmatter."
             )
-            post = frontmatter.Post(content, metadata={})
+            # Use Post(content) not Post(content, metadata={})
+            # The latter creates {"metadata": {}} in the metadata dict (issue #528)
+            post = frontmatter.Post(content)
 
         # Normalize frontmatter values
         metadata = normalize_frontmatter_metadata(post.metadata)
 
-        # Ensure required fields have defaults
+        # Ensure required string fields are always strings.
+        # YAML can parse these as lists when authors use block sequence syntax
+        # (e.g. "title:\n  - My Title"), causing 'list' has no attribute 'strip'
+        # downstream.  See basic-memory-cloud#376.
         title = metadata.get("title")
+        if title is not None:
+            title = _coerce_to_string(title)
         if not title or title == "None":
             metadata["title"] = file_path.stem
         else:
             metadata["title"] = title
 
-        entity_type = metadata.get("type")
-        metadata["type"] = entity_type if entity_type is not None else "note"
+        note_type = metadata.get("type")
+        if note_type is not None:
+            note_type = _coerce_to_string(note_type)
+        metadata["type"] = note_type if note_type is not None else "note"
 
         tags = parse_tags(metadata.get("tags", []))  # pyright: ignore
         if tags:

src/basic_memory/markdown/plugins.py

@@ -1,6 +1,8 @@
 """Markdown-it plugins for Basic Memory markdown parsing."""
 
 from typing import List, Any, Dict
+
+from basic_memory.utils import normalize_project_reference
 from markdown_it import MarkdownIt
 from markdown_it.token import Token
 
@@ -114,7 +116,7 @@ def parse_relation(token: Token) -> Dict[str, Any] | None:
             rel_type = before
 
         # Get target
-        target = content[start + 2 : end].strip()
+        target = normalize_project_reference(content[start + 2 : end].strip())
 
         # Look for context after
         after = content[end + 2 :].strip()
@@ -160,7 +162,7 @@ def parse_inline_relations(content: str) -> List[Dict[str, Any]]:
             # No matching ]] found
             break
 
-        target = content[start + 2 : end].strip()
+        target = normalize_project_reference(content[start + 2 : end].strip())
         if target:
             relations.append({"type": "links_to", "target": target, "context": None})
 

src/basic_memory/markdown/utils.py

@@ -9,6 +9,7 @@ from frontmatter import Post
 
 from basic_memory.file_utils import has_frontmatter, remove_frontmatter, parse_frontmatter
 from basic_memory.markdown import EntityMarkdown
+from basic_memory.markdown.entity_parser import normalize_frontmatter_metadata
 from basic_memory.models import Entity
 from basic_memory.models import Observation as ObservationModel
 
@@ -49,7 +50,7 @@ def entity_model_from_markdown(
 
     # Update basic fields
     model.title = markdown.frontmatter.title
-    model.entity_type = markdown.frontmatter.type
+    model.note_type = markdown.frontmatter.type
     # Only update permalink if it exists in frontmatter, otherwise preserve existing
     if markdown.frontmatter.permalink is not None:
         model.permalink = markdown.frontmatter.permalink
@@ -58,9 +59,9 @@ def entity_model_from_markdown(
     model.created_at = markdown.created
     model.updated_at = markdown.modified
 
-    # Handle metadata - ensure all values are strings and filter None
-    metadata = markdown.frontmatter.metadata or {}
-    model.entity_metadata = {k: str(v) for k, v in metadata.items() if v is not None}
+    # Handle metadata - normalize values and filter None (preserve structured data)
+    metadata = normalize_frontmatter_metadata(markdown.frontmatter.metadata or {})
+    model.entity_metadata = {k: v for k, v in metadata.items() if v is not None}
 
     # Get project_id from entity if not provided
     obs_project_id = project_id or (model.project_id if hasattr(model, "project_id") else None)
@@ -85,7 +86,7 @@ async def schema_to_markdown(schema: Any) -> Post:
     Convert schema to markdown Post object.
 
     Args:
-        schema: Schema to convert (must have title, entity_type, and permalink attributes)
+        schema: Schema to convert (must have title, note_type, and permalink attributes)
 
     Returns:
         Post object with frontmatter metadata
@@ -112,7 +113,7 @@ async def schema_to_markdown(schema: Any) -> Post:
     post = Post(
         content,
         title=schema.title,
-        type=schema.entity_type,
+        type=schema.note_type,
     )
     # set the permalink if passed in
     if schema.permalink:

src/basic_memory/mcp/async_client.py

@@ -1,11 +1,99 @@
-from contextlib import asynccontextmanager, AbstractAsyncContextManager
+import os
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
 from typing import AsyncIterator, Callable, Optional
 
 from httpx import ASGITransport, AsyncClient, Timeout
 from loguru import logger
 
 from basic_memory.api.app import app as fastapi_app
-from basic_memory.config import ConfigManager
+from basic_memory.config import ConfigManager, ProjectMode
+
+
+def _force_local_mode() -> bool:
+    """Check if local mode is forced via environment variable."""
+    return os.environ.get("BASIC_MEMORY_FORCE_LOCAL", "").lower() in ("true", "1", "yes")
+
+
+def _force_cloud_mode() -> bool:
+    """Check if cloud mode is forced via environment variable."""
+    return os.environ.get("BASIC_MEMORY_FORCE_CLOUD", "").lower() in ("true", "1", "yes")
+
+
+def _explicit_routing() -> bool:
+    """Check if CLI --local/--cloud flag was explicitly passed."""
+    return os.environ.get("BASIC_MEMORY_EXPLICIT_ROUTING", "").lower() in ("true", "1", "yes")
+
+
+def _build_timeout() -> Timeout:
+    """Create a standard timeout config used across all clients."""
+    return Timeout(
+        connect=10.0,
+        read=30.0,
+        write=30.0,
+        pool=30.0,
+    )
+
+
+def _asgi_client(timeout: Timeout) -> AsyncClient:
+    """Create a local ASGI client."""
+    return AsyncClient(
+        transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
+    )
+
+
+async def _resolve_cloud_token(config) -> str:
+    """Resolve cloud token with API key preferred, OAuth fallback."""
+    token = config.cloud_api_key
+    if token:
+        return token
+
+    from basic_memory.cli.auth import CLIAuth
+
+    auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
+    token = await auth.get_valid_token()
+    if token:
+        return token
+
+    raise RuntimeError(
+        "Cloud routing requested but no credentials found. "
+        "Run 'bm cloud api-key save <key>' or 'bm cloud login' first."
+    )
+
+
+@asynccontextmanager
+async def _cloud_client(
+    config,
+    timeout: Timeout,
+    workspace: Optional[str] = None,
+) -> AsyncIterator[AsyncClient]:
+    """Create a cloud proxy client with resolved credentials."""
+    token = await _resolve_cloud_token(config)
+    proxy_base_url = f"{config.cloud_host}/proxy"
+    headers = {"Authorization": f"Bearer {token}"}
+    if workspace:
+        headers["X-Workspace-ID"] = workspace
+    logger.info(f"Creating HTTP client for cloud proxy at: {proxy_base_url}")
+    async with AsyncClient(
+        base_url=proxy_base_url,
+        headers=headers,
+        timeout=timeout,
+    ) as client:
+        yield client
+
+
+@asynccontextmanager
+async def get_cloud_control_plane_client() -> AsyncIterator[AsyncClient]:
+    """Create a control-plane cloud client for endpoints outside /proxy."""
+    config = ConfigManager().config
+    timeout = _build_timeout()
+    token = await _resolve_cloud_token(config)
+    logger.info(f"Creating HTTP client for cloud control plane at: {config.cloud_host}")
+    async with AsyncClient(
+        base_url=config.cloud_host,
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=timeout,
+    ) as client:
+        yield client
 
 
 # Optional factory override for dependency injection
@@ -13,127 +101,111 @@ _client_factory: Optional[Callable[[], AbstractAsyncContextManager[AsyncClient]]
 
 
 def set_client_factory(factory: Callable[[], AbstractAsyncContextManager[AsyncClient]]) -> None:
-    """Override the default client factory (for cloud app, testing, etc).
-
-    Args:
-        factory: An async context manager that yields an AsyncClient
-
-    Example:
-        @asynccontextmanager
-        async def custom_client_factory():
-            async with AsyncClient(...) as client:
-                yield client
-
-        set_client_factory(custom_client_factory)
-    """
+    """Override the default client factory (for cloud app, testing, etc)."""
     global _client_factory
     _client_factory = factory
 
 
+def is_factory_mode() -> bool:
+    """Return True when a client factory override is active (e.g., cloud app)."""
+    return _client_factory is not None
+
+
 @asynccontextmanager
-async def get_client() -> AsyncIterator[AsyncClient]:
+async def get_cloud_proxy_client(
+    workspace: Optional[str] = None,
+) -> AsyncIterator[AsyncClient]:
+    """Create a cloud proxy client for project-level operations.
+
+    Used by MCP tools to fetch cloud project lists independently of the
+    default get_client() routing, which always goes through the local ASGI
+    transport in stdio mode.
+    """
+    config = ConfigManager().config
+    timeout = _build_timeout()
+    async with _cloud_client(config, timeout, workspace=workspace) as client:
+        yield client
+
+
+@asynccontextmanager
+async def get_client(
+    project_name: Optional[str] = None,
+    workspace: Optional[str] = None,
+) -> AsyncIterator[AsyncClient]:
     """Get an AsyncClient as a context manager.
 
-    This function provides proper resource management for HTTP clients,
-    ensuring connections are closed after use. It supports three modes:
-
-    1. **Factory injection** (cloud app, tests):
-       If a custom factory is set via set_client_factory(), use that.
-
-    2. **CLI cloud mode**:
-       When cloud_mode_enabled is True, create HTTP client with auth
-       token from CLIAuth for requests to cloud proxy endpoint.
-
-    3. **Local mode** (default):
-       Use ASGI transport for in-process requests to local FastAPI app.
-
-    Usage:
-        async with get_client() as client:
-            response = await client.get("/path")
-
-    Yields:
-        AsyncClient: Configured HTTP client for the current mode
-
-    Raises:
-        RuntimeError: If cloud mode is enabled but user is not authenticated
+    Routing priority:
+    1. Factory injection.
+    2. Explicit routing flags (--local/--cloud).
+    3. Per-project mode routing when project_name is provided.
+    4. Local ASGI transport by default.
     """
     if _client_factory:
-        # Use injected factory (cloud app, tests)
         async with _client_factory() as client:
             yield client
-    else:
-        # Default: create based on config
-        config = ConfigManager().config
-        timeout = Timeout(
-            connect=10.0,  # 10 seconds for connection
-            read=30.0,  # 30 seconds for reading response
-            write=30.0,  # 30 seconds for writing request
-            pool=30.0,  # 30 seconds for connection pool
-        )
+        return
 
-        if config.cloud_mode_enabled:
-            # CLI cloud mode: inject auth when creating client
-            from basic_memory.cli.auth import CLIAuth
+    config = ConfigManager().config
+    timeout = _build_timeout()
 
-            auth = CLIAuth(client_id=config.cloud_client_id, authkit_domain=config.cloud_domain)
-            token = await auth.get_valid_token()
+    # --- Explicit routing override ---
+    # Trigger: user passed --local/--cloud.
+    # Why: command-level override should be deterministic and bypass project mode.
+    # Outcome: route strictly based on explicit flag.
+    if _explicit_routing():
+        if _force_local_mode():
+            logger.debug("Explicit local routing enabled - using ASGI client")
+            async with _asgi_client(timeout) as client:
+                yield client
+            return
 
-            if not token:
+        if _force_cloud_mode():
+            logger.debug("Explicit cloud routing enabled - using cloud proxy client")
+            async with _cloud_client(config, timeout, workspace=workspace) as client:
+                yield client
+            return
+
+    # --- Per-project routing ---
+    # Trigger: project_name provided without explicit routing override.
+    # Why: project mode is the source of truth for project-scoped commands.
+    # Outcome: route via project.mode (CLOUD/LOCAL).
+    if project_name is not None and not _explicit_routing():
+        project_mode = config.get_project_mode(project_name)
+        if project_mode == ProjectMode.CLOUD:
+            logger.debug(f"Project '{project_name}' is cloud mode - using cloud proxy client")
+            try:
+                async with _cloud_client(config, timeout, workspace=workspace) as client:
+                    yield client
+            except RuntimeError as exc:
                 raise RuntimeError(
-                    "Cloud mode enabled but not authenticated. "
-                    "Run 'basic-memory cloud login' first."
-                )
+                    f"Project '{project_name}' is set to cloud mode but no credentials found. "
+                    "Run 'bm cloud api-key save <key>' or 'bm cloud login' first."
+                ) from exc
+            return
 
-            # Auth header set ONCE at client creation
-            proxy_base_url = f"{config.cloud_host}/proxy"
-            logger.info(f"Creating HTTP client for cloud proxy at: {proxy_base_url}")
-            async with AsyncClient(
-                base_url=proxy_base_url,
-                headers={"Authorization": f"Bearer {token}"},
-                timeout=timeout,
-            ) as client:
-                yield client
-        else:
-            # Local mode: ASGI transport for in-process calls
-            # Note: ASGI transport does NOT trigger FastAPI lifespan, so no special handling needed
-            logger.info("Creating ASGI client for local Basic Memory API")
-            async with AsyncClient(
-                transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
-            ) as client:
-                yield client
+        logger.debug(f"Project '{project_name}' is local mode - using ASGI client")
+        async with _asgi_client(timeout) as client:
+            yield client
+        return
+
+    # --- Default fallback ---
+    logger.debug("Default routing - using ASGI client for local Basic Memory API")
+    async with _asgi_client(timeout) as client:
+        yield client
 
 
 def create_client() -> AsyncClient:
-    """Create an HTTP client based on configuration.
+    """Create an HTTP client based on explicit routing flags.
 
     DEPRECATED: Use get_client() context manager instead for proper resource management.
-
-    This function is kept for backward compatibility but will be removed in a future version.
-    The returned client should be closed manually by calling await client.aclose().
-
-    Returns:
-        AsyncClient configured for either local ASGI or remote proxy
     """
-    config_manager = ConfigManager()
-    config = config_manager.config
+    timeout = _build_timeout()
 
-    # Configure timeout for longer operations like write_note
-    # Default httpx timeout is 5 seconds which is too short for file operations
-    timeout = Timeout(
-        connect=10.0,  # 10 seconds for connection
-        read=30.0,  # 30 seconds for reading response
-        write=30.0,  # 30 seconds for writing request
-        pool=30.0,  # 30 seconds for connection pool
-    )
-
-    if config.cloud_mode_enabled:
-        # Use HTTP transport to proxy endpoint
-        proxy_base_url = f"{config.cloud_host}/proxy"
-        logger.info(f"Creating HTTP client for proxy at: {proxy_base_url}")
-        return AsyncClient(base_url=proxy_base_url, timeout=timeout)
-    else:
-        # Default: use ASGI transport for local API (development mode)
+    if _force_local_mode() or not _force_cloud_mode():
         logger.info("Creating ASGI client for local Basic Memory API")
-        return AsyncClient(
-            transport=ASGITransport(app=fastapi_app), base_url="http://test", timeout=timeout
-        )
+        return _asgi_client(timeout)
+
+    logger.info("Creating HTTP client for cloud proxy (legacy create_client path)")
+    config = ConfigManager().config
+    proxy_base_url = f"{config.cloud_host}/proxy"
+    return AsyncClient(base_url=proxy_base_url, timeout=timeout)